sentinelayer-cli 0.8.7 → 0.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -50,7 +50,11 @@ import {
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import { readSessionPreview } from "../session/preview.js";
-import { syncSessionMetadataToApi } from "../session/sync.js";
+import {
+  listSessionsFromApi,
+  probeSessionAccess,
+  syncSessionMetadataToApi,
+} from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import {
@@ -604,6 +608,16 @@ export function registerSessionCommand(program) {
         since: sinceArg,
       });
 
+      // Discriminate "owned-but-no-human-messages" from "not a member /
+      // wrong session id". The hydrate path returns ok:true with
+      // relayed=0 + cursor=null in both cases, which Carter just hit
+      // on session d34f03ba — the user couldn't tell whether they
+      // typed the wrong id or it was just genuinely empty.
+      let access = null;
+      if (result.ok && result.relayed === 0 && !result.cursor) {
+        access = await probeSessionAccess(normalizedSessionId, { targetPath });
+      }
+
       const payload = {
         command: "session sync",
         targetPath,
@@ -614,6 +628,7 @@ export function registerSessionCommand(program) {
         dropped: result.dropped,
         cursor: result.cursor,
         persistedCursor: result.persistedCursor,
+        access: access || undefined,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -623,6 +638,27 @@ export function registerSessionCommand(program) {
         console.log(
           `Hydrated session ${normalizedSessionId}: relayed=${result.relayed} dropped=${result.dropped}.`,
         );
+        if (access && !access.accessible) {
+          if (access.reason === "session_not_found") {
+            console.log(
+              pc.yellow(
+                `Heads up: that session id isn't in your account. Verify with \`sl session list --remote\`.`,
+              ),
+            );
+          } else if (access.reason === "not_a_member") {
+            console.log(
+              pc.yellow(
+                `Heads up: you aren't a member of session ${normalizedSessionId} — sync silently no-ops. Ask the owner to add you, or list your own with \`sl session list --remote\`.`,
+              ),
+            );
+          } else if (access.reason !== "" && access.reason !== "no_session") {
+            console.log(
+              pc.gray(
+                `(probe: ${access.reason}; if you expected messages, check \`sl session list --remote\`.)`,
+              ),
+            );
+          }
+        }
       } else {
         console.log(
           pc.yellow(
@@ -802,6 +838,122 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("download <sessionId>")
+    .description(
+      "Download an iMessage-style Markdown transcript: deterministic timestamps, per-agent active duration, known persona/orchestrator/family avatars, and human avatars from your auth profile",
+    )
+    .option("--out <file>", "Output path (default: <sessionId>.md in cwd)")
+    .option(
+      "--no-system-events",
+      "Suppress join/leave/identified/daemon-alert lines (keeps only user + agent messages)",
+    )
+    .option(
+      "--remote",
+      "Hydrate from the SentinelLayer API before rendering (pulls web-posted messages into the local NDJSON)",
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const emitJson = shouldEmitJson(options, command);
+
+      let hydration = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        }).catch((error) => ({ ok: false, reason: error?.message || "hydrate_failed" }));
+      }
+
+      const sessionPayload = await getSession(normalizedSessionId, { targetPath });
+      if (!sessionPayload) {
+        throw new Error(`Session '${normalizedSessionId}' was not found.`);
+      }
+
+      const [agents, events] = await Promise.all([
+        listAgents(normalizedSessionId, { targetPath, includeInactive: true }),
+        readStream(normalizedSessionId, { targetPath, tail: 0 }),
+      ]);
+
+      // Pull GitHub/Google avatar + display name from the active auth
+      // session so any human-id seen in the stream renders with the
+      // user's real photo instead of the generic 🧑 fallback.
+      const speakerProfiles = new Map();
+      const auth = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      }).catch(() => null);
+      const userAvatarUrl = normalizeString(auth?.user?.avatarUrl);
+      const userDisplay =
+        normalizeString(auth?.user?.githubUsername) ||
+        normalizeString(auth?.user?.email);
+      if (userAvatarUrl || userDisplay) {
+        const profile = {
+          displayName: userDisplay || "You",
+          avatarUrl: userAvatarUrl || null,
+          family: "human",
+        };
+        for (const id of ["cli-user", "human", "you", "user"]) {
+          speakerProfiles.set(id, profile);
+        }
+        if (userDisplay) speakerProfiles.set(userDisplay, profile);
+      }
+
+      const { buildTranscriptMarkdown } = await import(
+        "../session/transcript.js"
+      );
+      const { markdown, stats } = buildTranscriptMarkdown({
+        sessionMeta: {
+          sessionId: normalizedSessionId,
+          createdAt: sessionPayload.createdAt,
+          status: sessionPayload.status,
+        },
+        events,
+        agents,
+        speakerProfiles,
+        options: {
+          // commander maps --no-system-events to systemEvents: false
+          includeSystemEvents: options.systemEvents !== false,
+        },
+      });
+
+      const outArg = normalizeString(options.out);
+      const outPath = outArg
+        ? path.resolve(process.cwd(), outArg)
+        : path.resolve(process.cwd(), `${normalizedSessionId}.md`);
+      await fsp.mkdir(path.dirname(outPath), { recursive: true });
+      await fsp.writeFile(outPath, markdown, "utf-8");
+
+      const payload = {
+        command: "session download",
+        sessionId: normalizedSessionId,
+        outPath,
+        bytes: Buffer.byteLength(markdown, "utf-8"),
+        eventCount: events.length,
+        agentCount: agents.length,
+        sessionLiveSeconds: stats.sessionLiveSeconds,
+        sentiActions: stats.sentiActions,
+        totals: stats.totals,
+        remote: hydration,
+      };
+      if (emitJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Downloaded session ${normalizedSessionId} → ${outPath}`));
+      console.log(
+        pc.gray(
+          `${events.length} events · ${agents.length} agents · live ${stats.sessionLiveSeconds}s · senti=${stats.sentiActions} · tokens=${stats.totals.tokenTotal} · cost=$${stats.totals.costTotalUsd.toFixed(4)}`,
+        ),
+      );
+    });
+
   session
     .command("leave <sessionId>")
     .description("Leave a session")
@@ -838,7 +990,13 @@ export function registerSessionCommand(program) {
 
   session
     .command("list")
-    .description("List sessions in the local workspace cache")
+    .description(
+      "List sessions. Defaults to local cache; pass --remote to query the SentinelLayer API for every session on your account.",
+    )
+    .option(
+      "--remote",
+      "Query the API for sessions on the authenticated account (covers sessions created from any workspace or the web dashboard)",
+    )
     .option(
       "--include-archived",
       "Include archived/expired sessions (past conversations)",
@@ -854,18 +1012,80 @@ export function registerSessionCommand(program) {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const includeArchived = Boolean(options.includeArchived);
       const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const emitJson = shouldEmitJson(options, command);
+
+      if (options.remote) {
+        const remote = await listSessionsFromApi({
+          targetPath,
+          includeArchived,
+          limit,
+        });
+        const trimmed = emitJson ? remote.sessions : remote.sessions.slice(0, limit);
+        const payload = {
+          command: "session list",
+          source: "remote",
+          targetPath,
+          includeArchived,
+          ok: remote.ok,
+          reason: remote.reason || "",
+          count: remote.count,
+          sessions: trimmed,
+        };
+        if (emitJson) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+        if (!remote.ok) {
+          console.log(
+            pc.yellow(
+              `Remote list unavailable (${remote.reason}). Try \`sl auth login\` or run without --remote for local cache.`,
+            ),
+          );
+          return;
+        }
+        if (remote.sessions.length === 0) {
+          console.log(
+            pc.yellow(
+              includeArchived
+                ? "No sessions on your account."
+                : "No active sessions on your account. Re-run with --include-archived to see history.",
+            ),
+          );
+          return;
+        }
+        for (const item of trimmed) {
+          const archive = item.archiveStatus ? ` archive=${item.archiveStatus}` : "";
+          const created = item.createdAt || "?";
+          const lastActivity = item.lastActivityAt
+            ? ` last=${item.lastActivityAt}`
+            : "";
+          console.log(
+            `${item.sessionId} status=${item.status}${archive} created=${created}${lastActivity}`,
+          );
+        }
+        if (remote.count > trimmed.length) {
+          console.log(
+            pc.gray(
+              `… ${remote.count - trimmed.length} more (raise --limit or use --json).`,
+            ),
+          );
+        }
+        return;
+      }
+
       const sessions = includeArchived
         ? await listAllSessions({ targetPath })
         : await listActiveSessions({ targetPath });
