@gotcos/glasses-server 6.47.0 → 6.48.0

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

@@ -0,0 +1,211 @@
+// ONE derivation of a session's state, for every surface.
+//
+// Before 6.48.0 three readers derived state on their own: this server (`running` and
+// `running_active` from occupancy and a 30 s transcript window), the Control helper
+// (transcript tail + a 15 minute "in flight, then waiting" guess), and the EHPK (four
+// states from the row's flags). The pet, the Sessions tab, the phone and the lens could
+// disagree about the same tab. This function is the only place a state is decided;
+// the rows carry its answer and its provenance.
+//
+// PRECEDENCE, in order, each with the evidence that makes it yield:
+//
+//   hook        the engine's own hook events for this session (`session-signal-store`)
+//               yields to registry when the registry's status moved more recently and the
+//               hooks have been silent for HOOK_SILENCE_MS
+//   registry    `~/.claude/sessions/<pid>.json` status busy|idle|waiting with a live pid
+//               yields to `ended` after MISS_LIMIT consecutive derives with a dead pid
+//   transcript  whatever the transcript tail says (activity clock, in-flight marker)
+//
+// `ended` from a SessionEnd hook is honoured only when no alive registry record remains:
+// a COS Continue child shares the tab's session id and ends while the tab stays open.
+//
+// The wire key is `agent_state`, never `state`: `state` already exists on every row as
+// `running|recent` and Control renders anything else as "Running" (validation round 1).
+
+import type { SessionSignal, WaitingKind } from './session-signal-store.js'
+
+export type AgentState = 'running' | 'waiting' | 'idle' | 'failed' | 'ended'
+export type StateSource = 'hook' | 'registry' | 'transcript'
+
+export interface DerivedSessionState {
+  agent_state: AgentState
+  state_source: StateSource
+  /** ISO time of the event that produced the current state. */
+  state_since: string
+  waiting_kind?: WaitingKind
+  waiting_detail?: string
+  failure?: string
+  last_reply?: string
+  pending_permission_id?: string
+  /** Consecutive derives that saw a dead registry pid; carried by the caller between polls. */
+  deadScans: number
+  /** When the pid was first seen dead, so two observations must also be DEAD_GRACE_MS apart. */
+  deadSince: number | null
+}
+
+/** The registry facts the deriver reads; a projection of the peer record, never the wire. */
+export interface RegistryFacts {
+  alive: boolean
+  status: string | null
+  waitingFor: string | null
+  statusUpdatedAt: number | null
+  lastActiveAt: number | null
+}
+
+/** What the transcript tail says, when nothing better is known. */
+export interface TranscriptFacts {
+  /** The newest assistant record is a tool_use with no result, or a user prompt awaits. */
+  inFlight: boolean
+  lastActivityAt: number | null
+}
+
+export interface DeriveInput {
+  signal: SessionSignal | undefined
+  registry: RegistryFacts | undefined
+  transcript: TranscriptFacts | undefined
+  now: number
+  /** The previous derive's `deadScans`, so the two-scan rule survives between polls. */
+  prevDeadScans?: number
+  /** The previous derive's `deadSince`. */
+  prevDeadSince?: number | null
+}
+
+/** Harness `MISS_LIMIT`: a pid must be dead on two consecutive scans before a row ends. */
+export const MISS_LIMIT = 2
+/**
+ * The two scans must also be this far apart in wall-clock time. A derive runs per HTTP
+ * request, and one client refresh is two requests in milliseconds; a registry file that
+ * is being rewritten must not read as a death.
+ */
+export const DEAD_GRACE_MS = 5_000
+/** A hook-derived wait with no live registry record behind it is not trusted past this. */
+export const WAITING_CEILING_MS = 30 * 60_000
+/** Transcript activity this much newer than a wait means the tool ran: the wait is over. */
+export const WAITING_TRANSCRIPT_VETO_MS = 60_000
+/** Hooks silent this long while the registry moved: the registry wins. */
+export const HOOK_SILENCE_MS = 30 * 60_000
+/** A turn that has been open this long with no event at all is no longer trusted as running. */
+export const OPEN_TURN_CEILING_MS = 30 * 60_000
+
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export function deriveSessionState(input: DeriveInput): DerivedSessionState {
+  const { signal, registry, transcript, now } = input
+  const prevDead = input.prevDeadScans ?? 0
+  const dead = !!registry && !registry.alive
+  const deadScans = dead ? prevDead + 1 : 0
+  const deadSince = dead ? (input.prevDeadSince ?? now) : null
+  const deadLongEnough = dead && deadScans >= MISS_LIMIT && deadSince !== null && now - deadSince >= DEAD_GRACE_MS
+  const registryMovedLater = !!(registry?.statusUpdatedAt && signal && registry.statusUpdatedAt > signal.lastEventAt)
+  const hooksSilent = !!signal && now - signal.lastEventAt > HOOK_SILENCE_MS
+  const carry = { deadScans, deadSince }
+
+  // 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).
+  if (deadLongEnough && !(signal && registry.lastActiveAt && signal.lastEventAt > registry.lastActiveAt)) {
+    return { agent_state: 'ended', state_source: 'registry', state_since: iso(registry.lastActiveAt ?? now), ...carry, ...replyOf(signal) }
+  }
+
+  if (signal && !(registryMovedLater && hooksSilent)) {
+    const fromHook = deriveFromSignal(signal, registry, transcript, now)
+    if (fromHook) return { ...fromHook, ...carry }
+  }
+
+  if (registry?.alive) {
+    const since = iso(registry.statusUpdatedAt ?? registry.lastActiveAt ?? now)
+    if (registry.status === 'waiting') {
+      return { agent_state: 'waiting', state_source: 'registry', state_since: since, waiting_kind: registryWaitingKind(registry.waitingFor), waiting_detail: registry.waitingFor ?? '', ...carry, ...replyOf(signal) }
+    }
+    if (registry.status === 'busy') return { agent_state: 'running', state_source: 'registry', state_since: since, ...carry, ...replyOf(signal) }
+    if (registry.status === 'idle') return { agent_state: 'idle', state_source: 'registry', state_since: since, ...carry, ...replyOf(signal) }
+  }
+
+  if (transcript) {
+    const since = iso(transcript.lastActivityAt ?? now)
+    return { agent_state: transcript.inFlight ? 'running' : 'idle', state_source: 'transcript', state_since: since, ...carry, ...replyOf(signal) }
+  }
+
+  // Only a signal that was ruled stale above, or nothing at all: a stale open turn is not
+  // evidence of work, so it reads idle.
+  if (signal) return { agent_state: 'idle', state_source: 'hook', state_since: iso(signal.stopAt ?? signal.lastEventAt), ...carry, ...replyOf(signal) }
+  return { agent_state: 'idle', state_source: 'transcript', state_since: iso(now), ...carry }
+}
+
+/** The registry writes `waitingFor: "dialog open"` for a permission dialog on this Mac. */
+function registryWaitingKind(waitingFor: string | null): WaitingKind {
+  return waitingFor && /dialog|permission|approv/i.test(waitingFor) ? 'permission' : 'question'
+}
+
+function replyOf(signal: SessionSignal | undefined): { last_reply?: string } {
+  return signal?.lastReply ? { last_reply: signal.lastReply } : {}
+}
+
+type HookVerdict = Omit<DerivedSessionState, 'deadScans' | 'deadSince'>
+
+function deriveFromSignal(signal: SessionSignal, registry: RegistryFacts | undefined, transcript: TranscriptFacts | undefined, now: number): HookVerdict | null {
+  const reply = replyOf(signal)
+  if (signal.ended && !(registry?.alive)) {
+    return { agent_state: 'ended', state_source: 'hook', state_since: iso(signal.ended.at), ...reply }
+  }
+  if (signal.waiting && waitStillStands(signal.waiting.since, registry, transcript, now)) {
+    return {
+      agent_state: 'waiting',
+      state_source: 'hook',
+      state_since: iso(signal.waiting.since),
+      waiting_kind: signal.waiting.kind,
+      waiting_detail: signal.waiting.detail,
+      ...(signal.waiting.requestId ? { pending_permission_id: signal.waiting.requestId } : {}),
+      ...reply,
+    }
+  }
+  if (signal.waiting) {
+    // The wait was overtaken by evidence the store cannot see (registry moved on, the
+    // transcript moved on, or nothing alive stands behind it): fall through to whoever can.
+    return null
+  }
+  if (signal.failure && !signal.turnOpen) {
+    return { agent_state: 'failed', state_source: 'hook', state_since: iso(signal.failure.at), failure: signal.failure.kind, ...reply }
+  }
+  if (signal.turnOpen) {
+    // An interrupt (Esc) fires no Stop: the registry moving to idle AFTER the last hook
+    // event is the only signal, and it must not wait for the half-hour ceiling.
+    if (registry?.alive && registry.status === 'idle' && registry.statusUpdatedAt && registry.statusUpdatedAt > signal.lastEventAt) return null
+    // An open turn with no event for half an hour is not evidence of work any more;
+    // let the registry or the transcript answer.
+    if (now - signal.lastEventAt > OPEN_TURN_CEILING_MS) return null
+    return { agent_state: 'running', state_source: 'hook', state_since: iso(signal.turnStartedAt ?? signal.lastEventAt), ...reply }
+  }
+  // A child that ended while the tab is alive reads idle, since the tab's own hooks are
+  // what would say otherwise.
+  return { agent_state: 'idle', state_source: 'hook', state_since: iso(signal.stopAt ?? signal.lastEventAt), ...reply }
+}
+
+/**
+ * A hook-derived wait stands while nothing contradicts it. Three things do: the registry
+ * moved after the wait began and no longer says waiting (the dialog closed); the
+ * transcript moved on well after the wait began (the tool ran); nothing alive stands
+ * behind a wait older than the ceiling (a tab that died with its dialog up, or a
+ * PermissionRequest spooled during an outage whose close half the guard dropped).
+ */
+function waitStillStands(since: number, registry: RegistryFacts | undefined, transcript: TranscriptFacts | undefined, now: number): boolean {
+  if (registry?.alive && registry.statusUpdatedAt && registry.statusUpdatedAt > since && registry.status !== 'waiting' && registry.status !== null) return false
+  if (transcript?.lastActivityAt && transcript.lastActivityAt > since + WAITING_TRANSCRIPT_VETO_MS) return false
+  if (!(registry?.alive) && now - since > WAITING_CEILING_MS) return false
+  return true
+}
+
+/** 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 {}
+  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.last_reply ? { last_reply: derived.last_reply } : {}),
+    ...(derived.pending_permission_id ? { pending_permission_id: derived.pending_permission_id } : {}),
+  }
+}

package/server/routes/agent-sessions.ts

@@ -37,7 +37,10 @@ import {
   type AgentSessionSort,
 } from '../lib/agent-session-store.js'
 import { searchAgentSessions, type AgentSessionSearchHit } from '../lib/agent-session-search.js'
-import { claudeSessionNamesVisible, claudeSessionsDir, claudeSessionsEnabled, readClaudePeers } from './claude-sessions.js'
+import { claudeSessionNamesVisible, claudeSessionsDir, claudeSessionsEnabled, readClaudePeerRecords, registryFacts } from './claude-sessions.js'
+import type { ClaudePeerRecord } from '../lib/claude-session-registry.js'
+import { deriveForRow } from '../lib/session-hooks-runtime.js'
+import { derivedRowFields, type DerivedSessionState } from '../lib/session-state-derive.js'
 import { workspaceFromCwd } from '../lib/claude-session-registry.js'
 import {
   occupiedThreads,
@@ -261,7 +264,7 @@ function runningForThread(provider: AgentProvider, threadId: string, mtimeMs: nu
   }
 }
 
-function toEntry(row: AgentSessionRow, activity?: SessionActivity | null) {
+function toEntry(row: AgentSessionRow, activity?: SessionActivity | null, derived?: DerivedSessionState) {
   return {
     session_id: row.session_id,
     provider: row.provider,
@@ -286,12 +289,19 @@ function toEntry(row: AgentSessionRow, activity?: SessionActivity | null) {
     // unknown, so an older client and a Cursor row see exactly the payload they did.
     ...(activity?.lastActivityAt ? { last_activity_at: activity.lastActivityAt } : {}),
     ...(activity?.lastTool ? { last_tool: activity.lastTool } : {}),
+    // 6.48.0: the one derived state (hook > registry > transcript) with its provenance.
+    // Under a NEW key: `state` above is `running|recent` and Control renders any other
+    // value there as "Running". Omitted entirely when nothing is known, like the two above.
+    ...derivedRowFields(derived),
   }
 }
 
-async function liveClaudeRows(): Promise<AgentSessionRow[]> {
+async function liveClaudePeerRecords(): Promise<ClaudePeerRecord[]> {
   if (!claudeSessionsEnabled()) return []
-  const peers = await readClaudePeers(claudeSessionsDir(), undefined, claudeSessionNamesVisible())
+  return readClaudePeerRecords(claudeSessionsDir(), undefined, claudeSessionNamesVisible())
+}
+
+function liveClaudeRows(peers: ClaudePeerRecord[]): AgentSessionRow[] {
   return peers.filter(peer => peer.alive).map(peer => ({
     session_id: peer.id,
     provider: 'claude' as const,
@@ -322,7 +332,8 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
     // ONE alias load per request, shared by the walk, every live row and every
     // held thread. Measured 2026-09-10: sixteen loads of 119 MB before this line.
     const aliases = await loadClaudeDesktopAliases(roots.claudeCodeSessions)
-    const live = await liveClaudeRows()
+    const peers = await liveClaudePeerRecords()
+    const live = liveClaudeRows(peers)
     const dropped = emptySessionListDropped()
     const sessions = await listAgentSessions(roots, new Date(), live, limit, sort, dropped, aliases)
     // 6.45.5: each row's last real activity, read from its transcript records. Memoized on
@@ -342,8 +353,35 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
       if (mtimeMs !== null) clocks.set(threadId, activityClockMs(mtimeMs, activityById.get(threadId)))
     }
     const running = withActiveRecently(scan, clocks, Date.now())
+    // Derived AFTER the walk: live rows carry the registry's eight-character id until
+    // `enrichLiveClaude` finds their transcript, and the deriver wants the full one where
+    // it exists. The registry facts are joined back by prefix; a transcript-only row (an
+    // ended job, a tab closed hours ago) still gets a state from its activity clock.
+    const now = Date.now()
+    // First wins, and `readClaudePeerRecords` sorts alive first: a dead predecessor's file
+    // (a resumed tab, a finished Continue child) must never shadow the live record.
+    const peersByPrefix = new Map<string, ClaudePeerRecord>()
+    for (const peer of peers) {
+      const prefix = peer.sessionId.slice(0, 8)
+      if (!peersByPrefix.has(prefix)) peersByPrefix.set(prefix, peer)
+    }
+    const derivedById = new Map<string, DerivedSessionState | undefined>()
+    for (const row of sessions) {
+      if (row.provider !== 'claude') continue
+      const peer = peersByPrefix.get(row.session_id.slice(0, 8).toLowerCase())
+      const hint = running.occupied.get(row.session_id)
+      derivedById.set(row.session_id, deriveForRow({
+        sessionId: row.session_id,
+        registry: peer ? registryFacts(peer) : undefined,
+        transcript: {
+          inFlight: hint?.activeRecently === true,
+          lastActivityAt: activityById.get(row.session_id)?.lastActivityAt ? Date.parse(activityById.get(row.session_id)!.lastActivityAt!) : null,
+        },
+        now,
+      }))
+    }
     res.json({
-      sessions: sessions.map((row, index) => withRunning(toEntry(row, activity[index]), running)),
+      sessions: sessions.map((row, index) => withRunning(toEntry(row, activity[index], derivedById.get(row.session_id)), running)),
       total: sessions.length,
       windowHours: AGENT_SESSION_WINDOW_HOURS,
       sort,
@@ -417,8 +455,20 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     const modified = st.mtime.toISOString()
     const activity = await readSessionActivity(provider, found)
     const running = runningForThread(provider, parsed.session_id, activityClockMs(st.mtimeMs, activity))
+    // 6.48.0: the detail carries the same derived state as its list row. The registry is
+    // read once here (a few hundred small files at most) because the detail has no walk.
+    let derived: DerivedSessionState | undefined
+    if (provider === 'claude') {
+      const peer = (await liveClaudePeerRecords()).find(p => p.sessionId === parsed.session_id.toLowerCase()) // alive first
+      derived = deriveForRow({
+        sessionId: parsed.session_id,
+        registry: peer ? registryFacts(peer) : undefined,
+        transcript: { inFlight: running.occupied.get(parsed.session_id)?.activeRecently === true, lastActivityAt: activity.lastActivityAt ? Date.parse(activity.lastActivityAt) : null },
+      })
+    }
     res.json({
       ...withRunning({ session_id: parsed.session_id }, running),
+      ...derivedRowFields(derived),
       // The client must be able to tell "this server stamped nothing" from "this
       // server stamped false", because the two demand opposite behaviour: an old
       // server's silence means keep using the hint borrowed from the list row, and

package/server/routes/claude-sessions.ts

@@ -28,7 +28,12 @@ import {
   type ClaudePeer,
   type PeerProbes,
   type RawClaudeSession,
+  type ClaudePeerRecord,
+  peerRecordFacts,
+  toWirePeer,
 } from '../lib/claude-session-registry.js'
+import { deriveForRow } from '../lib/session-hooks-runtime.js'
+import { derivedRowFields, type RegistryFacts } from '../lib/session-state-derive.js'
 
 export const claudeSessionsRouter = Router()
 
@@ -92,6 +97,15 @@ export async function readClaudePeers(
   probes: PeerProbes = realProbes,
   showNames = claudeSessionNamesVisible(),
 ): Promise<ClaudePeer[]> {
+  return (await readClaudePeerRecords(dir, probes, showNames)).map(toWirePeer)
+}
+
+/** The peers with the deriver's facts attached. Server-side only; see `toWirePeer`. */
+export async function readClaudePeerRecords(
+  dir: string,
+  probes: PeerProbes = realProbes,
+  showNames = claudeSessionNamesVisible(),
+): Promise<ClaudePeerRecord[]> {
   let names: string[]
   try {
     names = await readdir(dir)
@@ -101,7 +115,7 @@ export async function readClaudePeers(
     // separately so this cannot be mistaken for "the feature is off".
     return []
   }
-  const peers: ClaudePeer[] = []
+  const peers: ClaudePeerRecord[] = []
   for (const name of names.filter(n => REGISTRY_FILENAME.test(n)).slice(0, MAX_REGISTRY_FILES)) {
     const full = join(dir, name)
     try {
@@ -114,7 +128,8 @@ export async function readClaudePeers(
       let mtimeMs: number | null = null
       try { mtimeMs = (await stat(full)).mtimeMs } catch { /* raced the reaper */ }
       const peer = toPeer(raw, probes, mtimeMs, showNames)
-      if (peer) peers.push(peer)
+      const facts = peerRecordFacts(raw)
+      if (peer && facts) peers.push({ ...peer, ...facts })
     } catch {
       // ENOENT between readdir and read is NORMAL here — the reaper is actively
       // unlinking these — and a torn read is expected because writes are
@@ -122,7 +137,12 @@ export async function readClaudePeers(
       continue
     }
   }
-  return sortPeers(peers)
+  return sortPeers(peers) as ClaudePeerRecord[]
+}
+
+/** The deriver's view of a registry record. */
+export function registryFacts(record: ClaudePeerRecord): RegistryFacts {
+  return { alive: record.alive, status: record.status, waitingFor: record.waitingFor, statusUpdatedAt: record.statusUpdatedAt, lastActiveAt: record.lastActiveAt }
 }
 
 function boundedInteger(value: unknown, fallback: number, min: number, max: number): number {
@@ -148,9 +168,16 @@ claudeSessionsRouter.get('/claude-sessions', async (req, res) => {
   }
   try {
     const limit = boundedInteger(req.query.limit, 30, 1, 100)
-    const peers = await readClaudePeers(claudeSessionsDir())
+    const records = await readClaudePeerRecords(claudeSessionsDir())
+    const peers = records.map(toWirePeer)
+    // 6.48.0: the same derived state every surface reads, stamped ADDITIVELY on the wire
+    // peer. `toPeer` stays byte-identical (its key set is pinned); the eight extra keys
+    // come from the signal store and the registry facts an older client never sees.
     res.json({
-      peers: peers.slice(0, limit),
+      peers: records.slice(0, limit).map(record => ({
+        ...toWirePeer(record),
+        ...derivedRowFields(deriveForRow({ sessionId: record.sessionId, registry: registryFacts(record) })),
+      })),
       counts: countPeers(peers),
       enabled: true,
       generatedAt: Date.now(),

package/server/routes/health.ts

@@ -79,6 +79,7 @@ import {
   threadAttachCapability,
   threadAttachHealthFields,
 } from '../lib/thread-attach-capability.js'
+import { sessionHooksHealthFields } from '../lib/session-hooks-runtime.js'
 
 export const healthRouter = Router()
 
@@ -349,6 +350,7 @@ healthRouter.get('/health', async (_req, res) => {
     ...checks,
     server_version: managedServerVersion(),
     ...threadAttachHealthFields(threadAttach),
+    ...sessionHooksHealthFields(),
     server_instance_id: getServerInstanceId(),
     boot_id: serverMetrics.bootId,
     generation_id: getServerGenerationId(),

package/server/routes/session-hooks.ts

@@ -0,0 +1,70 @@
+// Session hooks: status, install, uninstall, and today's runs.
+//
+// `GET /api/session-hooks/status` is what Control's banner keys off. Five outcomes on
+// the client side and this route owns three of them: 200 with `installed` (no banner),
+// 200 with `drift`, `missing`, `script_outdated`, `settings_*` (banner with Install). A
+// 404 means a server older than 6.48.0 (`route_absent`), and no answer at all is
+// `unreachable`; neither is "not installed", and Control must never say so for them.
+
+import { Router } from 'express'
+import { installClaudeHooks, uninstallClaudeHooks } from '../lib/claude-hooks-installer.js'
+import { deskIdleSeconds, invalidateHookStatus, sessionHooksHealthFields, sessionSignalStore } from '../lib/session-hooks-runtime.js'
+import { workspaceFromCwd } from '../lib/claude-session-registry.js'
+
+export function createSessionHooksRouter(options: { port: number }): Router {
+  const router = Router()
+
+  router.get('/session-hooks/status', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    res.json({ ok: true, ...sessionHooksHealthFields() })
+  })
+
+  router.post('/session-hooks/install', (req, res) => {
+    const dryRun = req.query.dryRun === '1' || (req.body && typeof req.body === 'object' && (req.body as { dryRun?: unknown }).dryRun === true)
+    const result = installClaudeHooks({ port: options.port, deskIdleSeconds: deskIdleSeconds(), dryRun })
+    invalidateHookStatus()
+    if (!result.ok) {
+      res.status(409).json({ ok: false, reason: result.reason ?? 'install_failed', status: result.status })
+      return
+    }
+    res.json({ ok: true, changed: result.changed, scriptCopied: result.scriptCopied, backupPath: result.backupPath, status: result.status, ...(dryRun ? { merged: result.merged } : {}) })
+  })
+
+  router.post('/session-hooks/uninstall', (req, res) => {
+    const dryRun = req.query.dryRun === '1'
+    const result = uninstallClaudeHooks({ dryRun })
+    invalidateHookStatus()
+    if (!result.ok) {
+      res.status(409).json({ ok: false, reason: result.reason ?? 'uninstall_failed', status: result.status })
+      return
+    }
+    res.json({ ok: true, changed: result.changed, backupPath: result.backupPath, status: result.status, ...(dryRun ? { merged: result.merged } : {}) })
+  })
+
+  // Sessions the hooks saw start and end, for Control's scheduled-job ledger. A run
+  // shorter than the pet's 20 s poll is recorded here where the poll never saw it.
+  router.get('/session-hooks/runs', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const since = Number(req.query.since)
+    const sinceMs = Number.isFinite(since) && since > 0 ? since : Date.now() - 24 * 60 * 60_000
+    const runs: Array<Record<string, unknown>> = []
+    for (const signal of sessionSignalStore.snapshot()) {
+      if (signal.firstSeenAt < sinceMs && !(signal.ended && signal.ended.at >= sinceMs)) continue
+      runs.push({
+        session_id: signal.sessionId,
+        started_at: new Date(signal.firstSeenAt).toISOString(),
+        ended_at: signal.ended ? new Date(signal.ended.at).toISOString() : null,
+        end_reason: signal.ended?.reason ?? null,
+        // The registry route reduces cwd to a workspace name on the wire; so does this one.
+        workspace: workspaceFromCwd(signal.cwd),
+        keep_warm: signal.keepWarm,
+        child_events: signal.childEvents,
+        last_reply: signal.lastReply || null,
+      })
+    }
+    runs.sort((a, b) => String(b.started_at).localeCompare(String(a.started_at)))
+    res.json({ ok: true, runs, since: new Date(sinceMs).toISOString() })
+  })
+
+  return router
+}

package/server/scripts/hooks-cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+// Install, inspect or remove the COS session hook in ~/.claude/settings.json.
+//
+//   npx --yes @gotcos/glasses-server@latest --hooks install [--dry-run] [--port 3141]
+//   npx --yes @gotcos/glasses-server@latest --hooks status
+//   npx --yes @gotcos/glasses-server@latest --hooks uninstall [--dry-run]
+//
+// Prints one JSON document. Exit 0 on success, 2 on a refusal (unparseable or symlinked
+// settings, a missing packaged script), 64 on a bad argument. Never prints the token.
+
+import { hookStatus, installClaudeHooks, uninstallClaudeHooks } from '../lib/claude-hooks-installer.js'
+import { sessionHooksEnabled } from '../lib/session-hooks-runtime.js'
+
+const args = process.argv.slice(2)
+const action = args.find(a => !a.startsWith('--'))
+const dryRun = args.includes('--dry-run')
+const portIndex = args.indexOf('--port')
+const port = portIndex >= 0 ? Number(args[portIndex + 1]) : Number(process.env.PORT ?? 3141)
+const deskIndex = args.indexOf('--desk-idle-s')
+const deskIdleSeconds = deskIndex >= 0 ? Number(args[deskIndex + 1]) : Number(process.env.COS_PERMISSION_BROKER_DESK_IDLE_S ?? 90)
+
+function print(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2))
+}
+
+// `serverApplies` says whether the running server would READ the spool into rows: the
+// hooks can be installed while the feature is off (COS_CLAUDE_SESSIONS_ENABLED unset),
+// and a status that said only "installed" would hide that.
+const serverApplies = sessionHooksEnabled()
+const flagsNote = serverApplies ? undefined : 'Rows change only when the server runs with COS_CLAUDE_SESSIONS_ENABLED=1 (or COS_SESSION_HOOKS=1).'
+
+if (action === 'status') {
+  print({ action, serverApplies, ...(flagsNote ? { note: flagsNote } : {}), ...hookStatus() })
+  process.exit(0)
+}
+if (action === 'install') {
+  if (!Number.isFinite(port) || port <= 0) { console.error('Bad --port'); process.exit(64) }
+  const result = installClaudeHooks({ port, deskIdleSeconds: Number.isFinite(deskIdleSeconds) ? deskIdleSeconds : 90, dryRun })
+  print({ action, dryRun, serverApplies, ...(flagsNote ? { note: flagsNote } : {}), ...result })
+  process.exit(result.ok ? 0 : 2)
+}
+if (action === 'uninstall') {
+  const result = uninstallClaudeHooks({ dryRun })
+  print({ action, dryRun, ...result })
+  process.exit(result.ok ? 0 : 2)
+}
+console.error('Usage: --hooks install|status|uninstall [--dry-run] [--port N] [--desk-idle-s N]')
+process.exit(64)

package/server/lib/__fixtures__/query-jobs-6.43.3/2099-01-01.jsonl

@@ -1,2 +0,0 @@
-{"schemaVersion":1,"recordId":"02b09947-ed7d-47ef-99c5-4985af3ec924","partitionDay":"2099-01-01","persistedAt":"2099-01-01T12:00:00.000Z","bootId":"boot-6-43-3-fixture","jobId":"43b397bd-dd67-4312-9a5c-4c5d4b246f1d","clientJobId":"11111111-1111-4111-8111-111111111111","generation":2,"turnId":"a456fd1d-1e82-4b2d-8a20-5d34681201fd","requestFingerprint":"024966024134bf0d46090335da03a732a7fb7eaea161b1fd07dc4c5b9d536e95","eventSeq":1,"type":"accepted","status":"accepted","request":{"clientJobId":"11111111-1111-4111-8111-111111111111","generation":2,"query":"written by 6.43.3","sessionId":"session-6-43-3","model":"opus","effort":"high","cursorExecutionMode":"ask","messageEra":"era1","globalMsgNum":78,"reference":{"query":"earlier q","response":"earlier a"},"handoffCode":"ABCD","handoffLatest":true,"clientQueueItemId":"q1","attachmentIds":[],"attachmentRefs":[],"activityToolMode":"status"},"patch":{},"eventData":{"requestFingerprint":"024966024134bf0d46090335da03a732a7fb7eaea161b1fd07dc4c5b9d536e95"}}
-{"schemaVersion":1,"recordId":"a1145a40-2ced-4da3-9cf7-76d84cffc946","partitionDay":"2099-01-01","persistedAt":"2099-01-01T12:00:00.000Z","bootId":"boot-6-43-3-fixture","jobId":"64c5b502-13f2-4871-b6c4-007b91be2414","clientJobId":"22222222-2222-4222-8222-222222222222","generation":1,"turnId":"843e633f-0f92-4fe3-b2a1-9dc683715791","requestFingerprint":"91edfdeeb088e9fb3b1ffab4202bca02d3e7a23674d8b54dd51a50ce9adbf638","eventSeq":1,"type":"accepted","status":"accepted","request":{"clientJobId":"22222222-2222-4222-8222-222222222222","generation":1,"query":"minimal by 6.43.3","sessionId":"session-6-43-3-min","attachmentIds":[],"attachmentRefs":[],"activityToolMode":"status"},"patch":{},"eventData":{"requestFingerprint":"91edfdeeb088e9fb3b1ffab4202bca02d3e7a23674d8b54dd51a50ce9adbf638"}}