@gotcos/glasses-server 6.99.33 → 7.0.18

package/server/routes/live-events.ts

@@ -0,0 +1,334 @@
+// GET /api/events (7.0.1 live state). The contract is docs/live-events-contract.md; the hub is lib/live-events.ts.
+//
+// ONE stream per open Control Web page. It tells the page when the server's own session state changes (a session
+// opens, works, waits, idles or ends; a reply lands; a question opens or closes; the queue moves), so the pet, the
+// session rows, Today's counts and the running clocks stop drifting between polls.
+//
+// TRANSPORT, copied from the per-session stream that already works through Tailscale Serve and the https listener
+// (agent-session-stream.ts): the same four headers, `flushHeaders()`, `retry:` first, one JSON object per `data:`
+// line with no named events and no comment keepalives, a heartbeat every 15 s, and every refusal BEFORE the headers
+// as ordinary JSON so a client sees a failed request, never a socket that never speaks.
+//
+// AUTH is the global /api gate (token header or the Control Web cookie), exactly as for `/stream`. Nothing here
+// re-checks it, so nothing here can drift from it.
+//
+// SWITCH: COS_WEB_LIVE_EVENTS. Absent means on. `0` registers no route at all (404), which is also what a client
+// sees from a server older than 7.0.1, so both take the same polling path.
+
+import { streamSignInHolds } from '../lib/api-auth.js'
+import { Router, type Request, type Response } from 'express'
+import { readSwitch } from '../lib/env-switch.js'
+import {
+  LIVE_ENDED_LINGER_MS,
+  LiveEventsHub,
+  parseLiveCursor,
+  type LiveFrame,
+  type LiveProvider,
+  type LiveQuestionReading,
+  type LiveQueueReading,
+  type LiveSessionReading,
+  type LiveSources,
+  type LiveState,
+} from '../lib/live-events.js'
+import { claudeSessionsDir, claudeSessionsEnabled, readClaudePeerRecords, registryFacts } from './claude-sessions.js'
+import type { ClaudePeerRecord } from '../lib/claude-session-registry.js'
+import { deriveForRow, sessionHooksEnabled, sessionSignalStore, signalFor } from '../lib/session-hooks-runtime.js'
+import type { SessionSignal } from '../lib/session-signal-store.js'
+import { isAttachedTurnActive, sessionStreamKey } from '../lib/session-stream-bus.js'
+import { runningHintFor } from './agent-sessions.js'
+import { queuedThreadKeys, readQueue } from '../lib/thread-turn-queue-store.js'
+import type { PermissionBroker } from '../lib/permission-broker.js'
+
+/** Inside a 30 s client deadline with room for one lost write; the same cadence as `/stream`. */
+export const LIVE_EVENTS_HEARTBEAT_MS = 15_000
+/**
+ * Open streams per server. A phone, a laptop and a few tabs each hold one; 16 is room plus a ceiling. At the ceiling the
+ * OLDEST stream is closed to make room (ghost review W5): a peer that vanished behind Tailscale holds its slot until TCP
+ * gives up, and the newest request is usually the person who just opened the page. A closed live client reconnects
+ * with its last id.
+ */
+export const LIVE_EVENTS_MAX_STREAMS = 16
+/** Unsent bytes past this close the stream: a slow client is dropped, never buffered without limit. */
+export const LIVE_EVENTS_MAX_BUFFER_BYTES = 256 * 1024
+/** A hook-only session with no event for this long (and no open turn or wait) is not open. The deriver's open-turn ceiling. */
+export const LIVE_SIGNAL_OPEN_WINDOW_MS = 30 * 60_000
+
+/** Absent means on; `0` (or false/off) means no route. Read at server start. */
+export function liveEventsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readSwitch(env.COS_WEB_LIVE_EVENTS, true)
+}
+
+function newestOf(...values: Array<number | null | undefined>): number | null {
+  let out: number | null = null
+  for (const v of values) if (typeof v === 'number' && Number.isFinite(v) && v > 0 && (out === null || v > out)) out = v
+  return out
+}
+
+/**
+ * One session's reading, from the same derivation the list and the per-session stream use (deriveForRow, then
+ * runningHintFor), so `working` here is the list's `running_active` and the pet never disagrees with the rows.
+ *
+ * Exported for tests. Pure apart from the deriver's own reads of the signal store (remember: false, so it never
+ * touches the row readers' two-scan memory).
+ */
+export function readingFor(provider: LiveProvider, sessionId: string, peer: ClaudePeerRecord | undefined, signal: SessionSignal | undefined, now: number): LiveSessionReading {
+  const id = sessionId.toLowerCase()
+  const derived = deriveForRow({
+    sessionId: id,
+    registry: peer ? registryFacts(peer) : undefined,
+    now,
+    remember: false,
+    attachedTurn: isAttachedTurnActive(sessionStreamKey(provider, id)),
+  })
+  const hookClock = signal ? newestOf(signal.lastEventAt, signal.lastThought?.at) : null
+  let state: LiveState
+  let source: 'hook' | 'registry' = derived?.state_source === 'hook' ? 'hook' : 'registry'
+  if (!derived) {
+    // Hooks off: the registry's own status is all there is.
+    source = 'registry'
+    state = peer?.status === 'busy' ? 'working' : peer?.status === 'waiting' ? 'waiting' : 'idle'
+  } else if (derived.agent_state === 'ended') {
+    state = 'ended'
+  } else {
+    const hint = runningHintFor(provider, derived, derived.state_source === 'hook' ? hookClock : null, now, null)
+    if (hint?.active) state = 'working'
+    // A registry `busy` with no hooks: the list reads its transcript clock here; the registry's word is the closest
+    // thing this stream has without a file read, and a busy tab writes its transcript continuously.
+    else if (!hint && derived.agent_state === 'running' && derived.state_source !== 'hook') state = 'working'
+    else if (derived.agent_state === 'waiting') state = 'waiting'
+    else state = 'idle'
+  }
+  const registryTurn = peer && (peer.status === 'busy' || peer.status === 'waiting') ? peer.statusUpdatedAt : null
+  return {
+    provider,
+    sessionId: id,
+    state,
+    startedAt: newestOf(peer?.startedAt) ?? newestOf(signal?.firstSeenAt),
+    turnStartedAt: signal?.turnOpen && signal.turnStartedAt ? signal.turnStartedAt : registryTurn,
+    updatedAt: newestOf(hookClock, peer?.statusUpdatedAt),
+    source,
+    failed: derived?.agent_state === 'failed',
+  }
+}
+
+/**
+ * Which sessions are open, from the two things the server holds without walking transcripts: the Claude registry
+ * (alive records) and the hook signal store. Exported for tests with injected inputs.
+ */
+export function liveReadings(input: { peers: ClaudePeerRecord[] | null; signals: SessionSignal[]; now: number; signalFor: (id: string) => SessionSignal | undefined; reading?: typeof readingFor }): LiveSessionReading[] {
+  const reading = input.reading ?? readingFor
+  const out: LiveSessionReading[] = []
+  const included = new Set<string>()
+  const registryKnown = input.peers !== null
+  for (const peer of input.peers ?? []) {
+    if (!peer.alive) continue
+    const id = peer.sessionId.toLowerCase()
+    const key = `claude:${id}`
+    if (included.has(key)) continue
+    included.add(key)
+    out.push(reading('claude', id, peer, input.signalFor(id), input.now))
+  }
+  for (const signal of input.signals) {
+    if (signal.keepWarm) continue
+    const provider: LiveProvider = signal.provider === 'codex' || signal.provider === 'cursor' ? signal.provider : 'claude'
+    const id = signal.sessionId.toLowerCase()
+    const key = `${provider}:${id}`
+    if (included.has(key)) continue
+    const endedRecently = !!signal.ended && input.now - signal.ended.at <= LIVE_ENDED_LINGER_MS
+    const open = !signal.ended && (signal.turnOpen || !!signal.waiting || input.now - signal.lastEventAt <= LIVE_SIGNAL_OPEN_WINDOW_MS)
+    // A Claude tab is open while its registry record is alive. With the registry readable and no alive record, a
+    // hook record that never said SessionEnd is a tab that died (or a COS child that finished): not open.
+    if (provider === 'claude' && registryKnown && !endedRecently) continue
+    if (!open && !endedRecently) continue
+    included.add(key)
+    const r = reading(provider, id, undefined, signal, input.now)
+    out.push(endedRecently && r.state !== 'ended' ? { ...r, state: 'ended', turnStartedAt: null } : r)
+  }
+  return out
+}
+
+/**
+ * The server's own sources. `broker` is read lazily so the route can mount before the broker exists. `readPeers` is a
+ * test seam for the registry read.
+ */
+export function realLiveSources(deps: { broker: () => PermissionBroker | null; readPeers?: () => Promise<ClaudePeerRecord[]> }): LiveSources {
+  const readPeers = deps.readPeers ?? (() => readClaudePeerRecords(claudeSessionsDir(), undefined, undefined, true))
+  // The registry as last read: a hook push rebuilds against it instead of reading the folder (ghost review W4).
+  let last: { peers: ClaudePeerRecord[] | null; degraded: boolean } | null = null
+  return {
+    async sessions(now, opts) {
+      let peers: ClaudePeerRecord[] | null = null
+      let degraded = false
+      if (opts?.hooksOnly && last) {
+        peers = last.peers
+        degraded = last.degraded
+      } else if (claudeSessionsEnabled()) {
+        // A folder that cannot be read throws: degraded, and the hub keeps its last good model rather than marking
+        // every tab ended (ghost review note 8).
+        try { peers = await readPeers() } catch { peers = null; degraded = true }
+        last = { peers, degraded }
+      } else {
+        last = { peers: null, degraded: false }
+      }
+      const signals = sessionHooksEnabled() ? sessionSignalStore.snapshot() : []
+      return { sessions: liveReadings({ peers, signals, now, signalFor }), degraded }
+    },
+    questions() {
+      const broker = deps.broker()
+      if (!broker) return []
+      return broker.list().map((q): LiveQuestionReading => ({ provider: q.provider, sessionId: q.sessionId, kind: q.kind === 'approval' ? 'approval' : 'question' }))
+    },
+    queue(now) {
+      const rows: LiveQueueReading[] = []
+      for (const { provider, threadId } of queuedThreadKeys()) {
+        if (provider !== 'claude' && provider !== 'codex' && provider !== 'cursor') continue
+        const count = readQueue(provider, threadId, now).filter(t => t.status === 'waiting').length
+        if (count > 0) rows.push({ provider, sessionId: threadId, count })
+      }
+      return rows
+    },
+    subscribe(listener) {
+      if (!sessionHooksEnabled()) return () => {}
+      return sessionSignalStore.subscribe((signal, env, child) => {
+        listener({ sessionId: signal.sessionId, turnEnded: !child && (env.event === 'Stop' || env.event === 'StopFailure') })
+      })
+    },
+  }
+}
+
+export interface LiveEventsRouterDeps {
+  hub: LiveEventsHub
+  enabled?: boolean
+  maxStreams?: number
+  heartbeatMs?: number
+  maxBufferBytes?: number
+  log?: (line: string) => void
+}
+
+/**
+ * The stream frame on the wire: an `id:` line on every frame a resume can start after (the state frames, and the
+ * snapshot, whose seq is the state it describes), then one `data:` line. Heartbeat and resume carry none: they repeat
+ * the newest seq, and an id on them would only restate the last one.
+ *
+ * The snapshot's id means the browser's OWN EventSource reconnect resumes from the snapshot instead of asking for a
+ * second whole snapshot when nothing changed in between.
+ */
+export function frameText(frame: LiveFrame): string {
+  const remembered = frame.kind === 'snapshot' || frame.kind === 'session' || frame.kind === 'session.removed' || frame.kind === 'questions' || frame.kind === 'queue'
+  return `${remembered ? `id: ${frame.epoch}.${frame.seq}\n` : ''}data: ${JSON.stringify(frame)}\n\n`
+}
+
+export function createLiveEventsRouter(deps: LiveEventsRouterDeps): Router {
+  const router = Router()
+  if (deps.enabled === false) return router
+  router.get('/events', liveEventsHandler(deps))
+  return router
+}
+
+/** The handler, exported so the backpressure and heartbeat guards can be driven with a fake response. */
+export function liveEventsHandler(deps: LiveEventsRouterDeps): (req: Request, res: Response) => Promise<void> {
+  const maxStreams = deps.maxStreams ?? LIVE_EVENTS_MAX_STREAMS
+  const heartbeatMs = deps.heartbeatMs ?? LIVE_EVENTS_HEARTBEAT_MS
+  const maxBuffer = deps.maxBufferBytes ?? LIVE_EVENTS_MAX_BUFFER_BYTES
+  const log = deps.log ?? (line => console.log(line))
+  let open = 0
+  /** Each open stream's teardown, oldest first (a Map keeps insertion order). */
+  const streams = new Map<number, (why: string) => void>()
+  let nextStream = 0
+
+  return async (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    if (open >= maxStreams) {
+      const oldest = streams.entries().next().value as [number, (why: string) => void] | undefined
+      if (oldest) {
+        log(`[live-events] stream cap ${maxStreams} reached: closing the oldest stream to admit a new one (open ${open})`)
+        oldest[1]('evicted')
+      }
+      if (open >= maxStreams) {
+        log(`[live-events] stream cap ${maxStreams} reached: refused a new stream, none could be closed (open ${open})`)
+        res.status(503).json({ error: 'too many live streams', reason: 'live_events_capacity' })
+        return
+      }
+    }
+    open++
+    const streamId = nextStream++
+    let closed = false
+    let detach: (() => void) | null = null
+    let heartbeat: ReturnType<typeof setInterval> | null = null
+    // Frames that arrive while the snapshot is being prepared, written after it in order. Bounded like the buffer.
+    const pending: LiveFrame[] = []
+    let deliver: (frame: LiveFrame) => void = frame => {
+      pending.push(frame)
+      if (pending.length > 512) pending.shift()
+    }
+
+    const teardown = (why = 'closed'): void => {
+      if (closed) return
+      closed = true
+      open--
+      streams.delete(streamId)
+      if (heartbeat !== null) clearInterval(heartbeat)
+      detach?.()
+      if (why === 'slow') log(`[live-events] dropped a stream that stopped reading (${res.writableLength} bytes unsent, open ${open})`)
+      try { res.end() } catch { /* already gone */ }
+    }
+    streams.set(streamId, teardown)
+    const write = (frame: LiveFrame): void => {
+      if (closed) return
+      try {
+        res.write(frameText(frame))
+        // BACKPRESSURE: a client that is not reading is dropped. It reconnects with its last id and resumes or
+        // snapshots; holding its frames in memory without limit is how one stuck phone grows the server.
+        if (res.writableLength > maxBuffer) teardown('slow')
+      } catch {
+        teardown()
+      }
+    }
+
+    req.on('close', () => teardown())
+    res.on('error', () => teardown())
+
+    try {
+      detach = await deps.hub.attach(frame => deliver(frame))
+    } catch {
+      if (!closed) { closed = true; open--; streams.delete(streamId); res.status(503).json({ error: 'live events unavailable', reason: 'live_events_unavailable' }) }
+      return
+    }
+    if (closed) { detach(); return }
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    })
+    res.flushHeaders()
+    res.write('retry: 3000\n\n')
+
+    // The query wins over the header: a manual reconnect sets `?after=`, the browser's own reconnect sends the header.
+    const cursor = parseLiveCursor(typeof req.query.after === 'string' ? req.query.after : undefined) ?? parseLiveCursor(req.get('last-event-id'))
+    const replay = deps.hub.replayAfter(cursor)
+    if (replay === null) {
+      write(deps.hub.snapshotFrame())
+      // Anything queued while attaching is already in the snapshot when its seq is not newer.
+      const snapSeq = deps.hub.newestSeq
+      for (const frame of pending.splice(0)) if (frame.seq > snapSeq) write(frame)
+    } else {
+      for (const frame of replay) write(frame)
+      const last = replay.length ? replay[replay.length - 1]!.seq : cursor!.seq
+      for (const frame of pending.splice(0)) if (frame.seq > last) write(frame)
+      write(deps.hub.resumeFrame(replay.length))
+    }
+    deliver = write
+    // A write during the snapshot or replay can tear the stream down (a throw, or the buffer cap): no heartbeat then,
+    // or its interval would outlive the stream (review N1).
+    if (closed) return
+
+    // Final review S1: each heartbeat first asks whether the browser sign-in that opened the stream still verifies.
+    heartbeat = setInterval(() => {
+      if (!streamSignInHolds(res)) { teardown('signed_out'); return }
+      write(deps.hub.heartbeatFrame())
+    }, heartbeatMs)
+    ;(heartbeat as { unref?: () => void }).unref?.()
+  }
+}

