@gotcos/glasses-server 6.40.2 → 6.42.0

package/.env.example

@@ -14,9 +14,27 @@ BIND_HOST=0.0.0.0
 # PORT=3141
 
 # ── AUTH ────────────────────────────────────────────────────────────────
-# A token is REQUIRED on every /api call. Leave UNSET and the server prints an
-# auto-generated one at boot — paste it into the phone app. Set a fixed value
-# here for a stable token across restarts.
+# A token is required on every /api call EXCEPT six paths. Four are public because
+# a client needs them BEFORE it holds a usable token; two are capability URLs
+# because the browser API that fetches them cannot send a header at all:
+#
+#   GET  /api/health          server availability and capability advertisement
+#   GET  /api/diag/health     recovery diagnostics
+#   POST /api/diag/client     client-side crash/diagnostic upload
+#   GET  /api/display-stream  the glasses display bus. EventSource cannot set
+#                             headers, so this returns 200 to anyone — but a
+#                             subscriber without a token gets a live transport and
+#                             lifecycle markers ONLY, never transcripts or answers.
+#   GET  /api/display-stream/<expiry>.<hmac>   short-lived capability URLs, each
+#   GET  /api/tts/play/<uuid>                  minted by an AUTHENTICATED call, for
+#                             EventSource and for native audio players respectively
+#                             — neither can send a header. On the display stream the
+#                             X-Cos-Token header is accepted as an equivalent, so any
+#                             caller that CAN send one should; the TTS UUID also names
+#                             which audio to play, so it is not interchangeable.
+#
+# Leave UNSET and the server prints an auto-generated token at boot — paste it into
+# the phone app. Set a fixed value here for a stable token across restarts.
 # COS_API_TOKEN=pick-any-long-random-string
 
 # Optional durable image-store location. Defaults to

package/CHANGELOG.md

@@ -1,3 +1,104 @@
+## 6.42.0
+
+The display stream stops broadcasting your meetings to the local network.
+
+`GET /api/display-stream` has been public since it was written, because
+EventSource cannot attach an `X-Cos-Token` header. That is still true, so the
+route is still public and still returns 200 to everyone — but what it SENDS is
+now decided per event. A subscriber that proves it holds the pairing token gets
+the whole bus. A subscriber that does not gets a live transport, the handshake,
+the keepalive, replay-gap notices, and one projected lifecycle marker. It never
+receives a transcript, an answer, a coaching cue, a tool status or an error.
+
+**COS Glasses app 6.8.441 is required to restore full content delivery.** Older
+builds keep working — that is the entire reason the connection is not rejected —
+but they connect without a capability, so they will see the content-suppressed
+stream: no live transcript on the lens and no streamed answers, while meeting
+capture, saving, and offline sync continue normally. 6.8.441 is the first app
+build that fetches a ticket and reconnects on `contentAuthorized: false`. Nothing
+else states this, so state it here: update the app with the server.
+
+Two ways to prove you hold the token:
+
+- `X-Cos-Token` on the request, for every fetch-based consumer (COS Control, the
+  companion's own connection probe, curl). Preferred wherever it is possible.
+- `GET /api/display-stream/<expiry>.<hmac>` for EventSource, which cannot send a
+  header. The ticket is an HMAC over its own expiry keyed on the pairing token,
+  so it is stateless, unforgeable without the key, and invalidated the instant
+  the token rotates. `GET /api/models` mints one; `GET /api/health` advertises the
+  capability so a client can detect an older server by its absence.
+
+An invalid or expired ticket is never rejected. It degrades to the ticketless
+stream, so a client whose ticket died mid-reconnect keeps its transport instead
+of entering a retry loop — and the `ready` frame now carries
+`contentAuthorized: <boolean>` so it can tell the difference and re-mint. Without
+that field a degraded stream is indistinguishable from a healthy one.
+
+The ticket TTL is 15 minutes, chosen by the platform rather than by taste: a
+backgrounded Even Hub WebView is suspended and cannot re-mint, and the Even Hub
+review loop locks the phone for five minutes. A 2-minute TTL was guaranteed to
+be dead on the reviewer's exact path. Minting requires the pairing token, so the
+TTL only bounds the value of a ticket that leaks out of a URL.
+
+Also in this release:
+
+- `recording_stop` reaches ticketless subscribers as a PROJECTION carrying only
+  `sessionId`. The production payload also carries `filename`, which embeds the
+  transcript-derived meeting title (`..._Q3_Budget_Cuts_Layoffs_....md`), plus
+  duration and business domain. An allowlist of event TYPES passed the whole
+  event through and would have broadcast the title of every meeting.
+- `replay_gap` reaches ticketless subscribers too. It carries only a reason, the
+  cursor the client itself sent, the watermark already in `ready`, and a buffer
+  boundary, and withholding it strands a client on a dead cursor after a server
+  restart. The buffer it describes is still never served without a ticket.
+- The ticketed path is exempt from the recovery lease classifier. It matched by
+  exact string, so the new path segment classified as a leased request — and an
+  SSE lease never settles, so a connected lens would have held the recovery gate
+  open and 409'd every COS Control server restart. (In this build the admission
+  middleware is exported but not mounted, so that was latent, not live; the
+  classification is a contract a build that mounts it would inherit.) Lease kinds
+  are also redacted now, so `GET /api/recovery/status` can never republish a live
+  display ticket or TTS capability as plain text.
+- `mintDisplayTicket` throws on an empty token instead of returning a ticket that
+  can never verify, and `/api/models` omits the field rather than advertising a
+  dead capability.
+- Ticketless connects are summarized once a minute with a count instead of logged
+  per connect. `retry: 3000` means one stale client would otherwise write ~1,200
+  lines an hour into the launchd log.
+- `.env.example` said a token is required on every `/api` call. It is not, and it
+  never was: four paths are public and two are capability URLs. That file ships in
+  the npm tarball.
+
+## 6.41.0
+
+Allowlist mode can finally read the workspace it was pointed at.
+
+A public user set `COS_CLAUDE_TRUST_MODE=allowlist` (the security-conscious
+choice, tried first) and got "I don't have access to your workspace files."
+That was the code working as written: in allowlist mode the per-query tool
+list is the entire tool universe, and it was built as WebSearch + WebFetch,
+with Read added only when the query carried a photo. The CLI's working
+directory correctly pointed at the user's workspace; nothing in the list
+could open a file in it.
+
+Three changes, one release:
+
+- The base tool list now always includes `Read`, `Glob`, and `Grep` — the
+  read-only exploration trio. Allowlist mode becomes "web plus read-only
+  workspace": shell, edits, and writes remain impossible by construction,
+  and a new test pins that Bash/Edit/Write can never appear in this list.
+  In trusted mode (the default) the list is only an auto-approve hint, so
+  behavior there is unchanged.
+- The allowlist capability prompt now affirms workspace readability — but
+  only when the list actually grants it, so the prompt can never over-claim.
+  Without the affirmation, a model told it is "genuinely limited" tends to
+  refuse reads it has.
+- The one listless spawn (prewarm) no longer passes an empty `--tools` in
+  allowlist mode. On the current CLI that flag triggers a spurious context
+  compaction and a synthetic 400 (the same pathology isolated by the fork
+  bisection on 2026-08-26); denial now rides `--permission-mode dontAsk`
+  plus an empty `--allowedTools` alone.
+
 ## 6.40.2
 
 A finished answer could leave the stream open forever.

