@gotcos/glasses-server 6.99.33 → 7.0.7

package/server/lib/preview-content.ts

@@ -0,0 +1,172 @@
+/**
+ * The content parts of the preview contract (preview engine phase 1, PLAN 4c). Pure transforms of bytes that were
+ * already authorized and read by the resolver (agent-session-output-images.ts `previewFile`), plus the headers each
+ * part is served with. Every part has a FIXED type; nothing a file says about itself decides how it is served.
+ *
+ *   raw      octet-stream attachment, sandbox CSP
+ *   inline   a PDF for the browser's viewer (images go through the normalizer instead)
+ *   text     JSON: a UTF-8 window, 512 KiB per call, `more` for "load more" (HTML: up to 8 MiB, one call)
+ *   table    JSON: CSV or TSV rows, 200 a page, 50 columns, 5,000 rows in all
+ *   html     the page as text/html under `CSP: sandbox` (no scripts, opaque origin, no network), full length (32 MiB)
+ *   html-run the page under `CSP: sandbox allow-scripts` and `connect-src 'none'`: scripts run, nothing is fetched
+ *            Both HTML parts also carry a CSP <meta> injected at the top of the document (PLAN 6), so the policy holds
+ *            even where a response header is lost on the way (a proxy, a saved copy, a future srcdoc frame).
+ *   thumb    PNG from Quick Look (`qlmanage -t`), see preview-thumbs.ts
+ */
+
+export const TEXT_WINDOW_MAX = 512 * 1024
+/** HTML is shown full length (PLAN 5: the 512 KiB cut is gone), up to the raw-file cap. */
+export const HTML_PREVIEW_MAX = 32 * 1024 * 1024
+export const TABLE_PAGE_ROWS = 200
+export const TABLE_COLUMNS_MAX = 50
+export const TABLE_ROWS_MAX = 5000
+export const TABLE_CELL_CHARS = 1000
+export const TABLE_BYTES_MAX = 16 * 1024 * 1024
+
+export type PreviewPart = 'raw' | 'inline' | 'text' | 'table' | 'html' | 'html-run' | 'thumb'
+export const PREVIEW_PARTS: readonly PreviewPart[] = ['raw', 'inline', 'text', 'table', 'html', 'html-run', 'thumb']
+
+/** Scripts off: nothing runs, nothing is fetched (a remote image is a tracking pixel and leaks the phone's address). */
+export const HTML_SAFE_CSP = "sandbox; default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:; form-action 'none'; base-uri 'none'; frame-ancestors 'self'"
+/**
+ * "Run scripts" (Miles decision 3): inline script runs in a unique opaque origin (no allow-same-origin), with no
+ * network (`connect-src 'none'`, no remote script, image, style or font), no forms, no popups and no top navigation
+ * (sandbox tokens other than allow-scripts are absent). It can read only itself, never the COS cookie or API.
+ */
+export const HTML_RUN_CSP = "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; media-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-ancestors 'self'"
+export const DERIVED_CSP = "sandbox; default-src 'none'"
+/**
+ * The policies injected as a <meta> (a meta CSP cannot carry `sandbox` or `frame-ancestors`; the header and the frame's
+ * own sandbox attribute carry those). Two policies are both enforced, so a page's own looser meta never widens these.
+ */
+export const HTML_SAFE_META_CSP = "default-src 'none'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; form-action 'none'; base-uri 'none'"
+export const HTML_RUN_META_CSP = "default-src 'none'; script-src 'unsafe-inline'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; media-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'"
+
+/**
+ * 7.0.5 canary 16 (Chrome 156 and WebKit 26.6, real viewer and route): with scripts on, a page script reached the
+ * network through WebRTC (5 STUN UDP datagrams in each). `connect-src 'none'` does not cover WebRTC and Chrome ignores
+ * `webrtc 'block'`. This guard, run before any page script, makes the RTC constructors non-configurable `undefined` on
+ * the window: 0 datagrams in both browsers. It is not a promise of "no network" (the words never say that).
+ */
+export const HTML_RUN_RTC_NAMES = ['RTCPeerConnection', 'webkitRTCPeerConnection', 'RTCDataChannel', 'RTCSessionDescription', 'RTCIceCandidate'] as const
+export const HTML_RUN_RTC_GUARD = '<script>(function(){var n=' + JSON.stringify(HTML_RUN_RTC_NAMES) +
+  ';for(var i=0;i<n.length;i++){try{Object.defineProperty(window,n[i],{value:undefined,writable:false,enumerable:false,configurable:false})}catch(e){}}})();</script>'
+
+/**
+ * The page with a CSP <meta> as the first thing the parser sees after any BOM, leading whitespace, comments and the
+ * doctype (a tag before the doctype would put the page in quirks mode). Nothing before that point can load anything.
+ * Bytes are spliced, never re-encoded, so a page in another charset is not changed beyond the inserted tag.
+ */
+export function withCspMeta(bytes: Buffer, part: 'html' | 'html-run'): Buffer {
+  const policy = part === 'html-run' ? HTML_RUN_META_CSP : HTML_SAFE_META_CSP
+  // Run scripts: the WebRTC guard is the first script the page has (canary 16d), right after the policy.
+  const tag = Buffer.from(`<meta http-equiv="Content-Security-Policy" content="${policy}">` + (part === 'html-run' ? HTML_RUN_RTC_GUARD : ''), 'utf8')
+  // The prefix is ASCII in every case that matters; latin1 keeps one char per byte so offsets are byte offsets.
+  const head = bytes.subarray(0, 64 * 1024).toString('latin1')
+  let at = head.charCodeAt(0) === 0xef && head.charCodeAt(1) === 0xbb && head.charCodeAt(2) === 0xbf ? 3 : 0
+  for (let guard = 0; guard < 64; guard++) {
+    const ws = /^[\t\n\f\r ]*/.exec(head.slice(at))![0].length
+    at += ws
+    if (head.startsWith('<!--', at)) {
+      const end = head.indexOf('-->', at + 4)
+      if (end < 0) break
+      at = end + 3; continue
+    }
+    if (/^<!doctype[\s>]/i.test(head.slice(at, at + 10))) {
+      const end = head.indexOf('>', at)
+      if (end < 0) break
+      at = end + 1; continue
+    }
+    break
+  }
+  return Buffer.concat([bytes.subarray(0, at), tag, bytes.subarray(at)])
+}
+
+function asciiName(name: string): string { return name.replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[ .]+/, '') || 'file' }
+
+/** Headers for each part. `nosniff`, `no-store` and same-origin CORP on every one. */
+export function previewHeaders(part: PreviewPart, name: string): Record<string, string> {
+  const base: Record<string, string> = { 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'private, no-store', 'Cross-Origin-Resource-Policy': 'same-origin' }
+  const disposition = (kind: 'inline' | 'attachment') => `${kind}; filename="${asciiName(name)}"; filename*=UTF-8''${encodeURIComponent(name)}`
+  switch (part) {
+    case 'raw': return { ...base, 'Content-Type': 'application/octet-stream', 'Content-Disposition': disposition('attachment'), 'Content-Security-Policy': DERIVED_CSP }
+    case 'inline': return { ...base, 'Content-Type': 'application/pdf', 'Content-Disposition': disposition('inline') }
+    case 'html': return { ...base, 'Content-Type': 'text/html; charset=utf-8', 'Content-Disposition': 'inline', 'Content-Security-Policy': HTML_SAFE_CSP, 'Referrer-Policy': 'no-referrer' }
+    case 'html-run': return { ...base, 'Content-Type': 'text/html; charset=utf-8', 'Content-Disposition': 'inline', 'Content-Security-Policy': HTML_RUN_CSP, 'Referrer-Policy': 'no-referrer' }
+    case 'thumb': return { ...base, 'Content-Type': 'image/png', 'Content-Disposition': 'inline', 'Content-Security-Policy': DERIVED_CSP }
+    default: return { ...base, 'Content-Type': 'application/json; charset=utf-8', 'Content-Security-Policy': DERIVED_CSP }
+  }
+}
+
+/** A NUL byte in the first 8 KiB: a binary file, never shown as words. */
+export function looksBinary(bytes: Buffer): boolean { return bytes.subarray(0, 8192).includes(0) }
+
+function charStart(bytes: Buffer, at: number): number {
+  let i = Math.max(0, Math.min(at, bytes.length))
+  while (i < bytes.length && i > 0 && (bytes[i] & 0xc0) === 0x80) i--
+  return i
+}
+
+/** A UTF-8 window that never splits a character. `end` is where the next window starts. */
+export function textWindow(bytes: Buffer, offset: number, limit: number, max = TEXT_WINDOW_MAX): { text: string; offset: number; end: number; size: number; more: boolean } {
+  const want = Math.max(1, Math.min(max, Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : max))
+  let start = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0
+  if (start > bytes.length) start = bytes.length
+  // A start inside a character moves forward to the next one.
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++
+  let end = Math.min(bytes.length, start + want)
+  if (end < bytes.length) { const c = charStart(bytes, end); end = c > start ? c : end }
+  let text = bytes.subarray(start, end).toString('utf8')
+  if (start === 0 && text.charCodeAt(0) === 0xfeff) text = text.slice(1)
+  return { text, offset: start, end, size: bytes.length, more: end < bytes.length }
+}
+
+/**
+ * RFC 4180 rows from CSV (or TSV): quoted fields, doubled quotes, CR LF or LF, a newline inside quotes. Bounded: at most
+ * TABLE_ROWS_MAX rows are ever read, TABLE_COLUMNS_MAX columns per row and TABLE_CELL_CHARS per cell are kept.
+ */
+export function tableRows(text: string, delimiter: ',' | '\t', limitRows = TABLE_ROWS_MAX): { rows: string[][]; complete: boolean; columnsCut: boolean } {
+  const rows: string[][] = []
+  let row: string[] = [], cell = '', quoted = false, columnsCut = false, i = 0
+  const push = () => {
+    if (row.length < TABLE_COLUMNS_MAX) row.push(cell.length > TABLE_CELL_CHARS ? cell.slice(0, TABLE_CELL_CHARS - 1) + '…' : cell)
+    else columnsCut = true
+    cell = ''
+  }
+  const endRow = () => { push(); rows.push(row); row = [] }
+  if (text.charCodeAt(0) === 0xfeff) i = 1
+  for (; i < text.length; i++) {
+    const c = text[i]
+    if (quoted) {
+      if (c === '"') { if (text[i + 1] === '"') { if (cell.length <= TABLE_CELL_CHARS) cell += '"'; i++ } else quoted = false }
+      else if (cell.length <= TABLE_CELL_CHARS) cell += c
+      continue
+    }
+    if (c === '"' && cell === '') { quoted = true; continue }
+    if (c === delimiter) { push(); continue }
+    if (c === '\r' || c === '\n') {
+      if (c === '\r' && text[i + 1] === '\n') i++
+      endRow()
+      if (rows.length >= limitRows) return { rows, complete: i + 1 >= text.length, columnsCut }
+      continue
+    }
+    if (cell.length <= TABLE_CELL_CHARS) cell += c
+  }
+  if (cell !== '' || row.length) endRow()
+  return { rows, complete: true, columnsCut }
+}
+
+/** One page of a table: the header row always first, then rows [offset, offset + TABLE_PAGE_ROWS). */
+export function tablePage(bytes: Buffer, name: string, offset: number): { header: string[]; rows: string[][]; offset: number; next: number; more: boolean; capped: boolean; columnsCut: boolean } {
+  const text = bytes.subarray(0, TABLE_BYTES_MAX).toString('utf8')
+  const delimiter = /\.tsv$/i.test(name) ? '\t' : ','
+  const parsed = tableRows(text, delimiter, TABLE_ROWS_MAX + 1)
+  const all = parsed.rows
+  const header = all[0] ?? []
+  const body = all.slice(1, TABLE_ROWS_MAX + 1)
+  const start = Math.max(0, Math.min(body.length, Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0))
+  const page = body.slice(start, start + TABLE_PAGE_ROWS)
+  const next = start + page.length
+  const capped = !parsed.complete || bytes.length > TABLE_BYTES_MAX || all.length > TABLE_ROWS_MAX
+  return { header, rows: page, offset: start, next, more: next < body.length, capped, columnsCut: parsed.columnsCut }
+}

