@gotcos/glasses-server 6.99.33 → 7.0.18

package/server/routes/today-brief.ts

@@ -4,10 +4,19 @@
  * - GET  /api/today/brief           the cached summary; never generates.
  * - POST /api/today/brief           an open Today's ask, with the rows it read (titles, states, how long, last lines,
  *                                   what needs you). Generates only when the switch is on, the inputs changed, 10 minutes
- *                                   passed and the day's 60 are not spent. The Work cards in progress come from the
+ *                                   passed and the day's cap (Summaries per day, 7.0.5) is not spent. The Work cards in progress come from the
  *                                   server's own shared board read, never the body.
+ *                                   7.0.1: `"force": true` in the body is the Today refresh button. It skips the
+ *                                   10-minute interval and the "inputs unchanged" check, at most once every 30 s,
+ *                                   inside the same daily cap. A throttled one answers reason `refresh_throttled` and
+ *                                   `retryAfterMs`.
+ *                                   7.0.5: `"reason": "reconnect"` says the client's read just recovered from a failed
+ *                                   one: that start skips the 10-minute interval, at most once per 10 minutes. The
+ *                                   "inputs unchanged" check, the breaker, the switch and the daily cap still apply.
  * - GET  /api/today/brief/settings  the switch and what set it.
  * - POST /api/today/brief/settings  { enabled: boolean }, the Settings toggle. COS_TODAY_BRIEF_LLM, when set, still wins.
+ * - GET  /api/today/brief/settings/cap   7.0.5 "Summaries per day": { dailyCap, min: 1, max: 100, default: 100, usedToday }.
+ * - PUT  /api/today/brief/settings/cap   { dailyCap: number }, clamped to 1 to 100 and saved; answers the same shape.
  * Auth is the parent /api gate (token or web session cookie). Every answer is private, no-store.
  */
 import { Router } from 'express'
@@ -16,52 +25,90 @@ import { dataPath } from '../lib/data-dir.js'
 import { runClaudeText } from '../lib/claude-text-runner.js'
 import { logTokenAudit } from '../lib/token-audit.js'
 import type { TaskBoardRow } from '../lib/task-store.js'
-import { agentSessionRoots, findAgentSessionFile } from '../lib/agent-session-store.js'
+import type { TaskDateFields } from '../lib/task-dates.js'
+import { agentSessionRoots, codexSessionRootsOf, findAgentSessionFile, listCodexJsonlFiles, loadClaudeDesktopAliases, loadClaudeTranscriptIndex, type AgentProvider } from '../lib/agent-session-store.js'
 import { readClaudeSubagents, summarize, type SessionSubagents } from '../lib/session-subagents.js'
 import { readCodexSubagentDetails } from '../lib/codex-subagent-activity.js'
