@gotcos/glasses-server 6.99.33 → 7.0.7

package/server/routes/live-events.ts

@@ -0,0 +1,329 @@
+// 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 { 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
+
+    heartbeat = setInterval(() => write(deps.hub.heartbeatFrame()), heartbeatMs)
+    ;(heartbeat as { unref?: () => void }).unref?.()
+  }
+}

package/server/routes/permission-broker.ts

@@ -60,8 +60,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. */
@@ -188,23 +189,86 @@ 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)
 }
 
 export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps): Router {

package/server/routes/session-preview.ts

@@ -0,0 +1,200 @@
+/**
+ * The preview contract's routes (preview engine phase 1, PLAN 4c), mounted inside agentSessionsRouter, so behind the
+ * shared /api gate. Neither a request nor a response carries a filesystem path: a card or file is named by an opaque
+ * id that the resolver re-authorizes on every call (agent-session-output-images.ts `previewFile`).
+ *
+ *   GET /api/preview/agent-sessions/:provider/:sessionId/:id/meta
+ *   GET /api/preview/agent-sessions/:provider/:sessionId/:id/content?part=raw|inline|text|table|html|html-run|thumb
+ *   GET|POST /api/preview-folders/settings   the Settings extra folders (lib/preview-folders-setting.ts)
+ *
+ * "Show session files, screenshots and images" (7.0.4 name) off answers 403 previews_off before any transcript or file is read.
+ * A denied secret name answers 403 secret_file_denied (as the 7.0.4 output routes do). A folder card has no content (phase 2 lists folders).
+ * Every refusal or failure but a missing id logs one line (`logPreviewRefusal`): reason code, provider, part, kind.
+ */
+import { Router, type Request, type Response } from 'express'
+import { agentSessionOutputImages } from '../lib/agent-session-output-images.js'
+import { sessionFilesSetting } from '../lib/session-files-setting.js'
+import { previewFoldersSetting, folderDisplay, type PreviewFoldersStore } from '../lib/preview-folders-setting.js'
+import { previewThumbnailer } from '../lib/preview-thumbs.js'
+import {
+  HTML_PREVIEW_MAX, looksBinary, PREVIEW_PARTS, previewHeaders, tablePage, TEXT_WINDOW_MAX, textWindow, withCspMeta, type PreviewPart,
+} from '../lib/preview-content.js'
+import type { PreviewKind } from '../lib/session-links.js'
+import { previewErrorCode } from '../lib/preview-error-code.js'
+import { warnPreviewThrottled } from '../lib/preview-log-throttle.js'
+/** The 7.0.4 code (routes/agent-sessions.ts PREVIEWS_BUSY), repeated here so this router needs nothing from that one. */
+const PREVIEWS_BUSY = 'previews_busy'
+
+type Previews = Pick<typeof agentSessionOutputImages, 'previewFile' | 'previewImage'>
+type Thumbs = Pick<typeof previewThumbnailer, 'thumbnail'>
+export interface SessionPreviewDeps {
+  previews?: Previews
+  enabled?: () => boolean
+  thumbs?: Thumbs
+  folders?: PreviewFoldersStore
+  home?: () => string
+}
+
+const PROVIDERS = new Set(['claude', 'codex', 'cursor'])
+const TEXT_KINDS = new Set<PreviewKind>(['markdown', 'text', 'code', 'html', 'table'])
+const THUMB_KINDS = new Set<PreviewKind>(['pdf', 'document', 'slides', 'sheet', 'html'])
+const NORMALIZED = /\.(png|jpe?g|webp|hei[cf]|avif)$/i
+
+/** Which parts a kind has. The web reads this from `meta` and never asks for another. */
+export function partsFor(kind: PreviewKind, name: string): PreviewPart[] {
+  const parts: PreviewPart[] = []
+  if (kind === 'folder') return parts
+  parts.push('raw')
+  if (kind === 'pdf') parts.push('inline')
+  if (kind === 'image' && NORMALIZED.test(name)) parts.push('inline')
+  if (TEXT_KINDS.has(kind)) parts.push('text')
+  if (kind === 'table') parts.push('table')
+  if (kind === 'html') parts.push('html', 'html-run')
+  if (THUMB_KINDS.has(kind)) parts.push('thumb')
+  if (kind === 'image' && NORMALIZED.test(name)) parts.push('thumb')
+  return parts
+}
+
+/** What a refusal or failure is logged with. Only fixed words: never a path, a file name, an id, a token or content. */
+interface LogAt { route: 'meta' | 'content'; provider: string; part?: string; kind?: PreviewKind; detail?: string }
+const SAFE_WORD = /^[a-z0-9_-]{1,40}$/i
+/**
+ * QA 7.0.5 (the 7.0.4 promise, for the preview engine's routes): one line per refusal or failure, with a stable reason
+ * code and the provider, part and file kind. A missing id (404 preview_not_found) is ordinary and is not logged, as in
+ * the 7.0.4 output routes. 7.0.7 (final QA N1): a burst of the same line (a page of thumbnails while another client is
+ * busy) logs once per 10 seconds with the count it held back, through the 7.0.4 routes' own limiter.
+ */
+export function logPreviewRefusal(at: LogAt, error: string, now = Date.now()): void {
+  if (error === 'preview_not_found') return
+  const words = [`reason=${error}`, `provider=${PROVIDERS.has(at.provider) ? at.provider : 'unknown'}`]
+  if (at.part && SAFE_WORD.test(at.part)) words.push(`part=${at.part}`)
+  if (at.kind && SAFE_WORD.test(at.kind)) words.push(`kind=${at.kind}`)
+  if (at.detail && SAFE_WORD.test(at.detail)) words.push(`detail=${at.detail}`)
+  const line = `[preview] ${at.route} refused ${words.join(' ')}`
+  warnPreviewThrottled(line, line, now)
+}
+
+function refuse(res: Response, status: string, at: LogAt) {
+  const map: Record<string, [number, string]> = {
+    not_found: [404, 'preview_not_found'], unavailable: [503, 'preview_unavailable'], too_large: [413, 'preview_too_large'],
+    secret: [403, 'secret_file_denied'], folder: [404, 'preview_folder'], busy: [503, PREVIEWS_BUSY],
+  }
+  const [code, error] = map[status] ?? [503, 'preview_unavailable']
+  logPreviewRefusal(at, error)
+  if (status === 'busy') res.set('Retry-After', '2')
+  res.status(code).json({ error })
+}
+/** A refusal the route answers itself (not through `refuse`), logged the same way. */
+function answer(res: Response, code: number, error: string, at: LogAt) {
+  logPreviewRefusal(at, error)
+  res.status(code).json({ error })
+}
+
+export function createSessionPreviewRouter(deps: SessionPreviewDeps = {}): Router {
+  const router = Router()
+  const previews = deps.previews ?? agentSessionOutputImages
+  const enabled = deps.enabled ?? (() => sessionFilesSetting.read().enabled)
+  const thumbs = deps.thumbs ?? previewThumbnailer
+  const folders = deps.folders ?? previewFoldersSetting
+
+  const gate = (req: Request, res: Response, route: LogAt['route']): { provider: 'claude' | 'codex' | 'cursor'; sessionId: string; id: string } | null => {
+    res.set('Cache-Control', 'private, no-store')
+    res.set('X-Content-Type-Options', 'nosniff')
+    const provider = String(req.params.provider ?? '').toLowerCase()
+    // The switch decides before anything is read (no transcript, no file, no stat).
+    if (!enabled()) { answer(res, 403, 'previews_off', { route, provider }); return null }
+    if (!PROVIDERS.has(provider)) { res.status(404).json({ error: 'preview_not_found' }); return null }
+    return { provider: provider as 'claude' | 'codex' | 'cursor', sessionId: String(req.params.sessionId ?? ''), id: String(req.params.id ?? '') }
+  }
+
+  router.get('/preview/agent-sessions/:provider/:sessionId/:id/meta', async (req, res) => {
+    const g = gate(req, res, 'meta'); if (!g) return
+    const at: LogAt = { route: 'meta', provider: g.provider }
+    try {
+      const found = await previews.previewFile(g.provider, g.sessionId, g.id, true)
+      if (found.status === 'folder') { res.json({ id: g.id, name: '', kind: 'folder', type: 'Folder', state: 'available', parts: [] }); return }
+      if (found.status !== 'ok') { refuse(res, found.status, { ...at, detail: found.reason }); return }
+      res.json({ id: g.id, name: found.name, kind: found.kind, type: found.type, size: found.identity.size, ...(found.line ? { line: found.line } : {}), state: 'available', parts: partsFor(found.kind, found.name) })
+    } catch (error) { refuse(res, 'unavailable', { ...at, detail: 'error_' + previewErrorCode(error) }) }
+  })
+
+  router.get('/preview/agent-sessions/:provider/:sessionId/:id/content', async (req, res) => {
+    const g = gate(req, res, 'content'); if (!g) return
+    const part = String(req.query.part ?? 'raw') as PreviewPart
+    const at: LogAt = { route: 'content', provider: g.provider }
+    if (!PREVIEW_PARTS.includes(part)) { answer(res, 400, 'preview_part', at); return }
+    at.part = part
+    try {
+      const found = await previews.previewFile(g.provider, g.sessionId, g.id)
+      if (found.status !== 'ok') { refuse(res, found.status, { ...at, detail: found.reason }); return }
+      at.kind = found.kind
+      if (!partsFor(found.kind, found.name).includes(part)) { answer(res, 400, 'preview_part', at); return }
+      // A picture goes through the output-image normalizer, as a JPEG, never as the bytes a file claims to be.
+      if (found.kind === 'image' && part !== 'raw') {
+        const img = await previews.previewImage(g.provider, g.sessionId, g.id, part === 'thumb' ? 'thumb' : 'phone')
+        if (img.status !== 'ok') { refuse(res, img.status, { ...at, detail: 'reason' in img ? img.reason : undefined }); return }
+        if (!('path' in img)) { refuse(res, 'unavailable', at); return }
+        res.set({ 'Content-Type': 'image/jpeg', 'Content-Disposition': 'inline', 'Content-Security-Policy': "sandbox; default-src 'none'", 'Cross-Origin-Resource-Policy': 'same-origin' })
+        res.sendFile(img.path, { dotfiles: 'allow', headers: { 'Content-Type': 'image/jpeg' } }, err => {
+          if (!err) return
+          if (!res.headersSent) refuse(res, 'unavailable', { ...at, detail: 'send_' + previewErrorCode(err) }); else { logPreviewRefusal({ ...at, detail: 'send_' + previewErrorCode(err) }, 'preview_cut'); res.destroy() }
+        })
+        return
+      }
+      const bytes = found.bytes
+      if (part === 'raw' || part === 'inline') { res.set(previewHeaders(part, found.name)); res.status(200).end(bytes); return }
+      if (part === 'thumb') {
+        const t = await thumbs.thumbnail(bytes, found.name, found.identity)
+        if (t.status !== 'ok') {
+          if (t.status === 'busy') res.set('Retry-After', '2')
+          answer(res, 503, t.status === 'busy' ? PREVIEWS_BUSY : 'thumb_unavailable', { ...at, detail: t.status === 'unavailable' ? t.reason : undefined })
+          return
+        }
+        res.set(previewHeaders('thumb', found.name))
+        res.sendFile(t.path, { dotfiles: 'allow', headers: { 'Content-Type': 'image/png' } }, err => {
+          if (!err) return
+          if (!res.headersSent) answer(res, 503, 'thumb_unavailable', { ...at, detail: 'send_' + previewErrorCode(err) }); else { logPreviewRefusal({ ...at, detail: 'send_' + previewErrorCode(err) }, 'preview_cut'); res.destroy() }
+        })
+        return
+      }
+      if (looksBinary(bytes)) { answer(res, 415, 'preview_binary', at); return }
+      if (part === 'html' || part === 'html-run') {
+        if (bytes.length > HTML_PREVIEW_MAX) { refuse(res, 'too_large', at); return }
+        // PLAN 6: the policy is in the page itself too, before anything in it can load.
+        res.set(previewHeaders(part, found.name)); res.status(200).end(withCspMeta(bytes, part)); return
+      }
+      if (part === 'table') {
+        res.set(previewHeaders('table', found.name))
+        res.json(tablePage(bytes, found.name, Number(req.query.offset ?? 0)))
+        return
+      }
+      // Every text window, an HTML page's source included, is 512 KiB a call with "load more".
+      res.set(previewHeaders('text', found.name))
+      res.json({ ...textWindow(bytes, Number(req.query.offset ?? 0), Number(req.query.limit ?? TEXT_WINDOW_MAX), TEXT_WINDOW_MAX), ...(found.line ? { line: found.line } : {}) })
+    } catch (error) {
+      refuse(res, 'unavailable', { ...at, detail: 'error_' + previewErrorCode(error) })
+    }
+  })
+
+  // Settings, Privacy: the named extra folders. Shown as ~/x inside home. A refusal names each folder's problem.
+  router.get('/preview-folders/settings', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    try {
+      const s = folders.read()
+      res.json({ folders: s.folders.map(f => folderDisplay(f, deps.home?.())), source: s.source })
+    } catch { res.status(500).json({ error: 'preview_folders_unavailable' }) }
+  })
+  router.post('/preview-folders/settings', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const body = req.body
+    if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(k => k !== 'folders') || !Array.isArray(body.folders)) {
+      res.status(400).json({ error: { code: 'invalid_preview_folders', message: 'Send { folders: ["~/cos-worktrees"] }.' } }); return
+    }
+    try {
+      const r = folders.set(body.folders)
+      if (!r.ok) { res.status(400).json({ error: { code: 'preview_folder_refused', message: r.errors[0]?.message ?? 'That folder cannot be used.' }, errors: r.errors }); return }
+      res.json({ folders: r.setting.folders.map(f => folderDisplay(f, deps.home?.())), source: r.setting.source })
+    } catch { res.status(500).json({ error: 'preview_folders_unavailable' }) }
+  })
+  return router
+}