@gotcos/glasses-server 7.0.7 → 7.0.18

package/server/lib/turn-end-ask.ts

@@ -0,0 +1,320 @@
+// 7.0.18 (X1, Miles 2026-11-10 07:14, "fold this in ... so I can respond from glasses, web app and desktop"):
+// a session whose turn ENDS by asking a question in the Claude desktop app's next-step box.
+//
+// WHAT HAPPENS: the session calls `mcp__ccd_turn__wrap_up` with `ask` and reply buttons (`actions[].label`),
+// then its turn stops. There is no AskUserQuestion and no PermissionRequest, so the permission broker never
+// sees it, and the row read idle: the glasses said nothing was waiting (Miles, 07:02).
+//
+// WHAT COS RECEIVES (canaries C15 on the CLI with a stand-in ccd_turn server, C17 in a real Claude desktop
+// Code tab, 2026-11-10): the COS hook spools PostToolUse for every tool, and that payload carries
+// `tool_input.ask` and `tool_input.actions` verbatim, plus `prompt_id`; the Stop follows (about 5 s in the
+// canary; the PostToolUse hook is async, so either order). PreToolUse is not spooled for this tool.
+//
+// WHAT THIS FILE DOES: keeps, per session, the newest qualifying ask (only an ask with at least one reply
+// button, or `blocked`), marks it asked once the turn has stopped, shows it only after the Mac's desk has
+// been idle for the broker's threshold (then latched, so the frozen glasses stay quiet while Miles sits at
+// the Mac), and drops it on any reply, a new turn, the session ending, or 8 hours. The words (the ask, 80
+// characters; reply labels, 40 each, at most 2) follow COS_WAITING_QUESTION_WORDS; with that at 0 the row
+// still says a question waits, with no words. App-action buttons (commit, create PR) are never choices.
+//
+// THE SWITCH: `COS_TURN_END_ASKS`, read once (the first read, at startup), default in TURN_END_ASKS_DEFAULT.
+// Off: nothing here runs, nothing is projected into the ledger, and every row is 7.0.17's.
+//
+// THE ANSWER is the existing Continue (contract v1, COORD 07:18), with text that never reads as typed at the
+// desk. Memory and counters only; nothing here logs a question's words.
+
+import { readSwitch } from './env-switch.js'
+import { questionRowText } from './full-hold.js'
+import type { HookEnvelope } from './session-hook-events.js'
+
+/** The default when COS_TURN_END_ASKS is unset. One constant, per the lead (Miles chooses the value). */
+export const TURN_END_ASKS_DEFAULT = true
+
+/** The Claude desktop app's next-step tool (its `ccd_turn` MCP server). */
+export const WRAP_UP_TOOL = 'mcp__ccd_turn__wrap_up'
+export const TURN_ASK_MAX_CHARS = 80
+export const TURN_ASK_CHOICE_MAX_CHARS = 40
+export const TURN_ASK_MAX_CHOICES = 2
+/** A question nobody answered in 8 hours is not news the next morning; it stays in the transcript. */
+export const TURN_ASK_MAX_AGE_MS = 8 * 60 * 60_000
+/** The shortest gap between two desk reads while an ask waits for the latch. */
+export const TURN_ASK_DESK_POLL_MS = 3_000
+/** When the desk cannot be read, the next try. */
+export const TURN_ASK_UNREADABLE_RETRY_MS = 60_000
+/** The latch never fires for a desk idle less than this, whatever the setting says (the broker's floor). */
+export const TURN_ASK_DESK_IDLE_MIN_S = 30
+/** Sessions tracked at once; past it the oldest go. */
+export const MAX_TURN_ASKS = 128
+/** The registry saying busy this long after the stop means the session runs again. */
+export const TURN_ASK_BUSY_GRACE_MS = 5_000
+
+let enabledAtStartup: boolean | null = null
+
+/** `COS_TURN_END_ASKS`, read on the first call (startup) and kept: a change needs a restart. */
+export function turnEndAsksEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (enabledAtStartup === null) enabledAtStartup = readSwitch(env.COS_TURN_END_ASKS, TURN_END_ASKS_DEFAULT)
+  return enabledAtStartup
+}
+
+/** Tests only: set the switch, or null to read it again on the next call. */
+export function __setTurnEndAsksForTests(value: boolean | null): void {
+  enabledAtStartup = value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function rowText(value: unknown, max: number): string {
+  const text = questionRowText(value).replace(/\s+/g, ' ').trim()
+  return text.length > max ? text.slice(0, max - 1) + '…' : text
+}
+
+/** What is kept of one ask: already cleaned and bounded; empty words when the words switch is off. */
+export interface TurnAskCapture { ask: string; choices: string[]; blocked: boolean }
+
+/**
+ * A `wrap_up` input read strictly. Null unless it carries a non-blank `ask` AND (at least one reply button
+ * or `blocked: true`): an ask with no buttons is the session's suggestion, not a decision it stopped on. A
+ * reply button has a `label` and no `action`; a button with an `action` (commit, create PR) is the app's own
+ * and never a choice. `words` false keeps the fact and drops every word.
+ */
+export function captureTurnAsk(toolInput: unknown, words: boolean): TurnAskCapture | null {
+  if (!isRecord(toolInput)) return null
+  const ask = rowText(toolInput.ask, TURN_ASK_MAX_CHARS)
+  if (!ask) return null
+  const labels: string[] = []
+  if (Array.isArray(toolInput.actions)) {
+    for (const action of toolInput.actions) {
+      if (!isRecord(action)) continue
+      if (action.action !== undefined && action.action !== null && action.action !== '') continue
+      const label = rowText(action.label, TURN_ASK_CHOICE_MAX_CHARS)
+      if (label) labels.push(label)
+    }
+  }
+  const blocked = toolInput.blocked === true
+  if (labels.length === 0 && !blocked) return null
+  return { ask: words ? ask : '', choices: words ? labels.slice(0, TURN_ASK_MAX_CHOICES) : [], blocked }
+}
+
+/** The ledger's copy (`projectHookPayload`): the capture as stored, so a restart replays it. */
+export function projectedTurnAsk(value: unknown): TurnAskCapture | null {
+  if (!isRecord(value) || typeof value.ask !== 'string' || !Array.isArray(value.choices)) return null
+  const choices = value.choices.filter((c): c is string => typeof c === 'string').slice(0, TURN_ASK_MAX_CHOICES).map(c => rowText(c, TURN_ASK_CHOICE_MAX_CHARS)).filter(Boolean)
+  return { ask: rowText(value.ask, TURN_ASK_MAX_CHARS), choices, blocked: value.blocked === true }
+}
+
+/** What a row shows (`deriveSessionState` input). */
+export interface VisibleTurnAsk { ask: string; choices: string[]; stoppedAt: number }
+
+interface AskState {
+  sessionId: string
+  promptId: string | null
+  capture: TurnAskCapture
+  armedAt: number
+  stoppedAt: number | null
+  visibleAt: number | null
+}
+
+export interface TurnEndAskTrackerDeps {
+  now(): number
+  enabled(): boolean
+  /** COS_WAITING_QUESTION_WORDS (default on): the words, or the fact alone. */
+  words(): boolean
+  readDeskIdleSeconds(): Promise<number | null>
+  deskIdleSeconds(): number
+  pollMs?: number
+}
+
+export type TurnEndAskCounters = { armed: number; shown: number; clearedByReply: number; clearedByTurn: number; agedOut: number }
+
+/** Events that end a session's present: whatever it asked is moot. */
+const SESSION_RESETS: ReadonlySet<string> = new Set(['SessionEnd', 'Interrupt', 'StopFailure'])
+
+function str(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+export class TurnEndAskTracker {
+  private readonly deps: TurnEndAskTrackerDeps
+  private readonly asks = new Map<string, AskState>()
+  /** The newest Stop per session, for a wrap_up whose (async) PostToolUse lands after it. */
+  private readonly lastStop = new Map<string, { at: number; promptId: string | null }>()
+  private poll: ReturnType<typeof setTimeout> | null = null
+  private pollInFlight = false
+  private stopped = false
+  readonly counters: TurnEndAskCounters = { armed: 0, shown: 0, clearedByReply: 0, clearedByTurn: 0, agedOut: 0 }
+
+  constructor(deps: TurnEndAskTrackerDeps) {
+    this.deps = deps
+  }
+
+  /**
+   * One applied hook event (the signal store's subscriber: the raw envelope live, the ledger's projection
+   * on replay). `signal` is the store's signal after the event; only its registry `entrypoint` is read.
+   */
+  observe(env: HookEnvelope, child: boolean, signal?: { entrypoint: string | null }): void {
+    if (!this.deps.enabled()) return
+    const p = env.payload
+    // A sub-agent's events are never the session asking you, and never its reply.
+    if (str(p.agent_id)) return
+    const sessionId = env.sessionId.toLowerCase()
+    const current = this.asks.get(sessionId)
+    // Any prompt, from the desk or a COS-spawned Continue child, is a reply: the question is answered.
+    if (env.event === 'UserPromptSubmit') {
+      if (current) { this.asks.delete(sessionId); this.counters.clearedByReply++ }
+      return
+    }
+    // A COS-spawned child's other events are not the session's own turn.
+    if (child) return
+    if (SESSION_RESETS.has(env.event) || (env.event === 'SessionStart' && p.source !== 'compact')) {
+      if (current) { this.asks.delete(sessionId); this.counters.clearedByTurn++ }
+      this.lastStop.delete(sessionId)
+      return
+    }
+    if (env.event === 'Stop') {
+      const promptId = str(p.prompt_id)
+      this.rememberStop(sessionId, env.ts, promptId)
+      if (current && current.stoppedAt === null && env.ts >= current.armedAt && (current.promptId === null || promptId === null || current.promptId === promptId)) {
+        current.stoppedAt = env.ts
+        this.ensurePolling()
+      }
+      return
+    }
+    const toolName = typeof p.tool_name === 'string' ? p.tool_name : ''
+    if (env.event === 'PostToolUse' && toolName === WRAP_UP_TOOL) {
+      // A print run never asks anyone (the broker's own rule: registry entrypoint sdk-cli).
+      if (signal?.entrypoint === 'sdk-cli') return
+      const capture = p.turn_ask !== undefined ? projectedTurnAsk(p.turn_ask) : captureTurnAsk(p.tool_input, this.deps.words())
+      const promptId = str(p.prompt_id)
+      if (!capture) {
+        // A later wrap_up of the same turn without a qualifying ask disarms the earlier one.
+        if (current && current.stoppedAt === null) this.asks.delete(sessionId)
+        return
+      }
+      const stop = this.lastStop.get(sessionId)
+      const stoppedAlready = !!stop && env.ts <= stop.at && (stop.promptId === null || promptId === null || stop.promptId === promptId)
+      this.asks.set(sessionId, { sessionId, promptId, capture, armedAt: env.ts, stoppedAt: stoppedAlready ? stop!.at : null, visibleAt: null })
+      this.counters.armed++
+      this.prune()
+      if (stoppedAlready) this.ensurePolling()
+      return
+    }
+    // Any other tool step after the stop, from another prompt, is a new turn running: the ask is moot.
+    if (current && current.stoppedAt !== null && env.ts > current.stoppedAt && (env.event === 'PreToolUse' || env.event === 'PostToolUse' || env.event === 'PostToolUseFailure' || env.event === 'PermissionRequest')) {
+      const promptId = str(p.prompt_id)
+      if (promptId === null || current.promptId === null || promptId !== current.promptId) {
+        this.asks.delete(sessionId)
+        this.counters.clearedByTurn++
+      }
+    }
+  }
+
+  private rememberStop(sessionId: string, at: number, promptId: string | null): void {
+    this.lastStop.delete(sessionId)
+    this.lastStop.set(sessionId, { at, promptId })
+    if (this.lastStop.size > MAX_TURN_ASKS) {
+      const oldest = this.lastStop.keys().next().value
+      if (oldest !== undefined) this.lastStop.delete(oldest)
+    }
+  }
+
+  /** The ask a row shows now: stopped, latched visible, not older than the age-out. */
+  visibleAsk(sessionId: string, now = this.deps.now()): VisibleTurnAsk | null {
+    if (!this.deps.enabled()) return null
+    const key = sessionId.toLowerCase()
+    const state = this.asks.get(key) ?? (key.length < 36 ? [...this.asks.values()].find(s => s.sessionId.startsWith(key)) : undefined)
+    if (!state || state.stoppedAt === null) return null
+    if (now - state.stoppedAt > TURN_ASK_MAX_AGE_MS) {
+      this.asks.delete(state.sessionId)
+      this.counters.agedOut++
+      return null
+    }
+    if (state.visibleAt === null) return null
+    return { ask: state.capture.ask, choices: [...state.capture.choices], stoppedAt: state.stoppedAt }
+  }
+
+  /** The session's row ended: nothing it asked can still be answered. */
+  sessionRowEnded(sessionId: string): void {
+    const key = sessionId.toLowerCase()
+    for (const state of [...this.asks.values()]) {
+      if (state.sessionId === key || (key.length < 36 && state.sessionId.startsWith(key))) { this.asks.delete(state.sessionId); this.counters.clearedByTurn++ }
+    }
+  }
+
+  private prune(): void {
+    const now = this.deps.now()
+    for (const state of [...this.asks.values()]) {
+      if (state.stoppedAt !== null && now - state.stoppedAt > TURN_ASK_MAX_AGE_MS) { this.asks.delete(state.sessionId); this.counters.agedOut++ }
+    }
+    while (this.asks.size > MAX_TURN_ASKS) {
+      const oldest = [...this.asks.values()].sort((a, b) => a.armedAt - b.armedAt)[0]
+      if (!oldest) break
+      this.asks.delete(oldest.sessionId)
+    }
+  }
+
+  private waitingForLatch(): boolean {
+    for (const state of this.asks.values()) if (state.stoppedAt !== null && state.visibleAt === null) return true
+    return false
+  }
+
+  private ensurePolling(): void {
+    if (this.poll || this.stopped || !this.waitingForLatch()) return
+    this.schedule(this.deps.pollMs ?? TURN_ASK_DESK_POLL_MS)
+  }
+
+  private schedule(delayMs: number): void {
+    this.stopPolling()
+    if (this.stopped) return
+    this.poll = setTimeout(() => {
+      this.poll = null
+      void this.tick().then(next => { if (next !== null) this.schedule(next) })
+    }, delayMs)
+    this.poll.unref?.()
+  }
+
+  private stopPolling(): void {
+    if (this.poll) clearTimeout(this.poll)
+    this.poll = null
+  }
+
+  private thresholdS(): number {
+    const configured = Number(this.deps.deskIdleSeconds())
+    return Math.max(TURN_ASK_DESK_IDLE_MIN_S, Number.isFinite(configured) ? configured : TURN_ASK_DESK_IDLE_MIN_S)
+  }
+
+  /**
+   * One desk read while an ask waits: idle at or past the threshold latches every stopped ask visible.
+   * Returns when to read again (ms), or null when nothing waits. The desk cannot reach the threshold
+   * sooner than (threshold - idle) seconds, so a busy desk is read about once per threshold, not every
+   * poll: an unanswered ask on a Mac in use costs one `ioreg` a minute or so, never one every 3 s.
+   */
+  async tick(): Promise<number | null> {
+    this.prune()
+    if (!this.waitingForLatch()) return null
+    const pollMs = this.deps.pollMs ?? TURN_ASK_DESK_POLL_MS
+    if (this.pollInFlight) return pollMs
+    this.pollInFlight = true
+    let idle: number | null = null
+    try { idle = await this.deps.readDeskIdleSeconds() } catch { idle = null } finally { this.pollInFlight = false }
+    // Unreadable: nothing is shown (it never guesses the desk is empty); read again later.
+    if (idle === null || !Number.isFinite(idle)) return Math.max(pollMs, TURN_ASK_UNREADABLE_RETRY_MS)
+    const threshold = this.thresholdS()
+    if (idle < threshold) return Math.max(pollMs, Math.ceil((threshold - idle) * 1000))
+    const now = this.deps.now()
+    for (const state of this.asks.values()) {
+      if (state.stoppedAt !== null && state.visibleAt === null) { state.visibleAt = now; this.counters.shown++ }
+    }
+    return null
+  }
+
+  stats(): TurnEndAskCounters & { tracked: number } {
+    return { ...this.counters, tracked: this.asks.size }
+  }
+
+  stop(): void {
+    this.stopped = true
+    this.stopPolling()
+  }
+}

package/server/lib/turn-footer.ts

@@ -11,9 +11,9 @@
 // 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 COS-WEB tag is for a web turn signed by an enrolled phone key the API token cannot produce
+// (6.99.31, behind COS_WEB_KEY_AUTHORITY, default off: lib/web-key-authority.ts). Off, as in 6.99.29,
+// no turn is footed COS-WEB: a web turn is recorded, never vouched. The readers take either tag off.
 //
 // The verifier (MU-Chief-Staff operations/scripts/verify_g2_turn.py) mirrors G2_TURN_FOOTER_RE.
 //

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

@@ -0,0 +1,160 @@
+// Served-asset integrity for COS Control Web (6.99.31, plan §4.8 / Phase 6). OFF by default:
+// on with COS_WEB_CONTROL_INTEGRITY=1, and by default whenever COS_WEB_KEY_AUTHORITY=1 (signing
+// is worthless if the page that holds the key can be rewritten on disk); COS_WEB_CONTROL_INTEGRITY=0
+// turns it off even then. Read once at boot.
+//
+// WHY. The managed generation is user-writable (plan canary C7), and the static layer re-read the
+// tree every second (C8), so any process running as Miles could rewrite app.js and have the phone
+// run it within a second. With integrity on:
+//   - the pack step writes `web-control/.manifest.json` (sha256 of every shipped file; the script is
+//     server/scripts/write-web-control-manifest.mjs, mirrored by computeWebControlManifest below)
+//   - at boot the manifest is read ONCE and kept in memory; every file is read once, hashed and
+//     compared; only bytes that matched are ever served, from memory (the 1 s disk re-read is off)
+//   - nothing outside the manifest is served (express.static is not mounted behind it)
+//   - the tree is re-checked every `recheckMs` (60 s); a mismatch flips /control to a plain
+//     integrity-error page (503) and logs which files; a later passing check serves again
+//
+// WHAT IT CANNOT DO. The manifest sits in the same writable directory: an edit of both an asset
+// and the manifest BEFORE a boot passes here. Only COS Control (signed, App Management protected)
+// holding the manifest hash itself catches that (plan §4.8 Control audit, Phase 2). `manifestSha256`
+// is reported for that audit. A process that patches the server code and restarts it is out of reach.
+
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { readSwitch } from './env-switch.js'
+
+export const WEB_CONTROL_MANIFEST_FILE = '.manifest.json'
+export const WEB_CONTROL_INTEGRITY_RECHECK_MS = 60_000
+
+export function webControlIntegrityEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readSwitch(env.COS_WEB_CONTROL_INTEGRITY, readSwitch(env.COS_WEB_KEY_AUTHORITY, false))
+}
+
+export interface WebControlManifest { v: 1; algorithm: 'sha256'; files: Record<string, string> }
+
+/** The files the manifest covers: every regular, non-dot file, except tests (never shipped). */
+export function manifestFiles(dir: string, base = ''): Array<{ urlPath: string; file: string }> {
+  const out: Array<{ urlPath: string; file: string }> = []
+  let names: string[]
+  try { names = readdirSync(dir) } catch { return out }
+  for (const name of names.sort()) {
+    if (name.startsWith('.')) continue
+    const file = join(dir, name)
+    let st
+    try { st = statSync(file) } catch { continue }
+    const urlPath = `${base}/${name}`
+    if (st.isDirectory()) out.push(...manifestFiles(file, urlPath))
+    else if (st.isFile() && !name.endsWith('.test.ts')) out.push({ urlPath, file })
+  }
+  return out
+}
+
+/** What the pack step writes (and the .mjs script must produce byte for byte). */
+export function computeWebControlManifest(dir: string): WebControlManifest {
+  const files: Record<string, string> = {}
+  for (const f of manifestFiles(dir)) files[f.urlPath] = createHash('sha256').update(readFileSync(f.file)).digest('hex')
+  return { v: 1, algorithm: 'sha256', files }
+}
+
+export type IntegrityMismatch = { path: string; problem: 'changed' | 'missing' | 'unexpected' | 'unreadable' }
+
+export interface IntegrityState {
+  ok: boolean
+  /** Why it failed, when it did: a manifest problem or the files that differ. */
+  error: 'manifest_missing' | 'manifest_invalid' | 'files_mismatch' | null
+  mismatches: IntegrityMismatch[]
+  checkedAt: number
+}
+
+export class WebControlIntegrity {
+  private manifest: WebControlManifest | null = null
+  private manifestError: 'manifest_missing' | 'manifest_invalid' | null = null
+  readonly manifestSha256: string | null
+  private snapshotBytes: Map<string, Buffer> | null = null
+  /** Bumps each time a passing check follows a failed one (or the first pass): the static layer rebuilds then. */
+  generation = 0
+  state: IntegrityState
+
+  constructor(readonly dir: string, private readonly opts: { now?: () => number; log?: (line: string) => void } = {}) {
+    let raw: Buffer | null = null
+    try { raw = readFileSync(join(dir, WEB_CONTROL_MANIFEST_FILE)) } catch { this.manifestError = 'manifest_missing' }
+    this.manifestSha256 = raw ? createHash('sha256').update(raw).digest('hex') : null
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw.toString('utf8')) as WebControlManifest
+        const files = parsed?.files
+        if (parsed?.v === 1 && parsed.algorithm === 'sha256' && files && typeof files === 'object'
+          && Object.entries(files).every(([k, v]) => k.startsWith('/') && !k.includes('..') && typeof v === 'string' && /^[0-9a-f]{64}$/.test(v))) {
+          this.manifest = { v: 1, algorithm: 'sha256', files: { ...files } }
+        } else this.manifestError = 'manifest_invalid'
+      } catch { this.manifestError = 'manifest_invalid' }
+    }
+    this.state = { ok: false, error: this.manifestError ?? 'files_mismatch', mismatches: [], checkedAt: 0 }
+    this.check()
+  }
+
+  private now(): number { return (this.opts.now ?? Date.now)() }
+  private log(line: string): void { (this.opts.log ?? ((l: string) => console.error(l)))(line) }
+
+  /** The verified bytes (urlPath to bytes), or null while failing. Never re-read from disk by a server. */
+  snapshot(): Map<string, Buffer> | null {
+    return this.state.ok ? this.snapshotBytes : null
+  }
+
+  /**
+   * Read every file once, hash it, compare with the boot manifest. The snapshot is built from the
+   * very bytes that were hashed, so nothing read after the comparison is ever served.
+   */
+  check(): IntegrityState {
+    const wasOk = this.state.ok
+    const first = this.state.checkedAt === 0
+    const at = this.now()
+    if (!this.manifest) {
+      this.state = { ok: false, error: this.manifestError ?? 'manifest_missing', mismatches: [], checkedAt: at }
+      if (first) this.log(`[web-control-integrity] ${this.state.error}: /control is refused`)
+      this.snapshotBytes = null
+      return this.state
+    }
+    const expected = this.manifest.files
+    const seen = new Set<string>()
+    const bytes = new Map<string, Buffer>()
+    const mismatches: IntegrityMismatch[] = []
+    for (const f of manifestFiles(this.dir)) {
+      seen.add(f.urlPath)
+      const want = expected[f.urlPath]
+      if (!want) { mismatches.push({ path: f.urlPath, problem: 'unexpected' }); continue }
+      let body: Buffer
+      try { body = readFileSync(f.file) } catch { mismatches.push({ path: f.urlPath, problem: 'unreadable' }); continue }
+      if (createHash('sha256').update(body).digest('hex') !== want) { mismatches.push({ path: f.urlPath, problem: 'changed' }); continue }
+      bytes.set(f.urlPath, body)
+    }
+    for (const p of Object.keys(expected)) if (!seen.has(p)) mismatches.push({ path: p, problem: 'missing' })
+    const ok = mismatches.length === 0
+    this.state = { ok, error: ok ? null : 'files_mismatch', mismatches, checkedAt: at }
+    if (ok) {
+      if (!wasOk) { this.snapshotBytes = bytes; this.generation += 1 }
+    } else {
+      this.snapshotBytes = null
+      const list = mismatches.slice(0, 20).map(m => `${m.problem}:${m.path}`).join(', ')
+      this.log(`[web-control-integrity] ${mismatches.length} file(s) do not match the manifest; /control is refused: ${list}`)
+    }
+    if (ok && !wasOk && this.generation > 1) this.log('[web-control-integrity] files match the manifest again; /control is served')
+    return this.state
+  }
+
+  status(): Record<string, unknown> {
+    return {
+      enabled: true,
+      ok: this.state.ok,
+      error: this.state.error,
+      mismatches: this.state.mismatches.slice(0, 50),
+      checkedAt: this.state.checkedAt ? new Date(this.state.checkedAt).toISOString() : null,
+      manifestSha256: this.manifestSha256,
+      files: this.manifest ? Object.keys(this.manifest.files).length : 0,
+    }
+  }
+}
+
+/** The page served instead of /control while integrity fails. Plain, no script, no references. */
+export const INTEGRITY_ERROR_PAGE = '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>COS Control Web: integrity check failed</title></head><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:3rem auto;padding:0 1rem;line-height:1.5"><h1 style="font-size:1.25rem">COS Control Web is paused</h1><p>The files this Mac would send your phone do not match the files that shipped with this version, so they are not being served. Nothing was signed.</p><p>Open COS Control on the Mac to repair or reinstall the server.</p></body></html>'