package/server/lib/preview-error-code.ts

@@ -0,0 +1,10 @@
+/**
+ * 7.0.4 QA: what a failed preview read is logged as: the error's code (ENOENT, EACCES, ...) or its class, never its
+ * message. An fs error message carries the path, and a path never goes into a log line.
+ */
+export function previewErrorCode(error: unknown): string {
+  const code = (error as { code?: unknown } | null)?.code
+  if (typeof code === 'string' && /^[A-Z0-9_]{1,40}$/.test(code)) return code
+  const name = (error as { name?: unknown } | null)?.name
+  return typeof name === 'string' && /^[A-Za-z]{1,40}$/.test(name) ? name : 'unknown'
+}

package/server/lib/preview-folders-setting.ts

@@ -0,0 +1,133 @@
+/**
+ * Extra folders COS may preview from (preview engine phase 1, Miles 2026-11-08, decision 2).
+ *
+ * A link card or a sent file is served only when its canonical path is inside the session's own workspace OR inside
+ * one of the folders named here. Nothing else ever opens. The list starts EMPTY.
+ *
+ * Stored the way "Show session files, screenshots and images" is (lib/session-files-setting.ts): a small private JSON
+ * file in the data folder, written atomically with mode 0600. Only a file that is not there (first use) gets the
+ * default (no folders). A saved file that is damaged, unreadable or not this schema fails CLOSED: no extra folders,
+ * source 'damaged'. Settings says so, and saving from it writes a good file again.
+ *
+ * Each folder must be absolute (or ~/...), exist, be a directory, and must not be or contain a broad root: /, /Users,
+ * home, ~/Documents, ~/Library, ~/.cos-glasses, /Volumes, the temp roots (the same exact roots a session workspace may
+ * never be). A folder inside ~/Library, ~/.cos-glasses, ~/.ssh, ~/.codex, ~/.claude or ~/.config is refused too. Stored canonical (realpath), and
+ * re-checked on every read, so a folder deleted or replaced by a link later simply stops counting.
+ */
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { securePrivateDirectory } from './secure-user-config.js'
+import { broadWorkspaceRoots } from './agent-session-output-images.js'
+
+export const PREVIEW_FOLDERS_FILE = 'web-preview-folders.json'
+export const PREVIEW_FOLDERS_MAX = 20
+const FOLDER_CHARS_MAX = 1024
+
+export type PreviewFoldersSource = 'settings' | 'default' | 'damaged'
+export interface PreviewFoldersSetting { folders: string[]; source: PreviewFoldersSource }
+export type FolderRefusal = 'not_absolute' | 'missing' | 'not_folder' | 'broad' | 'private' | 'too_long' | 'too_many'
+export interface FolderError { index: number; code: FolderRefusal; message: string }
+export interface PreviewFoldersStore {
+  read(): PreviewFoldersSetting
+  set(input: unknown): { ok: true; setting: PreviewFoldersSetting } | { ok: false; errors: FolderError[] }
+}
+
+const MESSAGES: Record<FolderRefusal, string> = {
+  not_absolute: 'Use a full folder path, like ~/cos-worktrees.',
+  missing: 'That folder is not on this Mac.',
+  not_folder: 'That is a file, not a folder.',
+  broad: 'That folder is too broad. Name a project folder inside it.',
+  private: 'COS never previews from that folder.',
+  too_long: 'That path is too long.',
+  too_many: `At most ${PREVIEW_FOLDERS_MAX} folders.`,
+}
+
+/** Folders under home that are never a preview folder, nor anything inside them. */
+export const PRIVATE_HOME_FOLDERS: readonly string[] = ['Library', '.cos-glasses', '.ssh', '.codex', '.claude', '.config']
+
+function within(root: string, path: string): boolean {
+  const rel = relative(root, path)
+  return rel === '' || (!rel.startsWith('..' + sep) && rel !== '..' && !isAbsolute(rel))
+}
+
+/** One folder as typed, checked. Pure apart from the filesystem reads. */
+export function checkFolder(input: unknown, home = homedir()): { ok: true; path: string } | { ok: false; code: FolderRefusal } {
+  if (typeof input !== 'string') return { ok: false, code: 'not_absolute' }
+  const raw = input.trim()
+  if (!raw) return { ok: false, code: 'not_absolute' }
+  if (raw.length > FOLDER_CHARS_MAX || /[\u0000-\u001f\u007f]/.test(raw)) return { ok: false, code: 'too_long' }
+  const expanded = raw === '~' ? home : raw.startsWith('~/') ? join(home, raw.slice(2)) : raw
+  if (!isAbsolute(expanded)) return { ok: false, code: 'not_absolute' }
+  let canonical: string
+  try { canonical = realpathSync(resolve(expanded)) } catch { return { ok: false, code: 'missing' } }
+  try { if (!statSync(canonical).isDirectory()) return { ok: false, code: 'not_folder' } } catch { return { ok: false, code: 'missing' } }
+  // Never a broad root, and never a folder that CONTAINS one (/ contains everything, /private contains /private/tmp).
+  for (const broad of broadWorkspaceRoots(home)) if (within(canonical, broad)) return { ok: false, code: 'broad' }
+  // QA 7.0.5: the AI apps' own folders hold their sign-in tokens and settings (~/.codex/auth.json, ~/.claude, ~/.config).
+  for (const p of PRIVATE_HOME_FOLDERS) {
+    const base = join(home, p)
+    let real = base
+    try { real = realpathSync(base) } catch { /* absent: the literal still counts */ }
+    if (within(base, canonical) || within(real, canonical)) return { ok: false, code: 'private' }
+  }
+  return { ok: true, path: canonical }
+}
+
+/** How Settings shows a folder: ~/x inside home, the full path elsewhere. */
+export function folderDisplay(path: string, home = homedir()): string {
+  const rel = relative(home, path)
+  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? '~/' + rel.split(sep).join('/') : path
+}
+
+export function createPreviewFoldersSetting(deps: { file: () => string; home?: () => string }): PreviewFoldersStore {
+  const home = () => deps.home?.() ?? homedir()
+  type Saved = { kind: 'absent' } | { kind: 'damaged' } | { kind: 'saved'; folders: string[] }
+  const saved = (): Saved => {
+    let text: string
+    try { text = readFileSync(deps.file(), 'utf8') } catch (e) {
+      return (e as NodeJS.ErrnoException | null)?.code === 'ENOENT' ? { kind: 'absent' } : { kind: 'damaged' }
+    }
+    try {
+      const raw = JSON.parse(text) as { schema?: unknown; folders?: unknown }
+      if (raw && typeof raw === 'object' && raw.schema === 1 && Array.isArray(raw.folders) && raw.folders.length <= PREVIEW_FOLDERS_MAX
+        && raw.folders.every(f => typeof f === 'string')) return { kind: 'saved', folders: raw.folders as string[] }
+    } catch { /* damaged */ }
+    return { kind: 'damaged' }
+  }
+  const store: PreviewFoldersStore = {
+    read() {
+      const s = saved()
+      if (s.kind === 'damaged') return { folders: [], source: 'damaged' }
+      if (s.kind === 'absent') return { folders: [], source: 'default' }
+      // Re-checked on every read: a folder that is gone, became a link to a broad root, or is now private never counts.
+      const out: string[] = []
+      for (const f of s.folders) {
+        const c = checkFolder(f, home())
+        if (c.ok && c.path === f && !out.includes(c.path)) out.push(c.path)
+      }
+      return { folders: out, source: 'settings' }
+    },
+    set(input) {
+      if (!Array.isArray(input)) return { ok: false, errors: [{ index: -1, code: 'not_absolute', message: 'Send { folders: [ ... ] }.' }] }
+      if (input.length > PREVIEW_FOLDERS_MAX) return { ok: false, errors: [{ index: -1, code: 'too_many', message: MESSAGES.too_many }] }
+      const errors: FolderError[] = [], folders: string[] = []
+      input.forEach((f, index) => {
+        const c = checkFolder(f, home())
+        if (!c.ok) errors.push({ index, code: c.code, message: MESSAGES[c.code] })
+        else if (!folders.includes(c.path)) folders.push(c.path)
+      })
+      if (errors.length) return { ok: false, errors }
+      const file = deps.file()
+      securePrivateDirectory(dirname(file))
+      durableAtomicWriteFileSync(file, JSON.stringify({ schema: 1, folders }) + '\n', { mode: 0o600 })
+      return { ok: true, setting: store.read() }
+    },
+  }
+  return store
+}
+
+/** The server's list, in the data folder. */
+export const previewFoldersSetting = createPreviewFoldersSetting({ file: () => dataPath(PREVIEW_FOLDERS_FILE) })

