@gotcos/glasses-server 6.99.25 → 6.99.29

package/server/routes/thread-turn-queue.ts

@@ -15,6 +15,7 @@
 //
 // EVERY DEPENDENCY IS INJECTED so the whole path is testable without a live server.
 
+import { randomBytes } from 'node:crypto'
 import { Router, type Request, type Response } from 'express'
 import { CONTINUE_NOTE_HEADER, continueNoteAcknowledged } from '../lib/continue-plan.js'
 import { nativeQueueControl, plainQueueText, type NativeQueueControl } from '../lib/codex-queue-control.js'
@@ -29,8 +30,24 @@ import { readQueue, writeQueue, queuedThreadKeys } from '../lib/thread-turn-queu
 import type { DeliveryEvidence } from '../lib/queue-turn-evidence.js'
 import { continueLiveEnabled } from '../lib/session-peer-inbox-deps.js'
 import { PEER_VERIFY_TIMEOUT_MS } from '../lib/session-peer-inbox.js'
+import { attachmentsDigest, FOOTER_LINE_REFUSED_COPY, hasFooterShapedLine, stripG2TurnFooter, TURN_ID_IN_USE_COPY, unvouched, type G2TurnProvenance, type OriginVerdict } from '../lib/g2-turn-provenance.js'
+import { defaultTurnAttachmentStore, keepTurnAttachments, parseTurnAttachmentIds, TURN_ATTACHMENT_COPY, turnAttachmentManifest, type TurnAttachmentStore } from '../lib/session-turn-attachments.js'
+
+/**
+ * G2 authority Tier 1 (6.99.29, Codex audit of e4758a6): the verdict a parked turn's files allow, and
+ * the attachment digest its origin is sealed to. Files whose content cannot be read leave the turn
+ * unvouched (it still parks); no files is the empty digest and reads nothing.
+ */
+async function sealFiles(ids: readonly string[] | undefined, verdict: OriginVerdict, store: TurnAttachmentStore | undefined): Promise<{ verdict: OriginVerdict; attachments: string }> {
+  if (!Array.isArray(ids) || ids.length === 0) return { verdict, attachments: '' }
+  const manifest = await turnAttachmentManifest(ids, store)
+  if (!manifest.ok) return { verdict: unvouched(verdict, 'attachments_unsealable'), attachments: '' }
+  return { verdict, attachments: attachmentsDigest(manifest.manifest) }
+}
 
 export interface ThreadTurnQueueDeps {
+  /** 11/07: the media store a parked turn's `attachmentIds` are checked against. Absent: the real store. Tests pass a fake. */
+  turnAttachmentStore?: TurnAttachmentStore
   /** Re-runs the FULL occupancy gate. The drainer never decides attachability itself. */
   occupancy: (provider: string, threadId: string) => { attachable: boolean; reason: string | null }
   /** Did the holder's last transcript record end a turn? */
@@ -66,6 +83,13 @@ export interface ThreadTurnQueueDeps {
    * Stop hook. Absent: no Cursor turn is ever drained here, exactly as in 6.61.
    */
   cursorCliChat?: (threadId: string) => boolean
+  /**
+   * G2 authority Tier 1, with web origin (6.99.29), optional: the origin of each parked turn is
+   * captured here (and again on an edit or a Send again, each judged by its own request) and carried to
+   * its drain, forgotten on any settle; a steer and a native Codex queue edit are ledgered and
+   * footed like a turn. Absent: the 6.99.28 behaviour.
+   */
+  provenance?: G2TurnProvenance
   now: () => number
 
   // ------------------------------------------------------------- 6.78.0 (P3)
@@ -126,6 +150,8 @@ export function publicRow(turn: QueuedThreadTurn, position: number): Record<stri
     preview: turn.prompt.length > 80 ? `${turn.prompt.slice(0, 79)}…` : turn.prompt,
     ...(turn.reason ? { reason: turn.reason } : {}),
     ...(turn.settledAt ? { settledAt: turn.settledAt } : {}),
+    // 11/07: how many files wait with the words (never their ids or paths). Absent without files.
+    ...(Array.isArray(turn.attachmentIds) && turn.attachmentIds.length > 0 ? { attachments: turn.attachmentIds.length } : {}),
   }
   // 6.78.0: additive, and only while a P3 flag is on, so the row is the 6.77 bytes otherwise.
   // `resendable` is the per-row capability: present only when Send again can act on it.
@@ -211,6 +237,11 @@ export async function drainThread(
     if (index >= 0) { latest[index] = turn; writeQueue(provider, threadId, latest, durable ? { durable: true } : {}) }
   }
   let refusedGate: ReturnType<ThreadTurnQueueDeps['occupancy']> | null = null
+  // G2 authority Tier 1 (QA 6.99.29): a parked origin is forgotten on ANY settle (delivered,
+  // cancelled, refused, expired, given up). Only a row still `waiting` keeps it for its next attempt.
+  const forgetIfSettled = (turn: QueuedThreadTurn): void => {
+    if (turn.status !== 'waiting') deps.provenance?.forgetQueued(provider, threadId, turn.clientTurnId)
+  }
 
   for (const snapshot of queue) {
     const turn = readQueue(provider, threadId, deps.now()).find(t => t.clientTurnId === snapshot.clientTurnId)
@@ -259,6 +290,7 @@ export async function drainThread(
       turn.reason = decision === 'expire' ? 'queued_turn_expired' : 'delivery_attempts_exhausted'
       turn.settledAt = deps.now()
       retired += 1; persist(turn)
+      forgetIfSettled(turn)
       continue
     }
 
@@ -335,6 +367,7 @@ export async function drainThread(
       held += 1
     }
     persist(turn)
+    forgetIfSettled(turn)
   }
   return { delivered, held, retired }
 }
