humanish 0.106.1 → 0.108.0

package/dist/routes/computer-use/legacy-lane-spec.d.ts

@@ -1,62 +0,0 @@
-import type { ActorPersonaRef } from "../../actors/contract.js";
-import type { ReasoningEffort } from "../../actors/reasoning-effort.js";
-import type { DwellWindow, StopWhen } from "../../actors/stop-conditions.js";
-import type { DevicePreset } from "../../lab/device-presets.js";
-import type { LabTask } from "../../lab/tasks.js";
-import type { RunStream } from "../../run/streams.js";
-import type { DesktopParticipantRun } from "./types.js";
-/**
- * A lane as the deprecated cuaHooks.buildProvider and cuaHooks.createDesktopLane receive it: a flat
- * copy of a DesktopParticipantRun.
- * @deprecated Use RunLabOptions.createProvider, which receives a ParticipantRef. Removed with the
- * compatibility section in the next minor.
- */
-export interface CuaLaneSpec {
-    laneId: string;
-    actorType?: string;
-    surface?: string;
-    caseGroup?: string;
-    /** 0-based. */
-    laneIndex: number;
-    simId: string;
-    streamId: string;
-    persona: ActorPersonaRef;
-    instructions: string;
-    /** Redacted original composed prompt for legacy study context; execution uses instructions. */
-    evidenceInstructions?: string;
-    /** Original declarative assignment, separate from runtime-composed instructions. */
-    assignment?: RunStream["assignment"];
-    /** App-url fan-out only: this lane's explicit browser target; absent falls back to deps.appUrl. */
-    targetUrl?: string;
-    /** Deterministic harness-owned completion guard. Lane-level override, else actor default. */
-    stopWhen?: StopWhen;
-    /** A declared observation window (#510). Lane-level override, else actor default. */
-    dwell?: DwellWindow;
-    /**
-     * How hard this lane's model is asked to think. Lane-level override, else the actor default,
-     * else absent — and absent means the provider's own default, which the trace records as the
-     * resolved value rather than as nothing (#497).
-     */
-    reasoningEffort?: ReasoningEffort;
-    maxOutputTokens?: number;
-    /** The lab's declared protocol (#414). Every lane runs the SAME protocol — that is what makes the
-     *  per-task rates comparable across participants. Goals are already composed into `instructions`;
-     *  this carries the full tasks so the loop can corroborate completion, and the criteria never
-     *  reach the prompt. */
-    tasks?: readonly LabTask[];
-    /** Per-lane override of the CUA idle backstop (consecutive screenshot/wait turns before gave_up).
-     *  Absent falls back to the loop default. Raised for a lane whose job includes a long LEGITIMATE
-     *  wait (e.g. a shared-world HOST idling in the waiting room while followers provision + join). */
-    idleSteps?: number;
-    /** Per-lane override of the non-idle no-progress backstop; see idleSteps. */
-    noProgressSteps?: number;
-    deviceName: string;
-    devicePreset: DevicePreset;
-    resolution: [number, number];
-    /** "" for N=1 (screenshots/<name>); the laneId for N>1 (screenshots/<laneId>/<name>). */
-    screenshotDir: string;
-    /** "actor.json" for N=1; "actors/<streamId>.json" for N>1. */
-    traceArtifactPath: string;
-}
-/** The flat hook view of one participant run. Called only where a caller's hook receives a lane. */
-export declare function legacyHookSpecOf(run: DesktopParticipantRun): CuaLaneSpec;

package/dist/routes/computer-use/legacy-lane-spec.js