package/server/lib/preview-log-throttle.ts

@@ -0,0 +1,18 @@
+/**
+ * 7.0.4 QA, shared in 7.0.7: the one burst limit for preview refusal and failure logs. The 7.0.4 file and image routes
+ * (routes/agent-sessions.ts logPreviewOutcome) and the 7.0.5 preview engine routes (routes/session-preview.ts
+ * logPreviewRefusal) both log through it. The same line logs once per 10 seconds, with the count it held back. A line is
+ * only fixed words (a route, a reason code, a provider, a part, a kind, a detail code), so the keys stay few.
+ */
+const lastLogged = new Map<string, { at: number; quiet: number }>()
+export const PREVIEW_LOG_WINDOW_MS = 10_000
+
+export function warnPreviewThrottled(key: string, line: string, now = Date.now()): void {
+  const last = lastLogged.get(key)
+  if (last && now - last.at < PREVIEW_LOG_WINDOW_MS) { last.quiet++; return }
+  lastLogged.set(key, { at: now, quiet: 0 })
+  console.warn(`${line}${last?.quiet ? ` (+${last.quiet} like it)` : ''}`)
+}
+
+/** Tests only: forget the burst window, so each case logs. */
+export function resetPreviewLogThrottle(): void { lastLogged.clear() }