package/server/routes/permission-broker.ts

@@ -50,6 +50,7 @@
 
 import express, { Router, type NextFunction, type Request, type Response } from 'express'
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import { turnEndAskStats } from '../lib/session-hooks-runtime.js'
 import {
   ANSWERING_CLIENTS,
   CLIENT_LIVE_WINDOW_MS,
@@ -60,8 +61,9 @@ import {
   type PermissionBroker,
 } from '../lib/permission-broker.js'
 import { noteQuestionsPoll, noteWebPresence, validPresenceAgeMs, type QuestionsPollFacts } from '../lib/client-liveness.js'
-import { hasProxyForwardedHeaders, isLoopbackAddress, normalizeRemoteIp, reachableIpv4Addresses } from '../lib/network-policy.js'
+import { hasProxyForwardedHeaders, isLoopbackAddress, isTailscaleIpv4, isTailscaleIpv6, normalizeRemoteIp, reachableIpv4Addresses } from '../lib/network-policy.js'
 import { networkInterfaces } from 'node:os'
+import { isIP } from 'node:net'
 
 export const PERMISSION_BROKER_HOOK_PATH = '/api/permission-requests/ask'
 /** The hook posts its spool envelope, capped at 1 MiB by the script itself. */
@@ -161,6 +163,8 @@ export interface SessionQuestionsRouterDeps {
    * rules: `isWebSessionAuthorized` in production). Absent: only the token opens the list, as before.
    */
   webSessionAuthorized?: (req: Request) => boolean
+  /** 7.0.18 (X1): the turn-end ask counters (lib/turn-end-ask.ts), null while COS_TURN_END_ASKS is off. Defaults to the runtime's. */
+  turnEndAskStats?: () => Record<string, number> | null
   /** Where a counted poll is recorded; `noteQuestionsPoll` in production. */
   notePoll?: (at: number, poll: QuestionsPollFacts) => void
   /** 6.99.26: where COS Control Web's presence is recorded; `noteWebPresence` in production. */
@@ -188,23 +192,92 @@ export function questionsPollFacts(query: Record<string, unknown>): QuestionsPol
   return { hold, presenceAgeMs: hold && validPresenceAgeMs(parsed) ? parsed : null }
 }
 
