@gotcos/glasses-server 6.99.20 → 6.99.29

package/server/lib/turn-file-store.ts

@@ -0,0 +1,202 @@
+// Any file, for a session turn only (Miles, 2026-11-07: "We still don't have the ability to take picture, or add photo
+// or files from the web").
+//
+// The media store takes what a MODEL can read (photos, PDF, TXT, MD, CSV, JSON, XLSX, MP4, MOV): it extracts text and
+// frames, and an Ask, a Drop or Prep hands those to a model. A Claude or Codex session on this Mac is different: it gets
+// the file's path (lib/session-turn-attachments.ts) and opens it with its own tools, so a .zip, a .docx, a log or a
+// HEIC is useful there. This keeps those, and only those, beside the media store:
+//
+//   - Same upload: POST /api/media/file. Only when the upload says `X-COS-Purpose: session-turn` AND the media store
+//     refuses the file as a format it cannot read does the file land here instead (routes/media.ts).
+//   - Same ids (m_ + 24 hex), but never in the media index: an Ask, a Drop, Prep or GET /api/media/:id cannot find one
+//     (media_not_found), so a file no model can read never reaches a model. Only the turn and fork routes resolve them.
+//   - Same cap as the media store's own for a file that is not a video: 64 MB (MAX_OTHER_MEDIA_BYTES).
+//   - Kept 4 hours until a turn takes it, then 30 days. Swept on each new file, at boot and every 5 minutes after
+//     (startSweep, beside the media store's own GC; QA 6.99.27).
+//   - Each file is `<root>/<id>/file/<its own name, made safe>`, so the agent sees a real name and extension, and the
+//     record is `<root>/<id>/meta.json`, one folder up. No name a person gives a file can reach the record: on the
+//     default case-insensitive macOS disk a file named META.JSON beside the record WAS the record, and the record write
+//     replaced its bytes (QA, 6.99.27). Nothing here ever serves the bytes back over HTTP.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, copyFileSync, statSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { DATA_DIR } from './data-dir.js'
+import { atomicWriteFileSync } from './atomic-fs.js'
+import { MAX_OTHER_MEDIA_BYTES, RichMediaSafetyError } from './rich-media-safety.js'
+import { isValidMediaId, type MediaAttachmentRef } from '../../shared/media-attachment.js'
+import { MediaStoreError, MEDIA_GC_INTERVAL_MS } from './media-store.js'
+
+export const TURN_FILE_MAX_BYTES = MAX_OTHER_MEDIA_BYTES
+export const TURN_FILE_STAGED_TTL_MS = 4 * 60 * 60_000
+export const TURN_FILE_KEPT_TTL_MS = 30 * 24 * 60 * 60_000
+const PAYLOAD_DIR = 'file'
+
+interface TurnFileMeta {
+  id: string
+  name: string
+  label: string
+  mime: string
+  bytes: number
+  createdAtMs: number
+  associatedAtMs?: number
+  runId?: string
+}
+
+/** What the upload answers: an id and what it is. Never a path. */
+export interface TurnFileRef {
+  id: string
+  kind: 'session_file'
+  mime: string
+  bytes: number
+  label: string
+  createdAt: string
+}
+
+/** A filename the agent can read, that cannot climb out of its folder or carry control characters. */
+export function safeTurnFileName(label: string | undefined): string {
+  // eslint-disable-next-line no-control-regex
+  // QA 6.99.27: bidi controls go too, so the name on disk (and in the path the agent reads) shows as what it is.
+  let name = String(label ?? '').replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '')
+    .replace(/[\u0000-\u001f\u007f\u2028\u2029/\\:]+/g, ' ').replace(/\s+/g, ' ').trim()
+  name = name.replace(/^[.\s]+/, '').trimEnd()
+  if (!name) name = 'file'
+  if (name.length > 120) {
+    const dot = name.lastIndexOf('.')
+    const ext = dot > 0 && name.length - dot <= 12 ? name.slice(dot) : ''
+    name = name.slice(0, 120 - ext.length).trimEnd() + ext
+  }
+  return name
+}
+
+function safeMime(declared: string | undefined): string {
+  const m = String(declared ?? '').toLowerCase().split(';', 1)[0]!.trim()
+  return /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/.test(m) ? m : 'application/octet-stream'
+}
+
+export class TurnFileStore {
+  readonly root: string
+  private readonly now: () => number
+  constructor(root: string = join(DATA_DIR, 'turn-files'), now: () => number = Date.now) {
+    this.root = resolve(root)
+    this.now = now
+  }
+
+  private dirOf(id: string): string { return join(this.root, id) }
+  /** The file's own folder, apart from the record (see the header). */
+  private payloadDirOf(id: string): string { return join(this.root, id, PAYLOAD_DIR) }
+
+  private readMeta(id: string): TurnFileMeta | null {
+    if (!isValidMediaId(id)) return null
+    const path = join(this.dirOf(id), 'meta.json')
+    if (!existsSync(path)) return null
+    try {
+      const m = JSON.parse(readFileSync(path, 'utf8')) as TurnFileMeta
+      if (m.id !== id || typeof m.name !== 'string' || m.name !== safeTurnFileName(m.name) || typeof m.createdAtMs !== 'number') return null
+      return m
+    } catch { return null }
+  }
+
+  private expired(m: TurnFileMeta, now: number): boolean {
+    return typeof m.associatedAtMs === 'number' ? now - m.associatedAtMs > TURN_FILE_KEPT_TTL_MS : now - m.createdAtMs > TURN_FILE_STAGED_TTL_MS
+  }
+
+  /** Takes a staged upload (moved, else copied). Throws RichMediaSafetyError('attachment_too_large') past the cap. */
+  ingestFromFile(input: { sourcePath: string; byteLength: number; label?: string; declaredMime?: string }): TurnFileRef {
+    if (!Number.isSafeInteger(input.byteLength) || input.byteLength <= 0) throw new RichMediaSafetyError('corrupt_attachment', 'attachment is empty')
+    if (input.byteLength > TURN_FILE_MAX_BYTES) throw new RichMediaSafetyError('attachment_too_large', `attachment exceeds ${TURN_FILE_MAX_BYTES} byte limit`)
+    this.sweep()
+    const id = 'm_' + randomBytes(12).toString('hex')
+    const dir = this.dirOf(id)
+    const payloadDir = this.payloadDirOf(id)
+    mkdirSync(payloadDir, { recursive: true, mode: 0o700 })
+    const name = safeTurnFileName(input.label)
+    const target = join(payloadDir, name)
+    try {
+      renameSync(input.sourcePath, target)
+    } catch {
+      copyFileSync(input.sourcePath, target)
+    }
+    const now = this.now()
+    const meta: TurnFileMeta = { id, name, label: String(input.label ?? '').slice(0, 120) || name, mime: safeMime(input.declaredMime), bytes: input.byteLength, createdAtMs: now }
+    atomicWriteFileSync(join(dir, 'meta.json'), JSON.stringify(meta))
+    return { id, kind: 'session_file', mime: meta.mime, bytes: meta.bytes, label: meta.label, createdAt: new Date(now).toISOString() }
+  }
+
+  /** The file's ref (in the media ref's shape, for the turn's line) and path, or a media-store error. */
+  resolveUsable(id: string): { record: { ref: MediaAttachmentRef }; path: string } {
+    const m = this.readMeta(id)
+    if (!m) throw new MediaStoreError('media_not_found', `attachment ${id} not found`)
+    if (this.expired(m, this.now())) throw new MediaStoreError('media_expired', `attachment ${id} expired`)
+    const path = join(this.payloadDirOf(id), m.name)
+    if (!resolve(path).startsWith(this.payloadDirOf(id) + sep) || !existsSync(path)) throw new MediaStoreError('media_unavailable', `attachment ${id} content unavailable`)
+    // Shaped as a ref only for the line the agent reads (kind and mime are not in the media contract and never leave
+    // this server as one).
+    const ref = { id, kind: 'session_file', category: 'file', mime: m.mime, width: 0, height: 0, createdAt: new Date(m.createdAtMs).toISOString(), bytes: m.bytes, label: m.label } as unknown as MediaAttachmentRef
+    return { record: { ref }, path }
+  }
+
+  has(id: string): boolean { return this.readMeta(id) !== null }
+
+  /** Kept for 30 days from now: a turn took it. */
+  async associate(ids: string[], target: { runId?: string }): Promise<void> {
+    const now = this.now()
+    for (const id of ids) {
+      const m = this.readMeta(id)
+      if (!m) throw new MediaStoreError('media_not_found', `attachment ${id} not found`)
+      if (this.expired(m, now)) throw new MediaStoreError('media_expired', `attachment ${id} expired`)
+      m.associatedAtMs = now
+      if (target.runId) m.runId = target.runId.slice(0, 160)
+      atomicWriteFileSync(join(this.dirOf(id), 'meta.json'), JSON.stringify(m))
+    }
+  }
+
+  private sweepTimer: ReturnType<typeof setInterval> | null = null
+  /**
+   * QA 6.99.27 (Skeptic W2): a sweep at once and then every `intervalMs` (the media store's GC interval), so a file
+   * past its time goes even when no new file arrives. Before, only an upload swept. Idempotent; the timer never holds
+   * the process open.
+   */
+  startSweep(intervalMs: number = MEDIA_GC_INTERVAL_MS): void {
+    if (this.sweepTimer) return
+    this.sweep()
+    this.sweepTimer = setInterval(() => { this.sweep() }, intervalMs)
+    this.sweepTimer.unref?.()
+  }
+  stopSweep(): void {
+    if (this.sweepTimer) clearInterval(this.sweepTimer)
+    this.sweepTimer = null
+  }
+
+  /** Removes expired files and folders that are not ours. Never throws. */
+  sweep(): number {
+    let removed = 0
+    if (!existsSync(this.root)) return 0
+    const now = this.now()
+    let names: string[] = []
+    try { names = readdirSync(this.root) } catch { return 0 }
+    for (const name of names) {
+      const dir = join(this.root, name)
+      try {
+        if (!statSync(dir).isDirectory()) continue
+        const m = this.readMeta(name)
+        // A folder with no readable meta is a crashed upload once it is past the staged TTL.
+        const stale = m ? this.expired(m, now) : now - statSync(dir).mtimeMs > TURN_FILE_STAGED_TTL_MS
+        if (stale) { rmSync(dir, { recursive: true, force: true }); removed++ }
+      } catch { /* one bad folder never stops the sweep */ }
+    }
+    return removed
+  }
+}
+
+let defaultStore: TurnFileStore | null = null
+export function getTurnFileStore(): TurnFileStore {
+  if (!defaultStore) defaultStore = new TurnFileStore()
+  return defaultStore
+}
+/** Test hook. */
+export function _setTurnFileStoreForTests(store: TurnFileStore | null): TurnFileStore | null {
+  const prev = defaultStore
+  defaultStore = store
+  return prev
+}

