@jeffober/thatch 0.1.42 → 0.1.44

package/src/chat.ts

@@ -1,4 +1,6 @@
 import type { Database } from "bun:sqlite";
+import { openSync, readSync, closeSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { CHAT_NAME_POOL } from "./chat-names";
 
 /**
@@ -46,6 +48,13 @@ export function isoMinutesAgo(minutes: number): string {
   return new Date(Date.now() - minutes * 60_000).toISOString().slice(0, 19) + "Z";
 }
 
+/** Where the session's host process is running its checkout: "root" for the
+ *  project's main checkout, "worktree" for a linked git worktree, null when
+ *  undetected (e.g. an MCP host with no directory context). Displayed in
+ *  the roster so sessions coordinating on a shared tree can tell who sits
+ *  where. */
+export type ChatWorktreeKind = "root" | "worktree" | null;
+
 export interface ChatSessionRow {
   session_id: string;
   name: string;
@@ -57,6 +66,7 @@ export interface ChatSessionRow {
   host_kind: ChatHostKind;
   registered_at: string;
   last_seen: string;
+  worktree: ChatWorktreeKind;
 }
 
 /** One message selected for wake-up delivery, with the sender's display name
@@ -90,8 +100,112 @@ export function mcpSessionID(hostSessionID: string): string {
   return `mcp_${hash}`;
 }
 
+/**
+ * Reads a Claude Code transcript's last line and returns the session id the
+ * conversation continued INTO, when the file ends with a continued-in record
+ * (Claude Code writes it when a conversation is resumed or forked into a new
+ * session id). Returns null otherwise. This is the link that lets a hook
+ * follow a continuation backwards: the NEW session id is all the hook knows,
+ * and the OLD transcript names it.
+ */
+export function continuedInTarget(transcriptPath: string): string | null {
+  let raw: string;
+  try {
+    // The marker is the file's final record; reading the tail avoids
+    // loading potentially large transcripts.
+    const stat = statSync(transcriptPath);
+    const tailLen = Math.min(stat.size, 4096);
+    const buf = Buffer.alloc(tailLen);
+    const fd = openSync(transcriptPath, "r");
+    try {
+      readSync(fd, buf, 0, tailLen, stat.size - tailLen);
+    } finally {
+      closeSync(fd);
+    }
+    raw = buf.toString("utf8");
+  } catch {
+    return null;
+  }
+  const lines = raw.trimEnd().split("\n").filter((l) => l.trim());
+  const last = lines[lines.length - 1];
+  if (!last) return null;
+  try {
+    const record = JSON.parse(last) as { type?: string; continuedInSessionId?: string };
+    if (record.type !== "continued-in" || !record.continuedInSessionId) return null;
+    return record.continuedInSessionId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Finds the immediate predecessor of a continued session by scanning the
+ * transcript directory for a sibling whose tail hands off TO this session
+ * (see continuedInTarget). Most recently modified wins. Returns the
+ * predecessor's raw session id (transcript file stem), or null.
+ */
+export function scanPredecessorTranscript(
+  transcriptPath: string,
+  sessionID: string,
+  maxFiles = 200,
+): string | null {
+  const dir = dirname(transcriptPath);
+  let files: string[];
+  try {
+    files = readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl") && f !== basename(transcriptPath))
+      .map((f) => {
+        try {
+          return { f, m: statSync(join(dir, f)).mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter((e): e is { f: string; m: number } => e !== null)
+      .sort((a, b) => b.m - a.m)
+      .slice(0, maxFiles)
+      .map((e) => e.f);
+  } catch {
+    return null;
+  }
+  for (const f of files) {
+    if (continuedInTarget(join(dir, f)) === sessionID) {
+      return f.slice(0, -".jsonl".length);
+    }
+  }
+  return null;
+}
+
+/**
+ * Walks a continuation chain back to the nearest session that has a chat
+ * directory row. Claude Code sessions fork on resume (new session id, same
+ * conversation), so a hook registering an unknown session id can adopt the
+ * predecessor's identity - same name, same mailbox - instead of stranding
+ * it. `isRegistered` maps a raw host session id to its chat session id when
+ * that row exists, else null. Bounded by maxHops; multi-hop forks resolve
+ * to the oldest registered ancestor.
+ */
+export function resolveRegisteredPredecessor(
+  transcriptPath: string,
+  sessionID: string,
+  isRegistered: (rawSessionID: string) => string | null,
+  maxHops = 10,
+): string | null {
+  let current = sessionID;
+  let currentPath = transcriptPath;
+  for (let hop = 0; hop < maxHops; hop++) {
+    const pred = scanPredecessorTranscript(currentPath, current);
+    if (!pred) return null;
+    const registered = isRegistered(pred);
+    if (registered) return registered;
+    current = pred;
+    currentPath = join(dirname(transcriptPath), `${pred}.jsonl`);
+  }
+  return null;
+}
+
 /** Which kind of harness hosts a chat session: opencode rows are
- *  poller-driven (liveness = process alive), mcp rows are turn-driven
+ *  poller-driven (liveness = heartbeat fresh), mcp rows are turn-driven
  *  (liveness = a turn ran recently; mail is read at the next prompt). */
 export type ChatHostKind = "opencode" | "mcp";
 
@@ -100,10 +214,11 @@ export type ChatHostKind = "opencode" | "mcp";
 // into a context bomb; the reader fetches full content via chat_read anyway.
 const MAX_BODY_LEN = 10_000;
 
-// Assigned names are lowercase slugs with a numeric counter suffix
-// ("fix-auth-bug-00001"), which satisfies NAME_CHARSET. The charset stays
-// exported for the pool conformance test. Slugs never contain underscores,
-// so the name-cannot-shadow-an-ID invariant in find() still holds.
+// Assigned names are lowercase slugs of a pool name with a numeric counter
+// suffix ("al-go-rithm-00001"), which satisfies NAME_CHARSET. The charset
+// stays exported for the pool conformance test. Slugs never contain
+// underscores, so the name-cannot-shadow-an-ID invariant in find() still
+// holds.
 export const NAME_CHARSET = /^[\p{L}\p{N} '.\-]+$/u;
 
 // Topics are free text (unlike names) but must stay one line for the
@@ -114,7 +229,7 @@ const MAX_TOPIC_LEN = 80;
 // many days are pruned from the directory. Counters never decrement, so a
 // pruned session's name is never reissued - pruning cannot create identity
 // confusion, only roster silence.
-export const CHAT_AUTO_TTL_DAYS = 7;
+const CHAT_AUTO_TTL_DAYS = 7;
 
 /**
  * Slugifies a session title into a name base: lowercase, letter/number runs
@@ -148,12 +263,94 @@ export function isDefaultSessionTitle(title: string): boolean {
   return /^New session - /.test(title) || /^Child session - /.test(title);
 }
 
-// Timing defaults, shared by the poller and the chat_list staleness display
-// so both agree on what "stale" means.
+// Poller cadence. A hosting harness beats each of its sessions once per
+// interval and delivers their mail on the same tick.
 export const CHAT_POLL_INTERVAL_MS = 30_000;
-export const CHAT_STALE_MINUTES = 10;
+// Staleness threshold, shared by the poller, chat_list, chat_send, and the
+// broadcast skip so every surface agrees on what "stale" means: a row that
+// has missed two consecutive beats belongs to a harness that stopped
+// (crash, kill, machine asleep). Two beats rather than one so a single
+// late poll cycle does not flap the roster.
+export const CHAT_STALE_MS = 2 * CHAT_POLL_INTERVAL_MS;
+// Wake re-nudge window and the per-recipient hourly nudge cap (the anti-loop
+// hard brake); see ChatPoller.
 export const CHAT_RENUDGE_MINUTES = 15;
-export const CHAT_MAX_NUDGES_PER_HOUR = 6;
+const CHAT_MAX_NUDGES_PER_HOUR = 6;
+
+/** Human-readable age of an ISO timestamp: "45s ago", "5m ago", "3h ago",
+ *  "2d ago". Shared by the CLI roster and the chat_list tool so both
+ *  surfaces render the same last-check-in wording. */
+export function humanAge(iso: string, now = Date.now()): string {
+  const seconds = Math.max(0, Math.floor((now - Date.parse(iso)) / 1000));
+  if (Number.isNaN(seconds)) return "unknown age";
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  if (minutes < 24 * 60) return `${Math.floor(minutes / 60)}h ago`;
+  return `${Math.floor(minutes / (24 * 60))}d ago`;
+}
+
+/** The liveness verdict for one roster row, from heartbeat age alone:
+ *  - "fresh"/"stale" for opencode rows (poller-driven heartbeat; stale means *    the hosting harness has missed two beats and is presumed gone)
+ *  - "active"/"idle" for MCP rows (turn-driven; idle between prompts is the
+ *    NORMAL state, so an idle MCP row is reachable, not dead)
+ *  Heartbeat age is the only signal on purpose. A process id cannot serve:
+ *  the same session is re-hosted by a new process on every `-s` resume, so
+ *  a pid stamped on the row lies as soon as a different harness beats it.
+ *  One clock, one rule. */
+export function chatLiveness(row: ChatSessionRow, now = Date.now()): "fresh" | "stale" | "active" | "idle" {
+  const stale = isStale(row, now);
+  if (row.host_kind === "mcp") return stale ? "idle" : "active";
+  return stale ? "stale" : "fresh";
+}
+
+/** Splits the roster for the two-section display: Active (wake-able or
+ *  reachable - fresh opencode rows and every MCP row, which read mail at
+ *  their next prompt) and Stale (opencode rows whose harness has stopped
+ *  reporting; mail to them waits until they resume). */
+export function splitChatRoster(rows: ChatSessionRow[], now = Date.now()): { active: ChatSessionRow[]; stale: ChatSessionRow[] } {
+  const active: ChatSessionRow[] = [];
+  const stale: ChatSessionRow[] = [];
+  for (const row of rows) {
+    (chatLiveness(row, now) === "stale" ? stale : active).push(row);
+  }
+  return { active, stale };
+}
+
+/**
+ * The wake-delivery gate, shared by the chat poller and the watcher
+ * registry: can this session be woken with a prompt right now? Three
+ * layers - the compacting set, the event-fed status map (cheap pre-filter
+ * for KNOWN busy/retry states), and the server's authoritative live status
+ * map. ABSENCE from the event-fed map is not evidence of busy: the `-s`
+ * startup session is hosted from init, before it has emitted any status
+ * event, so absence falls through to the live check. A gate that rejected
+ * on absence would leave that session mail-deaf - beating fine, never
+ * woken - until its first turn. The live
+ * map only carries ACTIVE sessions - the server deletes idle entries - so
+ * absent means idle there; busy/retry fails closed, as does an unreachable
+ * server (the mail stays pending and retries).
+ */
+export function createWakeGate(deps: {
+  isCompacting: (sessionID: string) => boolean;
+  mappedStatus: (sessionID: string) => string | undefined;
+  fetchStatuses: () => Promise<Record<string, { type?: string } | undefined>>;
+  onStatusError?: (sessionID: string, err: unknown) => void;
+}): (sessionID: string) => Promise<boolean> {
+  return async (sessionID: string) => {
+    if (deps.isCompacting(sessionID)) return false;
+    const mapped = deps.mappedStatus(sessionID);
+    if (mapped === "busy" || mapped === "retry") return false;
+    try {
+      const statuses = await deps.fetchStatuses();
+      const live = statuses[sessionID];
+      return !live || live.type === "idle";
+    } catch (err) {
+      deps.onStatusError?.(sessionID, err);
+      return false;
+    }
+  };
+}
 
 /**
  * SQLite CRUD for the chat tables. Constructed by ThatchDB with the shared
@@ -169,17 +366,20 @@ export class ChatStore {
   /**
    * Joins the directory, or refreshes an existing registration. Names are
    * assigned by the system, never claimed: a new session gets
-   * "<slug>-<counter>" (e.g. "fix-auth-bug-00001"), where the slug comes
-   * from the session title (or a pool-draw slug when there is none) and the
-   * per-base counter only ever increments - so a name is minted exactly
-   * once, machine-wide, and pruning an old session can never reissue its
-   * name to someone else. Idempotent for an already-registered session: it
-   * keeps its name and just refreshes liveness.
+   * "<slug>-<counter>" (e.g. "al-go-rithm-00001"), where the slug is a
+   * random pool name (chat-names.ts) and the per-base counter only ever
+   * increments - so a name is minted exactly once, machine-wide, and
+   * pruning an old session can never reissue its name to someone else. The
+   * session title never feeds the name; it rides along as the topic, so a
+   * placeholder or later-edited title cannot leave a misleading name
+   * behind. Idempotent for an already-registered session: it keeps its
+   * name and just refreshes liveness.
    *
-   * `nameBase` is the slugified title for a new registration (null draws a
-   * pool slug instead). `topic` is the live title for auto-registrations;
-   * null leaves the topic unset. Every row minted here is marked auto=1 -
-   * rows with auto=0 exist only as legacy data from the claimed-names era.
+   * `nameBase` overrides the pool draw with a fixed base (tests only; every
+   * production caller passes null). `topic` is the live title for
+   * auto-registrations; null leaves the topic unset. Every row minted here
+   * is marked auto=1 - rows with auto=0 exist only as legacy data from the
+   * claimed-names era.
    */
   register(
     sessionID: string,
@@ -187,9 +387,14 @@ export class ChatStore {
     topic: string | null,
     kind: ChatHostKind,
     nameBase: string | null = null,
-  ): { ok: true; name: string; topic: string | null } | { ok: false; error: string } {
+    worktree: ChatWorktreeKind = null,
+  ): { ok: true; name: string; topic: string | null; created: boolean } | { ok: false; error: string } {
     const existing = this.#find(sessionID);
     if (existing) {
+      // Reclaim: registration is keyed by session id, so a session
+      // continued in a new harness process (`opencode -s <id>`) reclaims
+      // its row and name by re-registering. Touching last_seen is the
+      // whole of ownership: the harness that beats a row is its host.
       this.#touch(sessionID);
       // An explicit registration clears the leave tombstone for its own
       // session ID: "I want back in" is the opposite of "I left". This is
@@ -200,7 +405,7 @@ export class ChatStore {
       // session.deleted suppresses exactly that session.
       const gate = this.#tombstoneGate(sessionID, kind);
       if (gate) return gate;
-      return { ok: true, name: existing.name, topic: existing.topic };
+      return { ok: true, name: existing.name, topic: existing.topic, created: false };
     }
     const gate = this.#tombstoneGate(sessionID, kind);
     if (gate) return gate;
@@ -216,13 +421,13 @@ export class ChatStore {
     for (let attempt = 0; attempt < 10; attempt++) {
       const next = this.#bumpCounter(base);
       const name = `${base}-${String(next).padStart(5, "0")}`;
-      const claimed = this.#insertSession(sessionID, name, project, cleanTopic, kind);
-      if (claimed.ok) return { ok: true, name, topic: cleanTopic };
+      const claimed = this.#insertSession(sessionID, name, project, cleanTopic, kind, worktree);
+      if (claimed.ok) return { ok: true, name, topic: cleanTopic, created: true };
       if (claimed.reason === "already-registered") {
         // A concurrent registration of the same session ID won the race;
         // report its row rather than erroring.
         const winner = this.#find(sessionID);
-        if (winner) return { ok: true, name: winner.name, topic: winner.topic };
+        if (winner) return { ok: true, name: winner.name, topic: winner.topic, created: false };
       }
     }
     return { ok: false, error: "Could not assign a unique name after several attempts." };
@@ -335,7 +540,7 @@ export class ChatStore {
 
   list(): ChatSessionRow[] {
     return (this.#db
-      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions ORDER BY name")
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen, worktree FROM chat_sessions ORDER BY name")
       .all() as any[]).map(rowFromSession);
   }
 
@@ -411,7 +616,7 @@ export class ChatStore {
         // Staleness means "host process gone" only for opencode rows; an
         // mcp row between turns reads its mail at the next prompt, so it
         // always receives.
-        if (row.host_kind === "opencode" && isStale(row, CHAT_STALE_MINUTES)) {
+        if (row.host_kind === "opencode" && isStale(row)) {
           skipped.push(row.name);
           continue;
         }
@@ -465,6 +670,65 @@ export class ChatStore {
     return row.n;
   }
 
+  /**
+   * Records (or refreshes) the hook-parent-process -> session mapping: the
+   * identity anchor that closes the caller-claimed `as` hole on Claude Code.
+   * Hooks receive the true session id from the host and run as children of
+   * the same Claude Code process that spawned the MCP server, so the server
+   * can resolve its own parent pid against this mapping - a fact the model
+   * cannot influence. Recorded only from payloads that carried Claude Code's
+   * `session_id`; Cursor's hooks come from a shared extension host with
+   * per-workspace MCP servers, so ppid is ambiguous there and `as` stays the
+   * identity source.
+   */
+  recordHostPid(ppid: number, sessionID: string): void {
+    this.#db.run(
+      `INSERT INTO chat_host_pids (ppid, session_id, seen_at) VALUES (?, ?, ?)
+       ON CONFLICT(ppid) DO UPDATE SET session_id = excluded.session_id, seen_at = excluded.seen_at`,
+      [ppid, sessionID, nowIso()],
+    );
+  }
+
+  /**
+   * Resolves a host process id to a chat session id, when a hook recorded
+   * the mapping recently and the session still exists in the directory.
+   * Freshness bounds the pid-reuse hazard: a dead host's pid can be
+   * reassigned by the OS, and a stale mapping must not hand the new
+   * occupant the old conversation's identity.
+   */
+  findSessionByHostPid(ppid: number, maxAgeSeconds: number): string | null {
+    const cutoff = isoMinutesAgo(Math.ceil(maxAgeSeconds / 60));
+    const row = this.#db
+      .query(
+        `SELECT p.session_id FROM chat_host_pids p
+         JOIN chat_sessions s ON s.session_id = p.session_id
+         WHERE p.ppid = ? AND p.seen_at >= ?`,
+      )
+      .get(ppid, cutoff) as { session_id: string } | undefined;
+    return row?.session_id ?? null;
+  }
+
+  /**
+   * Migrates a chat identity onto a continued session id. Claude Code forks
+   * the session id on resume/fork while the conversation (name, mailbox,
+   * leave state) belongs to the human-level conversation, so the old row's
+   * key moves forward and everything referencing the old key follows:
+   * message sender/recipient columns (no foreign keys by design - the
+   * departed-sender degradation must not apply to a continued conversation),
+   * hook-recorded host-pid anchors, and leave tombstones. No-op when the
+   * old row does not exist.
+   */
+  continueSession(oldSessionID: string, newSessionID: string): void {
+    if (oldSessionID === newSessionID) return;
+    const row = this.#db.query("SELECT session_id FROM chat_sessions WHERE session_id = ?").get(oldSessionID);
+    if (!row) return;
+    this.#db.run("UPDATE chat_sessions SET session_id = ? WHERE session_id = ?", [newSessionID, oldSessionID]);
+    this.#db.run("UPDATE chat_messages SET from_session = ? WHERE from_session = ?", [newSessionID, oldSessionID]);
+    this.#db.run("UPDATE chat_messages SET to_session = ? WHERE to_session = ?", [newSessionID, oldSessionID]);
+    this.#db.run("UPDATE chat_host_pids SET session_id = ? WHERE session_id = ?", [newSessionID, oldSessionID]);
+    this.#db.run("UPDATE chat_leave_tombstones SET session_id = ? WHERE session_id = ?", [newSessionID, oldSessionID]);
+  }
+
   /**
    * The caller's mailbox summary for chat_status: whether a directory row
    * exists, and pending/total counts. Touches last_seen on use, which is
@@ -512,18 +776,15 @@ export class ChatStore {
     ).map((r) => ({ name: r.name, pending: r.pending }));
   }
 
-  /** Refreshes last_seen for the given sessions. Sessions that never
-   *  registered are absent from chat_sessions, so the UPDATE is a no-op for
-   *  them - no filtering needed on the caller's side. */
+  /** Refreshes last_seen for the given sessions - the heartbeat that keeps
+   *  them out of the stale section. Sessions that never registered are absent from
+   *  chat_sessions, so the UPDATE is a no-op for them - no filtering needed
+   *  on the caller's side. */
   heartbeat(sessionIDs: string[]): void {
     if (sessionIDs.length === 0) return;
     const marks = sessionIDs.map(() => "?").join(",");
-    this.#db.run(`UPDATE chat_sessions SET last_seen = ? WHERE session_id IN (${marks})`, [
-      nowIso(),
-      ...sessionIDs,
-    ]);
+    this.#db.run(`UPDATE chat_sessions SET last_seen = ? WHERE session_id IN (${marks})`, [nowIso(), ...sessionIDs]);
   }
-
   /**
    * The full message feed for `thatch chat tail`: every row with sender and
    * recipient display names resolved (departed senders degrade to unknown),
@@ -609,14 +870,14 @@ export class ChatStore {
 
   #find(sessionID: string): ChatSessionRow | null {
     const row = this.#db
-      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions WHERE session_id = ?")
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen, worktree FROM chat_sessions WHERE session_id = ?")
       .get(sessionID) as any;
     return row ? rowFromSession(row) : null;
   }
 
   #findByName(name: string): ChatSessionRow | null {
     const row = this.#db
-      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen FROM chat_sessions WHERE name = ? COLLATE NOCASE")
+      .query("SELECT session_id, name, topic, project, host_kind, registered_at, last_seen, worktree FROM chat_sessions WHERE name = ? COLLATE NOCASE")
       .get(name) as any;
     return row ? rowFromSession(row) : null;
   }
@@ -694,11 +955,12 @@ export class ChatStore {
     project: string | null,
     topic: string | null,
     kind: ChatHostKind,
+    worktree: ChatWorktreeKind,
   ): { ok: true; topic: string | null } | { ok: false; reason: "name-taken" | "already-registered" } {
     try {
       this.#db.run(
-        "INSERT INTO chat_sessions (session_id, name, topic, project, host_kind, registered_at, last_seen, auto) VALUES (?, ?, ?, ?, ?, ?, ?, 1)",
-        [sessionID, name, topic, project, kind, nowIso(), nowIso()],
+        "INSERT INTO chat_sessions (session_id, name, topic, project, host_kind, registered_at, last_seen, auto, worktree) VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?)",
+        [sessionID, name, topic, project, kind, nowIso(), nowIso(), worktree ?? ""],
       );
       return { ok: true, topic };
     } catch (err) {
@@ -726,6 +988,9 @@ function rowFromSession(r: any): ChatSessionRow {
     project: r.project,
     registered_at: r.registered_at,
     last_seen: r.last_seen,
+    // Pre-migration rows carry the empty-string default; read back as
+    // undetected so the roster omits the token instead of printing a blank.
+    worktree: r.worktree === "root" || r.worktree === "worktree" ? r.worktree : null,
   };
 }
 
@@ -746,9 +1011,27 @@ export function renderChatParticipant(name: string | null, sessionID: string | n
 // Tail events (pure logic behind `thatch chat tail`)
 // ---------------------------------------------------------------------------
 
+/**
+ * One line of the `thatch chat tail` event log. Sending a message and
+ * reading it are two events, each on its own line, linked by `id` (the
+ * message row id). Broadcast fan-out is one message row per recipient, so
+ * a broadcast to N sessions is N sent events with `broadcast: true`, each
+ * naming its real recipient and tracking its own read. Timestamps are the
+ * database's ISO-8601 UTC strings, untouched.
+ */
 export type ChatTailEvent =
-  | { kind: "sent"; timestamp: string; from: string; to: string; fromTopic: string | null; toTopic: string | null; body: string }
-  | { kind: "read"; timestamp: string; reader: string; from: string; fromTopic: string | null; toTopic: string | null; body: string };
+  | {
+      event: "sent";
+      at: string;
+      id: number;
+      from: string;
+      from_topic: string | null;
+      to: string;
+      to_topic: string | null;
+      broadcast: boolean;
+      body: string;
+    }
+  | { event: "read"; at: string; id: number; reader: string; reader_topic: string | null; from: string; from_topic: string | null };
 
 /** One message row as the tail diff consumes it. */
 export interface ChatTailRow {
@@ -781,25 +1064,27 @@ export function chatTailDiff(
     const isNew = !prev.has(r.id);
     if (isNew) {
       events.push({
-        kind: "sent",
-        timestamp: r.created_at,
+        event: "sent",
+        at: r.created_at,
+        id: r.id,
         from: r.from ?? "unknown",
-        to: r.viaBroadcast ? "broadcast" : r.to ?? "unknown",
-        fromTopic: r.fromTopic,
-        toTopic: r.viaBroadcast ? null : r.toTopic,
+        from_topic: r.fromTopic,
+        to: r.to ?? "unknown",
+        to_topic: r.toTopic,
+        broadcast: r.viaBroadcast,
         body: r.body,
       });
     } else {
       const prevRead = prev.get(r.id) ?? null;
       if (r.read_at !== null && prevRead === null) {
         events.push({
-          kind: "read",
-          timestamp: r.read_at,
+          event: "read",
+          at: r.read_at,
+          id: r.id,
           reader: r.to ?? "unknown",
+          reader_topic: r.toTopic,
           from: r.from ?? "unknown",
-          fromTopic: r.fromTopic,
-          toTopic: r.toTopic,
-          body: r.body,
+          from_topic: r.fromTopic,
         });
       }
     }
@@ -809,7 +1094,7 @@ export function chatTailDiff(
 }
 
 /**
- * The default number of backlog cards `thatch chat tail` renders before
+ * The default number of backlog messages `thatch chat tail` prints before
  * follow mode takes over. The message table is machine-scale but the
  * history still grows forever, so an unbounded default would dump the
  * entire database on every run.
@@ -818,7 +1103,8 @@ export const CHAT_TAIL_DEFAULT_LIMIT = 20;
 
 /**
  * Parses a tail time-bound value into epoch milliseconds, interpreted in
- * the terminal's local timezone (the same clock the When headers print).
+ * the terminal's local timezone (event timestamps print in UTC; the bounds
+ * are typed by a human at a terminal, so they read as local time).
  * Accepted: "YYYY-MM-DD" (midnight) or "YYYY-MM-DD HH:MM", with either a
  * space or a T between the date and the time. The component round-trip
  * rejects impossible calendar values like 2026-09-31 and 25:99, which
@@ -858,11 +1144,10 @@ function roundTrip(date: Date, y: number, mo: number, d: number, h: number, mi:
  * test the message body; `fromSubstr`/`toSubstr` are case-insensitive
  * substrings of the rendered participant names (so a departed sender can
  * only match as "unknown (...)", the string the reader actually sees).
- * One deliberate asymmetry: broadcast rows keep the real recipient in
- * `to`, so `--to <realname>` matches fan-out rows even though their cards
- * say "broadcast", and `--to broadcast` matches nothing. `sinceMs`/
- * `untilMs` bound created_at in a since-inclusive, until-exclusive
- * window. An empty field is no constraint.
+ * Broadcast fan-out rows carry their real recipient in `to`, so `--to
+ * <name>` matches them like any direct message. `sinceMs`/`untilMs`
+ * bound created_at in a since-inclusive, until-exclusive window. An empty
+ * field is no constraint.
  *
  * Name inputs are not stable across polls: they are re-resolved from the
  * live directory on every feed snapshot, so an unregister or rename
@@ -896,16 +1181,18 @@ export function filterChatTailRows(rows: Array<ChatTailRow>, filter: ChatTailFil
 /**
  * Prepares the tail's first render. The diff state seeds from EVERY row in
  * the feed - filtered or not, rendered or not - for two reasons. First,
- * the limit hides cards, not history: a state seeded only from the
- * rendered slice would re-emit the elided history as new sent events on
+ * the limit hides messages, not history: a state seeded only from the
+ * printed slice would re-emit the elided history as new sent events on
  * the first follow poll. Second, the name filters test JOIN-resolved
  * participant names that can flip mid-follow (a peer unregisters and its
  * history starts rendering as "unknown (... departed)", or it re-registers
  * under a new name); seeding everything means an old row can never resurface
  * as a sent event no matter how its rendered name changes. The last
- * `limit` filtered rows (null = all) shape into sent events via
- * chatTailDiff, so card rendering keeps a single source. `elided` counts
- * matching rows the limit hid, for the CLI's summary line.
+ * `limit` filtered rows (null = all) shape into sent events, plus a read
+ * event for each row already read, via chatTailDiff, so event shaping
+ * keeps a single source. `shown` and `elided` count MESSAGES (not
+ * events: a shown message contributes one or two lines) for the CLI's
+ * summary line.
  *
  * The caller must re-apply the same filter to every follow poll's feed
  * BEFORE the diff (filterChatTailRows, then chatTailDiff with the state
@@ -916,93 +1203,33 @@ export function chatTailBacklog(
   rows: Array<ChatTailRow>,
   filter: ChatTailFilter,
   limit: number | null,
-): { events: ChatTailEvent[]; state: Map<number, string | null>; elided: number } {
+): { events: ChatTailEvent[]; state: Map<number, string | null>; shown: number; elided: number } {
   const state = new Map(rows.map((r) => [r.id, r.read_at]));
   const filtered = filterChatTailRows(rows, filter);
   const shown = limit === null ? filtered : filtered.slice(-limit);
-  const events = chatTailDiff(new Map(), shown).events;
-  return { events, state, elided: filtered.length - shown.length };
-}
-
-/** Renders one tail event in the CLI's line format. */
-export function formatChatTailEvent(event: ChatTailEvent): string {
-  if (event.kind === "sent") {
-    return `[${event.timestamp}] ${event.from} -> ${event.to}: ${event.body}`;
+  // A snapshot has the full history of each shown message: its send, and
+  // its read if read_at is set. Emit both, in time order, so `--once`
+  // prints the same event log a follow would have accumulated. Reads of
+  // messages the limit hid stay hidden with them.
+  const events: ChatTailEvent[] = [];
+  for (const r of shown) {
+    events.push(...chatTailDiff(new Map(), [r]).events);
+    if (r.read_at !== null) events.push(...chatTailDiff(new Map([[r.id, null]]), [r]).events);
   }
-  const clipped = event.body.length > 60 ? event.body.slice(0, 60) + "..." : event.body;
-  return `[${event.timestamp}] ${event.reader} read a message from ${event.from}: ${clipped}`;
-}
-
-/** "2026-09-12 19:46 MT" - the UTC timestamp converted to the terminal's
- *  local timezone (abbreviation from the locale, fallback "UTC"), one line
- *  for the card header. */
-function localWhen(timestamp: string): string {
-  const date = new Date(timestamp);
-  if (Number.isNaN(date.getTime())) return timestamp;
-  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
-  const pad = (n: number) => String(n).padStart(2, "0");
-  return (
-    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
-    `${pad(date.getHours())}:${pad(date.getMinutes())} ${tz}`
-  );
+  events.sort((a, b) => Date.parse(a.at) - Date.parse(b.at) || (a.event === b.event ? 0 : a.event === "sent" ? -1 : 1));
+  return { events, state, shown: shown.length, elided: filtered.length - shown.length };
 }
 
 /**
- * Renders one tail event as a chat card: header block (From / To / When),
- * blank line, full body, then a separator line. This is the human format
- * for `thatch chat tail` - the single-line formatChatTailEvent remains for
- * tests and compact contexts. Read events use the same card shape with the
- * reader in the From slot; broadcast events show "broadcast" as the
- * recipient. The separator is between cards, so the caller joins cards
- * with it and never gets a trailing rule.
+ * Renders one tail event as a JSON line. Plain JSON.stringify of the event
+ * object: no ANSI, no markdown rendering, no local-time conversion. The
+ * tail is a log, and a log is for grep and jq; a terminal reader who wants
+ * color pipes through their own tool.
  */
-// ANSI styling for the tail cards: black-on-green field-label chips, green
-// values, dim for the timestamps and the "read" marker, and a drawn rule
-// for the separator. Bare ESC sequences rather than a color library - the
-// tail is a terminal surface, and the codes are trivial.
-const ANSI = {
-  // Label chips are padded to a fixed width (5 + padding = 7 columns) so
-  // every line's content starts at the same column - To's 2-char label
-  // misaligned against 4-char labels without this.
-  labelBg: (s: string) => `\x1b[30;42m ${s.padEnd(5)} \x1b[0m`,
-  valueFg: (s: string) => `\x1b[32m${s}\x1b[0m`, // green (field values)
-  dim: (s: string) => `\x1b[2m${s}\x1b[0m`, // dim ("read" marker)
-  rule: (s: string) => `\x1b[2m${s}\x1b[0m`, // dim (the drawn separator)
-  // Session-of-origin annotation: italic + bright-black (muted gray).
-  originLabel: (s: string) => `\x1b[3;90m<${s}>\x1b[0m`,
-};
-
-const CARD_INDENT = ""; // cards sit flush with the separator (no extra indent)
-
-export function formatChatTailCard(event: ChatTailEvent): string {
-  const lines: string[] = [];
-  const when = ANSI.dim(localWhen(event.timestamp));
-  // The session-of-origin annotation: the participant's registered topic,
-  // italic + muted bright-black, after the name. Omitted for participants
-  // without a topic (and for the broadcast pseudo-recipient, whose topic
-  // is null by construction).
-  const origin = (topic: string | null) => (topic ? ` ${ANSI.originLabel(topic)}` : "");
-  const chip = (label: string, value: string, topic: string | null) =>
-    `${CARD_INDENT}${ANSI.labelBg(label)} ${ANSI.valueFg(value)}${origin(topic)}`;
-  if (event.kind === "sent") {
-    lines.push(chip("From", event.from, event.fromTopic));
-    lines.push(chip("To", event.to, event.toTopic));
-    lines.push(chip("When", when, null));
-    lines.push("");
-    lines.push(event.body);
-  } else {
-    const clipped = event.body.length > 60 ? event.body.slice(0, 60) + "..." : event.body;
-    lines.push(chip("From", event.reader, event.toTopic));
-    lines.push(`${CARD_INDENT}${ANSI.dim("read")} ${ANSI.valueFg(event.from)}${origin(event.fromTopic)}`);
-    lines.push(chip("When", when, null));
-    lines.push("");
-    lines.push(clipped);
-  }
-  return lines.join("\n");
+export function formatChatTailJsonl(event: ChatTailEvent): string {
+  return JSON.stringify(event);
 }
 
-export const CHAT_TAIL_SEPARATOR = "_".repeat(60);
-
 // ---------------------------------------------------------------------------
 // Poller
 // ---------------------------------------------------------------------------
@@ -1025,9 +1252,10 @@ export interface ChatPollerStore {
 
 export interface ChatPollerOptions {
   store: ChatPollerStore;
-  /** Session IDs this process has seen events for. Only sessions hosted by
-   *  this process can be delivered to - the recipient's host is the single
-   *  deliverer, by design. */
+  /** Session IDs this process hosts: those it has seen events for plus the
+   *  `-s` startup session. Only sessions hosted by this process can be
+   *  delivered to - the recipient's host is the single deliverer, by
+   *  design. */
   hostedSessions: () => string[];
   /** Delivers a wake prompt for a recipient. Injected so tests never spawn. */
   deliver: (sessionID: string, senders: string[], count: number) => Promise<void>;
@@ -1203,8 +1431,9 @@ export class ChatPoller {
   }
 }
 
-/** True when a session row's last_seen is older than the staleness
- *  threshold. Used by chat_list to mark ghosts. */
-export function isStale(row: ChatSessionRow, staleMinutes: number, now = Date.now()): boolean {
-  return now - Date.parse(row.last_seen) > staleMinutes * 60_000;
+/** True when a session row has missed two heartbeats (see CHAT_STALE_MS).
+ *  The one staleness rule: chat_list, chat_send's stale note, and the
+ *  broadcast skip all go through here so they can never disagree. */
+export function isStale(row: ChatSessionRow, now = Date.now()): boolean {
+  return now - Date.parse(row.last_seen) > CHAT_STALE_MS;
 }