Skip to content

[Air #1938] feat: Show workspace images inline in Decisions tab items - #1939

Open
waleedkadous wants to merge 7 commits into
mainfrom
builder/air-1938
Open

waleedkadous wants to merge 7 commits into
mainfrom
builder/air-1938

Conversation

@waleedkadous

@waleedkadous waleedkadous commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

An item in the Decisions tab can now show an image saved in the workspace: ![Compact layout](decision-assets/web-4-compact.png) renders inline in the card, in item bodies, their question/answer entries, and the ruled section. http(s) images work exactly as before.

Closes #1938

The Decisions tab showing a workspace PNG, a /-rooted SVG and an http(s) image inline, with two not-loaded notes

Playwright, real Tower and browser: a 1600 px PNG beside the decisions file (scaled to the card), a /-rooted SVG, an http(s) image, and two refused images: one missing, one escaping the workspace through ../../...

What Changed

Server: GET /workspace/<enc>/api/decisions/image?path=<path> (servers/decisions/routes.ts, handleDecisionsImage), key-gated like the other decisions routes. It is the first decisions route that takes a path, so it fails closed:

  • A relative path resolves against the directory of the configured decisions file; a path starting with / resolves against the workspace root. No decisions file (or one outside the workspace) means no images, through the existing locate().
  • Containment is checked twice: lexically, before the path touches the disk (so nothing outside the workspace is even probed), and again on the realpath with symlinks followed.
  • Extension allowlist (png jpg jpeg gif webp svg) on the requested path and on its realpath target, so an innocent.png symlink to .env is refused.
  • stat before read: not a regular file is not-found (a FIFO named *.png is never opened); over 10 MB is refused.
  • Content-Type from the existing getMimeTypeForFile, X-Content-Type-Options: nosniff, plus a sandbox CSP. Tower's global Cache-Control: no-store stands. A file that disappears between being located and being read is not-found, not a 500.
  • Refusals use the existing { ok: false, code, message } shape and codes (invalid-request, not-found, outside-workspace, config-error) plus two new ones: not-an-image (415) and image-too-large (413).

Client: DecisionsMarkdown (DecisionsView.tsx) and fetchDecisionImage (lib/api.ts):

  • Every image source that is not http(s) is parked in data-decisions-src inside an inert DOMParser document before the HTML reaches the page, and srcset is dropped from every <img>. Rendering through MarkdownView's innerHTML would have let the browser start a native load of each relative path against the dashboard URL (a 401 and a Tower WARN per image) before any effect could run. So the view now calls renderMarkdown directly; the shared renderer is unchanged.
  • Each parked workspace path (without any ?query / #fragment, which are not part of a file name) is fetched with the key, shown from a blob object URL, and revoked when the markdown changes or the card leaves. An in-flight load is aborted on cleanup.
  • A missing, refused, or undecodable image, and every data: / other-scheme / protocol-relative source, is replaced by a dashed note: Image not loaded + alt text + the path as written, with the reason in its tooltip. No broken-image icon.
  • Layout: max-width: 100%, max-height: 480px, object-fit: contain. A click opens the image full size in a new tab.

Docs, both trees: an "Images" rule in "What the tab reads" (resources/decision-protocol.md) and a sentence in the Decisions tab section of resources/commands/agent-farm.md, both suggesting decision-assets/ beside the decisions file. arch.md (route + view) and a lessons-learned.md entry are updated.

Key Decisions

  • Server-side path resolution. The client sends the path as written; only the server knows the configured decisions file, and the containment rules live in one place.
  • Click-to-enlarge never opens an SVG as a document. A blob URL inherits the dashboard's origin, so opening an SVG blob in a new tab would run its scripts with access to the Tower key in localStorage. The click opens a tiny HTML page we write, holding only an <img> of the blob (revoked after 60 s). This keeps the issue's "SVG only through <img>" rule true for the full-size view too. http(s) images open themselves, like links.
  • Parser: no change. A fixture test confirms that image lines in the body, and on the line directly above **Your word:**, leave the id, options, writability and ruling splice unchanged. The fingerprint is the item's text as before, computed server-side, so image load state cannot reach it.

Adjacent bug fixed in place

React 19 compares dangerouslySetInnerHTML by object identity, not by the __html string. Any inline { __html: html } (as in MarkdownView) re-sets the HTML on every render. In the Decisions tab every card re-renders on a poll that brings a new document, on a ruling, and on each draft keystroke. Each re-render undid the link rule: a relative link got its href back, so a middle-click could open it. The effect, keyed on the unchanged string, never re-ran. I confirmed this against the shipped MarkdownView with a throwaway test. It surfaced here because it wiped loaded images in the Playwright case. Fix: DecisionsMarkdown memoizes the { __html } object itself, and so does the shared MarkdownView (artifact-canvas), so the trap is fixed where it starts. MarkdownView has no remaining production caller in this repo; this protects the package's other consumers, and the reader's text selection. Tests: a view test re-renders with a fresh document and the same markdown and checks that both the image and the link rule survive; a MarkdownView test checks that the rendered DOM survives a same-source re-render and is replaced on a new source.

Test Plan

  • Route unit tests (decisions-routes.test.ts, 18 new): a file vanishing between locate and read (404); relative and /-rooted resolution, resolution against a configured decisions path; refusal of ../.., /.., a sibling dir sharing the workspace's name prefix, an absolute filesystem path, a symlink out, a symlinked dir out; serving an in-workspace symlink; non-image extensions (including .env, .png.txt) and an image-named symlink to a non-image; size limit at and over 10 MB; missing file, directory, path through a file; empty/NUL path; no decisions file.
  • Parser fixture test (decisions-parse.test.ts): image lines in the body and adjacent to **Your word:**.
  • View tests (DecisionsView.images.test.tsx, 18 new): keyed fetch and object URL; /-rooted and percent-encoded paths; ?query/#fragment stripped; srcset dropped (raw-HTML <img srcset>); all three render sites; refused / network-failure / non-image response / decode error leave a not-loaded note; data:, ftp:, //host never fetched; http(s) untouched; revoke on markdown change and unmount; abort in flight; re-render keeps image and link rule; click behaviours.
  • Playwright (decisions-tab.test.ts, new case): real Tower and Chromium. A browser-drawn PNG beside the decisions file, a /-rooted SVG and a routed http(s) image all decode; a 1600 px image stays within the card; missing and escaping images show the note; no native request for any .png/.svg path reaches Tower; the click opens a full-size tab; ruling on the item writes exactly the word, and the images stay loaded. Full decisions suite 14/14; the image case 5/5 on --repeat-each=5. Re-run once on the final head 3d545e074 after the review fixes, with a rebuilt dashboard: 14/14.
  • MarkdownView test (artifact-canvas, new): the rendered DOM survives a same-source re-render.
  • Build passes; porch build + tests checks pass (packages/codev, 8263 tests).
  • Typecheck: apps/web tsc -b, packages/codev and packages/artifact-canvas tsc --noEmit.
  • Windows (run 44838260160, head 3d545e074, suites=true): green on attempt 4. All 11 jobs pass (2 skipped by design); Unit tests on Node 22 and on Node 24 each pass 405 files. Before that, Unit tests (Node 22) failed three times, on three different non-test causes. The decisions tests (routes incl. all new image cases, parse, splice) pass on Windows under Node 22 and Node 24 in every attempt, and Node 24 unit tests pass in full.
    • attempt 1: one timing test failed, pir-1233-session-launch-loop.test.ts > failures slower than the threshold never trip the degrade fallback (3.7 s);
    • attempt 2: "The hosted runner lost communication with the server" (infrastructure);
    • attempt 3: 404 files / 8,109 tests passed, 0 failed; vitest exited 1 on one unhandled pool error, "Worker exited unexpectedly".
    • attempt 4 (the one agreed final rerun of the failed job): passed.

Flaky Tests

Porch's tests check failed twice before passing, each time with 5 s timeouts in pre-existing process-spawning tests unrelated to this change, a different set each run, while the machine's load average was 30–39 (other workspaces). Each passes in isolation (72/72). The check passed once load fell to 11. None was edited, skipped, or given a longer timeout.

  • packages/codev/src/agent-farm/__tests__/bugfix-1267-launch-loop.test.ts: "keeps resuming across a CRASH", "the switch to fresh is sticky"
  • packages/codev/src/agent-farm/__tests__/ide-command.test.ts: "ideInstall … reports the installed server version on success"
  • packages/codev/src/commands/consult/__tests__/agy-auth-cache.test.ts: "spawns agy at most once across a 5-wide burst when unauthenticated"
  • packages/codev/src/commands/consult/__tests__/tripwire-wiring.test.ts: "fires even when the lane throws"
  • Windows only, Node 22: packages/codev/src/agent-farm/__tests__/pir-1233-session-launch-loop.test.ts: "failures slower than the threshold never trip the degrade fallback" (failed in attempt 1 of the Windows run above, then passed in attempt 3).

Separately, locally on Node 26, 93 apps/web terminal / keyboard / toolbar tests fail on localStorage.getItem of undefined (Node's built-in web storage shadows jsdom's). With NODE_OPTIONS=--no-experimental-webstorage the whole web suite passes (598). This predates the change and is environment-only; the new view test supplies the key the way Tower injects it, so it passes either way.

Review Notes

  • Security-relevant: locateImage / handleDecisionsImage in routes.ts, and openFullSize + decisionsHtml in DecisionsView.tsx.
  • "The browser never requests a workspace path itself" holds for <img> (markdown images and raw-HTML <img>, srcset included). Not done (out of scope per the issue): <picture>/<source>, <video poster>, CSS url() in raw-HTML style attributes, which can still make the browser request a path natively (a harmless 401), and image keyboard focus.
  • Windows: path resolution uses path.join/path.resolve; the absolute-path test expects outside-workspace on win32. The Windows workflow ran (see Test Plan).
  • CMAP: codex = REQUEST_CHANGES: the Windows workflow had not been run; it was then dispatched (see Test Plan). claude = APPROVE, with notes, all addressed in 3d545e074: a test pinning the srcset guard, ?query/#fragment stripping, the read-race 404, keeping Tower's no-store, the MarkdownView memo, and scoping the "no native request" claim (above). Not changed: status.yaml gate fields, which porch fills at the gate.

🤖 Generated with Claude Code

waleedkadous and others added 7 commits November 20, 2026 14:31
New read-only route GET /api/decisions/image?path= serves one image an item
references. Relative paths resolve against the decisions file's directory and
/-rooted paths against the workspace root. It fails closed: containment is
checked before and after following symlinks, the extension allowlist is
checked on both the link and its target, files over 10 MB are refused, and
responses carry nosniff and a sandbox CSP.

DecisionsMarkdown parks every non-http(s) image source in an inert document,
so the browser never requests a workspace path itself. It then fetches each
image with the key, shows it from an object URL (revoked on cleanup), and
shows an "Image not loaded" note for refusals and other schemes. A click
opens a workspace image on a page holding only an <img> of it, so an SVG
never runs as a dashboard-origin document.

Also fixes in place: React 19 re-sets dangerouslySetInnerHTML whenever the
prop object changes identity, so every re-render undid the link rule (a
relative link got its href back). The markup object is now memoized.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… race, MarkdownView memo)

- Pin the srcset guard with a test: a raw-HTML <img srcset> would otherwise
  make the browser load a workspace candidate itself.
- An image source's ?query or #fragment is not part of the file name; strip it
  before the path is sent, so shot.png?v=2 loads instead of being refused as
  not-an-image.
- An image that goes between being located and being read is not-found, not a
  generic 500, matching readBytes for the decisions file.
- Leave Tower's global Cache-Control: no-store in place on the image route.
- MarkdownView memoizes its { __html } object too, so the React 19 identity
  trap is fixed where it starts for any other host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Decisions tab: show images from the workspace inline in decision items

1 participant