humanish 0.84.0 → 0.85.0

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/feedback.md

@@ -156,6 +156,15 @@ Generating a public issue draft is blocked when:
 
 ## GitHub Issue Semantics
 
+Generated acceptance commands use the installed `humanish` CLI from the workspace
+containing the evidence. They require no repository package script or manifest.
+When regenerating feedback from a retained first-party candidate, exact legacy
+`pnpm humanish -- verify/watch` templates for the same run are projected to direct
+CLI commands. Recognition checks the existing candidate/stream identity and
+idempotency conventions; it is a compatibility rule, not provenance attestation.
+Custom candidates and instructions remain unchanged. Source bundles, candidates
+and receipts are never rewritten by this projection.
+
 GitHub issues filed from feedback should say `contributes to` unless the
 acceptance proof closes the full product claim. The public issue should include
 only redacted evidence pointers and reproduction instructions that a maintainer

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.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.85.0`; 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 23)
 
 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.0`)
+## Current Program Truth (source `0.85.0`)
 
 The package source and repository implementation in this tree agree on these
 points:
 
+**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.
 
 **Declared evidence verification (#715).** Ordinary verification checks final/partial actor frame references and feedback candidate files. Explicit raw frame declarations keep partial traces `local_only`; valid zero-event terminal logs remain supported. Missing or unknown per-frame redaction metadata retains existing compatibility behavior, and unreferenced files are outside this check.

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.84.0` (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.0` (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.84.1-portable-feedback.md

@@ -0,0 +1,20 @@
+# Humanish 0.84.1: feedback commands work in exported workspaces
+
+Feedback acceptance commands now call the installed `humanish` CLI directly.
+They work from a standalone exported evidence workspace without a package
+manifest or repository script:
+
+```bash
+humanish verify --run RUN --json
+humanish watch --run RUN --no-open
+```
+
+Run them from the directory containing `.humanish/`, with the CLI on `PATH`.
+The watch command serves the Observer until stopped. These commands do not
+download a different package version.
+
+Redrafting feedback from recognized first-party candidates also updates exact
+legacy command templates. Custom acceptance instructions and all original
+candidate evidence and receipts remain unchanged. Unusual run IDs are quoted
+for shell use. The [feedback contract](../contracts/feedback.md) describes the
+compatibility boundary.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "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",