-      const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
+      const trimmed = emitJson ? sessions : sessions.slice(0, limit);
       const payload = {
         command: "session list",
+        source: "local",
         targetPath,
         includeArchived,
         count: sessions.length,
         sessions: trimmed,
       };
-      if (shouldEmitJson(options, command)) {
+      if (emitJson) {
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
@@ -873,8 +1093,8 @@ export function registerSessionCommand(program) {
         console.log(
           pc.yellow(
             includeArchived
-              ? "No sessions in cache."
-              : "No active sessions. Run with --include-archived to see history.",
+              ? "No sessions in local cache. Run with --remote to fetch from the API."
+              : "No active sessions in local cache. Run with --remote to see sessions from other workspaces or the web.",
           ),
         );
         return;

package/src/session/sync.js

@@ -735,6 +735,161 @@ export async function pollHumanMessages(
   }
 }
 
+/**
+ * List sessions owned by the active user via `GET /api/v1/sessions`.
+ *
+ * Mirrors the failure shape of `pollHumanMessages` so callers can render
+ * a single error path: `{ ok, reason, sessions, count }`. Sessions are
+ * returned in API order (newest-first per the server's contract); the
+ * caller is responsible for any further sort or filter.
+ *
+ * @param {object} [options]
+ * @param {string} [options.targetPath]
+ * @param {boolean} [options.includeArchived]
+ * @param {number} [options.limit]
+ * @param {Function} [options.resolveAuthSession]
+ * @param {Function} [options.fetchImpl]
+ * @returns {Promise<{ok: boolean, reason: string, sessions: Array<object>, count: number}>}
+ */
+export async function listSessionsFromApi({
+  targetPath = process.cwd(),
+  includeArchived = false,
+  limit = 50,
+  resolveAuthSession = resolveActiveAuthSession,
+  fetchImpl = fetchWithTimeout,
+  timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+} = {}) {
+  let session;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { ok: false, reason: "no_session", sessions: [], count: 0 };
+  }
+  if (!session || !session.token) {
+    return { ok: false, reason: "not_authenticated", sessions: [], count: 0 };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  if (includeArchived) query.set("include_archived", "true");
+  const normalizedLimit = Math.max(1, Math.min(200, normalizePositiveInteger(limit, 50)));
+  query.set("limit", String(normalizedLimit));
+  const endpoint = `${apiBaseUrl}/api/v1/sessions?${query.toString()}`;
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      reason: normalizeString(err?.message) || "list_failed",
+      sessions: [],
+      count: 0,
+    };
+  }
+  if (!response || !response.ok) {
+    return {
+      ok: false,
+      reason: `api_${response ? response.status : "no_response"}`,
+      sessions: [],
+      count: 0,
+    };
+  }
+  const payload = await response.json().catch(() => ({}));
+  const sessions = Array.isArray(payload?.sessions) ? payload.sessions : [];
+  return {
+    ok: true,
+    reason: "",
+    sessions,
+    count: typeof payload?.count === "number" ? payload.count : sessions.length,
+  };
+}
+
+/**
+ * Probe whether a single session is visible to the active user.
+ *
+ * Used by `session sync` to discriminate between "owned but empty" and
+ * "not a member / wrong session id" — the former is a quiet success,
+ * the latter deserves a loud hint.
+ *
+ * @returns {Promise<{accessible: boolean, reason: string, status?: number}>}
+ */
+export async function probeSessionAccess(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { accessible: false, reason: "invalid_session_id" };
+  }
+
+  let session;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { accessible: false, reason: "no_session" };
+  }
+  if (!session || !session.token) {
+    return { accessible: false, reason: "not_authenticated" };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(
+    normalizedSessionId,
+  )}/events?limit=1`;
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+    );
+  } catch (err) {
+    return {
+      accessible: false,
+      reason: normalizeString(err?.message) || "probe_failed",
+    };
+  }
+
+  if (response && response.ok) {
+    return { accessible: true, reason: "", status: response.status };
+  }
+  if (!response) {
+    return { accessible: false, reason: "no_response" };
+  }
+  if (response.status === 403) {
+    return { accessible: false, reason: "not_a_member", status: 403 };
+  }
+  if (response.status === 404) {
+    return { accessible: false, reason: "session_not_found", status: 404 };
+  }
+  return { accessible: false, reason: `api_${response.status}`, status: response.status };
+}
+
 export function resetSessionSyncStateForTests() {
   outboundCircuit.consecutiveFailures = 0;
   outboundCircuit.openedAtMs = 0;

package/src/session/transcript.js

@@ -0,0 +1,423 @@
+/**
+ * Session transcript renderer — produces an iMessage-style Markdown
+ * document from a session's NDJSON event stream + agent roster +
+ * metadata. Deterministic: same inputs → identical output (modulo the
+ * `generatedAt` line in the header).
+ *
+ * Adds at render time:
+ *   - Per-agent active duration (first → last event with that agent id)
+ *   - Total session live-for (createdAt → last event)
+ *   - Token + cost roll-up if events carry usage payloads
+ *   - Avatar per speaker, picked from PERSONA_VISUALS / CLIENT_FAMILY_AVATARS,
+ *     or a deterministic letter-tile fallback
+ *   - Senti-orchestrator events tagged with the orchestrator avatar so
+ *     "if orchestrator did anything it signs its name + time" — even
+ *     when the underlying event came from a worker job
+ *
+ * Scales: O(events + agents). Tested up to 20 speakers without degradation.
+ */
+
+import { PERSONA_VISUALS, ORCHESTRATOR_VISUALS } from "../agents/persona-visuals.js";
+
+/**
+ * Avatar map for client families (the OUTSIDE-the-persona-set agents
+ * that show up in any session: human users, browser-side coding
+ * assistants, etc). Keep emoji + a one-color hint so terminal + web
+ * renderers can tint consistently.
+ */
+export const CLIENT_FAMILY_AVATARS = Object.freeze({
+  human: { avatar: "🧑", color: "blue", label: "Human" },
+  claude: { avatar: "🟣", color: "purple", label: "Claude" },
+  codex: { avatar: "🟢", color: "green", label: "Codex" },
+  gpt: { avatar: "🟢", color: "green", label: "GPT" },
+  gemini: { avatar: "🔷", color: "cyan", label: "Gemini" },
+  grok: { avatar: "⚫", color: "gray", label: "Grok" },
+  cli: { avatar: "💻", color: "white", label: "CLI" },
+  guest: { avatar: "👤", color: "gray", label: "Guest" },
+  senti: { avatar: "🛡️", color: "gold", label: "Senti" },
+});
+
+const TRANSCRIPT_EVENT_KINDS = new Set([
+  "session_message",
+  "session_say",
+  "agent_response",
+  "human_relay",
+  "agent_join",
+  "agent_left",
+  "agent_killed",
+  "agent_identified",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+const SYSTEM_EVENT_KINDS = new Set([
+  "agent_join",
+  "agent_left",
+  "agent_killed",
+  "agent_identified",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+function normalize(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function detectFamily(modelOrId) {
+  const v = normalize(modelOrId).toLowerCase();
+  if (!v) return "guest";
+  if (v.includes("senti") || v.includes("kai-chen")) return "senti";
+  if (v.includes("claude") || v.includes("sonnet") || v.includes("opus")) return "claude";
+  if (v.includes("codex") || v.startsWith("gpt-") || v === "gpt") return "codex";
+  if (v.includes("gemini")) return "gemini";
+  if (v.includes("grok")) return "grok";
+  if (v.startsWith("human-") || v.includes("human")) return "human";
+  if (v === "cli" || v.startsWith("cli-")) return "cli";
+  if (v.startsWith("guest-")) return "guest";
+  return v.split(/[\s:/_-]+/).find(Boolean) || "guest";
+}
+
+function letterTile(label) {
+  const trimmed = normalize(label);
+  if (!trimmed) return "·";
+  return trimmed.slice(0, 2).toUpperCase();
+}
+
+/**
+ * Resolve a speaker's display identity given the agent id, model, and
+ * whatever profile bag the caller provides (e.g. github avatar URL,
+ * google photo URL, friendly name from auth).
+ */
+export function resolveSpeakerIdentity({
+  agentId,
+  agentModel = "",
+  profile = null,
+} = {}) {
+  const id = normalize(agentId) || "unknown";
+  const lowerId = id.toLowerCase();
+
+  // 1. Persona visuals — Nina, Maya, Jules, etc.
+  if (PERSONA_VISUALS[lowerId]) {
+    const v = PERSONA_VISUALS[lowerId];
+    return {
+      agentId: id,
+      family: lowerId,
+      avatar: v.avatar,
+      avatarUrl: null,
+      color: v.color,
+      displayName: v.fullName || v.shortName || id,
+    };
+  }
+
+  // 2. Orchestrator visuals — Senti / Kai Chen
+  if (lowerId === "senti" || lowerId === "kai-chen") {
+    const v = ORCHESTRATOR_VISUALS["kai-chen"] || {};
+    return {
+      agentId: id,
+      family: "senti",
+      avatar: v.avatar || CLIENT_FAMILY_AVATARS.senti.avatar,
+      avatarUrl: null,
+      color: v.color || CLIENT_FAMILY_AVATARS.senti.color,
+      displayName: v.fullName || "Senti",
+    };
+  }
+
+  // 3. Caller-provided profile (github avatar, google photo) wins for humans.
+  if (profile && (profile.avatarUrl || profile.displayName)) {
+    return {
+      agentId: id,
+      family: profile.family || detectFamily(id || agentModel),
+      avatar: profile.avatar || CLIENT_FAMILY_AVATARS.human.avatar,
+      avatarUrl: normalize(profile.avatarUrl) || null,
+      color: profile.color || CLIENT_FAMILY_AVATARS.human.color,
+      displayName: normalize(profile.displayName) || id,
+    };
+  }
+
+  // 4. Client family fallback by model / id pattern.
+  const family = detectFamily(agentModel || id);
+  const fallback = CLIENT_FAMILY_AVATARS[family] || CLIENT_FAMILY_AVATARS.guest;
+  return {
+    agentId: id,
+    family,
+    avatar: fallback.avatar,
+    avatarUrl: null,
+    color: fallback.color,
+    displayName: id || letterTile(family),
+  };
+}
+
+function eventTimestamp(event) {
+  return normalize(event?.ts || event?.timestamp);
+}
+
+function eventBody(event) {
+  const payload = event && typeof event.payload === "object" ? event.payload : {};
+  const text =
+    payload.message ||
+    payload.response ||
+    payload.text ||
+    payload.alert ||
+    payload.reason ||
+    "";
+  return normalize(text);
+}
+
+/**
+ * Compute deterministic activity stats from the event log:
+ *  - sessionLiveSeconds: created → last event
+ *  - perAgent[agentId]: { firstSeen, lastSeen, eventCount, activeSeconds, family, displayName, model }
+ *  - totals: { tokenTotal, costTotalUsd } summed from any payload.usage hints
+ *  - sentiActions: count of orchestrator events
+ */
+export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerProfiles = new Map() } = {}) {
+  const perAgent = new Map();
+  let firstEventTs = null;
+  let lastEventTs = null;
+  let tokenTotal = 0;
+  let costTotalUsd = 0;
+  let sentiActions = 0;
+
+  for (const event of events) {
+    const ts = eventTimestamp(event);
+    if (!ts) continue;
+    const epoch = Date.parse(ts);
+    if (!Number.isFinite(epoch)) continue;
+    if (firstEventTs == null || epoch < firstEventTs) firstEventTs = epoch;
+    if (lastEventTs == null || epoch > lastEventTs) lastEventTs = epoch;
+
+    const agentId = normalize(event.agent?.id || event.agentId);
+    if (!agentId) continue;
+    const lowerId = agentId.toLowerCase();
+    if (lowerId === "senti" || lowerId === "kai-chen") sentiActions += 1;
+
+    if (!perAgent.has(agentId)) {
+      const profile = speakerProfiles.get(agentId) || null;
+      const identity = resolveSpeakerIdentity({
+        agentId,
+        agentModel: event.agent?.model || event.agentModel || "",
+        profile,
+      });
+      perAgent.set(agentId, {
+        agentId,
+        family: identity.family,
+        displayName: identity.displayName,
+        avatar: identity.avatar,
+        avatarUrl: identity.avatarUrl,
+        color: identity.color,
+        model: event.agent?.model || event.agentModel || "",
+        firstSeenMs: epoch,
+        lastSeenMs: epoch,
+        eventCount: 0,
+        tokens: 0,
+        costUsd: 0,
+      });
+    }
+    const record = perAgent.get(agentId);
+    record.eventCount += 1;
+    if (epoch < record.firstSeenMs) record.firstSeenMs = epoch;
+    if (epoch > record.lastSeenMs) record.lastSeenMs = epoch;
+
+    const usage = event?.payload?.usage;
+    if (usage && typeof usage === "object") {
+      const t =
+        Number(usage.totalTokens || usage.total_tokens || usage.tokens || 0) || 0;
+      const c = Number(usage.costUsd || usage.cost_usd || usage.cost || 0) || 0;
+      record.tokens += t;
+      record.costUsd += c;
+      tokenTotal += t;
+      costTotalUsd += c;
+    }
+  }
+
+  const createdAtMs = sessionMeta?.createdAt
+    ? Date.parse(sessionMeta.createdAt)
+    : null;
+  let startedAtMs;
+  if (Number.isFinite(createdAtMs) && firstEventTs != null) {
+    // Imported sessions can have events older than the local createdAt;
+    // pick the earlier of the two so live-for never goes negative.
+    startedAtMs = Math.min(createdAtMs, firstEventTs);
+  } else if (Number.isFinite(createdAtMs)) {
+    startedAtMs = createdAtMs;
+  } else {
+    startedAtMs = firstEventTs;
+  }
+  const sessionLiveSeconds =
+    startedAtMs != null && lastEventTs != null
+      ? Math.max(0, Math.round((lastEventTs - startedAtMs) / 1000))
+      : 0;
+
+  const agents = [];
+  for (const record of perAgent.values()) {
+    agents.push({
+      ...record,
+      activeSeconds: Math.max(0, Math.round((record.lastSeenMs - record.firstSeenMs) / 1000)),
+      firstSeen: new Date(record.firstSeenMs).toISOString(),
+      lastSeen: new Date(record.lastSeenMs).toISOString(),
+    });
+  }
+  agents.sort((a, b) => b.eventCount - a.eventCount);
+
+  return {
+    startedAt: startedAtMs ? new Date(startedAtMs).toISOString() : null,
+    endedAt: lastEventTs ? new Date(lastEventTs).toISOString() : null,
+    sessionLiveSeconds,
+    agents,
+    totals: { tokenTotal, costTotalUsd },
+    sentiActions,
+  };
+}
+
+function formatDuration(seconds) {
+  const s = Math.max(0, Math.round(seconds));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const remS = s % 60;
+  if (m < 60) return `${m}m ${remS}s`;
+  const h = Math.floor(m / 60);
+  const remM = m % 60;
+  if (h < 24) return `${h}h ${remM}m`;
+  const d = Math.floor(h / 24);
+  const remH = h % 24;
+  return `${d}d ${remH}h`;
+}
+
+function timestampOnly(iso) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toISOString().replace("T", " ").replace(/\..+/, " UTC");
+}
+
+function avatarMd(identity) {
+  if (identity.avatarUrl) {
+    return `![${identity.displayName}](${identity.avatarUrl})`;
+  }
+  return identity.avatar || letterTile(identity.displayName || identity.agentId);
+}
+
+/**
+ * Build the iMessage-style markdown transcript.
+ *
+ * @param {object} params
+ * @param {object} params.sessionMeta  - { sessionId, createdAt, status, ... }
+ * @param {Array<object>} params.events
+ * @param {Array<object>} [params.agents] - registered agents (optional)
+ * @param {Map<string, object>} [params.speakerProfiles] - agentId →
+ *   { displayName, avatarUrl, family, color }. Used to surface real
+ *   GitHub / Google photos for human users.
+ * @param {object} [params.options]
+ * @param {boolean} [params.options.includeSystemEvents=true]
+ * @returns {{ markdown: string, stats: object }}
+ */
+export function buildTranscriptMarkdown({
+  sessionMeta = {},
+  events = [],
+  agents = [],
+  speakerProfiles = new Map(),
+  options = {},
+} = {}) {
+  const includeSystemEvents = options.includeSystemEvents !== false;
+  const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles });
+
+  const lines = [];
+  const sessionId = normalize(sessionMeta.sessionId) || "unknown";
+  lines.push(`# Session ${sessionId}`);
+  lines.push("");
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  if (stats.startedAt) lines.push(`Started: ${stats.startedAt}`);
+  if (stats.endedAt) lines.push(`Last activity: ${stats.endedAt}`);
+  lines.push(`Live for: ${formatDuration(stats.sessionLiveSeconds)}`);
+  lines.push(`Senti actions: ${stats.sentiActions}`);
+  if (stats.totals.tokenTotal > 0 || stats.totals.costTotalUsd > 0) {
+    lines.push(
+      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}`,
+    );
+  }
+  lines.push("");
+
+  // Participants table
+  lines.push("## Participants");
+  lines.push("");
+  lines.push("| Avatar | Name | Family | Active for | Events | Tokens | Cost |");
+  lines.push("|---|---|---|---:|---:|---:|---:|");
+  for (const agent of stats.agents) {
+    const identity = {
+      avatar: agent.avatar,
+      avatarUrl: agent.avatarUrl,
+      displayName: agent.displayName,
+      agentId: agent.agentId,
+    };
+    lines.push(
+      `| ${avatarMd(identity)} | **${agent.displayName}** \`${agent.agentId}\` | ${agent.family} | ${formatDuration(agent.activeSeconds)} | ${agent.eventCount} | ${agent.tokens.toLocaleString("en-US")} | $${agent.costUsd.toFixed(4)} |`,
+    );
+  }
+  if (stats.agents.length === 0) {
+    lines.push("| 👤 | (no agents joined) | — | 0s | 0 | 0 | $0.00 |");
+  }
+  // Surface registered-but-silent agents at the bottom of the table so
+  // the participants list is comprehensive even if they never emitted
+  // a stream event.
+  const seenIds = new Set(stats.agents.map((a) => a.agentId));
+  for (const registered of agents || []) {
+    const id = normalize(registered?.agentId);
+    if (!id || seenIds.has(id)) continue;
+    const profile = speakerProfiles.get(id) || null;
+    const identity = resolveSpeakerIdentity({
+      agentId: id,
+      agentModel: registered.model || "",
+      profile,
+    });
+    lines.push(
+      `| ${avatarMd(identity)} | **${identity.displayName}** \`${id}\` | ${identity.family} | 0s · idle | 0 | 0 | $0.0000 |`,
+    );
+  }
+  lines.push("");
+
+  // Conversation
+  lines.push("## Conversation");
+  lines.push("");
+  for (const event of events) {
+    const kind = normalize(event.event || event.type);
+    if (!kind || !TRANSCRIPT_EVENT_KINDS.has(kind)) continue;
+    if (!includeSystemEvents && SYSTEM_EVENT_KINDS.has(kind)) continue;
+
+    const agentId = normalize(event.agent?.id || event.agentId);
+    const profile = speakerProfiles.get(agentId) || null;
+    const identity = resolveSpeakerIdentity({
+      agentId,
+      agentModel: event.agent?.model || event.agentModel || "",
+      profile,
+    });
+    const ts = eventTimestamp(event);
+    const body = eventBody(event);
+
+    if (SYSTEM_EVENT_KINDS.has(kind)) {
+      const hint = body || kind.replace(/_/g, " ");
+      lines.push(
+        `- _${timestampOnly(ts)} · ${avatarMd(identity)} **${identity.displayName}** ${hint}_`,
+      );
+      continue;
+    }
+
+    lines.push(`### ${avatarMd(identity)} ${identity.displayName}`);
+    lines.push(`> ${timestampOnly(ts)}`);
+    lines.push("");
+    if (body) {
+      const indented = body
+        .split(/\r?\n/)
+        .map((line) => (line ? line : ""))
+        .join("\n");
+      lines.push(indented);
+    } else {
+      lines.push(`_${kind}_`);
+    }
+    lines.push("");
+  }
+
+  return {
+    markdown: lines.join("\n"),
+    stats,
+  };
+}