package/server/lib/preview-thumbs.ts

@@ -0,0 +1,139 @@
+/**
+ * Card thumbnails from Quick Look (preview engine phase 1, PLAN 6 and 7). `qlmanage -t` is built into macOS and runs
+ * the Mac's own sandboxed Quick Look extensions; it drew page 1 of a PDF, DOCX, PPTX, XLSX and HTML headless in 0.26 to
+ * 0.48 s in the plan's canary, and its HTML thumbnail runs no script and loads no remote image (canary 3).
+ *
+ * - Runs on a PRIVATE COPY of bytes the resolver already validated (no TOCTOU on the original), in a 0700 temp folder,
+ *   with an argument array, `nice`, a 10 s timeout and SIGKILL past it. Two at once, machine-wide in this process.
+ * - The output must be a real PNG under 4 MiB, or there is no thumbnail.
+ * - Cached on disk under the data folder, keyed by the file's identity (device, inode, size, mtime, ctime), never by
+ *   path. 128 MiB and 7 days at most; the oldest go first. A hit refreshes its age.
+ * - When Quick Look cannot run (no window server, a launchd context that refuses it, a timeout), the answer is
+ *   `unavailable` and the card says there is no preview image. It never fails the card.
+ */
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { extname, join } from 'node:path'
+import { dataPath } from './data-dir.js'
+import { previewErrorCode } from './preview-error-code.js'
+
+export const THUMB_SIZE = 256
+export const THUMB_TIMEOUT_MS = 10_000
+export const THUMB_CONCURRENCY = 2
+export const THUMB_CACHE_BYTES = 128 * 1024 * 1024
+export const THUMB_CACHE_AGE_MS = 7 * 24 * 60 * 60_000
+export const THUMB_OUTPUT_MAX = 4 * 1024 * 1024
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+export interface Identity { dev: number; ino: number; size: number; mtimeMs: number; ctimeMs: number }
+export type RunResult = { code: number | null; signal: string | null; timedOut: boolean }
+/** QA 7.0.5: why a thumbnail was not made, for the route's one log line (never a path or a file name). */
+export type ThumbFailure = 'timeout' | 'exit' | 'no_png' | 'bad_png' | `error_${string}`
+export interface ThumbDeps {
+  dir(): string
+  tmp(): string
+  now(): number
+  run(file: string, args: string[], timeoutMs: number): Promise<RunResult>
+}
+
+/**
+ * 7.0.5 canary 4: Quick Look reads an HTML page with no declared charset as Latin-1, so a UTF-8 page thumbnails as
+ * mojibake ("Café"). In the PRIVATE copy only, and only when the page declares no charset and its bytes are valid
+ * UTF-8, `<meta charset="utf-8">` goes right after `<head>` (or first, when there is no head). Proven under launchd.
+ */
+export function withUtf8Charset(bytes: Buffer, name: string): Buffer {
+  if (!/\.html?$/i.test(name)) return bytes
+  const head = bytes.subarray(0, 4096).toString('latin1')
+  if (/<meta\b[^>]*\bcharset\s*=/i.test(head)) return bytes
+  try { new TextDecoder('utf-8', { fatal: true }).decode(bytes) } catch { return bytes }
+  const tag = Buffer.from('<meta charset="utf-8">')
+  const m = /<head\b[^>]*>/i.exec(head)
+  const at = m ? m.index + m[0].length : 0
+  return Buffer.concat([bytes.subarray(0, at), tag, bytes.subarray(at)])
+}
+
+export function thumbKey(identity: Identity): string {
+  // v2 (7.0.5): HTML thumbnails drawn before the charset fix were mojibake; a new key draws them again.
+  return createHash('sha256').update(JSON.stringify(['thumb-v2', THUMB_SIZE, identity.dev, identity.ino, identity.size, identity.mtimeMs, identity.ctimeMs])).digest('hex')
+}
+
+const realRun: ThumbDeps['run'] = (file, args, timeoutMs) => new Promise(resolve => {
+  const child = execFile(file, args, { timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 256 * 1024, windowsHide: true }, err => {
+    const e = err as (NodeJS.ErrnoException & { killed?: boolean; signal?: string; code?: number | string }) | null
+    resolve({ code: e ? (typeof e.code === 'number' ? e.code : null) : 0, signal: e?.signal ?? null, timedOut: !!e?.killed })
+  })
+  child.stdin?.end()
+})
+
+export function createThumbnailer(deps: ThumbDeps) {
+  let active = 0
+  const evict = (dir: string) => {
+    let entries: Array<{ path: string; size: number; at: number }> = []
+    try {
+      entries = readdirSync(dir).filter(n => /^[a-f0-9]{64}\.png$/.test(n)).map(n => {
+        const p = join(dir, n), st = statSync(p)
+        return { path: p, size: st.size, at: st.mtimeMs }
+      })
+    } catch { return }
+    const now = deps.now()
+    entries.sort((a, b) => a.at - b.at)
+    let total = entries.reduce((n, e) => n + e.size, 0)
+    for (const e of entries) {
+      if (now - e.at <= THUMB_CACHE_AGE_MS && total <= THUMB_CACHE_BYTES) continue
+      try { rmSync(e.path, { force: true }); total -= e.size } catch { /* next */ }
+    }
+  }
+  return {
+    get active() { return active },
+    /** The cached or new PNG for these bytes, or why there is none. */
+    async thumbnail(bytes: Buffer, name: string, identity: Identity): Promise<{ status: 'ok'; path: string } | { status: 'busy' } | { status: 'unavailable'; reason: ThumbFailure }> {
+      const dir = deps.dir()
+      const key = thumbKey(identity)
+      const cached = join(dir, key + '.png')
+      try {
+        const st = statSync(cached)
+        if (deps.now() - st.mtimeMs <= THUMB_CACHE_AGE_MS && st.size > PNG.length) {
+          const t = new Date(deps.now()); try { utimesSync(cached, t, t) } catch { /* age only */ }
+          return { status: 'ok', path: cached }
+        }
+      } catch { /* not cached */ }
+      if (active >= THUMB_CONCURRENCY) return { status: 'busy' }
+      active++
+      const work = mkdtempSync(join(deps.tmp(), 'cos-preview-'))
+      try {
+        chmodSync(work, 0o700)
+        // A fixed base name with the original extension: Quick Look picks its generator by extension, and no
+        // file name a session wrote reaches the command line.
+        const ext = extname(name).toLowerCase().replace(/[^.a-z0-9]/g, '').slice(0, 10)
+        const copy = join(work, 'preview' + ext)
+        writeFileSync(copy, withUtf8Charset(bytes, name), { mode: 0o600 })
+        const out = join(work, 'out'); mkdirSync(out, { mode: 0o700 })
+        const result = await deps.run('/usr/bin/nice', ['-n', '10', '/usr/bin/qlmanage', '-t', '-s', String(THUMB_SIZE), '-o', out, copy], THUMB_TIMEOUT_MS)
+        if (result.timedOut || result.code !== 0) return { status: 'unavailable', reason: result.timedOut ? 'timeout' : 'exit' }
+        const produced = join(out, 'preview' + ext + '.png')
+        let png: Buffer
+        try { png = readFileSync(produced) } catch { return { status: 'unavailable', reason: 'no_png' } }
+        if (png.length <= PNG.length || png.length > THUMB_OUTPUT_MAX || !png.subarray(0, 8).equals(PNG)) return { status: 'unavailable', reason: 'bad_png' }
+        mkdirSync(dir, { recursive: true, mode: 0o700 })
+        const staged = join(dir, key + '.' + process.pid + '.tmp')
+        writeFileSync(staged, png, { mode: 0o600 })
+        renameSync(staged, cached)
+        evict(dir)
+        return { status: 'ok', path: cached }
+      } catch (error) { return { status: 'unavailable', reason: ('error_' + previewErrorCode(error)) as ThumbFailure } }
+      finally {
+        active--
+        try { rmSync(work, { recursive: true, force: true }) } catch { /* temp */ }
+      }
+    },
+  }
+}
+
+export const previewThumbnailer = createThumbnailer({
+  dir: () => dataPath('preview-thumbs'),
+  tmp: () => tmpdir(),
+  now: Date.now,
+  run: realRun,
+})