@@ -1,39 +0,0 @@
-// Translation module: legacy lane spellings stay only in modules like this one, so the rest of the
-// route reads participants. CuaActorLabHooks is public API in the deprecated compatibility section, and two of its hooks,
-// buildProvider and createDesktopLane, receive a lane. They keep receiving this flat record until
-// the next minor removes the section. Internally a lane is a DesktopParticipantRun.
-/** The flat hook view of one participant run. Called only where a caller's hook receives a lane. */
-export function legacyHookSpecOf(run) {
-    const { planned } = run;
-    const { labels, limits, device } = planned;
-    return {
-        laneId: planned.id,
-        ...(labels.actorType === undefined ? {} : { actorType: labels.actorType }),
-        ...(labels.surface === undefined ? {} : { surface: labels.surface }),
-        ...(labels.caseGroup === undefined ? {} : { caseGroup: labels.caseGroup }),
-        laneIndex: planned.index,
-        simId: run.recordId,
-        streamId: run.streamId,
-        persona: run.persona,
-        instructions: run.instructions,
-        ...(run.evidenceInstructions === undefined
-            ? {}
-            : { evidenceInstructions: run.evidenceInstructions }),
-        ...(run.evidenceAssignment === undefined ? {} : { assignment: run.evidenceAssignment }),
-        ...(planned.targetUrl === undefined ? {} : { targetUrl: planned.targetUrl }),
-        ...(limits.stopWhen === undefined ? {} : { stopWhen: limits.stopWhen }),
-        ...(limits.dwell === undefined ? {} : { dwell: limits.dwell }),
-        ...(limits.reasoningEffort === undefined ? {} : { reasoningEffort: limits.reasoningEffort }),
-        ...(limits.maxOutputTokens === undefined ? {} : { maxOutputTokens: limits.maxOutputTokens }),
-        ...(planned.tasks === undefined ? {} : { tasks: planned.tasks }),
-        ...(run.backstop?.idleSteps === undefined ? {} : { idleSteps: run.backstop.idleSteps }),
-        ...(run.backstop?.noProgressSteps === undefined
-            ? {}
-            : { noProgressSteps: run.backstop.noProgressSteps }),
-        deviceName: device.name,
-        devicePreset: device.preset,
-        resolution: device.resolution,
-        screenshotDir: run.screenshotDir,
-        traceArtifactPath: run.traceArtifactPath,
-    };
-}

package/docs/architecture/comms-inbox.md

