@gotcos/glasses-server 6.46.1 → 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/lib/voice-evidence-guard.ts

@@ -0,0 +1,87 @@
+/**
+ * What may be used as VOICE EVIDENCE (6.47.0, WS5).
+ *
+ * A voice profile is built from audio this Mac captured. An imported meeting has
+ * no audio at all — Fireflies sends text — and a derived record (a merge, or one
+ * piece of a split) is a FUNCTION of other records rather than a recording. Its
+ * speaker names came from the vendor's own diarization or from a voice match
+ * suggestion, so training a profile on either would fold a cloud label back into
+ * the local identity store and then present it as local evidence. That is the
+ * one loop the speaker system must never close (CLAUDE.md: "Cloud speaker names
+ * training voice profiles (never)").
+ *
+ * REFUSES BY ID KIND ONLY. The rule is a property of the identifier in hand:
+ * an `imported:` or `blended:` record id, or an `.import.json` / `.derived.json`
+ * evidence path. It is NOT a property of the underlying meeting. A G2 session
+ * that happens to have a merged record derived from it is still a real capture
+ * with real audio, and relabelling it is exactly how its profile gets better —
+ * so this guard must never refuse a G2 session merely because derived records
+ * exist. The plan states that explicitly, and the execution gate pins it.
+ *
+ * PURE. No filesystem, no lookups: a guard that has to read the disk to decide
+ * fails open the moment the disk is slow, and this one runs before every voice
+ * mutation.
+ */
+
+/** A record id that names an imported or derived record rather than a capture. */
+export const IMPORTED_EVIDENCE_ID_PATTERN = /^(imported|blended):/
+
+/** The two sidecars of the imported library. Never chunk audio, never `.g2-chunks.json`. */
+export const IMPORTED_EVIDENCE_PATH_PATTERN = /\.(?:import|derived)\.json$/i
+
+export type VoiceEvidenceReason = 'imported_read_only' | 'blended_derived_record'
+
+export interface VoiceEvidenceRefusal {
+  status: 409
+  body: {
+    error: string
+    reason: VoiceEvidenceReason
+    /** The exact value that was refused, so a caller can say which input failed. */
+    source: string
+  }
+}
+
+/** The kind of an id, or null when it names neither. */
+export function importedEvidenceKind(value: unknown): 'imported' | 'blended' | null {
+  if (typeof value !== 'string') return null
+  const id = value.match(IMPORTED_EVIDENCE_ID_PATTERN)
+  if (id) return id[1] as 'imported' | 'blended'
+  // A path is only ever evidence of a derived record, so it refuses as `blended`
+  // when it is a `.derived.json` and as `imported` when it is an `.import.json`.
+  if (IMPORTED_EVIDENCE_PATH_PATTERN.test(value)) {
+    return /\.derived\.json$/i.test(value) ? 'blended' : 'imported'
+  }
+  return null
+}
+
+export function isImportedVoiceEvidence(value: unknown): boolean {
+  return importedEvidenceKind(value) !== null
+}
+
+/**
+ * Refuse the first value that names an imported or derived record.
+ *
+ * Returns null when every value is acceptable, so a caller reads as
+ * `const refusal = assertVoiceEvidenceSource([...]); if (refusal) ...`.
+ */
+export function assertVoiceEvidenceSource(values: ReadonlyArray<unknown>): VoiceEvidenceRefusal | null {
+  for (const value of values) {
+    const kind = importedEvidenceKind(value)
+    if (!kind) continue
+    return {
+      status: 409,
+      body: kind === 'imported'
+        ? {
+          error: 'Imported meetings carry no audio, so they cannot train or correct a voice',
+          reason: 'imported_read_only',
+          source: String(value),
+        }
+        : {
+          error: 'This record was derived from other meetings. Open the recording it came from',
+          reason: 'blended_derived_record',
+          source: String(value),
+        },
+    }
+  }
+  return null
+}

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/fireflies-key.ts