package/server/lib/secret-path-guard.ts

@@ -0,0 +1,80 @@
+// One shared secret-name deny guard for every route that serves a local file (7.0.4 S2).
+//
+// WHY. The preview routes (sent output files, sent output images, Markdown output images and
+// path-backed tool images) authorize by workspace containment: a file inside the session's exact
+// workspace is servable. A repo holds its own secrets inside that workspace (`.env`, a service
+// account `*-key.json`, a `.pem`), and a session can name one in a SendUserFile call or a Markdown
+// image just as easily as a render. Containment says "this session may show files from here", not
+// "every file here is safe to put in a browser". This guard is the second question.
+//
+// HOW. By name, case-insensitively, and on both the path as given and its canonical (realpath) form, so a symlink
+// with an innocent name that points at a secret is still refused. File-name patterns (`.env*`, `*-key.json`, `id_rsa`,
+// ...) are matched against the BASE NAME only. Folders are matched only against an exact list of secret folder names
+// (`.ssh`, `.gnupg`, `secrets`) and a few exact folder and file pairs (`.aws/config`, `.kube/config`, ...). 7.0.4 QA:
+// the first cut ran every file pattern against every folder, so a repo under `credentials-portal/`, `.envoy/` or
+// `id_verification/` had every preview refused. A path that cannot be canonicalised (gone, permission) is judged by its
+// lexical form only; the callers refuse unreadable files separately.
+//
+// LIMITS. A name-based guard cannot see a COPY of a secret under another name, and realpath does not resolve a HARD
+// link. The sent-file routes, which can serve any text, refuse a file with more than one hard link for that reason
+// (agent-session-output-images.ts); images go through the JPEG normaliser, so a text secret cannot leave as one.
+//
+// The name is fixed (`isDeniedSecretPath`): another branch codes against it.
+import { realpathSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+
+/** File names refused, matched against the base name only. Lower-cased input. */
+const SECRET_NAME: readonly RegExp[] = [
+  /^\.env/, // .env*: .env, .env.local, .envrc, .env_backup …
+  /-key\.json$/, // service-account keys (gcp-key.json, firebase-admin-key.json)
+  /^service-account.*\.json$/, // service-account.json, service-account-prod.json
+  /^\.cos-profile/, // the COS profile and its backups
+  /^id_(rsa|dsa|ecdsa|ed25519|xmss)/, /^id_[a-z0-9_-]*(\.pub)?$/, // SSH keys and look-alikes (id_rsa.png), not id_card.png
+  /\.pem$/, /\.p12$/, /\.pfx$/, /\.key$/, // certificates and private keys
+  /^authkey_.*\.p8$/, // App Store Connect API keys (AuthKey_ABC123.p8)
+  /^credentials/, // credentials, credentials.json, credentials.csv; also .aws/credentials
+  /^\.git-credentials$/, // plaintext git tokens
+  /^tokens?\.json$/, // OAuth token stores (token.json)
+  /^secrets?\.ya?ml$/, // secrets.yaml, secrets.yml
+  /^\.netrc$/, /^\.npmrc$/, /^\.pypirc$/, /^\.pgpass$/, /^\.htpasswd$/, // package, network and database credentials
+  /\.keychain/, // login.keychain-db and friends
+  /^hook-token$/, // 7.0.5 (preview engine, PLAN 6): the COS hook token beside the glasses data
+  // QA 7.0.5: a link card puts a file one tap away, so these join the list.
+  /^hubspot\.config\.ya?ml$/, // the HubSpot CLI's portal keys
+  /^\.mcp\.json$/, // MCP server definitions, which often carry tokens
+  /^\.credentials\.json$/, // Claude Code's sign-in (~/.claude/.credentials.json)
+]
+/** Folders whose whole subtree is refused, matched exactly as a folder name. Lower-cased. */
+const SECRET_DIRECTORY = new Set(['.ssh', '.gnupg', 'secrets'])
+/** A file refused only inside this folder (`config` alone is an ordinary name). Lower-cased `folder/file`. */
+const SECRET_PAIR = new Set(['.aws/credentials', '.aws/config', '.docker/config.json', '.kube/config', 'gh/hosts.yml', '.codex/auth.json'])
+
+function segments(path: string): string[] {
+  return path.split(/[\\/]+/).filter(Boolean).map(s => s.toLowerCase())
+}
+
+function deniedLexically(path: string): boolean {
+  const parts = segments(path)
+  const name = parts[parts.length - 1]
+  if (!name) return false
+  if (SECRET_NAME.some(re => re.test(name))) return true
+  if (parts.length >= 2 && SECRET_PAIR.has(parts[parts.length - 2] + '/' + name)) return true
+  return parts.slice(0, -1).some(folder => SECRET_DIRECTORY.has(folder))
+}
+
+/**
+ * True when this local path, or the file it canonically resolves to, may hold secrets and must
+ * never be served to a browser. A relative path is resolved against the process directory first;
+ * callers pass absolute paths. Never throws.
+ */
+export function isDeniedSecretPath(absPath: string): boolean {
+  if (typeof absPath !== 'string' || !absPath) return false
+  const path = isAbsolute(absPath) ? absPath : resolve(absPath)
+  if (deniedLexically(path)) return true
+  let canonical: string
+  try { canonical = realpathSync(path) } catch { return false }
+  return deniedLexically(canonical)
+}
+
+/** The card text a projection shows in place of a denied file. No name beyond the base name travels with it. */
+export const SECRET_FILE_NOTICE = 'Not shown: this file may hold secrets'

package/server/lib/session-files-setting.ts

@@ -0,0 +1,88 @@
+/**
+ * "Show files and images your sessions make" (6.99.35). Miles asked where a person opts in to the images (6.99.28) and
+ * files (SendUserFile) Control Web shows from a session's project folder. This is that switch, stored the way the
+ * Today summary switch is (lib/today-brief.ts): a small private JSON file in the data folder, written atomically.
+ *
+ * - DEFAULT ON, as both features shipped.
+ * - The Settings toggle (Control Web, Settings, Privacy) saves { schema: 1, enabled } to web-session-files-settings.json.
+ * - COS_WEB_SESSION_FILES=0 (or false, off) on the Mac forces it OFF, whatever was saved. No value forces it on: an
+ *   environment that wants previews leaves the variable unset.
+ * - Read on every request, so a change applies at once and a restart is never needed.
+ * - QA 7.0.0: only a file that is not there (first use) gets the default. A saved file that is damaged, unreadable or
+ *   not this schema fails CLOSED (source 'damaged', off): it may have said off, and a privacy switch never turns itself
+ *   back on. The Settings row says so, and saving from it writes a good file again.
+ *
+ * Preview engine phase 1: link cards (outputLinks) and GET /api/preview/... ride the same switch, default on.
+ *
+ * Off means: GET .../output-images/:id/content, .../output-files/:id/content and .../tool-images/:id/content answer 403 previews_off before any
+ * transcript or file is read, and the session detail's turns carry `previewsOff: true` instead of image and file
+ * descriptors (withoutPreviews), so not even a name reaches the browser.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { readSwitch } from './env-switch.js'
+import { securePrivateDirectory } from './secure-user-config.js'
+import type { SessionTurn } from './agent-session-turns.js'
+import { withoutLinkCards } from './session-links.js'
+
+export const SESSION_FILES_SETTINGS_FILE = 'web-session-files-settings.json'
+export type SessionFilesSource = 'env' | 'settings' | 'default' | 'damaged'
+export interface SessionFilesSetting { enabled: boolean; source: SessionFilesSource; saved: boolean | null }
+export interface SessionFilesSettingStore {
+  read(): SessionFilesSetting
+  set(enabled: boolean): SessionFilesSetting
+}
+
+export function createSessionFilesSetting(deps: { file: () => string; env?: () => Record<string, string | undefined> }): SessionFilesSettingStore {
+  const env = deps.env ?? (() => process.env)
+  // 'absent' only for ENOENT (first use). Any other read error, bad JSON or a foreign shape is 'damaged'.
+  type Saved = { kind: 'absent' } | { kind: 'damaged' } | { kind: 'saved'; enabled: boolean }
+  const saved = (): Saved => {
+    let text: string
+    try { text = readFileSync(deps.file(), 'utf8') } catch (e) {
+      return (e as NodeJS.ErrnoException | null)?.code === 'ENOENT' ? { kind: 'absent' } : { kind: 'damaged' }
+    }
+    try {
+      const raw = JSON.parse(text) as unknown
+      if (raw && typeof raw === 'object' && (raw as { schema?: unknown }).schema === 1 && typeof (raw as { enabled?: unknown }).enabled === 'boolean') {
+        return { kind: 'saved', enabled: (raw as { enabled: boolean }).enabled }
+      }
+    } catch { /* damaged */ }
+    return { kind: 'damaged' }
+  }
+  const store: SessionFilesSettingStore = {
+    read() {
+      const s = saved()
+      const value = s.kind === 'saved' ? s.enabled : null
+      // Only an off value forces anything; readSwitch with an ON fallback is false exactly for 0, false and off.
+      if (!readSwitch(env().COS_WEB_SESSION_FILES, true)) return { enabled: false, source: 'env', saved: value }
+      if (s.kind === 'saved') return { enabled: s.enabled, source: 'settings', saved: s.enabled }
+      if (s.kind === 'damaged') return { enabled: false, source: 'damaged', saved: null }
+      return { enabled: true, source: 'default', saved: null }
+    },
+    set(enabled) {
+      const file = deps.file()
+      securePrivateDirectory(dirname(file))
+      durableAtomicWriteFileSync(file, JSON.stringify({ schema: 1, enabled }) + '\n', { mode: 0o600 })
+      return store.read()
+    },
+  }
+  return store
+}
+
+/** The server's switch, in the data folder. */
+export const sessionFilesSetting = createSessionFilesSetting({ file: () => dataPath(SESSION_FILES_SETTINGS_FILE) })
+
+/** Turns with every image and file descriptor (tool-result and prompt images too) removed and `previewsOff` marked where there were any. Pure. */
+export function withoutPreviews(turns: SessionTurn[]): SessionTurn[] {
+  return turns.map(t => {
+    if (!t.outputImages?.length && !t.outputFiles?.length && !t.toolImages?.length && !t.toolImagesMore && !t.outputLinks?.length) return t
+    const { outputImages: _i, outputFiles: _f, toolImages: _t, toolImagesMore: _m, outputLinks: _l, ...rest } = t
+    // Preview engine phase 1: link cards ride this switch. Off, a card marker turns back into the link's words and the
+    // "N more linked files" sentence goes (QA 7.0.5), so not even a count reaches the browser. The Mac path was already
+    // gone from the text (session-links.ts).
+    return { ...rest, ...(_l?.length ? { text: withoutLinkCards(rest.text) } : {}), previewsOff: true as const }
+  })
+}