@gotcos/glasses-server 6.47.0 → 6.48.1

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

@@ -0,0 +1,389 @@
+// The signal store: what the hooks have said about each Claude session, reduced to
+// one record per full session id.
+//
+// POSITIVE SIGNALS ONLY. Before 6.48.0 every state on a session row was inferred: a
+// registry pid that answers signal 0, a transcript mtime inside a window, a tool_use
+// block with no result behind it. This store holds what the engine itself announced
+// through its hooks (session started, prompt submitted, permission wanted, turn stopped,
+// session ended), and `session-state-derive.ts` ranks it above every inference.
+//
+// The reducer is PURE (`applyHookEvent`), so a recorded sequence of envelopes replays
+// into a deterministic record and the fixtures under `__fixtures__/session-hooks-6.48.0`
+// are the specification. Three rules that came out of the validation rounds:
+//
+//  1. A `waiting` entry clears only on RESOLUTION EVIDENCE for that request: the
+//     matching PostToolUse/PostToolUseFailure/PermissionDenied (same tool name + input
+//     fingerprint), or a turn boundary (Stop, StopFailure, UserPromptSubmit, SessionEnd, a
+//     non-compact SessionStart), or the broker's own decision. A parallel auto-allowed
+//     Read or a sub-agent's tool must not clear a real prompt. The deriver adds two more
+//     clearers it can see and this store cannot: a registry status that moved after the
+//     wait, and transcript activity newer than the wait.
+//  2. A COS-spawned Continue child (`claude -p --resume <id>`) shares the Desktop tab's
+//     session id and fires its own SessionStart/Stop/SessionEnd. Events whose spooled
+//     ppid is a COS spawn are recorded as `child*` counters and never touch the phase.
+//  3. `ended` is recorded here but RANKED in the deriver, which also sees the registry:
+//     an ended signal with an alive registry record is a child that ended, not the tab.
+
+import type { HookEnvelope, HookEventName } from './session-hook-events.js'
+import { clipText, toolFingerprint, toolTarget } from './session-hook-events.js'
+import { isKeepWarmSessionTitle } from './agent-session-store.js'
+
+export type WaitingKind = 'permission' | 'question' | 'plan' | 'mcp_input'
+
+export interface WaitingSignal {
+  kind: WaitingKind
+  /** "Bash git push", "Use the API error text in the form?", "" */
+  detail: string
+  toolName: string
+  /** sha256(tool_name + canonical tool_input); '' when the event carried no tool. */
+  fingerprint: string
+  since: number
+  /** The broker's minted id when a permission request is pending there. */
+  requestId: string | null
+}
+
+export interface FailureSignal {
+  kind: string
+  at: number
+}
+
+export interface SessionSignal {
+  sessionId: string
+  firstSeenAt: number
+  lastEventAt: number
+  lastEvent: HookEventName
+  cwd: string | null
+  transcriptPath: string | null
+  permissionMode: string | null
+  model: string | null
+  /** A prompt was submitted and no Stop/StopFailure/SessionEnd has closed it. */
+  turnOpen: boolean
+  turnStartedAt: number | null
+  promptId: string | null
+  /** 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
+  lastReply: string
+  lastTool: string | null
+  lastToolAt: number | null
+  subagentsOpen: number
+  ended: { at: number; reason: string } | null
+  /** The prompt prefix Control already suppresses as a readiness check. */
+  keepWarm: boolean
+  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
+}
+
+export interface ReducerContext {
+  /** Is this pid (or its parent) a process COS spawned itself? Consulted only when the
+   *  envelope was not already classified at ingest (`child`). */
+  isCosSpawnedPid: (pid: number | null) => boolean
+}
+
+/** The tool fields the reducer reads: the live payload's, or the ledger's projection on replay. */
+function toolFacts(p: Record<string, unknown>): { name: string; target: string; fingerprint: string } {
+  const name = typeof p.tool_name === 'string' ? p.tool_name : ''
+  const projectedTarget = typeof p.tool_target === 'string' ? p.tool_target : null
+  const projectedFingerprint = typeof p.tool_fingerprint === 'string' ? p.tool_fingerprint : null
+  return {
+    name,
+    target: projectedTarget ?? toolTarget(p.tool_input),
+    fingerprint: projectedFingerprint ?? toolFingerprint(name, p.tool_input ?? null),
+  }
+}
+
+function fresh(env: HookEnvelope): SessionSignal {
+  return {
+    sessionId: env.sessionId,
+    firstSeenAt: env.ts,
+    lastEventAt: env.ts,
+    lastEvent: env.event,
+    cwd: null,
+    transcriptPath: null,
+    permissionMode: null,
+    model: null,
+    turnOpen: false,
+    turnStartedAt: null,
+    promptId: null,
+    stopAt: null,
+    waiting: null,
+    failure: null,
+    lastReply: '',
+    lastTool: null,
+    lastToolAt: null,
+    subagentsOpen: 0,
+    ended: null,
+    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' }
+
+function resolvesWaiting(waiting: WaitingSignal, event: HookEventName, toolName: string, fingerprint: string): boolean {
+  if (waiting.fingerprint && waiting.fingerprint === fingerprint) return true
+  // Question/plan tools carry no meaningful input to fingerprint; the tool name is the key.
+  if (waiting.kind !== 'permission') return waiting.toolName === toolName
+  // A permission dialog is one at a time (canary 11: hooks run serially), and only a
+  // denied PROMPT fires PermissionDenied, so a denial naming the waiting tool is that
+  // prompt's denial even when the dialog rewrote the input. PostToolUse of the same name
+  // is not: a parallel auto-allowed Bash must not clear a prompt that still stands.
+  return event === 'PermissionDenied' && waiting.toolName === toolName
+}
+
+/**
+ * Apply one envelope. Returns a NEW record; the previous one is never mutated, so a
+ * subscriber holding the old value sees a consistent snapshot.
+ */
+export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelope, ctx: ReducerContext, child?: boolean): SessionSignal {
+  const base = prev ? { ...prev } : fresh(env)
+  const p = env.payload
+  const common = {
+    cwd: str(p.cwd) ?? base.cwd,
+    transcriptPath: str(p.transcript_path) ?? base.transcriptPath,
+    permissionMode: str(p.permission_mode) ?? base.permissionMode,
+  }
+
+  // Rule 2: a COS-spawned child on this session id is counted, never applied. The verdict
+  // is taken at ingest (and remembered on the ledger row) because the spawn ledger forgets
+  // a pid the moment the child exits.
+  if (child ?? ctx.isCosSpawnedPid(env.ppid)) {
+    return { ...base, ...common, childEvents: base.childEvents + 1 }
+  }
+
+  const next: SessionSignal = { ...base, ...common, lastEventAt: Math.max(base.lastEventAt, env.ts), lastEvent: env.event }
+
+  switch (env.event) {
+    case 'SessionStart': {
+      const source = str(p.source) ?? 'startup'
+      next.model = str(p.model) ?? next.model
+      if (source === 'compact') { next.compactions += 1; return next }
+      // startup | resume | clear | fork: a fresh conversation surface, nothing in flight.
+      return { ...next, turnOpen: false, turnStartedAt: null, waiting: null, failure: null, ended: null, subagentsOpen: 0 }
+    }
+    case 'UserPromptSubmit': {
+      const prompt = clipText(p.prompt)
+      return {
+        ...next,
+        turnOpen: true,
+        turnStartedAt: env.ts,
+        promptId: str(p.prompt_id),
+        waiting: null,
+        failure: null,
+        // The same predicate the session list uses to hide readiness checks.
+        keepWarm: prompt.length > 0 && isKeepWarmSessionTitle(prompt),
+      }
+    }
+    case 'PreToolUse': {
+      const tool = toolFacts(p)
+      const kind = TOOL_WAITING[tool.name]
+      if (kind) {
+        return {
+          ...next,
+          turnOpen: true,
+          waiting: { kind, detail: tool.target, toolName: tool.name, fingerprint: tool.fingerprint, since: env.ts, requestId: null },
+        }
+      }
+      return { ...next, ...turnOpenedByTool(next, p, env.ts), lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
+    }
+    case 'PermissionRequest': {
+      const tool = toolFacts(p)
+      return {
+        ...next,
+        turnOpen: true,
+        waiting: {
+          kind: 'permission',
+          detail: tool.target ? `${tool.name} ${tool.target}` : tool.name,
+          toolName: tool.name,
+          fingerprint: tool.fingerprint,
+          since: env.ts,
+          requestId: null,
+        },
+      }
+    }
+    case 'PermissionDenied':
+    case 'PostToolUse':
+    case 'PostToolUseFailure': {
+      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, ...turnOpenedByTool(next, p, env.ts), waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
+    }
+    case 'Notification': {
+      const type = str(p.notification_type) ?? ''
+      if (type === 'idle_prompt') return { ...next, turnOpen: false }
+      if (next.waiting) return next // a dialog already owns the attention; never downgrade its kind
+      const message = clipText(p.message, 120)
+      const kind: WaitingKind | null =
+        type === 'permission_prompt' ? 'permission'
+        : type === 'agent_needs_input' ? 'question'
+        : type === 'elicitation_dialog' ? 'mcp_input'
+        : null
+      if (!kind) return next
+      return { ...next, turnOpen: true, waiting: { kind, detail: message, toolName: '', fingerprint: '', since: env.ts, requestId: null } }
+    }
+    case 'Stop':
+      return {
+        ...next,
+        turnOpen: false,
+        stopAt: env.ts,
+        waiting: null,
+        lastReply: clipText(p.last_assistant_message) || next.lastReply,
+      }
+    case 'StopFailure':
+      return {
+        ...next,
+        turnOpen: false,
+        waiting: null,
+        failure: { kind: str(p.matcher) ?? str(p.error_type) ?? (clipText(p.error, 60) || 'unknown'), at: env.ts },
+      }
+    case 'SubagentStart':
+      return { ...next, subagentsOpen: next.subagentsOpen + 1 }
+    case 'SubagentStop':
+      return { ...next, subagentsOpen: Math.max(0, next.subagentsOpen - 1) }
+    case 'PostCompact':
+      return { ...next, compactions: next.compactions + 1 }
+    case 'PostModelSwitch':
+      return { ...next, model: str(p.to_model) ?? next.model }
+    case 'SessionEnd':
+      return { ...next, turnOpen: false, waiting: null, ended: { at: env.ts, reason: str(p.reason) ?? 'other' } }
+  }
+}
+
+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
+/** A record with no event at all for this long is a tab that died without a SessionEnd. */
+export const SIGNAL_PRUNE_SILENT_MS = 24 * 60 * 60_000
+
+export class SessionSignalStore {
+  private readonly signals = new Map<string, SessionSignal>()
+  private readonly listeners = new Set<SignalListener>()
+  private readonly ctx: ReducerContext
+
+  constructor(ctx: ReducerContext) {
+    this.ctx = ctx
+  }
+
+  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, 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 {
+    const current = this.signals.get(sessionId)
+    if (!current?.waiting || current.waiting.kind !== 'permission') return
+    this.signals.set(sessionId, { ...current, waiting: { ...current.waiting, requestId } })
+  }
+
+  /** RESERVED FOR 6.48.2 (the permission broker); no caller in 6.48.0. The broker decided
+   *  (allow or deny): that is resolution evidence. */
+  resolveWaiting(sessionId: string): void {
+    const current = this.signals.get(sessionId)
+    if (!current?.waiting) return
+    this.signals.set(sessionId, { ...current, waiting: null })
+  }
+
+  get(sessionId: string): SessionSignal | undefined {
+    return this.signals.get(sessionId.toLowerCase())
+  }
+
+  /** Eight-char prefix lookup for the registry's short ids. Two matches means no answer. */
+  getByPrefix(prefix: string): SessionSignal | undefined {
+    const needle = prefix.toLowerCase()
+    let found: SessionSignal | undefined
+    for (const [id, signal] of this.signals) {
+      if (!id.startsWith(needle)) continue
+      if (found) return undefined
+      found = signal
+    }
+    return found
+  }
+
+  subscribe(listener: SignalListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** Drop records that ended long ago, and records silent for a day (a tab that died with no SessionEnd). */
+  prune(nowMs = Date.now()): number {
+    let dropped = 0
+    for (const [id, signal] of this.signals) {
+      const endedLongAgo = !!signal.ended && !signal.turnOpen && nowMs - signal.ended.at > SIGNAL_PRUNE_AFTER_END_MS
+      const silentForADay = nowMs - signal.lastEventAt > SIGNAL_PRUNE_SILENT_MS
+      if (endedLongAgo || silentForADay) {
+        this.signals.delete(id)
+        dropped++
+      }
+    }
+    return dropped
+  }
+
+  size(): number {
+    return this.signals.size
+  }
+
+  /** Every record, newest event first. A copy: callers cannot reach the map. */
+  snapshot(): SessionSignal[] {
+    return [...this.signals.values()].sort((a, b) => b.lastEventAt - a.lastEventAt)
+  }
+
+  newestEventAt(): number | null {
+    let newest: number | null = null
+    for (const signal of this.signals.values()) {
+      if (newest === null || signal.lastEventAt > newest) newest = signal.lastEventAt
+    }
+    return newest
+  }
+
+  __resetForTests(): void {
+    this.signals.clear()
+    this.listeners.clear()
+  }
+}

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

@@ -0,0 +1,249 @@
+// 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
+  /**
+   * 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`. */
+  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 }
+
+  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).
+  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 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 {}
+  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 } : {}),
+  }
+}