package/server/lib/web-control-offnet-page.ts

@@ -0,0 +1,58 @@
+/**
+ * W1 (audit 02 F1): what a browser sees when it opens /control from outside Tailscale (home Wi-Fi, a coffee shop).
+ *
+ * The answer stays 403. Only the body changes: a page that says why and what to do, in place of one line of plain text.
+ * It is fixed text with no script, no link, no name, no address and no version, so it tells a stranger on the same network
+ * nothing the old text did not ("available on this Mac and over Tailscale"). It never offers a LAN way in: COS Control Web
+ * is Tailscale only unless the owner sets COS_WEB_CONTROL_LAN=1 on the Mac (lib/web-session-auth.ts isWebControlSocketAllowed).
+ *
+ * A request that does not ask for HTML (an asset, a fetch) keeps the plain text line, so nothing that parses it changes.
+ */
+export const WEB_CONTROL_OFFNET_TEXT = 'COS Control Web is available on this Mac and over Tailscale.'
+
+/** Its own policy: no script, no outside request, inline style only. Replaces nothing for pages that pass the socket check. */
+export const WEB_CONTROL_OFFNET_CSP = "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+export const WEB_CONTROL_OFFNET_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="referrer" content="no-referrer">
+<meta name="robots" content="noindex">
+<title>Open COS over Tailscale</title>
+<style>
+:root { color-scheme: light dark; --bg: #f6f5f2; --ink: #1d1c1a; --sub: #5d5a54; --card: #ffffff; --line: #e3e0da; }
+@media (prefers-color-scheme: dark) { :root { --bg: #151514; --ink: #f1efea; --sub: #a9a59d; --card: #1f1e1c; --line: #34322e; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 17px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+main { max-width: 520px; margin: 0 auto; padding: max(28px, env(safe-area-inset-top)) 16px 40px; }
+h1 { font-size: 24px; line-height: 1.25; margin: 0 0 12px; }
+p { margin: 0 0 14px; color: var(--sub); }
+ol { margin: 0 0 18px; padding: 16px 16px 16px 36px; background: var(--card); border: 1px solid var(--line); border-radius: 14px; }
+li { margin: 0 0 10px; }
+li:last-child { margin-bottom: 0; }
+strong { color: var(--ink); }
+</style>
+</head>
+<body>
+<main>
+<h1>Open COS over Tailscale</h1>
+<p>This is COS Control Web. It only opens over Tailscale, so it stays hidden from everyone else on this network.</p>
+<ol>
+<li>Install <strong>Tailscale</strong> on this phone or computer, and sign in with the same account your Mac uses.</li>
+<li>Turn Tailscale on.</li>
+<li>Open the COS link again. To get a new one, open COS Control Settings on your Mac and choose <strong>Open COS on your phone</strong>.</li>
+</ol>
+<p>Nothing was sent and you are not signed in.</p>
+</main>
+</body>
+</html>
+`
+
+/** The 403 body for a request outside Tailscale: the page for a browser, the old line for anything else. */
+export function webControlOffnetResponse(acceptsHtml: boolean): { type: 'html' | 'text'; body: string; csp: string | null } {
+  return acceptsHtml
+    ? { type: 'html', body: WEB_CONTROL_OFFNET_HTML, csp: WEB_CONTROL_OFFNET_CSP }
+    : { type: 'text', body: WEB_CONTROL_OFFNET_TEXT, csp: null }
+}

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

@@ -25,6 +25,7 @@ import fs from 'fs'
 import path from 'path'
 import zlib from 'zlib'
 import type { NextFunction, Request, RequestHandler, Response } from 'express'
+import { INTEGRITY_ERROR_PAGE, WEB_CONTROL_INTEGRITY_RECHECK_MS, type WebControlIntegrity } from './web-control-integrity.js'
 
 /** A versioned URL's lifetime. Safe because the hash changes whenever the bytes do. */
 export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable'
@@ -114,11 +115,18 @@ export function rewriteReferences(text: string, mount: string, hashes: Map<strin
  * 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)
+export function buildWebAssetTable(dir: string, mount = '/control', source?: ReadonlyMap<string, Buffer>): WebAssetTable {
+  // 6.99.31: with `source` (integrity mode), the table is built ONLY from those verified bytes; the
+  // disk is not read at all.
+  const files = source
+    ? [...source.keys()].sort().filter(urlPath => TYPES[path.extname(urlPath).toLowerCase()] && !urlPath.split('/').some(part => part.startsWith('.'))).map(urlPath => ({ urlPath, file: urlPath }))
+    : 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 read = (file: string): Buffer | null => {
+    if (source) return source.get(file) ?? 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)
@@ -168,20 +176,45 @@ function compressed(asset: WebAsset, encoding: 'br' | 'gzip'): Promise<Buffer> {
 
 export interface WebControlStaticOptions {
   mount?: string
-  /** How often the tree is re-checked for edits. 0 checks on every request. */
+  /** How often the tree is re-checked for edits. 0 checks on every request. Ignored in integrity mode. */
   recheckMs?: number
   now?: () => number
+  /**
+   * 6.99.31 (Phase 6): serve only bytes that matched the pack-time manifest, from memory. The disk is
+   * never re-read per request; the integrity check re-runs every `integrityRecheckMs` (default 60 s,
+   * 0: never on a timer, tests call `integrity.check()`). While it fails, every GET or HEAD under the
+   * mount answers the plain integrity-error page (503), and nothing falls through to a disk server.
+   */
+  integrity?: WebControlIntegrity
+  integrityRecheckMs?: number
 }
 
-export function createWebControlStatic(dir: string, opts: WebControlStaticOptions = {}): RequestHandler & { table: () => WebAssetTable } {
+export function createWebControlStatic(dir: string, opts: WebControlStaticOptions = {}): RequestHandler & { table: () => WebAssetTable; stop: () => void } {
   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)
+  const integrity = opts.integrity ?? null
+  let signature = integrity ? '' : treeSignature(dir)
+  let table: WebAssetTable = integrity ? new Map() : buildWebAssetTable(dir, mount)
+  let builtFrom = -1
   let checkedAt = now()
+  let timer: ReturnType<typeof setInterval> | null = null
+  if (integrity) {
+    const every = opts.integrityRecheckMs ?? WEB_CONTROL_INTEGRITY_RECHECK_MS
+    if (every > 0) { timer = setInterval(() => { try { integrity.check() } catch { /* the next tick retries */ } }, every); timer.unref?.() }
+  }
+
+  /** Integrity mode: the table of verified bytes, or null while the check fails. */
+  const verified = (): WebAssetTable | null => {
+    if (!integrity) return null
+    const snap = integrity.snapshot()
+    if (!snap) return null
+    if (integrity.generation !== builtFrom) { table = buildWebAssetTable(dir, mount, snap); builtFrom = integrity.generation }
+    return table
+  }
 
   const current = (): WebAssetTable => {
+    if (integrity) return verified() ?? new Map()
     if (now() - checkedAt >= recheckMs) {
       checkedAt = now()
       const next = treeSignature(dir)
@@ -194,8 +227,19 @@ export function createWebControlStatic(dir: string, opts: WebControlStaticOption
     if (req.method !== 'GET' && req.method !== 'HEAD') { next(); return }
     let urlPath = req.path || '/'
     if (urlPath.endsWith('/')) urlPath += 'index.html'
+    if (integrity && verified() === null) {
+      res.status(503)
+      res.setHeader('Content-Type', 'text/html; charset=utf-8')
+      res.setHeader('Cache-Control', 'no-store')
+      if (req.method === 'HEAD') res.end(); else res.end(INTEGRITY_ERROR_PAGE)
+      return
+    }
     const asset = current().get(urlPath)
-    if (!asset) { next(); return }
+    if (!asset) {
+      // Integrity mode serves nothing it did not verify: no fall-through to a disk server.
+      if (integrity) { res.status(404).type('text').send('Not found'); return }
+      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
@@ -222,5 +266,5 @@ export function createWebControlStatic(dir: string, opts: WebControlStaticOption
       if (req.method === 'HEAD') res.end(); else res.end(asset.body)
     })
   }
-  return Object.assign(handler, { table: current })
+  return Object.assign(handler, { table: current, stop: () => { if (timer) clearInterval(timer); timer = null } })
 }