@gotcos/glasses-server 6.48.0 → 6.48.2

package/server/lib/session-hooks-runtime.ts

@@ -7,8 +7,11 @@
 // Update Server (main.swift `providerEnvironmentKeys`).
 
 import { execFileSync } from 'node:child_process'
-import { mkdirSync } from 'node:fs'
+import { mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 import { cosSpawnedPids } from './agent-session-ownership-store.js'
+import { REGISTRY_FILENAME, claudeSessionsDir } from './claude-session-registry.js'
+import { MAX_REGISTRY_FILES } from './thread-occupancy.js'
 import { dataPath } from './data-dir.js'
 import { SessionHookLedger } from './session-hook-ledger.js'
 import { startSpoolIngester, type SpoolIngester, type SpoolStats } from './session-hook-spool.js'
@@ -78,6 +81,87 @@ export function isCosSpawnedPid(pid: number | null, nowMs = Date.now()): boolean
 
 export const sessionSignalStore = new SessionSignalStore({ isCosSpawnedPid })
 
+// 6.48.1: which kind of process a session is, read off its registry record while it is alive.
+// `claude -p` registers as `entrypoint: sdk-cli`; a Desktop tab as `claude-desktop`; a terminal
+// as `cli`. The record may land a beat after the SessionStart hook, so the read is retried on
+// the session's next few events (a synchronous, bounded registry scan each) and then given
+// up. Once known it rides the LEDGER ROW (QA, 2026-09-15): a replay after a restart restores
+// it, so a tab that ended inside the replay window is not listed as a print run for want of
+// a registry record that the reaper has since removed.
+const ENTRYPOINT_ATTEMPTS = 6
+const entrypointAttempts = new Map<string, number>()
+
+/** The entrypoint to write on this event's ledger row: the store's, else one registry read while attempts remain. */
+function entrypointFor(sessionId: string, child: boolean): string | null {
+  const known = sessionSignalStore.get(sessionId)?.entrypoint ?? null
+  if (known || child) return known
+  const tried = entrypointAttempts.get(sessionId) ?? 0
+  if (tried >= ENTRYPOINT_ATTEMPTS) return null
+  entrypointAttempts.set(sessionId, tried + 1)
+  if (entrypointAttempts.size > 512) entrypointAttempts.clear()
+  return registryEntrypointSync(sessionId)
+}
+
+/** One synchronous pass over `~/.claude/sessions/<pid>.json`; null when no record names the session. */
+export function registryEntrypointSync(sessionId: string, dir = claudeSessionsDir()): string | null {
+  return registryRecordSync(sessionId, dir)?.entrypoint ?? null
+}
+
+export interface RegistryRecordFacts {
+  pid: number | null
+  entrypoint: string | null
+  status: string | null
+  statusUpdatedAt: number | null
+}
+
+/**
+ * The registry record naming a session, read synchronously and bounded; null when none
+ * does. A COS Continue child (`claude -p --resume <id>`) registers under the SAME session
+ * id as the tab it resumes, so when two records name the session the one whose pid COS
+ * did not spawn is the tab's and wins; the child's is used only when it is alone.
+ */
+export function registryRecordSync(sessionId: string, dir = claudeSessionsDir()): RegistryRecordFacts | null {
+  let names: string[]
+  try { names = readdirSync(dir).filter(n => REGISTRY_FILENAME.test(n)).slice(0, MAX_REGISTRY_FILES) } catch { return null }
+  const wanted = sessionId.toLowerCase()
+  let childRecord: RegistryRecordFacts | null = null
+  for (const name of names) {
+    try {
+      const raw = JSON.parse(readFileSync(join(dir, name), 'utf-8')) as Record<string, unknown>
+      if (typeof raw.sessionId !== 'string' || raw.sessionId.toLowerCase() !== wanted) continue
+      const record: RegistryRecordFacts = {
+        pid: typeof raw.pid === 'number' ? raw.pid : null,
+        entrypoint: typeof raw.entrypoint === 'string' && raw.entrypoint ? raw.entrypoint : null,
+        status: typeof raw.status === 'string' ? raw.status : null,
+        statusUpdatedAt: typeof raw.statusUpdatedAt === 'number' ? raw.statusUpdatedAt : null,
+      }
+      if (isCosSpawnedPid(record.pid)) { childRecord ??= record; continue }
+      return record
+    } catch { /* a torn write; the next read retries */ }
+  }
+  return childRecord
+}
+
+/**
+ * THE ENGINE'S OWN END OF TURN (6.48.1, QA round). Claude Code does not end a turn at
+ * the `end_turn` row or at the Stop hook: it ends it when every Stop hook has RETURNED,
+ * and only then writes `stop_hook_summary`, dequeues anything typed meanwhile, and flips
+ * the registry to `idle`. On the release Mac the COS repo's own Stop hooks run 12-38 s
+ * (`transcript_summary_hook.py`), so "Stop + 2 s" was 13-38 s early: a prompt typed at
+ * the desk in that window is QUEUED and dequeues after the hooks, and a follow-up
+ * delivered at Stop + 2 s would have been a second writer. The registry's `idle` with
+ * `statusUpdatedAt` at or after the Stop is the only signal that says the hooks are done
+ * (measured: it flips 4-39 ms after the summary row).
+ *
+ * True only when a live record names the session AND says idle AND moved at or after
+ * `stopAt`. No record (a print run that already exited) is answered by the caller.
+ */
+export function registryIdleAfterStop(sessionId: string, stopAt: number, dir = claudeSessionsDir()): boolean | null {
+  const record = registryRecordSync(sessionId, dir)
+  if (!record) return null
+  return record.status === 'idle' && typeof record.statusUpdatedAt === 'number' && record.statusUpdatedAt >= stopAt
+}
+
 let ledger: SessionHookLedger | null = null
 let ingester: SpoolIngester | null = null
 let replayed: { rows: number; applied: number } | null = null
@@ -96,14 +180,22 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
   ledger = new SessionHookLedger(dataPath('session-hook-events.jsonl'))
   const enabled = sessionHooksEnabled()
   const since = Date.now() - LEDGER_REPLAY_WINDOW_MS
-  const replay = ledger.replay(since, (env, _key, child) => { if (enabled) sessionSignalStore.apply(env, child) })
+  const replay = ledger.replay(since, (env, _key, child, entrypoint) => {
+    if (!enabled) return
+    sessionSignalStore.apply(env, child)
+    if (entrypoint) sessionSignalStore.setEntrypoint(env.sessionId, entrypoint)
+  })
   replayed = { rows: replay.rows, applied: replay.applied }
   ingester = startSpoolIngester({
     dir,
     ledger,
     seenKeys: replay.keys,
     isChild: env => isCosSpawnedPid(env.ppid),
-    apply: enabled ? (env, child) => { sessionSignalStore.apply(env, child) } : undefined,
+    entrypointOf: enabled ? (env, child) => entrypointFor(env.sessionId, child) : undefined,
+    apply: enabled ? (env, child, entrypoint) => {
+      sessionSignalStore.apply(env, child)
+      if (entrypoint) sessionSignalStore.setEntrypoint(env.sessionId, entrypoint)
+    } : undefined,
   })
   // Runtime files the script reads. The port can change per install; the token never does.
   // The script is copied only when MISSING here: a boot must never downgrade what a newer
@@ -125,8 +217,17 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
   }
 }
 