@@ -1,122 +0,0 @@
-# Participant inboxes
-
-This page describes local capture. For fresh hosted inboxes, see
-[real email receiving](real-email-receiving.md); that route has a separate
-parsed renderer, strict remote-asset blocking and private lease lifecycle.
-
-The catch captures application mail without sending it to an external recipient.
-humanish gives each participant an address and a matching
-`/inbox/for/<address-digest>` URL. The same address scope applies to list, message,
-plain view, latest-message and JSON routes. Going back from a missing message
-stays in that scope. An unknown scope is empty; it never falls back to all mail.
-A participant without an assigned address receives no inbox instruction.
-
-This works with separate participant worlds, shared worlds, and an external catch.
-Sharing an application world does not require sharing an inbox. If a lab deliberately
-assigns the same address to two participants, both see that address's mail. Generated
-addresses that collide after normalization are made distinct. A message addressed
-to several participants appears in each recipient's inbox and retains its actual
-To field.
-
-`/inbox` remains available and is labeled **Shared operator inbox**. Address digests
-are routing identifiers, not authentication credentials. The catch is study
-infrastructure, not a mailbox service with hostile-tenant isolation. Keep its network
-exposure appropriate for test mail. The read-only listener cannot expose the private
-`/deliveries` drain, even when supplied a valid drain token. The capture listener
-retains its existing optional bearer-token protection for that endpoint.
-
-A standalone catch tracks its generated files. Reusing its directory with a changed
-`--recipient` roster or an emptied delivery log removes obsolete message, latest and
-recipient routes; unrelated files are untouched.
-
-## Local browser studies
-
-Run a catch on the same host as the local study:
-
-```bash
-humanish comms catch --port 8025 --dir .humanish/mail-catch
-```
-
-Configure your **app's** email transport to send to `http://127.0.0.1:8025`
-using its supported HTTP send configuration, or add `--smtp-port 1025` and
-point its SMTP transport at `127.0.0.1:1025`. humanish does not change an
-already-running app's environment. No real mailbox-provider credentials are
-needed. This captures mail sent by that app; it does not receive arbitrary
-internet email.
-
-Add this to an existing local `app-url` lab:
-
-```yaml
-comms:
-  email:
-    external:
-      catchBaseUrl: http://127.0.0.1:8025
-```
-
-Then run `humanish doctor --lab <lab>` and `humanish run <lab>`. Omit
-`recipients` to assign an address per participant automatically, or declare explicit
-`{ lane, address }` entries for an existing roster. The participant receives its
-address and inbox URL in its mission. Verification links keep their original
-app origin; ensure they target the loopback app port selected by the lab.
-
-Each local desktop forwards a separate host-owned read-only proxy for its
-assigned recipient. Other recipient routes, the operator inbox, mail sends and
-the private delivery drain are unavailable through that proxy. The study closes
-these proxies with its desktops and leaves your catch running. Host-side
-collection uses the existing digest-only comms evidence. Supported captured
-images and explicit unavailable-image placeholders work as described below.
-
-The local path supports captured email only. Provider-backed real receiving
-retains its separate hosted-route and management-credential requirements.
-
-## Existing external catches
-
-Upgrade the humanish installation that runs `humanish comms catch` and **restart that
-catch process**, as well as upgrading the installation that starts the study. Updating
-only the study client leaves an older catch without participant routes.
-
-Before allocating participants, the client checks `/health` on both `catchBaseUrl`
-and a distinct `inboxBaseUrl`. Each must return the normal service marker and
-`capabilities: ["recipient-inbox-v1", ...]`. Missing, malformed or older responses
-fail admission with an upgrade/restart instruction. Existing email capture endpoints
-and unscoped operator URLs remain available; their payload contracts are unchanged.
-
-## Captured and remote images
-
-The SMTP catch preserves MIME parts with a Content-ID when they contain PNG, JPEG,
-GIF or WebP bytes. The generic `/emails` payload can also carry runtime-only
-`inlineImages` entries with `contentId`, `contentType` and `base64`. Provider-specific
-attachment fields are not converted; unsupported or missing CID references show an
-explicit unavailable-image placeholder instead of pretending capture succeeded.
-
-Captured images are limited to 12 entries, 1 MiB each and 2 MiB total. The renderer
-checks canonical base64 and the declared raster format's signature before creating a
-data URL. This is not a full image decoder; malformed raster content can still fail
-in the browser. Inline data URLs receive the same per-image checks. SVG, arbitrary
-attachment URLs and local paths are not fetched or converted.
-
-HTTP(S) images remain browser loads with `no-referrer`. humanish does not fetch or
-proxy them server-side. Relative image URLs use the existing declared origin-rewrite
-map when available; otherwise they receive an explicit placeholder. Remote URLs that
-return errors retain the browser's alt-text fallback. The renderer does not claim to
-repair a dead URL. The inbox retains `script-src 'none'` and the existing HTML
-neutralization and origin-rewrite protections.
-
-Raw mail and image bytes remain runtime catch data. Persisted comms evidence remains
-digest-only; adding image capture does not add raw attachments to the run artifact.
-
-## Reproduce the contract
-
-```bash
-pnpm exec vitest run tests/comms/ tests/substrates/local/captured-inbox.test.ts
-pnpm exec tsx scripts/comms-inbox-proof.ts
-```
-
-The browser proof starts owned loopback HTTP, read-only inbox and SMTP listeners,
-sends fictional multipart mail through the real MIME parser, and renders two recipient
-inboxes in Chromium at desktop and phone sizes. It checks decoded CID/data/remote
-images, unavailable sources, a genuine remote 404, recipient isolation across HTML
-and JSON, navigation, script blocking, referrer suppression, directory reuse and drain
-access. Screenshots and a machine-readable receipt are saved under the ignored
-`.humanish/comms-inbox-proof/` directory. It uses no external email delivery, paid model
-calls or hosted desktop, and makes no claim about those providers.

package/docs/architecture/desktop-recording.md