package/server/lib/turn-footer.ts

@@ -0,0 +1,81 @@
+// The one trailing verify line a vouched glasses or phone turn carries into an agent session (G2
+// authority Tier 1, 6.99.29). PURE: no I/O, no imports, so the stream grammar
+// (session-stream-events.ts), the transcript readers and the queue evidence can take the line off
+// without importing the ledger. lib/g2-turn-provenance.ts re-exports all of it.
+//
+//   [COS-G2 turn <id> · verify: operations/scripts/cos_python operations/scripts/verify_g2_turn.py <id> --session <your session id> --provider claude]
+//
+// The provider is filled in (claude, codex or cursor): the server footing the turn knows which
+// harness it delivers into (Codex re-audit of 910eb90). The session stays a placeholder ON PURPOSE:
+// the receiving agent states its OWN session id and the verifier compares it with the record, so a
+// message that landed in the wrong session does not verify there. An unknown provider keeps the
+// `<claude|codex|cursor>` placeholder rather than naming a wrong one.
+//
+// The COS-WEB tag is reserved for a future web origin backed by a device key the API token cannot
+// produce. In 6.99.29 no turn is footed COS-WEB: a web turn is recorded, never vouched. The readers
+// still take either tag off.
+//
+// The verifier (MU-Chief-Staff operations/scripts/verify_g2_turn.py) mirrors G2_TURN_FOOTER_RE.
+//
+// FOOTER-SHAPED LINES IN TYPED TEXT ARE REFUSED (QA 6.99.29). Only the server writes a footer, so
+// words that carry anything that looks like one are refused at every route that hands words to a
+// session (turns, queue park and edit, steer, fork, Send again, native Codex queue edit).
+
+/** The footer tag per origin: the glasses and the phone keep COS-G2, a web turn says COS-WEB. */
+export function turnFooterTag(client: string): 'COS-G2' | 'COS-WEB' {
+  return client === 'web' ? 'COS-WEB' : 'COS-G2'
+}
+
+/** The harnesses the verifier accepts for --provider. */
+export const FOOTER_PROVIDERS: ReadonlySet<string> = new Set(['claude', 'codex', 'cursor'])
+
+/** The footer's --provider value: the receiving harness when it is one the verifier knows, else the placeholder. */
+export function footerProvider(provider: string | null | undefined): string {
+  return typeof provider === 'string' && FOOTER_PROVIDERS.has(provider) ? provider : '<claude|codex|cursor>'
+}
+
+export function turnFooter(turnId: string, client: string = 'glasses', provider?: string | null): string {
+  return `[${turnFooterTag(client)} turn ${turnId} · verify: operations/scripts/cos_python operations/scripts/verify_g2_turn.py ${turnId} --session <your session id> --provider ${footerProvider(provider)}]`
+}
+
+/**
+ * Anything that looks like a footer, anywhere in the text: `[COS-G2 turn` or `[COS-WEB turn`, any
+ * case, with spaces or any dash between the parts. Lenient on purpose: refusing a lookalike costs a
+ * retyped line; accepting one could put a second footer in front of a reader.
+ */
+export const TURN_FOOTER_SHAPED_RE = /\[\s*COS[-\u2010-\u2015\u2212\s]*(?:G2|WEB)\s+turn\b/i
+
+/** Whether typed words carry a footer-shaped line (refused: only the server writes a footer). */
+export function hasFooterShapedLine(text: string): boolean {
+  return typeof text === 'string' && TURN_FOOTER_SHAPED_RE.test(text)
+}
+
+/** The refusal copy for a footer-shaped line, shown where the words were typed. */
+export const FOOTER_LINE_REFUSED_COPY = 'This message has a line that looks like a COS verify footer ("[COS-G2 turn" or "[COS-WEB turn"). Only COS writes those lines. Take that line out and send it again.'
+
+/** The refusal copy for a turn id this server already used for a different turn. */
+export const TURN_ID_IN_USE_COPY = 'That message id was already used for a different message. Send it again as a new message.'
+
+/** The 6.66 name, kept: a glasses or phone footer. */
+export function g2TurnFooter(turnId: string, provider?: string | null): string {
+  return turnFooter(turnId, 'glasses', provider)
+}
+
+/** The footer line as it ends a delivered prompt (either tag). Used by tests and mirrored by the verifier. */
+export const G2_TURN_FOOTER_RE = /\n\[COS-(G2|WEB) turn ([A-Za-z0-9][A-Za-z0-9_-]{7,127}) · verify: [^\n\]]*\][\t\n\v\f\r ]*$/
+
+/** The prompt with its footer stripped, and the turn id the footer named (null: no footer). */
+export function stripG2TurnFooter(text: string): { text: string; turnId: string | null; tag: 'COS-G2' | 'COS-WEB' | null } {
+  const m = G2_TURN_FOOTER_RE.exec(text)
+  if (!m) return { text, turnId: null, tag: null }
+  return { text: text.slice(0, m.index), turnId: m[2], tag: m[1] === 'WEB' ? 'COS-WEB' : 'COS-G2' }
+}
+
+/**
+ * The words a transcript row shows with a trailing verify footer taken off, for the code that
+ * matches a transcript against the words it sent (queue-turn-evidence.ts). Only a footer at the
+ * very end, of either tag, is removed.
+ */
+export function withoutTurnFooter(text: string): string {
+  return stripG2TurnFooter(text).text
+}

