humanish 0.84.1 → 0.85.1

package/docs/architecture/observer.md

@@ -65,6 +65,42 @@ The browser polls `observer-data.json` with `no-store` caching. Static
 operator path. Agents and CI should use `humanish watch --json --no-open` for
 the same fresh evidence without browser open or a long-running process.
 
+### Reopening a run
+
+The TUI's **Open Observer** action opens an HTTP view that follows saved captures
+as the run writes them. One loopback evidence server is shared by the session's
+browser tabs; exiting the TUI closes it, including when the UI fails. Opening a
+run does not launch a study. The URL is always shown for manual opening or SSH
+port forwarding, and only contained run paths in the TUI's project are accepted.
+
+| Entry point | What updates | Lifetime |
+| --- | --- | --- |
+| `watch` during a study | Saved evidence and available in-memory desktop streams | Until the attached command exits |
+| `observe --run <id>` | Saved evidence from the selected run | Until the command exits |
+| TUI Open Observer | Saved evidence in the selected run; shares the project's evidence library | Until the TUI exits |
+| `serve` | Saved evidence across the project's library | Until the server command exits |
+| Static HTML or `file://` | The exported snapshot | Independent of a server |
+
+`observe` uses the same current-data projection as the attached viewer, scoped
+to the selected run. Its history cannot enumerate other runs. HTML exports use
+the installed Observer renderer around the recording's saved data and embedded
+images, so older recordings get UI improvements without changing their source.
+
+Reopening an active run follows its saved captures; it cannot recover a live
+desktop URL held by another process. Stream credentials are never recovered
+from disk or added to the TUI/library server. Original `watch` attachment is
+what enables a live desktop stream. The loopback library retains its Host
+allowlist, contained file reads, read-only routes and no-store security headers.
+
+Served data may also include `runtime` with `state`, `observedAt`, and
+`source: "local-run-status"`. This is a current observation of a contained,
+matching `status.json`; it never changes the run's recorded verdict or participant
+outcomes. A fresh heartbeat means running, an explicitly finalized record means
+finished, and stale or invalid timing means unknown. Missing, malformed, or
+mismatched records omit the observation. A stale heartbeat alone does not prove
+interruption, and stored PIDs are neither probed nor returned. Static rendering
+and export do not create this served-only observation.
+
 Local `codex-exec` actor runs now publish an initial running `run.json` and
 `observer/observer-data.json` before actor completion, then refresh both after
 sanitized transcripts, traces, and verdict events are available. This gives a
@@ -81,13 +117,15 @@ stream URLs in any mode; remote viewers see persisted evidence only. See
 ### Exposed hardening and `watch --expose`
 
 The live `serveObserver` server binds `127.0.0.1` and, by default, is a