@@ -1,80 +0,0 @@
-# Optional desktop recording
-
-humanish keeps screenshots, actions, participant feedback and analysis by default.
-For continuous playback, opt into a desktop video:
-
-```yaml
-execution:
-  desktop:
-    recording: { audio: true }
-```
-
-Set `audio: false` for screen-only video. Omit `recording` to keep the lightweight
-snapshot recording. This applies to independent computer-use desktop participants on
-local Firecracker and E2B; scripted-browser, shared-world and in-process executors
-do not consume this setting and reject it before execution.
-
-Recording does not enable a camera, speech synthesis or speech recognition.
-Those remain separate [participant media](participant-media.md) options. With
-audio enabled, microphone input and speaker output are mixed into one AAC track.
-`audioSources` identifies the capture points feeding that mix, not separate
-retained tracks. The microphone can be silent when speech is not configured.
-A recorded microphone signal proves what was offered to the browser, not what
-another person received. Confirm reciprocal delivery from the other
-participant's evidence.
-
-## Capture and playback
-
-The desktop runs FFmpeg against its X display. MP4 carries H.264 video and optional
-AAC audio. Recording stops and streams to the run directory before desktop cleanup.
-Both providers use the same encoding settings and artifact metadata. Video encoding
-uses the capture input’s microsecond time base, preserving closely spaced captures
-and their offsets rather than rounding them to the nominal frame interval.
-Explicit variable-frame-rate output preserves gaps without filling them with
-duplicate frames across the supported FFmpeg versions. The recording
-mix disables playback rewinds to avoid the null sink's initial two-second buffer. The local
-runtime transfers one bounded file over its existing owner connection; E2B uses
-the SDK's streaming file download. Participant tools cannot request arbitrary files.
-
-Local recording uses the existing optional media runtime archive. This keeps the
-browser-only download unchanged, but the optional archive also contains speech
-assets even when speech is disabled. Recording alone does not start Whisper or
-text-to-speech. E2B's stock desktop already has the recording dependencies; a custom
-template must provide compatible FFmpeg, X11 and, for audio, PulseAudio tools.
-
-Observer uses the existing study clock to play the selected participant's video.
-Scrubbing, opening a participant and returning to the grid preserve study time.
-The grid continues to show lightweight captures; only the selected participant
-has audible playback. Outside the retained media interval, Observer shows that
-video is unavailable rather than extending its coverage. Old screenshot-only runs
-continue to work.
-
-Capture still begins after device and transport startup. An audio track can contain
-silence before a cold source delivers sound; early dispatch of speech or playback
-does not itself prove audible capture. Preserve these offsets when reviewing early
-events. The startup correction does not reconstruct missing frames or audio in
-existing files. Variable guest execution stalls can still leave frame gaps; the
-recorded timestamps preserve those gaps. A regularly timestamped video can also
-show an unchanged screen while the application stalls. Visual/audio event timing
-depends on source delivery and guest execution; timestamp precision does not
-guarantee simultaneous delivery. See #854 for the remaining investigation.
-
-The file and its measured interval are recorded in `streams[].recording` and a
-`recording` artifact entry. A recorder failure warns and preserves screenshots,
-actions and feedback; it does not fail an otherwise useful participant. Incomplete
-but playable media is labeled partial. Forced VM loss may leave no retrievable
-video. Analysis continues to use the existing screenshot and text evidence; it
-does not inspect the MP4.
-
-## Local evidence and exports
-
-Video and audio are raw local evidence. `policies.redactScreenshots` does not redact
-them, and verification keeps a run with continuous media `local_only`. The recorder
-has a 128 MiB per-participant file limit; a retained size-limited recording is partial.
-Encoding consumes additional CPU, memory and disk, so snapshots remain the default.
-
-`humanish export --local-only` produces the existing portable HTML with screenshots
-and text, excludes continuous media and displays that exclusion. Open the original
-run through `humanish watch` or `humanish serve` to play its video. Redacted bundle
-export does not redact video/audio and rejects these runs. There is no new portable
-video format or automatic audio/video redaction in this feature.

package/docs/architecture/local-browser-runtime.md