package/README.md

@@ -87,8 +87,12 @@ without silently losing completed replies.
 > has those tools, so you will see it use them more readily than before.
 > Set `COS_CLAUDE_TRUST_MODE=allowlist` to remove Claude's permission bypass
 > and restrict it to COS's explicit per-query tool allowlist; undeclared tools
-> then fail closed without prompting. Only the exact value `allowlist` restricts
-> anything — any other value logs a warning and stays trusted.
+> then fail closed without prompting. In allowlist mode the query keeps web
+> search/fetch and **read-only workspace access** (Read, Glob, Grep) — no
+> shell, no edits, no writes. Only the exact value `allowlist` restricts
+> anything — any other value logs a warning and stays trusted. Servers before
+> 6.41.0 denied ALL workspace reads in allowlist mode; if a hardened install
+> answers "I don't have access to your workspace files", update the server.
 
 ## Connect your phone (the one gotcha)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.40.2",
+  "version": "6.42.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/lib/api-auth.ts

@@ -16,10 +16,26 @@ const PUBLIC_API_PATHS = new Set([
 // path segment, and no query-token fallback that could leak into URL logs.
 const TTS_PLAYBACK_CAPABILITY_PATH = /^\/tts\/play\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 
+// EventSource has the identical constraint, so the display stream reuses the same
+// shape: `/display-stream/<expUnixSeconds>.<hex hmac>`, GET/HEAD only, path segment,
+// no query-token fallback. Admission here is SHAPE ONLY — the signature is verified
+// in the route, which is the only place that holds the API token.
+//
+// `/display-stream` itself STAYS PUBLIC, deliberately. Removing it would make a
+// ticketless connect fall through to the token check and 401, and neither EventSource
+// in the client can send a header — every installed build would enter a permanent
+// reconnect loop and, because `displayBusConnected` would never turn true, would also
+// stop syncing already-recorded offline meetings. Confidentiality is enforced by
+// withholding CONTENT in the route, not by rejecting the connection. The route also
+// accepts a valid X-Cos-Token header as equivalent authorization, for the fetch-based
+// callers that can send one; the ticket exists only for the ones that cannot.
+const DISPLAY_STREAM_CAPABILITY_PATH = /^\/display-stream\/\d{1,15}\.[0-9a-f]{64}$/
+
 export function isPublicApiRequest(method: string, path: string): boolean {
   if (PUBLIC_API_PATHS.has(path)) return true
-  return (method === 'GET' || method === 'HEAD')
-    && TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+  if (method !== 'GET' && method !== 'HEAD') return false
+  return TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+    || DISPLAY_STREAM_CAPABILITY_PATH.test(path)
 }
 
 /** Global /api authentication boundary. Mount before all body parsers. */

package/server/lib/claude-bridge.ts

@@ -459,7 +459,6 @@ export async function callClaudeStreaming(
     throw err
   }
   const allowedToolList = buildClaudeToolList({
-    includeRead: imagePaths.length > 0,
     publisherTool: outputImagePublisher?.claudeAllowedTool,
   })
   let mcpConfigArgs: string[]

package/server/lib/claude-permissions.ts

@@ -45,10 +45,16 @@ export function claudePermissionArgs(
       : ['--dangerously-skip-permissions', '--allowedTools', allowedTools]
   }
 
-  const tools = allowedTools ?? ''
+  // No per-query list (the prewarm spawn): deny everything via dontAsk plus an
+  // empty allowedTools, but never pass an empty --tools — on the current CLI
+  // an empty --tools triggers a spurious context compaction and a synthetic
+  // 400 (single-flag bisection 2026-08-26, documented in fork-thread.ts).
+  if (allowedTools === null) {
+    return ['--permission-mode', 'dontAsk', '--allowedTools', '']
+  }
   return [
     '--permission-mode', 'dontAsk',
-    '--tools', tools,
-    '--allowedTools', tools,
+    '--tools', allowedTools,
+    '--allowedTools', allowedTools,
   ]
 }

package/server/lib/claude-tool-access.ts

@@ -89,12 +89,15 @@ export function reportClaudeExtraToolConfiguration(
 }
 
 export function buildClaudeToolList(input: {
-  includeRead?: boolean
   publisherTool?: string
   env?: NodeJS.ProcessEnv
 } = {}): string[] {
-  const tools = ['WebSearch', 'WebFetch']
-  if (input.includeRead) tools.push('Read')
+  // Read-only workspace tools are unconditional: in allowlist mode this list
+  // is the entire tool universe, and without them a hardened install cannot
+  // read the workspace the glasses are pointed at (field report 2026-08-27).
+  // Shell/Edit/Write stay excluded, so allowlist keeps its no-side-effects
+  // property. In trusted mode the list is only an auto-approve hint.
+  const tools = ['WebSearch', 'WebFetch', 'Read', 'Glob', 'Grep']
   tools.push(...configuredClaudeExtraTools(input.env))
   if (input.publisherTool) tools.push(input.publisherTool)
   return [...new Set(tools)]
@@ -186,8 +189,15 @@ export function claudeToolCapabilityPrompt(
   const honesty = TOOL_HONESTY_CLAUSE
 
   if (mode === 'allowlist') {
+    // Affirm workspace readability ONLY when the list actually grants it —
+    // this prompt is something the session trusts, and promising reads a
+    // caller did not include would recreate the 2026-07-28 class of header
+    // mismatch in the opposite direction.
+    const workspaceLine = tools.includes('Read')
+      ? `\nYour working directory is the user's COS workspace: Read, Glob, and Grep are in the list so you can search and read its files. The restriction here is on shell, writes, and undeclared tools — not on reading the workspace. Never refuse a workspace read in this mode.`
+      : ''
     return `TOOL CAPABILITY CONTRACT:
-This request runs in RESTRICTED allowlist mode and is genuinely limited to these tool selectors: ${list}. Undeclared tools are denied without prompting, so a call outside this list will fail.
+This request runs in RESTRICTED allowlist mode and is genuinely limited to these tool selectors: ${list}. Undeclared tools are denied without prompting, so a call outside this list will fail.${workspaceLine}
 Selectors are permissions, not proof that a connector is online. Use a tool only when it is actually present in this session. If the user asks for a tool or connector that is absent, or a tool call fails, say that it is unavailable. ${honesty}
 ${UNTRUSTED_CONTENT_CLAUSE}`
   }

package/server/lib/display-ticket.ts

@@ -0,0 +1,99 @@
+import { createHmac } from 'node:crypto'
+import { timingSafeTokenEqual } from './token-auth.js'
+
+/**
+ * Short-lived capability for GET /api/display-stream.
+ *
+ * WHY A CAPABILITY AT ALL. `EventSource` cannot attach `X-Cos-Token` — the same
+ * constraint native HTML audio has, which is why `api-auth.ts` already carries a
+ * TTS playback capability. This reuses that reviewed shape rather than inventing
+ * a second one: **a path segment, GET/HEAD only, and no query-token fallback that
+ * could leak into URL logs.**
+ *
+ * WHY STATELESS. An HMAC over the expiry needs no store, so there is no eviction
+ * policy to get wrong, no unbounded Map, and no timer to leak. It also invalidates
+ * every outstanding ticket the moment the pairing token rotates, which a UUID store
+ * would not. The TTS capability needs a store because its UUID carries no claims;
+ * this one carries its own expiry.
+ *
+ * WHY REPLAY WITHIN THE TTL IS FINE. Minting requires the pairing token, so an
+ * attacker who could mint already has full API access. The TTL bounds the value of
+ * a ticket that leaks out of a URL, which is the actual threat. Single-use would be
+ * strictly worse: the server sends `retry: 3000`, so a browser-initiated reconnect
+ * replays the same URL, and a consumed ticket would turn every transport blip into a
+ * hard failure.
+ */
+
+/**
+ * 15 minutes, set by the PLATFORM, not by taste.
+ *
+ * The first draft used 120s, which is exactly the Even Hub reviewer's boundary: the
+ * review rubric checks a two-minute idle, and the pre-submission loop locks the phone
+ * for five. A backgrounded Even Hub WebView is SUSPENDED — no timer, no fetch, no
+ * re-mint — so a 120s ticket is guaranteed to be dead on the exact path a reviewer
+ * exercises, and the app would come back to a content-suppressed stream.
+ *
+ * The TTL is not what protects the stream. MINTING requires the pairing token, so
+ * anyone who can mint already has full API access; the TTL only bounds the value of
+ * a ticket that leaks out of a URL (proxy log, screen share, shoulder surf). 15
+ * minutes keeps that window small while surviving every suspension a phone actually
+ * imposes.
+ */
+export const DISPLAY_TICKET_TTL_SECONDS = 900
+
+/** Domain separation. Without a purpose string, any future feature that HMACs an
+ *  integer under the same key would mint cross-usable display tickets. */
+const TICKET_PURPOSE = 'display-stream'
+
+function signature(apiToken: string, expSeconds: number): string {
+  return createHmac('sha256', apiToken)
+    .update(`${TICKET_PURPOSE}:${expSeconds}`)
+    .digest('hex')
+}
+
+/**
+ * `<expUnixSeconds>.<hex sha256 hmac>` — safe in a path segment, no encoding needed.
+ *
+ * THROWS on an empty token rather than returning a ticket. An HMAC keyed on '' is a
+ * well-formed string that `verifyDisplayTicket` rejects unconditionally (it fails
+ * closed on `!apiToken`), so a silent mint would publish a capability that can never
+ * be redeemed — the caller would advertise `ticketSupported` and hand out a value
+ * that is dead on arrival. Callers must decide what to do without a token; they may
+ * not be handed a placeholder.
+ */
+export function mintDisplayTicket(
+  apiToken: string,
+  nowMs: number = Date.now(),
+): string {
+  if (!apiToken) {
+    throw new Error('mintDisplayTicket requires a non-empty API token — a ticket minted without one can never verify')
+  }
+  const exp = Math.floor(nowMs / 1000) + DISPLAY_TICKET_TTL_SECONDS
+  return `${exp}.${signature(apiToken, exp)}`
+}
+
+/**
+ * True only for a well-formed, unexpired, correctly-signed ticket.
+ *
+ * Fails CLOSED on every malformed input. The expiry is parsed from the ticket
+ * itself, so a forged expiry changes the signed message and fails the HMAC — the
+ * claim cannot be edited without the key.
+ */
+export function verifyDisplayTicket(
+  apiToken: string,
+  ticket: unknown,
+  nowMs: number = Date.now(),
+): boolean {
+  if (typeof ticket !== 'string' || !apiToken) return false
+  const separator = ticket.indexOf('.')
+  if (separator <= 0) return false
+  const expRaw = ticket.slice(0, separator)
+  const provided = ticket.slice(separator + 1)
+  if (!/^\d{1,15}$/.test(expRaw) || !/^[0-9a-f]{64}$/.test(provided)) return false
+  const exp = Number(expRaw)
+  if (!Number.isSafeInteger(exp)) return false
+  // Expiry is checked BEFORE the compare so a stale ticket cannot be probed for
+  // signature validity, and so the common rejection costs no hashing.
+  if (Math.floor(nowMs / 1000) >= exp) return false
+  return timingSafeTokenEqual(provided, signature(apiToken, exp))
+}

package/server/lib/recovery-activity.ts

@@ -29,6 +29,40 @@ const EXEMPT_EXACT = new Set([
   'POST /api/recovery/server/restart',
 ])
 
+/**
+ * Exempt by PREFIX, because the display stream grew a path segment.
+ *
+ * EXEMPT_EXACT matches whole strings, so `GET /api/display-stream/<exp>.<hmac>`
+ * (6.42.0's ticketed form) fell through to 'request' and would take a lease. An SSE
+ * connection has no `finish`, and `close` only converts the lease to a 120s grace
+ * window that a live socket never reaches — so one connected lens would hold the
+ * recovery gate open indefinitely and 409 every COS Control server restart. A
+ * long-lived stream is the exact shape that must never take a lease.
+ *
+ * SCOPE, stated honestly: in THIS build `recoveryAdmissionMiddleware` is exported
+ * but never mounted (`grep -rn "recovery-activity" server` shows routes/recovery.ts
+ * importing only acquireMaintenance and getRecoveryActivityStatus), so no lease is
+ * taken for any route and the 409 above is latent rather than live. The
+ * classification is still a published contract that a build mounting the middleware
+ * would inherit, so it is fixed here rather than left as a trap.
+ */
+const EXEMPT_GET_PREFIXES = ['/api/display-stream/']
+
+/**
+ * A capability URL is a live bearer credential. GET /api/recovery/status publishes
+ * every lease `kind` verbatim, and that route is reachable by anyone who can already
+ * read status — so a kind built from the raw path would republish a working display
+ * ticket (or a TTS playback capability) as plain text in a diagnostic response.
+ *
+ * Redaction happens where the kind is BUILT, not where it is read, so no future
+ * reader of `active` can reintroduce the leak.
+ */
+export function redactCapabilityPath(path: string): string {
+  return path
+    .replace(/^(\/api\/display-stream)\/[^/]+$/, '$1/<ticket>')
+    .replace(/^(\/api\/tts\/play)\/[^/]+$/, '$1/<capability>')
+}
+
 const OPERATION_GET_PREFIXES = [
   '/api/models',
   '/v1/models',
@@ -53,6 +87,10 @@ export function classifyRecoveryRoute(method: string, path: string): RecoveryRou
   const verb = method.toUpperCase()
   const normalized = path.split('?')[0]
   if (EXEMPT_EXACT.has(`${verb} ${normalized}`)) return 'exempt'
+  if ((verb === 'GET' || verb === 'HEAD')
+    && EXEMPT_GET_PREFIXES.some(prefix => normalized.startsWith(prefix))) {
+    return 'exempt'
+  }
   if (!normalized.startsWith('/api/') && !normalized.startsWith('/v1/')) return 'exempt'
   if (verb !== 'GET' && verb !== 'HEAD') return 'operation'
   if (OPERATION_GET_PREFIXES.some(prefix => normalized === prefix || normalized.startsWith(prefix))) {
@@ -144,7 +182,10 @@ export function recoveryAdmissionMiddleware(req: Request, res: Response, next: N
   }
 
   const id = `${routeClass}:${++sequence}`
-  const release = createLease(`${req.method} ${(req.originalUrl || req.path).split('?')[0]}`, id)
+  const release = createLease(
+    `${req.method} ${redactCapabilityPath((req.originalUrl || req.path).split('?')[0])}`,
+    id,
+  )
   res.once('finish', release)
   res.once('close', () => {
     const lease = active.get(id)

package/server/routes/display.ts

@@ -2,30 +2,181 @@
 // Any connected glasses client receives real-time query responses
 // regardless of which interface submitted the query
 
-import { Router, type Response } from 'express'
+import { Router, type Request, type Response } from 'express'
 import {
   emitDisplay,
   getDisplayWatermark,
   onDisplay,
   replayDisplayEvents,
+  type DisplayEvent,
   type PublishedDisplayEvent,
 } from '../lib/display-bus.js'
+import { verifyDisplayTicket } from '../lib/display-ticket.js'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
 
 export const displayRouter = Router()
 
+/**
+ * What a TICKETLESS subscriber may receive, as a per-type PROJECTION.
+ *
+ * ALLOWLIST, NEVER A DENYLIST. A new member of the DisplayEvent union is withheld
+ * by default, so adding an event type can never silently widen the unauthenticated
+ * surface.
+ *
+ * A projection, not a pass-through, because an allowlisted TYPE can still carry
+ * content in its payload — which is exactly the bug the first cut of this shipped.
+ * The projection is the contract: whatever the emitter grows later, only the fields
+ * named here can ever leave.
+ *
+ * The other ten members of the union all carry user content: `transcript_chunk` and
+ * `prompt_transcript` carry meeting speech with speaker labels, `chunk`/`done` carry
+ * answer text, `session_restore` carries conversation state, `coaching_nudge` carries
+ * derived guidance, `start` carries session metadata, `tool_status` carries a message,
+ * `error` carries error text, and `recording_start` is covered by its own note below.
+ *
+ * NOT ROUTED THROUGH HERE: `keepalive` is an SSE comment (`: keepalive`), not an
+ * event. `ready` and `replay_gap` are written directly by the handler below — both
+ * are transport metadata with no user content, and `replay_gap` is deliberately
+ * ticketless-visible (see the handler).
+ */
+const TICKETLESS_PROJECTIONS: {
+  readonly [K in DisplayEvent['type']]?: (data: Record<string, unknown>) => Record<string, unknown>
+} = {
+  /**
+   * `recording_stop` is a lifecycle marker: the lens uses it to clear a stale
+   * "recording" indicator that would otherwise persist forever.
+   *
+   * BUT THE PRODUCTION PAYLOAD IS NOT BARE. Both emitters (routes/meeting.ts, the
+   * durable save path and the orphan-recovery path) send
+   * `{ sessionId, filename, durationMin, domain }`, and `filename` is built by
+   * meeting-store.ts `filenameStem()` from the transcript-derived meeting TITLE —
+   * `2026-08-31_Q3_Budget_Cuts_Layoffs_1a2b3c4d.md`. Passing the event through whole
+   * broadcast the meeting title, its duration and its business domain to every
+   * unauthenticated listener on the LAN, which is precisely what a ticket exists to
+   * withhold.
+   *
+   * Only `sessionId` survives. It is the id the CLIENT supplied when it started the
+   * capture (meeting-store `normalizeSessionId` constrains it to
+   * `[A-Za-z0-9:_-]{3,96}` and the server never derives it from the transcript), so
+   * it is the one field the subscriber already holds and the one the lens needs to
+   * match the marker to its own indicator.
+   */
+  // `durationMin` rides along because the lens renders `Meeting saved — ${n}m`
+  // straight from this frame (glasses-entry.ts). Projecting it away left a valid
+  // JSON payload — so the client's catch never fired — and painted
+  // "Meeting saved — undefinedm". A duration is a scalar with no transcript in it;
+  // `filename` stays stripped precisely because it embeds the meeting TITLE.
+  recording_stop: data => ({ sessionId: data.sessionId, durationMin: data.durationMin }),
+
+  /**
+   * `recording_start` is NOT here, as a DECISION rather than an omission.
+   *
+   * Three reasons, in order of weight:
+   *  1. The failure modes are asymmetric. A missing `stop` leaves the lens asserting
+   *     something FALSE — a recording indicator burning with no recording behind it.
+   *     A missing `start` leaves it showing nothing, which is exactly what the
+   *     ticketless contract promises anyway. Only the wrong state needs repairing.
+   *  2. `start` is a live presence signal. "A meeting is beginning on this machine,
+   *     right now" is occupancy intelligence for any listener on the network; `stop`
+   *     is the erasure of a signal already shown.
+   *  3. Nothing in this server emits it. `grep -rn "type: 'recording_start'" server`
+   *     returns no emitter as of 6.42.0 — it exists in the union for client-side
+   *     use — so allowlisting it would advertise a path that never runs.
+   *
+   * If a server-side emitter is ever added, revisit this WITH a projection; do not
+   * simply add the key.
+   */
+}
+
+/**
+ * The event a ticketless subscriber may receive, or null when it may receive none.
+ * Never returns the input event unchanged — the projection is always applied.
+ */
+function projectForTicketless(event: PublishedDisplayEvent): PublishedDisplayEvent | null {
+  const project = TICKETLESS_PROJECTIONS[event.type]
+  if (!project) return null
+  return { ...event, data: project(event.data) }
+}
+
 function writeEvent(res: Response, event: PublishedDisplayEvent): void {
   const data = JSON.stringify({
     ...event.data,
+    // NESTED, and it must stay nested. Every shipped client reads
+    // `parsed._cosDisplayCursor` and RETURNS EARLY when it is absent
+    // (Main.ts, identically in 6.8.353 and 6.8.441), so flattening these three
+    // fields to the top level silently freezes the client cursor at its
+    // connect-time watermark: `rememberCursor` never fires, and every reconnect
+    // then re-replays and re-processes everything since the connect (duplicate
+    // `done` renders), or trips a spurious buffer_overflow replay_gap past 200
+    // events. 6.42.0 briefly shipped the flattened shape in development; it was
+    // caught pre-release. A test that only asserts `"eventId":1` cannot see the
+    // difference, because that substring is present in BOTH shapes.
     _cosDisplayCursor: {
       bootId: event.bootId,
       eventId: event.eventId,
       publishedAt: event.publishedAt,
     },
   })
+  // SSE `id:` is the reconnect cursor EventSource echoes back as Last-Event-ID.
+  // Namespaced by bootId so a restarted server cannot look like a resumable gap.
   res.write(`id: ${event.bootId}:${event.eventId}\nevent: ${event.type}\ndata: ${data}\n\n`)
 }
 
-displayRouter.get('/display-stream', (req, res) => {
+/**
+ * Ticketless-connect accounting, summarized rather than logged per connect.
+ *
+ * The server sends `retry: 3000`, so ONE client that cannot mint reconnects every
+ * three seconds — 1,200 lines an hour into the launchd log, forever, from a single
+ * stale install. The counter is the point (adoption is measured, not guessed); the
+ * per-line volume is not.
+ */
+const TICKETLESS_LOG_INTERVAL_MS = 60_000
+let ticketlessConnects = 0
+let ticketlessRejectedTickets = 0
+let ticketlessLoggedAt = 0
+
+function noteTicketlessConnect(rejectedTicket: boolean): void {
+  ticketlessConnects++
+  if (rejectedTicket) ticketlessRejectedTickets++
+  const now = Date.now()
+  if (ticketlessLoggedAt !== 0 && now - ticketlessLoggedAt < TICKETLESS_LOG_INTERVAL_MS) return
+  ticketlessLoggedAt = now
+  console.warn(
+    `[display-bus] ${ticketlessConnects} ticketless subscriber(s)`
+    + ` (${ticketlessRejectedTickets} with a rejected ticket) — content withheld, lifecycle only`,
+  )
+  ticketlessConnects = 0
+  ticketlessRejectedTickets = 0
+}
+
+export function __resetDisplayStreamLogForTests(): void {
+  ticketlessConnects = 0
+  ticketlessRejectedTickets = 0
+  ticketlessLoggedAt = 0
+}
+
+/**
+ * A valid `X-Cos-Token` header is equivalent authorization to a ticket.
+ *
+ * The ticket exists only because EventSource cannot set headers. Every fetch-based
+ * consumer can — including the client's own `probeConnectionTarget`, COS Control, and
+ * curl — so requiring those to mint first would suppress content for callers that are
+ * already fully authenticated, and would permanently pollute the ticketless adoption
+ * counter with connections that were never the problem.
+ */
+function headerAuthorized(req: Request): boolean {
+  return timingSafeTokenEqual(req.headers['x-cos-token'], process.env.COS_API_TOKEN ?? '')
+}
+
+/**
+ * Shared handler for both registrations.
+ *
+ * `authorized` decides CONTENT, never admission. A ticketless subscriber still gets
+ * 200, `ready`, the keepalive, lifecycle markers, and replay-gap notices, so every
+ * already-installed client keeps a live transport, keeps `displayBusConnected` true,
+ * and keeps syncing offline meetings. It simply never receives transcripts or answers.
+ */
+function serveDisplayStream(req: Request, res: Response, authorized: boolean): void {
   res.writeHead(200, {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
@@ -38,26 +189,48 @@ displayRouter.get('/display-stream', (req, res) => {
   // Tell EventSource to retry quickly on disconnect (3s instead of browser default ~5-10s)
   res.write('retry: 3000\n\n')
 
+  // DO NOT move this inside an `if (authorized)`. It looks unused on the ticketless
+  // path and is not: a ticketless subscriber never receives buffered events, but it
+  // MUST still be told when its cursor is unresumable (see replay_gap below), and
+  // that verdict is a function of the cursor. Hiding the cursor behind the
+  // authorization check would silently delete ticketless gap reporting.
   const headerCursor = String(req.headers['last-event-id'] ?? '')
   const [headerBootId, headerEventId] = headerCursor.includes(':')
     ? headerCursor.split(':', 2)
     : ['', headerCursor]
   const cursorBootId = String(req.query.bootId ?? headerBootId ?? '') || null
   const cursorEventId = Number(req.query.eventId ?? headerEventId ?? 0)
-  const replay = replayDisplayEvents(cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0)
 
   // Ready is a transport handshake, not proof that replay was consumed. It
   // must precede application events so build 188 can finish admission first.
+  //
+  // `contentAuthorized` is what makes a degraded stream DETECTABLE. Without it the
+  // two handshakes are byte-identical, so a client whose ticket expired sets
+  // `displayBusConnected = true`, sees a healthy socket, and never re-mints — the
+  // stream stays silent forever with nothing anywhere reporting a fault. Old clients
+  // JSON.parse this frame and read only bootId/eventId, so the extra key is inert
+  // for them.
   const watermark = getDisplayWatermark()
-  res.write(`event: ready\ndata: ${JSON.stringify(watermark)}\n\n`)
+  res.write(`event: ready\ndata: ${JSON.stringify({ ...watermark, contentAuthorized: authorized })}\n\n`)
+
+  const replay = replayDisplayEvents(cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0)
   if (replay.gap) {
+    // Ticketless-VISIBLE on purpose. The payload is transport metadata only —
+    // reason, the cursor the client itself sent, the watermark already in `ready`,
+    // and a buffer boundary — so it discloses nothing. Withholding it silently
+    // breaks the client's replay-reconciliation branch after a server restart: the
+    // client would sit on a dead cursor waiting for a resume that cannot come.
     res.write(`event: replay_gap\ndata: ${JSON.stringify({
       reason: replay.reason,
       requested: { bootId: cursorBootId, eventId: cursorEventId },
       watermark,
       oldestEventId: replay.oldestEventId,
     })}\n\n`)
-  } else {
+  } else if (authorized) {
+    // The replay buffer holds up to REPLAY_BUFFER_SIZE past events, so serving it
+    // to a ticketless subscriber would be a retroactive transcript dump — a larger
+    // disclosure than the live subscription. Skipped entirely rather than filtered,
+    // so no future event type can leak through a per-item test here.
     for (const event of replay.events) writeEvent(res, event)
     if (replay.events.length > 0) {
       console.log(`[display-bus] Replayed ${replay.events.length} publish-owned events after ${cursorEventId}`)
@@ -70,13 +243,43 @@ displayRouter.get('/display-stream', (req, res) => {
   }, 15_000)
 
   const unsub = onDisplay((event) => {
-    try { writeEvent(res, event) } catch { /* client gone */ }
+    // The projection runs INSIDE the try, not above it. This is a synchronous
+    // EventEmitter listener, so anything that throws here propagates back out
+    // through `bus.emit()` into whoever called `emitDisplay` — and one of those
+    // callers is the meeting-save path. A malformed event must never be able to
+    // reach a recording. 6.41.0 guarded the whole listener body; keep that.
+    try {
+      const outgoing = authorized ? event : projectForTicketless(event)
+      if (!outgoing) return
+      writeEvent(res, outgoing)
+    } catch { /* client gone, or an event this subscriber simply cannot render */ }
   })
 
   req.on('close', () => {
     clearInterval(ping)
     unsub()
   })
+}
+
+// Ticketless path. Stays public so installed clients keep a live transport; content
+// is withheld above unless the caller sent a valid token header.
+displayRouter.get('/display-stream', (req, res) => {
+  const authorized = headerAuthorized(req)
+  if (!authorized) noteTicketlessConnect(false)
+  serveDisplayStream(req, res, authorized)
+})
+
+// Ticketed path. `api-auth` admits it on SHAPE alone; the signature is verified
+// here, where the API token lives. A bad or expired ticket is not rejected — it
+// degrades to exactly the ticketless stream, so a client whose ticket expired
+// mid-reconnect keeps its transport instead of entering a retry loop. It learns it
+// is degraded from `contentAuthorized:false` in the `ready` frame, and re-mints.
+displayRouter.get('/display-stream/:ticket', (req, res) => {
+  const apiToken = process.env.COS_API_TOKEN ?? ''
+  const ticketOk = verifyDisplayTicket(apiToken, req.params.ticket)
+  const authorized = ticketOk || headerAuthorized(req)
+  if (!authorized) noteTicketlessConnect(true)
+  serveDisplayStream(req, res, authorized)
 })
 
 // POST /api/display-session — broadcast session restore to glasses (cross-surface sync)

package/server/routes/health.ts

@@ -10,6 +10,7 @@ import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contra
 import { isSileroAvailable } from '../lib/vad-silero.js'
 import { profileProvenanceSummary, speakerModelState, speakerReadiness } from '../lib/speaker-embeddings.js'
 import { chunkEmbeddingStoreStats } from '../lib/chunk-embedding-store.js'
+import { mintDisplayTicket, DISPLAY_TICKET_TTL_SECONDS } from '../lib/display-ticket.js'
 import { correctionStoreStats } from '../lib/meeting-corrections.js'
 import { meetingAudioStats } from '../lib/meeting-audio-archive.js'
 import { adaptivePlaybackStatus } from '../lib/adaptive-playback-audio.js'
@@ -353,6 +354,14 @@ healthRouter.get('/health', async (_req, res) => {
     review_audio: reviewAudio,
     ...(voiceProvenance ? { voice_provenance: voiceProvenance } : {}),
     capabilities: {
+      // Advertised on the PUBLIC health route on purpose: a client deciding whether
+      // to request a display ticket may not hold a usable token yet, and an old
+      // server simply omits this key, which is how a new client detects it.
+      displayStream: {
+        ticketSupported: true,
+        ticketTtlSeconds: DISPLAY_TICKET_TTL_SECONDS,
+        contentRequiresTicket: true,
+      },
       transcription: {
         ...transcription,
         live: transcriptionLive,
@@ -429,6 +438,9 @@ healthRouter.get('/models', async (req, res) => {
   // THIS surface and Main.ts states outright that /api/health alone is not used,
   // so a capability published only there is invisible to the phone.
   const threadAttach = threadAttachCapability()
+  // mintDisplayTicket refuses an empty key, because a ticket signed with '' can
+  // never verify. Omit the field rather than publish a dead capability.
+  const apiToken = process.env.COS_API_TOKEN ?? ''
   res.json({
     ...catalog,
     ...threadAttachHealthFields(threadAttach),
@@ -447,6 +459,33 @@ healthRouter.get('/models', async (req, res) => {
     },
     ollamaReady: isOllamaProviderReady(),
     serverInstanceId: getServerInstanceId(),
+    // Minted here rather than on a route of its own: this response is already
+    // authenticated, and the mint is stateless, so it costs nothing and stores
+    // nothing.
+    //
+    // TWO THINGS THIS ROUTE IS NOT, both of which the client must plan around:
+    //
+    // 1. It IS fetched before every connect in the 6.8.441 client — every retry
+    //    calls connectDisplayBus() with no argument, which re-runs
+    //    probeConnectionTarget, which fetches this route. Do not assume that of
+    //    any OTHER client: nothing in the protocol requires it, and a client that
+    //    minted once at pairing would go content-free one TTL later.
+    // 2. Its drain behaviour is NOT what classifyRecoveryRoute implies. That
+    //    classifier puts /api/models in OPERATION_GET_PREFIXES, but its only
+    //    consumer — recoveryAdmissionMiddleware — is never mounted in this build,
+    //    and the gate that IS mounted (server/index.ts) returns next() for every
+    //    GET/HEAD/OPTIONS on its first line. So this route answers 200 during a
+    //    COS Control drain today. Treat the classifier's verdict as the contract a
+    //    build that mounts that middleware would enforce, not as current behaviour.
+    //    (The ticketed display-stream path is exempt either way, so an already-held
+    //    ticket keeps working through a drain — which is still why the TTL has to
+    //    outlive one.)
+    //
+    // So the CLIENT carries the re-mint obligation: fetch /api/models and reconnect
+    // when a display-stream `ready` frame reports `contentAuthorized: false`, or
+    // when DISPLAY_TICKET_TTL_SECONDS has elapsed since the last mint — retrying if
+    // the fetch 503s. Nothing on the server can re-mint on the client's behalf.
+    ...(apiToken ? { displayStreamTicket: mintDisplayTicket(apiToken) } : {}),
     capabilities: {
       durableQueryJobs: {
         enabled: durableJobs.enabled,

package/server/routes/query.ts

@@ -161,9 +161,13 @@ queryRouter.post('/query', async (req, res) => {
           emitDisplay({ type: 'tool_status', data: { message } })
         }
       },
-      // Activity lines stay on this authenticated request stream. The global
-      // display stream is intentionally unauthenticated for Even Hub recovery,
-      // so observable command/output text must never be broadcast there.
+      // Activity lines stay on this authenticated request stream. The guard is
+      // unchanged; the reason has moved. Since 6.42.0 the global display stream is
+      // not "unauthenticated" — it ADMITS ticketless subscribers (200 for everyone,
+      // so an installed client keeps a live transport) and withholds CONTENT per
+      // event instead. Broadcasting observable command/output text onto that bus
+      // would leave it one allowlist entry away from an unauthenticated listener,
+      // so it is never emitted there at all.
       ...(activityToolMode === 'preview' ? {
         onActivityLine: (line: { kind: 'input' | 'output'; text: string }) => {
           if (!done) {