+/**
+ * The Mac's own addresses: every external IPv4 (its tailnet address first) and its Tailscale IPv6 (fd7a:115c:a1e0::/48).
+ * Safari on the Mac often reaches its own MagicDNS name over IPv6, so the IPv6 tailnet address is the Mac too.
+ */
+export function selfAddressesFromInterfaces(
+  nets: ReturnType<typeof networkInterfaces> = networkInterfaces(),
+): string[] {
+  const out = reachableIpv4Addresses(nets).map(a => a.address)
+  for (const infos of Object.values(nets)) {
+    for (const info of infos ?? []) {
+      // Node 18.0-18.3 reported the family as a number.
+      const v6 = String(info.family) === 'IPv6' || String(info.family) === '6'
+      if (v6 && isTailscaleIpv6(info.address)) out.push(info.address.toLowerCase())
+    }
+  }
+  return out
+}
+
+/** Headers `tailscale serve` adds to a hop it forwards (ipn/ipnlocal/serve.go). Anything else proxy-shaped is not Serve. */
+const SERVE_HOP_HEADERS = new Set([
+  'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto',
+  'tailscale-user-login', 'tailscale-user-name', 'tailscale-user-profile-pic', 'tailscale-headers-info',
+])
+
+/**
+ * W12 (QA week of 11/01-11/08): a `tailscale serve` hop from the Mac to itself. Control Web opened at the Mac's own
+ * https://<mac>.ts.net is the desk, but Serve forwards it over loopback with proxy headers, so 6.99.26 stored its touch
+ * as away and a web-only hold waited up to 10 minutes. It is the Mac only when ALL of these hold:
+ *   - the socket is loopback: the local Serve proxy connected (a peer reaching 3141 directly has its own address);
+ *   - no `Forwarded` or `X-Real-IP` (Serve never sets either);
+ *   - exactly one `X-Forwarded-For` address, no list. Serve SETS that header to the hop's real source (Header.Set, and
+ *     Go's ReverseProxy drops the incoming X-Forwarded-* before its Rewrite runs), so a remote device's spoofed value
+ *     never survives; a proxy that appended instead would make a list, which is refused;
+ *   - that address is loopback or one of the Mac's own TAILSCALE addresses (Serve listens on the tailnet only).
+ */
+export function serveHopFromThisMac(
+  req: { socket?: { remoteAddress?: string | undefined } | null; headers?: Record<string, unknown> | null },
+  selfAddresses: () => readonly string[],
+): boolean {
+  const headers = req.headers
+  if (!headers || typeof headers !== 'object') return false
+  if (!isLoopbackAddress(req.socket?.remoteAddress)) return false
+  for (const name of ['forwarded', 'x-real-ip']) {
+    const v = headers[name]
+    if (v !== undefined && v !== null && !(typeof v === 'string' && v.trim() === '')) return false
+  }
+  // Only Serve's own headers: an unknown proxy-shaped header means a hop this check does not understand.
+  for (const name of Object.keys(headers)) {
+    if (/^(x-forwarded-|tailscale-)/i.test(name) && !SERVE_HOP_HEADERS.has(name.toLowerCase())) return false
+  }
+  const xff = headers['x-forwarded-for']
+  if (typeof xff !== 'string') return false
+  // One address and nothing else: a list ("a, b"), a padded pair or a name is not an IP, so it is refused here.
+  const ip = normalizeRemoteIp(xff.trim()).toLowerCase()
+  if (isIP(ip) === 0) return false
+  if (isLoopbackAddress(ip)) return true
+  if (!isTailscaleIpv4(ip) && !isTailscaleIpv6(ip)) return false
+  let own: readonly string[] = []
+  try { own = selfAddresses() } catch { own = [] }
+  return own.some(a => normalizeRemoteIp(String(a)).toLowerCase() === ip)
+}
+
 /**
  * 6.99.26 (QA round 1): a request from this Mac itself: its socket is loopback or one of the Mac's own addresses (its
  * tailnet address first), and no proxy header says it was forwarded for someone else (a `tailscale serve` hop arrives on
  * loopback for a remote peer). Control Web open on the Mac is the desk: its touch never makes the Mac away.
+ * W12: a proxied request is the Mac only as a Serve hop from the Mac to itself (serveHopFromThisMac).
  */
 export function requestFromThisMac(
   req: { socket?: { remoteAddress?: string | undefined } | null; headers?: Record<string, unknown> | null },
-  selfAddresses: () => readonly string[] = () => reachableIpv4Addresses(networkInterfaces()).map(a => a.address),
+  selfAddresses: () => readonly string[] = () => selfAddressesFromInterfaces(),
 ): boolean {
-  if (hasProxyForwardedHeaders(req.headers)) return false
+  if (hasProxyForwardedHeaders(req.headers)) return serveHopFromThisMac(req, selfAddresses)
   const remote = req.socket?.remoteAddress
   if (isLoopbackAddress(remote)) return true
-  const ip = normalizeRemoteIp(remote ?? '')
+  const ip = normalizeRemoteIp(remote ?? '').toLowerCase()
   if (!ip) return false
   let own: readonly string[] = []
   try { own = selfAddresses() } catch { own = [] }
-  return own.includes(ip)
+  return own.some(a => normalizeRemoteIp(String(a)).toLowerCase() === ip)
+}
+
+function turnEndAskCounters(deps: SessionQuestionsRouterDeps): { turnEndAsks?: Record<string, number> } {
+  let counters: Record<string, number> | null = null
+  try { counters = (deps.turnEndAskStats ?? turnEndAskStats)() } catch { counters = null }
+  return counters ? { turnEndAsks: counters } : {}
 }
 
 export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps): Router {
@@ -261,6 +334,13 @@ export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps):
       // forgotten (the server started then, or dropped it while it still waited). Missing from
       // `settled` and settled after it: the session moved past it.
       waitingAtMacForgottenBefore: new Date(deps.broker.waitingAtMacForgottenBeforeMs()).toISOString(),