package/server/lib/web-control-static.ts

@@ -0,0 +1,226 @@
+/**
+ * Fast static serving for COS Control Web (`/control/*`).
+ *
+ * Before this, `/control` went straight to `express.static`: no compression and
+ * `Cache-Control: public, max-age=0`, so every open on the phone re-asked the Mac about
+ * all 22 boot files over Tailscale and downloaded about 1.2 MB of uncompressed JS and CSS
+ * plus 770 KB of fonts whenever anything changed.
+ *
+ * What this does:
+ * - Every asset gets a content hash. `index.html` and the CSS files have their
+ *   `/control/...` references rewritten to `/control/...?v=<hash>`.
+ * - A request whose `?v=` matches the current hash is cached for a year as `immutable`.
+ *   Anything else (index.html, a stale or missing `?v=`) is `no-cache`, so it revalidates
+ *   with its ETag and a new release is picked up on the next open.
+ * - Text assets are served brotli or gzip compressed when the browser accepts it. The
+ *   compressed bytes are built on first request and kept in memory.
+ * - Files on disk are re-checked at most once per `recheckMs`, so a test copy served from
+ *   a worktree picks up edits without a restart.
+ *
+ * Anything not in the table (a path this walker skips) falls through to `next()`, and the
+ * caller keeps `express.static` behind it, so no URL that worked before stops working.
+ */
+import crypto from 'crypto'
+import fs from 'fs'
+import path from 'path'
+import zlib from 'zlib'
+import type { NextFunction, Request, RequestHandler, Response } from 'express'
+
+/** A versioned URL's lifetime. Safe because the hash changes whenever the bytes do. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable'
+/** Unversioned and HTML responses: always revalidate, so a new release shows on the next open. */
+export const REVALIDATE_CACHE = 'no-cache'
+
+const TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.json': 'application/json; charset=utf-8',
+  '.ttf': 'font/ttf',
+  '.woff2': 'font/woff2',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.jpg': 'image/jpeg',
+}
+/** Worth compressing. WOFF2 and images are already compressed. */
+const COMPRESSIBLE = new Set(['.html', '.js', '.css', '.svg', '.json', '.ttf'])
+/** Files whose `/control/...` references are rewritten to versioned URLs. */
+const REWRITTEN = new Set(['.html', '.css'])
+/** Only assets of these types get a versioned URL; HTML pages are always revalidated. */
+const VERSIONABLE = new Set(['.js', '.css', '.svg', '.json', '.ttf', '.woff2', '.png', '.webp', '.jpg'])
+
+export interface WebAsset {
+  /** Path under the mount, with a leading slash: `/panes/work.js`. */
+  urlPath: string
+  ext: string
+  type: string
+  body: Buffer
+  /** First 16 hex characters of the SHA-256 of `body` (after any rewrite). */
+  hash: string
+  gzip?: Promise<Buffer>
+  br?: Promise<Buffer>
+}
+
+export type WebAssetTable = Map<string, WebAsset>
+
+/** Dotfiles are never served. Sources (`.ts`) and maps stay out because TYPES does not list them. */
+function skip(name: string): boolean {
+  return name.startsWith('.')
+}
+
+function walk(dir: string, base = ''): Array<{ urlPath: string; file: string; stat: fs.Stats }> {
+  const out: Array<{ urlPath: string; file: string; stat: fs.Stats }> = []
+  let names: string[]
+  try { names = fs.readdirSync(dir) } catch { return out }
+  for (const name of names.sort()) {
+    if (skip(name)) continue
+    const file = path.join(dir, name)
+    let stat: fs.Stats
+    try { stat = fs.statSync(file) } catch { continue }
+    const urlPath = `${base}/${name}`
+    if (stat.isDirectory()) out.push(...walk(file, urlPath))
+    else if (stat.isFile() && TYPES[path.extname(name).toLowerCase()]) out.push({ urlPath, file, stat })
+  }
+  return out
+}
+
+/** A cheap fingerprint of the tree: every path, size and mtime. */
+export function treeSignature(dir: string): string {
+  return walk(dir).map((f) => `${f.urlPath}:${f.stat.size}:${f.stat.mtimeMs}`).join('|')
+}
+
+function sha(body: Buffer): string {
+  return crypto.createHash('sha256').update(body).digest('hex').slice(0, 16)
+}
+
+/**
+ * Rewrite `/control/<path>` references (quoted, or inside `url(...)`) to carry `?v=<hash>`.
+ * Only references to a known, versionable asset are touched; a reference that already has a
+ * query string, or names a file that does not exist, is left exactly as written.
+ */
+export function rewriteReferences(text: string, mount: string, hashes: Map<string, string>): string {
+  const prefix = mount.replace(/\/$/, '')
+  const re = new RegExp(`(["'(])${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(/[A-Za-z0-9_./-]+)(["')])`, 'g')
+  return text.replace(re, (whole, open: string, rel: string, close: string) => {
+    const hash = hashes.get(rel)
+    if (!hash || !VERSIONABLE.has(path.extname(rel).toLowerCase())) return whole
+    return `${open}${prefix}${rel}?v=${hash}${close}`
+  })
+}
+
+/**
+ * Build the table. Leaves (JS, fonts, images) are hashed first, then CSS is rewritten against
+ * them and hashed, then HTML is rewritten against everything. So a font change gives its CSS a
+ * new hash, and that gives index.html new references.
+ */
+export function buildWebAssetTable(dir: string, mount = '/control'): WebAssetTable {
+  const files = walk(dir)
+  const hashes = new Map<string, string>()
+  const table: WebAssetTable = new Map()
+  const read = (file: string): Buffer | null => { try { return fs.readFileSync(file) } catch { return null } }
+  const add = (urlPath: string, ext: string, body: Buffer): void => {
+    const hash = sha(body)
+    hashes.set(urlPath, hash)
+    table.set(urlPath, { urlPath, ext, type: TYPES[ext], body, hash })
+  }
+  const pass = (pick: (ext: string) => boolean): void => {
+    for (const f of files) {
+      const ext = path.extname(f.urlPath).toLowerCase()
+      if (!pick(ext)) continue
+      const raw = read(f.file)
+      if (!raw) continue
+      const body = REWRITTEN.has(ext) ? Buffer.from(rewriteReferences(raw.toString('utf8'), mount, hashes), 'utf8') : raw
+      add(f.urlPath, ext, body)
+    }
+  }
+  pass((ext) => !REWRITTEN.has(ext))
+  pass((ext) => ext === '.css')
+  pass((ext) => ext === '.html')
+  return table
+}
+
+/** Which encoding to send: brotli, then gzip, then none. `q=0` refuses an encoding. */
+export function pickEncoding(acceptEncoding: string | undefined): 'br' | 'gzip' | null {
+  const accepted = new Map<string, number>()
+  for (const part of String(acceptEncoding || '').toLowerCase().split(',')) {
+    const [name, ...params] = part.trim().split(';')
+    if (!name) continue
+    const q = params.map((p) => p.trim()).find((p) => p.startsWith('q='))
+    accepted.set(name.trim(), q ? Number(q.slice(2)) || 0 : 1)
+  }
+  const ok = (name: string): boolean => (accepted.get(name) ?? accepted.get('*') ?? 0) > 0
+  if (ok('br')) return 'br'
+  if (ok('gzip')) return 'gzip'
+  return null
+}
+
+function compressed(asset: WebAsset, encoding: 'br' | 'gzip'): Promise<Buffer> {
+  if (encoding === 'br') {
+    asset.br ??= new Promise((resolve, reject) => zlib.brotliCompress(asset.body, {
+      params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 9, [zlib.constants.BROTLI_PARAM_SIZE_HINT]: asset.body.length },
+    }, (err, out) => (err ? reject(err) : resolve(out))))
+    return asset.br
+  }
+  asset.gzip ??= new Promise((resolve, reject) => zlib.gzip(asset.body, { level: 9 }, (err, out) => (err ? reject(err) : resolve(out))))
+  return asset.gzip
+}
+
+export interface WebControlStaticOptions {
+  mount?: string
+  /** How often the tree is re-checked for edits. 0 checks on every request. */
+  recheckMs?: number
+  now?: () => number
+}
+
+export function createWebControlStatic(dir: string, opts: WebControlStaticOptions = {}): RequestHandler & { table: () => WebAssetTable } {
+  const mount = opts.mount ?? '/control'
+  const recheckMs = opts.recheckMs ?? 1000
+  const now = opts.now ?? Date.now
+  let signature = treeSignature(dir)
+  let table = buildWebAssetTable(dir, mount)
+  let checkedAt = now()
+
+  const current = (): WebAssetTable => {
+    if (now() - checkedAt >= recheckMs) {
+      checkedAt = now()
+      const next = treeSignature(dir)
+      if (next !== signature) { signature = next; table = buildWebAssetTable(dir, mount) }
+    }
+    return table
+  }
+
+  const handler = (req: Request, res: Response, next: NextFunction): void => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') { next(); return }
+    let urlPath = req.path || '/'
+    if (urlPath.endsWith('/')) urlPath += 'index.html'
+    const asset = current().get(urlPath)
+    if (!asset) { next(); return }
+
+    const versioned = VERSIONABLE.has(asset.ext) && req.query.v === asset.hash
+    const encoding = COMPRESSIBLE.has(asset.ext) ? pickEncoding(req.headers['accept-encoding'] as string | undefined) : null
+    const etag = `"${asset.hash}${encoding ? `-${encoding}` : ''}"`
+    res.setHeader('Content-Type', asset.type)
+    res.setHeader('Cache-Control', versioned ? IMMUTABLE_CACHE : REVALIDATE_CACHE)
+    res.setHeader('ETag', etag)
+    if (COMPRESSIBLE.has(asset.ext)) res.setHeader('Vary', 'Accept-Encoding')
+
+    const inm = String(req.headers['if-none-match'] || '')
+    if (inm && inm.split(',').map((t) => t.trim().replace(/^W\//, '')).includes(etag)) { res.status(304).end(); return }
+
+    const send = (body: Buffer): void => {
+      if (encoding) res.setHeader('Content-Encoding', encoding)
+      res.setHeader('Content-Length', String(body.length))
+      if (req.method === 'HEAD') res.end(); else res.end(body)
+    }
+    if (!encoding) { send(asset.body); return }
+    compressed(asset, encoding).then(send, () => {
+      // Compression failed: send the plain bytes rather than nothing.
+      res.removeHeader('Content-Encoding')
+      res.setHeader('ETag', `"${asset.hash}"`)
+      res.setHeader('Content-Length', String(asset.body.length))
+      if (req.method === 'HEAD') res.end(); else res.end(asset.body)
+    })
+  }
+  return Object.assign(handler, { table: current })
+}

package/server/lib/web-memories-bridge.ts

@@ -306,14 +306,15 @@ export async function dispatchMemoriesWebOp(
       return r.status === 200 ? reply(true, 'Duplicates ready', r.body) : reply(false, r.body.message || r.body.error || 'Failed')
     }
     case 'cues.summary': {
-      // Rating cues opens Control's native cue pane, which the browser does not have, so the
-      // page is told cues are unavailable and hides "Cues to rate" rather than show a button
-      // that does nothing. The counts use Control's keys for when a web cue pane exists.
-      const r = await loopbackFetch('/api/live-cues/history?days=7&limit=200', { timeoutMs: 10_000 })
-      const counts = (r.status === 200 ? r.body.counts ?? {} : {}) as Record<string, any>
-      const unrated = typeof counts.unrated === 'number' ? counts.unrated : 0
-      const rated = typeof counts.rated === 'number' ? counts.rated : 0
-      return reply(true, 'Cues', { available: false, unrated, rated, total: unrated + rated })
+      // Control's CueVerdicts.summary: the cue history read is the capability check. A 200 in the v1 contract means the
+      // server keeps the cue log and verdicts, and COS Control Web rates them in Memories (Cues to rate, Rated cues), so
+      // the answer is available with the week's counts; anything else is unavailable and the entries hide.
+      const r = await loopbackFetch('/api/live-cues/history?days=7&unrated=1&limit=1', { timeoutMs: 10_000 })
+      const counts = (r.status === 200 && r.body.v === 1 ? r.body.counts ?? null : null) as Record<string, any> | null
+      if (!counts || typeof counts.unrated !== 'number' || typeof counts.rated !== 'number' || typeof counts.total !== 'number') {
+        return reply(true, 'Cues', { available: false })
+      }
+      return reply(true, 'Cues', { available: true, unrated: counts.unrated, rated: counts.rated, total: counts.total })
     }
     case 'copy':
       return reply(true, 'Copied', {})