Merge branch 'rel1411/html-md': render HTML files as pages (#547) and open .md from the terminal in the rendered viewer

Conflicts resolved against #604, #606 and #601:
- constants.js: the rooted link pattern takes html-md's `markdown` and
  `html?` with #606's m4v/ogv; #604's relative pattern gets the same list
  (link-provider-regex pins the two equal); #604's findFilePathLinks /
  folder helpers and html-md's rendersAsPage() are both kept, and
  window.CodemanFilePaths exports all of them.
- terminal-ui.js: #604's resolved `target` (relative, ~/ and folder links)
  now also goes through rendersAsPage(), so every link kind routes .html to
  the page preview; .md routes there through FILE_PREVIEW_EXTENSIONS.
- CLAUDE.md, api-reference, architecture-invariants: both sides' text kept.
- test/folder-grid-ui.test.ts (#604) stubs rendersAsPage() like the other
  panels-ui harnesses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -303,19 +303,19 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Prompt uploads** (`POST /api/sessions/:id/paste-image`: clipboard paste, drop, the Compose Attach key and the phone toolbar's Attach button; client wiring in `image-input.js` and `keyboard-accessory.js`): a pick is written to `<workspace>/.codeman-uploads/` and its path lands on the prompt as unsent text. The folder is IN the workspace because that is the only path identical for a local and a container agent, FLAT because `<workspace>/.codeman/` would BE the data dir when the workspace is the home directory, and self-ignoring through a `.gitignore` of `*` written ONCE with `wx` (a file already there is the user's and is never overwritten; the user's own ignore file is never touched). ⚠️ The directory names live ONLY in `paste-image-gc.ts` (`UPLOAD_DIR_NAMES`): the pre-move `.claude-images/` receives nothing but stays readable for one release, so the GC sweep and the delete cleanup (through `uploadDirs()`) and the image watcher's ignore filter (reading the names) cover BOTH; retire the legacy entry there, never by hand elsewhere. ⚠️ `uploadDirs()` is async and probes the workspace BOUNDED first (`probePathKind()`, the #516 rule: an `unknown` path is skipped, never touched; the sweep keeps the stall cap and the delete passes `pastCap`), then returns only REAL directories (lstat, so a planted symlink is never one), none that is or contains `getDataDir()` (one strictly inside it only holds uploads and is listed), and none for a remote session, since both consumers delete; the check is made at list time, and the same-user race after it is accepted. Images are buffered in memory under `MAX_PASTE_IMAGE_BYTES` (50MB) after a client-side canvas re-encode. A VIDEO is never buffered: `?kind=video` streams it to disk under `MAX_PASTE_VIDEO_BYTES` (1GB, env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), judges the container on the first 12 bytes as they arrive (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv; a mislabeled body is drained unwritten from there, never parked on disk first) and unlinks on any failure, a dead transfer included. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced: mp4/webm/mov/m4v/ogv, so an uploaded video is one the file viewer can also play; 3gp/mkv are out, since a phone's camera roll produces neither and neither previews), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. Busboy takes its size limit before the part is seen, which is why the choice rides the URL and not the file. ⚠️ A video draws on its OWN per-(IP, session) rate bucket (`consumeVideoToken`, 3/min) beside the image bucket (`consumePasteToken`, 30/min): at 1GB each, 30/min would be 30GB of disk a minute, so the lower rate bounds it to 3GB; the image path keeps the 30/min bucket and is unchanged without the flag. A remote (SSH) session is refused (400) before any disk touch: its `workingDir` is the remote path, so the file would land on THIS host where the agent cannot read it (Docker is fine, the workspace is bind-mounted at the same absolute path). ⚠️ A live session's workspace can still sit on a network mount that stopped answering, so the route probes it BOUNDED (`probePathKind(session.workingDir, { pastCap: true })`, the #516 rule) before the first disk touch and refuses an `unknown` mount through `describeUnknownPath()` (OPERATION_FAILED), the way session create does, so a mount already unreachable cannot freeze a libuv worker on every upload (a mount that dies after the probe is the same residual race create accepts). ⚠️ The client classifies a pick through ONE helper, `_promptAttachKind()` (MIME type first, then the name's extension, because some Android file managers hand over a File with none); every pick and paste filter (Attach, drop, the tile grid's drop in `tile-grid.js`, the Compose and paste-dialog pickers, the clipboard handlers), the flag and the re-encode gate read it, never `file.type` directly. ⚠️ A pick that lands while the tile grid owns the terminal goes to the PTY, never the main terminal's overlay: that terminal is parked and hidden then, and a tile's Enter cannot flush it (`_tilesOwnTerminal()` in the `_attachFromToolbar` guard). Tests: `test/toolbar-attach.test.ts`, `test/mobile-prompt-composer.test.ts`, `test/paste-image-gc.test.ts`, `test/paste-image-dir-shared.test.ts`, the paste-image block of `test/routes/session-routes.test.ts`. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history)
 
-**File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). Both call `findFilePathLinks()`, which adds `~/`, relative and folder paths without overlapping a rooted match or a URL; a relative path resolves against `workingDir` (`resolveLinkedFilePath`), `~/` only server-side on the session's host (attachment route), and `terminalPathLine()` joins a path a program hard-wrapped short of the edge. ⚠️ A folder link opens the **folder grid**: `POST /api/sessions/:id/folders` guards + GRANTS the folder (`folder-listing.ts`, own registry, never the 200-capped attachment registry), files come by bare name via `…/folders/:folderId/files/:name/*` through `resolveServableAttachmentPath` plus the same extension/regular-file gate on the symlink's resolved target, so no browser request carries a path; `~/` is refused in a Docker case (the container's home is not this host's). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. Media extensions are single-sourced in `attachment-registry.ts`. ⚠️ **XLSX previews parse in the BROWSER**, never on the server: `spreadsheet-preview.js` fetches the raw route with `?preview=true` (413 above `MAX_XLSX_BROWSER_PREVIEW_BYTES`, 10 MB) and hands the bytes to `spreadsheet-preview-worker.js`, the only place the pinned `exceljs`/`fflate` vendor bundles load (never on page load). `admitXlsx()` caps the ZIP before ExcelJS runs, counting what ExcelJS will EXPAND as well as what it reads (a merge costs its area, a `<col>` past 16384 is refused, validations are never parsed via `ignoreNodes`, and defined names are never expanded: the worker stubs `_definedNames.model`). ⚠️ The INDEX a row or sheet claims is bounded too, since ExcelJS allocates and walks up to it: a `<row r>` outside 1-1048576 and an `xl/workbook.xml` `<sheet sheetId>` above `LIMITS.maxSheetId` (65535) are refused, and `sendTile` reuses the merges read at load (`mergesById`), never `sheet.model`, which rebuilds the whole sheet. ⚠️ The COLUMN index costs the same way (a row's cells live at `_cells[col - 1]`, so one `XFD` cell makes ExcelJS's `eachRow`/`eachCell`/`hasValues` visit 16,384 slots per row): `worksheetMetadata` builds each sheet's row and cell index from the keys that exist (`Object.keys` of `_rows` and `_cells`, skipping falsy and `Null`-type cells as `eachCell({ includeEmpty: false })` does), reads row heights in that pass and merges from `sheet._merges`, and `sendTile` reads cells from that index (`populatedRowsById`); never call ExcelJS's dense `eachRow`/`eachCell` there. `parseThemePalette` returns the default palette for a theme above 64 KB (64 * 1024 characters), since its patterns are quadratic on unclosed tags. ⚠️ Merges are capped per sheet (`LIMITS.maxMergesPerSheet`, 2,000) AND workbook-wide (`LIMITS.maxMerges`, 10,000), refused as `merge-limit` before ExcelJS loads, since ExcelJS's `_mergeCellsInternal` checks each merge against every earlier one on its sheet (quadratic). Every `<numFmt>` in `xl/styles.xml` is read with `readTagAttributes()` and refused (`number-format`) when its decoded `formatCode` is over 255 characters or has a `[` after its last `]`: ExcelJS's `isDateFmt` rescans to the end of the code per unclosed `[` once per numeric cell, and the code is echoed into the notice bar. ⚠️ `formatCellValue` caps every cell's display text at `LIMITS.maxCellTextChars` (1,000, ellipsis, never splitting a surrogate pair) for every value shape (rich text, hyperlink text, formula source, errors), since structured clone copies each tile cell's whole string to the page and the load timeout no longer covers tiles. `richTextPrefix` also visits at most `maxCellTextChars + 1` runs, not only keeps that much text: an empty `<r/>` adds nothing, so a shared string of a million empty runs was walked whole per cell, per tile (56 s a tile). ⚠️ Every part ExcelJS parses (all but the pure-bytes `xl/media/<name>.<ext>`) is also charged per START TAG against `LIMITS.maxElements` (2,000,000, refused as `element-limit`): ExcelJS builds an object per element in sharedStrings, styles, comments, drawings, VML and tables too, and empty stored blocks pad a deflate stream past the ratio cap, so 8.3M empty `<r/>` runs in a 375 KB file cost 570 MB of heap. ⚠️ Admission keys every entryLine truncated
+**File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). Both call `findFilePathLinks()`, which adds `~/`, relative and folder paths without overlapping a rooted match or a URL; a relative path resolves against `workingDir` (`resolveLinkedFilePath`), `~/` only server-side on the session's host (attachment route), and `terminalPathLine()` joins a path a program hard-wrapped short of the edge. ⚠️ A folder link opens the **folder grid**: `POST /api/sessions/:id/folders` guards + GRANTS the folder (`folder-listing.ts`, own registry, never the 200-capped attachment registry), files come by bare name via `…/folders/:folderId/files/:name/*` through `resolveServableAttachmentPath` plus the same extension/regular-file gate on the symlink's resolved target, so no browser request carries a path; `~/` is refused in a Docker case (the container's home is not this host's). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. ⚠️ The ONE place HTML renders is `/html-view/<cap>/...` (`html-view-routes.ts`, `html-view-capabilities.ts`): `POST /api/sessions/:id/html-view` mints a capability for the file's own directory, every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin` (opaque origin even as a top-level tab, so the page can never read Codeman or drive its API) and with NO fetch directive (open network, owner decision 2026-10-13: never restrict it or add `allow-same-origin` without the owner), and only non-dot, asset-allowlisted files under that directory are served (GET/HEAD only; capabilities revoked with the web-tab ones on logout). That tree is served recursively, so minting is refused for a hidden directory or a broad root (`isBroadHtmlViewRoot`); the preview renders by default and the **Page** pill (or a refused mint) falls through to the source view and its Edit button. Never serve HTML same-origin anywhere else. Tests: `test/routes/html-view-routes.test.ts`. Media extensions are single-sourced in `attachment-registry.ts`. ⚠️ **XLSX previews parse in the BROWSER**, never on the server: `spreadsheet-preview.js` fetches the raw route with `?preview=true` (413 above `MAX_XLSX_BROWSER_PREVIEW_BYTES`, 10 MB) and hands the bytes to `spreadsheet-preview-worker.js`, the only place the pinned `exceljs`/`fflate` vendor bundles load (never on page load). `admitXlsx()` caps the ZIP before ExcelJS runs, counting what ExcelJS will EXPAND as well as what it reads (a merge costs its area, a `<col>` past 16384 is refused, validations are never parsed via `ignoreNodes`, and defined names are never expanded: the worker stubs `_definedNames.model`). ⚠️ The INDEX a row or sheet claims is bounded too, since ExcelJS allocates and walks up to it: a `<row r>` outside 1-1048576 and an `xl/workbook.xml` `<sheet sheetId>` above `LIMITS.maxSheetId` (65535) are refused, and `sendTile` reuses the merges read at load (`mergesById`), never `sheet.model`, which rebuilds the whole sheet. ⚠️ The COLUMN index costs the same way (a row's cells live at `_cells[col - 1]`, so one `XFD` cell makes ExcelJS's `eachRow`/`eachCell`/`hasValues` visit 16,384 slots per row): `worksheetMetadata` builds each sheet's row and cell index from the keys that exist (`Object.keys` of `_rows` and `_cells`, skipping falsy and `Null`-type cells as `eachCell({ includeEmpty: false })` does), reads row heights in that pass and merges from `sheet._merges`, and `sendTile` reads cells from that index (`populatedRowsById`); never call ExcelJS's dense `eachRow`/`eachCell` there. `parseThemePalette` returns the default palette for a theme above 64 KB (64 * 1024 characters), since its patterns are quadratic on unclosed tags. ⚠️ Merges are capped per sheet (`LIMITS.maxMergesPerSheet`, 2,000) AND workbook-wide (`LIMITS.maxMerges`, 10,000), refused as `merge-limit` before ExcelJS loads, since ExcelJS's `_mergeCellsInternal` checks each merge against every earlier one on its sheet (quadratic). Every `<numFmt>` in `xl/styles.xml` is read with `readTagAttributes()` and refused (`number-format`) when its decoded `formatCode` is over 255 characters or has a `[` after its last `]`: ExcelJS's `isDateFmt` rescans to the end of the code per unclosed `[` once per numeric cell, and the code is echoed into the notice bar. ⚠Line truncated
 
 **Filesystem path picker** (Link Existing "Browse" + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file. Inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping** — it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)
 
 **File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place — `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that WRITES**: read-path confinement (realpath + workspace + ownership) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md`
 
-**File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md` stays OUT of `FILE_PREVIEW_EXTENSIONS`: only an IN-WORKSPACE `.md` path clicked in the TERMINAL keeps the tail viewer (live follow); the Files panel, chat paths, out-of-workspace terminal paths and attachment cards all reach `openFilePreview()` and render it. Tests: `test/file-preview-markdown.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
+**File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md`/`markdown` are IN `FILE_PREVIEW_EXTENSIONS` (owner decision 2026-10-13): a markdown path clicked or tapped in the TERMINAL (main pane, grid tiles and split Pane B share `registerFilePathLinkProvider`) opens this rendered view like every other surface, never the streaming log viewer; other in-workspace text keeps the tail viewer (live follow). The terminal pattern links `.markdown` and `.htm` too. Tests: `test/file-preview-markdown.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
 
 **Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure) compiles the query into a predicate the server-side walk prunes with; a query returns a FLAT match list and the walk recurses past non-matching directories. An empty, whitespace-only or overlong (`MAX_QUERY_LENGTH`, 256) query compiles to `null`, keeping the default tree response byte-identical. ⚠️ **Never compile a glob into a RegExp** (`*a*a*a…` backtracks and freezes the event loop for the whole server): `globMatch()` is a two-pointer wildcard walk. → [architecture-invariants#files-panel-search](docs/architecture-invariants.md#files-panel-search)
 
 **Git status indicator** (`showGitStatus`, per-device, default OFF; `src/git-workspace-status.ts`, `routes/git-status-routes.ts`, `git-status-ui.js`): the bottom-bar indicator and its panel read `GET /api/sessions/:id/git-status` and `/git-diff`, read-only and offline (it never fetches and never writes). ⚠️ git never runs on a repository at or inside a Docker case workspace (walk-up, scan and diff alike, and a cached repository list is re-checked against the CURRENT Docker roots), since a container could plant a clean filter that runs on the host; remote and Docker sessions answer `unsupported`. ⚠️ `git-diff` takes `repo`/`path`/`kind` only as keys matched against the workspace's own repository list (`findWorkspaceRepo()`) and that repository's current status, never as paths. ⚠️ Keep `--no-optional-locks`, `core.fsmonitor=false` and `log.showSignature=false` on every call and `--no-ext-diff --no-textconv` on diffs; clean filters still run, which is why the Docker rule exists. ⚠️ An enclosing repository at `$HOME` or above is ignored (`isUnrelatedAncestor()`), and is identified by one cached `rev-parse` before any full status runs. Everything git supplies renders via `textContent`. Tests: `test/git-workspace-status.test.ts`, `test/routes/git-status-routes.test.ts`, and `test/git-status.browser.test.ts` (browser suite, not in the gate).
 
-**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route and `GET /api/download` share `sendFileBody()`, advertise `Accept-Ranges: bytes` and answer `Range` with `206` + `Content-Range` (single-range, parser in `src/web/http-range.ts`); without it `<video>` cannot seek. The size cap (`MAX_FILE_DOWNLOAD_BYTES`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) is a sanity bound, not memory protection; never reintroduce a whole-file buffer. ⚠️ Bodies go out via `reply.hijack()`, so `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships as `200`. ⚠️ Closing the preview must pause and unload media (`_stopFilePreviewMedia`), since a detached `HTMLMediaElement` keeps playing. → [architecture-invariants#raw-file-bodies-streamed-and-range-aware](docs/architecture-invariants.md#raw-file-bodies-streamed-and-range-aware)
+**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route, `GET /api/download` and the rendered-HTML route `GET /html-view/<cap>/...` share `sendFileBody()`, advertise `Accept-Ranges: bytes` and answer `Range` with `206` + `Content-Range` (single-range, parser in `src/web/http-range.ts`); without it `<video>` cannot seek. The size cap (`MAX_FILE_DOWNLOAD_BYTES`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) is a sanity bound, not memory protection; never reintroduce a whole-file buffer. ⚠️ Bodies go out via `reply.hijack()`, so `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships as `200`. ⚠️ Closing the preview must pause and unload media (`_stopFilePreviewMedia`), since a detached `HTMLMediaElement` keeps playing. → [architecture-invariants#raw-file-bodies-streamed-and-range-aware](docs/architecture-invariants.md#raw-file-bodies-streamed-and-range-aware)
 
 **Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
 

docs/api-reference.md

@@ -43,8 +43,9 @@ payload return `{ "success": true, "data": {} }`.
 
 > Non-JSON endpoints are exempt from the envelope: `GET /api/sessions/:id/file-raw`,
 > `GET /api/sessions/:id/tail-file` (SSE), `GET /api/download`,
-> `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect), and the
-> `GET /ws/sessions/:id/terminal` WebSocket upgrade.
+> `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect),
+> `GET /html-view/:cap/*` (a [rendered HTML file](#rendered-html-files) and its
+> assets), and the `GET /ws/sessions/:id/terminal` WebSocket upgrade.
 >
 > **Deprecated:** `POST /api/screenshots`, `GET /api/screenshots` and
 > `GET /api/screenshots/:name` keep working but log a one-time warning on first
@@ -599,6 +600,49 @@ beside the 30 per minute the image path keeps; without the flag the route is
 byte-identical to the image-only version, same 50 MB image cap and same 30/min
 bucket. The response shape is unchanged (`path`, `filename`).
 
+## Rendered HTML files
+
+An `.html`/`.htm` file renders as a page in a sandbox, in two steps
+(`src/web/routes/html-view-routes.ts`).
+
+**`POST /api/v1/sessions/:id/html-view`** with `{ "path": "<file>" }` (absolute, or
+relative to the session's workspace; a non-empty string of at most 4096 characters
+without NUL or line breaks, and no other keys) answers `data: { url }`, a
+`/html-view/<cap>/<file>` URL. The capability grants GET access to the files under
+that file's own folder, so a page's relative CSS, scripts, images and data files
+resolve. It is held in memory only (a restart invalidates it), has a rolling TTL
+(`CODEMAN_WEBVIEW_CAPABILITY_TTL_MS`, default 12 h), is reused for the same folder,
+and is revoked on logout, admin logout and user deletion. Refusals:
+
+- `400`: an invalid body, a remote (SSH) session, or a file that is not HTML (the
+  symlink-resolved name counts too);
+- `404`: no such file;
+- `403`: a file outside the workspace that the attachment guard blocks (a blocked
+  tree, or `attachmentConfineToWorkspace` on), a file in a hidden directory (inside
+  the workspace, one below the workspace root), or a file directly in a folder too
+  broad to serve recursively: `/`, the home folder, `/tmp`, `/var/tmp`, `$TMPDIR`,
+  the cases and user-space roots, a drive's mount point (`/mnt/d`), or any folder
+  above one of those (`/home`, `/Users`).
+
+**`GET /html-view/:cap/*`** serves the page and its assets. It needs no cookie: the
+capability in the path is the credential, because the page runs in an opaque origin
+that never sends one. It is not under `/api`, so it has no `/api/v1` alias and no
+envelope. `GET` and `HEAD` only; a CORS preflight on a live capability is answered
+with `Access-Control-Allow-Methods: GET, HEAD`. What it serves: files under the
+capability's folder whose path (requested and symlink-resolved) has no dot segment
+and whose extension is on an asset allowlist (html, css, js/mjs, json, map, txt,
+csv, md, svg and common image, font, wasm, audio, video and PDF types), never
+outside the folder, never a blocked tree, and, for a folder outside the workspace,
+not while `attachmentConfineToWorkspace` is on. Every response carries
+`Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads`
+as its whole policy (never `allow-same-origin`, so the page cannot read Codeman's
+document, cookies or API, even opened as a top-level tab; and no fetch directive, so
+by the owner's decision the page may load from and send requests to any host), `Cache-Control: no-store`,
+`Referrer-Policy: no-referrer` and `Access-Control-Allow-Origin: *`. A `Range`
+request is answered with `206` + `Content-Range` (`416` past the end), like
+`file-raw`. Every refusal is a plain-text `404 Not found`; with a password set, an
+unknown or revoked capability is the auth hook's `401` instead.
+
 ## Session lineage (`parentSessionId`)
 
 A create request may name the session that spawned it, which the web UI draws as a

docs/architecture-invariants.md

@@ -376,13 +376,13 @@ A file path an agent prints is a link on both surfaces it can appear on, and cli
 
 **Out-of-workspace paths go through the attachment routes, not the file routes.** `file-content`/`file-raw` resolve against `workingDir` and 404 anything that escapes it, which is correct and unchanged — but the paths agents most often print (a `/tmp` capture, Claude's own scratchpad, another checkout) are exactly that, so clicking one used to report "File not found" for a file sitting on disk. `openFilePreview()` now detects the case (`_isExternalPreviewPath`, a string compare for ROUTING only; the real decision stays server-side) and registers the path via `POST /api/sessions/:id/attachments` first, rendering by id. ⚠️ That registration passes `notify: false`, which suppresses ONLY the `attachment:detected` broadcast — the guard, the registry entry and the by-id routes are identical either way. Without it every click also popped an attachment card announcing the file already filling the screen. ⚠️ The click is an explicit user action on the **explicit, Origin-guarded** registration route, which is why it may cross the workspace boundary at all; the passive magic-link scanner stays force-confined. A type outside `SUPPORTED_ATTACHMENT_EXTENSIONS` (`.svg`, `.bmp`) is refused with a message naming what IS previewable, rather than the registry's own policy term.
 
-⚠️ **The terminal routes an out-of-workspace path to the preview, not the log viewer.** The log viewer spawns `tail -f` and allows only the workspace, `/var/log` and `~/logs`, so an external `.log`/`.json`/code path answered `Path must be within working directory or allowed log directories` while the SAME path clicked in the response viewer previewed fine. `activate()` now checks `_isExternalPreviewPath` alongside `previewsInFileViewer`. In-workspace text keeps the tail viewer, which is the point of it (live follow); nothing widened `file-stream-manager`'s allowlist, so no `tail -f` is spawned on an arbitrary host path.
+⚠️ **The terminal routes an out-of-workspace path to the preview, not the log viewer.** The log viewer spawns `tail -f` and allows only the workspace, `/var/log` and `~/logs`, so an external `.log`/`.json`/code path answered `Path must be within working directory or allowed log directories` while the SAME path clicked in the response viewer previewed fine. `activate()` now checks `_isExternalPreviewPath` alongside `previewsInFileViewer`. In-workspace text keeps the tail viewer, which is the point of it (live follow), except markdown (`.md`/`.markdown`, in `FILE_PREVIEW_EXTENSIONS` since the owner's 2026-10-13 decision, rendered as a document) and `.html`/`.htm` (`rendersAsPage()`, rendered as a page, see below), which always go to the preview; nothing widened `file-stream-manager`'s allowlist, so no `tail -f` is spawned on an arbitrary host path.
 
 **Path forms beyond the rooted one.** `findFilePathLinks(text)` (constants.js) is the single entry point both consumers call; it returns the rooted matches first, then `~/` and relative paths (`RELATIVE_FILE_PATH_LINK_PATTERN`, same extension list, pinned equal by `test/link-provider-regex.test.ts`), then folder paths, each only where it overlaps neither an earlier match nor an `http(s)` URL. A relative match must start at a boundary (line start, whitespace, quote, bracket, `=`, `,`, `>`), so it can never begin inside a word, an absolute path or a URL; brackets, `=` and `,` end it (`(shot.png)`, `OUT=shots/a.png`). `resolveLinkedFilePath()` resolves a relative path against the session's `workingDir` (`.`/`..` collapsed, so `../x.png` lands outside and routes like any external path) and passes absolute and `~/` paths through. ⚠️ `~` is the home of the SESSION'S host, which only the server knows: `~/` paths always take the attachment route, where `registerExternalAttachment` expands them (`homedir()` locally, `$HOME` inside the remote probe script), and the guard runs on the expanded, realpath-resolved path as before. ⚠️ Programs hard-wrap their own output short of the terminal edge (Claude Code breaks tool output at 59-118 columns), so xterm's `isWrapped` never fires. `terminalPathLine()` (link provider only; touch selection keeps `terminalLogicalLine`) joins the next row when the previous row ends in a path token with a `/` and no extension and the join reaches an extension; a row that starts a new path is never joined: rooted or `~/`, `./`/`../`, or a relative one that opens on the same top directory the broken token did (the next entry of `git ls-files`/`find`/`ls -R`: `src/components` + `src/index.ts` are two paths, not `src/componentssrc/index.ts`), while a wrapped path continues INSIDE a name, so `…/captures/2` + `026-10-10/…` still joins; a 3+ row chain is kept only if a later row completes the path, and the broken row must be at least as long as the continuing one (keeps `cd /mnt/foo` + a longer next line apart). Tests: `test/file-path-link-forms.test.ts`.
 
 **Folder grid: a folder is granted, then served by bare file name.** A folder path (rooted or `~/` whose last segment has no extension, relative only with a trailing `/`; `FOLDER_PATH_LINK_PATTERN` + `folderLinkPath()`) opens `openFolderGrid()` (panels-ui.js), as does the preview's "Show folder" button. `POST /api/sessions/:id/folders {path}` (`src/folder-listing.ts`) resolves the folder (locally a bounded `probePathKind(…, { pastCap: true })` first, then async `fs.realpath`; remotely one ssh round trip via `remoteListFolder`, through `runWithRemoteSshLimit`), runs the attachment guard on it (blocklist, `confineToWorkspace`, and in multi-user mode `folderAllowedForUser`: a non-admin only inside their own `userSpacePath` or the session's `workingDir`, as the filesystem path picker), locally BEFORE reading it, lists non-hidden subfolders and files of a supported attachment type (each file also blocklist-checked, newest first, capped at `MAX_FOLDER_ENTRIES`), and GRANTS it an id. Files are then fetched as `GET …/folders/:folderId/files/:name/(raw|preview|thumbnail)`: `:name` must be a bare file name of a supported type (no `/`, `\`, NUL, no leading `.`, since the listing hides those), the local file is probed bounded (`unknown` → 503, never 404), and the joined path goes through the SAME `resolveServableAttachmentPath` as an attachment by id (symlink re-resolution, remote re-probe, guard), then the same gate registration applies to what a symlink RESOLVES to (a supported extension on the resolved path and a regular file: locally `fs.stat`, remotely the probe kind; else 400, so `shot.png -> ../secret.bin` is not served and a FIFO or device behind a supported name never reaches `open`), then `folderAllowedForUser` once more on the resolved file, before `serveServableRaw` (the attachment raw route's body, shared) streams it. So browser requests still never carry a path. ⚠️ Grants live in their own registry (`folderGrants`, 32 per session, cleared with the session's attachments), NOT the attachment registry: that one is capped at 200 per session, and paging a folder of 300 renders would evict the session's real attachments. ⚠️ A local folder is never touched unbounded (#516 rule): a folder on a network mount that stopped answering answers 503 with `describeUnknownPath()`, not 404 and not a frozen server. ⚠️ The remote listing script tells "missing" (`E|n`, 404) from "is a file" (`E|f`, 400 `Not a folder`), because the client falls back to the file preview on `Not a folder`; a remote extensionless file otherwise answered "Folder not found". ⚠️ `.folder-grid-overlay` sits at `z-index: 5090`, one step BELOW the preview (5100) and above the response viewer (5000): a tile's preview opens on top and closing it lands back on the grid. ⚠️ ←/→/Esc are handled in a document CAPTURE listener with `stopPropagation`, because the terminal keeps keyboard focus under the overlays and an arrow that reached xterm would be typed into the session; inputs other than xterm's helper textarea keep their keys. ⚠️ A route PARAMETER is capped by the router (Fastify's default is 100 characters, answered as 404 "Route not found"), and a file name goes up to 255, percent-encoded: the server sets `routerOptions.maxParamLength` to `MAX_ROUTE_PARAM_LENGTH` (route-helpers.ts), the route test harness uses the same constant, and a wiring guard pins it. ⚠️ `~/` in a Docker case is refused with 400 (attachment POST and `POST …/folders`): the session is local for these routes, but `~` inside the container is the container's own home, and expanding it on the host would open a different file than the one the agent printed. Tests: `test/routes/folder-grid-routes.test.ts` (incl. the listing script on a real `sh`), `test/folder-grid-ui.test.ts`.
 
-**Text reuses the edit-mode allowlist; markup stays download-only.** `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (`config/file-editing.ts`) rather than a second curated list that would drift from it: if the viewer would open a file for editing inside the workspace, the same file outside it can be read. The justification for widening is that the agent in the session can already `cat` any of these and the picker already previews them, so the suffix was never the confidentiality gate; the path guard is (sensitive-file blocklist, `/root` and `/etc` trees, realpath first). ⚠️ Two consequences had to be handled at the same time: `~/.codeman*/state.json` joined `isSensitivePath` (it persists `SessionState.envOverrides`, and the env allowlist admits key-shaped names like `GEMINI_API_KEY`, so it can hold a live credential), and `html`/`htm` joined `svg` in `serveRawFile`'s **download-only** branch so that widening what can be READ never widens what can RUN on our own origin. Text with no dedicated MIME entry goes out as inert `text/plain; charset=utf-8` + `nosniff`, matching the picker. The by-id text preview is bounded like the workspace one: a `Range` request for the first 512KB (a real partial read, not a discarded 50MB download) plus a 500-line cap, with the footer saying so.
+**Text reuses the edit-mode allowlist; markup stays download-only.** `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (`config/file-editing.ts`) rather than a second curated list that would drift from it: if the viewer would open a file for editing inside the workspace, the same file outside it can be read. The justification for widening is that the agent in the session can already `cat` any of these and the picker already previews them, so the suffix was never the confidentiality gate; the path guard is (sensitive-file blocklist, `/root` and `/etc` trees, realpath first). ⚠️ Two consequences had to be handled at the same time: `~/.codeman*/state.json` joined `isSensitivePath` (it persists `SessionState.envOverrides`, and the env allowlist admits key-shaped names like `GEMINI_API_KEY`, so it can hold a live credential), and `html`/`htm` joined `svg` in `serveRawFile`'s **download-only** branch so that widening what can be READ never widens what can RUN on our own origin. Text with no dedicated MIME entry goes out as inert `text/plain; charset=utf-8` + `nosniff`, matching the picker. ⚠️ **The one place HTML renders is `/html-view/<cap>/...`** (`html-view-routes.ts`, `html-view-capabilities.ts`), never these routes: `POST /api/sessions/:id/html-view` mints a capability for the HTML file's own directory, and every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin`, so the page is opaque-origin even as a top-level tab and cannot read Codeman or drive its API. ⚠️ **Network access is open, by the owner's decision (2026-10-13, #547):** `HTML_VIEW_CSP` is the `sandbox` directive alone, which REPLACES Codeman's own CSP, with no fetch directive, so a page loads scripts, styles, fonts, images and media from anywhere and may fetch, XHR, open WebSockets, send beacons and post forms anywhere, like a file opened from disk. It can read its own folder through the capability and nothing else on this server; it cannot use Codeman's origin, cookies or API, or reach other folders. Never add a fetch directive or `allow-same-origin` without the owner; the exact header is pinned in `test/routes/html-view-routes.test.ts`. The directory is served recursively to the page's scripts (non-dot, asset-allowlisted, realpath-confined, blocklist applied, GET/HEAD only; the dot and extension rules run on the requested name AND on the symlink-resolved target, or a `cfg.json -> .git/config` link would serve the git config), which is why minting is refused for an HTML file in a hidden directory (for a file inside the workspace, a hidden directory below the workspace root, so a workspace that itself lives under one still renders) or directly in a broad root (`/`, home, `/tmp`, `/var/tmp` and `$TMPDIR` (named literally, since macOS sets `TMPDIR` in every terminal), the cases and user-space roots, a drive's mount point such as WSL's `/mnt/d`) or in any directory above one of them (`/home`, `/Users`, macOS's `/private`; `isBroadHtmlViewRoot`). A capability minted for a folder outside the workspace records that, and the serving route refuses it per request once `attachmentConfineToWorkspace` is on, the same re-check the attachment serve path makes. The preview renders it by default; the **Page** pill (`htmlRendered`, per-device like `mdRendered`) and any refused mint fall through to the source view with its Edit button. Tests: `test/routes/html-view-routes.test.ts`, the html-view block in `test/webview-auth-exemption.test.ts`, `test/webview-capability-revocation.test.ts`. The by-id text preview is bounded like the workspace one: a `Range` request for the first 512KB (a real partial read, not a discarded 50MB download) plus a 500-line cap, with the footer saying so.
 
 **Media is single-sourced across the two preview paths.** `VIDEO_ATTACHMENT_EXTENSIONS` / `AUDIO_ATTACHMENT_EXTENSIONS` live in `attachment-registry.ts` and are imported by `file-content`'s media classification, so a clip plays identically whether it is in the workspace or reached by id from outside it. They diverged first: the workspace path had its own inline sets and the registry allowlist had no media at all, so a video an agent wrote to `/tmp` was refused as an unsupported type while the same file inside the repo played. ⚠️ Three things have to line up for a player rather than a dead frame: the extension in the allowlist, a **real MIME entry** in `MIME_TYPES` (a `<video>` refuses to decode `application/octet-stream`, which presents as a player that renders and then does nothing), and the range-aware body (`serveRawFile` → `sendFileBody`) that makes the scrub bar work. `getAttachmentType()` returns the `video`/`audio` members of `AttachmentDetectedType` for them; the attachment card has no per-type CSS and its thumbnail falls back to the type label, since `generateFirstPageThumbnail` has no media branch and answers 204. ⚠️ The image-watcher keeps its OWN narrow detection list (`png/pdf/docx/pptx`), so this does not start popping cards for every video an agent writes.
 
@@ -427,7 +427,7 @@ Tests: `test/file-editing-policy.test.ts` (pure policy), `test/routes/file-write
 - ⚠️ **`data-i18n-skip` on the container.** The translator's MutationObserver translates inserted headings and paragraphs, and the `.file-preview-content` entry in its skip list matches nothing (no element has that class), so the attribute is what keeps a Chinese UI from rewriting a README.
 - ⚠️ **Toggles are per-device, in their own localStorage keys** (`codeman:filePreviewMdRendered` / `LineNumbers` / `Wrap`), for the same reason as the Files panel's show-hidden toggle: the app-settings object is rebuilt from the settings modal on every save, and they are display state, not synced settings (`SettingsUpdateSchema` is `.strict()`). MD re-renders from the kept source (`filePreviewContent`, which is also what Copy copies) without a refetch; Lines/Wrap are class flips on the one `<pre>`, whose rules are scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's own code blocks. Lines are one inline `<span class="fp-line">` per line joined by real newlines, the counter in `::before` with `user-select: none`, so select and copy return the exact text.
 - ⚠️ **Caps.** Markdown fetches `lines=10000` (the route's `MAX_LINES_LIMIT`), because a rendered document cut at 500 lines reads as the whole document; other text keeps 500, which is what stops a huge log locking the tab in one `<pre>`. The attachment (out-of-workspace) branch keeps its 512 KB Range read and skips the 500-line clip for markdown. Edit mode is unchanged and still re-fetches `edit=1`; the three toggles hide while editing and for images, media and PDFs.
-- ⚠️ **`md` is NOT in `FILE_PREVIEW_EXTENSIONS`.** Only an in-workspace `.md` path clicked in the terminal still opens the tail viewer (see File-path links above: in-workspace text keeps live follow, which is what Ralph's `fix_plan.md` needs). Everything else reaches `openFilePreview()` and renders it: the Files panel, a path clicked in the Response Viewer (its delegate calls `openFilePreview()` directly), an out-of-workspace terminal path, and attachment cards. `avif` and `ico` were added to the set (a printed `favicon.ico` used to tail binary noise), with `avif` also in file-content's image set and file-raw's MIME map; out-of-workspace avif/ico stay unregistrable, like svg/bmp.
+- ⚠️ **`md` and `markdown` ARE in `FILE_PREVIEW_EXTENSIONS`** (owner decision 2026-10-13). Until then an in-workspace `.md` path clicked in the terminal opened the tail viewer, which showed "streaming" over raw text instead of the document (the live follow it gave Ralph's `fix_plan.md` was not worth that). Now every surface reaches `openFilePreview()` and renders it: the terminal (the main pane, grid tiles and the split's Pane B share `registerFilePathLinkProvider`, and a touch tap activates the same provider), the Files panel, a path clicked in the Response Viewer (its delegate calls `openFilePreview()` directly), and attachment cards. `FILE_PATH_LINK_PATTERN` links `.markdown` (and `.htm`) as well, or such a path would not be clickable at all. Other in-workspace text (`.log`, `.txt`, `.json`, code) keeps the tail viewer. `avif` and `ico` were added to the set (a printed `favicon.ico` used to tail binary noise), with `avif` also in file-content's image set and file-raw's MIME map; out-of-workspace avif/ico stay unregistrable, like svg/bmp.
 
 Tests: `test/file-preview-markdown.test.ts` (jsdom-in-vm, pins every rule above), `test/routes/file-routes.test.ts` (avif).
 
@@ -669,7 +669,7 @@ Matching semantics: a query containing `/` matches the relative path, otherwise
 
 ### Raw file bodies: streamed and range-aware
 
-**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route and `GET /api/download` always advertise `Accept-Ranges: bytes` and answer a `Range` header with `206` + `Content-Range` (single-range only; parser is pure + unit-tested in `src/web/http-range.ts`, a malformed spec is ignored → 200 while an out-of-bounds one is a 416).
+**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route, `GET /api/download` and the rendered-HTML route `GET /html-view/<cap>/...` (so a rendered page's own `<video>`/`<audio>` can seek) always advertise `Accept-Ranges: bytes` and answer a `Range` header with `206` + `Content-Range` (single-range only; parser is pure + unit-tested in `src/web/http-range.ts`, a malformed spec is ignored → 200 while an out-of-bounds one is a 416).
 
 ⚠️ **The size cap on all three is a sanity bound, not memory protection** (`MAX_FILE_DOWNLOAD_BYTES` in `config/buffer-limits.ts`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited): the bodies stream, so size costs a read stream and not RSS (measured: a 600MB download moved peak RSS by ~37MB). Its predecessor was a hardcoded 50MB whose comment still said "prevent memory exhaustion" long after the `readFile()` it described was replaced by `sendFileBody()`, so all it did was refuse legitimate downloads of build artifacts, videos and archives. `/api/download` was the last route that really did buffer the whole file, and now shares `sendFileBody()` with the other two.
 

docs/security-architecture.md

@@ -546,6 +546,7 @@ A saved dashboard URL renders as a tab, served through Codeman's own origin at `
 - **The proxy is exempt from cookie auth and the Origin/CSRF guard, and that is deliberate.** The iframe is sandboxed without `allow-same-origin`, so it is opaque‑origin: its requests are cross‑site, meaning the `SameSite=lax` session cookie is never attached and its writes and WS upgrades arrive with `Origin: null`. The credential is instead a 192‑bit capability in the path, minted only by an authenticated `POST /api/webviews/:id/open`, held in memory (a restart invalidates every one), rolling TTL, bound to the minting user, and granting nothing but "relay bytes to this one saved URL". ⚠️ **The Host allowlist is NOT bypassed**, so DNS‑rebinding protection is unaffected. A second `Referer`‑keyed form exists for root‑absolute assets and is the only exemption decided by a request‑supplied header, so it is fenced to safe methods on non‑`/api`, non‑`/ws`, non‑`/q` paths. Edges pinned by `test/webview-auth-exemption.test.ts`.
 - **The lost‑frame recovery page is the third unauthenticated 200, and the only one decided by request headers alone.** The proxy's runtime shim masks `/webview/<cap>/` off the page's own URL so a single‑page app routes on the path it expects; a navigation the page then starts itself (`location.reload()`, a root‑absolute `location.href`) lands on Codeman's root with no capability anywhere, no cookie (opaque origin) and a Referer naming the masked page. `serveLostWebviewFrame()` in `middleware/auth.ts` recognises it by shape (`GET`/`HEAD`, `Sec-Fetch-Dest: iframe` or `frame`, `Accept: text/html`, `Sec-Fetch-Mode: navigate` or absent) and answers, BEFORE the credential checks and without counting an auth failure, with a static page whose only content is a `postMessage` of the lost path to the parent tab (`default-src 'none'` plus the hash of that one script, `no-store`, `referrer: no-referrer`, no reflected input). It is fenced to paths that are NOT registered routes and never `/api/`, `/ws/` or `/q/`, with one carve‑out: `/` itself, because the landing page masks to exactly `/` and its reload otherwise rendered Codeman's app shell inside the web tab. `/` is admitted only when the request carries neither the `codeman_session` cookie nor an `Authorization` header: nothing in Codeman frames its own root and a sandboxed frame has neither, while a framed `/` that does carry credentials still gets the shell. On a passwordless install no auth hook runs, so the index route applies the same test itself (`isLostWebviewRootFrame`). ⚠️ Known property, accepted rather than mitigated: those headers are trivially set by a non‑browser client, so an unauthenticated caller can distinguish a registered route (401) from a non‑route (200) and enumerate the route table; the routes are public in `docs/api-reference.md`, so nothing is learned. Pinned by `test/webview-auth-exemption.test.ts` (password) and `test/webview-lost-root-frame.test.ts` (passwordless).
 - **Sandboxed by default; `allow-same-origin` is an explicit per‑dashboard opt‑in.** A proxied page is same‑origin with Codeman, so without the sandbox its JavaScript could read the Codeman document and call the agent‑spawning API. ⚠️ In BOTH modes the `Authorization` header and the `codeman_session` cookie are stripped before the upstream request, because a trusted (same‑origin) frame makes the browser attach Codeman's own Basic‑auth credentials to every proxied request; forwarding them would hand `CODEMAN_PASSWORD` to the dashboard.
+- **Rendered HTML files (`/html-view/<capability>/`) are the other capability-gated route that skips cookie auth.** A clicked `.html` file renders through it so an agent's report can be viewed from any device. The exemption is narrower than the proxy's: `GET`/`HEAD` only (plus the page's CORS preflight, which `registerSecurityHeaders` answers itself with `Access-Control-Allow-Methods: GET, HEAD` and never hands to a route), the capability in the path only (no `Referer` form), and it is a separate store, so a web-tab capability never opens a page and vice versa. The capability is minted by an authenticated `POST /api/sessions/:id/html-view` (session ownership via `findSessionOrFail`, the attachment guard for out-of-workspace files), held in memory with a rolling TTL and revoked with the web-tab ones on logout, admin logout and user deletion. Every response carries `Content-Security-Policy: sandbox` without `allow-same-origin`, so the page is opaque-origin even when opened as a top-level tab and cannot read Codeman's document, cookies or API. **Network access is open, by the owner's decision (2026-10-13):** that `sandbox` directive is the whole policy (it replaces Codeman's own `default-src 'self'` CSP and carries no fetch directive), so a rendered page behaves like a file opened from disk in a browser. What a page CAN do: load scripts, styles, fonts, images and media from any host (an agent's dashboard pulling Chart.js from a CDN), make fetch, XHR, WebSocket, beacon and form requests to any host, and read the files of its own folder through its capability. What it CANNOT do: act as Codeman's origin, read Codeman's cookies or document, use Codeman's API (a write arrives with `Origin: null` and the Origin guard refuses it; a read's response stays unreadable, because Codeman answers CORS only for its own localhost origins, and with a password set the request carries no session cookie either), or read any folder other than its own. The accepted consequence is that a page can send what it can read, its own folder, to any host, which is why the folder rules below are the boundary that matters. `Referrer-Policy: no-referrer` keeps the capability URL out of the `Referer` the page's third-party requests carry. Pinned by the exact-header test in `test/routes/html-view-routes.test.ts`. It may read its own directory tree (non-dot, asset-allowlisted, realpath-confined, blocklist applied; the dot and extension rules hold for the symlink-resolved target as well as the requested name), so minting is refused for an HTML file in a hidden directory or directly in a broad root (`/`, home, `/tmp`, `/var/tmp` and `$TMPDIR`, the cases and user-space roots, a drive's mount point) or in a directory above one (`/home`, `/Users`). Pinned by `test/routes/html-view-routes.test.ts` and the html-view block in `test/webview-auth-exemption.test.ts`.
 - **Not an open relay, and not a privilege boundary.** `resolveUpstreamUrl()` refuses anything leaving the saved origin, and cross‑origin redirects are handed back unchanged rather than followed. The proxy does reach whatever the SERVER can reach, which is not an escalation for someone who already commands `--dangerously-skip-permissions` agents, but in multi‑user mode it means a non‑admin's dashboard is fetched from the server's network position. Saved URLs are validated to plain http(s) with no embedded credentials, and there is deliberately **no magic‑link path**: terminal output can never create a webview (the mistake the attachment scanner had to be walled off from). The one refused destination class is link‑local and cloud‑metadata addresses (`169.254.0.0/16`, `fe80::/10`, `fd00:ec2::254`, `168.63.129.16`, `100.100.100.200`, `metadata.google.internal`): `webview-egress-policy.ts` refuses them at save time, and `webview-egress.ts` re‑judges the RESOLVED address at connect time through a `lookup` hook on the proxy's undici Agent and on its WebSocket client, so a DNS name pointing into those ranges is refused as well. Loopback and RFC1918 stay allowed on purpose. Capabilities are revoked on logout, admin logout and user deletion, and proxied responses carry `Referrer-Policy: same-origin` so a dashboard cannot hand the capability‑bearing URL to a third‑party host it links.
 
 ---

docs/wiki/Mobile-Guide.md

@@ -128,8 +128,9 @@ already writing in the editor.
 - **Tap a link** in terminal output and it opens in a new tab. Same for a link in an agent's
   answer in the response viewer — it opens a tab rather than navigating the dashboard away,
   which on a phone would unload the whole session view.
-- **Tap a file path** an agent printed and the file-preview overlay opens; a log path opens the
-  log viewer. Works in scrolled-up transcript too.
+- **Tap a file path** an agent printed and the file-preview overlay opens (Markdown rendered,
+  HTML as a page); a log or other plain-text path opens the log viewer. Works in scrolled-up
+  transcript too.
 - A tap on the prose *beside* a link still places the cursor as usual, and a tap on a dialog's
   numbered choice still answers the dialog even when the row contains a path — the dialog wins,
   because on a phone it is the only interaction that matters.

docs/wiki/Working-With-Files.md

@@ -87,9 +87,10 @@ File paths in a session are links. That works in two places:
   render as underlined monospace links.
 
 Clicking one opens it in the preview: images and PDFs render, video and audio play with a
-working scrub bar, documents convert, text shows inline and Markdown renders. The exception is
-a text or Markdown file inside the workspace clicked in the terminal: that opens in the tail
-viewer instead, which follows a file that is still being written.
+working scrub bar, documents convert, text shows inline, Markdown renders and HTML opens as a
+page. The exception is a plain text file (a log, `.txt`, `.json`, code) inside the workspace
+clicked in the terminal: that opens in the tail viewer instead, which follows a file that is
+still being written. A Markdown file always opens rendered, wherever you click it.
 
 Paths **outside** the session's workspace work too, which matters because that is where most
 of an agent's output lands: a screenshot in `/tmp`, a capture in its own scratchpad, a file in
@@ -101,8 +102,24 @@ Outside the workspace the allowlist is images, video, audio, PDF, Office documen
 files, where "text" is the same list the viewer will let you edit: code, config, logs, csv,
 markdown. The reasoning is that a session can already `cat` any of those, so the file suffix
 was never what kept anything secret; the path guard is. Types outside the list (`.svg`,
-`.bmp`) say so rather than failing silently, and `.html` previews as source rather than being
-rendered, so nothing served this way can execute in the page.
+`.bmp`) say so rather than failing silently.
+
+An `.html` file opens as a rendered page by default, with its relative CSS, scripts, images and
+data files. The page is served from a separate `/html-view/...` address in a sandbox with no
+origin of its own, so its scripts can never read Codeman's page, cookies or API.
+
+By the project owner's decision, a rendered page has the same network access as a file you open
+from disk in your browser. It **can** load scripts, styles, fonts, images and media from
+anywhere on the internet (a dashboard that pulls Chart.js from a CDN works), send requests to
+any host, and read the files in its own folder. It **cannot** act as Codeman: it has no access
+to Codeman's page, cookies or API, and no access to any folder other than its own. Since a page
+can send what it can read to any host, open HTML only from sources you trust, as you would on
+your own desktop. The **Page**
+pill in the viewer header switches to the source view (where **Edit** works as for any text
+file), and the viewer falls back to source on its own when a page cannot be rendered: a remote
+(SSH) case, an HTML file inside a hidden folder, or one sitting directly in a broad folder such
+as your home folder or `/tmp` (the page may read the files in its own folder tree, so move it
+into a folder of its own). The raw file routes still serve HTML as a download only.
 
 Text previews are capped at the first 500 lines, fetched as a partial read, so clicking a
 one-gigabyte log does not try to paint one.

src/html-view-capabilities.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Capability tokens for rendering a local HTML file.
+ *
+ * `file-raw` never serves HTML as HTML: a page rendered from Codeman's own origin
+ * could read the Codeman document and drive the agent-spawning API. So an HTML
+ * file is rendered from `/html-view/:cap/*` instead, with a `Content-Security-
+ * Policy: sandbox` header that puts the document in an OPAQUE origin no matter how
+ * it is opened (iframe or top-level tab). That opaque origin is also why the route
+ * cannot authenticate on the session cookie: its subresource requests are
+ * cross-site, so the `SameSite=lax` cookie is never attached (the same reason the
+ * web-tab proxy uses capabilities, see webview-capabilities.ts).
+ *
+ * A capability is minted by an authenticated `POST /api/sessions/:id/html-view` and
+ * grants exactly one thing: GET access to the files in ONE directory (the HTML
+ * file's own), so a page's relative `style.css` / `chart.js` / images resolve.
+ *
+ * - 192 bits of `randomBytes` entropy, base64url.
+ * - Held in memory only. A restart invalidates every outstanding capability.
+ * - Rolling TTL, revoked on logout, admin logout and user deletion (`revokeOwner`).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { StaleExpirationMap } from './utils/index.js';
+import { MAX_WEBVIEW_CAPABILITIES, WEBVIEW_CAPABILITY_TTL_MS } from './config/webview-limits.js';
+
+/** URL prefix the rendered files are served under. */
+export const HTML_VIEW_PREFIX = '/html-view';
+
+export interface HtmlViewCapabilityRecord {
+  /** Realpath of the directory the capability serves. */
+  rootDir: string;
+  /** Username that minted it (multi-user); undefined in single-user mode. */
+  owner?: string;
+  /**
+   * Whether the directory lies outside the minting session's workspace (admitted
+   * under the attachment guard). Recorded so the serving route can refuse it the
+   * moment workspace confinement is switched on, as the attachment routes do.
+   */
+  outsideWorkspace: boolean;
+  createdAt: number;
+}
+
+export class HtmlViewCapabilityStore {
+  private readonly capabilities: StaleExpirationMap<string, HtmlViewCapabilityRecord>;
+  /** Reverse index so re-opening a page reuses its capability instead of leaking one per click. */
+  private readonly byRoot = new Map<string, string>();
+
+  constructor(ttlMs: number = WEBVIEW_CAPABILITY_TTL_MS) {
+    this.capabilities = new StaleExpirationMap<string, HtmlViewCapabilityRecord>({
+      ttlMs,
+      refreshOnGet: true,
+      onExpire: (token, record) => {
+        const key = rootKey(record.rootDir, record.owner, record.outsideWorkspace);
+        if (this.byRoot.get(key) === token) this.byRoot.delete(key);
+      },
+    });
+  }
+
+  /** Mint (or reuse) a capability for a directory. Returns the token. */
+  mint(rootDir: string, owner?: string, outsideWorkspace = false): string {
+    // The flag is part of the key: an out-of-workspace mint must never reuse a
+    // capability recorded as in-workspace, which confinement would not stop.
+    const key = rootKey(rootDir, owner, outsideWorkspace);
+    const existing = this.byRoot.get(key);
+    if (existing && this.capabilities.get(existing)) return existing;
+    if (existing) this.byRoot.delete(key);
+
+    if (this.capabilities.size >= MAX_WEBVIEW_CAPABILITIES) this.capabilities.cleanup();
+
+    const token = randomBytes(24).toString('base64url');
+    this.capabilities.set(token, { rootDir, owner, outsideWorkspace, createdAt: Date.now() });
+    this.byRoot.set(key, token);
+    return token;
+  }
+
+  /** Resolve a capability, refreshing its TTL. Returns undefined when unknown or expired. */
+  resolve(token: string): HtmlViewCapabilityRecord | undefined {
+    if (!token) return undefined;
+    return this.capabilities.get(token);
+  }
+
+  /** Revoke every capability bound to an identity (logout, admin logout, user deletion). */
+  revokeOwner(owner: string | undefined): number {
+    let revoked = 0;
+    for (const [key, token] of [...this.byRoot]) {
+      const record = this.capabilities.peek(token);
+      if (!record || record.owner === owner) {
+        this.capabilities.delete(token);
+        this.byRoot.delete(key);
+        if (record) revoked++;
+      }
+    }
+    return revoked;
+  }
+
+  get size(): number {
+    return this.capabilities.size;
+  }
+
+  dispose(): void {
+    this.capabilities.dispose();
+    this.byRoot.clear();
+  }
+}
+
+function rootKey(rootDir: string, owner: string | undefined, outsideWorkspace: boolean): string {
+  return `${owner ?? ''}\0${outsideWorkspace ? 'out' : 'in'}\0${rootDir}`;
+}
+
+/** The capability token in an `/html-view/<cap>/...` path, or null. */
+export function capabilityFromHtmlViewPath(pathname: string): string | null {
+  if (typeof pathname !== 'string') return null;
+  const prefix = `${HTML_VIEW_PREFIX}/`;
+  if (!pathname.startsWith(prefix)) return null;
+  const rest = pathname.slice(prefix.length);
+  const slash = rest.indexOf('/');
+  const cap = slash === -1 ? rest : rest.slice(0, slash);
+  return /^[A-Za-z0-9_-]{16,128}$/.test(cap) ? cap : null;
+}
+
+/** Process-wide store, shared by the routes and the auth middleware (see webviewCapabilities). */
+export const htmlViewCapabilities = new HtmlViewCapabilityStore();

src/web/middleware/auth.ts

@@ -23,6 +23,7 @@ import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { findUser, setPassword, touchLastLogin, verifyPassword } from '../../user-store.js';
 import { webviewCapabilities } from '../../webview-capabilities.js';
+import { capabilityFromHtmlViewPath, htmlViewCapabilities } from '../../html-view-capabilities.js';
 import {
   capabilityFromProxyPath,
   capabilityFromReferer,
@@ -183,6 +184,20 @@ function hasValidWebviewCapability(req: FastifyRequest, basePath = ''): boolean
   return !!fromReferer && webviewCapabilities.resolve(fromReferer) !== undefined;
 }
 
+/**
+ * Whether a request is a GET for a rendered HTML file (`/html-view/<cap>/...`) with
+ * a live capability. Same reasoning as the web-tab proxy: the page is sandboxed into
+ * an opaque origin, so its asset requests carry no session cookie. Read-only by
+ * construction (safe methods only), and the Host allowlist still applies. OPTIONS
+ * is the page's CORS preflight, which registerSecurityHeaders answers itself and
+ * never hands to a route.
+ */
+function hasValidHtmlViewCapability(req: FastifyRequest): boolean {
+  if (req.method !== 'GET' && req.method !== 'HEAD' && req.method !== 'OPTIONS') return false;
+  const cap = capabilityFromHtmlViewPath((req.url ?? '').split('?')[0]);
+  return !!cap && htmlViewCapabilities.resolve(cap) !== undefined;
+}
+
 /**
  * A web-tab frame that navigated itself off the proxy prefix (see
  * isLostWebviewFrameNavigation). It cannot authenticate: opaque origin, no cookie,
@@ -368,6 +383,11 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean, bas
       done();
       return;
     }
+    // Rendered HTML file, likewise authenticated by its capability.
+    if (hasValidHtmlViewCapability(req)) {
+      done();
+      return;
+    }
     // A web-tab frame that lost its prefix: hand it back to its tab, no credentials involved.
     if (serveLostWebviewFrame(req, reply)) return;
 
@@ -507,6 +527,8 @@ function registerMultiUserAuthHook(
     // ownership against the identity BOUND TO THE CAPABILITY, which is stricter
     // than re-deriving it from a request that carries no credentials.
     if (hasValidWebviewCapability(req, basePath)) return;
+    // Rendered HTML file, likewise authenticated by its capability.
+    if (hasValidHtmlViewCapability(req)) return;
     // A web-tab frame that lost its prefix: hand it back to its tab, no credentials involved.
     if (serveLostWebviewFrame(req, reply)) return;
 
@@ -711,6 +733,16 @@ export function registerSecurityHeaders(app: FastifyInstance, https: boolean, ba
     // are not CORS-checked). Falling through lets the proxy route reply with the
     // right headers.
     if (req.method === 'OPTIONS' && !hasValidWebviewCapability(req, basePath)) {
+      // A rendered HTML page (`/html-view/<cap>/...`) is opaque-origin for the same
+      // reason, so a fetch() of its own `data.json` with a non-safelisted header
+      // preflights with `Origin: null`. Answer it here, read-only: the route serves
+      // GET and HEAD only, and no credentials are involved (`*` is valid for both).
+      if (hasValidHtmlViewCapability(req)) {
+        reply.header('Access-Control-Allow-Origin', '*');
+        reply.header('Access-Control-Allow-Methods', 'GET, HEAD');
+        reply.header('Access-Control-Allow-Headers', '*');
+        reply.header('Access-Control-Max-Age', '600');
+      }
       reply.code(204).send();
       done();
       return;

src/web/public/constants.js

@@ -2047,7 +2047,7 @@ function computeRewriteScrollLine(input) {
  * a `/g` regex, so {@link absoluteFilePathPattern} mints a fresh one per call.
  */
 const FILE_PATH_LINK_PATTERN =
-  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
+  /(\/(?:home|Users|tmp|var|private|opt|mnt|srv|media|data|workspace)\/[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
 
 /** A fresh, zero-state instance of {@link FILE_PATH_LINK_PATTERN}. */
 function absoluteFilePathPattern() {
@@ -2059,13 +2059,18 @@ function absoluteFilePathPattern() {
  * points at goes to the tail/log viewer, which is the right home for a growing
  * text file and the wrong one for bytes (tailing a PNG shows binary noise).
  *
+ * Markdown is here too (owner decision 2026-10-13): an agent's `.md` is a
+ * document to read, so the preview renders it (its MD pill gives the source)
+ * instead of the log viewer streaming it as raw text. Other text (.log, .txt,
+ * .json, code) keeps the log viewer, which follows a file still being written.
+ *
  * The media entries mirror VIDEO_ATTACHMENT_EXTENSIONS/AUDIO_ATTACHMENT_EXTENSIONS
  * (src/attachment-registry.ts, the single source) — they diverged once and an
  * in-workspace `.m4a` opened as binary noise in the log viewer while the same
  * file in /tmp played fine. test/media-extension-parity.test.ts pins the sync.
  */
 const FILE_PREVIEW_EXTENSIONS = new Set(
-  ('png jpg jpeg gif webp avif bmp ico svg pdf docx pptx xlsx mp4 webm mov m4v ogv mp3 wav ogg oga m4a aac flac opus').split(' ')
+  ('png jpg jpeg gif webp avif bmp ico svg pdf docx pptx xlsx mp4 webm mov m4v ogv mp3 wav ogg oga m4a aac flac opus md markdown').split(' ')
 );
 
 /** Whether a path's extension is one {@link FILE_PREVIEW_EXTENSIONS} covers. */
@@ -2095,7 +2100,7 @@ function previewsInFileViewer(filePath) {
  * {@link findFilePathLinks}.
  */
 const RELATIVE_FILE_PATH_LINK_PATTERN =
-  /(^|[\s"'`(\[{<>=,])((?![^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*:\/\/)(?:~\/|[^\s"'`<>|;&()[\]{}=,\/~\n\x00-\x1f])[^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*\.(?:log|txt|json|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
+  /(^|[\s"'`(\[{<>=,])((?![^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*:\/\/)(?:~\/|[^\s"'`<>|;&()[\]{}=,\/~\n\x00-\x1f])[^\s"'`<>|;&()[\]{}=,\n\x00-\x1f]*\.(?:log|txt|json|markdown|md|ya?ml|csv|xml|sh|py|tsx|ts|jsx|js|mjs|cjs|css|html?|toml|ini|sql|png|jpe?g|gif|webp|avif|bmp|ico|svg|pdf|docx|pptx|xlsx|mp4|webm|mov|m4v|ogv|mp3|wav))\b/g;
 
 /** The `(?:log|txt|…)` extension group, read off the rooted pattern so it cannot drift. */
 const FILE_LINK_EXTENSION_GROUP = /\\\.(\(\?:[^()]*\))\)\\b$/.exec(FILE_PATH_LINK_PATTERN.source)[1];
@@ -2208,6 +2213,21 @@ function resolveLinkedFilePath(filePath, workingDir) {
   return `/${parts.join('/')}`;
 }
 
+/**
+ * Extensions the file preview renders as a PAGE, from the sandboxed
+ * `/html-view/<cap>/` route (src/web/routes/html-view-routes.ts, whose
+ * HTML_VIEW_EXTENSIONS this mirrors; test/file-preview-html-page.test.ts pins
+ * the two equal). The terminal sends a click on one to the preview, never to
+ * the log viewer, and the preview renders it with a Page pill back to source.
+ */
+const HTML_PAGE_EXTENSIONS = new Set(['html', 'htm']);
+
+/** Whether a path names a file the preview renders as a page ({@link HTML_PAGE_EXTENSIONS}). */
+function rendersAsPage(filePath) {
+  const ext = String(filePath || '').split('.').pop().toLowerCase();
+  return HTML_PAGE_EXTENSIONS.has(ext);
+}
+
 
 /**
  * The LOGICAL line a terminal row belongs to — the rows it spans, its text as one
@@ -3358,6 +3378,8 @@ if (typeof window !== 'undefined') {
     resolveLinkedFilePath,
     previewsInFileViewer,
     FILE_PREVIEW_EXTENSIONS,
+    rendersAsPage,
+    HTML_PAGE_EXTENSIONS,
   };
   window.CodemanTerminalLines = { terminalLogicalLine, terminalPathLine };
   window.CodemanUrlSession = { sessionIdFromFragment };

src/web/public/index.html

@@ -618,6 +618,7 @@
             <button class="btn-icon-sm" id="filePreviewNextBtn" onclick="app.stepFolderPreview(1)" title="Next file in folder (→)" aria-label="Next file in folder" hidden>&rsaquo;</button>
             <button class="btn-icon-sm" id="filePreviewFolderBtn" onclick="app.openFolderOfPreview()" title="Show folder" aria-label="Show folder" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/></svg></button>
             <button class="btn-icon-sm file-preview-pill" id="filePreviewMdBtn" onclick="app.toggleFilePreviewMd()" title="Rendered markdown" aria-label="Rendered markdown" aria-pressed="true" hidden>MD</button>
+            <button class="btn-icon-sm file-preview-pill" id="filePreviewPageBtn" onclick="app.toggleFilePreviewPage()" title="Rendered page" aria-label="Rendered page" aria-pressed="true" hidden>Page</button>
             <button class="btn-icon-sm" id="filePreviewLinesBtn" onclick="app.toggleFilePreviewLines()" title="Line numbers" aria-label="Line numbers" aria-pressed="false" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="10" y1="6" x2="21" y2="6"/><line x1="10" y1="12" x2="21" y2="12"/><line x1="10" y1="18" x2="21" y2="18"/><path d="M4 6h1v4"/><path d="M4 10h2"/><path d="M6 18H4c0-1 2-2 2-3s-1-1.5-2-1"/></svg></button>
             <button class="btn-icon-sm" id="filePreviewWrapBtn" onclick="app.toggleFilePreviewWrap()" title="Wrap lines" aria-label="Wrap lines" aria-pressed="true" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="3" y1="6" x2="21" y2="6"/><path d="M3 12h15a3 3 0 1 1 0 6h-4"/><polyline points="16 16 14 18 16 20"/><line x1="3" y1="18" x2="10" y2="18"/></svg></button>
             <button class="btn-icon-sm file-preview-edit-btn" id="filePreviewEditBtn" onclick="app.enterFilePreviewEdit()" title="Edit file" aria-label="Edit file" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5z"/></svg></button>

src/web/public/panels-ui.js

@@ -30,10 +30,11 @@ const MARKDOWN_EXTS = new Set(['md', 'markdown']);
 // would be dropped on the next save).
 const FILE_PREVIEW_PREF_KEYS = {
   mdRendered: 'codeman:filePreviewMdRendered',
+  htmlRendered: 'codeman:filePreviewHtmlRendered',
   lineNumbers: 'codeman:filePreviewLineNumbers',
   wrap: 'codeman:filePreviewWrap',
 };
-const FILE_PREVIEW_PREF_DEFAULTS = { mdRendered: true, lineNumbers: false, wrap: true };
+const FILE_PREVIEW_PREF_DEFAULTS = { mdRendered: true, htmlRendered: true, lineNumbers: false, wrap: true };
 const AWAY_DIGEST_SECTIONS = [
   ['needsAttention', 'Needs Attention'],
   ['completed', 'Completed'],
@@ -4126,6 +4127,8 @@ Object.assign(CodemanApp.prototype, {
     // Same for the text-view toggles: they act on the text this load has not
     // fetched yet, and an image or PDF has nothing for them to toggle.
     this.filePreviewText = null;
+    this.filePreviewPage = null;
+    this.filePreviewPageRefused = false;
     this._updateFilePreviewToolbar('none');
 
     // Show overlay with loading state
@@ -4136,6 +4139,27 @@ Object.assign(CodemanApp.prototype, {
 
     const ext = (filePath.split('.').pop() || '').toLowerCase();
 
+    // HTML renders as a page: the server mints a sandboxed /html-view URL for the
+    // file's directory (html-view-routes.ts), so relative CSS, scripts and images
+    // resolve, and the page runs in an opaque origin that cannot reach Codeman.
+    // The Page pill switches to the source view below (with its Edit button), and
+    // a refused mint (remote case, broad folder, hidden directory) falls through
+    // to that source view on its own.
+    if (!attachmentId && rendersAsPage(filePath) && this._filePreviewPref('htmlRendered')) {
+      const pageUrl = await this._mintHtmlViewUrl(filePath, sessionId);
+      if (pageUrl) {
+        footerEl.textContent = 'HTML';
+        this.filePreviewPage = { filePath, sessionId };
+        this.filePreviewDetachUrl = pageUrl;
+        if (detachBtn) detachBtn.hidden = false;
+        bodyEl.innerHTML = `<iframe src="${escapeHtml(pageUrl)}" title="${escapeHtml(filePath)}" sandbox="allow-scripts allow-forms allow-popups allow-modals allow-downloads"></iframe>`;
+        this._updateFilePreviewToolbar('page');
+        return;
+      }
+      // The pill would only retry a page the server just refused.
+      this.filePreviewPageRefused = true;
+    }
+
     // Out-of-workspace path: mint an attachment id up front. Every branch below
     // talks to a workspace-confined route, so without this the image/PDF ones
     // render a broken frame and the text one reports a bare "File not found"
@@ -4857,8 +4881,9 @@ Object.assign(CodemanApp.prototype, {
 
   /**
    * Show the toggles that apply to the current view: MD for a markdown file in
-   * either view, Lines/Wrap for the plain-text view only; `'none'` (loading,
-   * image, media, PDF, edit mode) hides all three.
+   * either view, Page for an HTML file in either view (`'page'` = rendered),
+   * Lines/Wrap for the plain-text view only; `'none'` (loading, image, media,
+   * PDF, edit mode) hides them all.
    */
   _updateFilePreviewToolbar(view) {
     const set = (id, shown, pressed) => {
@@ -4869,10 +4894,42 @@ Object.assign(CodemanApp.prototype, {
     };
     const isMarkdown = view !== 'none' && MARKDOWN_EXTS.has(this.filePreviewText?.ext || '');
     set('filePreviewMdBtn', isMarkdown, view === 'markdown');
+    // Page: shown on a rendered HTML page, and on its source view when that view
+    // can be re-rendered (a bare attachment-card name has no path to mint from).
+    const text = this.filePreviewText;
+    const htmlSource =
+      view === 'text' &&
+      !this.filePreviewPageRefused &&
+      rendersAsPage(text?.filePath) &&
+      (!text.attachmentId || text.filePath.startsWith('/'));
+    set('filePreviewPageBtn', view === 'page' || htmlSource, view === 'page');
     set('filePreviewLinesBtn', view === 'text', this._filePreviewPref('lineNumbers'));
     set('filePreviewWrapBtn', view === 'text', this._filePreviewPref('wrap'));
   },
 
+  /** Mint the sandboxed page URL for an HTML file; null when the server refuses. */
+  async _mintHtmlViewUrl(filePath, sessionId) {
+    try {
+      const res = await fetch(`/api/sessions/${sessionId}/html-view`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ path: filePath }),
+      });
+      const result = await res.json().catch(() => ({}));
+      return res.ok && result.success ? CodemanBase.url(result.data.url) : null;
+    } catch {
+      return null;
+    }
+  },
+
+  /** Page pill: flip between the rendered page and the source view of an HTML file. */
+  toggleFilePreviewPage() {
+    const target = this.filePreviewPage || this.filePreviewText;
+    if (!target) return;
+    this._setFilePreviewPref('htmlRendered', !this._filePreviewPref('htmlRendered'));
+    return this.openFilePreview(target.filePath, target.sessionId);
+  },
+
   toggleFilePreviewMd() {
     this._setFilePreviewPref('mdRendered', !this._filePreviewPref('mdRendered'));
     this._renderFilePreviewText();

src/web/public/sw.js

@@ -101,6 +101,10 @@ self.addEventListener('fetch', (event) => {
   if (request.headers.get('upgrade') === 'websocket') return;
   if (request.headers.get('accept') === 'text/event-stream') return;
   if (request.url.includes('/api/')) return;
+  // A rendered HTML page is served `no-store` behind a capability that logout
+  // revokes; caching a popped-out page here would let the offline fallback
+  // serve it after the capability is gone.
+  if (request.url.includes('/html-view/')) return;
 
   event.respondWith(
     fetch(request)

src/web/public/terminal-ui.js

@@ -2224,7 +2224,13 @@ Object.assign(CodemanApp.prototype, {
                 self.openFolderGrid(target, sessionId);
                 return;
               }
-              if (previewsInFileViewer(target) || self._isExternalPreviewPath(target, sessionId)) {
+              // An HTML file renders as a page in the preview, never as source
+              // in the log viewer (markdown is in FILE_PREVIEW_EXTENSIONS).
+              if (
+                previewsInFileViewer(target) ||
+                rendersAsPage(target) ||
+                self._isExternalPreviewPath(target, sessionId)
+              ) {
                 self.openFilePreview(target, sessionId);
                 return;
               }

src/web/routes/admin-routes.ts

@@ -36,6 +36,7 @@ import {
 } from '../../user-store.js';
 import { getAuthUser, requireAdmin, revokeUserSessions } from '../route-helpers.js';
 import { webviewCapabilities } from '../../webview-capabilities.js';
+import { htmlViewCapabilities } from '../../html-view-capabilities.js';
 import { appendAdminAudit } from '../admin-audit.js';
 import { SseEvent } from '../sse-events.js';
 import type { AuthPort } from '../ports/auth-port.js';
@@ -183,7 +184,8 @@ export function registerAdminRoutes(app: FastifyInstance, ctx: SessionPort & Aut
     // Web-tab proxy capabilities are a second credential the cookie purge does not
     // touch; a forced logout that left them alive would not be a logout.
     const revokedWebviews = webviewCapabilities.revokeOwner(normalizeUsername(username));
-    audit(req, 'user.logout', username, { revoked, revokedWebviews });
+    const revokedHtmlViews = htmlViewCapabilities.revokeOwner(normalizeUsername(username));
+    audit(req, 'user.logout', username, { revoked, revokedWebviews, revokedHtmlViews });
     return { success: true, data: { revoked } };
   });
 
@@ -206,6 +208,7 @@ export function registerAdminRoutes(app: FastifyInstance, ctx: SessionPort & Aut
       }
       revokeUserSessions(ctx.authSessions, username);
       webviewCapabilities.revokeOwner(normalizeUsername(username));
+      htmlViewCapabilities.revokeOwner(normalizeUsername(username));
       if (deleteSpace) await deleteUserSpace(username);
       audit(req, 'user.delete', username, { deleteSpace, killedSessions: owned.length });
       ctx.broadcast(SseEvent.AdminUsersChanged, {});

src/web/routes/file-routes.ts

@@ -210,8 +210,8 @@ interface FileBodySource {
   cleanup?: () => void;
 }
 
-/** Byte source for a LOCAL file (the historical, only path). */
-function localFileSource(resolvedPath: string) {
+/** Byte source for a LOCAL file (the historical, only path). Shared with html-view-routes.ts. */
+export function localFileSource(resolvedPath: string) {
   return (range?: { start: number; end: number }): FileBodySource => ({
     content: createReadStream(resolvedPath, range ? { start: range.start, end: range.end } : undefined),
   });
@@ -231,8 +231,11 @@ function localFileSource(resolvedPath: string) {
  * `open` supplies the bytes for the (optional) range, which is what lets a remote
  * case reuse this instead of re-implementing the 206/416 contract: same headers,
  * same status codes, whether the file sits on this host or behind an ssh pipe.
+ *
+ * Exported for the rendered-HTML route (html-view-routes.ts), so a page's own
+ * `<video>`/`<audio>` can seek as well.
  */
-function sendFileBody(
+export function sendFileBody(
   reply: FastifyReply,
   size: number,
   rangeHeader: string | string[] | undefined,
@@ -281,7 +284,9 @@ async function serveRawFile(
   // would be stored XSS. SVG was always here; HTML/HTM join it now that the text
   // family is servable, so widening what can be READ never widened what can RUN.
   // The preview overlay reads these through `fetch()`, which ignores the
-  // disposition, so a clicked .html still shows its source.
+  // disposition, so the source view of a clicked .html still works. Rendering it
+  // as a page is html-view-routes.ts's job (sandboxed, opaque origin), never this
+  // route's.
   const markupOnly = extension === 'svg' || extension === 'html' || extension === 'htm';
   if (download || markupOnly) {
     reply.header(

src/web/routes/html-view-routes.ts

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview Render a local HTML file (an agent's report, a generated page) as a
+ * page instead of as source text.
+ *
+ * Routes:
+ * - `POST /api/sessions/:id/html-view` (authenticated) — `{ path }` of an `.html` file;
+ *   returns `{ url }`, an `/html-view/<cap>/<file>` URL for that file.
+ * - `GET /html-view/:cap/*` (capability) — the HTML file and its sibling assets.
+ *
+ * ⚠️ Every response carries `Content-Security-Policy: sandbox ...` WITHOUT
+ * `allow-same-origin`, so the page runs in an opaque origin whether it is framed or
+ * opened as a top-level tab: it can run its own scripts but cannot read the Codeman
+ * document, its cookies or its API. That is what makes rendering safe at all; see
+ * html-view-capabilities.ts for why the route authenticates on a capability.
+ * Network access is deliberately OPEN (owner decision, see {@link HTML_VIEW_CSP}).
+ *
+ * Path policy: the HTML file itself is admitted like the file preview admits a file
+ * (inside the session workspace, or outside it under the attachment guard), and the
+ * capability then serves ONLY the files in that file's own directory tree, filtered
+ * by the same blocklist plus an asset-extension allowlist and a no-dotfile rule, so
+ * a page cannot use its own directory to pull a `.env` out through the browser.
+ * Because that tree is served recursively, minting is refused for an HTML file in a
+ * hidden directory or directly in a broad root (`/`, home, `/tmp`, `/var/tmp` and
+ * `$TMPDIR`, the cases and user-space roots, a drive's mount point) or in a
+ * directory above one, see {@link isBroadHtmlViewRoot}.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { ApiErrorCode, createErrorResponse } from '../../types.js';
+import { isBlockedAttachmentPath, isUnderTree, loadAttachmentGuardConfig } from '../../config/attachment-guard.js';
+import { HTML_VIEW_PREFIX, htmlViewCapabilities } from '../../html-view-capabilities.js';
+import { CASES_DIR, findSessionOrFail, ownerFor, parseBody, validateSessionFilePath } from '../route-helpers.js';
+import { HtmlViewOpenSchema } from '../schemas.js';
+import { localFileSource, sendFileBody } from './file-routes.js';
+import { getUserSpacesDir } from '../../config/multiuser.js';
+import { exceedsDownloadLimit } from '../../config/buffer-limits.js';
+import type { SessionPort } from '../ports/index.js';
+
+/** Extensions that open as a rendered page. */
+export const HTML_VIEW_EXTENSIONS: ReadonlySet<string> = new Set(['html', 'htm']);
+
+/** What a rendered page may load from its own directory, with the type it is served as. */
+const ASSET_TYPES: Record<string, string> = {
+  html: 'text/html; charset=utf-8',
+  htm: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  map: 'application/json; charset=utf-8',
+  txt: 'text/plain; charset=utf-8',
+  csv: 'text/csv; charset=utf-8',
+  md: 'text/plain; charset=utf-8',
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  ico: 'image/x-icon',
+  bmp: 'image/bmp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  wasm: 'application/wasm',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  pdf: 'application/pdf',
+};
+
+/**
+ * The whole Content-Security-Policy every response is served under: the `sandbox`
+ * directive and nothing else. It REPLACES Codeman's own policy (`default-src 'self'`
+ * and the rest, set earlier by registerSecurityHeaders). No `allow-same-origin`:
+ * that one token is the difference between "a page" and "a page that can drive
+ * Codeman".
+ *
+ * ⚠️ Network access is OPEN, by the owner's decision (2026-10-13, #547): a rendered
+ * page behaves like a file opened from disk in a browser, so there is deliberately
+ * no fetch directive (`default-src`, `script-src`, `connect-src`, ...). It loads
+ * scripts, styles, fonts, images and media from anywhere (an agent's dashboard
+ * pulling Chart.js from a CDN) and may fetch, XHR, open WebSockets, send beacons and
+ * post forms anywhere. What confines it is the opaque origin (no Codeman cookies, no
+ * Codeman API) and the capability serving only its own folder. Do not add a fetch
+ * directive, or `allow-same-origin`, without the owner. test/routes/html-view-routes.test.ts
+ * pins the exact value.
+ */
+export const HTML_VIEW_CSP = 'sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads';
+
+function extensionOf(path: string): string {
+  return extname(path).toLowerCase().replace(/^\./, '');
+}
+
+/** realpath when the path exists, else the plain resolved path. */
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/**
+ * The shared temp dirs, named literally: `os.tmpdir()` is `$TMPDIR` whenever that
+ * is set, and macOS sets it in every terminal session (`/var/folders/.../T`), so
+ * a server started from one would otherwise never see `/tmp` as broad.
+ */
+const SHARED_TEMP_DIRS = ['/tmp', '/var/tmp'];
+
+/**
+ * Where drives are mounted. A page at a drive's root (WSL's `/mnt/d/report.html`)
+ * would be handed the whole drive, so the mount parent and each mount point in it
+ * count as broad.
+ */
+const MOUNT_PARENTS = ['/mnt', '/media', '/Volumes'];
+
+/**
+ * Whether a directory is too broad to hand to a page as its asset root. The
+ * capability serves the HTML file's directory RECURSIVELY to the page's own
+ * scripts, so `/tmp/report.html` would expose every other session's scratch
+ * output under `/tmp`, and `~/report.html` the home tree. Refuse those roots
+ * (and the cases / user-space roots, which hold every workspace) outright, and
+ * any directory ABOVE one of them (`/home`, `/Users`, macOS's `/private`), since
+ * serving it recursively serves the root below it too.
+ */
+export function isBroadHtmlViewRoot(dir: string): boolean {
+  const target = canonical(dir);
+  const userSpaces = canonical(getUserSpacesDir());
+  // canonical() also maps the literal temp dirs to macOS's `/private/tmp` and `/private/var/tmp`.
+  const broad = [sep, homedir(), tmpdir(), ...SHARED_TEMP_DIRS, CASES_DIR, userSpaces].map(canonical);
+  if (broad.some((root) => isUnderTree(root, target))) return true;
+  for (const parent of MOUNT_PARENTS.map(canonical)) {
+    if (target === parent || dirname(target) === parent) return true;
+  }
+  // A user's own space (`<spaces>/<user>`) and its cases dir hold every workspace of that user.
+  if (dirname(target) === userSpaces) return true;
+  return basename(target) === 'cases' && dirname(dirname(target)) === userSpaces;
+}
+
+export function registerHtmlViewRoutes(app: FastifyInstance, ctx: SessionPort): void {
+  app.post('/api/sessions/:id/html-view', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const session = findSessionOrFail(ctx, id, req);
+    const body = parseBody(HtmlViewOpenSchema, req.body ?? {});
+    if (session.remote) {
+      reply
+        .code(400)
+        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'HTML pages in a remote (SSH) case cannot be rendered'));
+      return;
+    }
+    if (!HTML_VIEW_EXTENSIONS.has(extensionOf(body.path))) {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Not an HTML file'));
+      return;
+    }
+
+    // Inside the workspace: the same check every file route uses. Outside it: the
+    // attachment guard, exactly as an external file preview is admitted.
+    let resolvedPath: string;
+    const inWorkspace = validateSessionFilePath(session.workingDir, body.path);
+    if (inWorkspace) {
+      resolvedPath = inWorkspace.resolvedPath;
+    } else {
+      if (!isAbsolute(body.path)) {
+        reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
+        return;
+      }
+      try {
+        resolvedPath = await fs.realpath(body.path);
+      } catch {
+        reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
+        return;
+      }
+      const guard = await loadAttachmentGuardConfig();
+      if (guard.confineToWorkspace || isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)) {
+        reply.code(403).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Access to this file is blocked'));
+        return;
+      }
+    }
+
+    const stat = await fs.stat(resolvedPath).catch(() => null);
+    if (!stat?.isFile()) {
+      reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
+      return;
+    }
+    // The page URL names the RESOLVED file, so it has to be HTML too: a
+    // `report.html -> notes.txt` link would otherwise mint a page for a text file.
+    if (!HTML_VIEW_EXTENSIONS.has(extensionOf(resolvedPath))) {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Not an HTML file'));
+      return;
+    }
+
+    // The serving route never descends into a dot segment below the capability
+    // root; the HTML file's own path gets the same rule, or `.cache/r.html` would
+    // mint a capability over a hidden directory and serve its `token.json`. Inside
+    // the workspace the rule covers the part below the workspace root, which is
+    // all the page's tree can reach, so a workspace that itself lives under a
+    // hidden folder (`~/.local/src/app`) can still render its pages.
+    const checkedPath = inWorkspace ? inWorkspace.relativePath : resolvedPath;
+    if (checkedPath.split(sep).some((segment) => segment.startsWith('.'))) {
+      reply
+        .code(403)
+        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'HTML files in hidden directories cannot be rendered'));
+      return;
+    }
+    if (isBroadHtmlViewRoot(dirname(resolvedPath))) {
+      reply
+        .code(403)
+        .send(
+          createErrorResponse(
+            ApiErrorCode.INVALID_INPUT,
+            'This folder is too broad to render a page from; move the HTML file into its own folder'
+          )
+        );
+      return;
+    }
+
+    const cap = htmlViewCapabilities.mint(dirname(resolvedPath), ownerFor(req), !inWorkspace);
+    return {
+      success: true,
+      data: { url: `${HTML_VIEW_PREFIX}/${cap}/${encodeURIComponent(basename(resolvedPath))}` },
+    };
+  });
+
+  app.get(`${HTML_VIEW_PREFIX}/:cap/*`, async (req, reply) => {
+    const { cap, '*': rest } = req.params as { cap: string; '*': string };
+    const record = htmlViewCapabilities.resolve(cap);
+    const notFound = () => reply.code(404).header('Content-Type', 'text/plain; charset=utf-8').send('Not found');
+    if (!record) return notFound();
+
+    // Fastify has already percent-decoded the wildcard. Hidden files and
+    // directories are never served, whatever their extension. This is the cheap
+    // reject on the requested name; the same two rules run again on the resolved
+    // path below.
+    const segments = (rest || '').split('/').filter(Boolean);
+    if (segments.length === 0 || segments.some((s) => s.startsWith('.'))) return notFound();
+    if (!ASSET_TYPES[extensionOf(segments[segments.length - 1])]) return notFound();
+
+    let resolvedPath: string;
+    try {
+      resolvedPath = await fs.realpath(resolve(record.rootDir, segments.join(sep)));
+    } catch {
+      return notFound();
+    }
+    // Symlinks are resolved above, so this is the real containment check, and the
+    // dot and extension rules have to hold for where a link LANDS as well: a
+    // `cfg.json -> .git/config` inside the page's folder passes both on its own name.
+    if (!isUnderTree(resolvedPath, record.rootDir)) return notFound();
+    const landed = relative(record.rootDir, resolvedPath).split(sep);
+    if (landed.some((s) => s.startsWith('.'))) return notFound();
+    // Typed by what the bytes are, the resolved name.
+    const contentType = ASSET_TYPES[extensionOf(resolvedPath)];
+    if (!contentType) return notFound();
+    const guard = await loadAttachmentGuardConfig();
+    if (isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)) return notFound();
+    // Re-checked per request, like the attachment serve path (file-routes.ts): a
+    // page minted from outside the workspace before an admin switched confinement
+    // on stops serving once it is on, instead of living out its capability.
+    if (record.outsideWorkspace && guard.confineToWorkspace) return notFound();
+
+    const stat = await fs.stat(resolvedPath).catch(() => null);
+    if (!stat?.isFile() || exceedsDownloadLimit(stat.size)) return notFound();
+
+    reply.header('Content-Security-Policy', HTML_VIEW_CSP);
+    reply.header('Content-Type', contentType);
+    reply.header('Cache-Control', 'no-store');
+    reply.header('Referrer-Policy', 'no-referrer');
+    // The sandboxed page is opaque-origin, so even its fetch() of a sibling
+    // `data.json` is CORS-checked with `Origin: null`. `*` without credentials is
+    // enough, and widens nothing: these bytes are already readable by anyone
+    // holding the capability URL.
+    reply.header('Access-Control-Allow-Origin', '*');
+    // The file routes' body sender: Content-Length, and `Range` answered with 206
+    // (or 416), so a page's own <video>/<audio> can seek. It hijacks the reply, and
+    // carries every header set above across to it.
+    sendFileBody(reply, stat.size, req.headers.range, localFileSource(resolvedPath));
+    return reply;
+  });
+}

src/web/routes/index.ts

@@ -6,6 +6,7 @@ export { registerPushRoutes } from './push-routes.js';
 export { registerTeamRoutes } from './team-routes.js';
 export { registerMuxRoutes } from './mux-routes.js';
 export { registerFileRoutes } from './file-routes.js';
+export { registerHtmlViewRoutes } from './html-view-routes.js';
 export { registerScheduledRoutes } from './scheduled-routes.js';
 export { registerCronRoutes } from './cron-routes.js';
 export { registerSystemRoutes } from './system-routes.js';

src/web/routes/session-routes.ts

@@ -42,6 +42,7 @@ import {
 import type { PaneCaptureOptions } from '../../mux-interface.js';
 import { SseEvent } from '../sse-events.js';
 import { webviewCapabilities } from '../../webview-capabilities.js';
+import { htmlViewCapabilities } from '../../html-view-capabilities.js';
 import {
   CreateSessionSchema,
   SessionNameSchema,
@@ -996,6 +997,7 @@ export function registerSessionRoutes(
     // logout has to retire them too or every dashboard URL opened during this
     // login keeps relaying without one (WebviewCapabilityStore.revokeOwner).
     webviewCapabilities.revokeOwner(ownerFor(req));
+    htmlViewCapabilities.revokeOwner(ownerFor(req));
     reply.clearCookie(AUTH_COOKIE_NAME, { path: '/' });
     return {};
   });

src/web/schemas.ts

@@ -127,6 +127,24 @@ export const FileWriteSchema = z
   })
   .strict();
 
+/**
+ * Body validation for `POST /api/sessions/:id/html-view` (render a local HTML file
+ * as a sandboxed page). `path` is absolute or relative to the session workspace;
+ * the extension, containment, guard and broad-root checks are the route's
+ * (html-view-routes.ts), after parsing.
+ */
+export const HtmlViewOpenSchema = z
+  .object({
+    path: z
+      .string({ error: 'Missing path parameter' })
+      .min(1, 'Missing path parameter')
+      .max(4096)
+      .refine((p) => !p.includes('\0') && !p.includes('\n') && !p.includes('\r'), {
+        message: 'Invalid path',
+      }),
+  })
+  .strict();
+
 /**
  * The run-mode ids the API currently accepts: every ENABLED registry entry.
  *

src/web/server.ts

@@ -181,6 +181,7 @@ import {
   registerTeamRoutes,
   registerMuxRoutes,
   registerFileRoutes,
+  registerHtmlViewRoutes,
   registerScheduledRoutes,
   registerHookEventRoutes,
   registerApprovalRoutes,
@@ -1142,6 +1143,7 @@ export class WebServer extends EventEmitter {
     registerTeamRoutes(this.app, ctx);
     registerMuxRoutes(this.app, ctx);
     registerFileRoutes(this.app, ctx);
+    registerHtmlViewRoutes(this.app, ctx);
     registerScheduledRoutes(this.app, ctx);
     registerHookEventRoutes(this.app, ctx);
     registerApprovalRoutes(this.app, ctx);

test/file-preview-detach.test.ts

@@ -40,6 +40,8 @@ function loadApp() {
     escapeHtml: (s: string) => String(s),
     // Reverse-proxy route builder from constants.js (not loaded here); identity at root.
     CodemanBase: { base: '', url: (p: string) => p },
+    // Also from constants.js: no file in this suite renders as an HTML page.
+    rendersAsPage: () => false,
     document: { getElementById: () => null, addEventListener: vi.fn() },
     window: windowStub,
     setTimeout,

test/file-preview-html-page.test.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview File Viewer: an `.html` file renders as a sandboxed page.
+ *
+ * The server half (`/html-view/<cap>/...`, html-view-routes.ts) is pinned by
+ * test/routes/html-view-routes.test.ts. This file pins the frontend half:
+ *
+ *  1. `rendersAsPage()` (constants.js) and the server's HTML_VIEW_EXTENSIONS
+ *     name the same extensions, so the terminal, the preview and the route
+ *     agree on what a page is.
+ *  2. A successful mint renders an iframe whose `sandbox` carries scripts but
+ *     never `allow-same-origin` (with it, the page could drive Codeman), with
+ *     the Page pill shown and pressed.
+ *  3. A refused mint (remote case, broad folder, hidden directory) falls
+ *     through to the source view with its Edit button, and hides the pill,
+ *     which would only retry a page the server just refused.
+ *  4. The pill flips between page and source and persists
+ *     `codeman:filePreviewHtmlRendered` per device; with it off the preview
+ *     opens as source without asking the server for a page at all.
+ *
+ * Loaded via `vm` with a jsdom document injected, like
+ * file-preview-markdown.test.ts: constants.js + panels-ui.js only.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { JSDOM } from 'jsdom';
+import { describe, expect, it, vi } from 'vitest';
+import { HTML_VIEW_EXTENSIONS } from '../src/web/routes/html-view-routes.js';
+
+const PUBLIC = resolve(import.meta.dirname, '../src/web/public');
+const constantsJs = readFileSync(resolve(PUBLIC, 'constants.js'), 'utf8');
+const panelsJs = readFileSync(resolve(PUBLIC, 'panels-ui.js'), 'utf8');
+
+// A real origin: jsdom's localStorage getter throws on an opaque one.
+const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', { url: 'http://localhost/' });
+const { document } = dom.window;
+
+const PAGE_PATH = '/home/u/cases/demo/report/index.html';
+const PAGE_URL = '/html-view/AAAAAAAAAAAAAAAAAAAAAAAA/index.html';
+const HTML_SOURCE = '<!doctype html>\n<h1>Report</h1>\n';
+
+function jsonResponse(body: unknown, status = 200) {
+  return { ok: status < 400, status, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+/**
+ * The two routes the preview talks to for an HTML file: the mint (answered or
+ * refused per `mint`) and file-content, which serves the source view.
+ */
+function makeFetch(mint: 'ok' | 'refuse') {
+  return vi.fn(async (url: string, init?: { method?: string; body?: string }) => {
+    if (url.endsWith('/html-view')) {
+      return mint === 'ok'
+        ? jsonResponse({ success: true, data: { url: PAGE_URL } })
+        : jsonResponse({ success: false, error: 'This folder is too broad to render a page from' }, 403);
+    }
+    if (url.includes('/file-content')) {
+      return jsonResponse({
+        success: true,
+        data: { content: HTML_SOURCE, totalLines: 3, size: HTML_SOURCE.length, truncated: false, editable: true },
+      });
+    }
+    throw new Error(`unexpected fetch ${init?.method || 'GET'} ${url}`);
+  });
+}
+
+function loadApp(mint: 'ok' | 'refuse', prefs: Record<string, string> = {}) {
+  const store = new Map(Object.entries(prefs));
+  const CodemanApp = function CodemanApp(this: unknown) {} as unknown as new () => Record<string, any>;
+  const fetchMock = makeFetch(mint);
+  const context = vm.createContext({
+    CodemanApp,
+    console: { ...console, warn: vi.fn(), error: vi.fn() },
+    localStorage: {
+      getItem: (k: string) => (store.has(k) ? store.get(k) : null),
+      setItem: (k: string, v: string) => store.set(k, v),
+      removeItem: (k: string) => store.delete(k),
+    },
+    document,
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn(), open: vi.fn() },
+    MobileDetection: {},
+    setTimeout,
+    clearTimeout,
+    confirm: () => true,
+    fetch: fetchMock,
+  });
+  vm.runInContext(`${constantsJs}\n${panelsJs}`, context, { filename: 'panels-ui.js' });
+
+  // The overlay's elements, as index.html ships them.
+  document.body.innerHTML = `
+    <div id="filePreviewOverlay"></div><span id="filePreviewTitle"></span>
+    <button id="filePreviewMdBtn" hidden></button>
+    <button id="filePreviewPageBtn" hidden></button>
+    <button id="filePreviewLinesBtn" hidden></button>
+    <button id="filePreviewWrapBtn" hidden></button>
+    <button id="filePreviewEditBtn" hidden></button>
+    <button id="filePreviewDetachBtn" hidden></button>
+    <div id="filePreviewBody"></div><div id="filePreviewFooter"></div>`;
+
+  const app = new CodemanApp();
+  app.$ = (id: string) => document.getElementById(id);
+  app._resetFilePreviewEdit = () => {
+    const edit = document.getElementById('filePreviewEditBtn');
+    if (edit) edit.hidden = true;
+  };
+  app._isExternalPreviewPath = () => false;
+  app.formatFileSize = (n: number) => `${n} B`;
+  app.filePreviewContent = '';
+
+  const byId = (id: string) => document.getElementById(id) as HTMLElement;
+  return {
+    app,
+    fetchMock,
+    store,
+    body: byId('filePreviewBody'),
+    footer: byId('filePreviewFooter'),
+    page: byId('filePreviewPageBtn'),
+    edit: byId('filePreviewEditBtn'),
+  };
+}
+
+/** The mint requests the stub saw, as parsed bodies. */
+function mintCalls(fetchMock: ReturnType<typeof makeFetch>) {
+  return fetchMock.mock.calls
+    .filter(([url]) => url.endsWith('/html-view'))
+    .map(([url, init]) => ({ url, method: init?.method, body: JSON.parse(init?.body || '{}') }));
+}
+
+describe('rendersAsPage', () => {
+  it('names exactly the extensions the html-view route renders', () => {
+    const context = vm.createContext({});
+    vm.runInContext(`${constantsJs}\nglobalThis.__page = { rendersAsPage, HTML_PAGE_EXTENSIONS };`, context, {
+      filename: 'constants.js',
+    });
+    const { rendersAsPage, HTML_PAGE_EXTENSIONS } = (
+      context as { __page: { rendersAsPage: (p: string) => boolean; HTML_PAGE_EXTENSIONS: Set<string> } }
+    ).__page;
+
+    expect([...HTML_PAGE_EXTENSIONS].sort()).toEqual([...HTML_VIEW_EXTENSIONS].sort());
+    expect(rendersAsPage('/tmp/out/report.html')).toBe(true);
+    expect(rendersAsPage('docs/INDEX.HTM')).toBe(true);
+    expect(rendersAsPage('notes.md')).toBe(false);
+    expect(rendersAsPage('page.html.txt')).toBe(false);
+    expect(rendersAsPage(undefined as unknown as string)).toBe(false);
+  });
+});
+
+describe('file viewer HTML page', () => {
+  it('renders a minted page in a sandboxed iframe that never gets allow-same-origin', async () => {
+    const { app, fetchMock, body, footer, page, edit } = loadApp('ok');
+
+    await app.openFilePreview(PAGE_PATH, 's1');
+
+    expect(mintCalls(fetchMock)).toEqual([
+      { url: '/api/sessions/s1/html-view', method: 'POST', body: { path: PAGE_PATH } },
+    ]);
+    const frame = body.querySelector('iframe')!;
+    expect(frame.getAttribute('src')).toBe(PAGE_URL);
+    const sandbox = (frame.getAttribute('sandbox') || '').split(/\s+/);
+    expect(sandbox).toContain('allow-scripts');
+    expect(sandbox).not.toContain('allow-same-origin');
+    expect(footer.textContent).toBe('HTML');
+    expect(app.filePreviewDetachUrl).toBe(PAGE_URL);
+    expect(page.hidden).toBe(false);
+    expect(page.getAttribute('aria-pressed')).toBe('true');
+    // A page has no text for Edit to act on.
+    expect(edit.hidden).toBe(true);
+  });
+
+  it('falls back to the source view with Edit and no Page pill when the mint is refused', async () => {
+    const { app, fetchMock, body, page, edit } = loadApp('refuse');
+
+    await app.openFilePreview(PAGE_PATH, 's1');
+
+    expect(mintCalls(fetchMock)).toHaveLength(1);
+    expect(body.querySelector('iframe')).toBeNull();
+    const pre = body.querySelector('pre.file-preview-text')!;
+    expect(pre.textContent).toBe(HTML_SOURCE);
+    expect(page.hidden).toBe(true);
+    expect(edit.hidden).toBe(false);
+  });
+
+  it('flips between page and source with the pill and persists the choice per device', async () => {
+    const { app, fetchMock, body, page, edit, store } = loadApp('ok');
+
+    await app.openFilePreview(PAGE_PATH, 's1');
+    expect(body.querySelector('iframe')).not.toBeNull();
+
+    await app.toggleFilePreviewPage();
+    expect(store.get('codeman:filePreviewHtmlRendered')).toBe('0');
+    expect(body.querySelector('iframe')).toBeNull();
+    expect(body.querySelector('pre.file-preview-text')!.textContent).toBe(HTML_SOURCE);
+    expect(page.hidden).toBe(false);
+    expect(page.getAttribute('aria-pressed')).toBe('false');
+    expect(edit.hidden).toBe(false);
+    // Source never asks the server for a page.
+    expect(mintCalls(fetchMock)).toHaveLength(1);
+
+    await app.toggleFilePreviewPage();
+    expect(store.get('codeman:filePreviewHtmlRendered')).toBe('1');
+    expect(body.querySelector('iframe')!.getAttribute('src')).toBe(PAGE_URL);
+    expect(page.getAttribute('aria-pressed')).toBe('true');
+    expect(mintCalls(fetchMock)).toHaveLength(2);
+  });
+
+  it('opens as source, pill offered, when the device pref says so', async () => {
+    const { app, fetchMock, body, page } = loadApp('ok', { 'codeman:filePreviewHtmlRendered': '0' });
+
+    await app.openFilePreview(PAGE_PATH, 's1');
+
+    expect(mintCalls(fetchMock)).toHaveLength(0);
+    expect(body.querySelector('pre.file-preview-text')!.textContent).toBe(HTML_SOURCE);
+    expect(page.hidden).toBe(false);
+    expect(page.getAttribute('aria-pressed')).toBe('false');
+  });
+});

test/file-preview-markdown.test.ts

@@ -19,8 +19,10 @@
  *  4. Lines/Wrap flip classes on the <pre> and persist, and the text the <pre>
  *     holds is byte-identical to the file; every toggle is hidden for an image
  *     and while editing.
- *  5. `FILE_PREVIEW_EXTENSIONS` gained avif/ico and still has no `md`
- *     (in-workspace text keeps the tail viewer, see architecture-invariants).
+ *  5. `FILE_PREVIEW_EXTENSIONS` gained avif/ico, and `md`/`markdown` (owner
+ *     decision 2026-10-13: a markdown path clicked in the terminal opens this
+ *     rendered view, not the streaming log viewer), while other in-workspace
+ *     text keeps the tail viewer (see architecture-invariants).
  *  6. A preview opened by attachment id under a bare file name has no
  *     directory to resolve against, so its relative images degrade to alt text
  *     and its relative links to plain text instead of landing on the workspace
@@ -464,10 +466,13 @@ describe('file viewer markdown line breaks', () => {
 });
 
 describe('FILE_PREVIEW_EXTENSIONS', () => {
-  it('routes avif and ico paths to the viewer and leaves .md with the tail viewer', () => {
+  it('routes avif, ico and markdown paths to the viewer and leaves other text with the tail viewer', () => {
     const { exts } = loadApp();
     expect(exts.has('avif')).toBe(true);
     expect(exts.has('ico')).toBe(true);
-    expect(exts.has('md')).toBe(false);
+    // Markdown is a document to read rendered, not a log to follow.
+    expect(exts.has('md')).toBe(true);
+    expect(exts.has('markdown')).toBe(true);
+    for (const text of ['log', 'txt', 'json', 'ts', 'yaml', 'csv']) expect(exts.has(text), text).toBe(false);
   });
 });

test/file-preview-media.test.ts

@@ -66,6 +66,8 @@ function loadApp(media: FakeMedia[]) {
     escapeHtml: (s: string) => String(s),
     // Reverse-proxy route builder from constants.js (not loaded here); identity at root.
     CodemanBase: { base: '', url: (p: string) => p },
+    // Also from constants.js: no file in this suite renders as an HTML page.
+    rendersAsPage: () => false,
     document: { getElementById: () => null, addEventListener: vi.fn() },
     window: { addEventListener: vi.fn() },
     setTimeout,

test/folder-grid-ui.test.ts

@@ -164,6 +164,8 @@ function loadApp(fetchImpl: (url: string, init?: { body?: string }) => unknown)
     escapeHtml: (s: string) => String(s),
     CodemanBase: { base: '', url: (p: string) => p },
     resolveLinkedFilePath,
+    // Also from constants.js: no file in this suite renders as an HTML page.
+    rendersAsPage: () => false,
     document: {
       getElementById: () => null,
       createElement: (t: string) => el(t),

test/routes/html-view-routes.test.ts

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview Tests for html-view-routes: rendering a local HTML file as a page.
+ *
+ * Real files in a temp dir (no fs mocks): the point of the route is its path
+ * policy, and a mocked realpath would make every containment check pass.
+ * Port: N/A (app.inject doesn't open ports)
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import Fastify from 'fastify';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { HTML_VIEW_CSP, isBroadHtmlViewRoot, registerHtmlViewRoutes } from '../../src/web/routes/html-view-routes.js';
+import { registerSecurityHeaders } from '../../src/web/middleware/auth.js';
+import { capabilityFromHtmlViewPath, htmlViewCapabilities } from '../../src/html-view-capabilities.js';
+
+describe('html-view routes', () => {
+  let harness: RouteTestHarness;
+  let sid: string;
+  let root: string;
+  let workspace: string;
+
+  beforeEach(async () => {
+    root = mkdtempSync(join(tmpdir(), 'html-view-'));
+    workspace = join(root, 'ws');
+    mkdirSync(join(workspace, 'assets'), { recursive: true });
+    writeFileSync(join(workspace, 'index.html'), '<h1>hi</h1>');
+    writeFileSync(join(workspace, 'assets', 'app.css'), 'h1{}');
+    writeFileSync(join(workspace, 'data.json'), '{}');
+    writeFileSync(join(workspace, '.env'), 'SECRET=1');
+    writeFileSync(join(workspace, 'notes.sh'), 'echo');
+    writeFileSync(join(root, 'outside.txt'), 'outside');
+    symlinkSync(join(root, 'outside.txt'), join(workspace, 'escape.txt'));
+
+    harness = await createRouteTestHarness(registerHtmlViewRoutes);
+    sid = harness.ctx._sessionId as string;
+    (harness.ctx.sessions.get(sid) as { workingDir: string }).workingDir = workspace;
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    htmlViewCapabilities.revokeOwner(undefined);
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  async function open(path: string) {
+    return harness.app.inject({ method: 'POST', url: `/api/sessions/${sid}/html-view`, payload: { path } });
+  }
+
+  async function openUrl(): Promise<string> {
+    const res = await open(join(workspace, 'index.html'));
+    expect(res.statusCode).toBe(200);
+    return JSON.parse(res.body).data.url as string;
+  }
+
+  it('mints a capability URL for an HTML file in the workspace', async () => {
+    const url = await openUrl();
+    expect(url).toMatch(/^\/html-view\/[A-Za-z0-9_-]{16,}\/index\.html$/);
+    expect(capabilityFromHtmlViewPath(url)).not.toBeNull();
+  });
+
+  it('accepts a workspace-relative path', async () => {
+    const res = await open('index.html');
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('validates the body', async () => {
+    const post = (payload: unknown) =>
+      harness.app.inject({ method: 'POST', url: `/api/sessions/${sid}/html-view`, payload: payload as object });
+    for (const payload of [{}, { path: '' }, { path: 42 }, { path: 'a\nb.html' }, { path: 'index.html', extra: 1 }]) {
+      const res = await post(payload);
+      expect(res.statusCode, JSON.stringify(payload)).toBe(400);
+      expect(JSON.parse(res.body).success).toBe(false);
+    }
+    expect(JSON.parse((await post({})).body).error).toBe('Missing path parameter');
+  });
+
+  it('refuses non-HTML files and missing files', async () => {
+    expect((await open(join(workspace, 'data.json'))).statusCode).toBe(400);
+    expect((await open(join(workspace, 'missing.html'))).statusCode).toBe(404);
+    // An .html name that links to something else is judged by its target.
+    symlinkSync(join(workspace, 'data.json'), join(workspace, 'data.html'));
+    expect((await open(join(workspace, 'data.html'))).statusCode).toBe(400);
+  });
+
+  it('serves the page sandboxed, never same-origin', async () => {
+    const url = await openUrl();
+    const res = await harness.app.inject({ method: 'GET', url });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toContain('text/html');
+    const csp = String(res.headers['content-security-policy']);
+    expect(csp).toMatch(/^sandbox /);
+    expect(csp).not.toContain('allow-same-origin');
+    expect(res.body).toBe('<h1>hi</h1>');
+  });
+
+  it("serves exactly the sandbox CSP with open network, replacing Codeman's own policy (owner decision)", async () => {
+    // Owner decision 2026-10-13 (#547): a rendered page reaches the network like a
+    // file opened from disk, so the policy is the `sandbox` directive alone. Built
+    // with Codeman's own security headers registered first, as in production, to
+    // prove their `default-src 'self'` policy does not survive onto the page.
+    const app = Fastify({ logger: false });
+    registerSecurityHeaders(app, false);
+    registerHtmlViewRoutes(app, harness.ctx as unknown as Parameters<typeof registerHtmlViewRoutes>[1]);
+    await app.ready();
+    try {
+      const cap = htmlViewCapabilities.mint(realpathSync(workspace));
+      for (const file of ['index.html', 'data.json']) {
+        const res = await app.inject({ method: 'GET', url: `/html-view/${cap}/${file}` });
+        expect(res.statusCode, file).toBe(200);
+        const csp = res.headers['content-security-policy'];
+        // One header, this exact value.
+        expect(csp, file).toBe(HTML_VIEW_CSP);
+        expect(HTML_VIEW_CSP).toBe('sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads');
+        const directives = String(csp)
+          .split(';')
+          .map((d) => d.trim().split(/\s+/)[0])
+          .filter(Boolean);
+        // Sandboxed, never same-origin...
+        expect(directives).toEqual(['sandbox']);
+        expect(String(csp)).not.toContain('allow-same-origin');
+        // ...and no fetch directive anywhere: the network is not restricted.
+        expect(String(csp)).not.toMatch(/-src\b/);
+      }
+    } finally {
+      await app.close();
+    }
+  });
+
+  it('answers Range requests, so a page can seek its own media', async () => {
+    writeFileSync(join(workspace, 'clip.mp4'), '0123456789');
+    const base = (await openUrl()).replace(/index\.html$/, '');
+    const full = await harness.app.inject({ method: 'GET', url: `${base}clip.mp4` });
+    expect(full.statusCode).toBe(200);
+    expect(full.headers['accept-ranges']).toBe('bytes');
+    expect(full.headers['content-length']).toBe('10');
+
+    const part = await harness.app.inject({ method: 'GET', url: `${base}clip.mp4`, headers: { range: 'bytes=2-5' } });
+    expect(part.statusCode).toBe(206);
+    expect(part.headers['content-range']).toBe('bytes 2-5/10');
+    expect(part.body).toBe('2345');
+    // Every header the route sets survives the hijacked body sender.
+    expect(part.headers['content-type']).toBe('video/mp4');
+    expect(String(part.headers['content-security-policy'])).toMatch(/^sandbox /);
+    expect(part.headers['access-control-allow-origin']).toBe('*');
+    expect(part.headers['cache-control']).toBe('no-store');
+
+    const beyond = await harness.app.inject({ method: 'GET', url: `${base}clip.mp4`, headers: { range: 'bytes=50-' } });
+    expect(beyond.statusCode).toBe(416);
+  });
+
+  it('serves sibling assets, including subdirectories', async () => {
+    const base = (await openUrl()).replace(/index\.html$/, '');
+    expect((await harness.app.inject({ method: 'GET', url: `${base}assets/app.css` })).statusCode).toBe(200);
+    expect((await harness.app.inject({ method: 'GET', url: `${base}data.json` })).statusCode).toBe(200);
+  });
+
+  it('never serves dotfiles, non-asset types, escapes or symlinks out of the directory', async () => {
+    const base = (await openUrl()).replace(/index\.html$/, '');
+    for (const p of ['.env', 'assets/../.env', '%2e%2e/outside.txt', '..%2foutside.txt', 'notes.sh', 'escape.txt']) {
+      const res = await harness.app.inject({ method: 'GET', url: `${base}${p}` });
+      expect(res.statusCode, p).toBe(404);
+    }
+  });
+
+  it('applies the dot and extension rules to where a symlink lands, not only to its name', async () => {
+    mkdirSync(join(workspace, '.git'));
+    writeFileSync(join(workspace, '.git', 'config'), '[remote "origin"]');
+    symlinkSync(join(workspace, '.git', 'config'), join(workspace, 'cfg.json'));
+    symlinkSync(join(workspace, 'notes.sh'), join(workspace, 'notes.css'));
+    // A link that stays inside the folder and lands on an asset still works.
+    symlinkSync(join(workspace, 'data.json'), join(workspace, 'latest.json'));
+    const base = (await openUrl()).replace(/index\.html$/, '');
+    expect((await harness.app.inject({ method: 'GET', url: `${base}cfg.json` })).statusCode).toBe(404);
+    expect((await harness.app.inject({ method: 'GET', url: `${base}notes.css` })).statusCode).toBe(404);
+    const ok = await harness.app.inject({ method: 'GET', url: `${base}latest.json` });
+    expect(ok.statusCode).toBe(200);
+    expect(ok.headers['content-type']).toContain('application/json');
+  });
+
+  it('refuses an unknown or revoked capability', async () => {
+    const url = await openUrl();
+    expect(
+      (await harness.app.inject({ method: 'GET', url: '/html-view/AAAAAAAAAAAAAAAAAAAAAAAA/index.html' })).statusCode
+    ).toBe(404);
+    htmlViewCapabilities.revokeOwner(undefined);
+    expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(404);
+  });
+
+  it('reuses one capability per directory', async () => {
+    expect(await openUrl()).toBe(await openUrl());
+  });
+  describe('outside the workspace', () => {
+    let outsideDir: string;
+    const saved = {
+      confine: process.env.CODEMAN_ATTACHMENT_CONFINE,
+      blocked: process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS,
+    };
+
+    beforeEach(() => {
+      outsideDir = join(root, 'reports');
+      mkdirSync(outsideDir);
+      writeFileSync(join(outsideDir, 'report.html'), '<p>report</p>');
+    });
+
+    afterEach(() => {
+      for (const [key, value] of [
+        ['CODEMAN_ATTACHMENT_CONFINE', saved.confine],
+        ['CODEMAN_ATTACHMENT_BLOCKED_PATHS', saved.blocked],
+      ] as const) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    });
+
+    it('mints for a page under the attachment guard', async () => {
+      expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(200);
+    });
+
+    it('refuses a page in a blocked tree', async () => {
+      process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS = outsideDir;
+      expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);
+    });
+
+    it('stops serving an out-of-workspace page once confinement is switched on', async () => {
+      const res = await open(join(outsideDir, 'report.html'));
+      expect(res.statusCode).toBe(200);
+      const url = JSON.parse(res.body).data.url as string;
+      expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(200);
+      const inside = await openUrl();
+
+      process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
+      expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(404);
+      // A page minted from inside the workspace is not affected.
+      expect((await harness.app.inject({ method: 'GET', url: inside })).statusCode).toBe(200);
+    });
+
+    it('never reuses an in-workspace capability for the same folder minted from outside', () => {
+      const inside = htmlViewCapabilities.mint(outsideDir, undefined, false);
+      const outside = htmlViewCapabilities.mint(outsideDir, undefined, true);
+      expect(outside).not.toBe(inside);
+      expect(htmlViewCapabilities.resolve(outside)?.outsideWorkspace).toBe(true);
+    });
+
+    it('refuses every out-of-workspace page when attachments are confined to the workspace', async () => {
+      process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
+      expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);
+      // The workspace itself is still fine.
+      expect((await open(join(workspace, 'index.html'))).statusCode).toBe(200);
+    });
+  });
+
+  it('refuses an HTML file inside a hidden directory, in or out of the workspace', async () => {
+    mkdirSync(join(workspace, '.cache'));
+    writeFileSync(join(workspace, '.cache', 'r.html'), '<p>r</p>');
+    writeFileSync(join(workspace, '.cache', 'token.json'), '{}');
+    expect((await open(join(workspace, '.cache', 'r.html'))).statusCode).toBe(403);
+    mkdirSync(join(root, '.hidden'));
+    writeFileSync(join(root, '.hidden', 'r.html'), '<p>r</p>');
+    expect((await open(join(root, '.hidden', 'r.html'))).statusCode).toBe(403);
+  });
+
+  it('renders a page in a workspace that itself lives under a hidden folder', async () => {
+    const hiddenWorkspace = join(root, '.local', 'src', 'app');
+    mkdirSync(join(hiddenWorkspace, 'report'), { recursive: true });
+    writeFileSync(join(hiddenWorkspace, 'report', 'index.html'), '<p>r</p>');
+    mkdirSync(join(hiddenWorkspace, '.cache'));
+    writeFileSync(join(hiddenWorkspace, '.cache', 'r.html'), '<p>r</p>');
+    (harness.ctx.sessions.get(sid) as { workingDir: string }).workingDir = hiddenWorkspace;
+
+    const res = await open(join(hiddenWorkspace, 'report', 'index.html'));
+    expect(res.statusCode).toBe(200);
+    expect((await harness.app.inject({ method: 'GET', url: JSON.parse(res.body).data.url })).statusCode).toBe(200);
+    // A hidden directory BELOW the workspace root is still refused.
+    expect((await open(join(hiddenWorkspace, '.cache', 'r.html'))).statusCode).toBe(403);
+  });
+
+  it('treats the filesystem root, home and the temp dir as too broad to serve', () => {
+    expect(isBroadHtmlViewRoot('/')).toBe(true);
+    expect(isBroadHtmlViewRoot(homedir())).toBe(true);
+    expect(isBroadHtmlViewRoot(tmpdir())).toBe(true);
+    expect(isBroadHtmlViewRoot(workspace)).toBe(false);
+  });
+
+  it('treats /tmp, /var/tmp and every directory above a broad root as broad, whatever TMPDIR says', async () => {
+    // macOS sets TMPDIR to a per-user /var/folders dir in every terminal, which
+    // os.tmpdir() returns, so the literal shared temp dirs must not depend on it.
+    const savedTmpdir = process.env.TMPDIR;
+    process.env.TMPDIR = join(root, 'private-tmp');
+    mkdirSync(process.env.TMPDIR);
+    const page = join('/tmp', `html-view-broad-literal-${process.pid}.html`);
+    writeFileSync(page, '<p>broad</p>');
+    try {
+      expect(tmpdir()).toBe(process.env.TMPDIR);
+      expect(isBroadHtmlViewRoot('/tmp')).toBe(true);
+      expect(isBroadHtmlViewRoot('/var/tmp')).toBe(true);
+      expect((await open(page)).statusCode).toBe(403);
+    } finally {
+      rmSync(page, { force: true });
+      if (savedTmpdir === undefined) delete process.env.TMPDIR;
+      else process.env.TMPDIR = savedTmpdir;
+    }
+    // Above the home directory (`/home`, `/Users`): serving it would serve home too.
+    expect(isBroadHtmlViewRoot(join(homedir(), '..'))).toBe(true);
+    // A drive's mount point and the mount parent itself.
+    expect(isBroadHtmlViewRoot('/mnt')).toBe(true);
+    expect(isBroadHtmlViewRoot('/mnt/d')).toBe(true);
+    expect(isBroadHtmlViewRoot('/mnt/d/projects/report')).toBe(false);
+  });
+
+  it('refuses a page sitting directly in the temp dir', async () => {
+    const page = join(tmpdir(), `html-view-broad-${process.pid}.html`);
+    writeFileSync(page, '<p>broad</p>');
+    try {
+      expect((await open(page)).statusCode).toBe(403);
+    } finally {
+      rmSync(page, { force: true });
+    }
+  });
+});

test/spreadsheet-preview.test.ts

@@ -594,6 +594,8 @@ describe('file-preview overlay spreadsheet wiring', () => {
       console,
       escapeHtml: (value: unknown) => String(value ?? ''),
       CodemanBase: { base: '', url: (p: string) => p },
+      // From constants.js (not loaded here): a workbook never renders as an HTML page.
+      rendersAsPage: () => false,
       fetch: fetchMock,
       setTimeout,
       clearTimeout,

test/sw-fetch-skip.test.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Which requests the service worker leaves to the network.
+ *
+ * The fetch handler caches every OK GET it answers, and the offline fallback
+ * serves from that cache. A rendered HTML page (`/html-view/<cap>/...`) is
+ * served `no-store` behind a capability that logout revokes, so a popped-out
+ * page must never land there: it is skipped like `/api/`.
+ *
+ * Runs the shipped sw.js in a `vm` context with a stub ServiceWorkerGlobalScope
+ * and drives its real fetch listener.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+const swJs = readFileSync(resolve(import.meta.dirname, '../src/web/public/sw.js'), 'utf8');
+
+function loadFetchListener(): (event: unknown) => void {
+  const listeners = new Map<string, (event: unknown) => void>();
+  const self = {
+    location: { pathname: '/sw.js', origin: 'http://localhost' },
+    addEventListener: (type: string, fn: (event: unknown) => void) => listeners.set(type, fn),
+  };
+  // A fetch that never settles: the listener only has to decide whether to answer.
+  const fetch = vi.fn(() => new Promise(() => {}));
+  vm.runInContext(swJs, vm.createContext({ self, console, caches: {}, fetch, URL }), { filename: 'sw.js' });
+  const listener = listeners.get('fetch');
+  expect(listener, 'sw.js registers a fetch listener').toBeDefined();
+  return listener!;
+}
+
+function fetchEvent(path: string) {
+  return {
+    request: { method: 'GET', url: `http://localhost${path}`, headers: { get: () => null } },
+    respondWith: vi.fn(),
+  };
+}
+
+describe('service worker fetch skip list', () => {
+  it('leaves rendered HTML pages and the API to the network', () => {
+    const onFetch = loadFetchListener();
+    for (const path of ['/html-view/AAAAAAAAAAAAAAAAAAAAAAAA/index.html', '/api/status']) {
+      const event = fetchEvent(path);
+      onFetch(event);
+      expect(event.respondWith, path).not.toHaveBeenCalled();
+    }
+  });
+
+  it('still answers an app asset', () => {
+    const onFetch = loadFetchListener();
+    const event = fetchEvent('/app.js');
+    onFetch(event);
+    expect(event.respondWith).toHaveBeenCalledTimes(1);
+  });
+});

test/terminal-touch-tap.test.ts

@@ -1018,6 +1018,48 @@ describe('terminal link tap', () => {
     expect(app.openLogViewerWindow).toHaveBeenCalledWith('/var/log/app.log', 'sess-1');
   });
 
+  it('opens a tapped markdown or HTML path in the preview, and other text in the log viewer', () => {
+    // In-workspace paths (_isExternalPreviewPath is false here): markdown renders as a
+    // document and HTML as a page in the preview; other text keeps the live tail.
+    for (const path of ['/home/u/ws/notes.md', '/home/u/ws/README.markdown', '/home/u/ws/report/index.html']) {
+      const line = `wrote ${path} just now`;
+      const { app } = linkHarness([line, '', '❯ ']);
+      expect(app._handleMobileTerminalTap(at(line.indexOf('/home')), false, 'content'), path).toBe('link');
+      expect(app.openFilePreview, path).toHaveBeenCalledWith(path, 'sess-1');
+      expect(app.openLogViewerWindow, path).not.toHaveBeenCalled();
+    }
+    for (const path of ['/home/u/ws/run.log', '/home/u/ws/notes.txt', '/home/u/ws/data.json']) {
+      const line = `wrote ${path} just now`;
+      const { app } = linkHarness([line, '', '❯ ']);
+      expect(app._handleMobileTerminalTap(at(line.indexOf('/home')), false, 'content'), path).toBe('link');
+      expect(app.openLogViewerWindow, path).toHaveBeenCalledWith(path, 'sess-1');
+      expect(app.openFilePreview, path).not.toHaveBeenCalled();
+    }
+  });
+
+  it("routes a path clicked in a tile or split pane the same way, against that pane's session", () => {
+    // TerminalTile registers the SAME provider with its own terminal and session
+    // (terminal-tile.js), so a grid tile and the split's Pane B route like the main pane.
+    const { app } = linkHarness(['', '', '❯ ']);
+    const tileTerminal = createTerminalGrid(['see /home/u/ws/notes.md and /home/u/ws/run.log', '', '❯ '], 2);
+    let provider: any;
+    tileTerminal.registerLinkProvider = vi.fn((p: unknown) => {
+      provider = p;
+    });
+    app.registerFilePathLinkProvider({ terminal: tileTerminal, getSessionId: () => 'tile-2', setHovered: vi.fn() });
+
+    let links: any[] = [];
+    provider.provideLinks(1, (found: any[]) => {
+      links = found || [];
+    });
+    const byText = (text: string) => links.find((l) => l.text === text);
+    byText('/home/u/ws/notes.md').activate({}, '/home/u/ws/notes.md');
+    byText('/home/u/ws/run.log').activate({}, '/home/u/ws/run.log');
+
+    expect(app.openFilePreview).toHaveBeenCalledWith('/home/u/ws/notes.md', 'tile-2');
+    expect(app.openLogViewerWindow).toHaveBeenCalledWith('/home/u/ws/run.log', 'tile-2');
+  });
+
   it('activates a link in scrollback, where the tap sends no report at all', () => {
     // A scrolled-up tap deliberately reports nothing (it would land on whatever row now
     // occupies the cell), but reading old output and tapping a URL in it is the common case.

test/webview-auth-exemption.test.ts

@@ -14,6 +14,7 @@ import Fastify, { type FastifyInstance } from 'fastify';
 import fastifyCookie from '@fastify/cookie';
 import { registerAuthMiddleware, registerHostGuard, registerSecurityHeaders } from '../src/web/middleware/auth.js';
 import { webviewCapabilities } from '../src/webview-capabilities.js';
+import { htmlViewCapabilities } from '../src/html-view-capabilities.js';
 import type { HostPolicy } from '../src/web/network-auth-policy.js';
 
 const POLICY: HostPolicy = { allowedHosts: [], allowLan: true };
@@ -21,6 +22,7 @@ const PASSWORD = 'test-password';
 
 let app: FastifyInstance;
 let capability: string;
+let htmlCapability: string;
 let savedPassword: string | undefined;
 
 beforeEach(async () => {
@@ -29,6 +31,7 @@ beforeEach(async () => {
   process.env.CODEMAN_PASSWORD = PASSWORD;
 
   capability = webviewCapabilities.mint('webview-under-test', undefined);
+  htmlCapability = htmlViewCapabilities.mint('/srv/report-under-test', undefined);
 
   app = Fastify({ logger: false });
   await app.register(fastifyCookie);
@@ -48,6 +51,8 @@ beforeEach(async () => {
   app.all('/q/:token', async () => ({ qr: true }));
   app.get('/', async () => 'app shell');
   app.get('/webviewfoo/bar', async () => 'lookalike');
+  app.all('/html-view/:cap/*', async () => ({ page: true }));
+  app.all('/html-viewx/*', async () => 'lookalike');
   // Stand-in for @fastify/static mounted at '/', which is what actually serves
   // /static/app.js in production. It matches EVERY path, so the fence must treat a
   // root catch-all as "no real route" or the Referer form could never apply at all.
@@ -58,6 +63,7 @@ beforeEach(async () => {
 afterEach(async () => {
   await app.close();
   webviewCapabilities.revokeWebview('webview-under-test');
+  htmlViewCapabilities.revokeOwner(undefined);
   if (savedPassword === undefined) delete process.env.CODEMAN_PASSWORD;
   else process.env.CODEMAN_PASSWORD = savedPassword;
 });
@@ -319,3 +325,61 @@ describe('a lost web-tab frame', () => {
     });
   });
 });
+
+// The rendered-HTML route (/html-view/<cap>/...) has its own, narrower exemption:
+// read-only, capability in the path only, no Referer form.
+describe('the html-view exemption', () => {
+  it('lets an unauthenticated GET and HEAD through with a live capability', async () => {
+    for (const method of ['GET', 'HEAD'] as const) {
+      const res = await app.inject({ method, url: `/html-view/${htmlCapability}/index.html` });
+      expect(res.statusCode, method).toBe(200);
+    }
+  });
+
+  it("answers the page's CORS preflight, read-only, and nothing else", async () => {
+    const preflight = (url: string) =>
+      app.inject({
+        method: 'OPTIONS',
+        url,
+        headers: { origin: 'null', 'access-control-request-method': 'GET', 'access-control-request-headers': 'x-req' },
+      });
+    const res = await preflight(`/html-view/${htmlCapability}/data.json`);
+    expect(res.statusCode).toBe(204);
+    expect(res.headers['access-control-allow-origin']).toBe('*');
+    expect(res.headers['access-control-allow-methods']).toBe('GET, HEAD');
+    expect(res.headers['access-control-allow-headers']).toBe('*');
+    expect(res.headers['access-control-allow-credentials']).toBeUndefined();
+    // An unknown or revoked capability is not a preflight anyone answers.
+    expect((await preflight('/html-view/AAAAAAAAAAAAAAAAAAAAAAAA/data.json')).statusCode).toBe(401);
+    htmlViewCapabilities.revokeOwner(undefined);
+    expect((await preflight(`/html-view/${htmlCapability}/data.json`)).statusCode).toBe(401);
+  });
+
+  it('never exempts a write on the capability path', async () => {
+    for (const method of ['POST', 'PUT'] as const) {
+      const res = await app.inject({ method, url: `/html-view/${htmlCapability}/index.html`, payload: {} });
+      expect(res.statusCode, method).toBe(401);
+    }
+  });
+
+  it('rejects an unknown capability', async () => {
+    const res = await app.inject({ method: 'GET', url: '/html-view/AAAAAAAAAAAAAAAAAAAAAAAA/index.html' });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a revoked capability immediately', async () => {
+    htmlViewCapabilities.revokeOwner(undefined);
+    const res = await app.inject({ method: 'GET', url: `/html-view/${htmlCapability}/index.html` });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('does not match a lookalike prefix', async () => {
+    const res = await app.inject({ method: 'GET', url: `/html-viewx/${htmlCapability}/index.html` });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('is not a web-tab capability, and a web-tab capability is not an html-view one', async () => {
+    expect((await app.inject({ method: 'GET', url: `/webview/${htmlCapability}/x` })).statusCode).toBe(401);
+    expect((await app.inject({ method: 'GET', url: `/html-view/${capability}/x.html` })).statusCode).toBe(401);
+  });
+});

test/webview-capability-revocation.test.ts

@@ -6,10 +6,14 @@
  * exempt from cookie auth, with a rolling TTL refreshed on every use, so a leaked
  * proxy URL stayed valid indefinitely. These tests pin every call site:
  * `POST /api/logout` (own identity), the admin forced logout, and user deletion.
+ * The rendered-HTML capabilities (`htmlViewCapabilities`) are pinned at the same sites.
  */
 
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { dataPath } from '../src/config/instance.js';
 import { WebviewCapabilityStore, webviewCapabilities } from '../src/webview-capabilities.js';
+import { HtmlViewCapabilityStore, htmlViewCapabilities } from '../src/html-view-capabilities.js';
 import { createRouteTestHarness, type RouteTestHarness } from './routes/_route-test-utils.js';
 import { registerSessionRoutes } from '../src/web/routes/session-routes.js';
 import { registerAdminRoutes } from '../src/web/routes/admin-routes.js';
@@ -40,6 +44,28 @@ describe('WebviewCapabilityStore.revokeOwner', () => {
   });
 });
 
+describe('HtmlViewCapabilityStore.revokeOwner', () => {
+  it('revokes exactly the identity asked for, the single-user `undefined` identity included', () => {
+    const store = new HtmlViewCapabilityStore();
+    const solo = store.mint('/srv/solo', undefined);
+    const alice = store.mint('/srv/alice', 'alice');
+    const bob = store.mint('/srv/bob', 'bob');
+
+    expect(store.revokeOwner('alice')).toBe(1);
+    expect(store.resolve(alice)).toBeUndefined();
+    expect(store.resolve(bob)).toBeDefined();
+    expect(store.resolve(solo)).toBeDefined();
+
+    expect(store.revokeOwner(undefined)).toBe(1);
+    expect(store.resolve(solo)).toBeUndefined();
+    expect(store.resolve(bob)).toBeDefined();
+
+    // Re-opening mints a NEW token rather than resurrecting the revoked one.
+    expect(store.mint('/srv/alice', 'alice')).not.toBe(alice);
+    store.dispose();
+  });
+});
+
 describe('POST /api/logout', () => {
   let harness: RouteTestHarness;
 
@@ -53,11 +79,14 @@ describe('POST /api/logout', () => {
 
   it('single-user: every outstanding capability dies with the login', async () => {
     const cap = webviewCapabilities.mint('wv-logout-solo', undefined);
+    const page = htmlViewCapabilities.mint('/srv/logout-solo', undefined);
     expect(webviewCapabilities.resolve(cap)).toBeDefined();
+    expect(htmlViewCapabilities.resolve(page)).toBeDefined();
 
     const res = await harness.app.inject({ method: 'POST', url: '/api/logout' });
     expect(res.statusCode).toBe(200);
     expect(webviewCapabilities.resolve(cap)).toBeUndefined();
+    expect(htmlViewCapabilities.resolve(page)).toBeUndefined();
   });
 });
 
@@ -80,12 +109,17 @@ describe('POST /api/logout in multi-user mode', () => {
   it("revokes only the caller's capabilities, never another user's", async () => {
     const mine = webviewCapabilities.mint('wv-peon-own', 'peon');
     const theirs = webviewCapabilities.mint('wv-boss-own', 'boss');
+    const myPage = htmlViewCapabilities.mint('/srv/peon-own', 'peon');
+    const theirPage = htmlViewCapabilities.mint('/srv/boss-own', 'boss');
 
     const res = await harness.app.inject({ method: 'POST', url: '/api/logout' });
     expect(res.statusCode).toBe(200);
     expect(webviewCapabilities.resolve(mine)).toBeUndefined();
     expect(webviewCapabilities.resolve(theirs)).toBeDefined();
+    expect(htmlViewCapabilities.resolve(myPage)).toBeUndefined();
+    expect(htmlViewCapabilities.resolve(theirPage)).toBeDefined();
     webviewCapabilities.revokeWebview('wv-boss-own');
+    htmlViewCapabilities.revokeOwner('boss');
   });
 });
 
@@ -114,19 +148,36 @@ describe('admin routes (multi-user)', () => {
   it('a forced logout revokes the target user (normalised) and leaves the admin alone', async () => {
     const peon = webviewCapabilities.mint('wv-peon-forced', 'peon');
     const boss = webviewCapabilities.mint('wv-boss-forced', 'boss');
+    const peonPage = htmlViewCapabilities.mint('/srv/peon-forced', 'peon');
+    const bossPage = htmlViewCapabilities.mint('/srv/boss-forced', 'boss');
 
     const res = await harness.app.inject({ method: 'POST', url: '/api/admin/users/PEON/logout' });
     expect(res.statusCode).toBe(200);
     expect(webviewCapabilities.resolve(peon)).toBeUndefined();
     expect(webviewCapabilities.resolve(boss)).toBeDefined();
+    expect(htmlViewCapabilities.resolve(peonPage)).toBeUndefined();
+    expect(htmlViewCapabilities.resolve(bossPage)).toBeDefined();
     webviewCapabilities.revokeWebview('wv-boss-forced');
+    htmlViewCapabilities.revokeOwner('boss');
+
+    // The audit line counts both kinds of capability it retired.
+    await vi.waitFor(() => {
+      const entries = readFileSync(dataPath('admin-audit.jsonl'), 'utf8')
+        .trim()
+        .split('\n')
+        .map((line) => JSON.parse(line));
+      const logout = entries.filter((e) => e.action === 'user.logout' && e.target === 'PEON').pop();
+      expect(logout?.detail).toMatchObject({ revokedWebviews: 1, revokedHtmlViews: 1 });
+    });
   });
 
   it('deleting a user revokes whatever that user had open', async () => {
     const peon = webviewCapabilities.mint('wv-peon-deleted', 'peon');
+    const peonPage = htmlViewCapabilities.mint('/srv/peon-deleted', 'peon');
 
     const res = await harness.app.inject({ method: 'DELETE', url: '/api/admin/users/peon' });
     expect(res.statusCode).toBe(200);
     expect(webviewCapabilities.resolve(peon)).toBeUndefined();
+    expect(htmlViewCapabilities.resolve(peonPage)).toBeUndefined();
   });
 });