@gotcos/glasses-server 6.34.0 → 6.36.0

package/server/lib/session-transcript-watcher.ts

@@ -0,0 +1,364 @@
+// Phase 2: row-level push for a session COS did not spawn.
+//
+// There is no pipe. COS never started that desktop process, so the ONLY observable is
+// the transcript file it appends to. This tails that file and emits each new JSONL
+// record through the same grammar and the same envelope Phase 1 uses.
+//
+// WHAT THIS CAN AND CANNOT DO, stated plainly because the UI must not pretend
+// otherwise: Claude Code writes a COMPLETE record per message, so a long reply appears
+// ALL AT ONCE when it finishes. This is row-level push, not token streaming, and the
+// asymmetry with a Continue turn cannot be engineered away from a file.
+//
+// ---------------------------------------------------------------------------
+// WHY A STAT POLL AND NOT `fs.watch`
+// ---------------------------------------------------------------------------
+// `fs.watch` was considered and rejected. On macOS it coalesces rapid writes, so a
+// burst of records can arrive as one event or, during a rename or an atomic replace,
+// as none: the kFSEvents backend keeps watching the old inode and simply stops firing,
+// with no error and no callback. A watcher that goes silent is indistinguishable from
+// a session that went quiet, which is the exact failure class this repo has been
+// burned by repeatedly -- absence of a signal read as absence of activity.
+//
+// A `stat` every second is one syscall per second per OPEN session detail view. It
+// cannot miss a write, because it does not observe writes at all: it observes SIZE,
+// and size is cumulative. If three records land between two ticks, the next read
+// returns all three. Slower to first byte by up to a second, and incapable of the
+// silent-death mode. That trade is correct here.
+//
+// ---------------------------------------------------------------------------
+// OFFSET, AND THE 587 KB RECORD
+// ---------------------------------------------------------------------------
+// Reading forward from a byte offset, never a tail window. The tail window in
+// `agent-session-store.ts` exists for a one-shot digest of a huge file and it has a
+// measured hazard: a single JSONL record can exceed 768 KiB. This Mac's own largest
+// transcript holds four such records, the biggest 1,239,046 bytes. A tail read that
+// opens mid-record drops it whole and silently.
+//
+// Forward reading has no window, so record size is simply not a variable: a record of
+// any length up to `MAX_READ_BYTES` is delivered intact the moment it is complete. The
+// only bound is per TICK, not per record, so a burst larger than the cap drains across
+// several ticks instead of allocating it all at once. Re-reading the 81 MB file per
+// change, the thing the plan forbids, never happens: the cursor only ever reads the
+// bytes appended since the last tick.
+//
+// The pathological case is explicit rather than silent, and it does NOT try to be clever.
+// A record LARGER than `MAX_READ_BYTES` cannot be assembled without unbounded memory, so
+// the tailer emits a terminal `done` and DEGRADES TO THE POLL, which has no such bound.
+// `MAX_READ_BYTES` is 4 MiB, 3.2x the largest record measured on this machine, so this is
+// a safety valve rather than an expected path.
+//
+// Skipping the record instead was tried first and was wrong twice over. It wedged: after
+// discarding the oversized bytes the leftover in the same chunk still looked capped, so
+// the GOOD record behind it was skipped too, on every tick, forever -- zero events, not
+// even a status. And even working it would have silently dropped a reply the user was
+// waiting to read. Arriving 5 seconds later through the poll beats never arriving.
+
+import { constants as fsConstants } from 'node:fs'
+import { open, stat } from 'node:fs/promises'
+import { draftsFromLine, type SessionStreamProvider } from './session-stream-events.js'
+import { isAttachedTurnActive, publishSessionStream, type PublishedSessionEvent } from './session-stream-bus.js'
+import type { SessionStreamDraft } from './session-stream-events.js'
+
+/** Bytes read per tick. See the header for why this is a per-tick and not a per-record bound. */
+export const MAX_READ_BYTES = 4 * 1024 * 1024
+
+/** Stat cadence. Deliberately unremarkable; see the header. */
+export const POLL_INTERVAL_MS = 1_000
+
+/**
+ * Quiet before a tailing session is called idle.
+ *
+ * Longer than a poll interval by a wide margin, because a model thinking between tool
+ * calls writes nothing for tens of seconds and is not idle. This flag exists so a
+ * client can tell a live-but-quiet stream from a finished one; it must not flicker.
+ */
+export const IDLE_AFTER_MS = 45_000
+
+/** Cursor position in the file. Forward-only; see the header. */
+export interface TranscriptCursor {
+  offset: number
+}
+
+export interface ConsumeResult {
+  cursor: TranscriptCursor
+  lines: string[]
+  /**
+   * One record exceeded a whole tick's budget, so this stream cannot carry it.
+   * The caller must stop and let the poll take over. See the header.
+   */
+  tooLarge?: boolean
+}
+
+/**
+ * Advance the cursor over one freshly read chunk.
+ *
+ * PURE. No fs, no clock. Everything subtle about the offset strategy lives here so it
+ * can be tested by execution rather than by reading it.
+ *
+ * `capped` means the read filled `MAX_READ_BYTES` and more bytes are pending, which is
+ * the ONLY condition under which "no newline in this chunk" proves an oversized record
+ * rather than a record still being written.
+ */
+export function consumeTranscriptChunk(
+  cursor: TranscriptCursor,
+  chunk: Buffer,
+  capped: boolean,
+): ConsumeResult {
+  const last = chunk.lastIndexOf(0x0a)
+
+  if (last < 0) {
+    // Nothing completed in this chunk. Leave the cursor where it is so the partial
+    // record is re-read next tick; that is what makes a 587 KB record arrive whole.
+    // If the read was FULL, though, re-reading it will never terminate: hand it off.
+    return capped
+      ? { cursor, lines: [], tooLarge: true }
+      : { cursor, lines: [] }
+  }
+
+  const lines = chunk.subarray(0, last).toString('utf8').split('\n').filter(line => line.length > 0)
+  return { cursor: { offset: cursor.offset + last + 1 }, lines }
+}
+
+export interface TranscriptTailerOptions {
+  key: string
+  path: string
+  provider: SessionStreamProvider
+  /** Start position. Production passes the file's current size: no history replay. */
+  offset: number
+  now?: () => number
+  publish?: (key: string, draft: SessionStreamDraft) => void
+  /** True while a COS-spawned turn is the live writer. Suppresses emission, not advance. */
+  suppressed?: (key: string) => boolean
+  maxReadBytes?: number
+  idleAfterMs?: number
+}
+
+export interface TranscriptTailer {
+  /** One stat-and-read pass. Resolves; never rejects. */
+  tick(): Promise<void>
+  cursor(): TranscriptCursor
+  /** Last state this tailer published, or null if it has published none. */
+  state(): 'working' | 'idle' | 'done' | null
+  /** True once this tailer has handed off to the poll. Terminal; never clears. */
+  degraded(): boolean
+}
+
+/**
+ * Read a byte range with the flags this repo requires everywhere.
+ *
+ * `O_NONBLOCK` because an `open` on a FIFO with no writer never returns, and a planted
+ * path has wedged this entire server three times. `O_NOFOLLOW` because a symlinked
+ * `<id>.jsonl` could point at any file on disk and be streamed as session records.
+ * `fsPromises.open` also keeps the syscall off the event loop thread, unlike the
+ * `openSync` sites those incidents involved.
+ */
+async function readRangeAt(path: string, offset: number, length: number): Promise<Buffer | null> {
+  const noFollow = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0
+  const nonBlock = typeof fsConstants.O_NONBLOCK === 'number' ? fsConstants.O_NONBLOCK : 0
+  let handle: Awaited<ReturnType<typeof open>> | null = null
+  try {
+    handle = await open(path, fsConstants.O_RDONLY | noFollow | nonBlock)
+    const buffer = Buffer.allocUnsafe(length)
+    const { bytesRead } = await handle.read(buffer, 0, length, offset)
+    return buffer.subarray(0, bytesRead)
+  } catch {
+    // Deleted, replaced by a symlink, permissions changed mid-session. The next tick
+    // tries again; a read failure is never reported as session inactivity.
+    return null
+  } finally {
+    // Opened per tick rather than held: a transcript replaced by a new inode would
+    // otherwise be tailed forever at the wrong file, with no error.
+    await handle?.close().catch(() => {})
+  }
+}
+
+export function createTranscriptTailer(options: TranscriptTailerOptions): TranscriptTailer {
+  const now = options.now ?? (() => Date.now())
+  const publish = options.publish ?? ((key, draft) => { publishSessionStream(key, draft) })
+  const suppressed = options.suppressed ?? isAttachedTurnActive
+  const maxRead = options.maxReadBytes ?? MAX_READ_BYTES
+  const idleAfter = options.idleAfterMs ?? IDLE_AFTER_MS
+
+  let cursor: TranscriptCursor = { offset: Math.max(0, options.offset) }
+  let state: 'working' | 'idle' | 'done' | null = null
+  let lastActivity = now()
+  let degraded = false
+
+  const emit = (draft: SessionStreamDraft) => {
+    try {
+      publish(options.key, draft)
+    } catch {
+      /* a failed publish must not stop the cursor from advancing */
+    }
+  }
+
+  return {
+    cursor: () => ({ ...cursor }),
+    state: () => state,
+    degraded: () => degraded,
+    async tick(): Promise<void> {
+      // Terminal. Once the poll owns this session, continuing to stat and re-read a 4 MiB
+      // range every second would burn syscalls to produce nothing, forever.
+      if (degraded) return
+      try {
+        let size: number
+        try {
+          const st = await stat(options.path)
+          if (!st.isFile()) return
+          size = st.size
+        } catch {
+          return
+        }
+
+        if (size < cursor.offset) {
+          // Truncated or replaced. Re-reading an 81 MB file from zero is the one thing
+          // this design exists to avoid, so we rejoin at the new end and let the poll
+          // fallback carry whatever the rotation took with it.
+          cursor = { offset: size }
+          return
+        }
+
+        if (size > cursor.offset) {
+          const pending = size - cursor.offset
+          const length = Math.min(pending, maxRead)
+          const chunk = await readRangeAt(options.path, cursor.offset, length)
+          if (chunk !== null && chunk.length > 0) {
+            const result = consumeTranscriptChunk(cursor, chunk, chunk.length >= maxRead)
+            cursor = result.cursor
+            if (result.tooLarge) {
+              // HAND OFF, do not skip. `done` is the same terminal status a finished turn
+              // sends, so the client already knows to close the stream and resume its
+              // 5s/15s/60s poll -- no new client vocabulary, no frozen screen.
+              //
+              // Self-healing: the watcher is torn down when the last subscriber releases,
+              // and a fresh one starts at the file's CURRENT size, which is already past
+              // this record. A reconnect therefore streams normally again.
+              degraded = true
+              state = 'done'
+              emit({ kind: 'status', state: 'done' })
+              return
+            }
+            if (result.lines.length > 0) {
+              lastActivity = now()
+              // SUPPRESSED, NOT SKIPPED. A COS-spawned turn is already streaming these
+              // same records from stdout; emitting them again would double every line.
+              // The cursor still advanced above, so when the turn ends the tailer is
+              // already past them and replays nothing.
+              if (!suppressed(options.key)) {
+                if (state !== 'working') {
+                  state = 'working'
+                  emit({ kind: 'status', state: 'working' })
+                }
+                for (const line of result.lines) {
+                  for (const draft of draftsFromLine(options.provider, line)) emit(draft)
+                }
+              }
+            }
+          }
+        }
+
+        if (state === 'working' && now() - lastActivity >= idleAfter) {
+          state = 'idle'
+          emit({ kind: 'status', state: 'idle' })
+        }
+      } catch {
+        /* a tick that throws is a tick that produced nothing; the next one retries */
+      }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ref-counted lifetime
+// ---------------------------------------------------------------------------
+
+interface WatcherEntry {
+  refs: number
+  timer: ReturnType<typeof setInterval>
+  ticking: boolean
+  tailer: TranscriptTailer
+}
+
+const watchers = new Map<string, WatcherEntry>()
+
+export interface AcquireWatcherOptions {
+  key: string
+  path: string
+  provider: SessionStreamProvider
+  /** Where to start. Production passes the file's current size. */
+  offset: number
+  intervalMs?: number
+}
+
+/**
+ * Start tailing, or join a tail already running for this session.
+ *
+ * ONE WATCHER PER SESSION, ref-counted, torn down on the LAST release. Two glasses on
+ * the same session must not mean two pollers on an 81 MB file, and a release that
+ * fires twice must not tear down a tail another subscriber still holds.
+ */
+export function acquireTranscriptWatcher(options: AcquireWatcherOptions): () => void {
+  const existing = watchers.get(options.key)
+  if (existing) {
+    existing.refs++
+    return releaseOnce(options.key)
+  }
+
+  const tailer = createTranscriptTailer(options)
+  const timer = setInterval(() => {
+    const entry = watchers.get(options.key)
+    if (!entry) return
+    // A tick still in flight when the next one fires would read the same range twice
+    // and emit every record twice. Skipping is correct: size is cumulative, so the
+    // next tick sees everything the skipped one would have.
+    if (entry.ticking) return
+    entry.ticking = true
+    void tailer.tick().finally(() => { entry.ticking = false })
+  }, options.intervalMs ?? POLL_INTERVAL_MS)
+  // Never hold the process open. A tail is a view, not work.
+  if (typeof (timer as any).unref === 'function') (timer as any).unref()
+
+  watchers.set(options.key, { refs: 1, timer, ticking: false, tailer })
+  return releaseOnce(options.key)
+}
+
+function releaseOnce(key: string): () => void {
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    const entry = watchers.get(key)
+    if (!entry) return
+    entry.refs--
+    if (entry.refs > 0) return
+    clearInterval(entry.timer)
+    watchers.delete(key)
+  }
+}
+
+export function watchedTranscriptCount(): number {
+  return watchers.size
+}
+
+/**
+ * Has this session's tail handed off to the poll?
+ *
+ * The SSE route asks this so it can END the response instead of holding a socket that
+ * heartbeats forever and will never carry another record. Without that, the client's
+ * liveness check keeps reading `live` off the heartbeats and the footer keeps saying
+ * `stream` while the poll is quietly doing all the work -- which is precisely the
+ * "absence of a signal read as health" failure this repo keeps paying for.
+ *
+ * False for a session with no watcher, which includes every COS-spawned turn: those
+ * stream from a pipe and never degrade this way.
+ */
+export function transcriptWatcherDegraded(key: string): boolean {
+  return watchers.get(key)?.tailer.degraded() ?? false
+}
+
+export function __resetTranscriptWatchersForTests(): void {
+  for (const entry of watchers.values()) clearInterval(entry.timer)
+  watchers.clear()
+}
+
+export type { PublishedSessionEvent }

package/server/routes/agent-session-stream.ts

@@ -0,0 +1,250 @@
+// GET /api/agent-sessions/:provider/:sessionId/stream
+//
+// Server-sent events for ONE agent session. Each `data:` line is one JSON object:
+//
+//   {"seq":1,"at":1786890000000,"kind":"tool","verb":"read","target":"x.ts","detail":""}
+//   {"seq":2,"at":1786890001000,"kind":"prose","text":"..."}
+//   {"seq":3,"at":1786890002000,"kind":"status","state":"working"}
+//   {"seq":4,"at":1786890003000,"kind":"heartbeat"}
+//
+// `seq` is monotonic PER CONNECTION from 1, so a client detects loss from a gap. There
+// are no named SSE events and no comment keepalives: one shape, so a client needs one
+// handler and can never miss a keepalive it was not parsing.
+//
+// ---------------------------------------------------------------------------
+// A DEAD STREAM MUST DEGRADE TO THE POLL, NEVER TO A FROZEN SCREEN
+// ---------------------------------------------------------------------------
+// Everything here is arranged so failure is DETECTABLE rather than silent:
+//
+//   - A `status` is written before anything else, so the live view is never empty.
+//   - A `heartbeat` every 15s, inside the contract's 20s ceiling. Quiet past that is
+//     a dead stream, and the client resumes its 5s/15s/60s tiers.
+//   - Every refusal happens BEFORE the SSE headers, as ordinary JSON with a status
+//     code, so the client sees a failed request rather than an open socket that never
+//     speaks.
+//   - A write that throws tears the connection down rather than being swallowed.
+//
+// This route NEVER writes the lens. It hands events to the client, which owns every
+// paint. A second writer to the renderer is how `enqueue` deadlocked and blanked the
+// HUD, and no server route is going to reintroduce that.
+//
+// ---------------------------------------------------------------------------
+// THE FLAG DECISION: this is NOT behind `COS_THREAD_ATTACH_ENABLED`
+// ---------------------------------------------------------------------------
+// That flag gates WRITING into somebody's live conversation, and with it off the two
+// write routes are not registered at all. This route writes nothing. It streams
+// records from a transcript that `GET /api/agent-sessions/:provider/:sessionId`
+// already returns in full, to the same authenticated caller, through the same token.
+// Reusing the write flag would mean a desktop session -- Case B, which involves no
+// attaching whatsoever -- could not stream unless the user had first enabled the
+// ability to write into their threads. That is a worse posture, not a safer one: it
+// pushes people toward turning the write flag on to get a read feature.
+//
+// Phase 1 remains gated exactly as before, and not by anything here: a Continue turn
+// can only exist when `COS_THREAD_ATTACH_ENABLED=1`, so with the flag off this route
+// carries desktop rows and nothing else.
+//
+// `COS_SESSION_STREAM_ENABLED=0` is a separate kill switch for the streaming surface
+// alone. Absent means ON. That is safe here specifically because nothing writes this
+// key -- no COS Control toggle, no installer, no plist generator -- so key-absence can
+// never be mistaken for a user's explicit opt-out. Off answers 503 and the client
+// polls, which is the same code path as a server too old to have this route at all.
+
+import { Router, type Response } from 'express'
+import { stat } from 'node:fs/promises'
+import {
+  agentSessionRoots,
+  findAgentSessionFile,
+  isSafeSessionId,
+  type AgentProvider,
+} from '../lib/agent-session-store.js'
+import { ACTIVE_RECENTLY_WINDOW_MS } from '../lib/thread-occupancy.js'
+import {
+  isAttachedTurnActive,
+  sessionStreamKey,
+  subscribeSessionStream,
+  type PublishedSessionEvent,
+} from '../lib/session-stream-bus.js'
+import { acquireTranscriptWatcher, transcriptWatcherDegraded } from '../lib/session-transcript-watcher.js'
+import type { SessionStreamState } from '../lib/session-stream-events.js'
+
+export const agentSessionStreamRouter = Router()
+
+/** Inside the contract's 20s ceiling with room for one lost write. */
+export const HEARTBEAT_INTERVAL_MS = 15_000
+
+/** Events held between subscribing and the headers going out. Bounded; see below. */
+export const PREHEADER_BUFFER_MAX = 200
+
+export function sessionStreamEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_SESSION_STREAM_ENABLED !== '0'
+}
+
+function asProvider(value: string): AgentProvider | null {
+  if (value === 'claude' || value === 'codex' || value === 'cursor') return value
+  return null
+}
+
+/**
+ * The state to open with.
+ *
+ * `working` when a COS turn is writing right now, or when the transcript was touched
+ * inside the same 30s window the session list already uses to call a thread active.
+ * Otherwise `idle`. Never `done`: this route cannot observe the end of a turn it did
+ * not start, and claiming one would be an invention.
+ */
+export async function openingState(
+  key: string,
+  path: string | null,
+  nowMs: number,
+): Promise<SessionStreamState> {
+  if (isAttachedTurnActive(key)) return 'working'
+  if (path === null) return 'idle'
+  try {
+    const st = await stat(path)
+    return nowMs - st.mtimeMs <= ACTIVE_RECENTLY_WINDOW_MS ? 'working' : 'idle'
+  } catch {
+    return 'idle'
+  }
+}
+
+agentSessionStreamRouter.get('/agent-sessions/:provider/:sessionId/stream', async (req, res) => {
+  res.set('Cache-Control', 'private, no-store')
+
+  const provider = asProvider(String(req.params.provider ?? '').toLowerCase())
+  const sessionId = String(req.params.sessionId ?? '')
+  if (!provider) {
+    res.status(400).json({ error: 'provider must be claude, codex, or cursor', reason: 'bad_provider' })
+    return
+  }
+  if (!isSafeSessionId(sessionId)) {
+    res.status(400).json({ error: 'invalid session id', reason: 'bad_session_id' })
+    return
+  }
+  if (!sessionStreamEnabled()) {
+    res.status(503).json({ error: 'session streaming is disabled', reason: 'stream_disabled' })
+    return
+  }
+
+  const key = sessionStreamKey(provider, sessionId)
+
+  // Resolved BEFORE the headers so a missing transcript is a 404 the client can act on
+  // rather than an open socket that turns out to carry nothing. Null is not fatal for
+  // Phase 1: a Continue turn streams from stdout whether or not the file is locatable.
+  let path: string | null = null
+  try {
+    path = await findAgentSessionFile(provider, sessionId, agentSessionRoots())
+  } catch {
+    path = null
+  }
+  if (path === null && !isAttachedTurnActive(key)) {
+    res.status(404).json({ error: 'Session not found', reason: 'session_not_found' })
+    return
+  }
+
+  // Capacity is checked before the headers for the same reason. A refused subscribe is
+  // a 503 the client falls back from, not a stream that silently receives nothing.
+  //
+  // Subscribing happens HERE, two awaits before the headers, so a turn that starts in
+  // that window is not lost. Until the headers go out the events are buffered, bounded
+  // by `PREHEADER_BUFFER_MAX` -- an unbounded buffer in front of a socket that may
+  // never open is a leak, and the poll fallback covers anything dropped.
+  const pending: PublishedSessionEvent[] = []
+  let deliver = (event: PublishedSessionEvent): void => {
+    pending.push(event)
+    if (pending.length > PREHEADER_BUFFER_MAX) pending.shift()
+  }
+  const unsubscribe = subscribeSessionStream(key, event => { deliver(event) })
+  if (unsubscribe === null) {
+    res.status(503).json({ error: 'too many live streams', reason: 'stream_capacity' })
+    return
+  }
+
+  // Where the tail joins: the file's CURRENT size. A subscriber wants what happens
+  // next, and the history it already has came from the polled detail payload. Starting
+  // at zero would replay an 81 MB transcript into a pair of glasses.
+  let startOffset = 0
+  try {
+    if (path !== null) startOffset = (await stat(path)).size
+  } catch {
+    startOffset = 0
+  }
+
+  const state = await openingState(key, path, Date.now())
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  })
+  res.flushHeaders()
+  res.write('retry: 3000\n\n')
+
+  // Declared before `teardown` reads them. Both are assigned below; a `const` here
+  // would put them in the temporal dead zone for a teardown triggered by the very
+  // first write, and that ReferenceError would leak the subscription it exists to
+  // release.
+  let releaseWatcher: (() => void) | null = null
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+
+  let seq = 0
+  let closed = false
+
+  const teardown = (): void => {
+    if (closed) return
+    closed = true
+    if (heartbeat !== null) clearInterval(heartbeat)
+    unsubscribe()
+    releaseWatcher?.()
+    try { res.end() } catch { /* already gone */ }
+  }
+
+  const write = (event: PublishedSessionEvent): void => {
+    if (closed) return
+    try {
+      res.write(`data: ${JSON.stringify({ seq: ++seq, ...event })}\n\n`)
+    } catch {
+      // A failed write means the socket is gone. Close rather than swallow, so the
+      // watcher and the subscription are released instead of leaking behind a dead
+      // client that will never send `close`.
+      teardown()
+    }
+  }
+
+  heartbeat = setInterval(() => {
+    // The tail gave up on a record too large to stream (see session-transcript-watcher).
+    // END the response rather than heartbeat over a dead tail: the client's fallback to
+    // its own poll is already written and tested, and a socket that stays "live" while
+    // producing nothing is worse than no socket at all.
+    if (transcriptWatcherDegraded(key)) {
+      teardown()
+      return
+    }
+    write({ kind: 'heartbeat', at: Date.now() })
+  }, HEARTBEAT_INTERVAL_MS)
+  if (typeof (heartbeat as any).unref === 'function') (heartbeat as any).unref()
+
+  // The contract's "emit a status immediately" -- written before any queued event so
+  // the client's first frame is always a state, never a bare tool line.
+  write({ kind: 'status', state, at: Date.now() })
+  // Then anything published while the headers were being prepared, in order, before
+  // the listener starts writing straight through. All three steps are synchronous, so
+  // no event can interleave and arrive out of order.
+  for (const event of pending.splice(0)) write(event)
+  deliver = write
+
+  releaseWatcher = path === null
+    ? null
+    : acquireTranscriptWatcher({ key, path, provider, offset: startOffset })
+  // The socket may already have died during the writes above. Acquiring a watcher for
+  // a closed connection would leave it polling with nobody listening.
+  if (closed) {
+    releaseWatcher?.()
+    releaseWatcher = null
+    return
+  }
+
+  req.on('close', teardown)
+  res.on('error', teardown)
+})

package/server/routes/agent-sessions.ts

@@ -366,6 +366,12 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
       // summary — Miles: "it should be in the body not the title, the row should
       // be no more than the 180 characters."
       discussion_digest: parsed.discussion_digest || '',
+      // The newest assistant reply, whole. ADDITIVE: the digest above still carries
+      // its own 160-char `Latest:` line, so a client that never learns this field
+      // renders exactly what it rendered before. Measured at 4000 chars — see
+      // LATEST_REPLY_MAX. Before this existed the detail payload had NO full-text
+      // field at all, and an 1821-char reply left the Mac as 160 characters.
+      latest_reply: parsed.latest_reply || '',
       truncated: parsed.truncated,
       project: parsed.project,
       created: modified,