@gotcos/glasses-server 6.48.0 → 6.48.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 6.48.1
+
+One derivation everywhere, a Desktop turn ends when the engine says it ended, a queued follow-up drains then instead of on the 30 s idle window, and the live feed carries the same state every row does. No client change is required: the next Control and EHPK builds read the new keys, and today's consumers ignore them.
+
+- A queued follow-up is delivered when the turn ends, and "ends" means what the engine means. Claude Code does not close a turn at the `Stop` hook: it closes it when every Stop hook has RETURNED, and only then dequeues anything typed meanwhile and flips its registry record to `idle`. On the release Mac the COS repo's own Stop hooks run 12-38 s, so a delivery at Stop + 2 s would have raced a prompt typed at the desk. The drain now waits for the registry's `idle` stamped at or after the Stop (polled every second, 60 s at most), then sweeps through one in-flight guard shared with the 20 s timer, so a burst of Stops folds into exactly one follow-up pass and a sentence is never delivered twice. A kick is spent only when a queue names that session; a COS child's own end kicks at once so chained follow-ups do not wait for the timer. Measured on the release Mac against a live holder whose own Stop hook ran 25 s: the registry flipped idle 25.0 s after the Stop hook, the follow-up was delivered 185 ms after that flip (its user row landed 1.5 s later, once, answered once, in the holder's own transcript, with the holder still open). Before this release: 35 s or more from the turn's end, and a delivery during the Stop hooks was possible.
+- The attach gate reads the same end of turn. With `COS_SESSION_HOOKS` on, a foreign Desktop holder whose newest hook event is a `Stop`, with the turn closed, no sub-agent open, and the registry idle at or after that Stop, reads idle at once instead of after the 30 s window. Null, unknown, a record that says busy, Codex and a far-future clock stay strict; the clause narrows a `working` verdict and never lifts a doubt. A COS Continue child registers under the tab's session id: when two records name the session the tab's is read, the child's only when it is alone.
+- The transcript's own rule for "the turn ended", used where the hooks did not see the session: the newest assistant record's `stop_reason` is terminal (end_turn, stop_sequence, max_tokens, refusal) with no `tool_use` still awaiting its result, a `result` row, or a user interrupt; a new prompt reopens it, a `<task-notification>` and a cross-session message included; a prompt queued during the Stop hooks (Claude's `queue-operation` row) keeps it open; other meta and compact rows do not. The tail read is 512 KiB: 3 of the 10 newest Desktop transcripts on the release Mac end in a ~76 KB attachment row after the terminal record, which a 64 KiB read could not see past. Positive evidence that a turn is OPEN (the hooks, or the tail) now holds ahead of the tail's ended verdict and ahead of the idle backstop, each bounded to the last 30 minutes so a crashed session still drains.
+- Every `status` draft on the session stream carries `agent_state`, `state_source`, `state_since` and, when known, `waiting_kind`, `waiting_detail`, `failure`, and on an idle state `last_reply`, as extra fields on the existing kind; `state` keeps its vocabulary (running and waiting read `working`, idle and failed `idle`, ended `done`). Every change of a session's hook state is a live status draft, so a client's state line moves on the engine's events. The stream derives from the same inputs the rows do (the hook signal, the registry record, and whether a COS turn is attached), so an Esc-interrupted turn reads idle on the lens the moment the list says so, and a Continue's trail reads `working` for as long as the child writes, never `done` from a stale Stop or from the child's own end. A shipped lens renders the frames exactly as before (its parser keeps `seq` and strips unknown fields). `COS_SESSION_HOOK_SSE=0` omits the extra fields and the live state drafts.
+- Reconnect without a reseed: each streamed session keeps a ring of its last 500 events (the active turn kept whole up to 2,000, the ring outliving the last subscriber by five minutes), each event carries a `cursor` and the server's `epoch`, and the SSE `id:` line is `<epoch>.<cursor>`. `?after=` (or `Last-Event-ID`) replays what the ring holds after that cursor, from the same server life only; a cursor from another life, one past the ring, and one with nothing after it all seed as a fresh open, so a reconnect is never an empty screen. `?seed=turn` opens a session at its current prompt and every step since, oldest first, bounded by the same 512 KiB tail read. The default seed is unchanged.
+- `queued_turns` on every `/api/agent-sessions` row (list, search, detail) and every `/api/claude-sessions` peer: the waiting follow-ups on that thread, omitted at 0. Search hits carry the same derived state fields the list does.
+- Two 6.48.0 defects: a tab adopted mid-turn read idle from a `PostToolUse` with no prompt seen (Claude 2.1.272 reloads hooks when the settings change, so open tabs report without a restart); a main-thread tool event now opens the turn, and a sub-agent's (`agent_id`) does not, live or replayed. `GET /api/session-hooks/runs` listed an interactive tab as a run with no end; runs carry the registry `entrypoint` (`sdk-cli` for `claude -p`, `claude-desktop`, `cli`), the ledger row remembers it so a restart cannot forget which sessions were tabs, and tabs are listed only with `?all=1`.
+- Two defects the live proof found in the follow-up path, both older than 6.48.0. The drainer's loopback delivery sent a turn body without `epoch` and `targetKey`, which the turns route has required since the binding hardening, so every drained follow-up was refused `invalid_request`, refunded and held for its whole TTL: it now sends the epoch the attach minted, the server's own target key and the attach's `boundTo`. And the 30 s idle backstop delivered a follow-up INTO a turn whose tool was still running (a 45 s tool leaves the transcript untouched for 45 s): the open-turn evidence above holds it. A queued turn whose `cosSessionId` the attach route would refuse is refused at enqueue instead of sitting in the queue.
+- `/api/health` `sessionHooks.drain` reports the kick's passes, kicks, folds and open waits.
+
 ## 6.48.0
 
 Session state now comes from Claude Code itself. A hook script spools every session event (session start and end, prompt submitted, turn stopped, permission wanted) and every session row carries one derived state with its provenance. No client change is required: Control 0.5.230 and glasses 6.9.478 ignore the new keys; Control 0.5.231 and the next EHPK read them.

package/README.md

@@ -181,14 +181,25 @@ The install keeps every hook you already had, backs the file up, and copies a sm
 POSIX sh script to `~/.cos-glasses/bin/cos-session-hook`. The script writes one file per
 event into `~/.cos-glasses/data/hook-spool` and never contacts the server (a permission
 request may, only after the desk has been idle for 90 s, for the approval feature that ships
-next). Sessions started after the install report `state_source: hook` on
-`/api/agent-sessions` and `/api/claude-sessions`; tabs already open keep their startup
-hook snapshot until restarted, and may show Claude's "hooks modified externally" notice once (expected: the user-level file changed under them). The next COS Control (0.5.231) offers the same install from
-its Sessions tab. Rows change only while the server runs with `COS_CLAUDE_SESSIONS_ENABLED=1`
+next). Sessions report `state_source: hook` on `/api/agent-sessions` and
+`/api/claude-sessions` from their next event on (Claude Code 2.1.272 reloads its hooks
+when the settings file changes, so open tabs need no restart; they may show Claude's
+"hooks modified externally" notice once, which is expected: the user-level file changed
+under them). A later COS Control offers the same install from its Sessions tab. Rows
+change only while the server runs with `COS_CLAUDE_SESSIONS_ENABLED=1`
 (`--hooks status` prints `serverApplies`). Turn the ingestion off with `COS_SESSION_HOOKS=0`
 (the spool is still drained and stamped, rows are exactly as before). Removing the package
 does not remove the hooks: run `--hooks uninstall` first.
 