@@ -0,0 +1,102 @@
+// Fireflies key endpoints.
+//
+//   POST   /api/fireflies-key/set     store the key, then check it
+//   GET    /api/fireflies-key/status  configured, source, savedAt, validatedAt, lastCheck
+//   DELETE /api/fireflies-key         remove the stored key
+//   POST   /api/fireflies-key/check   check now (this is the user-initiated one)
+//
+// The key is never in a response, and never in a log line. `status` reads the
+// remembered check rather than calling the vendor, so a settings pane that
+// polls it costs nothing.
+
+import { Router } from 'express'
+import { FirefliesKeyError, getFirefliesClient, getFirefliesKeyStore, type FirefliesKeyStore } from '../lib/fireflies-key.js'
+import { getFirefliesImporter } from '../lib/meeting-import.js'
+import type { FirefliesClient, FirefliesKeyCheck } from '../lib/fireflies-client.js'
+
+export interface FirefliesKeyRouterDeps {
+  store: () => FirefliesKeyStore
+  client: () => FirefliesClient
+  /** Told whenever the stored key changes, so a sticky invalid_key can clear. */
+  onKeyChanged?: (event: { configured: boolean }) => void
+  /** Told the result of every check, for the same reason. */
+  onKeyChecked?: (check: FirefliesKeyCheck) => void
+}
+
+export function createFirefliesKeyRouter(deps: FirefliesKeyRouterDeps): Router {
+  const router = Router()
+
+  const runCheck = async (): Promise<FirefliesKeyCheck> => {
+    const client = deps.client()
+    const check = await client.checkKey({ userInitiated: true })
+    deps.store().recordCheck(check)
+    deps.onKeyChecked?.(check)
+    return check
+  }
+
+  router.post('/fireflies-key/set', async (req, res) => {
+    try {
+      const store = deps.store()
+      const saved = store.save(req.body?.key)
+      deps.client().forgetKeyCheck()
+      deps.onKeyChanged?.({ configured: true })
+      const check = await runCheck()
+      res.json({ ok: true, savedAt: saved.savedAt, status: store.status(), check })
+    } catch (error) {
+      if (error instanceof FirefliesKeyError) {
+        return res.status(error.status).json({ error: { code: error.code, message: error.message } })
+      }
+      console.error('[fireflies-key] save failed')
+      res.status(500).json({ error: { code: 'fireflies_key_save_failed', message: 'The key could not be saved.' } })
+    }
+  })
+
+  router.get('/fireflies-key/status', (_req, res) => {
+    try {
+      const status = deps.store().status()
+      const cached = deps.client().cachedKeyCheck()
+      res.json({ ...status, ...(cached ? { lastCheck: { ...cached, cached: undefined } } : {}) })
+    } catch (error) {
+      console.error('[fireflies-key] status failed')
+      res.status(500).json({ error: { code: 'fireflies_key_unavailable', message: 'The key status could not be read.' } })
+    }
+  })
+
+  router.delete('/fireflies-key', (_req, res) => {
+    try {
+      const store = deps.store()
+      store.delete()
+      deps.client().forgetKeyCheck()
+      deps.onKeyChanged?.({ configured: store.status().configured })
+      res.json({ ok: true, status: store.status() })
+    } catch (error) {
+      if (error instanceof FirefliesKeyError) {
+        return res.status(error.status).json({ error: { code: error.code, message: error.message } })
+      }
+      console.error('[fireflies-key] delete failed')
+      res.status(500).json({ error: { code: 'fireflies_key_delete_failed', message: 'The key could not be removed.' } })
+    }
+  })
+
+  router.post('/fireflies-key/check', async (_req, res) => {
+    try {
+      res.json(await runCheck())
+    } catch (error) {
+      console.error('[fireflies-key] check failed')
+      res.status(500).json({ error: { code: 'fireflies_key_check_failed', message: 'The key could not be checked.' } })
+    }
+  })
+
+  return router
+}
+
+// A sticky invalid_key is what stops the importer from spending a budget on a
+// key the vendor already refused, so the two things that can make it wrong - a
+// new key, and a check that now succeeds - have to reach the importer from
+// here. Without this the only way out of the sticky state is a restart.
+export const firefliesKeyRouter = createFirefliesKeyRouter({
+  store: getFirefliesKeyStore,
+  client: getFirefliesClient,
+  onKeyChanged: () => getFirefliesImporter().onKeyChanged(),
+  onKeyChecked: check => getFirefliesImporter().onKeyChecked(check),
+})

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(),