@gotcos/glasses-server 6.51.0 → 6.52.3

package/server/lib/session-stream-producer.ts

@@ -22,6 +22,7 @@ import {
   type SessionStreamProvider,
 } from './session-stream-events.js'
 import { beginAttachedTurn, publishSessionStream, sessionStreamKey } from './session-stream-bus.js'
+import { releaseAfterTranscriptCatchUp } from './session-transcript-watcher.js'
 
 /**
  * Ceiling on the incomplete trailing line held between chunks.
@@ -68,8 +69,15 @@ export function createLineAssembler(maxCarry: number = MAX_LINE_CARRY_CHARS): Li
 export interface AttachedTurnStream {
   /** Wire this as the adapter's `observeStdout`. Never throws. */
   observeStdout(chunk: string): void
-  /** Call exactly once when the turn settles, whatever its outcome. Never throws. */
-  finish(outcome: 'done' | 'idle'): void
+  /**
+   * Call exactly once when the turn settles, whatever its outcome. Never throws.
+   *
+   * The terminal status is published before this returns. The hold-off lifts once the
+   * session's transcript watcher is at end of file (6.52.0 QA round 2): at once when no
+   * watcher tails the session, within `CATCH_UP_TIMEOUT_MS` otherwise. The promise
+   * settles then and never rejects; callers need not await it.
+   */
+  finish(outcome: 'done' | 'idle'): Promise<void>
 }
 
 export interface AttachedTurnStreamOptions {
@@ -96,6 +104,7 @@ export function createAttachedTurnStream(options: AttachedTurnStreamOptions): At
   const assembler = createLineAssembler()
   const endTurn = beginAttachedTurn(key)
   let finished = false
+  let released: Promise<void> = Promise.resolve()
 
   const emit = (draft: SessionStreamDraft) => {
     try {
@@ -117,8 +126,8 @@ export function createAttachedTurnStream(options: AttachedTurnStreamOptions): At
         /* a malformed chunk costs its own events and nothing else */
       }
     },
-    finish(outcome: 'done' | 'idle'): void {
-      if (finished) return
+    finish(outcome: 'done' | 'idle'): Promise<void> {
+      if (finished) return released
       finished = true
       try {
         for (const line of assembler.flush()) {
@@ -128,11 +137,21 @@ export function createAttachedTurnStream(options: AttachedTurnStreamOptions): At
         /* fall through: the terminal status and the gate release matter more */
       }
       emit({ kind: 'status', state: outcome })
+      // NOT released here. The CLI wrote this turn's records to the transcript as well,
+      // and the watcher reads the hold-off only when it reads: released now, its next
+      // check would show the last lines again and put `working` after this `done`
+      // (6.52.0 QA round 2). The watcher module brings every watcher on this session to
+      // end of file while the hold still applies, then releases, within a bound.
       try {
-        endTurn()
+        released = releaseAfterTranscriptCatchUp(key, endTurn)
       } catch {
-        /* the gate is a Map delete; there is no failure mode to report */
+        try {
+          endTurn()
+        } catch {
+          /* the gate is a Map delete; there is no failure mode to report */
+        }
       }
+      return released
     },
   }
 }

package/server/lib/session-transcript-watcher.ts

@@ -141,6 +141,12 @@ export interface TranscriptTailer {
   state(): 'working' | 'idle' | 'done' | null
   /** True once this tailer has handed off to the poll. Terminal; never clears. */
   degraded(): boolean
+  /**
+   * One HELD pass (6.52.0 QA round 2): move the cursor to end of file and emit nothing.
+   * Only `releaseAfterTranscriptCatchUp` calls it, while a Continue turn still holds the
+   * session. Resolves; never rejects.
+   */
+  skipToEnd(): Promise<void>
 }
 
 /**
@@ -319,6 +325,18 @@ export function createTranscriptTailer(options: TranscriptTailerOptions): Transc
         /* a tick that throws is a tick that produced nothing; the next one retries */
       }
     },