+Since 6.48.1 the hooks also drive the follow-up queue (a queued Continue lands when the
+engine closes the turn: its `Stop` hook followed by its registry record flipping idle,
+which is when every Stop hook has returned), the attach gate (a Desktop holder whose
+turn just ended reads idle at once), and the live session stream (every `status` draft
+carries `agent_state` and friends; `?after=<epoch>.<cursor>` replays what the ring holds
+after a reconnect and seeds afresh when it holds nothing, `?seed=turn` opens at the
+current prompt). `COS_SESSION_HOOK_SSE=0` omits the extra status fields and the live
+state drafts; the `cursor`, `epoch` and `id:` line stay.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.48.0",
+  "version": "6.48.1",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -23,7 +23,7 @@ import { agentSessionStreamRouter } from './routes/agent-session-stream.js'
 import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import { createSessionHooksRouter } from './routes/session-hooks.js'
-import { startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
+import { registerDrainKickStats, registryIdleAfterStop, sessionHooksEnabled, sessionSignalStore, signalFor, startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
 import {
   createAgentSessionBindingsRouter,
   TargetGuard,
@@ -33,7 +33,7 @@ import {
 import { AgentSessionBindingRegistry } from './lib/agent-session-binding-registry.js'
 import { targetKey } from './lib/agent-session-binding-store.js'
 import { cosSpawnedPids } from './lib/agent-session-ownership-store.js'
-import { buildOccupancyProbes, realOccupancyDirs } from './lib/occupancy-probes.js'
+import { buildOccupancyProbes, realOccupancyDirs, withHookTurnClock } from './lib/occupancy-probes.js'
 import { realAttachedWorkspaceDeps, resolveAttachedWorkspace } from './lib/attached-workspace.js'
 import { deliverAttachedTurn, realAttachedTurnDeps } from './lib/attached-provider-adapter.js'
 import { forkThread, realForkDeps } from './lib/fork-thread.js'
@@ -129,7 +129,9 @@ import {
 
 const app = express()
 import { createThreadTurnQueueRouter, drainAllThreads } from './routes/thread-turn-queue.js'
-import { transcriptTurnEnded } from './lib/thread-turn-queue-store.js'
+import { queuedThreadKeys, transcriptTurnEnded, transcriptTurnVerdict } from './lib/thread-turn-queue-store.js'
+import { OPEN_TURN_CEILING_MS } from './lib/session-state-derive.js'
+import { createDrainKick, kickPlanFor } from './lib/thread-drain-kick.js'
 import { transcriptPathFor } from './lib/native-head.js'
 import { deliverQueuedTurnOverLoopback } from './lib/thread-turn-queue-deliver.js'
 import { readFences, writeFences } from './lib/thread-fence-store.js'
@@ -382,7 +384,12 @@ const attachedWorkspaceDeps = realAttachedWorkspaceDeps(nativeHeadDeps)
  * Read the canary evidence in `thread-occupancy.ts` under THE IDLE-HOLDER
  * RELAXATION before changing this line.
  */
-const occupancyProbes = buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled())
+const occupancyProbes = sessionHooksEnabled()
+  // 6.48.1, the B6 clause: with the hooks on, a foreign Desktop holder whose newest hook
+  // event is a Stop reads idle at once instead of after the 30 s transcript window. The
+  // wrapper only adds a probe; the gate's precedence is unchanged. Off is 6.48.0.
+  ? withHookTurnClock(buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled()), signalFor, registryIdleAfterStop)
+  : buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled())
 
 // 6.48.0: the hook spool ingester and the one signal store every session row reads. Starts
 // before any router is registered so the first list request already sees the replayed
@@ -622,11 +629,44 @@ if (threadAttachEnabled()) {
     turnEnded: (provider: string, threadId: string) => {
       if (provider !== 'claude' && provider !== 'codex') return false
       try {
+        // 6.48.1: the engine's own end of turn: a Stop hook newer than the turn's prompt
+        // AND the registry flipped idle after it (the Stop hooks have returned; a prompt
+        // typed during them is queued and dequeues only then). The transcript tail
+        // (`turnFromTail`) answers for everything the hooks did not see. Both refuse on doubt.
+        if (provider === 'claude') {
+          const signal = signalFor(threadId)
+          if (signal && !signal.turnOpen && signal.lastEvent === 'Stop' && typeof signal.stopAt === 'number'
+            && signal.stopAt >= (signal.turnStartedAt ?? 0) && signal.subagentsOpen === 0
+            && registryIdleAfterStop(threadId, signal.stopAt) === true) return true
+        }
         return transcriptTurnEnded(provider, transcriptPathFor(provider, threadId, nativeHeadDeps))
       } catch {
         return false
       }
     },
+    // 6.48.1: positive evidence the holder's turn is OPEN, which outranks the 30 s idle
+    // backstop (a long tool leaves the transcript untouched while it runs). Bounded: a
+    // signal or a tail older than OPEN_TURN_CEILING_MS is not evidence any more, so a
+    // crashed mid-tool session still drains by the backstop rather than holding for the TTL.
+    turnOpen: (provider: string, threadId: string): boolean => {
+      if (provider !== 'claude' && provider !== 'codex') return false
+      try {
+        const now = Date.now()
+        if (provider === 'claude') {
+          const signal = signalFor(threadId)
+          if (signal && signal.turnOpen && now - signal.lastEventAt <= OPEN_TURN_CEILING_MS) return true
+        }
+        const path = transcriptPathFor(provider, threadId, nativeHeadDeps)
+        const verdict = transcriptTurnVerdict(provider, path)
+        if (!verdict || verdict.ended) return false
+        if (verdict.reason !== 'tool_pending' && verdict.reason !== 'prompt_open') return false
+        const read = occupancyProbes.transcriptMtimeMs
+        const mtime = typeof read === 'function' ? read(provider, threadId) : null
+        return typeof mtime === 'number' && now - mtime <= OPEN_TURN_CEILING_MS
+      } catch {
+        return false
+      }
+    },
     activity: (provider: string, threadId: string): 'working' | 'idle' | 'unknown' => {
       try {
         const read = occupancyProbes.transcriptMtimeMs
@@ -645,10 +685,33 @@ if (threadAttachEnabled()) {
   // Every 20s. Fast enough that a freed thread drains while the user is still looking
   // at the pending row, slow enough to be nothing: the sweep does no work at all when
   // no queue file exists. Unref'd so it never holds the process open.
-  const queueDrainTimer = setInterval(() => {
-    void drainAllThreads(queueDeps).catch(() => { /* the next sweep retries */ })
-  }, 20_000)
+  //
+  // 6.48.1: the timer and the hooks' Stop share ONE in-flight guard (`thread-drain-kick`),
+  // so a Stop landing mid-sweep folds into exactly one follow-up pass and a sentence is
+  // never delivered twice. A Stop kicks only when a queue file names that session. A
+  // SubagentStop does NOT kick (QA, 2026-09-15): a background sub-agent finishing after
+  // the tab's Stop is answered by the model in a turn of its own, whose Stop kicks; and
+  // neither the hook short-circuit nor the B6 clause vouches for a session whose newest
+  // event is a SubagentStop, so a kick there could only fall through to the 30 s backstop.
+  const drainKick = createDrainKick({
+    drain: () => drainAllThreads(queueDeps),
+    queuedThreadIds: () => queuedThreadKeys().map(k => k.threadId),
+  })
+  registerDrainKickStats(() => drainKick.stats())
+  const queueDrainTimer = setInterval(() => { void drainKick.sweep() }, 20_000)
   queueDrainTimer.unref()
+  if (sessionHooksEnabled()) {
+    sessionSignalStore.subscribe((signal, env, child) => {
+      // The rule is `kickPlanFor` (pure, pinned in thread-drain-kick.test.ts). The Stop is
+      // not the engine's end of turn: that is the registry flipping idle once every Stop
+      // hook has returned (12-38 s on this Mac). Wait for it, then sweep; a session with
+      // no registry record (a print run that exited) is ready at once.
+      const plan = kickPlanFor(signal, env.event, env.ts, child)
+      if (!plan) return
+      if (plan.kind === 'kick') drainKick.kick(signal.sessionId)
+      else drainKick.kickWhen(signal.sessionId, () => registryIdleAfterStop(signal.sessionId, plan.stopAt) !== false)
+    })
+  }
 }
 
 app.use('/api', createAgentSessionBindingsRouter({

package/server/lib/claude-session-registry.ts

@@ -29,6 +29,9 @@
 //     nameSource entirely. Only `derived` is a function of the folder name.
 
 /** Fields this module will read. Everything else in the file is ignored. */
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
 export interface RawClaudeSession {
   pid?: unknown
   sessionId?: unknown
@@ -98,6 +101,22 @@ export interface PeerProbes {
 /** A registry filename is exactly `<pid>.json`. Not `*.json`. */
 export const REGISTRY_FILENAME = /^\d+\.json$/
 
+/**
+ * Where the registry lives.
+ *
+ * `COS_CLAUDE_SESSIONS_DIR` first because it is both the override for a non-standard
+ * install AND the test seam: `homedir()` is not mockable, so without an env hook the
+ * only testable path would be the real one. Then CLAUDE_CONFIG_DIR, which real
+ * installs do set; hardcoding ~/.claude breaks those. (Moved here from the route in
+ * 6.48.1 so the hooks runtime can read it without importing a router.)
+ */
+export function claudeSessionsDir(): string {
+  const explicit = process.env.COS_CLAUDE_SESSIONS_DIR
+  if (explicit) return resolve(explicit)
+  const configDir = process.env.CLAUDE_CONFIG_DIR
+  return join(configDir ? resolve(configDir) : join(homedir(), '.claude'), 'sessions')
+}
+
 function str(value: unknown): string | null {
   return typeof value === 'string' && value.length > 0 ? value : null
 }

package/server/lib/occupancy-probes.ts

@@ -787,6 +787,49 @@ export function buildOccupancyProbes(
  * adapter's pre-spawn preflight REFUSES a thenable rather than awaiting one —
  * awaiting there would reopen the very race the check exists to close.
  */
+/**
+ * Add the hook turn clock (the B6 clause, 6.48.1) to a probe set.
+ *
+ * `signalFor` is the signal store's reader, taking a full session id or the registry's
+ * 8-character form; `registryIdleAfterStop` reads the registry record for the session.
+ * The probe answers a Stop time only when BOTH vouch: the session's newest hook event is
+ * that Stop, the turn is closed, no sub-agent is open, the session has not ended, and
+ * the registry says idle at or after the Stop (the hooks have returned). Codex never
+ * asks (its ids are not Claude sessions, and a Codex thread id sharing a Claude prefix
+ * must not read a Claude signal); `readHolderActivity` guards the provider too.
+ *
+ * Wired at the composition root only when `COS_SESSION_HOOKS` is on. Absent, the
+ * gate is byte-for-byte 6.48.0.
+ */
+export function withHookTurnClock(
+  probes: OccupancyProbes,
+  signalFor: (sessionId: string) => HookTurnSignal | undefined,
+  registryIdleAfterStop: (sessionId: string, stopAt: number) => boolean | null,
+): OccupancyProbes {
+  return {
+    ...probes,
+    holderTurnEndedAtMs: (provider, threadId) => {
+      if (provider !== 'claude') return null
+      if (!NATIVE_THREAD_ID_RE.test(threadId)) return null
+      const signal = signalFor(threadId)
+      if (!signal || signal.lastEvent !== 'Stop' || signal.turnOpen || signal.subagentsOpen > 0 || signal.ended !== null) return null
+      if (typeof signal.stopAt !== 'number') return null
+      // The engine's own end of turn: the registry flipped idle AFTER this Stop, which
+      // happens only once every Stop hook has returned. Anything else is strict.
+      return registryIdleAfterStop(threadId, signal.stopAt) === true ? signal.stopAt : null
+    },
+  }
+}
+
+/** The facts the hook turn clock reads off a session signal. */
+export interface HookTurnSignal {
+  lastEvent: string
+  turnOpen: boolean
+  subagentsOpen: number
+  ended: { at: number; reason: string } | null
+  stopAt: number | null
+}
+
 export function withTranscriptClock(
   probes: OccupancyProbes,
   headDeps: NativeHeadDeps,

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

@@ -182,6 +182,11 @@ export function projectHookPayload(event: HookEventName, payload: Record<string,
         tool_target: toolTarget(payload.tool_input),
         tool_fingerprint: toolFingerprint(toolName, payload.tool_input ?? null),
         ...(str('tool_use_id') ? { tool_use_id: str('tool_use_id') } : {}),
+        // A sub-agent's tool events carry these (docs; unrecorded as of 2026-09-15). The
+        // store reads `agent_id` to keep them from reopening the main turn, so the ledger
+        // must keep it or a replay reopens what the live path did not.
+        ...(str('agent_id') ? { agent_id: str('agent_id') } : {}),
+        ...(str('agent_type') ? { agent_type: str('agent_type') } : {}),
         ...(event === 'PermissionRequest' && Array.isArray(payload.permission_suggestions)
           ? { permission_suggestions: payload.permission_suggestions.slice(0, 4) }
           : {}),

package/server/lib/session-hook-ledger.ts

@@ -20,6 +20,8 @@ export interface LedgerRow {
   session_id: string
   /** Classified at ingest, while the pid was alive: a COS-spawned child's event. */
   child?: boolean
+  /** The registry's `entrypoint` for the session, once read (6.48.1); a replay restores it. */
+  entrypoint?: string
   payload: Record<string, unknown>
 }
 
@@ -54,7 +56,7 @@ export class SessionHookLedger {
   }
 
   /** Append one row. Returns false (and remembers why) when the disk refused. */
-  append(key: string, env: HookEnvelope, child = false): boolean {
+  append(key: string, env: HookEnvelope, child = false, entrypoint: string | null = null): boolean {
     let row: LedgerRow
     try {
       row = {
@@ -64,6 +66,7 @@ export class SessionHookLedger {
         event: env.event,
         session_id: env.sessionId,
         ...(child ? { child: true } : {}),
+        ...(entrypoint ? { entrypoint } : {}),
         payload: projectHookPayload(env.event, env.payload),
       }
     } catch (error) {
@@ -96,7 +99,7 @@ export class SessionHookLedger {
    * hide the rows that matter most, and forget their keys). Malformed lines are skipped;
    * a boot must never fail on a torn last line.
    */
-  replay(sinceMs: number, apply: (env: HookEnvelope, key: string, child: boolean) => void): { rows: number; applied: number; keys: Set<string> } {
+  replay(sinceMs: number, apply: (env: HookEnvelope, key: string, child: boolean, entrypoint: string | null) => void): { rows: number; applied: number; keys: Set<string> } {
     const keys = new Set<string>()
     let rows = 0
     let applied = 0
@@ -115,7 +118,8 @@ export class SessionHookLedger {
       keys.add(r.key)
       if (r.ts < sinceMs) continue
       const payload = r.payload && typeof r.payload === 'object' ? r.payload as Record<string, unknown> : {}
-      apply({ ts: r.ts, ppid: typeof r.ppid === 'number' ? r.ppid : null, event: r.event, sessionId: r.session_id.toLowerCase(), payload: { session_id: r.session_id, ...payload } }, r.key, r.child === true)
+      const entrypoint = typeof r.entrypoint === 'string' && r.entrypoint ? r.entrypoint : null
+      apply({ ts: r.ts, ppid: typeof r.ppid === 'number' ? r.ppid : null, event: r.event, sessionId: r.session_id.toLowerCase(), payload: { session_id: r.session_id, ...payload } }, r.key, r.child === true, entrypoint)
       applied++
     }
     return { rows, applied, keys }

package/server/lib/session-hook-spool.ts

@@ -45,9 +45,15 @@ export interface SpoolIngesterOptions {
   dir: string
   ledger: SessionHookLedger
   /** Apply a parsed envelope to the store. Absent when the feature is off. */
-  apply?: (env: HookEnvelope, child: boolean) => void
+  apply?: (env: HookEnvelope, child: boolean, entrypoint: string | null) => void
   /** Classify the envelope's ppid at INGEST time, while the pid is still alive. */
   isChild?: (env: HookEnvelope) => boolean
+  /**
+   * The session's registry `entrypoint`, read at INGEST time while the record is alive
+   * (6.48.1). Written onto the ledger row so a replay after a restart knows a print run
+   * from a tab without a registry that has since been reaped.
+   */
+  entrypointOf?: (env: HookEnvelope, child: boolean) => string | null
   /** Keys already in the ledger at boot, so a replayed file is not applied twice. */
   seenKeys?: Set<string>
   sweepMs?: number
@@ -175,15 +181,17 @@ export function startSpoolIngester(options: SpoolIngesterOptions): SpoolIngester
     // replay after a restart (when the spawn ledger is empty) applies the same rule.
     let child = false
     try { child = options.isChild?.(env) ?? false } catch { child = false }
+    let entrypoint: string | null = null
+    try { entrypoint = options.entrypointOf?.(env, child) ?? null } catch { entrypoint = null }
     let appended = false
-    try { appended = ledger.append(name, env, child) } catch (error) { stats.lastError = errorCode(error) }
+    try { appended = ledger.append(name, env, child, entrypoint) } catch (error) { stats.lastError = errorCode(error) }
     if (!appended) {
       // Keep the file: the ledger is the durable record and it refused. Health shows why.
       stats.lastError = ledger.stats().lastError ?? stats.lastError
       return false
     }
     seen.add(name)
-    try { options.apply?.(env, child) } catch (error) {
+    try { options.apply?.(env, child, entrypoint) } catch (error) {
       stats.applyErrors++
       console.error(`[hook-spool] apply failed for ${name}: ${error instanceof Error ? error.message : error}`)
     }

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
 }