@@ -1,178 +0,0 @@
-# Local browser studies
-
-Linux x64 and supported Apple Silicon Mac users can run isolated Firecracker
-browser participants from the installed CLI or TUI. Docker manages their
-containers and private state volumes; the normal study runner supplies
-scheduling, recordings, Observer and findings.
-No separate host service is installed.
-
-## Start a study
-
-Both platforms need a signed-in, supported Codex CLI. Linux needs a local,
-rootful Docker Engine, KVM (`/dev/kvm`) and TUN (`/dev/net/tun`). Macs need an
-M3-or-newer chip, native ARM64 Node, Lima 2.2+ (`brew install lima`) and a macOS
-version supporting nested virtualization; see [Mac setup](#apple-silicon-macs).
-Docker Desktop is unnecessary. See
-[Codex account setup](restricted-codex-analysis.md) for the qualified version
-and account restrictions. Docker access is an administrative capability.
-humanish does not install Docker on Linux or change host permissions. On Mac,
-setup installs Docker only inside the dedicated Lima host.
-
-Configure the starter while initializing the project, then start your app on
-the same loopback URL:
-
-```sh
-npx humanish init --yes \
-  --local-browser http://127.0.0.1:3000 \
-  --local-mission "Create a note and explain anything confusing about saving it"
-npx humanish doctor --lab local-browser
-npx humanish run local-browser
-npx humanish verify
-```
-
-`verify` checks the saved run bundle, and its share-safety line says whether the evidence can be
-shared as-is. `init` also adds `humanish:*` scripts to `package.json`; `humanish:run` among them
-is `humanish run --dry-run`, a contract-proof dry run rather than this live study. `init` also
-writes `humanish/labs/local-browser.yaml` with safe defaults when the two options are omitted.
-The options provide the normal setup path for the app URL and mission on first setup. If the
-file already exists, `init` preserves it and warns that these options were skipped; edit the
-existing manifest to change its URL or mission. The commands above write this lab (its
-`description` is omitted here):
-
-```yaml
-schema: humanish.lab.v2
-id: local-browser
-title: Local browser · your app · Codex account
-subject:
-  source: app-url
-  appUrl: "http://127.0.0.1:3000"
-actors:
-  - type: local-agent
-    localAgent: codex
-    persona: synthetic-new-user
-    mission: "Create a note and explain anything confusing about saving it"
-execution:
-  target: local
-  concurrency: 1
-  timeoutMs: 120000
-scenario:
-  mode: live
-defaults:
-  open: true
-```
-
-```sh
-npx humanish runtime status --json
-npx humanish doctor --lab local-browser --json
-npx humanish run local-browser
-npx humanish verify
-```
-
-The first live run downloads the pinned runtime archive (about 569 MiB on x64 or
-556 MiB on ARM64), verifies its exact size and SHA-256, and loads it into Docker.
-Later runs reuse the image.
-`humanish runtime setup` prepares it in advance. Status, doctor and dry-run never
-download an image or launch a participant. Preparation does not consume the
-participant's task-time budget. The TUI lists the same lab and runtime readiness;
-starting it uses the same preparation and execution path.
-
-This configuration needs neither an E2B key nor an OpenAI API key. Participants
-and the separate post-run analyst use Codex account quota and **remote model
-inference**. It is not an offline model. The restricted participant has no host
-shell, checkout mount or credential files. Account dollar cost and output-token
-ceilings are unknown; numeric dollar/token caps are rejected. Set
-`review.analysis: false` to skip analysis.
-
-For API billing and its supported caps, use `type: openai-computer-use`, remove
-`localAgent`, and provide `OPENAI_API_KEY`. Its analysis retains the existing API
-default. Neither path silently falls back to another provider or hosted desktop.
-Existing labs without `execution.target: local` retain their previous behavior.
-
-Before handing the desktop to the participant, the guest opens the
-selected app and waits up to 30 seconds for the initial document's
-`DOMContentLoaded` event, then allows a bounded paint. It does not wait for app
-data, images or network idle: the app's own loading screen remains observable.
-Navigation failures and timeouts fail startup and release the owned desktop.
-Later participant actions and observations do not use this startup wait.
-
-## Current limits
-
-- Linux x64 or M3-or-newer Mac with native ARM64 Node and Lima. Linux ARM64 is
-  refused: the local participant, the restricted Codex participant, runs only on
-  Linux x64 and Apple-silicon macOS. The installed Mac setup was tested on an M5
-  Max; smaller machines are not capacity-qualified.
-- On Linux, a local Docker Engine; remote contexts, rootless Docker and Docker
-  Desktop are unsupported. The Mac adapter uses Docker inside its own Lima host.
-- Loopback HTTP(S) app URLs on explicit ports above 1023. Each participant can
-  reach its selected app port, its assigned captured inbox when declared, and public destinations over ordinary TCP/UDP.
-  Other private host/LAN destinations and cloud metadata are blocked.
-- Chromium at 960×720, 2 vCPUs and 2 GiB guest RAM per participant. Docker's
-  enclosing memory limit is 3 GiB. Start with a small concurrency for your host;
-  these allocations are not a promise of measured peak memory or capacity.
-- Browser-only by default. [Optional camera and spoken conversation](participant-media.md)
-  use a separate media image and the same study loop.
-- [Captured inboxes](comms-inbox.md#local-browser-studies) use an operator-run mail catch.
-  Real email receiving remains unsupported on the local route.
-- A 20-minute default and maximum participant session budget, within the runtime
-  image's 30-minute process lifetime. A shorter `execution.timeoutMs` is supported.
-- Codex participants currently use `gpt-6-astra` at low effort. Hosted templates,
-  device presets and hosted sandbox timeouts do not apply.
-
-Normal close and cooperative startup cancellation remove the owned container
-and its private state volume. After a desktop connects, controller death
-disconnects the guest, which reboots; Firecracker exits and Docker removes both.
-A small host socket directory can remain after abrupt death.
-Run evidence remains in `.humanish/` under the normal local capture and sharing
-rules. An unconfirmed release is reported as such.
-
-## Runtime maintenance
-
-The npm build pins a release URL, byte count, SHA-256 and immutable Docker image
-ID in `src/substrates/local/runtime-release.ts`. It has no moving `latest` image dependency.
-Runtime releases include source archives and notices separately; study users do
-not download those archives. Updating a runtime requires a reviewed catalog
-change and a new CLI release.
-
-Source builders can use the
-[maintained recipes](https://github.com/danielgwilson/humanish/blob/main/runtime/local-firecracker/README.md) and set
-`HUMANISH_LOCAL_RUNTIME_IMAGE` to an already-built compatible local image. An
-invalid override fails; it does not cause an implicit registry pull.
-
-## Apple Silicon Macs
-
-The Mac adapter uses a dedicated `humanish-runtime` Lima/VZ host on M3 or
-newer Macs, with Lima 2.2+ and macOS supporting nested virtualization. Docker
-runs inside that host; Docker Desktop is unnecessary. Setup creates the host
-with 6 CPUs, 8 GiB RAM and an 80 GiB growable disk. It mounts no Mac directories.
-Start with two participants; larger concurrency has not been qualified by this
-integration. Use Lima's normal resource configuration for subsequent capacity
-experiments, without changing study concurrency behind the user's back.
-
-The scheduler and study loop remain shared. Standard OpenSSH forwards the
-browser-control Unix socket to the Mac, and the selected app port back into the
-Linux host. It preserves HTTP(S)/WebSocket bytes without parsing them. Codex
-runs on the Mac and retains the same separate participant/analyst profiles and
-file-backed login requirement. Keychain-only authentication is not supported.
-
-The installed CLI passed first-attempt public image setup and two-participant
-studies on an M5 Max: distinct app-side saves, overlapping participants,
-verified recordings and automatic account analysis. A fresh Lima instance used
-the public ARM64 catalog without a development image override. The separately
-available source archives match that native build. The manually dispatched ARM64
-job in `browser-appliance-proof.yml` builds images and sources; compilation alone
-does not establish Mac execution.
-
-Status and doctor do not create or start Lima. Explicit setup/first live use
-starts the owned host; closing a study removes its participant containers and
-volumes, but keeps the reusable Lima host running. Stop it with
-`limactl stop humanish-runtime` when no studies are running. An interrupted
-first provision remains inspectable through Lima and can be retried. humanish
-does not replace a conflicting instance or stop unrelated instances.
-
-Normal close, cancellation and controller death were exercised on established
-Mac desktops. Shared startup cancellation and interrupted create-reply recovery
-were exercised against real Linux Docker/Firecracker, with a separate regression
-check for Lima cleanup. Forced controller death during startup, full-study
-cancellation, host sleep/wake and higher concurrency remain unqualified. A forced
-kill before a desktop connects can leave resources requiring inspection; this
-adapter adds no suspend detector that unconditionally destroys a study.

package/docs/architecture/observer-review.md

@@ -1,144 +0,0 @@
-# Watching and reviewing evidence
-
-Observer shows a study's participants, their recorded screens, and the events
-that explain those screens. The grid, player and exported HTML use the same
-current renderer. Screens fit their actual aspect ratio; a portrait capture is
-never cropped to fill a wide tile.
-
-## Choose the right entry point
-
-`humanish watch <lab>` starts a study and keeps its viewer attached. The process
-that owns a hosted desktop can offer its live stream while it runs. `--no-open`
-keeps that attachment without launching a browser. `--json` is the machine-result
-path and does not keep an interactive stream server attached.
-
-`humanish observe --run <id>` opens an existing study without starting another. The
-TUI's **Open in Observer** action does the same through its session-owned loopback
-library. These entry points follow saved captures; they cannot recover live desktop
-credentials owned by another process. Keep the owning CLI or TUI open while using its
-viewer. Exported HTML is an independent offline recording.
-
-## Read status without guessing
-
-The top band separates the run's current status from evidence freshness. A
-finished study never uses its execution mode (`live`, as opposed to `dry-run`)
-as a claim that it is still running. When updates fail, the last usable evidence
-stays visible, the band reports the failure, and **Retry** requests another
-snapshot. A stale process heartbeat does not prove that the process died.
-
-A player's **Live desktop** label identifies what it displays. An iframe loading
-is not a connection-health signal: the provider owns that connection. **Reload
-stream** reloads the desktop viewer without restarting a participant. **Latest capture**
-follows the latest saved screenshot without a desktop stream. **Replay** means
-the researcher has chosen a recorded moment. Offline exports say so explicitly.
-
-Freshness uses recorded activity and capture timestamps, not the time the server
-reserialized the same data. Browser tabs poll less frequently while hidden and
-refresh when visible again. Requests are serialized, bounded by a timeout and
-cancelled when the viewer closes.
-
-## Work through a study
-
-Previews share a height and wrap into rows; desktop cards are wider and portrait
-cards narrower. Complete screens remain contained when the available width is
-smaller than a preview. Sparse rows keep their chosen size. Open **View and filter
-participants** in the top right to search, change **Preview size**, or enter
-**Monitor** for a larger evidence area. **Exit monitor** stays beside the run status.
-Open a card's **Participant details** to **Pin** it at the beginning. Ordering changes only
-when the researcher changes it. Large studies have reachable participant pages.
-At most four desktop previews attach in the grid; allocation prioritizes screens
-that are actually visible, with the hovered or keyboard-focused participant taking
-priority. Other cards show their latest saved capture.
-
-Each card follows its screen's aspect ratio without a minimum width that adds
-portrait gutters. Its 44px caption holds the participant name, a short preview
-source (**Live**, **Capture**, or **Snapshot**) or finished outcome, and a stable
-**Participant details** button. Labels and controls never cover captured pixels.
-Details contains labeled **Pin** and **Compare** toggles, the full source and
-freshness, final messages, recorded notices, duration and dimensions. Historical
-notices do not turn the details control into a warning; exceptional outcomes
-remain in the caption. Comparison permits three participants and explains the
-limit while keeping selected participants removable.
-
-Icon buttons use Lucide glyphs, accessible names, hover/focus hints and visible
-keyboard focus. Touch targets expand to 44px. Popovers have explicit close buttons;
-Escape dismisses a hint without moving the player. These conventions follow
-[Carbon icon usage](https://carbondesignsystem.com/elements/icons/usage/),
-[ARIA toggle-button semantics](https://www.w3.org/WAI/ARIA/apg/patterns/button/),
-and [WCAG target sizing](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
-The bookmark icon in the top bar opens **Saved moments**; recalling an available
-moment closes the popover, while an unavailable moment leaves the error visible.
-
-Opening a participant provides elapsed-time seeking, the original frame number,
-playback speed, **Fit**, **Actual size**, zoom/pan and fullscreen. The inspector can
-be hidden or resized. Click markers use the recorded desktop coordinate system
-and the image's rendered rectangle, including at zoomed sizes.
-
-Arrow keys, mouse controls, same-participant links, browser navigation and reload
-agree about the selected moment. Seeking leaves live mode. Pausing on the newest
-frame stays paused when new evidence arrives; **Go live** explicitly resumes
-following. A missing addressed moment is reported instead of silently replaced.
-
-Screenshot playback is sparse evidence, not a video recording. Capture gaps stay
-visible. **Skip waits** compresses intervals associated with recorded waits and
-reports the skipped duration. **Next action**, **Next flagged frame**, activity
-filters and grouped waits make long traces easier to inspect without deleting events.
-Older unstamped recordings use labeled estimated pacing. Long feeds, filmstrips,
-terminal output and event lists stay bounded while earlier/later content remains
-reachable.
-
-**Copy moment link** creates a frame address; denied clipboard access exposes a
-selectable link. **Original frame** opens/downloads the captured raster. **Saved
-moments** keeps bounded run/participant/frame identifiers in this browser. It does
-not save credentials, publish annotations or change the evidence bundle. Storage
-failure leaves the controls usable for the current visit.
-
-## Compare recorded evidence
-
-Select participants and open **Compare selected**. Capture-time alignment chooses
-the latest frame at or before the cursor, never a future frame. Before/after
-coverage and each frame's age are explicit. Clock differences between desktops
-remain an uncertainty; matching timestamps alone do not establish causality.
-
-Elapsed-time alignment starts each participant at its first capture and compares
-progress rather than simultaneous events. Missing or descending timestamps cannot
-be used as a shared clock. Another run can be loaded from the available library
-as recorded evidence. The address retains the chosen runs, participants, clock
-and cursor so reopening it restores the comparison.
-
-## Boundaries and checks
-
-Only the attached process can grant a desktop iframe its own origin for provider
-module loading. Stored grants are removed, exports contain no runtime grants,
-and every local viewer response refuses to be framed. Generic imported embeds
-retain an opaque sandbox. Artifact and history links cannot introduce arbitrary
-URL schemes or traverse outside their evidence roots.
-
-`pnpm observer:browser:proof` exercises generated synthetic evidence in the
-production artifact. `pnpm observer:iframe:proof`, after `pnpm build`, checks the
-actual serving boundary against direct, redirected and scripted iframe attacks.
-CI retains their screenshots and JSON receipts. These Chromium checks do not
-claim physical-device or non-Chromium coverage. Actual provider checks and their
-resource-cleanup receipts are separate acceptance evidence.
-
-Interaction references rechecked September 8, 2026:
-[Base UI popover](https://base-ui.com/react/components/popover),
-[React state structure](https://react.dev/learn/choosing-the-state-structure),
-[WAI-ARIA tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/),
-[iframe sandboxing](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe),
-[Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer), and
-[PostHog recording controls](https://posthog.com/docs/session-replay/how-to-watch-recordings).
-
-### Moving between review views
-
-The library button opens a drawer while reviewing a participant or comparison,
-including on desktop. Comparison panels use the same participant names as the
-grid. **Open frame** opens the displayed capture in the player, where it can be
-saved; **Back to comparison** restores that comparison's selection, alignment and
-cursor. Browser Back also returns to the addressed comparison. Comparing another
-run needs a free slot within the three-participant limit.
-
-**Reported thinking** is an explicit filter; the Thinking checkbox controls only
-All evidence. **Warnings & findings** includes a separate Run and setup notices
-section. These recorded operational notices retain their source timestamps and
-are not assigned invented screenshot positions or counted as participant findings.