+      // X1, additive and only while a full-hold switch is on: every question a live session waits on (held, at the
+      // Mac, or just answered), with its words while it waits, and what a web page must send with an answer right now.
+      // With both off the response is 7.0.13's, key for key.
+      ...(deps.broker.extendedQuestionsView() ? { waiting: deps.broker.waitingList(), webAnswer: deps.broker.webAnswerRules() } : {}),
+      // 7.0.18 (X1), additive and only while COS_TURN_END_ASKS is on: how many turn-end asks armed, were shown,
+      // were answered, were overtaken by a new turn, or aged out. Counts only, never words.
+      ...turnEndAskCounters(deps),
     })
   })
   router.post('/session-questions/:id/answer', (req: Request, res: Response) => {
@@ -273,5 +353,15 @@ export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps):
     const result = deps.broker.answer(String(req.params.id ?? ''), req.body, by)
     res.status(result.status).json(result.body)
   })
+  // X1: the web door's confirm step for an approval (lib/permission-broker.ts `confirm`). The /api gate let the
+  // request in; the door is labelled exactly as for an answer, and only the web door gets a confirm id.
+  router.post('/session-questions/:id/confirm', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    let expected = ''
+    try { expected = deps.apiToken() } catch { expected = '' }
+    const by = timingSafeTokenEqual(req.headers['x-cos-token'], expected) ? 'app' : 'web'
+    const result = deps.broker.confirm(String(req.params.id ?? ''), req.body, by)
+    res.status(result.status).json(result.body)
+  })
   return router
 }

package/server/routes/query-jobs.ts

@@ -1,3 +1,4 @@
+import { streamSignInHolds } from '../lib/api-auth.js'
 import { Router, type Request, type Response } from 'express'
 import { durableQueryJobsEnabled, messagesSteerEnabled } from '../lib/query-job-feature.js'
 import { ACTIVE_QUERY_JOBS_LIST_MAX, ACTIVE_QUERY_JOBS_PROTOCOL } from '../lib/query-job-active.js'
@@ -429,6 +430,8 @@ export function createQueryJobsRouter(
       if (closed) return
 
       heartbeat = setInterval(() => {
+        // Final review S1: a stream opened by a browser sign-in ends once that sign-in no longer verifies.
+        if (!streamSignInHolds(res)) { finish(); return }
         if (!closed && !res.writableEnded) res.write(': keepalive\n\n')
       }, heartbeatMs)
       heartbeat.unref?.()