@gotcos/glasses-server 6.99.29 → 7.0.7

package/server/lib/agent-session-output-images.ts

@@ -12,7 +12,18 @@ import { realAttachedWorkspaceDeps, resolveAttachedWorkspace } from './attached-
 import { readComposerFacts } from './cursor-session-model.js'
 import { MAX_OUTPUT_ARTIFACT_BYTES } from './image-safety.js'
 import { getMediaStore, STAGED_TTL_MS, type MediaStore } from './media-store.js'
-import { readRecentSessionTurns, SESSION_TURNS_MAX, type SessionTurnProjection } from './agent-session-turns.js'
+import { previewFoldersSetting } from './preview-folders-setting.js'
+import { isDeniedSecretPath, SECRET_FILE_NOTICE } from './secret-path-guard.js'
+import { previewErrorCode } from './preview-error-code.js'
+import { readRecentSessionTurns, SESSION_TURNS_MAX, type SessionTurn, type SessionTurnProjection } from './agent-session-turns.js'
+import {
+  authorizedRoot, insideRoot, isLocalTarget, LINK_CARDS_PER_TURN, linkCardWords, linkLabel, linkTokens, previewKind, resolveLinkTarget, SESSION_OUTPUT_LINK_ID,
+  linkOverflowSentence, splitLineAnchor, type LinkRoots, type PreviewKind, type SessionOutputLink,
+} from './session-links.js'
+import {
+  decodeToolImage, estimateBytes, MAX_TOOL_IMAGE_BYTES, promptImages, SESSION_TOOL_IMAGE_ID, TOOL_IMAGES_PER_TURN, toolResultImages, toolUsesOf,
+  type FoundToolImage, type SessionToolImage, type ToolUseMeta,
+} from './agent-session-tool-images.js'
 
 export interface SessionOutputImage {
   id: string
@@ -21,19 +32,63 @@ export interface SessionOutputImage {
   /**
    * `outside_workspace`: permanent (the path leaves the workspace, or the workspace is a broad
    * root that is never eligible). `unavailable`: the workspace lookup failed this time; the
-   * content route re-resolves it, so a retry can succeed.
+   * content route re-resolves it, so a retry can succeed. `secret_file` (7.0.4): the file's name (or
+   * the name it canonically resolves to) says it may hold secrets; never served (403 secret_file_denied).
    */
-  reason?: 'outside_workspace' | 'unavailable'
+  reason?: 'outside_workspace' | 'unavailable' | 'missing' | 'secret_file'
+  /** 7.0.4: the words the card shows instead, set only with `secret_file`. */
+  notice?: string
 }
+/**
+ * A file a Claude session sent to the person with its SendUserFile tool (6.99.35), when it is not
+ * an image the preview pipeline normalizes. Only the base name travels; never a Mac path.
+ * `missing`: the path is inside the workspace but nothing is there now.
+ */
+export interface SessionOutputFile {
+  id: string
+  name: string
+  /** How the web may open it: `pdf` inline, `text` as words, `html` sandboxed or downloaded, `image` (GIF) as a picture, `file` downloaded. */
+  kind: SharedFileKind
+  /** A short type for people: "PDF", "HTML page", "Markdown", "Word document". */
+  type: string
+  size?: number
+  state: 'available' | 'unavailable'
+  reason?: 'outside_workspace' | 'unavailable' | 'missing' | 'secret_file'
+  /** 7.0.4: the words the card shows instead, set only with `secret_file`. */
+  notice?: string
+}
+export type SharedFileKind = 'pdf' | 'text' | 'html' | 'image' | 'file'
+export const SESSION_OUTPUT_FILE_ID = /^af_[a-f0-9]{64}$/
+/** Files one SendUserFile row may show (images and other files together). The rest are counted in words. */
+export const SHARED_FILES_PER_TURN = 10
+/** The largest sent file the web may fetch. Bigger files stay listed as "Too large to open here". */
+export const MAX_SHARED_FILE_BYTES = 32 * 1024 * 1024
 export const SESSION_OUTPUT_IMAGE_ID = /^ai_[a-f0-9]{64}$/
 export const OUTPUT_IMAGES_PER_TURN = 5
 export const OUTPUT_IMAGE_SCAN_CHARS = 128 * 1024
 export const OUTPUT_IMAGE_CACHE_MAX = 128
 export const OUTPUT_IMAGE_CONCURRENCY = 2
 const CACHE_TTL = Math.min(30 * 60_000, STAGED_TTL_MS)
+/** Sources kept per read: every preview the newest turns can name, a sent-files turn being the widest. */
+const SOURCES_MAX = (SESSION_TURNS_MAX + 1) * Math.max(OUTPUT_IMAGES_PER_TURN, SHARED_FILES_PER_TURN)
 interface Candidate { source: string; label: string }
 interface Source { candidate: Candidate; root: string | null; descriptor: SessionOutputImage }
-interface PreviewContext { project: SessionTurnProjection; sources: Map<string, Source> }
+interface FileSource { path: string | null; root: string | null; file: SessionOutputFile }
+/** A link card's authorized source (preview engine phase 1). Kept only for an available card. */
+interface LinkSource { path: string; root: string; link: SessionOutputLink }
+/** Where a tool-result image's bytes are. Embedded bytes are kept only for the one id a content request names. */
+type ToolSource = { kind: 'embedded'; mediaType: string; data: string } | { kind: 'path'; source: string; root: string; label: string }
+interface PreviewContext { project: SessionTurnProjection; sources: Map<string, Source>; files: Map<string, FileSource>; toolSources: Map<string, ToolSource>; links: Map<string, LinkSource>; workspace: string | null }
+/**
+ * PLAN 7 load: a reader with 20 cards asks for 20 thumbnails. The preview routes keep one projection of a transcript for
+ * 30 s while its size and mtime stand, so that is one transcript parse, not 20. Only ids, names and canonical sources are
+ * kept, and every content call still re-checks the file (containment, links, the deny list, identity) and the root.
+ */
+export const PREVIEW_PROJECTION_TTL_MS = 30_000
+const PREVIEW_PROJECTIONS_MAX = 8
+interface PreviewProjection { at: number; size: number; mtimeMs: number; read: Promise<{ context: PreviewContext; turns: SessionTurn[] }> }
+/** Tool calls remembered per read, so a result row can be labelled by the call that asked for it. */
+const TOOL_USES_MAX = 4096
 interface MediaCache { id: string; at: number }
 type PreviewStore = Pick<MediaStore, 'ingestOutputImage' | 'getContent'>
 export interface OutputImageDeps {
@@ -44,6 +99,8 @@ export interface OutputImageDeps {
   now(): number
   /** The home directory the broad-root denylist is built from (tests inject a scratch home). */
   home?(): string
+  /** Settings extra folders COS may preview from (lib/preview-folders-setting.ts), canonical. Read on every context. */
+  extraRoots?(): readonly string[]
 }
 
 function assistantText(provider: AgentProvider, row: Record<string, unknown>): string | null {
@@ -156,15 +213,126 @@ function canonicalRoot(path: string | null, home: string): string | 'broad' | nu
   } catch { return null }
 }
 function digest(value: string): string { return createHash('sha256').update(value).digest('hex') }
+/**
+ * 7.0.4 S2: whether a path a session named may hold secrets. Resolved against the workspace when there is one,
+ * otherwise judged by its own segments only (anchored at '/', never the server's directory). The guard checks the
+ * path as written AND its canonical file, so an innocently named link to a secret is refused too.
+ */
+function secretSource(root: string | null, written: string): boolean {
+  return isDeniedSecretPath(root !== null ? resolve(root, written) : resolve('/', written))
+}
+const SECRET = { state: 'unavailable' as const, reason: 'secret_file' as const, notice: SECRET_FILE_NOTICE }
+
+// ── Files a Claude session sent with SendUserFile (6.99.35) ──────────────────────────────
+// Its input is { files: [paths], caption?, status, display? }; paths are absolute or relative to the
+// session's working directory at that moment (the row's `cwd`). The row is evidence of what was
+// shared, not permission to read: a file is served only when its canonical path is inside the
+// session's exact workspace, as for images. Codex and Cursor transcripts have no such record.
+const NORMALIZED_IMAGE = /\.(png|jpe?g|webp|hei[cf]|avif)$/i
+const SHARED_KINDS: Array<[RegExp, SharedFileKind, string]> = [
+  [/\.pdf$/i, 'pdf', 'PDF'],
+  [/\.html?$/i, 'html', 'HTML page'],
+  [/\.(md|markdown)$/i, 'text', 'Markdown'],
+  [/\.csv$/i, 'text', 'CSV'],
+  [/\.tsv$/i, 'text', 'TSV'],
+  [/\.json$/i, 'text', 'JSON'],
+  [/\.ya?ml$/i, 'text', 'YAML'],
+  [/\.(txt|log)$/i, 'text', 'Text'],
+  // An SVG can carry script, so it is shown as its source, never as a picture from a same-origin URL.
+  [/\.svg$/i, 'text', 'SVG source'],
+  [/\.xml$/i, 'text', 'XML'],
+  [/\.gif$/i, 'image', 'GIF image'],
+  [/\.docx?$/i, 'file', 'Word document'],
+  [/\.xlsx?$/i, 'file', 'Excel workbook'],
+  [/\.pptx?$/i, 'file', 'PowerPoint deck'],
+  [/\.(wav|mp3|m4a|aac|flac)$/i, 'file', 'Audio'],
+  [/\.(mp4|mov|webm)$/i, 'file', 'Video'],
+  [/\.zip$/i, 'file', 'ZIP archive'],
+  [/\.ehpk$/i, 'file', 'EHPK package'],
+]
+export function sharedFileKind(name: string): { kind: SharedFileKind; type: string } {
+  for (const [re, kind, type] of SHARED_KINDS) if (re.test(name)) return { kind, type }
+  const ext = /\.([a-z0-9]{1,8})$/i.exec(name)
+  return { kind: 'file', type: ext ? ext[1].toUpperCase() + ' file' : 'File' }
+}
+/** The base name a person sees: no directories, no control characters, at most 120 characters. */
+function displayName(source: string): string {
+  const base = source.split(/[\\/]/).filter(Boolean).pop() || ''
+  const clean = base.replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  return (clean || 'File').slice(0, 120)
+}
+interface SentFiles { caption: string; files: string[] }
+/** The SendUserFile tool uses in one Claude assistant row, or null. Pure. */
+export function sentUserFiles(provider: AgentProvider, row: Record<string, unknown>): SentFiles | null {
+  if (provider !== 'claude' || row.type !== 'assistant') return null
+  // A sub-agent's share went to its parent, not to the person; an injected row is no one's.
+  if (row.isSidechain === true || row.isMeta === true || row.isCompactSummary === true) return null
+  const message = row.message as Record<string, unknown> | null
+  const content = message && typeof message === 'object' ? message.content : null
+  if (!Array.isArray(content)) return null
+  const files: string[] = [], captions: string[] = []
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue
+    const b = block as Record<string, unknown>
+    if (b.type !== 'tool_use' || b.name !== 'SendUserFile' || !b.input || typeof b.input !== 'object') continue
+    const input = b.input as Record<string, unknown>
+    // Preview engine phase 1: 11 of 1,112 real calls sent `files` as a JSON string ("[\"a.png\"]"). Parse it, then the same checks.
+    let list: unknown = input.files
+    if (typeof list === 'string' && list.length <= 64 * 1024) { try { list = JSON.parse(list) } catch { list = null } }
+    if (!Array.isArray(list)) continue
+    let any = false
+    for (const f of list) {
+      if (typeof f !== 'string' || !f || f.length > 4096 || /[\u0000-\u001f\u007f]/.test(f)) continue
+      files.push(f); any = true
+    }
+    if (any && typeof input.caption === 'string' && input.caption.trim()) captions.push(input.caption.trim().slice(0, 4000))
+  }
+  return files.length ? { caption: captions.join('\n\n'), files } : null
+}
+
+/** A Claude row's content has typed words (a text block that is not blank). */
+function hasWords(row: Record<string, unknown>): boolean {
+  const content = (row.message as Record<string, unknown> | null | undefined)?.content
+  if (typeof content === 'string') return content.trim().length > 0
+  return Array.isArray(content) && content.some(b => !!b && typeof b === 'object' && (b as Record<string, unknown>).type === 'text' && typeof (b as Record<string, unknown>).text === 'string' && ((b as Record<string, unknown>).text as string).trim().length > 0)
+}
 
 export class AgentSessionOutputImages {
   private cache = new Map<string, MediaCache>()
   private pending = new Map<string, Promise<string>>()
   private active = 0
   private readers = 0
+  private projections = new Map<string, PreviewProjection>()
+  /** Transcript parses the preview routes made (the load gate counts them). */
+  previewParses = 0
   constructor(private readonly deps: OutputImageDeps) {}
 
-  async context(provider: AgentProvider, sessionId: string, transcript: string): Promise<PreviewContext> {
+  /** The preview routes' projection of a transcript, reused for PREVIEW_PROJECTION_TTL_MS while the file is unchanged. */
+  private previewProjection(provider: AgentProvider, sessionId: string, transcript: string) {
+    const st = statSync(transcript)
+    const key = JSON.stringify([provider, sessionId, transcript])
+    const now = this.deps.now()
+    const hit = this.projections.get(key)
+    if (hit && now - hit.at < PREVIEW_PROJECTION_TTL_MS && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.read
+    this.previewParses++
+    const read = (async () => {
+      const context = await this.context(provider, sessionId, transcript)
+      const recent = await readRecentSessionTurns(provider, transcript, SESSION_TURNS_MAX, undefined, context.project)
+      return { context, turns: recent.turns }
+    })()
+    this.projections.delete(key)
+    this.projections.set(key, { at: now, size: st.size, mtimeMs: st.mtimeMs, read })
+    while (this.projections.size > PREVIEW_PROJECTIONS_MAX) this.projections.delete(this.projections.keys().next().value!)
+    // A failed parse is never reused.
+    read.catch(() => { if (this.projections.get(key)?.read === read) this.projections.delete(key) })
+    return read
+  }
+
+  /**
+   * `want`: the one tool-image id a content request is for. Only its embedded bytes are kept; a detail read
+   * (no `want`) keeps none, so a long session never holds 50 base64 images past the line that parsed them.
+   */
+  async context(provider: AgentProvider, sessionId: string, transcript: string, want?: string): Promise<PreviewContext> {
     let workspace: string | null = null
     try { workspace = await this.deps.workspace(provider, sessionId, transcript) } catch { /* unavailable, words still load */ }
     const canonical = canonicalRoot(workspace, this.deps.home?.() ?? homedir())
@@ -173,7 +341,19 @@ export class AgentSessionOutputImages {
     const lookupFailed = canonical === null
     const sources = new Map<string, Source>()
     const transcriptKey = digest(resolve(transcript))
-    const project: SessionTurnProjection = (p, row, turn) => {
+    const files = new Map<string, FileSource>()
+    const home = this.deps.home?.() ?? homedir()
+    let extraRoots: readonly string[] = []
+    try { extraRoots = this.deps.extraRoots?.() ?? [] } catch { extraRoots = [] }
+    const roots: LinkRoots = { workspace: root, extra: extraRoots, home }
+    const links = new Map<string, LinkSource>()
+    // A Codex rollout names its working folder in session_meta and each turn_context, not on the message rows.
+    let codexCwd: string | null = null
+    const markdown: SessionTurnProjection = (p, row, turn) => {
+      if (p === 'codex' && (row.type === 'turn_context' || row.type === 'session_meta')) {
+        const cwd = (row.payload as Record<string, unknown> | null)?.cwd
+        if (typeof cwd === 'string' && isAbsolute(cwd)) codexCwd = cwd
+      }
       const raw = assistantText(p, row)
       if (!raw) return turn
       // Prose cleanup can collapse a huge whitespace/code prefix, bringing an unscanned
@@ -182,36 +362,333 @@ export class AgentSessionOutputImages {
       const shortened = raw.length > OUTPUT_IMAGE_SCAN_CHARS
       const scanned = shortened ? raw.slice(0, raw.lastIndexOf('\n', OUTPUT_IMAGE_SCAN_CHARS - 1) + 1) : raw
       const candidates = imageTokens(scanned)
-      if (!candidates.length && !shortened) return turn
+      // Link cards: local links only, never one inside an image token.
+      const linked = linkTokens(scanned).filter(l => isLocalTarget(l.target) && !candidates.some(c => l.start < c.end && c.start < l.end))
+      if (!candidates.length && !linked.length && !shortened) return turn
       const recordKey = digest(JSON.stringify(row))
       const refs = candidates.slice(0, OUTPUT_IMAGES_PER_TURN).map((c, ordinal) => {
         const id = 'ai_' + createHmac('sha256', this.deps.secret).update(JSON.stringify([provider, sessionId, transcriptKey, recordKey, ordinal, c.source])).digest('hex')
-        const allowed = root !== null && inside(root, resolve(root, c.source))
-        const descriptor: SessionOutputImage = { id, label: c.label, state: allowed ? 'available' : 'unavailable', ...(!allowed ? { reason: lookupFailed ? 'unavailable' as const : 'outside_workspace' as const } : {}) }
+        // 7.0.4 S2: a secret by name is refused before containment, and its card carries the base name only.
+        const descriptor: SessionOutputImage = secretSource(root, c.source)
+          ? { id, label: displayName(c.source), ...SECRET }
+          : root !== null && inside(root, resolve(root, c.source))
+            ? { id, label: c.label, state: 'available' }
+            : { id, label: c.label, state: 'unavailable', reason: lookupFailed ? 'unavailable' : 'outside_workspace' }
         sources.delete(id); sources.set(id, { candidate: c, root, descriptor })
-        while (sources.size > (SESSION_TURNS_MAX + 1) * OUTPUT_IMAGES_PER_TURN) sources.delete(sources.keys().next().value!)
+        while (sources.size > SOURCES_MAX) sources.delete(sources.keys().next().value!)
         return descriptor
       })
       // Never turn an explicit local image into a browser-visible Mac path. Existing callers
       // without this opt-in projection retain their original text and contract.
       // The preview cap limits DTOs, not redaction: the sixth image is still private.
+      // Link cards (preview engine phase 1): each local link becomes `[words](cos-file:N)`, N its card. The Mac path
+      // never stays in the text, with previews on or off, past the card cap or not. The same target twice is one card.
+      const rowCwd = p === 'claude' ? (typeof row.cwd === 'string' && isAbsolute(row.cwd) ? row.cwd : null) : p === 'codex' ? codexCwd : null
+      const linkRefs: SessionOutputLink[] = [], byTarget = new Map<string, number>()
+      let linkExtra = 0
+      const linkWords = (token: { label: string; target: string }): string => {
+        let n = byTarget.get(token.target)
+        if (n === undefined) {
+          const resolved = resolveLinkTarget(token.target, [rowCwd, root], roots)
+          if (linkRefs.length >= LINK_CARDS_PER_TURN) { linkExtra++; return linkCardWords(token.label, resolved.name, token.target) }
+          n = linkRefs.length; byTarget.set(token.target, n)
+          linkRefs.push(this.describeLink(provider, sessionId, transcriptKey, recordKey, n, token, resolved, lookupFailed, links))
+        }
+        // Each link keeps its own words; the same target twice shares one card.
+        return '[' + linkCardWords(token.label, linkRefs[n].name, token.target) + '](cos-file:' + n + ')'
+      }
+      const edits = [
+        ...candidates.map(c => ({ start: c.start, end: c.end, words: () => '[Output image]' })),
+        ...linked.map(l => ({ start: l.start, end: l.end, words: () => linkWords(l) })),
+      ].sort((a, b) => a.start - b.start)
       const parts: string[] = []; let end = 0
-      for (const token of candidates) { parts.push(scanned.slice(end, token.start), '[Output image]'); end = token.end }
+      for (const edit of edits) { parts.push(scanned.slice(end, edit.start), edit.words()); end = edit.end }
       parts.push(scanned.slice(end))
+      if (linkExtra > 0) parts.push('\n\n' + linkOverflowSentence(linkExtra))
       const omission = '[Reply shortened at the image preview scan limit.]'
-      const text = shortened
+      let text = shortened
         ? [latestAssistantReply(parts.join(''), LATEST_REPLY_MAX - omission.length - 1), omission].filter(Boolean).join('\n')
         : latestAssistantReply(parts.join(''))
+      // The reply cap can cut a card marker in half; keep its words, never a broken marker.
+      text = text.replace(/\[([^\]\n]*)\]\(cos-[^)\s]*…/g, '$1…')
       const at = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined
-      return { ...(turn ?? { role: 'assistant' as const, text: '', ...(at ? { at } : {}) }), text, outputImages: refs }
+      return {
+        ...(turn ?? { role: 'assistant' as const, text: '', ...(at ? { at } : {}) }), text,
+        ...(candidates.length || shortened ? { outputImages: refs } : {}),
+        ...(linkRefs.length ? { outputLinks: linkRefs } : {}),
+      }
+    }
+    const project: SessionTurnProjection = (p, row, turn) => {
+      const shaped = markdown(p, row, turn)
+      const sent = sentUserFiles(p, row)
+      if (!sent) return shaped
+      const recordKey = digest(JSON.stringify(row))
+      // Relative paths are relative to where the session stood when it sent them, as the tool reads them.
+      const cwd = typeof row.cwd === 'string' && isAbsolute(row.cwd) ? row.cwd : root
+      const images: SessionOutputImage[] = [], out: SessionOutputFile[] = []
+      sent.files.slice(0, SHARED_FILES_PER_TURN).forEach((written, ordinal) => {
+        const name = displayName(written)
+        // Never a URL, a network path or a home shorthand: only a local path is ever opened.
+        const remote = /^[a-z][a-z0-9+.-]*:/i.test(written) || written.startsWith('//') || written.startsWith('~')
+        const lexical = remote || !cwd ? null : resolve(cwd, written)
+        let canonical: string | null = null
+        // Preview engine phase 1: a Settings extra folder is an allowed root too (Miles decision 2). Nothing else is.
+        if (lexical && (root !== null || extraRoots.length)) { try { canonical = realpathSync(lexical) } catch { canonical = null } }
+        const allowRoot = canonical !== null ? authorizedRoot(canonical, roots) : null
+        const outside = root === null && lookupFailed ? 'unavailable' as const : 'outside_workspace' as const
+        let reason: SessionOutputFile['reason'] | undefined
+        let size: number | undefined
+        // 7.0.4 S2: refused by name (as written or as it canonically resolves) before anything else is asked.
+        if (secretSource(cwd, written)) reason = 'secret_file'
+        // Preview engine phase 1: with no workspace, a Settings extra folder can still authorize the file.
+        else if (root === null && !extraRoots.length) reason = lookupFailed ? 'unavailable' : 'outside_workspace'
+        else if (!lexical) reason = 'outside_workspace'
+        // The canonical file decides: a link that leaves the workspace is outside it.
+        else if (canonical !== null && !allowRoot) reason = outside
+        else if (canonical === null) reason = authorizedRoot(lexical, roots) ? 'missing' : outside
+        else {
+          try {
+            const st = statSync(canonical)
+            if (!st.isFile()) reason = 'missing'
+            // 7.0.4 QA: a hard link is the same file under another name, and realpath cannot see it. A sent file can be
+            // any text, so one with more than one link is refused as a secret. Images go through the JPEG normaliser.
+            else if (st.nlink > 1 && !NORMALIZED_IMAGE.test(name)) reason = 'secret_file'
+            else size = st.size
+          } catch { reason = 'missing' }
+        }
+        const allowed = reason === undefined
+        if (NORMALIZED_IMAGE.test(name)) {
+          const id = 'ai_' + createHmac('sha256', this.deps.secret).update(JSON.stringify([provider, sessionId, transcriptKey, recordKey, 'sent', ordinal, written])).digest('hex')
+          const descriptor: SessionOutputImage = reason === 'secret_file' ? { id, label: name, ...SECRET } : { id, label: name, state: allowed ? 'available' : 'unavailable', ...(reason ? { reason } : {}) }
+          // The canonical path is the source, so the content route's no-symlink check holds for it.
+          sources.delete(id); sources.set(id, { candidate: { source: allowed ? canonical! : written, label: name }, root: allowRoot ?? root, descriptor })
+          while (sources.size > SOURCES_MAX) sources.delete(sources.keys().next().value!)
+          images.push(descriptor)
+          return
+        }
+        const id = 'af_' + createHmac('sha256', this.deps.secret).update(JSON.stringify([provider, sessionId, transcriptKey, recordKey, 'file', ordinal, written])).digest('hex')
+        const { kind, type } = sharedFileKind(name)
+        const file: SessionOutputFile = reason === 'secret_file' ? { id, name, kind, type, ...SECRET } : { id, name, kind, type, ...(size !== undefined ? { size } : {}), state: allowed ? 'available' : 'unavailable', ...(reason ? { reason } : {}) }
+        files.delete(id); files.set(id, { path: allowed ? canonical : null, root: allowRoot ?? root, file })
+        while (files.size > SOURCES_MAX) files.delete(files.keys().next().value!)
+        out.push(file)
+      })
+      // The caption is the session's own words; an inline image in it is never a way to show a path.
+      const tokens = imageTokens(sent.caption)
+      let caption = '', end = 0
+      for (const token of tokens) { caption += sent.caption.slice(end, token.start) + '[Output image]'; end = token.end }
+      caption += sent.caption.slice(end)
+      const extra = sent.files.length - SHARED_FILES_PER_TURN
+      const words = [caption && latestAssistantReply(caption), extra > 0 ? extra + (extra === 1 ? ' more file was sent and is not listed here.' : ' more files were sent and are not listed here.') : ''].filter(Boolean).join('\n\n')
+      const at = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined
+      const base = shaped ?? { role: 'assistant' as const, text: '', ...(at ? { at } : {}) }
+      return {
+        ...base,
+        text: [base.text, words].filter(Boolean).join('\n\n'),
+        ...(images.length || base.outputImages?.length ? { outputImages: [...(base.outputImages ?? []), ...images] } : {}),
+        ...(out.length ? { outputFiles: out } : {}),
+      }
+    }
+    // ── Images the session looked at: tool results, and images attached to prompts ──
+    // The reader shows messages, not tool calls, so a step's images ride on the assistant turn the step followed
+    // (the words before it, as the Claude app shows the step under them). A step that came before any words in this
+    // window waits for the next assistant turn and is marked `before`. A user turn ends a step that never got words.
+    const toolSources = new Map<string, ToolSource>()
+    const uses = new Map<string, ToolUseMeta>()
+    let groups = new WeakMap<SessionTurn, { before: number; after: number }>()
+    let last: SessionTurn | null = null
+    let pending: SessionToolImage[] = [], pendingExtra = 0
+    const recordKeyOf = (row: Record<string, unknown>) => typeof row.uuid === 'string' && row.uuid ? 'u:' + row.uuid : digest(JSON.stringify(row))
+    const describe = (recordKey: string, scope: 'tool' | 'prompt', ordinal: number, found: FoundToolImage): SessionToolImage => {
+      const id = 'ti_' + createHmac('sha256', this.deps.secret).update(JSON.stringify([provider, sessionId, transcriptKey, recordKey, scope, ordinal])).digest('hex')
+      const ref = found.ref
+      let reason: SessionToolImage['reason'] | undefined
+      if (ref.kind === 'embedded') {
+        // 7.0.4 QA: a Read's embedded bytes are judged by the file it read; bytes with no path (a screenshot, a prompt
+        // attachment) have no name to judge.
+        if (ref.path && secretSource(root, ref.path)) reason = 'secret_file'
+        else if (estimateBytes(ref.data) > MAX_TOOL_IMAGE_BYTES) reason = 'too_large'
+        else if (id === want) toolSources.set(id, { kind: 'embedded', mediaType: ref.mediaType, data: ref.data })
+      } else if (ref.kind === 'path') {
+        // A Read that names a path and carries no bytes: the output-image rule, the session's exact workspace only.
+        // 7.0.4 S2: a secret by name is refused first (embedded bytes from a Read are judged by the same name above).
+        let canonical: string | null = null
+        if (secretSource(root, ref.path)) reason = 'secret_file'
+        else if (root === null) reason = lookupFailed ? 'unavailable' : 'outside_workspace'
+        else if (!inside(root, resolve(root, ref.path))) reason = 'outside_workspace'
+        else {
+          // The canonical file decides, as for sent files: a link that leaves the workspace is outside it. Resolved
+          // once: a second realpath could throw if the file went away in between (7.0.4 QA), which lost the history.
+          try { canonical = realpathSync(resolve(root, ref.path)) } catch { canonical = null }
+          if (canonical === null) reason = 'missing'
+          else if (!inside(root, canonical)) reason = 'outside_workspace'
+        }
+        if (root !== null && !reason && canonical !== null) {
+          // The canonical path is the source, as for sent images, so the content read's no-link check holds for it.
+          toolSources.delete(id); toolSources.set(id, { kind: 'path', source: canonical, root, label: found.tool })
+          while (toolSources.size > SOURCES_MAX) toolSources.delete(toolSources.keys().next().value!)
+        }
+      } else reason = 'missing'
+      return { id, tool: found.tool, index: 0, total: 0, state: reason ? 'unavailable' : 'available', ...(reason ? { reason } : {}), ...(reason === 'secret_file' ? { notice: SECRET_FILE_NOTICE } : {}) }
+    }
+    // The turn is already in the reader's list, so it is extended in place. Past the cap an image is counted, never listed.
+    const attach = (turn: SessionTurn, images: SessionToolImage[], extra: number, before: boolean) => {
+      const g = groups.get(turn) ?? { before: 0, after: 0 }; groups.set(turn, g)
+      const key = before ? 'before' : 'after'
+      const list = turn.toolImages ?? []
+      for (const d of images) {
+        g[key]++
+        if (list.length < TOOL_IMAGES_PER_TURN) list.push({ ...d, index: g[key], ...(before ? { before: true as const } : {}) })
+        else turn.toolImagesMore = (turn.toolImagesMore ?? 0) + 1
+      }
+      if (extra > 0) { g[key] += extra; turn.toolImagesMore = (turn.toolImagesMore ?? 0) + extra }
+      for (const d of list) if ((d.before === true) === before) d.total = g[key]
+      if (list.length) turn.toolImages = list
     }
-    return { project, sources }
+    const withTools: SessionTurnProjection = (p, row, turn) => {
+      for (const [id, meta] of toolUsesOf(p, row)) {
+        uses.delete(id); uses.set(id, meta)
+        while (uses.size > TOOL_USES_MAX) uses.delete(uses.keys().next().value!)
+      }
+      let result = project(p, row, turn)
+      const found = toolResultImages(p, row, uses)
+      if (found.length) {
+        const key = recordKeyOf(row)
+        const described = found.map((f, i) => describe(key, 'tool', i, f))
+        if (last && last.role === 'assistant') attach(last, described, 0, false)
+        else for (const d of described) { if (pending.length < TOOL_IMAGES_PER_TURN) pending.push(d); else pendingExtra++ }
+      }
+      const attached = promptImages(p, row)
+      if (attached.length) {
+        // A Claude prompt that is only an image (sent through the SDK) is still something the person said.
+        if (!result && p === 'claude' && !hasWords(row)) {
+          const at = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined
+          result = { role: 'user', text: attached.length === 1 ? '[Image]' : `[${attached.length} images]`, ...(at ? { at } : {}) }
+        }
+        if (result && result.role === 'user') {
+          const key = recordKeyOf(row)
+          attach(result, attached.map((ref, i) => describe(key, 'prompt', i, { tool: 'Attached', ref })), 0, false)
+        }
+      }
+      if (result) {
+        if (result.role === 'assistant' && (pending.length || pendingExtra)) attach(result, pending, pendingExtra, true)
+        pending = []; pendingExtra = 0
+        last = result
+      }
+      return result
+    }
+    withTools.reset = () => {
+      // readRecentSessionTurns may grow from 2 to 8 to 24 MiB. Each pass must project
+      // only its own records, not attach early images to a turn discarded with the smaller window.
+      sources.clear(); files.clear(); toolSources.clear(); uses.clear(); links.clear()
+      codexCwd = null
+      groups = new WeakMap()
+      last = null; pending = []; pendingExtra = 0
+    }
+    return { project: withTools, sources, files, toolSources, links, workspace: root }
+  }
+
+  /** One link card's descriptor; an available card's canonical source is remembered for the preview route. */
+  private describeLink(provider: AgentProvider, sessionId: string, transcriptKey: string, recordKey: string, ordinal: number,
+    token: { label: string; target: string }, resolved: ReturnType<typeof resolveLinkTarget>, lookupFailed: boolean, links: Map<string, LinkSource>): SessionOutputLink {
+    const id = 'al_' + createHmac('sha256', this.deps.secret).update(JSON.stringify([provider, sessionId, transcriptKey, recordKey, 'link', ordinal, token.target])).digest('hex')
+    const { line } = splitLineAnchor(token.target)
+    const name = resolved.name
+    const typed = resolved.state === 'available' && resolved.isDir ? { kind: 'folder' as PreviewKind, type: 'Folder' } : previewKind(name)
+    const link: SessionOutputLink = {
+      id, label: linkLabel(token.label, name), name, kind: typed.kind, type: typed.type,
+      ...(resolved.state === 'available' && resolved.size !== undefined ? { size: resolved.size } : {}),
+      ...(line ? { line } : {}),
+      state: resolved.state,
+      ...(resolved.state === 'unavailable' ? { reason: resolved.reason === 'outside_workspace' && lookupFailed ? 'unavailable' as const : resolved.reason } : {}),
+      ...(resolved.state === 'unavailable' && resolved.reason === 'secret_file' ? { notice: SECRET_FILE_NOTICE } : {}),
+    }
+    if (resolved.state === 'available') {
+      links.delete(id); links.set(id, { path: resolved.path, root: resolved.root, link })
+      while (links.size > SOURCES_MAX) links.delete(links.keys().next().value!)
+    }
+    return link
+  }
+
+  /**
+   * A link card (`al_`) or a sent file (`af_`), re-authorized for the preview route: the id must name a card or file in
+   * the session's newest turns, its canonical path must still be inside the root it was authorized under (the workspace
+   * or a Settings extra folder, read fresh), never a denied secret name, no component a link, and the same file before
+   * and after the read. `peek` reads no bytes (the meta part and image parts).
+   */
+  async previewFile(provider: AgentProvider, sessionId: string, id: string, peek = false): Promise<
+    | { status: 'ok'; bytes: Buffer; name: string; kind: PreviewKind; type: string; line?: number; identity: { dev: number; ino: number; size: number; mtimeMs: number; ctimeMs: number }; path: string; root: string; descriptor: SessionOutputLink | SessionOutputFile }
+    | { status: 'not_found' | 'unavailable' | 'too_large' | 'secret' | 'folder' | 'busy'; reason?: string }> {
+    const isLink = SESSION_OUTPUT_LINK_ID.test(id)
+    if (!isLink && !SESSION_OUTPUT_FILE_ID.test(id)) return { status: 'not_found' }
+    // 7.0.4 QA: at the limit the answer is "busy" (503 previews_busy, retried by the web), never "unavailable".
+    if (this.readers >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'busy' }
+    this.readers++
+    try {
+      const transcript = await this.deps.findSession(provider, sessionId)
+      if (!transcript) return { status: 'not_found' }
+      const { context, turns } = await this.previewProjection(provider, sessionId, transcript)
+      const descriptor = isLink
+        ? turns.flatMap(t => t.outputLinks ?? []).find(l => l.id === id)
+        : turns.flatMap(t => t.outputFiles ?? []).find(f => f.id === id)
+      if (!descriptor) return { status: 'not_found' }
+      // 7.0.4 S2: an id that names a secret answers 403 secret_file_denied, never bytes.
+      if (descriptor.reason === 'secret_file') return { status: 'secret' }
+      let path: string | null = null, root: string | null = null
+      if (isLink) { const s = context.links.get(id); path = s?.path ?? null; root = s?.root ?? null }
+      else { const s = context.files.get(id); path = s?.path ?? null; root = s?.root ?? null }
+      if (descriptor.state !== 'available' || !path || !root) return { status: 'unavailable' }
+      // The root must still be allowed NOW: a Settings extra folder removed since the projection no longer counts.
+      if (root !== context.workspace) {
+        let extra: readonly string[] = []
+        try { extra = this.deps.extraRoots?.() ?? [] } catch { extra = [] }
+        if (!extra.includes(root)) return { status: 'unavailable' }
+      }
+      // The shared deny list, before any byte is read (and for a file sent before the list existed).
+      if (isDeniedSecretPath(path)) return { status: 'secret' }
+      if ((descriptor as SessionOutputLink).kind === 'folder') return { status: 'folder' }
+      if (!insideRoot(root, path) || realpathSync(path) !== path) return { status: 'unavailable' }
+      const { kind, type } = previewKind(descriptor.name)
+      const line = isLink ? (descriptor as SessionOutputLink).line : undefined
+      const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+      try {
+        const before = await file.stat()
+        if (!before.isFile()) return { status: 'unavailable' }
+        // 7.0.4 QA (the sent-file rule, for link cards too): a file with another hard link may be a secret under an
+        // innocent name, which realpath cannot see. Pictures go through the JPEG normaliser and are exempt.
+        if (before.nlink > 1 && !NORMALIZED_IMAGE.test(descriptor.name)) return { status: 'secret' }
+        if (before.size > MAX_SHARED_FILE_BYTES) return { status: 'too_large' }
+        const identity = { dev: before.dev, ino: before.ino, size: before.size, mtimeMs: before.mtimeMs, ctimeMs: before.ctimeMs }
+        const base = { status: 'ok' as const, name: descriptor.name, kind, type, ...(line ? { line } : {}), identity, path, root, descriptor }
+        if (peek) return { ...base, bytes: Buffer.alloc(0) }
+        const bytes = Buffer.alloc(before.size)
+        let offset = 0
+        while (offset < bytes.length) { const got = await file.read(bytes, offset, bytes.length - offset, offset); if (!got.bytesRead) break; offset += got.bytesRead }
+        const after = await file.stat(), current = statSync(path)
+        if (offset !== bytes.length || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs
+          || current.dev !== before.dev || current.ino !== before.ino || realpathSync(path) !== path) return { status: 'unavailable' }
+        return { ...base, bytes }
+      } finally { await file.close() }
+    } catch (error) {
+      // QA 7.0.5: the route logs this once, as reason=error_<code> (never the message, which carries the path).
+      return { status: 'unavailable', reason: 'error_' + previewErrorCode(error) }
+    }
+    finally { this.readers-- }
+  }
+
+  /** A link card or sent file that is a picture, through the same normalizer as output images (a JPEG). */
+  async previewImage(provider: AgentProvider, sessionId: string, id: string, variant: 'thumb' | 'phone') {
+    const found = await this.previewFile(provider, sessionId, id, true)
+    if (found.status !== 'ok') return found
+    if (found.kind !== 'image') return { status: 'unavailable' as const }
+    try { return await this.workspaceImage(id, found.root, found.path, found.name, variant) } catch (error) { return { status: 'unavailable' as const, reason: 'error_' + previewErrorCode(error) } }
   }
 
   async content(provider: AgentProvider, sessionId: string, imageId: string, variant: 'thumb' | 'phone') {
     if (!SESSION_OUTPUT_IMAGE_ID.test(imageId)) return { status: 'not_found' as const }
-    // Admission covers discovery, transcript parsing, authorization and image IO alike.
-    if (this.readers >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'unavailable' as const }
+    // Admission covers discovery, transcript parsing, authorization and image IO alike. Full is `busy` (7.0.4 QA): the
+    // Mac is working on other previews, which is not the same as unreachable.
+    if (this.readers >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'busy' as const }
     this.readers++
     try {
       const transcript = await this.deps.findSession(provider, sessionId)
@@ -220,51 +697,151 @@ export class AgentSessionOutputImages {
       const recent = await readRecentSessionTurns(provider, transcript, SESSION_TURNS_MAX, undefined, context.project)
       if (!recent.turns.some(t => t.outputImages?.some(i => i.id === imageId))) return { status: 'not_found' as const }
       const source = context.sources.get(imageId)
+      // 7.0.4 S2: after the id is authorized from the transcript, a secret by name answers 403, never bytes.
+      if (source?.descriptor.reason === 'secret_file') return { status: 'secret' as const }
       if (!source?.root || source.descriptor.state !== 'available') return { status: 'unavailable' as const }
-      const path = resolve(source.root, source.candidate.source)
-      const canonical = realpathSync(path)
-      if (!inside(source.root, canonical)) return { status: 'unavailable' as const }
-      // Reject symlinks in any component and recheck path/fd identity after reading.
-      // A changed path never becomes a published preview.
-      if (canonical !== path) return { status: 'unavailable' as const }
+      return await this.workspaceImage(imageId, source.root, source.candidate.source, source.candidate.label, variant)
+    } catch (error) { logPreviewFailure('output_image', error); return { status: 'unavailable' as const } }
+    finally { this.readers-- }
+  }
+
+  /**
+   * A tool-result or prompt image (`ti_` id), re-authorized from the transcript: the id must name an image in the
+   * session's newest turns. Embedded bytes are decoded here and typed by what they are; a path-only Read goes
+   * through the same workspace read and normalizer as an output image.
+   */
+  async toolImageContent(provider: AgentProvider, sessionId: string, imageId: string): Promise<
+    { status: 'ok'; bytes: Buffer; type: string } | { status: 'ok'; path: string; mime: string; bytes: number } | { status: 'not_found' | 'unavailable' | 'too_large' | 'secret' | 'busy' }> {
+    if (!SESSION_TOOL_IMAGE_ID.test(imageId)) return { status: 'not_found' }
+    if (this.readers >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'busy' }
+    this.readers++
+    try {
+      const transcript = await this.deps.findSession(provider, sessionId)
+      if (!transcript) return { status: 'not_found' }
+      const context = await this.context(provider, sessionId, transcript, imageId)
+      const recent = await readRecentSessionTurns(provider, transcript, SESSION_TURNS_MAX, undefined, context.project)
+      const descriptor = recent.turns.flatMap(t => t.toolImages ?? []).find(i => i.id === imageId)
+      if (!descriptor) return { status: 'not_found' }
+      if (descriptor.reason === 'too_large') return { status: 'too_large' }
+      if (descriptor.reason === 'secret_file') return { status: 'secret' }
+      const source = context.toolSources.get(imageId)
+      if (descriptor.state !== 'available' || !source) return { status: 'unavailable' }
+      if (source.kind === 'embedded') return decodeToolImage(source)
+      const normalized = await this.workspaceImage(imageId, source.root, source.source, source.label, 'phone')
+      return normalized.status === 'ok' ? normalized : normalized.status === 'busy' ? { status: 'busy' } : { status: 'unavailable' }
+    } catch (error) { logPreviewFailure('tool_image', error); return { status: 'unavailable' } }
+    finally { this.readers-- }
+  }
+
+  /** The workspace read every path-based preview shares: exact containment, no links, the same file before and after. */
+  private async workspaceImage(imageId: string, root: string, written: string, label: string, variant: 'thumb' | 'phone') {
+    const source = { root, candidate: { source: written, label } }
+    const path = resolve(source.root, source.candidate.source)
+    const canonical = realpathSync(path)
+    if (!inside(source.root, canonical)) return { status: 'unavailable' as const }
+    // Reject symlinks in any component and recheck path/fd identity after reading.
+    // A changed path never becomes a published preview.
+    if (canonical !== path) return { status: 'unavailable' as const }
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    let bytes: Buffer, key: string
+    try {
+      const before = await file.stat()
+      if (!before.isFile() || before.size <= 0 || before.size > MAX_OUTPUT_ARTIFACT_BYTES) return { status: 'unavailable' as const }
+      key = digest(JSON.stringify([imageId, before.dev, before.ino, before.size, before.mtimeMs, before.ctimeMs]))
+      // Even a cache hit rechecks that the authorized source still exists within the root.
+      const hit = this.cache.get(key)
+      if (hit && this.deps.now() - hit.at < CACHE_TTL) {
+        const current = statSync(path)
+        if (realpathSync(path) !== canonical || current.dev !== before.dev || current.ino !== before.ino) return { status: 'unavailable' as const }
+        const content = this.deps.store().getContent(hit.id, variant)
+        if (content.status === 'ok') return content
+      }
+      // Bounded positional read, not readFile(): an append during read cannot allocate past the cap.
+      bytes = Buffer.alloc(before.size)
+      let offset = 0
+      while (offset < bytes.length) { const got = await file.read(bytes, offset, bytes.length - offset, offset); if (!got.bytesRead) break; offset += got.bytesRead }
+      const after = await file.stat(), current = statSync(path)
+      if (offset !== bytes.length || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || current.dev !== before.dev || current.ino !== before.ino || realpathSync(path) !== canonical) return { status: 'unavailable' as const }
+    } finally { await file.close() }
+    let job = this.pending.get(key!)
+    if (!job) {
+      if (this.active >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'busy' as const }
+      this.active++
+      job = this.deps.store().ingestOutputImage({ bytes: bytes!, kind: 'generated_visual', label: source.candidate.label }).then(ref => {
+        this.cache.set(key!, { id: ref.id, at: this.deps.now() })
+        while (this.cache.size > OUTPUT_IMAGE_CACHE_MAX) this.cache.delete(this.cache.keys().next().value!)
+        return ref.id
+      }).finally(() => { this.active--; this.pending.delete(key!) })
+      this.pending.set(key!, job)
+    }
+    return this.deps.store().getContent(await job, variant)
+  }
+
+  /**
+   * The bytes of a file a session sent (6.99.35), re-authorized like an image: the id must name a
+   * file in the session's newest turns, its canonical path must still be inside the exact workspace,
+   * no component may be a link, and the file must be the same one before and after the read.
+   */
+  async fileContent(provider: AgentProvider, sessionId: string, fileId: string): Promise<
+    { status: 'ok'; bytes: Buffer; name: string; kind: SharedFileKind } | { status: 'not_found' | 'unavailable' | 'too_large' | 'secret' | 'busy' }> {
+    if (!SESSION_OUTPUT_FILE_ID.test(fileId)) return { status: 'not_found' }
+    if (this.readers >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'busy' }
+    this.readers++
+    try {
+      const transcript = await this.deps.findSession(provider, sessionId)
+      if (!transcript) return { status: 'not_found' }
+      const context = await this.context(provider, sessionId, transcript)
+      const recent = await readRecentSessionTurns(provider, transcript, SESSION_TURNS_MAX, undefined, context.project)
+      if (!recent.turns.some(t => t.outputFiles?.some(f => f.id === fileId))) return { status: 'not_found' }
+      const source = context.files.get(fileId)
+      if (source?.file.reason === 'secret_file') return { status: 'secret' }
+      if (!source?.root || !source.path || source.file.state !== 'available') return { status: 'unavailable' }
+      const path = source.path
+      if (!inside(source.root, path) || realpathSync(path) !== path) return { status: 'unavailable' }
       const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
-      let bytes: Buffer, key: string
       try {
         const before = await file.stat()
-        if (!before.isFile() || before.size <= 0 || before.size > MAX_OUTPUT_ARTIFACT_BYTES) return { status: 'unavailable' as const }
-        key = digest(JSON.stringify([imageId, before.dev, before.ino, before.size, before.mtimeMs, before.ctimeMs]))
-        // Even a cache hit rechecks that the authorized source still exists within the root.
-        const hit = this.cache.get(key)
-        if (hit && this.deps.now() - hit.at < CACHE_TTL) {
-          const current = statSync(path)
-          if (realpathSync(path) !== canonical || current.dev !== before.dev || current.ino !== before.ino) return { status: 'unavailable' as const }
-          const content = this.deps.store().getContent(hit.id, variant)
-          if (content.status === 'ok') return content
-        }
-        // Bounded positional read, not readFile(): an append during read cannot allocate past the cap.
-        bytes = Buffer.alloc(before.size)
+        if (!before.isFile()) return { status: 'unavailable' }
+        // 7.0.4 QA: the hard-link rule again on the open file, so a link made after the listing is refused too.
+        if (before.nlink > 1) return { status: 'secret' }
+        if (before.size > MAX_SHARED_FILE_BYTES) return { status: 'too_large' }
+        const bytes = Buffer.alloc(before.size)
         let offset = 0
         while (offset < bytes.length) { const got = await file.read(bytes, offset, bytes.length - offset, offset); if (!got.bytesRead) break; offset += got.bytesRead }
         const after = await file.stat(), current = statSync(path)
-        if (offset !== bytes.length || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || current.dev !== before.dev || current.ino !== before.ino || realpathSync(path) !== canonical) return { status: 'unavailable' as const }
+        if (offset !== bytes.length || after.size !== before.size || after.mtimeMs !== before.mtimeMs || current.dev !== before.dev || current.ino !== before.ino || realpathSync(path) !== path) return { status: 'unavailable' }
+        return { status: 'ok', bytes, name: source.file.name, kind: source.file.kind }
       } finally { await file.close() }
-      let job = this.pending.get(key!)
-      if (!job) {
-        if (this.active >= OUTPUT_IMAGE_CONCURRENCY) return { status: 'unavailable' as const }
-        this.active++
-        job = this.deps.store().ingestOutputImage({ bytes: bytes!, kind: 'generated_visual', label: source.candidate.label }).then(ref => {
-          this.cache.set(key!, { id: ref.id, at: this.deps.now() })
-          while (this.cache.size > OUTPUT_IMAGE_CACHE_MAX) this.cache.delete(this.cache.keys().next().value!)
-          return ref.id
-        }).finally(() => { this.active--; this.pending.delete(key!) })
-        this.pending.set(key!, job)
-      }
-      return this.deps.store().getContent(await job, variant)
-    } catch { return { status: 'unavailable' as const } }
+    } catch (error) { logPreviewFailure('sent_file', error); return { status: 'unavailable' } }
     finally { this.readers-- }
   }
 }
 
+/** 7.0.4 QA: a preview read that failed is logged with its kind and error code only (lib/preview-error-code.ts). */
+function logPreviewFailure(kind: 'output_image' | 'tool_image' | 'sent_file', error: unknown): void {
+  console.warn(`[agent-session-previews] ${kind} read failed error=${previewErrorCode(error)}`)
+}
+
+/** Content-Type, Content-Disposition and CSP for a sent file. HTML is never served as HTML. */
+export function sharedFileHeaders(name: string, kind: SharedFileKind): Record<string, string> {
+  const ascii = name.replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[ .]+/, '') || 'file'
+  const inline = kind === 'pdf'
+  const type = kind === 'pdf' ? 'application/pdf'
+    : kind === 'text' ? 'text/plain; charset=utf-8'
+    : kind === 'image' && /\.gif$/i.test(name) ? 'image/gif'
+    : 'application/octet-stream'
+  const headers: Record<string, string> = {
+    'Content-Type': type,
+    'Content-Disposition': `${inline ? 'inline' : 'attachment'}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`,
+    'X-Content-Type-Options': 'nosniff',
+    'Cache-Control': 'private, no-store',
+    'Cross-Origin-Resource-Policy': 'same-origin',
+  }
+  // Opened directly, nothing in it runs and it cannot reach this origin. A PDF keeps the browser's viewer.
+  if (!inline) headers['Content-Security-Policy'] = "sandbox; default-src 'none'"
+  return headers
+}
+
 export const agentSessionOutputImages = new AgentSessionOutputImages({
   findSession: (p, id) => findAgentSessionFile(p, id, agentSessionRoots()),
   workspace: async (provider, id, transcript) => {
@@ -277,4 +854,5 @@ export const agentSessionOutputImages = new AgentSessionOutputImages({
   },
   store: getMediaStore,
   secret: randomBytes(32), now: Date.now,
+  extraRoots: () => previewFoldersSetting.read().folders,
 })