cctally 1.38.1 → 1.39.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.39.0] - 2026-06-12
+
+### Added
+- Conversation viewer: MCP tool calls now render an action-first chip — the readable action (e.g. `browser_take_screenshot`) leads, with a quiet pill for the friendly server name and a per-server icon (playwright, chrome, computer-use, codex each get a dedicated glyph; any other server gets a generic plug icon and its raw name), instead of the full namespaced `mcp__…` name on a generic box chip; the original name stays in the chip tooltip and expanded request panel (#177 S4).
+- Conversation viewer: WebFetch and WebSearch now render as semantic source cards instead of raw JSON tool chips — WebFetch shows the fetched domain, an HTTP status chip, labeled url/prompt fields, and the Markdown summary (clamped with a show-full reveal); WebSearch shows the quoted query, a result-count chip, and a clickable list of result titles and domains — with only `http`/`https` links made clickable and no outbound requests beyond a link you click yourself (#177 S4).
+- Conversation viewer: images now render inline — a lazy-loaded figure with an `open full size ↗` link and a size/type caption, including screenshots returned inside MCP tool results that were previously dropped at ingest — served on demand by a new privacy-gated `GET /api/conversation/<id>/media` route that re-reads the original session JSONL and decodes the bytes without ever copying pixel data into the cache; PDF documents get an upgraded badge with an `open ↗` link that opens the file in a new tab, and any load failure degrades gracefully back to a byte-count badge (#177 S4).
+- Conversation viewer: a one-time background reingest (cache migration 009) backfills the new MCP/web/media rendering onto your existing transcript history on the first `cache-sync` or dashboard sync after upgrade — resumable, lossless, and re-derivable; until it completes, older rows simply keep their pre-upgrade rendering, and `cache-sync --rebuild` forces it through in one pass (#177 S4).
+
 ## [1.38.1] - 2026-06-12
 
 ### Fixed

package/bin/_cctally_cache.py

@@ -638,12 +638,17 @@ def sync_cache(
             # input / full_length / stop_reason / attribution / search_aux); the
             # same offset-0 walk re-derives those through the enriched parser, so
             # drop that flag here too — MISSING this site re-arms the flag on
-            # every cache-sync --rebuild.
+            # every cache-sync --rebuild. #177 S4 migration 009 sets the DISTINCT
+            # conversation_media_reingest_pending flag (to land tool_result
+            # media[] placeholders + user-content media index + web_search/
+            # web_fetch captures); the same offset-0 walk re-derives them, so drop
+            # that flag here as well.
             conn.execute(
                 "DELETE FROM cache_meta WHERE key IN "
                 "('conversation_reingest_pending',"
                 " 'conversation_source_tool_use_reingest_pending',"
                 " 'conversation_reingest_enrichment_pending',"
+                " 'conversation_media_reingest_pending',"
                 " 'conversation_reingest_cursor',"
                 " 'conversation_reingest_cursor_gen')")
             conn.commit()
@@ -712,15 +717,20 @@ def sync_cache(
             # input_truncated, the raised result cap + full_length, stop_reason /
             # attribution_skill / attribution_plugin, and the search_aux FTS-aux
             # blob); the offset-0 re-parse through the enriched parser lands them
-            # all with zero new consumption code. We trigger the SAME clear +
-            # offset-0 backfill on ANY of these flags and clear them ALL atomically
-            # here under the held flock.
+            # all with zero new consumption code. #177 S4 migration 009 uses yet
+            # ANOTHER distinct flag ``conversation_media_reingest_pending`` to land
+            # the tool_result media[] placeholders + user-content media index +
+            # web_search/web_fetch captures; same offset-0 re-parse, same reason
+            # for a distinct flag. We trigger the SAME clear + offset-0 backfill on
+            # ANY of these flags and clear them ALL atomically here under the held
+            # flock.
             try:
                 _reingest = conn.execute(
                     "SELECT 1 FROM cache_meta WHERE key IN "
                     "('conversation_reingest_pending',"
                     " 'conversation_source_tool_use_reingest_pending',"
-                    " 'conversation_reingest_enrichment_pending')"
+                    " 'conversation_reingest_enrichment_pending',"
+                    " 'conversation_media_reingest_pending')"
                 ).fetchone() is not None
             except sqlite3.OperationalError:
                 _reingest = False
@@ -1163,6 +1173,7 @@ _REINGEST_FLAG_KEYS = (
     "conversation_reingest_pending",
     "conversation_source_tool_use_reingest_pending",
     "conversation_reingest_enrichment_pending",
+    "conversation_media_reingest_pending",   # #177 S4 (migration 009)
 )
 
 
@@ -1189,8 +1200,8 @@ def _resumable_reingest_conversation_messages(conn):
     fingerprint (the set of pending reingest flags) resets the cursor whenever the
     pending-flag set changes, so a newly-armed flag forces a fresh pass. The caller
     (``sync_cache``) already holds the cache.db flock; per-file commits bound only
-    the SQLite write transaction, not the flock. Clears the three flags + cursor +
-    gen atomically on completion."""
+    the SQLite write transaction, not the flock. Clears all _REINGEST_FLAG_KEYS +
+    cursor + gen atomically on completion."""
     # 1. Generation guard: reset the cursor if the live pending-flag set differs.
     set_flags = [k for k in _REINGEST_FLAG_KEYS
                  if conn.execute("SELECT 1 FROM cache_meta WHERE key=?", (k,)).fetchone()]
@@ -1243,6 +1254,7 @@ def _resumable_reingest_conversation_messages(conn):
         "('conversation_reingest_pending',"
         " 'conversation_source_tool_use_reingest_pending',"
         " 'conversation_reingest_enrichment_pending',"
+        " 'conversation_media_reingest_pending',"
         " 'conversation_reingest_cursor',"
         " 'conversation_reingest_cursor_gen')")
     conn.commit()

package/bin/_cctally_dashboard.py

@@ -5345,6 +5345,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # #178: on-demand load-full. Matched BEFORE the <id> reader
             # catch-all (same precedence as /api/conversation/search).
             self._handle_get_conversation_payload(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/media"):
+            # #177 S4: on-demand media bytes. Matched BEFORE the <id> reader.
+            self._handle_get_conversation_media(path)
         elif path.startswith("/api/conversation/"):
             self._handle_get_conversation_detail(path)
         else:
@@ -7388,6 +7391,95 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         self._respond_json(200, payload)
 
+    _MEDIA_FETCH_SITE_ALLOWED = ("same-origin", "same-site", "none")
+
+    def _handle_get_conversation_media(self, path: str) -> None:
+        """``GET /api/conversation/<sid>/media?tool_use_id=<id>&index=N`` or
+        ``?uuid=<uuid>&index=N`` (#177 S4) — serves decoded image/PDF bytes by
+        re-reading the source JSONL line (the #178 mechanism). Nothing is ever
+        written to cache.db or disk; no outbound requests.
+
+        Gated FIRST by the transcript privacy predicate (fail-closed 403),
+        then by Fetch-Metadata: unlike the JSON routes, images embed
+        cross-origin (an <img src> on any website the user visits passes the
+        Host/loopback gate and leaks existence + dimensions via
+        onload/naturalWidth), so a PRESENT Sec-Fetch-Site header must be
+        same-origin/same-site/none; an absent header (curl, older browsers)
+        is allowed — defense-in-depth, not the primary gate (Codex F1).
+        Exactly one addressing key (tool_use_id XOR uuid) + a non-negative
+        integer index, else 400. Content-Type is the kernel's allowlist
+        constant; images get CSP default-src 'none'; PDFs get inline
+        Content-Disposition instead (a CSP sandbox would break native PDF
+        viewers)."""
+        if not self._require_transcripts_allowed():
+            return
+        sfs = (self.headers.get("Sec-Fetch-Site") or "").strip().lower()
+        if sfs and sfs not in self._MEDIA_FETCH_SITE_ALLOWED:
+            self._respond_json(403, {"error": "cross-site media fetch not allowed"})
+            return
+        import urllib.parse as _u
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/media")])
+        q = _u.parse_qs(self.path.partition("?")[2])
+        tool_use_id = _qs_str(q, "tool_use_id", "")
+        uuid = _qs_str(q, "uuid", "")
+        index_raw = _qs_str(q, "index", "")
+        if (not session_id or bool(tool_use_id) == bool(uuid)
+                or not index_raw.isdigit()):
+            self._respond_json(400, {"error": "bad request"})
+            return
+        index = int(index_raw)
+        key = ({"tool_use_id": tool_use_id} if tool_use_id else {"uuid": uuid})
+        cq = self._conversation_query()
+        ok, loc = self._run_conversation_query(
+            lambda conn: cq.locate_media(conn, session_id, index=index, **key),
+            "/api/conversation/media")
+        if not ok:
+            return
+        if loc is None:
+            self._respond_json(404, {"error": "not found"})
+            return
+        # Defensive envelope parity with the sibling byte-serving handlers
+        # (`_handle_get_doctor` / `_serve_static_file`): `locate_media` already
+        # runs inside the `_run_conversation_query` 500-envelope, but the
+        # `read_media_bytes` read + the byte emission did not. `read_media_bytes`
+        # is internally defensive (OSError/ValueError → `gone`), so this guards
+        # only an UNEXPECTED escape — but an unguarded one would kill the handler
+        # thread with no logged 500. `response_started` tracks the commit point:
+        # an exception BEFORE `send_response(200)` sends a clean logged 500; one
+        # AFTER (mid-`wfile.write`, headers already out) can't re-send a status,
+        # so it's logged only — never a silent thread death.
+        response_started = False
+        try:
+            status, media_type, raw = cq.read_media_bytes(
+                loc[0], loc[1], index=index, **key)
+            if status == "unsupported":
+                self._respond_json(404, {"error": "not found"})
+                return
+            if status == "too_large":
+                self._respond_json(413, {"error": "media too large"})
+                return
+            if status != "ok":
+                self._respond_json(410, {"error": "source no longer available"})
+                return
+            self.send_response(200)
+            response_started = True
+            self.send_header("Content-Type", media_type)
+            self.send_header("Content-Length", str(len(raw)))
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Cache-Control", "private, max-age=86400")
+            if media_type == "application/pdf":
+                self.send_header("Content-Disposition",
+                                 f'inline; filename="attachment-{index}.pdf"')
+            else:
+                self.send_header("Content-Security-Policy", "default-src 'none'")
+            self.end_headers()
+            self.wfile.write(raw)
+        except Exception as exc:  # noqa: BLE001
+            self.log_error("/api/conversation/media failed: %r", exc)
+            if not response_started:
+                self._respond_json(
+                    500, {"error": f"{type(exc).__name__}: {exc}"})
+
     def _handle_get_project_detail(self) -> None:
         """Return ProjectDetail JSON for ``GET /api/project/<key>?weeks=N``
         (spec §5.3 / §6.5).

package/bin/_cctally_db.py

@@ -3207,6 +3207,24 @@ def _008_session_entries_speed_backfill(conn: sqlite3.Connection) -> None:
     conn.commit()
 
 
+@cache_migration("009_conversation_media_reingest")
+def _009_conversation_media_reingest(conn: sqlite3.Connection) -> None:
+    """Flag-only re-ingest so the #177 S4 media/web enrichment — tool_result
+    ``media[]`` placeholders (iter_media_items ordinals), user-content media
+    ``index``, and the bounded ``web_search``/``web_fetch`` toolUseResult
+    captures — lands on existing history. Sets the DISTINCT
+    ``conversation_media_reingest_pending`` flag (NOT the shared
+    ``conversation_reingest_pending``, which also gates migration 005's
+    read-time human-fallback in the query kernel). Consumption rides the #179
+    RESUMABLE per-file reingest (_resumable_reingest_conversation_messages) —
+    the flag is wired into _REINGEST_FLAG_KEYS + both flag SELECTs + the two
+    cleanup DELETE lists in _cctally_cache.py (all five sites; missing one
+    either never triggers or re-arms forever). Central stamp via the
+    dispatcher (#140); a fresh install stamps it without running."""
+    _set_cache_meta(conn, "conversation_media_reingest_pending", "1")
+    conn.commit()
+
+
 # === Region 7d: Stats migration 008_recompute_weekly_cost_snapshots_dedup_fix ===
 
 @stats_migration("008_recompute_weekly_cost_snapshots_dedup_fix")

package/bin/_lib_conversation.py

@@ -24,6 +24,14 @@ _INPUT_MAX_DEPTH = 12      # max nesting depth before subtree elision (Recursion
 _INPUT_KEY_CAP = 512       # max chars per dict key (else keys are stored verbatim, unbounded)
 _INPUT_ELISION = "…"       # sentinel for elided leaves / subtrees
 
+# #177 S4: WebSearch link-list capture bounds + the media item types whose
+# placeholders the ordinal chokepoint (iter_media_items) addresses.
+_WEB_SEARCH_LINK_CAP = 50
+_WEB_LINK_TITLE_CAP = 300
+_WEB_LINK_URL_CAP = 2000
+_WEB_FETCH_CODE_TEXT_CAP = 100   # HTTP reason phrases are short; generous bound
+_MEDIA_BLOCK_TYPES = ("image", "document")
+
 
 @dataclass
 class MessageRow:
@@ -107,6 +115,8 @@ def _normalize(obj, t, offset):
         _attach_subagent_result(blocks, obj)   # #166: record-level toolUseResult
         _attach_ask_answers(blocks, obj)       # #177 S2: AskUserQuestion answers
         _attach_bash_streams(blocks, obj)      # #177 S3: Bash stderr/interrupted
+        _attach_web_search(blocks, obj)        # #177 S4: WebSearch link list
+        _attach_web_fetch(blocks, obj)         # #177 S4: WebFetch HTTP status
         _attach_task_meta(blocks, obj)         # task checklist identity
         # tool_result rows are stored but NOT indexed as prose (spec §2). A
         # user line that mixes a text block with a tool_result block must not
@@ -174,6 +184,10 @@ def _blocks_and_text(content):
         return (([{"kind": "text", "text": content}] if content else []), content, "")
     blocks, texts, aux_parts = [], [], []
     if isinstance(content, list):
+        # #177 S4: ordinal among media items at THIS list level, keyed by the
+        # object identity of each image/document item, so the placeholder writers
+        # below stamp the same ``index`` the media-route reader recomputes.
+        media_index = {id(item): idx for idx, item in iter_media_items(content)}
         for b in content:
             if not isinstance(b, dict):
                 continue
@@ -202,14 +216,24 @@ def _blocks_and_text(content):
             elif bt == "tool_result":
                 raw = _stringify(b.get("content"))
                 clipped = raw[:_TOOL_RESULT_CAP]
-                blocks.append({"kind": "tool_result", "text": clipped,
-                               "truncated": len(raw) > _TOOL_RESULT_CAP,
-                               "full_length": len(raw),
-                               "is_error": bool(b.get("is_error")),
-                               "tool_use_id": b.get("tool_use_id")})
+                block = {"kind": "tool_result", "text": clipped,
+                         "truncated": len(raw) > _TOOL_RESULT_CAP,
+                         "full_length": len(raw),
+                         "is_error": bool(b.get("is_error")),
+                         "tool_use_id": b.get("tool_use_id")}
+                # #177 S4: media placeholders for image/document items inside the
+                # tool_result content array (where every MCP screenshot lives) —
+                # ordinals from the shared iter_media_items chokepoint.
+                media = [{"kind": item.get("type"), **_media(item.get("source")),
+                          "index": idx}
+                         for idx, item in iter_media_items(b.get("content"))]
+                if media:                      # omitted when empty (additive)
+                    block["media"] = media
+                blocks.append(block)
                 aux_parts.append(clipped)
-            elif bt in ("image", "document"):
-                blocks.append({"kind": bt, **_media(b.get("source"))})
+            elif bt in _MEDIA_BLOCK_TYPES:
+                blocks.append({"kind": bt, **_media(b.get("source")),
+                               "index": media_index[id(b)]})
             elif bt == "tool_reference":
                 blocks.append({"kind": "tool_reference", "name": b.get("name")})
     return (blocks, "\n".join(t for t in texts if t),
@@ -319,6 +343,78 @@ def _attach_bash_streams(blocks, obj):
         results[0]["bash_interrupted"] = True
 
 
+def _attach_web_search(blocks, obj):
+    """Stash a WebSearch toolUseResult's structured link list onto its single
+    tool_result block (#177 S4). Self-identifying: fires only on the WebSearch
+    shape (string ``query`` + list ``results``); the query kernel additionally
+    joins NAME-KEYED (only onto name=='WebSearch'), so a shape-coincident
+    toolUseResult from another tool never decorates the wrong card (Codex F3).
+    Links flatten from results[].content[]; items lacking string title+url are
+    skipped; bounded (<=_WEB_SEARCH_LINK_CAP links, title/url char caps) with
+    ``links_truncated`` when links were dropped. Parser-private key
+    ``web_search`` is popped in the query layer's Phase 1 so it never leaks on
+    orphan blocks. Same exactly-one-result-block guard as
+    _attach_subagent_result."""
+    tur = obj.get("toolUseResult")
+    if not isinstance(tur, dict):
+        return
+    query = tur.get("query")
+    raw_results = tur.get("results")
+    if not isinstance(query, str) or not isinstance(raw_results, list):
+        return
+    results = [b for b in blocks if b.get("kind") == "tool_result"]
+    if len(results) != 1:
+        return
+    links, dropped = [], False
+    for r in raw_results:
+        content = r.get("content") if isinstance(r, dict) else None
+        if not isinstance(content, list):
+            continue
+        for item in content:
+            if not (isinstance(item, dict) and isinstance(item.get("title"), str)
+                    and isinstance(item.get("url"), str)):
+                continue
+            if len(links) >= _WEB_SEARCH_LINK_CAP:
+                dropped = True
+                break
+            links.append({"title": item["title"][:_WEB_LINK_TITLE_CAP],
+                          "url": item["url"][:_WEB_LINK_URL_CAP]})
+        if dropped:
+            break
+    payload = {"query": query[:_WEB_LINK_TITLE_CAP], "links": links}
+    if dropped:
+        payload["links_truncated"] = True
+    results[0]["web_search"] = payload
+
+
+def _attach_web_fetch(blocks, obj):
+    """Stash a WebFetch toolUseResult's HTTP status onto its single tool_result
+    block (#177 S4). Self-identifying on the WebFetch triple — ``code`` +
+    ``codeText`` + ``result`` keys all present and ``code`` an int; the query
+    kernel additionally joins NAME-KEYED (only onto name=='WebFetch'). A bare
+    error-string toolUseResult never matches (the card then renders without a
+    status chip — the documented degrade). Only the status is stored (the
+    summary already IS result.text). Parser-private key ``web_fetch`` is popped
+    in Phase 1. Same exactly-one-result-block guard as
+    _attach_subagent_result."""
+    tur = obj.get("toolUseResult")
+    if not isinstance(tur, dict):
+        return
+    if "code" not in tur or "codeText" not in tur or "result" not in tur:
+        return
+    code = tur.get("code")
+    if not isinstance(code, int):
+        return
+    results = [b for b in blocks if b.get("kind") == "tool_result"]
+    if len(results) != 1:
+        return
+    meta = {"code": code}
+    code_text = tur.get("codeText")
+    if isinstance(code_text, str) and code_text:
+        meta["code_text"] = code_text[:_WEB_FETCH_CODE_TEXT_CAP]
+    results[0]["web_fetch"] = meta
+
+
 # Subagent Task tools record toolUseResult=null and put the identity in the
 # human-readable result text instead; the id is the only thing the fold needs
 # from the result (subject/status come from the call input). Anchored to the
@@ -513,3 +609,20 @@ def _media(source):
         return {"media_type": None, "bytes": 0}
     data = source.get("data") or ""
     return {"media_type": source.get("media_type"), "bytes": len(data)}
+
+
+def iter_media_items(content):
+    """Yield ``(index, item)`` for every image/document item in a content list,
+    in document order. ``index`` is the ordinal AMONG MEDIA ITEMS (not the list
+    position) — the stable address shared by the ingest placeholder writer here
+    and the media-route reader (read_media_bytes), so "media item N" can never
+    mean two different things (the _canonical_5h_window_key lesson applied to
+    media addressing — do NOT write a second walk). Non-list input and
+    non-dict / non-media entries are skipped without consuming an ordinal."""
+    if not isinstance(content, list):
+        return
+    idx = 0
+    for item in content:
+        if isinstance(item, dict) and item.get("type") in _MEDIA_BLOCK_TYPES:
+            yield idx, item
+            idx += 1

package/bin/_lib_conversation_query.py

@@ -11,6 +11,7 @@ deduped session_entries row (idx_entries_dedup), via the shared pricing helper
 — never per physical fragment and never from cost_usd_raw (often NULL).
 """
 from __future__ import annotations
+import base64 as _base64
 import json as _json
 import os
 import re
@@ -24,6 +25,9 @@ from _lib_pricing import _calculate_entry_cost
 # content block the same way the parser does at ingest — reuse the parser's
 # _stringify so the full (un-capped) result text matches the cached/capped one.
 from _lib_conversation import _stringify
+# #177 S4: the media-route reader walks a content array with the SAME ordinal
+# generator the ingest placeholders used, so "media item N" addresses one item.
+from _lib_conversation import iter_media_items
 
 
 # Mirror of dashboard/web/src/conversations/systemMarkers.ts::MARKER_RE — anchored
@@ -489,6 +493,8 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
     agent_link = {}     # tool_use id -> (agent_id, raw_meta)
     ask_link = {}       # tool_use id -> (answers, annotations)  (#177 S2)
     bash_link = {}      # tool_use id -> (stderr, interrupted)   (#177 S3)
+    web_search_link = {}  # tool_use id -> web_search payload    (#177 S4)
+    web_fetch_link = {}   # tool_use id -> web_fetch payload     (#177 S4)
     task_link = {}      # tool_use id -> {"task_id", "task_list"}  (Task* checklist)
     for it in items:
         for b in it["blocks"]:
@@ -510,6 +516,12 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                 bintr = b.pop("bash_interrupted", None)
                 if b.get("tool_use_id") is not None and (bstderr is not None or bintr):
                     bash_link[b["tool_use_id"]] = (bstderr, bool(bintr))
+                ws = b.pop("web_search", None)              # #177 S4
+                if ws is not None and b.get("tool_use_id") is not None:
+                    web_search_link[b["tool_use_id"]] = ws
+                wf = b.pop("web_fetch", None)               # #177 S4
+                if wf is not None and b.get("tool_use_id") is not None:
+                    web_fetch_link[b["tool_use_id"]] = wf
                 tid_ = b.pop("task_id", None)               # Task* checklist
                 tlist_ = b.pop("task_list", None)
                 if b.get("tool_use_id") is not None and (tid_ is not None or tlist_ is not None):
@@ -553,6 +565,9 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                                        "truncated": bool(res_block.get("truncated")),
                                        "full_length": res_block.get("full_length"),
                                        "is_error": bool(res_block.get("is_error"))}
+                res_media = res_block.get("media")    # #177 S4: public render-ready key
+                if res_media:
+                    use_block["result"]["media"] = res_media
             owner["member_uuids"].append(tr["anchor"]["uuid"])
             drop.add(id(tr))
         # else: leave tr standalone (orphan / multi-owner / mixed) — a folded
@@ -583,6 +598,14 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                             b["stderr"] = blink[0]
                         if blink[1]:
                             b["interrupted"] = True
+                    if b.get("name") == "WebSearch":         # #177 S4: name-keyed
+                        wslink = web_search_link.get(b["tool_use_id"])
+                        if wslink is not None:
+                            b["web_search"] = wslink
+                    if b.get("name") == "WebFetch":          # #177 S4: name-keyed
+                        wflink = web_fetch_link.get(b["tool_use_id"])
+                        if wflink is not None:
+                            b["web_fetch"] = wflink
 
     # ---- Phase 3b: fold the Task* op stream into per-run checklist snapshots ----
     _fold_task_runs(items, task_link)
@@ -1317,3 +1340,117 @@ def read_full_payload(source_path, byte_offset, tool_use_id, which):
                 resp["stderr"] = tur["stderr"][:_FULL_PAYLOAD_CEILING]   # per-stream bound (see above)
             return resp
     return None
+
+
+# ---------------------------------------------------------------------------
+# #177 S4: on-demand media kernel. The route re-reads the source JSONL line by
+# byte_offset (the #178 mechanism), decodes the base64 of the addressed media
+# ordinal, and serves the raw bytes — nothing is ever written to cache.db.
+# ---------------------------------------------------------------------------
+_MEDIA_LINE_CEILING = 64 * 1024 * 1024     # raw line read cap (pathological guard)
+_MEDIA_PAYLOAD_CEILING = 20 * 1024 * 1024  # decoded cap; enforced on ENCODED length
+# Response Content-Type is the matched constant — never an echoed transcript string.
+_MEDIA_TYPE_ALLOWLIST = {
+    "image/png": "image/png", "image/jpeg": "image/jpeg",
+    "image/gif": "image/gif", "image/webp": "image/webp",
+    "application/pdf": "application/pdf",
+}
+
+
+def locate_media(conn, session_id, *, tool_use_id=None, uuid=None, index=0):
+    """``(source_path, byte_offset)`` for the row whose stored placeholder
+    carries media ordinal ``index`` — tool_use_id mode reads tool_result
+    ``media[]``; uuid mode reads user-content image/document blocks. Mirrors
+    locate_tool_payload: instr() prefilter (never LIKE — ids contain ``_``),
+    candidates parsed + exact-matched, deterministic ORDER BY matching
+    get_conversation. ``None`` -> 404. Pre-reingest rows have no placeholder
+    and correctly 404 (the client renders the badge for them anyway)."""
+    if tool_use_id is not None:
+        rows = conn.execute(
+            "SELECT source_path, byte_offset, blocks_json FROM conversation_messages "
+            "WHERE session_id=? AND instr(blocks_json, ?) > 0 "
+            "ORDER BY timestamp_utc, id", (session_id, tool_use_id)).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT source_path, byte_offset, blocks_json FROM conversation_messages "
+            "WHERE session_id=? AND uuid=? ORDER BY timestamp_utc, id",
+            (session_id, uuid)).fetchall()
+    for source_path, byte_offset, blocks_json in rows:
+        try:
+            blocks = _json.loads(blocks_json)
+        except (ValueError, TypeError):
+            continue
+        if not isinstance(blocks, list):
+            continue
+        for b in blocks:
+            if not isinstance(b, dict):
+                continue
+            if tool_use_id is not None:
+                if (b.get("kind") == "tool_result"
+                        and b.get("tool_use_id") == tool_use_id):
+                    for m in b.get("media") or []:
+                        if isinstance(m, dict) and m.get("index") == index:
+                            return source_path, byte_offset
+            elif (b.get("kind") in ("image", "document")
+                    and b.get("index") == index):
+                return source_path, byte_offset
+    return None
+
+
+def read_media_bytes(source_path, byte_offset, *, tool_use_id=None, uuid=None,
+                     index=0):
+    """Re-read the source line and return ``("ok", media_type, raw_bytes)`` for
+    media ordinal ``index``, else ``("unsupported"|"too_large"|"gone", None,
+    None)`` (-> 404 / 413 / 410). The decoded cap is enforced as an
+    ENCODED-length precheck — never decode-then-measure (Codex F4); decode is
+    strict (validate=True; binascii.Error subclasses ValueError). The media
+    walk IS iter_media_items — the same generator the ingest placeholders used,
+    so ordinals cannot drift (spec §4.1 chokepoint)."""
+    try:
+        with open(source_path, "rb") as fh:
+            fh.seek(byte_offset)
+            line = fh.readline(_MEDIA_LINE_CEILING + 1)
+        if len(line) > _MEDIA_LINE_CEILING:
+            return ("too_large", None, None)
+        obj = _json.loads(line)
+    except (OSError, ValueError):
+        return ("gone", None, None)
+    if not isinstance(obj, dict):
+        return ("gone", None, None)
+    content = (obj.get("message") or {}).get("content")
+    if not isinstance(content, list):
+        return ("gone", None, None)
+    if tool_use_id is not None:
+        target = None
+        for b in content:
+            if (isinstance(b, dict) and b.get("type") == "tool_result"
+                    and b.get("tool_use_id") == tool_use_id):
+                target = b.get("content")
+                break
+        if target is None:
+            return ("gone", None, None)
+    else:
+        target = content
+    item = None
+    for idx, m in iter_media_items(target):
+        if idx == index:
+            item = m
+            break
+    if item is None:
+        return ("gone", None, None)
+    source = item.get("source")
+    if not isinstance(source, dict):
+        return ("gone", None, None)
+    media_type = _MEDIA_TYPE_ALLOWLIST.get(source.get("media_type"))
+    if media_type is None:
+        return ("unsupported", None, None)
+    data = source.get("data")
+    if not isinstance(data, str):
+        return ("gone", None, None)
+    if len(data) > _MEDIA_PAYLOAD_CEILING * 4 // 3:
+        return ("too_large", None, None)
+    try:
+        raw = _base64.b64decode(data, validate=True)
+    except ValueError:
+        return ("gone", None, None)
+    return ("ok", media_type, raw)