-permissive local-dev server (no Host allowlist, no security headers). Under its
+local-dev server without a Host allowlist. Every response carries security
+headers, including `X-Frame-Options: DENY` and CSP `frame-ancestors 'none'`.
+Under its
 `exposed` option — set by `watch --expose` — it enforces the SAME
 DNS-rebinding defense as the library surface: a strict Host allowlist (loopback
 names at bind, extended by `addPublicOrigin(tunnel.url | public-url)`, `421
 Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
 every response (both live in `src/serve-http.ts`, shared without a module cycle).
-Loopback (non-exposed) behavior is byte-identical to before.
+The Host allowlist applies in exposed mode; frame-denial headers apply in both modes.
 
 Exposed mode also SCOPES the surface to the attached live run (`result.run`): the
 `/_humanish/history.json` index is filtered to that one run, and `/_humanish/runs/<id>/…`
@@ -108,8 +146,45 @@ attached server comes up DURING the run and survives a `timed_out`/`failed` run
 to Ctrl-C. `serve` still never injects stream URLs. See
 [Serve: the run library surface](serve.md).
 
+### Live desktop iframe authority
+
+Only a URL in the attached server's in-memory runtime map receives
+`stream.embed.runtimeDesktop: true`. Persisted markers are removed when building
+Observer data and again when reading served fallback projections. Cross-run
+library routes do not inherit the attached run's runtime URLs, even when their
+stream ids match. Ended or invalid runtime entries do not receive the grant.
+The generic static-server helper strips this marker and saved `runtime` state
+from Observer JSON and inline data. Static responses carry the same framing
+denial headers; they never grant active desktop attachment.
+
+The browser can preserve a cross-origin provider's origin for its desktop viewer
+modules only with this grant. Ordinary stored embeds remain isolated. Every
+Observer/library response, including raw run HTML, refuses framing, so a provider
+redirect or scripted navigation back to an Observer-origin document cannot load
+it inside the iframe and gain access to the parent. This protects the receiving
+origin without a fixed provider allowlist that becomes stale as desktops start.
+The underlying standards are [iframe sandbox permissions](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe)
+and [CSP frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors).
+
+Raw artifact responses also carry `sandbox allow-scripts` in their CSP. Opening
+a saved HTML or SVG document directly gives its scripts an opaque origin, so
+they cannot read the Observer's other evidence or browser storage. The policy
+applies to every raw file, including unknown extensions, alongside `nosniff`.
+Generated Observer HTML and JSON routes retain normal same-origin access for
+updates. The generic static helper serves raw documents under the sandbox;
+origin-dependent scripts and modules in those artifacts may require independent
+hosting. See the [CSP sandbox standard](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox).
+
+History entries may include `runtimeState` from the same contained local status
+read as the Observer. Their existing `status` remains the recorded verdict.
+Running filters should use runtime state when present, preserving the difference
+between an active study and its provisional evidence outcome.
+
 ## UI Shape
 
+See [Watching and reviewing evidence](observer-review.md) for current controls,
+entry-point capabilities, timing limits and browser acceptance commands.
+
 The Observer shell has:
 
 - top mission-control band with run status and metrics;
@@ -119,6 +194,17 @@ The Observer shell has:
 - terminal/TUI transcript stage;
 - right evidence rail for events, artifacts, and known gaps.
 
+The participant grid uses equal-height previews whose widths follow each screen's
+aspect ratio. A 44px identity/source/outcome caption sits below the captured pixels;
+no badges or controls cover the screen. Generated computer-use lane labels display
+the recorded persona identity; repeated identities gain a lane or stream qualifier.
+A stable details button opens labeled Pin/Compare actions, recorded notices, final
+messages, dimensions, duration and exact identifiers. Exceptional outcomes remain
+in the caption. Icon controls have visible hover/focus hints and touch-sized targets. Search, preview size and monitor mode
+share the view/filter popover. Monitor mode keeps its exit beside the run status.
+Live previews remain bounded to four visible cards, with the hovered or focused
+participant taking priority when the grid shows more than four eligible cards.
+
 ## Codex UI Contract
 
 `codex-ui` streams are normalized session/event projections. Public artifacts

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.84.1`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.85.1`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.

package/docs/goals/current.md

@@ -1,6 +1,6 @@
 # Current Goals
 
-Status date: 2026-09-07 (rev 22)
+Status date: 2026-09-09 (rev 24)
 
 This page is the current public-safe operating goal for `humanish`. Keep it
 short enough to reread before a coding session and concrete enough that future
@@ -29,11 +29,15 @@ study completed, reproduced, and produced a real accessibility finding via a
 keyboard-first participant
 ([docs/goals/email-gated-signup/receipts/](email-gated-signup/receipts/)).
 
-## Current Program Truth (source `0.84.1`)
+## Current Program Truth (source `0.85.1`)
 
 The package source and repository implementation in this tree agree on these
 points:
 
+**Observer review continuity, 2026-09-09 (#731).** The run library opens during player/comparison review. Comparison frames link into the player and return to the saved alignment and cursor; participant names stay consistent. Explicit thinking filters reveal narration, and run/setup notices remain inspectable separately from frame-linked findings. See the [0.85.1 release note](../release/0.85.1-observer-continuity.md).
+
+**Observer watching and review, 2026-09-09 (#723, #724, #726, #728).** Grid previews preserve complete screens at a shared height, with compact captions and controls below the evidence. Run activity, live viewing, recorded replay and update freshness are distinct. Seeking, refresh and incoming captures preserve the selected viewing intent. The player adds elapsed-time review, zoom, saved moments and participant/cross-run comparison. The built TUI and observe serve existing evidence; exports contain no runtime desktop grants. See the [0.85.0 release note](../release/0.85.0-observer-review.md) for capabilities, acceptance evidence and limits.
+
 **Portable feedback acceptance commands, 2026-09-07 (#720).** Generated proof commands use the installed CLI from the evidence workspace, including standalone exports without a package manifest. Redrafting recognized first-party candidates projects exact legacy command templates without rewriting source candidates or receipts. Custom instructions remain unchanged. See the [0.84.1 release note](../release/0.84.1-portable-feedback.md).
 
 **Readable evidence and shareable feedback, 2026-09-07 (#136).** `export --format bundle --redact-screenshots` creates a separate verified workspace while retaining the readable original. Four real operator-run recordings preserved all measured findings and costs through export and ordinary feedback commands; all 31 frames played in both bundle and HTML views. Static Observer grades now reflect their actual verification result. See the [retained workflow receipt](computer-use-actor/receipts/redacted-evidence-workflow-2026-09-07.md). External maintainer use and acceptance remain unproven.

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.84.1` (2026-09-07). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.85.1` (2026-09-09). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/docs/release/0.85.0-observer-review.md

@@ -0,0 +1,56 @@
+# Humanish 0.85.0: watch and review complete screens
+
+Observer now shows portrait and desktop captures at their original proportions,
+with equal-height grid previews and a compact caption below each screen. Live
+labels and controls leave the captured pixels clear. A stable Info button opens
+participant details, labeled Pin/Compare actions and recorded notices.
+
+Run activity, viewing mode and evidence freshness are distinct. Finished studies
+say they are finished; failed updates preserve the last evidence and offer retry.
+Seeking, keyboard controls, moment links and refresh agree about the displayed
+capture. Paused replay stays on its selected frame as new evidence arrives.
+
+The review tools include:
+
+- elapsed-time playback, capture-gap labels, Skip waits and action/finding navigation;
+- fit, actual size, zoom/pan, fullscreen and a hideable/resizable inspector;
+- copyable moment links, original-frame inspection and local saved moments;
+- preview size, filtering, pinning, monitoring and reachable participant pages;
+- participant and cross-run comparison with explicit capture age and missing coverage;
+- consistent icons, keyboard hints, explicit popover dismissal and larger touch targets.
+
+`observe` and the built TUI open existing evidence through a local viewer. Live
+desktop access remains owned by the attached process; opening an existing study
+cannot recover another process's credentials. Offline exports keep the current
+renderer and saved images without runtime desktop authority. The
+[Observer review guide](../architecture/observer-review.md) explains these paths.
+
+## Updating
+
+Install this version using your usual package manager. For a global installation:
+
+```bash
+npm install -g humanish@0.85.0
+humanish --version
+humanish observe --run RUN
+```
+
+Run the last command from the workspace containing the existing study. Previously
+generated HTML embeds its viewer: reopen the run with the updated CLI, or
+regenerate its HTML export, to get the new interface.
+
+## Verification and limits
+
+The implementation was exercised with five hosted two-participant studies and
+140 retained screenshots. A separate check opened all 28 frames through observe,
+the built headed TUI and HTML export: 84 of 84 opens passed. The
+[implementation receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/observer-qol/receipts/2026-09-08-observer-review.md)
+distinguishes failed probes, accepted runs and cleanup evidence.
+
+Regression coverage includes 156 Observer tests, 33 production-artifact browser
+scenarios and 15 iframe/artifact isolation checks. Browser acceptance covers
+Chromium on Linux, including touch emulation; physical devices and other engines
+remain unverified. Screenshot replay remains sparse evidence, without a
+continuous video track or guaranteed before/after capture for every action.
+The pre-existing source-checkout TUI loader limitation remains; the built CLI
+is the tested installation path.

package/docs/release/0.85.1-observer-continuity.md

@@ -0,0 +1,20 @@
+# Humanish 0.85.1: keep your place while reviewing evidence
+
+The Observer review flow now carries the selected evidence between views:
+
+- The library button opens a drawer from the player and comparison on desktop and phone.
+- Comparison previews share a height, preserving complete portrait and desktop screens. Panels use the same participant names as the grid and link to their exact recorded frames. Open a frame, save it, and return to the previous comparison alignment and cursor. Reopening the same comparison from the grid also keeps its place.
+- Adding another run cannot silently remove one of the three selected participants. Grid-only filters no longer appear in comparison.
+- Recalling a saved moment after reloading and stepping through frames selects the saved image as well as its URL.
+- Player details identify the selected participant rather than the study's fan-out placeholder.
+- Selecting Reported thinking shows existing narration even when thinking is hidden in All evidence. Warnings & findings includes a separate, paged list of run/setup notices with their recorded timestamps; these notices do not invent screenshot links or claim participant product findings.
+
+Install with `npm install -g humanish@0.85.1`. Reopen an existing run with the updated CLI (`humanish observe --run RUN` from its workspace), or regenerate its HTML export, to refresh embedded viewers.
+
+## Verification and limits
+
+The [retained workflow receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/observer-qol/receipts/2026-09-09-review-continuity.md) records actual-study outcomes, independent review and practical limits. The production browser suite adds desktop/touch library access, comparison-to-frame/save/return, browser history and explicit capacity checks. Player regression tests cover narration filtering and separate notice pagination without changing the selected frame.
+
+A fresh hosted two-participant drawDB study exercises actual growing captures and the review journey. Retained run: `observer-review-journey-n2-20260909`. The attached `observe` check follows updated captures; it does not establish a new live-desktop connection or physical mobile fidelity. The release gate separately exercises the packed candidate in disposable terminal sandboxes.
+
+Saved moments remain local to the browser. Cross-run review requires the served run library. Screenshot replay remains sparse; continuous video, physical devices, other browser engines, and screen-reader acceptance remain separate work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.84.1",
+  "version": "0.85.1",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -76,7 +76,9 @@
     "tui:test": "pnpm --filter humanish-tui test",
     "release:dogfood": "node scripts/release-dogfood.mjs",
     "docs:generate": "tsx scripts/generate-cli-docs.ts",
-    "docs:check": "tsx scripts/generate-cli-docs.ts --check"
+    "docs:check": "tsx scripts/generate-cli-docs.ts --check",
+    "observer:browser:proof": "node scripts/observer-browser-proof.mjs",
+    "observer:iframe:proof": "node scripts/observer-iframe-proof.mjs"
   },
   "repository": {
     "type": "git",