@@ -451,8 +484,15 @@ async function steerTurn(
   queue: QueuedThreadTurn[],
   gateReason: string | null,
   fallbackNone: boolean,
+  verdict: OriginVerdict | null = null,
 ): Promise<unknown> {
   const { provider, threadId, clientTurnId, prompt } = turn
+  // G2 authority Tier 1 (6.99.29): a steer goes straight into the running session through its peer
+  // inbox, so it is a delivery of its own and carries the footer like a turn.
+  const steerPrompt = deps.provenance && verdict ? deps.provenance.footed(prompt, clientTurnId, verdict, provider) : prompt
+  const ledgerSteer = (via: string): void => {
+    if (deps.provenance && verdict) deps.provenance.record({ turnId: clientTurnId, prompt, verdict, provider, sessionId: threadId, via })
+  }
   const intent: QueuedThreadTurn = {
     ...turn,
     status: 'delivering',
@@ -462,7 +502,10 @@ async function steerTurn(
     ...(typeof deps.bootId === 'string' && deps.bootId.length > 0 ? { deliveringBootId: deps.bootId } : {}),
   }
   const admitted = admitToQueue(queue, intent)
-  if (!admitted.ok) return res.status(409).json({ error: admitted.reason })
+  if (!admitted.ok) {
+    deps.provenance?.forgetQueued(provider, threadId, clientTurnId)
+    return res.status(409).json({ error: admitted.reason })
+  }
   writeQueue(provider, threadId, admitted.queue, { durable: true })
 
   /** Rewrite this row on the CURRENT file: other requests may have changed others meanwhile. */
@@ -470,6 +513,9 @@ async function steerTurn(
     const latest = readQueue(provider, threadId, deps.now())
     const row = latest.find(t => t.clientTurnId === clientTurnId)
     if (row) { apply(row); writeQueue(provider, threadId, latest, { durable: true }) }
+    // G2 authority Tier 1 (QA 6.99.29): a steer that settled (delivered or refused) forgets its
+    // parked origin; one put back to wait keeps it for the drain.
+    if (!row || row.status !== 'waiting') deps.provenance?.forgetQueued(provider, threadId, clientTurnId)
     return latest
   }
   const backToWaiting = (row: QueuedThreadTurn): void => {
@@ -502,7 +548,7 @@ async function steerTurn(
 
   let live: { ok: boolean; reason: string } | null = null
   try {
-    live = await deps.deliverLiveTurn!({ provider, sessionId: threadId, prompt, verifyTimeoutMs: PEER_VERIFY_TIMEOUT_MS, clientTurnId })
+    live = await deps.deliverLiveTurn!({ provider, sessionId: threadId, prompt: steerPrompt, verifyTimeoutMs: PEER_VERIFY_TIMEOUT_MS, clientTurnId })
   } catch (error) {
     console.error(`[thread-turn-queue] steer delivery threw: ${error instanceof Error ? error.message : error}`)
     live = null
@@ -515,11 +561,13 @@ async function steerTurn(
 
   if (live?.ok === true) {
     journal('sent')
+    ledgerSteer('steer')
     settleRow(row => { row.status = 'delivered'; row.reason = 'steered'; row.settledAt = at })
     return res.status(200).json({ state: 'delivered', reason: 'steered', clientTurnId })
   }
   if (live === null || live.reason === 'unverified' || live.reason === 'write_failed') {
     journal('unknown')
+    ledgerSteer('steer-unverified')
     settleRow(row => { row.status = 'refused'; row.reason = 'steer_unverified'; row.deliveryState = 'unknown'; row.settledAt = at })
     return res.status(200).json({
       state: 'refused',
@@ -560,10 +608,21 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       return res.status(400).json({ error: 'invalid_request', reason: 'invalid_cos_session_id' })
     }
 
+    // G2 authority Tier 1 (QA 6.99.29): only the server writes a verify footer. Words carrying
+    // anything footer-shaped are refused where they were typed (this is also the steer's door).
+    if (deps.provenance && hasFooterShapedLine(prompt)) {
+      return res.status(400).json({ error: 'footer_line_refused', reasonCopy: FOOTER_LINE_REFUSED_COPY })
+    }
+
+    // 11/07 (Control Web attach): files with the words, as media-store ids. Absent is the old row, byte for byte.
+    const attach = parseTurnAttachmentIds(body.attachmentIds)
+    if (!attach.ok) return res.status(400).json({ error: 'invalid_request', reason: 'invalid_attachments' })
+
     // 6.78.0: `mode: 'steer'` asks for the running turn itself (COS_SESSION_STEER). Off, the
     // field is ignored exactly as a 6.77 server ignores it.
     const steerOn = sessionSteerEnabled()
-    const wantSteer = steerOn && body.mode === 'steer'
+    // A steer goes through the session's peer inbox, which carries words only: a turn with files always parks.
+    const wantSteer = steerOn && body.mode === 'steer' && attach.ids.length === 0
     const fallbackNone = wantSteer && body.fallback === 'none'
 
     // 6.78.0: REPLAY BEFORE THE GATE. A key this queue already holds answers with what that
@@ -584,6 +643,14 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       }
     }
 
+    // G2 authority Tier 1 (6.99.29): who parked these words, judged on this request's own socket,
+    // token and cookie. A turn id this server already holds a record for, for a different turn, is
+    // never reused (QA 6.99.29: it would overwrite that record).
+    let verdict = deps.provenance ? deps.provenance.originOf(req) : null
+    if (deps.provenance && verdict && deps.provenance.reusesTurnId(clientTurnId, { prompt, verdict, provider, sessionId: threadId })) {
+      return res.status(409).json({ error: 'turn_id_in_use', reasonCopy: TURN_ID_IN_USE_COPY })
+    }
+
     // THE GATE DECIDES WHETHER PARKING IS EVEN HONEST. A structural refusal can never
     // clear, and telling someone their turn is queued when it can never run is worse
     // than refusing it. An attachable thread is not queued either -- it is sent now,
@@ -601,6 +668,14 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       return res.status(423).json({ error: gate.reason ?? 'probe_failed', queueable: false })
     }
 
+    // 11/07: every file must be readable now, and is kept past the 4 hour staged TTL while the turn waits. A file
+    // that is gone refuses the park here, where the words are still in the box, never later at the drain.
+    if (attach.ids.length > 0) {
+      const store = deps.turnAttachmentStore ?? defaultTurnAttachmentStore()
+      const kept = await keepTurnAttachments(attach.ids, `session-turn:${clientTurnId}`, store)
+      if (!kept.ok) return res.status(409).json({ error: kept.code, attachmentError: kept.code, reasonCopy: TURN_ATTACHMENT_COPY[kept.code] })
+    }
+
     const now = deps.now()
     const queue = readQueue(provider, threadId, now)
     const turn: QueuedThreadTurn = {
@@ -608,20 +683,33 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       queuedAt: now, status: 'waiting', attempts: 0,
       // 6.62.0 /qa (Q3): the acknowledgement travels with the row to its drain.
       ...(continueNoteAcknowledged(req.headers[CONTINUE_NOTE_HEADER]) ? { continueNoteAck: true as const } : {}),
+      ...(attach.ids.length > 0 ? { attachmentIds: attach.ids } : {}),
+    }
+
+    // Held in memory with the words' hash, sealed to this provider, thread and these files (each id
+    // with its content hash), so the drain can carry it (QUEUED_ORIGIN_TTL_MS at most).
+    if (deps.provenance && verdict) {
+      const sealed = await sealFiles(attach.ids, verdict, deps.turnAttachmentStore)
+      verdict = sealed.verdict
+      deps.provenance.noteQueued(provider, threadId, clientTurnId, prompt, verdict, sealed.attachments)
     }
 
     let steerFallback: string | null = null
     if (wantSteer) {
       const availability = steerAvailabilityFor(deps, provider, threadId, gate.reason)
-      if (availability.available) return steerTurn(req, res, deps, turn, queue, gate.reason, fallbackNone)
+      if (availability.available) return steerTurn(req, res, deps, turn, queue, gate.reason, fallbackNone, verdict)
       if (fallbackNone) return res.status(409).json({ error: 'steer_unavailable', reason: availability.reason })
       steerFallback = availability.reason
     }
 
     const admitted = admitToQueue(queue, turn)
-    if (!admitted.ok) return res.status(409).json({ error: admitted.reason })
+    if (!admitted.ok) {
+      deps.provenance?.forgetQueued(provider, threadId, clientTurnId)
+      return res.status(409).json({ error: admitted.reason })
+    }
 
     writeQueue(provider, threadId, admitted.queue)
+    if (deps.provenance && verdict) deps.provenance.record({ turnId: clientTurnId, prompt, verdict, provider, sessionId: threadId, via: 'queue' })
     return res.status(202).json({
       queued: true,
       clientTurnId,
@@ -639,7 +727,7 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
   // writing it, so two taps (lens and phone) in the same tick cannot both pass the check.
   // The new row is admitted even when the thread is free: the drain sends it through the
   // ordinary front door, with every gate.
-  router.post('/agent-sessions/:provider/:threadId/queued-turns/:clientTurnId/resend', (req: Request, res: Response, next) => {
+  router.post('/agent-sessions/:provider/:threadId/queued-turns/:clientTurnId/resend', async (req: Request, res: Response, next) => {
     // Off: not a route at all, exactly as on 6.77 (a client reads the 404 as "update the server").
     if (!queueResendEnabled()) return next()
     res.set('Cache-Control', 'private, no-store')
@@ -664,6 +752,14 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
         : { clientTurnId: original.resentAs, resendOf: original.clientTurnId, replayed: true })
     }
     if (original.status !== 'refused' && original.status !== 'expired') return res.status(409).json({ error: 'not_resendable' })
+    // G2 authority Tier 1 (QA 6.99.29): the copy's words go to a session, so they meet the footer
+    // rule like any typed words, and its id may not be one this server already holds a record for.
+    if (deps.provenance && hasFooterShapedLine(original.prompt)) {
+      return res.status(400).json({ error: 'footer_line_refused', reasonCopy: FOOTER_LINE_REFUSED_COPY })
+    }
+    if (deps.provenance && deps.provenance.holds(newId)) return res.status(409).json({ error: 'turn_id_in_use', reasonCopy: TURN_ID_IN_USE_COPY })
+    // Judged now, from THIS request (Codex re-audit of 910eb90, P1): never inherited from the row.
+    const resendVerdict = deps.provenance ? deps.provenance.resendVerdict(req) : null
     // "May not have been sent": a second copy is possible, so the person has to have been told.
     if (original.deliveryState === 'unknown' && body.acknowledge !== 'may_duplicate') {
       return res.status(409).json({ error: 'acknowledge_required' })
@@ -673,12 +769,26 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       prompt: original.prompt,
       queuedAt: now, status: 'waiting', attempts: 0,
       ...(original.continueNoteAck === true ? { continueNoteAck: true as const } : {}),
+      // 11/07: Send again sends the same files; the turns route refuses it there if one has gone.
+      ...(Array.isArray(original.attachmentIds) && original.attachmentIds.length > 0 ? { attachmentIds: [...original.attachmentIds] } : {}),
       resendOf: original.clientTurnId,
     }
     const admitted = admitToQueue(queue, copy)
     if (!admitted.ok) return res.status(409).json({ error: admitted.reason })
     original.resentAs = newId
     writeQueue(provider, threadId, admitted.queue)
+    // G2 authority Tier 1 (Codex re-audit of 910eb90, P1): the row's words and files are mutable, so
+    // the copy NEVER inherits the original row's authority (that let a local caller change a refused
+    // G2 row and mint a new vouched turn from it). It carries the origin of the request that sent it
+    // again: a verified glasses or phone client is vouched on its own socket and instance, like any
+    // new turn; anyone else is recorded unvouched ('resend_not_reverified'), with no footer. The
+    // original id is kept only as the record's `resendOf` annotation.
+    if (deps.provenance && resendVerdict) {
+      // After the write: the read-modify-write above stays one synchronous step. Sealed to the copy's files.
+      const sealed = await sealFiles(copy.attachmentIds, resendVerdict, deps.turnAttachmentStore)
+      deps.provenance.noteQueued(provider, threadId, newId, copy.prompt, sealed.verdict, sealed.attachments)
+      deps.provenance.record({ turnId: newId, prompt: copy.prompt, verdict: sealed.verdict, provider, sessionId: threadId, via: 'queue-resend', resendOf: original.clientTurnId })
+    }
     console.log(`[thread-turn-queue] resend provider=${provider} from=${original.clientTurnId} as=${newId} unknown=${original.deliveryState === 'unknown'}`)
     return res.status(200).json(publicRow(copy, queuePosition(admitted.queue, newId)))
   })
@@ -693,7 +803,9 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
     if (provider === 'codex') {
       try {
         native = (await (deps.nativeQueue ?? nativeQueueControl).list(threadId)).map((row, position) => {
-          const text = plainQueueText(row)
+          // G2 authority Tier 1: the lens and the web show (and edit) the words, never the verify footer.
+          const plain = plainQueueText(row)
+          const text = plain === null ? null : stripG2TurnFooter(plain).text
           return { clientTurnId: `codex-native:${row.id}`, status: 'waiting', position, queuedAt: 0,
             attempts: 0, preview: text?.slice(0, 80) ?? 'Message with attachments · manage in Codex',
             ...(text !== null ? { prompt: text } : {}), editable: text !== null, owner: 'codex' }
@@ -711,17 +823,44 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
     const provider = String(req.params.provider), threadId = String(req.params.threadId), id = String(req.params.clientTurnId)
     const prompt = req.body?.prompt
     if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > DEFAULT_MAX_PROMPT_CHARS) return res.status(400).json({ error: 'invalid_prompt' })
+    // G2 authority Tier 1 (QA 6.99.29): an edit is typed words like any other.
+    if (deps.provenance && hasFooterShapedLine(prompt)) {
+      return res.status(400).json({ error: 'footer_line_refused', reasonCopy: FOOTER_LINE_REFUSED_COPY })
+    }
     if (provider === 'codex' && id.startsWith('codex-native:')) {
       try {
-        await (deps.nativeQueue ?? nativeQueueControl).update(threadId, id.slice(13), prompt)
+        // G2 authority Tier 1: the edit replaces the text in the Codex app's own queue, so it is a
+        // delivery of its own, under an id minted here (the native row id is not ours).
+        let sent = prompt
+        if (deps.provenance) {
+          const verdict = deps.provenance.originOf(req)
+          const editId = `cnedit-${randomBytes(12).toString('hex')}`
+          sent = deps.provenance.footed(prompt, editId, verdict, provider)
+          deps.provenance.record({ turnId: editId, prompt, verdict, provider, sessionId: threadId, via: 'codex-native-edit' })
+        }
+        await (deps.nativeQueue ?? nativeQueueControl).update(threadId, id.slice(13), sent)
         return res.json({ updated: true })
       } catch { return res.status(409).json({ error: 'queue_edit_unconfirmed' }) }
     }
     const queue = readQueue(provider, threadId, deps.now())
     const row = queue.find(t => t.clientTurnId === id)
     if (!row || row.status !== 'waiting') return res.status(409).json({ error: 'already_delivering' })
+    // The words are now whoever edited them: their origin replaces the parked one. Only over a record
+    // that is still parked (QA 6.99.29): a row written into the queue file under a delivered turn's id
+    // cannot be edited over that turn's record.
+    const verdict = deps.provenance ? deps.provenance.originOf(req) : null
+    if (deps.provenance && verdict && deps.provenance.reusesTurnId(id, { prompt, verdict, provider, sessionId: threadId }, { continues: true })) {
+      return res.status(409).json({ error: 'turn_id_in_use', reasonCopy: TURN_ID_IN_USE_COPY })
+    }
     row.prompt = prompt
     writeQueue(provider, threadId, queue)
+    if (deps.provenance && verdict) {
+      // Sealed to the row's files as they are now (an edit changes only the words).
+      const sealed = await sealFiles(row.attachmentIds, verdict, deps.turnAttachmentStore)
+      deps.provenance.noteQueued(provider, threadId, id, prompt, sealed.verdict, sealed.attachments)
+      // The queue's own row, re-judged: it continues the record parked under this id.
+      deps.provenance.record({ turnId: id, prompt, verdict: sealed.verdict, provider, sessionId: threadId, via: 'queue-edit', continues: true })
+    }
     return res.json({ updated: true })
   })
 
@@ -748,6 +887,7 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       row.status = 'cancelled'
       row.settledAt = now
       writeQueue(provider, threadId, queue)
+      deps.provenance?.forgetQueued(provider, threadId, clientTurnId)
     }
     return res.json({ cancelled: true, clientTurnId, status: row.status })
   })

package/server/routes/today-brief.ts

@@ -0,0 +1,148 @@
+/**
+ * 6.99.26 candidate: the Today summary for COS Control Web (lib/today-brief.ts says how it stops: switch, caps, breaker).
+ *
+ * - 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
+ *                                   server's own shared board read, never the body.
+ * - 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.
+ * Auth is the parent /api gate (token or web session cookie). Every answer is private, no-store.
+ */
+import { Router } from 'express'
+import type { Response } from 'express'
+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 { readClaudeSubagents, summarize, type SessionSubagents } from '../lib/session-subagents.js'
+import { readCodexSubagentDetails } from '../lib/codex-subagent-activity.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,
+} 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>>
+  now?: () => number
+}
+
+/** How long the sub-agent reads may hold the ask before it goes on without them. */
+export const TODAY_BRIEF_SUBAGENT_WAIT_MS = 2_500
+
+/**
+ * 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.
+ */
+export async function readSubagentsFor(keys: string[], now = Date.now()): Promise<Map<string, SubagentReading>> {
+  const out = new Map<string, SubagentReading>()
+  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)
+    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))
+    }
+  }
+  return out
+}
+
+/** The server's own brief: the data folder, Haiku through the isolated text runner, one audit row per start. */
+export function defaultTodayBrief(): TodayBrief {
+  return createTodayBrief({
+    stateFile: dataPath(TODAY_BRIEF_STATE_FILE),
+    settingsFile: dataPath(TODAY_BRIEF_SETTINGS_FILE),
+    generate: (prompt, systemPrompt, model) => runClaudeText(prompt, {
+      model, effort: TODAY_BRIEF_EFFORT, timeoutMs: TODAY_BRIEF_TIMEOUT_MS, systemPrompt, label: 'Today brief',
+    }),
+    audit: row => logTokenAudit({
+      source: 'web-today-brief', model: row.model, inputChars: row.inputChars, outputChars: row.outputChars,
+      durationMs: row.durationMs, caller: row.outcome === 'ok' ? 'today_brief' : `today_brief_${row.guard ?? row.error ?? row.outcome}`,
+    }),
+    // No call while a meeting records (it keeps the Mac's CPU and the CLI for the meeting) or while the server drains.
+    blocked: () => (!maintenanceAdmissionsOpen() ? 'maintenance' : isRecordingLive() ? 'recording' : null),
+    // The call holds api_mutation, as the generic mutation lease would have; this route is lifecycle-owned in index.ts.
+    lease: () => acquireMaintenanceWork('api_mutation'),
+  })
+}
+
+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[] {
+  if (!rows) return []
+  const out: BriefWork[] = []
+  for (const row of rows) {
+    if (row.checked || row.delegated) continue
+    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 })
+  }
+  return out.sort((a, b) => Number(b.running) - Number(a.running)).slice(0, 12)
+}
+
+export function createTodayBriefRouter(deps: TodayBriefRouterDeps): Router {
+  const router = Router()
+  router.use('/today/brief', (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
+  const failed = (res: Response) => res.status(503).json({ error: { code: 'today_brief_unavailable', message: 'The Today summary is unavailable right now.' } })
+
+  router.get('/today/brief', (_req, res) => {
+    try { res.json(deps.brief.peek()) } catch { failed(res) }
+  })
+  router.post('/today/brief', async (req, res) => {
+    try {
+      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.' } })
+      }
+      // The switch first: off reads nothing, not even the board.
+      if (!deps.brief.settings().enabled) {
+        normalizeTodayBriefInputs(req.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()
+      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)))
+    } 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'})`)
+      failed(res)
+    }
+  })
+  router.get('/today/brief/settings', (_req, res) => {
+    try { res.json(deps.brief.settings()) } catch { failed(res) }
+  })
+  router.post('/today/brief/settings', (req, res) => {
+    const body = req.body
+    if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(k => k !== 'enabled') || typeof body.enabled !== 'boolean') {
+      return res.status(400).json({ error: { code: 'invalid_today_brief_settings', message: 'Send { enabled: true } or { enabled: false }.' } })
+    }
+    try { res.json(deps.brief.setEnabled(body.enabled)) } catch { failed(res) }
+  })
+  return router
+}

package/server/web-control/app.css

@@ -246,6 +246,8 @@ select.field {
 @keyframes rec { 50% { opacity: 0.35; } }
 
 .story { font: 400 24px/1.28 var(--display); letter-spacing: -0.005em; margin: 26px 2px; text-wrap: pretty; }
+/* The Today summary's quiet age line (app.js briefWhen). */
+.story-when { display: block; margin-top: 10px; font: 400 14px/1.35 var(--body); letter-spacing: 0; color: var(--sub); }
 .story-skel { display: grid; gap: 12px; margin: 30px 0; }
 .story-skel .skeleton { height: 22px; }