+import { readRecentActivity, type RecentActivity } from '../lib/agent-session-recent.js'
 import { acquireMaintenanceWork, maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
 import { isRecordingLive } from '../lib/stt-runtime.js'
 import {
   TODAY_BRIEF_BODY_MAX_BYTES, TODAY_BRIEF_EFFORT, TODAY_BRIEF_SETTINGS_FILE, TODAY_BRIEF_STATE_FILE, TODAY_BRIEF_TIMEOUT_MS,
-  TodayBriefInputError, createTodayBrief, normalizeTodayBriefInputs, subagentLookups, todayBriefFingerprint, withSubagents, type BriefWork, type SubagentReading, type TodayBrief,
+  TodayBriefInputError, createTodayBrief, normalizeTodayBriefInputs, sessionContextLookups, todayBriefFingerprint, withCalendar, withRecentActivity, withSubagents, type BriefWork, type CalendarReading, type SubagentReading, type TodayBrief,
 } from '../lib/today-brief.js'
 
 export interface TodayBriefRouterDeps {
   brief: TodayBrief
-  /** The Work board as the server already reads it (a shared, bounded read), or null when it cannot be read. */
-  board: () => Promise<TaskBoardRow[] | null>
-  /** Sub-agents for up to 8 sessions, by "provider|id". Missing keys mean "not read"; the page's counts stay. */
-  subagents?: (keys: string[]) => Promise<Map<string, SubagentReading>>
+  /** The Work board, dated when it can be (2026-11-09: listBoardWithDates, so a card's last move is known), or null
+   *  when it cannot be read. */
+  board: () => Promise<Array<TaskBoardRow & Partial<TaskDateFields>> | null>
+  /** Sub-agents and recent activity for up to 12 sessions, by "provider|id", written into `into` as each session is
+   *  read, so an ask that stops waiting keeps what was read by then. Missing keys mean "not read": the page's counts
+   *  and `line` stay, the line marked "may be old". */
+  context?: (keys: string[], into: SessionContext) => Promise<unknown>
+  /** Today round 2: today's calendar (lib/calendar-source.ts calendarToday). Read with the session reads, inside the
+   *  same wait; a failed, slow or unconnected read means no calendar in the prompt. */
+  calendar?: () => Promise<CalendarReading | null>
   now?: () => number
 }
 
-/** How long the sub-agent reads may hold the ask before it goes on without them. */
+/** How long the session reads may hold the ask before it goes on with what was read by then. */
 export const TODAY_BRIEF_SUBAGENT_WAIT_MS = 2_500
 
+/** What the server read per session: its sub-agents and its recent activity, by "provider|id". */
+export interface SessionContext { agents: Map<string, SubagentReading>; recent: Map<string, RecentActivity> }
+export const emptySessionContext = (): SessionContext => ({ agents: new Map(), recent: new Map() })
+
 /**
- * The server's own sub-agent reads: Claude from the session's transcript tail (lib/session-subagents.ts), Codex from
- * the spawn-edge snapshot (readCodexSubagentDetails, server home only). Cursor has none. Sequential, bounded, read-only.
+ * 2026-11-09: readSubagentsFor became this. For each key, most important first: the sub-agents (Claude from the
+ * transcript tail, Codex from the spawn-edge snapshot) and the recent activity (lib/agent-session-recent.ts). Claude
+ * and Cursor read one after another; Codex reads in parallel with them, because a Codex rollout's first scan is the
+ * slow one (32 GB files) and must not starve the rest. Results land in `into` as they arrive. Read-only.
  */
-export async function readSubagentsFor(keys: string[], now = Date.now()): Promise<Map<string, SubagentReading>> {
-  const out = new Map<string, SubagentReading>()
+export async function readSessionContext(keys: string[], into: SessionContext = emptySessionContext(), now = Date.now()): Promise<SessionContext> {
   const roots = agentSessionRoots()
-  const codex = keys.filter(k => k.startsWith('codex|')).map(k => k.slice(6))
-  for (const key of keys.filter(k => k.startsWith('claude|'))) {
-    const file = await findAgentSessionFile('claude', key.slice(7), roots).catch(() => null)
-    const read: SessionSubagents | null = file ? await readClaudeSubagents(file) : null
-    if (read && read.total) out.set(key, read)
-  }
-  if (codex.length) {
-    const details = await readCodexSubagentDetails(codex, roots.codexSessions, now)
+  const split = (k: string) => { const i = k.indexOf('|'); return { provider: k.slice(0, i) as AgentProvider, id: k.slice(i + 1) } }
+  const codexKeys = keys.filter(k => k.startsWith('codex|'))
+  const localKeys = keys.filter(k => k.startsWith('claude|') || k.startsWith('cursor|'))
+  const local = (async () => {
+    // One index for every Claude id in this ask, not one per call.
+    const claudeFiles = localKeys.some(k => k.startsWith('claude|')) ? await loadClaudeTranscriptIndex(roots).catch(() => undefined) : undefined
+    const aliases = claudeFiles ? await loadClaudeDesktopAliases(roots.claudeCodeSessions).catch(() => undefined) : undefined
+    for (const key of localKeys) {
+      const { provider, id } = split(key)
+      const file = await findAgentSessionFile(provider, id, roots, new Date(now), aliases, claudeFiles ? { claudeFiles } : undefined).catch(() => null)
+      if (!file) continue
+      if (provider === 'claude') {
+        const read: SessionSubagents | null = await readClaudeSubagents(file)
+        if (read && read.total) into.agents.set(key, read)
+      }
+      const recent = await readRecentActivity(provider, file, now)
+      if (recent) into.recent.set(key, recent)
+    }
+  })()
+  const codex = (async () => {
+    if (!codexKeys.length) return
+    const ids = codexKeys.map(k => k.slice(6))
+    const details = await readCodexSubagentDetails(ids, roots.codexSessions, now).catch(() => new Map())
     for (const [id, list] of details) {
-      const rows = list.map(d => ({ name: d.name, task: d.task, status: d.state === 'active' ? 'running' as const : d.state === 'completed' ? 'done' as const : 'unknown' as const, at: d.at }))
-      if (rows.length) out.set('codex|' + id, summarize(rows, false))
+      const rows = (list as Array<{ name: string; task: string; state: string; at: number }>).map(d => ({ name: d.name, task: d.task, status: d.state === 'active' ? 'running' as const : d.state === 'completed' ? 'done' as const : 'unknown' as const, at: d.at }))
+      // Every row, not six: the brief keeps the live and recent ones and counts the rest as history.
+      if (rows.length) into.agents.set('codex|' + id, summarize(rows, false, rows.length))
     }
-  }
-  return out
+    const lists = await Promise.all(codexSessionRootsOf(roots).map(root => listCodexJsonlFiles(root).catch(() => [] as string[])))
+    const codexFiles = lists.flat()
+    for (const key of codexKeys) {
+      const file = await findAgentSessionFile('codex', key.slice(6), roots, new Date(now), undefined, { codexFiles }).catch(() => null)
+      if (!file) continue
+      const recent = await readRecentActivity('codex', file, now)
+      if (recent) into.recent.set(key, recent)
+    }
+  })()
+  await Promise.all([local, codex])
+  return into
 }
 
-/** The server's own brief: the data folder, Haiku through the isolated text runner, one audit row per start. */
+/** The server's own brief: the data folder, Sonnet (7.0.1) through the isolated text runner, one audit row per start. */
 export function defaultTodayBrief(): TodayBrief {
   return createTodayBrief({
     stateFile: dataPath(TODAY_BRIEF_STATE_FILE),
@@ -81,8 +128,12 @@ export function defaultTodayBrief(): TodayBrief {
 }
 
 const IN_PROGRESS = new Set(['draft', 'built', 'qa'])
-/** Work cards in progress, by title and stage: open, not delegated, drafting to QA, or with an agent on it. */
-export function workInProgress(rows: TaskBoardRow[] | null): BriefWork[] {
+/**
+ * Work cards in progress, by title and stage: open, not delegated, drafting to QA, or with an agent on it. 2026-11-09:
+ * with when each last moved (the dated board read: the line's git change time, else the day it was created; null when
+ * neither is known), running first, then the most recently moved, so the twelve kept are the live ones.
+ */
+export function workInProgress(rows: Array<TaskBoardRow & Partial<TaskDateFields>> | null, now = Date.now()): BriefWork[] {
   if (!rows) return []
   const out: BriefWork[] = []
   for (const row of rows) {
@@ -90,9 +141,23 @@ export function workInProgress(rows: TaskBoardRow[] | null): BriefWork[] {
     const stage = row.workStage ?? (row.stage === 'active' ? 'draft' : row.stage === 'review' ? 'qa' : 'planned')
     const running = row.agentState === 'running'
     if (!IN_PROGRESS.has(stage) && !running) continue
-    out.push({ title: row.title || row.text || '', stage, running })
+    const at = Date.parse(row.lineChangedAt ?? '') || Date.parse(row.createdOn ?? '') || 0
+    out.push({ title: row.title || row.text || '', stage, running, movedMinutes: at > 0 ? Math.max(0, Math.round((now - at) / 60000)) : null })
   }
-  return out.sort((a, b) => Number(b.running) - Number(a.running)).slice(0, 12)
+  const age = (w: BriefWork) => (w.movedMinutes == null ? Number.MAX_SAFE_INTEGER : w.movedMinutes)
+  return out.sort((a, b) => Number(b.running) - Number(a.running) || age(a) - age(b)).slice(0, 12)
+}
+
+/**
+ * The body without `force` and `reason`, and what they asked. Anything but a boolean `force` is a bad request; 7.0.5
+ * `reason` may only be "reconnect".
+ */
+export function splitForce(raw: unknown): { body: unknown; force: boolean; reconnect: boolean } {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !('force' in raw || 'reason' in raw)) return { body: raw, force: false, reconnect: false }
+  const { force, reason, ...rest } = raw as Record<string, unknown>
+  if (force !== undefined && typeof force !== 'boolean') throw new TodayBriefInputError('invalid_today_brief')
+  if (reason !== undefined && reason !== 'reconnect') throw new TodayBriefInputError('invalid_today_brief')
+  return { body: rest, force: force === true, reconnect: reason === 'reconnect' }
 }
 
 export function createTodayBriefRouter(deps: TodayBriefRouterDeps): Router {
@@ -108,26 +173,40 @@ export function createTodayBriefRouter(deps: TodayBriefRouterDeps): Router {
       if (Buffer.byteLength(JSON.stringify(req.body ?? null)) > TODAY_BRIEF_BODY_MAX_BYTES) {
         return res.status(413).json({ error: { code: 'today_brief_too_large', message: 'Too much for the Today summary.' } })
       }
+      // 7.0.1: `force` is the refresh button's flag, taken off before the rows are read (the rows reject unknown keys).
+      const { body, force, reconnect } = splitForce(req.body)
       // The switch first: off reads nothing, not even the board.
       if (!deps.brief.settings().enabled) {
-        normalizeTodayBriefInputs(req.body)
+        normalizeTodayBriefInputs(body)
         return res.json(deps.brief.peek())
       }
-      // Every gate that needs no reads goes first (switch, recording, drain, breaker, daily cap, interval): a gated ask
-      // answers from the page's rows alone and reads neither the board nor any transcript.
-      const pageInputs = normalizeTodayBriefInputs(req.body)
-      const closed = deps.brief.gate()
+      // Every gate that needs no reads goes first (switch, recording, drain, breaker, daily cap, interval or, forced,
+      // the 30 s refresh floor): a gated ask answers from the page's rows alone and reads neither the board nor any
+      // transcript.
+      const pageInputs = normalizeTodayBriefInputs(body)
+      const closed = deps.brief.gate({ force, reconnect })
       if (closed) return res.json(deps.brief.askGated(pageInputs, closed))
-      const work = workInProgress(await deps.board().catch(() => null))
-      let inputs = normalizeTodayBriefInputs(req.body, work)
-      const keys = subagentLookups(inputs)
-      if (keys.length && deps.subagents) {
-        let timer: ReturnType<typeof setTimeout> | undefined
-        const late = new Promise<Map<string, SubagentReading>>(resolve => { timer = setTimeout(() => resolve(new Map()), TODAY_BRIEF_SUBAGENT_WAIT_MS) })
-        const readings = await Promise.race([deps.subagents(keys).catch(() => new Map<string, SubagentReading>()), late]).finally(() => clearTimeout(timer))
-        inputs = withSubagents(inputs, readings, (deps.now ?? Date.now)())
-      }
-      res.json(await deps.brief.ask(inputs, todayBriefFingerprint(pageInputs)))
+      const now = (deps.now ?? Date.now)()
+      // The board and the session reads run together; the reads stop being waited for after 2.5 s and the ask goes on
+      // with whatever they wrote by then (a Codex first scan that runs on still fills its memo for the next ask).
+      const keys = sessionContextLookups(normalizeTodayBriefInputs(body))
+      const context = emptySessionContext()
+      // Today round 2: the calendar reads alongside the sessions, inside the same wait; whatever has not answered by
+      // then is left out (a slow bridge never holds the ask).
+      const cal: { value: CalendarReading | null } = { value: null }
+      const work: Array<Promise<unknown>> = []
+      if (keys.length && deps.context) work.push(Promise.resolve().then(() => deps.context!(keys, context)).catch(() => undefined))
+      if (deps.calendar) work.push(Promise.resolve().then(() => deps.calendar!()).then(c => { cal.value = c }, () => undefined))
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const reads = work.length
+        ? Promise.race([Promise.all(work), new Promise<void>(resolve => { timer = setTimeout(resolve, TODAY_BRIEF_SUBAGENT_WAIT_MS) })]).finally(() => clearTimeout(timer))
+        : Promise.resolve()
+      const [rows] = await Promise.all([deps.board().catch(() => null), reads])
+      // A snapshot: a read still running after the wait cannot change the inputs under the call.
+      const agents = new Map(context.agents), recent = new Map(context.recent), calendar = cal.value
+      let inputs = normalizeTodayBriefInputs(body, workInProgress(rows, now))
+      inputs = withCalendar(withRecentActivity(withSubagents(inputs, agents, now), recent, now), calendar, now)
+      res.json(await deps.brief.ask(inputs, todayBriefFingerprint(pageInputs), { force, reconnect }))
     } catch (error) {
       if (error instanceof TodayBriefInputError) return res.status(400).json({ error: { code: error.code, message: 'That is not a Today summary request.' } })
       console.warn(`[today-brief] ask failed (${error instanceof Error ? error.name : 'error'})`)
@@ -144,5 +223,16 @@ export function createTodayBriefRouter(deps: TodayBriefRouterDeps): Router {
     }
     try { res.json(deps.brief.setEnabled(body.enabled)) } catch { failed(res) }
   })
+  // 7.0.5 "Summaries per day" (Control Web Settings and COS Control use the same route).
+  router.get('/today/brief/settings/cap', (_req, res) => {
+    try { res.json(deps.brief.cap()) } catch { failed(res) }
+  })
+  router.put('/today/brief/settings/cap', (req, res) => {
+    const body = req.body
+    if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(k => k !== 'dailyCap') || typeof body.dailyCap !== 'number' || !Number.isFinite(body.dailyCap)) {
+      return res.status(400).json({ error: { code: 'invalid_today_brief_cap', message: 'Send { dailyCap: a number from 1 to 100 }.' } })
+    }
+    try { res.json(deps.brief.setDailyCap(body.dailyCap)) } catch { failed(res) }
+  })
   return router
 }

package/server/routes/web-control.ts

@@ -24,6 +24,10 @@ import {
   type WebLoginFailure,
   WebGlassesCodeProbeBudget,
   WEB_SESSION_TTL_MS,
+  WEB_SESSION_COOKIE_NAME,
+  WEB_SESSION_MAX_LIFE_MS,
+  readWebSessionCookie,
+  webSessionCookieFrom,
   WebHandoffStore,
   WebLoginLimiter,
   WebDeviceCodeStore,
@@ -199,6 +203,18 @@ export function webControlCsp(_requestPath: string): string {
   ].join('; ')
 }
 
+/**
+ * The expiry (ISO) of the cos_web_session cookie on a request, read from the SAME value the verifier reads (Q1 S1:
+ * `parseCookies` keeps the last of several; another app on this host name can plant an earlier one). Read only after
+ * verification. Shapes: `<exp>.<epoch>.<sig>`, or a renewed `<exp>.<epoch>.<orig>.<sig>`.
+ */
+export function webSessionCookieExpiry(cookieHeader: unknown): string | null {
+  const value = webSessionCookieFrom(cookieHeader)
+  const exp = typeof value === 'string' ? /^(\d{1,15})\./.exec(value) : null
+  const ms = exp ? Number(exp[1]) * 1000 : NaN
+  return Number.isSafeInteger(ms) && ms > 0 ? new Date(ms).toISOString() : null
+}
+
 export function createWebControlRouter(deps: WebControlRouterDeps): Router {
   const router = Router()
   const handoffStore = deps.handoffStore ?? new WebHandoffStore()
@@ -287,11 +303,20 @@ export function createWebControlRouter(deps: WebControlRouterDeps): Router {
         ? { authenticated: false, mode: 'none' }
         : { authenticated: false, mode: 'none', network: 'tailscale_only' })
     }
+    // W1 (audit 02 F2): a signed-in browser learns when ITS OWN cookie ends, so the page can say so before it does.
+    // Only after the cookie verified (its signature covers the expiry), only for cookie mode, and nothing a caller without
+    // that cookie can read. The 7-day lifetime itself is unchanged.
+    const expiresAt = cookieOk && !headerOk ? webSessionCookieExpiry(req.headers.cookie) : null
+    // Renewal (Miles 2026-11-09): the latest this sign-in can last while in use, 30 days from its first sign-in.
+    const read = cookieOk && !headerOk ? readWebSessionCookie(webSessionCookieFrom(req.headers.cookie), token) : null
+    const renewUntil = read ? new Date((read.origUnixSec + Math.floor(WEB_SESSION_MAX_LIFE_MS / 1000)) * 1000).toISOString() : null
     res.json({
       authenticated: true,
       mode: headerOk ? 'header' : 'cookie',
       serverName: hostname().replace(/\.local$/i, ''),
       ownerName: getOwnerName(),
+      ...(expiresAt ? { expiresAt } : {}),
+      ...(renewUntil ? { renewUntil } : {}),
     })
   })
 
@@ -322,10 +347,13 @@ export function createWebControlRouter(deps: WebControlRouterDeps): Router {
     const token = deps.apiToken()
     const result = classifyWebLogin(body, token, handoffStore, deviceCodes, glassesCheck)
     if (!result.ok) {
-      // Every failure counts, the glasses-code one included, so that check cannot be used to
-      // probe codes faster than the limiter allows.
-      loginLimiter.fail(ip, result.reason)
-      log(`[web-login] fail kind=${result.reason} len=${result.length} ip=${ip}`)
+      // Every failure counts toward the per-IP limit, the glasses-code one included, so that check cannot be used to
+      // probe codes faster than the limiter allows. Except a failed sign-in LINK (Miles 2026-11-09 20:00, "Yes, stop
+      // counting stale links"): a ticket is 192 random bits, so guessing one is not a risk, and a person reopening an old
+      // QR or link should not lock themselves out of typing a code. It still fails with the same message.
+      if (result.reason !== 'handoff_expired') loginLimiter.fail(ip, result.reason)
+      // S1 item 7: why a handoff link failed (expired, used, evicted, unknown). The log only; the message is unchanged.
+      log(`[web-login] fail kind=${result.reason}${result.handoff ? ` sub=${result.handoff}` : ''} len=${result.length} ip=${ip}`)
       return res.status(401).json({
         ok: false,
         error: 'invalid_credentials',
@@ -340,6 +368,8 @@ export function createWebControlRouter(deps: WebControlRouterDeps): Router {
     return res.json({
       ok: true,
       expiresAt: new Date(minted.expiresAtMs).toISOString(),
+      // Renewal (Miles 2026-11-09): while in use this sign-in renews up to 30 days from now (lib/web-session-auth.ts).
+      renewUntil: new Date((Math.floor(minted.expiresAtMs / 1000) - Math.floor(WEB_SESSION_TTL_MS / 1000) + Math.floor(WEB_SESSION_MAX_LIFE_MS / 1000)) * 1000).toISOString(),
       serverName: hostname().replace(/\.local$/i, ''),
       ownerName: getOwnerName(),
     })
@@ -357,6 +387,9 @@ export function createWebControlRouter(deps: WebControlRouterDeps): Router {
   router.post('/web-session/revoke-all', (req: Request, res: Response) => {
     res.set('Cache-Control', 'private, no-store')
     const epoch = bumpWebSessionEpoch()
+    // Final review V7: a sign-in link or code made before the sign-out no longer signs a browser in after it.
+    handoffStore.revokeAll()
+    deviceCodes.revokeAll()
     res.setHeader('Set-Cookie', formatClearWebSessionCookie(req.secure))
     res.json({ ok: true, epoch })
   })

package/server/routes/web-key.ts

@@ -0,0 +1,284 @@
+// /api/web-key/*: the enrolled phone key registry and enrollment ceremony (6.99.31, plan §4.3,
+// §4.7). Behind COS_WEB_KEY_AUTHORITY (default off). Off, none of these is a route (each falls
+// through to next(), exactly as on 6.99.29).
+//
+// WHO MAY CALL WHAT:
+//   - The phone's steps (enroll start, prove, status, nonce) need the WEB path: the signed cookie,
+//     no X-Cos-Token header, and a socket that is not this Mac (the same judgment as a web turn).
+//     A token-bearing, loopback or own-address request is refused: an agent on this Mac cannot
+//     start an enrollment for a key it made.
+//   - COS Control's steps (pending, approve) need X-Cos-Token, and approve ALSO needs the anchor's
+//     Secure Enclave signature over the frozen approval (Touch ID). The token alone approves nothing.
+//   - Revoke, revoke-all and the key list take either the token or the web path. Revocation never
+//     needs the anchor, so a lost phone can always be revoked (by a token holder too: denial of
+//     service only, logged in web-key-audit.jsonl).
+//   - Anchor registration (review B1) is COS Control's bootstrap: loopback socket only, no proxy
+//     headers, X-Cos-Token, and the anchor's own signature over its `cos-web-anchor/1` statement. A
+//     new anchor vouches nothing for 24 hours; the turn answer exposes its fingerprint and age so
+//     the verifier compares it with Miles's committed pin.
+//   - Approval packets name their creating session from the request context (`x-cos-provider`,
+//     `x-cos-session-id`), never from body text (review B4).
+//   - Phase 3: the phone's key steps (enroll start and prove, nonce) answer only on the 3144 signer
+//     listener when `isSignerRequest` is wired (index.ts), so a page on 3143 cannot make a key.
+//   - Phase 3 handoff: the composer creates one on the web path (the destination comes from the
+//     binding, never the body); only the signer page claims it, once, on 3144, naming its origin.
+//   - 7.0.9 anchor bootstrap (COS_WEB_KEY_ANCHOR_BOOTSTRAP on, COS_WEB_KEY_AUTHORITY off): ONLY
+//     GET status (X-Cos-Token only, reply `enabled: false, mode: 'bootstrap'`) and POST anchor (as
+//     above) answer. Every other route falls through exactly as with both switches off.
+
+import { Router, type Request, type Response, type NextFunction } from 'express'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import { hasProxyForwardedHeaders, isLoopbackAddress, normalizeRemoteIp } from '../lib/network-policy.js'
+import { WEB_KEY_ENABLED_APPROVE_ACTIONS, type WebKeyAuthority } from '../lib/web-key-authority.js'
+import { WEB_ANCHOR_MATURITY_MS, type WebKeyEnrollments } from '../lib/web-key-registry.js'
+import { parseHandoffRequest, type WebKeySignHandoffs } from '../lib/web-key-handoff.js'
+import type { WebApprovalPacket, WebTurnScope } from '../../shared/web-turn-envelope.js'
+
+export const ANCHOR_REGISTRATION_LOOPBACK_COPY = 'The COS Control anchor key can only be registered by COS Control on this Mac.'
+
+export interface WebKeyRouterDeps {
+  authority: WebKeyAuthority
+  enrollments: WebKeyEnrollments
+  /** The web path in full: cookie, no token, a socket that is not this Mac (G2TurnProvenance.originOf). */
+  isWebRequest: (req: Request) => boolean
+  apiToken: () => string
+  selfDnsName: () => string | null
+  expectedOrigin: () => string | null
+  /** Served-asset integrity (Phase 6) for Control's audit; absent: not reported. */
+  integrityStatus?: () => Record<string, unknown>
+  /**
+   * Phase 3: whether this request reached the 3144 signer listener (index.ts: the socket's local
+   * port). Given, the phone's key steps (enroll start and prove, nonce) and the handoff claim answer
+   * only there, so a page on 3143 can neither make a key nor fetch a handoff. Absent (tests that
+   * predate the signer): not checked, exactly as before.
+   */
+  isSignerRequest?: (req: Request) => boolean
+  /** Phase 3: the 3143 to 3144 handoff store. Absent: the handoff routes answer 404 `handoff_unavailable`. */
+  handoffs?: WebKeySignHandoffs
+  /** Phase 3: the binding's real destination, as the turn route will resolve it. Null: no such binding. */
+  resolveBinding?: (bindingId: string) => { provider: string; sessionId: string; epoch: number; targetKey: string } | null
+}
+
+export const SIGNER_ORIGIN_REQUIRED = 'signer_origin_required'
+
+export function createWebKeyRouter(deps: WebKeyRouterDeps): Router {
+  const router = Router()
+
+  const on = (req: Request, res: Response, next: NextFunction): void => {
+    if (!deps.authority.enabled()) { next('router'); return }
+    res.set('Cache-Control', 'private, no-store')
+    next()
+  }
+  const hasToken = (req: Request): boolean => {
+    let expected = ''
+    try { expected = deps.apiToken() } catch { expected = '' }
+    return expected.length > 0 && timingSafeTokenEqual(req.headers['x-cos-token'], expected)
+  }
+  const web = (req: Request): boolean => {
+    try { return deps.isWebRequest(req) === true } catch { return false }
+  }
+  const refuse = (res: Response, status: number, error: string, extra: Record<string, unknown> = {}): void => {
+    res.status(status).json({ ok: false, error, ...extra })
+  }
+  const by = (req: Request): string => (hasToken(req) ? 'token' : 'web')
+  const body = (req: Request): Record<string, unknown> => (req.body && typeof req.body === 'object' ? req.body as Record<string, unknown> : {})
+  /** On the 3144 listener, when the deployment can tell (Phase 3). Never throws. */
+  const onSigner = (req: Request): boolean => {
+    if (!deps.isSignerRequest) return true
+    try { return deps.isSignerRequest(req) === true } catch { return false }
+  }
+
+  // 7.0.9: status and anchor registration answer in either mode; with both switches off they fall
+  // through like every other route. They sit BEFORE `on`, which still gates everything else on the
+  // authority alone.
+  const anchorRoutes = (req: Request, res: Response, next: NextFunction): void => {
+    if (deps.authority.mode() === 'off') { next('router'); return }
+    res.set('Cache-Control', 'private, no-store')
+    next()
+  }
+
+  router.get('/web-key/status', anchorRoutes, (req, res) => {
+    const registry = deps.authority.registry
+    const selfDns = deps.selfDnsName()
+    if (deps.authority.mode() !== 'authority') {
+      // Bootstrap only: COS Control's anchor state, nothing that suggests approvals. Token only:
+      // no web page needs it while no phone can enroll. `enabled: false` keeps older Controls hidden.
+      if (!hasToken(req)) return refuse(res, 401, 'unauthorized')
+      const anchor = registry.anchor()
+      return void res.json({
+        ok: true,
+        enabled: false,
+        mode: 'bootstrap',
+        anchorRegistered: anchor !== null,
+        anchorMature: registry.anchorMature(),
+        anchorSetAt: anchor ? anchor.setAt : null,
+        aud: registry.aud(selfDns),
+        origin: deps.expectedOrigin(),
+        epoch: registry.epoch(),
+      })
+    }
+    if (!hasToken(req) && !web(req)) return refuse(res, 401, 'unauthorized')
+    res.json({
+      ok: true,
+      enabled: true,
+      anchorRegistered: registry.anchor() !== null,
+      anchorRefusal: registry.anchorRefusal(),
+      anchorMature: registry.anchorMature(),
+      registryReadable: !registry.unreadable,
+      nonceStoreReadable: !deps.authority.nonces.unavailable,
+      aud: registry.aud(selfDns),
+      origin: deps.expectedOrigin(),
+      epoch: registry.epoch(),
+      activeKeys: registry.activeCount(selfDns),
+      ...(deps.integrityStatus ? { integrity: deps.integrityStatus() } : {}),
+    })
+  })
+
+  router.post('/web-key/anchor', anchorRoutes, (req, res) => {
+    // Loopback socket, no forwarding headers (a local proxy makes every caller loopback), and the token.
+    const addr = normalizeRemoteIp(req.socket?.remoteAddress ?? '')
+    if (!addr || !isLoopbackAddress(addr) || hasProxyForwardedHeaders(req.headers)) return refuse(res, 403, 'loopback_required', { reasonCopy: ANCHOR_REGISTRATION_LOOPBACK_COPY })
+    if (!hasToken(req)) return refuse(res, 401, 'token_required')
+    const b = body(req)
+    const result = deps.authority.registry.registerAnchor({ anchorPub: b.anchorPub, statement: b.statement, signature: b.signature }, 'control')
+    if (!result.ok) return refuse(res, result.reason === 'registry_write_failed' || result.reason === 'registry_unreadable' ? 503 : result.reason === 'anchor_signature_invalid' ? 403 : 400, result.reason)
+    res.status(201).json({ ...result, maturesAt: result.setAt + WEB_ANCHOR_MATURITY_MS })
+  })
+
+  // Everything below: the authority only (bootstrap mode falls through here, as with both off).
+  router.use('/web-key', on)
+
+  router.post('/web-key/enroll/start', (req, res) => {
+    if (!web(req)) return refuse(res, 403, 'web_origin_required')
+    if (!onSigner(req)) return refuse(res, 403, SIGNER_ORIGIN_REQUIRED)
+    const b = body(req)
+    const result = deps.enrollments.start({
+      spki: b.spki,
+      label: b.label,
+      rotates: b.rotates,
+      sasCommit: b.sasCommit,
+      userAgent: typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : '',
+      remote: req.socket?.remoteAddress ?? 'unknown',
+    }, { selfDnsName: deps.selfDnsName(), origin: deps.expectedOrigin() })
+    if (!result.ok) return refuse(res, result.reason === 'device_not_allowed' ? 403 : result.reason === 'enrollment_pending' || result.reason === 'key_cap_reached' || result.reason === 'key_already_enrolled' ? 409 : 400, result.reason)
+    res.status(201).json(result)
+  })
+
+  router.post('/web-key/enroll/prove', (req, res) => {
+    if (!web(req)) return refuse(res, 403, 'web_origin_required')
+    if (!onSigner(req)) return refuse(res, 403, SIGNER_ORIGIN_REQUIRED)
+    const b = body(req)
+    const result = deps.enrollments.prove({ enrollId: b.enrollId, signature: b.signature, phoneNonce: b.phoneNonce, passkey: b.passkey })
+    if (!result.ok) return refuse(res, result.reason === 'enroll_unknown' ? 404 : 400, result.reason)
+    res.json(result)
+  })
+
+  router.get('/web-key/enroll/status', (req, res) => {
+    if (!web(req) && !hasToken(req)) return refuse(res, 401, 'unauthorized')
+    res.json({ ok: true, status: deps.enrollments.status(req.query.enrollId) })
+  })
+
+  router.get('/web-key/enroll/pending', (req, res) => {
+    if (!hasToken(req)) return refuse(res, 401, 'token_required')
+    res.json({ ok: true, pending: deps.enrollments.pendingView() })
+  })
+
+  router.post('/web-key/enroll/approve', (req, res) => {
+    if (!hasToken(req)) return refuse(res, 401, 'token_required')
+    const b = body(req)
+    const result = deps.enrollments.approve(b.enrollId, b.anchorSig, deps.selfDnsName())
+    if (!result.ok) return refuse(res, result.reason === 'enroll_unknown' ? 404 : result.reason === 'anchor_signature_invalid' ? 403 : 409, result.reason)
+    res.json(result)
+  })
+
+  router.get('/web-key/keys', (req, res) => {
+    if (!hasToken(req) && !web(req)) return refuse(res, 401, 'unauthorized')
+    res.json({ ok: true, epoch: deps.authority.registry.epoch(), keys: deps.authority.registry.list(deps.selfDnsName()) })
+  })
+
+  router.post('/web-key/revoke', (req, res) => {
+    if (!hasToken(req) && !web(req)) return refuse(res, 401, 'unauthorized')
+    const b = body(req)
+    if (typeof b.kid !== 'string') return refuse(res, 400, 'invalid_request')
+    const reason = typeof b.reason === 'string' && b.reason.trim() ? b.reason.trim() : 'revoked'
+    if (!deps.authority.registry.revoke(b.kid, reason, by(req))) return refuse(res, 404, 'key_unknown')
+    res.json({ ok: true, kid: b.kid, revoked: true })
+  })
+
+  router.post('/web-key/revoke-all', (req, res) => {
+    if (!hasToken(req) && !web(req)) return refuse(res, 401, 'unauthorized')
+    res.json({ ok: true, epoch: deps.authority.registry.revokeAll(by(req)) })
+  })
+
+  router.post('/web-key/nonce', (req, res) => {
+    if (!web(req)) return refuse(res, 403, 'web_origin_required')
+    if (!onSigner(req)) return refuse(res, 403, SIGNER_ORIGIN_REQUIRED)
+    const issued = deps.authority.nonces.issue()
+    if (!issued.ok) return refuse(res, 503, issued.reason)
+    res.status(201).json({ ok: true, nonce: issued.nonce, exp: issued.exp, aud: deps.authority.registry.aud(deps.selfDnsName()), epoch: deps.authority.registry.epoch() })
+  })
+
+  router.post('/web-key/packets', (req, res) => {
+    // A packet is only a request (a receiving session asks Miles to approve one exact action).
+    if (!hasToken(req)) return refuse(res, 401, 'token_required')
+    // The creating session comes from the request context, never the body (review B4).
+    const header = (name: string): string | null => { const v = req.headers[name]; return typeof v === 'string' && v.trim() ? v.trim() : null }
+    const created = deps.authority.packets.create(body(req), { provider: header('x-cos-provider'), sessionId: header('x-cos-session-id') })
+    if (!created.ok) return refuse(res, created.reason === 'packet_cap_reached' ? 409 : created.reason === 'creator_unknown' ? 401 : 400, created.reason)
+    res.status(201).json({ ok: true, packet: created.packet, packetSha256: created.packetSha256 })
+  })
+
+  router.get('/web-key/packets', (req, res) => {
+    if (!hasToken(req) && !web(req)) return refuse(res, 401, 'unauthorized')
+    const provider = req.query.provider, sessionId = req.query.sessionId
+    if ((provider !== undefined || sessionId !== undefined) && (typeof provider !== 'string' || !['claude', 'codex', 'cursor'].includes(provider) || typeof sessionId !== 'string' || !sessionId || sessionId.length > 128)) return refuse(res, 400, 'invalid_target')
+    const packets = deps.authority.packets.list().filter(row => WEB_KEY_ENABLED_APPROVE_ACTIONS.has(row.packet.action)
+      && (provider === undefined || (row.packet.provider === provider && row.packet.sessionId === sessionId)))
+    res.json({ ok: true, packets })
+  })
+
+  // ── Phase 3: the handoff from the Control Web composer (3143) to the signer page (3144) ──
+  // Create: the composer, on the web path. The destination is the binding's, never the body's.
+  router.post('/web-key/handoff', (req, res) => {
+    if (!web(req)) return refuse(res, 403, 'web_origin_required')
+    if (!deps.handoffs || !deps.resolveBinding) return refuse(res, 404, 'handoff_unavailable')
+    const signerOrigin = deps.expectedOrigin()
+    if (!signerOrigin) return refuse(res, 503, 'origin_unavailable')
+    if (deps.authority.registry.activeCount(deps.selfDnsName()) < 1) return refuse(res, 409, 'no_phone_key')
+    const parsed = parseHandoffRequest(req.body)
+    if (!parsed.ok) return refuse(res, 400, parsed.reason)
+    const { request } = parsed
+    let target: ReturnType<NonNullable<WebKeyRouterDeps['resolveBinding']>> = null
+    try { target = deps.resolveBinding(request.turn.bindingId) } catch { target = null }
+    if (!target) return refuse(res, 404, 'unknown_binding')
+    if (target.epoch !== request.turn.epoch || target.targetKey !== request.turn.targetKey) return refuse(res, 409, 'binding_changed')
+    let scope: WebTurnScope = { kind: 'message' }
+    let approvalPacket: WebApprovalPacket | null = null
+    if (request.packetSha256) {
+      const packet = deps.authority.packets.get(request.packetSha256)
+      if (!packet) return refuse(res, 404, 'packet_unknown')
+      if (!WEB_KEY_ENABLED_APPROVE_ACTIONS.has(packet.action)) return refuse(res, 400, 'approve_action_not_enabled')
+      // A packet is signable only for the session that asked for it (review B4).
+      if (packet.provider !== target.provider || packet.sessionId !== target.sessionId) return refuse(res, 409, 'packet_session_mismatch')
+      scope = { kind: 'approve', action: packet.action, artifact: packet.artifact, version: packet.version, digest: packet.digest, channel: packet.channel, packetSha256: request.packetSha256 }
+      approvalPacket = packet
+    }
+    const created = deps.handoffs.create(request, { provider: target.provider, sessionId: target.sessionId }, scope, approvalPacket)
+    if (!created.ok) return refuse(res, created.reason === 'handoff_cap_reached' ? 409 : 400, created.reason)
+    // The id rides in the fragment: never sent to a server, never in a Referer. The words are not in it.
+    res.status(201).json({ ok: true, handoffId: created.handoffId, exp: created.exp, signerUrl: `${signerOrigin}/#h=${created.handoffId}` })
+  })
+
+  // Claim: the signer page, once, on its own listener and naming its own origin.
+  router.post('/web-key/handoff/claim', (req, res) => {
+    if (!web(req)) return refuse(res, 403, 'web_origin_required')
+    if (!deps.handoffs) return refuse(res, 404, 'handoff_unavailable')
+    const signerOrigin = deps.expectedOrigin()
+    if (!deps.isSignerRequest || !onSigner(req) || !signerOrigin || req.headers.origin !== signerOrigin) return refuse(res, 403, SIGNER_ORIGIN_REQUIRED)
+    const claimed = deps.handoffs.claim(body(req).handoffId)
+    if (!claimed.ok) return refuse(res, claimed.reason === 'handoff_unknown' ? 404 : claimed.reason === 'handoff_expired' ? 410 : 409, claimed.reason)
+    res.json({ ok: true, handoff: claimed.handoff })
+  })
+
+  return router
+}