+/** 6.48.1: the drain kick's counters, registered by the composition root when thread attach is on. */
+type DrainKickStats = { passes: number; kicks: number; folded: number; inFlight: boolean; waiting: number }
+let drainKickStats: (() => DrainKickStats) | null = null
+export function registerDrainKickStats(read: () => DrainKickStats): void {
+  drainKickStats = read
+}
+
 export interface SessionHooksHealth {
   enabled: boolean
+  /** The Stop-driven drain (6.48.1): null when thread attach is off. */
+  drain: DrainKickStats | null
   /** The install state word; `installed` below is its boolean. */
   state: HookStatus['state']
   installed: boolean
@@ -169,6 +270,7 @@ export function sessionHooksHealthFields(): { sessionHooks: SessionHooksHealth }
   return {
     sessionHooks: {
       enabled: sessionHooksEnabled(),
+      drain: drainKickStats ? drainKickStats() : null,
       state: status.state,
       installed: status.installed,
       scriptSha: status.scriptSha,
@@ -197,11 +299,11 @@ export function signalFor(sessionId: string): SessionSignal | undefined {
  * Derive with the two-scan memory kept here, keyed by full id when known. Rows the
  * caller has no facts for at all get nothing, so an older payload stays byte-identical.
  */
-export function deriveForRow(input: { sessionId: string; registry?: RegistryFacts; transcript?: TranscriptFacts; now?: number }): DerivedSessionState | undefined {
+export function deriveForRow(input: { sessionId: string; registry?: RegistryFacts; transcript?: TranscriptFacts; now?: number; remember?: boolean; attachedTurn?: boolean }): DerivedSessionState | undefined {
   // Off means off: with the feature disabled every row is byte-identical to 6.47.0.
   if (!sessionHooksEnabled()) return undefined
   const signal = signalFor(input.sessionId)
-  if (!signal && !input.registry && !input.transcript) return undefined
+  if (!signal && !input.registry && !input.transcript && !input.attachedTurn) return undefined
   const now = input.now ?? Date.now()
   const key = signal?.sessionId ?? input.sessionId.toLowerCase()
   const prev = deadById.get(key)
@@ -212,7 +314,12 @@ export function deriveForRow(input: { sessionId: string; registry?: RegistryFact
     now,
     prevDeadScans: prev?.scans ?? 0,
     prevDeadSince: prev?.since ?? null,
+    attachedTurn: input.attachedTurn === true,
   })
+  // A reader with no registry facts (the live feed derives from the signal alone) must
+  // not touch the two-scan memory the row readers keep: a derive that saw no registry
+  // would reset a dead pid's count between two list requests.
+  if (input.remember === false || !input.registry) return derived
   if (deadById.size > 2_048) {
     for (const [k, v] of deadById) if (now - v.at > DEAD_MEMORY_MS) deadById.delete(k)
   }
@@ -225,5 +332,7 @@ export function __resetSessionHooksForTests(): void {
   deadById.clear()
   parentCache.clear()
   recentCosPids.clear()
+  entrypointAttempts.clear()
+  drainKickStats = null
   statusCache = null
 }

package/server/lib/session-signal-store.ts

@@ -60,7 +60,7 @@ export interface SessionSignal {
   turnOpen: boolean
   turnStartedAt: number | null
   promptId: string | null
-  /** Stamped by the newest Stop: `state_since` for an idle row. (6.48.1's B6 occupancy clause will compare it to the transcript.) */
+  /** Stamped by the newest Stop: `state_since` for an idle row, and the instant the B6 occupancy clause and the drain gate compare with the registry's `statusUpdatedAt` (6.48.1). */
   stopAt: number | null
   waiting: WaitingSignal | null
   failure: FailureSignal | null
@@ -74,6 +74,12 @@ export interface SessionSignal {
   compactions: number
   /** Events from a COS-spawned child on this id, kept out of the phase. */
   childEvents: number
+  /**
+   * The registry's `entrypoint` for this session (`claude-desktop`, `cli`, `sdk-cli`), read
+   * from `~/.claude/sessions` while the process is alive; null until seen. A `claude -p` job
+   * registers as `sdk-cli` (measured 2026-09-15), which is how `/runs` tells a job from a tab.
+   */
+  entrypoint: string | null
   /** Hooks have been seen for this session: the row may say `state_source: hook`. */
   hooksSeen: true
 }
@@ -120,12 +126,26 @@ function fresh(env: HookEnvelope): SessionSignal {
     keepWarm: false,
     compactions: 0,
     childEvents: 0,
+    entrypoint: null,
     hooksSeen: true,
   }
 }
 
 const str = (v: unknown): string | null => (typeof v === 'string' && v.length > 0 ? v : null)
 
+/**
+ * 6.48.1. A tool runs only inside a turn, so a MAIN-THREAD tool event (no `agent_id`) is
+ * evidence the turn is open even when its UserPromptSubmit was never seen: a tab adopted
+ * mid-turn when the hooks were installed (2.1.272 reloads hooks on the settings change,
+ * measured 2026-09-15 16:16) read `idle` from the hooks while the registry said busy. A
+ * sub-agent's tool events carry `agent_id` and say nothing about the main thread, and a
+ * tool event after SessionEnd is a child's, never the tab's.
+ */
+function turnOpenedByTool(prev: SessionSignal, p: Record<string, unknown>, at: number): Partial<SessionSignal> {
+  if (prev.turnOpen || prev.ended || str(p.agent_id)) return {}
+  return { turnOpen: true, turnStartedAt: prev.turnStartedAt ?? at }
+}
+
 /** Waiting kinds a PostToolUse of the same tool resolves without a fingerprint match. */
 const TOOL_WAITING: Record<string, WaitingKind> = { AskUserQuestion: 'question', ExitPlanMode: 'plan' }
 
@@ -193,7 +213,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
           waiting: { kind, detail: tool.target, toolName: tool.name, fingerprint: tool.fingerprint, since: env.ts, requestId: null },
         }
       }
-      return { ...next, lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
+      return { ...next, ...turnOpenedByTool(next, p, env.ts), lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
     }
     case 'PermissionRequest': {
       const tool = toolFacts(p)
@@ -216,7 +236,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
       const tool = toolFacts(p)
       const waiting = next.waiting && resolvesWaiting(next.waiting, env.event, tool.name, tool.fingerprint) ? null : next.waiting
       const ran = env.event !== 'PermissionDenied'
-      return { ...next, waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
+      return { ...next, ...turnOpenedByTool(next, p, env.ts), waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
     }
     case 'Notification': {
       const type = str(p.notification_type) ?? ''
@@ -259,7 +279,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
   }
 }
 
-export type SignalListener = (signal: SessionSignal, env: HookEnvelope) => void
+export type SignalListener = (signal: SessionSignal, env: HookEnvelope, child: boolean) => void
 
 /** Records older than this after a SessionEnd are dropped; Control keeps its own ledger. */
 export const SIGNAL_PRUNE_AFTER_END_MS = 6 * 60 * 60_000
@@ -278,14 +298,22 @@ export class SessionSignalStore {
   apply(env: HookEnvelope, child?: boolean): SessionSignal {
     const next = applyHookEvent(this.signals.get(env.sessionId), env, this.ctx, child)
     this.signals.set(env.sessionId, next)
+    const isChild = child ?? this.ctx.isCosSpawnedPid(env.ppid)
     for (const listener of this.listeners) {
-      try { listener(next, env) } catch (error) {
+      try { listener(next, env, isChild) } catch (error) {
         console.error(`[session-signals] listener failed: ${error instanceof Error ? error.message : error}`)
       }
     }
     return next
   }
 
+  /** The registry's entrypoint, once the runtime has read it; a no-op for an unknown session. */
+  setEntrypoint(sessionId: string, entrypoint: string | null): void {
+    const current = this.signals.get(sessionId)
+    if (!current || !entrypoint || current.entrypoint === entrypoint) return
+    this.signals.set(sessionId, { ...current, entrypoint })
+  }
+
   /** RESERVED FOR 6.48.2 (the permission broker); no caller in 6.48.0. Attach the broker's
    *  minted id so rows can carry `pending_permission_id`. */
   attachPermissionRequestId(sessionId: string, requestId: string | null): void {

package/server/lib/session-state-derive.ts

@@ -64,6 +64,14 @@ export interface DeriveInput {
   registry: RegistryFacts | undefined
   transcript: TranscriptFacts | undefined
   now: number
+  /**
+   * A COS-spawned turn (Continue, a queued follow-up, a job) is writing this session
+   * RIGHT NOW (`isAttachedTurnActive`). Its hook events are classified as a child's and
+   * kept out of the phase, so without this the tab's last state (idle after its Stop)
+   * would be reported while COS itself is generating (QA, 2026-09-15: the shipped lens
+   * drops the trail on `idle`). Running, source `transcript`: it is our own write.
+   */
+  attachedTurn?: boolean
   /** The previous derive's `deadScans`, so the two-scan rule survives between polls. */
   prevDeadScans?: number
   /** The previous derive's `deadSince`. */
@@ -100,6 +108,10 @@ export function deriveSessionState(input: DeriveInput): DerivedSessionState {
   const hooksSilent = !!signal && now - signal.lastEventAt > HOOK_SILENCE_MS
   const carry = { deadScans, deadSince }
 
+  if (input.attachedTurn === true) {
+    return { agent_state: 'running', state_source: 'transcript', state_since: iso(transcript?.lastActivityAt ?? signal?.lastEventAt ?? now), ...carry, ...replyOf(signal) }
+  }
+
   // A dead pid on two scans at least DEAD_GRACE_MS apart ends the row whatever the hooks
   // last said, unless a hook event is newer than the registry's last movement (a resumed
   // tab under a new pid).
@@ -195,6 +207,32 @@ function waitStillStands(since: number, registry: RegistryFacts | undefined, tra
   return true
 }
 
+/**
+ * The fields a `status` draft carries (6.48.1): the row fields minus the permission id
+ * (slice 4's, never on the stream) and with `last_reply` only on an idle state, where a
+ * feed renders "Idle, last reply: …". A typed projection, so a new row field cannot reach
+ * the wire by accident.
+ */
+export function derivedStatusFields(derived: DerivedSessionState): {
+  agent_state: AgentState
+  state_source: StateSource
+  state_since: string
+  waiting_kind?: WaitingKind
+  waiting_detail?: string
+  failure?: string
+  last_reply?: string
+} {
+  return {
+    agent_state: derived.agent_state,
+    state_source: derived.state_source,
+    state_since: derived.state_since,
+    ...(derived.waiting_kind ? { waiting_kind: derived.waiting_kind } : {}),
+    ...(derived.waiting_detail !== undefined ? { waiting_detail: derived.waiting_detail } : {}),
+    ...(derived.failure ? { failure: derived.failure } : {}),
+    ...(derived.agent_state === 'idle' && derived.last_reply ? { last_reply: derived.last_reply } : {}),
+  }
+}
+
 /** The additive row fields, ready to spread onto a list or detail entry. */
 export function derivedRowFields(derived: DerivedSessionState | undefined): Record<string, unknown> {
   if (!derived) return {}

package/server/lib/session-stream-bus.ts

@@ -21,16 +21,92 @@
 //
 // So: same transport, own keyspace. This module is deliberately small.
 //
-// NO REPLAY BUFFER HERE EITHER, and that is a decision rather than an omission. A
-// reconnecting client resumes LIVE and its 5s/15s/60s poll is what fills the gap it
-// missed; the contract gives it `seq` precisely so it can SEE the gap. Retaining a
-// per-session ring would add memory that grows with the number of sessions ever
-// opened, to duplicate a fallback that already exists and already works.
+// A BOUNDED REPLAY RING PER STREAMED SESSION (6.48.1), and why the earlier "no ring"
+// decision moved. `seq` stays per connection, so a shipped client still sees its gaps;
+// a new client ALSO reads `cursor`, monotonic per session for this server's life, and
+// reconnects with `?after=<cursor>` to be handed what it missed instead of a fresh
+// seed. The ring holds the last RING_MAX published events, keeps the ACTIVE TURN whole
+// (from its newest `prompt` draft onward, up to RING_HARD_MAX) and is dropped with the
+// session's last subscriber plus a linger, so memory is bounded by streamed sessions,
+// not by sessions ever opened. Even Terminal 0.10.4 ships the same shape (500-event
+// ring, replay on reconnect, the active turn always retained).
 
 import type { SessionStreamDraft } from './session-stream-events.js'
 
-/** A draft with the publish instant stamped. `seq` stays per connection. */
-export type PublishedSessionEvent = SessionStreamDraft & { at: number }
+/** A draft with the publish instant stamped. `seq` stays per connection; `cursor` is per session within `epoch`. */
+export type PublishedSessionEvent = SessionStreamDraft & { at: number; cursor?: number; epoch?: number }
+
+/**
+ * Cursors are meaningful only within one server life: a client holding a cursor from
+ * before a restart would otherwise be handed the wrong events from a fresh ring with no
+ * gap to notice (QA, 2026-09-15). Every event carries the epoch, and the SSE `id:` line
+ * is `<epoch>.<cursor>`; the route refuses to replay across epochs.
+ */
+export const RING_EPOCH = Date.now()
+
+/** Events the ring keeps per session. */
+export const RING_MAX = 500
+/** The active turn is never cut short of this. */
+export const RING_HARD_MAX = 2_000
+/** A session's ring outlives its last subscriber this long, so a reconnect finds the gap. */
+export const RING_LINGER_MS = 5 * 60_000
+
+interface Ring {
+  events: Array<PublishedSessionEvent & { cursor: number }>
+  nextCursor: number
+  /** Index into `events` of the newest prompt draft, or -1. */
+  turnStart: number
+  emptySince: number | null
+}
+
+const rings = new Map<string, Ring>()
+
+function ringFor(key: string): Ring {
+  let ring = rings.get(key)
+  if (!ring) {
+    ring = { events: [], nextCursor: 1, turnStart: -1, emptySince: null }
+    rings.set(key, ring)
+  }
+  return ring
+}
+
+function remember(key: string, event: PublishedSessionEvent): PublishedSessionEvent & { cursor: number } {
+  const ring = ringFor(key)
+  const stamped = { ...event, cursor: ring.nextCursor++, epoch: RING_EPOCH }
+  ring.events.push(stamped)
+  if (stamped.kind === 'prompt') ring.turnStart = ring.events.length - 1
+  // Trim the oldest, but never into the active turn until the hard cap.
+  while (ring.events.length > RING_MAX) {
+    if (ring.turnStart === 0 && ring.events.length <= RING_HARD_MAX) break
+    ring.events.shift()
+    if (ring.turnStart >= 0) ring.turnStart--
+  }
+  return stamped
+}
+
+/** Events published to this session after `afterCursor`, oldest first. Empty for an unknown session. */
+export function replaySessionStream(key: string, afterCursor: number): Array<PublishedSessionEvent & { cursor: number }> {
+  const ring = rings.get(key)
+  if (!ring) return []
+  const after = Number.isFinite(afterCursor) ? afterCursor : 0
+  return ring.events.filter(e => e.cursor > after)
+}
+
+/** The ring's oldest and newest cursors, so a client can tell a replay from a reseed. */
+export function ringBounds(key: string): { oldest: number; newest: number } | null {
+  const ring = rings.get(key)
+  if (!ring || ring.events.length === 0) return null
+  return { oldest: ring.events[0].cursor, newest: ring.events[ring.events.length - 1].cursor }
+}
+
+/** Drop rings whose session has had no subscriber for the linger. Called by the route on release. */
+export function sweepSessionRings(nowMs = Date.now()): number {
+  let dropped = 0
+  for (const [key, ring] of rings) {
+    if (ring.emptySince !== null && nowMs - ring.emptySince > RING_LINGER_MS) { rings.delete(key); dropped++ }
+  }
+  return dropped
+}
 
 export type SessionStreamListener = (event: PublishedSessionEvent) => void
 
@@ -78,6 +154,7 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
   const set = existing ?? new Set<SessionStreamListener>()
   set.add(listener)
   listeners.set(key, set)
+  ringFor(key).emptySince = null
 
   let released = false
   return () => {
@@ -88,7 +165,12 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
     const current = listeners.get(key)
     if (!current) return
     current.delete(listener)
-    if (current.size === 0) listeners.delete(key)
+    if (current.size === 0) {
+      listeners.delete(key)
+      const ring = rings.get(key)
+      if (ring) ring.emptySince = Date.now()
+      sweepSessionRings()
+    }
   }
 }
 
@@ -103,7 +185,8 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
 export function publishSessionStream(key: string, draft: SessionStreamDraft, at: number = Date.now()): number {
   const set = listeners.get(key)
   if (!set || set.size === 0) return 0
-  const event: PublishedSessionEvent = { ...draft, at }
+  // Remembered BEFORE fan-out, so a listener that reads the ring sees this event too.
+  const event: PublishedSessionEvent = remember(key, { ...draft, at })
   let delivered = 0
   for (const listener of [...set]) {
     try {
@@ -147,4 +230,5 @@ export function isAttachedTurnActive(key: string): boolean {
 export function __resetSessionStreamBusForTests(): void {
   listeners.clear()
   attachedTurns.clear()
+  rings.clear()
 }

package/server/lib/session-stream-events.ts

@@ -457,6 +457,150 @@ export function draftsFromLine(provider: SessionStreamProvider, line: string): S
   return draftsFromRecord(provider, parsed)
 }
 
+/**
+ * Did the newest turn in this transcript tail END? (6.48.1)
+ *
+ * THE RULE THE HARNESS USES, read against real Desktop transcripts on this Mac
+ * (2026-09-15): a Desktop session writes no `type:'result'` row at all (0 of 30 newest
+ * transcripts), so the status-draft rule above can only ever say "ended" for a
+ * `claude -p` run. What every Claude transcript DOES carry is `message.stop_reason` on
+ * each assistant record: `tool_use` while tools run, `end_turn` when the reply is done.
+ *
+ *   ended     the newest assistant record's stop_reason is terminal (end_turn,
+ *             stop_sequence, max_tokens, refusal) and no tool_use it issued is still
+ *             waiting for its tool_result; or a `result` row; or the user interrupted
+ *             (`[Request interrupted by user`), which ends the turn without a reply.
+ *   open      a user prompt newer than the last terminal reply (a `<task-notification>`
+ *             included: the model answers it), or a tool_use with no result yet.
+ *
+ * Skipped: `isMeta` and `isCompactSummary` rows (injected context, not a prompt), tool
+ * results, and the bookkeeping rows (`system`, `last-prompt`, `attachment`, `mode`...).
+ * Codex keeps its event rule (task_complete / turn_complete end, task_started opens).
+ *
+ * PURE, like everything else here. The queue store reads the tail; this decides.
+ */
+export const TERMINAL_STOP_REASONS: ReadonlySet<string> = new Set(['end_turn', 'stop_sequence', 'max_tokens', 'refusal'])
+
+export type TurnFromTail = { ended: boolean; reason: 'terminal_stop' | 'result_row' | 'interrupted' | 'codex_complete' | 'prompt_open' | 'prompt_queued' | 'tool_pending' | 'no_evidence' }
+
+export function turnFromTail(provider: SessionStreamProvider, lines: readonly string[]): TurnFromTail {
+  let verdict: TurnFromTail = { ended: false, reason: 'no_evidence' }
+  const pendingToolUses = new Set<string>()
+  for (const line of lines) {
+    const trimmed = typeof line === 'string' ? line.trim() : ''
+    if (!trimmed || trimmed[0] !== '{') continue
+    let record: unknown
+    try { record = JSON.parse(trimmed) } catch { continue }
+    const r = asRecord(record)
+    if (!r) continue
+
+    if (provider === 'codex') {
+      for (const draft of draftsFromRecord('codex', r)) {
+        if (draft.kind === 'status') verdict = draft.state === 'done' ? { ended: true, reason: 'codex_complete' } : { ended: false, reason: 'prompt_open' }
+      }
+      continue
+    }
+
+    const type = typeof r.type === 'string' ? r.type : ''
+    if (type === 'result') { verdict = { ended: true, reason: 'result_row' }; pendingToolUses.clear(); continue }
+    // A prompt typed while the Stop hooks run is QUEUED, not submitted (Claude writes a
+    // `queue-operation` row); it dequeues once the hooks return and the model answers it.
+    // The turn is not over until then (QA, 2026-09-15). The dequeue is followed by the
+    // user row itself, which the next branch reads.
+    if (type === 'queue-operation') {
+      if (r.operation === 'enqueue') verdict = { ended: false, reason: 'prompt_queued' }
+      continue
+    }
+    // Injected context is not a prompt, except a cross-session message (`promptSource:
+    // 'system'`), which the model answers as a turn.
+    if (r.isCompactSummary === true) continue
+    if (r.isMeta === true && r.promptSource !== 'system') continue
+    const message = asRecord(r.message)
+    if (!message) continue
+    const content = Array.isArray(message.content) ? message.content : typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : []
+    const blocks = content.map(asRecord).filter((b): b is Record<string, unknown> => b !== null)
+
+    if (type === 'user' || message.role === 'user') {
+      const results = blocks.filter(b => b.type === 'tool_result')
+      if (results.length > 0) {
+        for (const b of results) if (typeof b.tool_use_id === 'string') pendingToolUses.delete(b.tool_use_id)
+        continue
+      }
+      const text = blocks.filter(b => b.type === 'text' || b.type === undefined).map(b => (typeof b.text === 'string' ? b.text : '')).join(' ')
+      if (/\[Request interrupted by user/.test(text)) { verdict = { ended: true, reason: 'interrupted' }; pendingToolUses.clear(); continue }
+      if (text.trim().length === 0) continue
+      verdict = { ended: false, reason: 'prompt_open' }
+      continue
+    }
+
+    if (type === 'assistant' || message.role === 'assistant') {
+      for (const b of blocks) if (b.type === 'tool_use' && typeof b.id === 'string') pendingToolUses.add(b.id)
+      const stop = typeof message.stop_reason === 'string' ? message.stop_reason : ''
+      if (TERMINAL_STOP_REASONS.has(stop)) {
+        verdict = pendingToolUses.size === 0 ? { ended: true, reason: 'terminal_stop' } : { ended: false, reason: 'tool_pending' }
+      } else if (stop === 'tool_use' || pendingToolUses.size > 0) {
+        verdict = { ended: false, reason: 'tool_pending' }
+      }
+    }
+  }
+  return verdict
+}
+
+/**
+ * The derived session state on a `status` draft (6.48.1).
+ *
+ * EXTRA FIELDS ON THE EXISTING KIND, NEVER A NEW KIND: every shipped EHPK drops an
+ * unknown `kind` before its `seq` accounting and paints a "missed N" gap per event
+ * (validation round 1, B2). The shipped parser keeps `seq` and strips unknown fields
+ * on a `status` draft (canary 8), so an old client renders exactly as before and a
+ * new one reads the state line off the same event.
+ *
+ * `state` keeps its closed vocabulary. The table:
+ *   running -> working      waiting -> working (+ waiting_kind/detail)
+ *   idle    -> idle         failed  -> idle (+ failure)      ended -> done
+ *
+ * `done` on open flips the client to its digest body, which is intended for a session
+ * whose engine said SessionEnd. An ATTACHED COS TURN WINS (QA, 2026-09-15): the deriver
+ * is told `attachedTurn` and answers `running` for as long as the child is writing, so
+ * a Continue's trail is never handed off mid-stream by the tab's older Stop or by a
+ * child's own SessionEnd; the engine's state resumes the moment the turn detaches.
+ *
+ * `last_reply` rides only an idle state (the feed's "Idle, last reply: …" line).
+ */
+export interface DerivedStatusFields {
+  agent_state: 'running' | 'waiting' | 'idle' | 'failed' | 'ended'
+  state_source: 'hook' | 'registry' | 'transcript'
+  state_since: string
+  waiting_kind?: string
+  waiting_detail?: string
+  failure?: string
+  last_reply?: string
+}
+
+export type StatusDraftWithDerived = { kind: 'status'; state: SessionStreamState } & Partial<DerivedStatusFields>
+
+export function statusDraftWithDerived(
+  draft: { kind: 'status'; state: SessionStreamState },
+  derived: DerivedStatusFields | undefined,
+): StatusDraftWithDerived {
+  if (!derived) return draft
+  const state: SessionStreamState =
+    derived.agent_state === 'running' || derived.agent_state === 'waiting' ? 'working'
+    : derived.agent_state === 'ended' ? 'done'
+    : 'idle'
+  return {
+    kind: 'status',
+    state,
+    agent_state: derived.agent_state,
+    state_source: derived.state_source,
+    state_since: derived.state_since,
+    ...(derived.waiting_kind ? { waiting_kind: derived.waiting_kind } : {}),
+    ...(derived.waiting_detail !== undefined ? { waiting_detail: derived.waiting_detail } : {}),
+    ...(derived.failure ? { failure: derived.failure } : {}),
+    ...(state === 'idle' && derived.last_reply ? { last_reply: derived.last_reply } : {}),
+  }
+}
+
 /** Draft plus transport stamps, in the field order the contract shows. */
 export function stampSessionEvent(draft: SessionStreamDraft, seq: number, at: number): SessionStreamEvent {
   return { seq, at, ...draft }