+    async skipToEnd(): Promise<void> {
+      if (degraded) return
+      try {
+        const st = await stat(options.path)
+        if (!st.isFile()) return
+        // The RAW end, not the last newline: see `releaseAfterTranscriptCatchUp`. Moving
+        // backward on a truncated file is what `tick` does too.
+        cursor = { offset: st.size }
+      } catch {
+        /* unreadable right now: the cursor stays, and the caller's bound still releases */
+      }
+    },
   }
 }
 
@@ -330,6 +348,8 @@ interface WatcherEntry {
   refs: number
   timer: ReturnType<typeof setInterval>
   ticking: boolean
+  /** The pass `ticking` guards, so a catch-up can wait for it. Null when none runs. */
+  inflight: Promise<void> | null
   tailer: TranscriptTailer
 }
 
@@ -342,6 +362,8 @@ export interface AcquireWatcherOptions {
   /** Where to start. Production passes the file's current size. */
   offset: number
   intervalMs?: number
+  /** Injected for tests: the tail this entry drives. Production builds it from the fields above. */
+  tailer?: TranscriptTailer
 }
 
 /**
@@ -358,7 +380,7 @@ export function acquireTranscriptWatcher(options: AcquireWatcherOptions): () =>
     return releaseOnce(options.key)
   }
 
-  const tailer = createTranscriptTailer(options)
+  const tailer = options.tailer ?? createTranscriptTailer(options)
   const timer = setInterval(() => {
     const entry = watchers.get(options.key)
     if (!entry) return
@@ -367,12 +389,16 @@ export function acquireTranscriptWatcher(options: AcquireWatcherOptions): () =>
     // next tick sees everything the skipped one would have.
     if (entry.ticking) return
     entry.ticking = true
-    void tailer.tick().finally(() => { entry.ticking = false })
+    // Kept on the entry rather than voided, so a catch-up can wait for it (below).
+    entry.inflight = tailer.tick().catch(() => {}).finally(() => {
+      entry.ticking = false
+      entry.inflight = null
+    })
   }, options.intervalMs ?? POLL_INTERVAL_MS)
   // Never hold the process open. A tail is a view, not work.
   if (typeof (timer as any).unref === 'function') (timer as any).unref()
 
-  watchers.set(options.key, { refs: 1, timer, ticking: false, tailer })
+  watchers.set(options.key, { refs: 1, timer, ticking: false, inflight: null, tailer })
   return releaseOnce(options.key)
 }
 
@@ -410,6 +436,97 @@ export function transcriptWatcherDegraded(key: string): boolean {
   return watchers.get(key)?.tailer.degraded() ?? false
 }
 
+// ---------------------------------------------------------------------------
+// Catch-up before a Continue turn's hold-off lifts (6.52.0 QA round 2)
+// ---------------------------------------------------------------------------
+// The hold-off is read when a tick READS, and a tick runs once a second. The CLI
+// (`claude -p`, `codex exec resume`) writes each record to the transcript tailed here
+// AND prints it on stdout, which the producer maps. Records written after the watcher's
+// last check of the turn were therefore read by its first check AFTER the release, when
+// nothing held them off: the final reply appeared twice on the lens, and the watcher's
+// resume put `working` after `done`. QA reproduced it with the real tailer and producer
+// on the real codex exec sample.
+//
+// So the producer hands its release to `releaseAfterTranscriptCatchUp`, which, while the
+// hold still applies:
+//   1. waits for a tick already in flight, so it reads the hold-off while it holds;
+//   2. runs one held pass that moves the cursor to END OF FILE and emits nothing;
+//   3. only then releases.
+//
+// RAW END OF FILE, not the last newline. On an ordinary exit the child has closed, so
+// every byte there is the turn's. A record cut mid-write left BEHIND the cursor would
+// join the next real record into one unparseable line and lose it; a fragment AHEAD of
+// it is the tail of a record, which never parses (the outer record's closing brace
+// follows it), so the grammar drops it.
+//
+// BOUNDED. The pass is one stat, but a wedged volume or a tick that never settles must
+// not keep the hold-off: that would silence the session for good, which the producer
+// already names as worse than a duplicated line. After `CATCH_UP_TIMEOUT_MS` the release
+// happens anyway and is counted, as is a pass that throws.
+
+/** Ceiling on the catch-up. The pass is one stat; this is for a wedged disk, not an expected wait. */
+export const CATCH_UP_TIMEOUT_MS = 500
+
+const catchUpCounts = { timedOut: 0, failed: 0 }
+
+/** Catch-ups that released on the bound, or on a pass that threw, since this server started. */
+export function transcriptCatchUpCounts(): { timedOut: number; failed: number } {
+  return { ...catchUpCounts }
+}
+
+async function catchUpToEnd(entry: WatcherEntry): Promise<void> {
+  // 1. A check already reading: let it read the hold-off while it still holds.
+  while (entry.ticking && entry.inflight) await entry.inflight
+  // 2. One held pass, guarded like a tick so the timer cannot run another beside it.
+  entry.ticking = true
+  const pass = Promise.resolve().then(() => entry.tailer.skipToEnd())
+  entry.inflight = pass.catch(() => {}).finally(() => {
+    entry.ticking = false
+    entry.inflight = null
+  })
+  await pass
+}
+
+/**
+ * Bring every watcher on this session to end of file, THEN call `release`.
+ *
+ * `release` runs exactly once: at once when nothing tails the session, otherwise after
+ * the catch-up or after `timeoutMs`, whichever is first. The promise settles when it has
+ * run and never rejects.
+ */
+export function releaseAfterTranscriptCatchUp(
+  key: string,
+  release: () => void,
+  timeoutMs: number = CATCH_UP_TIMEOUT_MS,
+): Promise<void> {
+  const releaseSafely = () => {
+    try {
+      release()
+    } catch {
+      /* the release is a Map delete; there is no failure mode to report */
+    }
+  }
+  const entry = watchers.get(key)
+  if (!entry) {
+    // Nothing tails this session, so nothing can read the turn's records late.
+    releaseSafely()
+    return Promise.resolve()
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const bound = new Promise<'timed_out'>(resolve => {
+    timer = setTimeout(() => resolve('timed_out'), Math.max(0, timeoutMs))
+    if (typeof (timer as any).unref === 'function') (timer as any).unref()
+  })
+  const work = catchUpToEnd(entry).then(() => 'caught_up' as const, () => 'failed' as const)
+  return Promise.race([work, bound]).then(outcome => {
+    clearTimeout(timer)
+    if (outcome === 'timed_out') catchUpCounts.timedOut++
+    else if (outcome === 'failed') catchUpCounts.failed++
+    releaseSafely()
+  })
+}
+
 export function __resetTranscriptWatchersForTests(): void {
   for (const entry of watchers.values()) clearInterval(entry.timer)
   watchers.clear()

package/server/routes/agent-sessions.ts

@@ -29,6 +29,8 @@ import {
   emptySessionListDropped,
   loadClaudeDesktopAliases,
   loadCursorComposerNames,
+  loadCodexThreadNames,
+  idFromCodexFilename,
   parseAgentSession,
   type AgentProvider,
   type AgentSessionRoots,
@@ -482,7 +484,16 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     // `parsed.truncated` says so out loud, and the counts are then counts of what was
     // READ. Presenting a partial count as the session total would be the same
     // dishonesty as a silent cap, so the digest omits the number entirely instead.
-    const parsed = await parseAgentSession(provider, found)
+    // 6.52.0: a Codex thread is titled by its own name, as its list row already is. Keyed
+    // by the rollout's FILENAME id first: a cloned thread's `session_meta` carries its
+    // parent's id (see `listCodexSessions`), and the parent's name would be the wrong one.
+    let codexThreadName: string | undefined
+    if (provider === 'codex') {
+      const names = await loadCodexThreadNames(agentSessionRoots().codexSessions)
+      const fileId = idFromCodexFilename(found.split('/').pop() || '')
+      codexThreadName = (fileId ? names.get(fileId) : undefined) || names.get(sessionId) || undefined
+    }
+    const parsed = await parseAgentSession(provider, found, codexThreadName ? { codexThreadName } : {})
     // 6.50.0 `?turns=N`: the recent conversation, for the lens's scroll-up history. Only
     // when asked, so the detail poll and every older client get the same bytes as before.
     // A failure here costs the history, never the detail page.

package/server/routes/client-instance.ts

@@ -27,6 +27,8 @@ import {
 
 /** Owners kept at once; the least recently seen device is dropped past this. */
 export const CLIENT_INSTANCE_MAX_DEVICES = 16
+/** Copies whose last claim time is remembered (6.52.3); the least recent is dropped past this. */
+export const CLIENT_INSTANCE_MAX_SEEN = 64
 
 export interface ClientInstanceRouterDeps {
   now?: () => number
@@ -49,6 +51,13 @@ export function createClientInstanceRouter(deps: ClientInstanceRouterDeps | (()
   const router = Router()
   const owners = new Map<string, ClientInstanceOwner>()
   const chunks = new ClientChunkLedger()
+  // 6.52.3: when each copy last claimed, so an older boot proves it was awake before it
+  // may take a quiet ring back. Bounded like the chunk ledger.
+  const lastSeen = new Map<string, number>()
+  const noteSeen = (id: string, at: number) => {
+    lastSeen.delete(id); lastSeen.set(id, at)
+    while (lastSeen.size > CLIENT_INSTANCE_MAX_SEEN) lastSeen.delete(lastSeen.keys().next().value as string)
+  }
   router.use((req, _res, next) => {
     if (isMeetingChunkPost(req.method, req.path)) chunks.note(deviceKey(req.socket?.remoteAddress ?? req.ip), parseInstanceTag(req.query?.clientInstance), now())
     next()
@@ -61,7 +70,9 @@ export function createClientInstanceRouter(deps: ClientInstanceRouterDeps | (()
     const previous = owners.get(device) ?? null
     const evidence = previous ? chunks.evidence(device, previous.id, claim.id, at) : NO_CAPTURE
     const captureLive = previous ? ownerIsRecording(previous, evidence, at) : false
-    const result = arbitrateClientInstance(previous, claim, at, evidence)
+    const claimantLastSeenAt = lastSeen.get(claim.id)
+    noteSeen(claim.id, at)
+    const result = arbitrateClientInstance(previous, claim, at, evidence, claimantLastSeenAt)
     if (req.body?.check === true) {
       const shown = previous ?? result.owner
       return void res.json({ verdict: result.verdict, owner: { id: shown.id, bootAt: shown.bootAt, version: shown.version, seenAt: shown.seenAt }, check: true, captureLive })

package/server/routes/cursor-stop-followup.ts

@@ -4,11 +4,13 @@
 // NOT under /api, on purpose. The hook holds the per-install HOOK token
 // (`~/.cos-glasses/hook-token`, 0600), never the pairing token the /api gate checks, and
 // widening that gate for one caller would be the larger change. This route checks the
-// hook token itself, in constant time, before it reads anything. It answers only `{}` or
-// `{"followup_message": ...}` so the hook can print it verbatim, and it never answers
-// with anything a Claude Stop could act on: a body that is not a Cursor Stop is `{}`.
+// hook token itself, in constant time, BEFORE its body is read or parsed (6.52.0: it is
+// mounted ahead of the global 10 MB parser, and its own 2 MB parser runs only after the
+// token check). It answers only `{}` or `{"followup_message": ...}` so the hook can print
+// it verbatim, and it never answers with anything a Claude Stop could act on: a body that
+// is not a Cursor Stop is `{}`.
 
-import express, { Router, type Request, type Response } from 'express'
+import express, { Router, type NextFunction, type Request, type Response } from 'express'
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
 import { claimNextCursorTurn, cursorStopAcceptsFollowup, cursorStopIsFresh, parseCursorStopEnvelope } from '../lib/cursor-stop-followup.js'
 import { MAX_QUEUED_PER_THREAD, type QueuedThreadTurn } from '../lib/thread-turn-queue.js'
@@ -25,14 +27,19 @@ export const CURSOR_STOP_FOLLOWUP_PATH = '/hooks/cursor/stop-followup'
 
 export function createCursorStopFollowupRouter(deps: CursorStopFollowupDeps): Router {
   const router = Router()
-  // The hook posts its spool envelope, capped at 1 MiB by the script itself.
-  router.post(CURSOR_STOP_FOLLOWUP_PATH, express.json({ limit: '2mb' }), (req: Request, res: Response) => {
+  // The token first, then the body: the hook posts its spool envelope, capped at 1 MiB by
+  // the script itself.
+  const requireHookToken = (req: Request, res: Response, next: NextFunction): void => {
     res.set('Cache-Control', 'private, no-store')
     let expected: string | null = null
     try { expected = deps.hookToken() } catch { expected = null }
     if (!expected || !timingSafeTokenEqual(req.headers['x-cos-hook-token'], expected)) {
-      return res.status(401).json({})
+      res.status(401).json({})
+      return
     }
+    next()
+  }
+  router.post(CURSOR_STOP_FOLLOWUP_PATH, requireHookToken, express.json({ limit: '2mb' }), (req: Request, res: Response) => {
     const facts = parseCursorStopEnvelope(req.body)
     if (!facts || !cursorStopAcceptsFollowup(facts, MAX_QUEUED_PER_THREAD)) return res.json({})
     // The hook waits three seconds and then moves on. A claim made after it stopped

package/server/routes/health.ts

@@ -49,7 +49,8 @@ import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
 // The flag lives beside the endpoints it describes, so it cannot drift from
 // whether they are actually registered.
 import { MEDIA_CHUNKED_UPLOAD_ENABLED } from './media.js'
-import { durableQueryJobsCapability } from '../lib/query-job-feature.js'
+import { durableQueryJobsCapability, messagesTrailEnabled } from '../lib/query-job-feature.js'
+import { jobTrailStats } from '../lib/job-trail.js'
 import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
 import { getMorningBriefScheduler } from '../lib/morning-brief-runtime.js'
 import { getTranscriptionPolicySnapshot } from '../lib/transcription-policy.js'
@@ -80,6 +81,7 @@ import {
   threadAttachHealthFields,
 } from '../lib/thread-attach-capability.js'
 import { sessionHooksHealthFields } from '../lib/session-hooks-runtime.js'
+import { permissionBrokerHealthFields, sessionQuestionsCapability } from '../lib/permission-broker.js'
 import { continueLiveEnabled, liveDeliveryStats } from '../lib/session-peer-inbox-deps.js'
 import { codexLiveStats } from '../lib/codex-live-queue-deps.js'
 import { codexLiveQueueEnabled } from '../lib/codex-live-queue.js'
@@ -388,6 +390,9 @@ healthRouter.get('/health', async (_req, res) => {
     server_version: managedServerVersion(),
     ...threadAttachHealthFields(threadAttach),
     ...sessionHooksHealthFields(),
+    // 6.52.0: counts, the mode and two timestamps; never an id, a question, a command, or
+    // how many are held (that is on the authenticated questions route).
+    ...permissionBrokerHealthFields(),
     ...continueLiveHealthFields(),
     server_instance_id: getServerInstanceId(),
     boot_id: serverMetrics.bootId,
@@ -479,6 +484,12 @@ healthRouter.get('/health', async (_req, res) => {
       protocolVersion: durableJobs.protocolVersion,
       state: durableJobs.store.state,
     },
+    // 6.52.0: the Messages trail's readers, process-wide since boot. Counts and a
+    // timestamp only: stdout lines read, entries emitted, failures swallowed.
+    messages_trail: {
+      enabled: durableJobs.enabled && messagesTrailEnabled(),
+      ...jobTrailStats(),
+    },
   })
 })
 
@@ -568,7 +579,19 @@ healthRouter.get('/models', async (req, res) => {
       durableQueryJobs: {
         enabled: durableJobs.enabled,
         protocolVersion: durableJobs.protocolVersion,
+        // 6.52.0: jobs journal `trail` events and carry `snapshot.trail`. The app reads
+        // THIS surface (not /api/health) and falls back to the activity log without it.
+        // False whenever jobs themselves are off or COS_MESSAGES_TRAIL=0.
+        trail: durableJobs.enabled && messagesTrailEnabled(),
       },
+      // 6.52.0: the session questions API and its client contract. A client polls
+      // `GET /api/session-questions?client=glasses|phone` every `pollIntervalMs`; one
+      // quiet for `liveWindowMs` hands every held request back to the Mac.
+      sessionQuestions: sessionQuestionsCapability(),
+      // 6.52.1: Sessions prompt events carry additive `turn_started_at` (ISO), the
+      // real user-record time. Transport `at` stays the seed/live stamp. Absent on
+      // 6.52.0, the client falls back to a local pin.
+      runningTurnMeta: { protocolVersion: 1 },
       transcription: {
         ...transcription,
         live: transcriptionLive,

package/server/routes/permission-broker.ts

@@ -0,0 +1,176 @@
+// The permission broker's two doors (6.52.0). See `lib/permission-broker.ts` for the why.
+//
+// POST /api/permission-requests/ask -- the COS session hook, on a PermissionRequest at a
+// desk idle for 90 s. THIS IS THE URL THE 6.51.0 SCRIPT ALREADY CALLS, so no Mac needs
+// `--hooks install` again (QA round 1: a new URL meant a new script, and every Mac that did
+// not reinstall would have shown Control's "hooks outdated" banner and kept the old door).
+// The hook holds the per-install HOOK token (`~/.cos-glasses/hook-token`, 0600), never the
+// pairing token the /api gate checks, so this one route is registered BEFORE that gate and
+// before the global body parser, as a deliberate exemption for exactly this method and
+// path: it checks the hook token itself, in constant time, BEFORE it reads a byte of the
+// body, and only then parses up to 2 MB. Any other method on the path falls through to the
+// /api gate like every other /api route. It answers only `{}` or a
+// `{"hookSpecificOutput": ...}` the hook prints verbatim, and is mounted unconditionally
+// (not behind COS_THREAD_ATTACH_ENABLED): the switch is `COS_PERMISSION_BROKER`, read per
+// request. It holds no maintenance lease; the broker refuses to park during a drain itself.
+//
+// Mixed versions fail safe. Against a 6.51 server the same script gets 401 from the /api
+// gate, prints nothing, and the native dialog shows, as it always did there.
+//
+// GET /api/session-questions and POST /api/session-questions/:id/answer -- the lens and the
+// phone, behind the API token like every other /api route. Question and command text only
+// ever travels here, never on the display bus. The GET is ALSO the broker's liveness
+// signal (lib/client-liveness.ts), and only when it names the client: `?client=glasses` or
+// `?client=phone`. Anything else (missing, `control`, a typo) is answered but never counts,
+// so a surface that only shows a count can poll without making the Mac hold questions it
+// cannot answer. It checks X-Cos-Token itself as well, in constant time, and a request
+// without it is refused and never counted, whatever sits in front of this router.
+
+import express, { Router, type NextFunction, type Request, type Response } from 'express'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import {
+  ANSWERING_CLIENTS,
+  CLIENT_LIVE_WINDOW_MS,
+  QUESTIONS_POLL_INTERVAL_MS,
+  SESSION_QUESTIONS_PROTOCOL_VERSION,
+  type BrokerAdmission,
+  type HookReplyChannel,
+  type PermissionBroker,
+} from '../lib/permission-broker.js'
+import { noteQuestionsPoll } from '../lib/client-liveness.js'
+
+export const PERMISSION_BROKER_HOOK_PATH = '/api/permission-requests/ask'
+/** The hook posts its spool envelope, capped at 1 MiB by the script itself. */
+export const PERMISSION_BROKER_BODY_LIMIT = '2mb'
+
+export interface PermissionBrokerHookRouterDeps {
+  /** The per-install hook token, or null when none has been minted (then nothing is answered). */
+  hookToken: () => string | null
+  broker: PermissionBroker
+}
+
+/**
+ * The hook-token check, as middleware that runs BEFORE any body parser: a request without
+ * the token is answered 401 without a byte of its body being read or parsed.
+ */
+export function requireHookToken(hookToken: () => string | null) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    res.set('Cache-Control', 'private, no-store')
+    let expected: string | null = null
+    try { expected = hookToken() } catch { expected = null }
+    if (!expected || !timingSafeTokenEqual(req.headers['x-cos-hook-token'], expected)) {
+      res.status(401).json({})
+      return
+    }
+    next()
+  }
+}
+
+/** The held response, as the broker sees it. */
+export function replyChannelFor(res: Response): HookReplyChannel {
+  const writable = (): boolean => {
+    if (res.headersSent || res.writableEnded || res.destroyed) return false
+    const socket = res.socket
+    return !!socket && !socket.destroyed && socket.writable !== false
+  }
+  return {
+    writable,
+    reply(body) {
+      if (!writable()) return false
+      try {
+        res.status(200).json(body)
+        return true
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+export function createPermissionBrokerHookRouter(deps: PermissionBrokerHookRouterDeps): Router {
+  const router = Router()
+  router.post(
+    PERMISSION_BROKER_HOOK_PATH,
+    requireHookToken(deps.hookToken),
+    express.json({ limit: PERMISSION_BROKER_BODY_LIMIT }),
+    async (req: Request, res: Response) => {
+      let admission: BrokerAdmission
+      try {
+        admission = await deps.broker.admit(req.body)
+      } catch (error) {
+        console.error(`[permission-broker] admit failed: ${error instanceof Error ? error.message : error}`)
+        res.json({})
+        return
+      }
+      if (!admission.ok) {
+        res.json({})
+        return
+      }
+      const channel = replyChannelFor(res)
+      // The hook gave up during the desk read: nothing to hold.
+      if (!channel.writable()) {
+        deps.broker.noteFastPath('hook_gone_early')
+        return
+      }
+      const id = deps.broker.park(admission.request, channel)
+      // `res` close, not `req` close: since Node 16 the request emits `close` once its body
+      // is read, which is not the hook leaving. A close after the reply is a no-op.
+      res.on('close', () => { deps.broker.hookClosed(id) })
+    },
+  )
+  // A body the parser refused (too large, not JSON): `{}` and nothing else, never a stack.
+  router.use(PERMISSION_BROKER_HOOK_PATH, (error: unknown, _req: Request, res: Response, next: NextFunction) => {
+    if (res.headersSent) { next(error); return }
+    deps.broker.noteFastPath('malformed')
+    const status = Number((error as { status?: unknown })?.status)
+    res.status(Number.isInteger(status) && status >= 400 && status < 500 ? status : 400).json({})
+  })
+  return router
+}
+
+export interface SessionQuestionsRouterDeps {
+  broker: PermissionBroker
+  /** The pairing token (X-Cos-Token). A poll counts as a live client only with it. */
+  apiToken: () => string
+  /** Where a counted poll is recorded; `noteQuestionsPoll` in production. */
+  notePoll?: (at: number) => void
+  now?: () => number
+}
+
+export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps): Router {
+  const router = Router()
+  const notePoll = deps.notePoll ?? noteQuestionsPoll
+  const now = deps.now ?? Date.now
+  router.get('/session-questions', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    let expected = ''
+    try { expected = deps.apiToken() } catch { expected = '' }
+    // A hook token, or nothing: refused, and never a live client.
+    if (!timingSafeTokenEqual(req.headers['x-cos-token'], expected)) {
+      res.status(401).json({ error: 'unauthorized' })
+      return
+    }
+    // Only a client that says it can answer (and shows the cards) counts as live.
+    const client = typeof req.query.client === 'string' ? req.query.client : ''
+    if (ANSWERING_CLIENTS.has(client)) notePoll(now())
+    const health = deps.broker.health()
+    // Listed first: a deadline the timer has not caught yet is settled by the listing.
+    const items = deps.broker.list()
+    res.json({
+      enabled: health.enabled,
+      mode: health.mode,
+      protocolVersion: SESSION_QUESTIONS_PROTOCOL_VERSION,
+      pollIntervalMs: QUESTIONS_POLL_INTERVAL_MS,
+      liveWindowMs: CLIENT_LIVE_WINDOW_MS,
+      pending: deps.broker.pendingCount(),
+      stats: deps.broker.stats(),
+      items,
+    })
+  })
+  router.post('/session-questions/:id/answer', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    const result = deps.broker.answer(String(req.params.id ?? ''), req.body)
+    res.status(result.status).json(result.body)
+  })
+  return router
+}