humanish 0.107.0 → 0.108.0

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.

package/docs/architecture/participant-media.md

@@ -1,90 +0,0 @@
-# Optional participant media
-
-Media belongs to the desktop. The participant still works through screenshots
-and the shared computer-use loop, using one continuing Codex conversation for
-clicks, listening and spoken replies.
-
-```yaml
-actors:
-  - type: local-agent
-    localAgent: codex
-execution:
-  target: local
-  desktop:
-    media:
-      camera: { source: synthetic }
-      microphone: { source: speech }
-policies:
-  mediaPermission: prompt
-```
-
-Omit `media` and `recording` for ordinary browser studies. They keep the smaller
-browser image and start no audio server, camera producer or speech worker. Camera and speech
-can also be requested separately. Local media setup uses a separately pinned
-image, prepared by the first live study or `humanish runtime setup --media`.
-
-The local camera is an animated test pattern behind a native V4L2 device. Speech
-uses a synthetic microphone and a separate speaker sink. Chromium uses its
-ordinary devices and permission dialog. `mediaPermission: granted` bypasses the
-dialog explicitly; it does not replace the devices.
-
-## Speaking and listening
-
-With speech enabled, `humanish_ui` accepts `{kind: "speak", text: "..."}` in
-addition to browser actions. It plays into the microphone; the participant must
-join and unmute through the app. Tool narration is never automatically spoken.
-Keep each utterance within 400 characters. Playback acknowledgement establishes
-local microphone input, not delivery to another caller.
-
-The desktop captures actual speaker audio. Finalized English transcriptions
-arrive as `heardSpeech` observations with an utterance ID, `speaker_audio` source
-and duration. A participant can use the existing `wait` action while listening.
-Hearing something counts as progress even when the screen stays unchanged.
-
-Transcription and synthetic speech run inside the Linux desktop, without a
-speech API key or a host Python installation. Codex inference still runs remotely
-using the selected account. The first voice uses espeak-ng and sounds robotic;
-whisper.cpp uses the pinned English `base.en` model for recognition. This is bounded turn-taking, with recognition
-latency and possible transcription errors, not a streaming voice conversation
-with interruption handling.
-
-Spoken text and heard observations pass through the existing evidence redaction
-before being retained in the trace. Analysis reads that evidence alongside screenshots and actions; it does not
-inspect raw audio or video. Raw audio is not saved by default. [Optional desktop recording](desktop-recording.md)
-can retain actual screen and audio playback alongside this evidence.
-
-## Hosted desktops
-
-The same worker and participant loop support hosted speech. humanish selects a
-versioned public E2B media template when speech is requested; ordinary browser
-studies keep the stock desktop. The usual E2B credentials and Codex login are
-sufficient. `execution.desktop.template` remains an explicit override for your
-own compatible image; see the [build recipe](https://github.com/danielgwilson/humanish/blob/main/runtime/browser-media/E2B.md).
-The host starts the worker through the SDK's streaming command interface, and
-model credentials stay on the host. Missing dependencies fail desktop preparation
-before a participant starts.
-
-Existing hosted synthetic cameras use Chromium's fake-device flags. Those flags
-also replace its microphone, so hosted camera and speech cannot currently be
-combined. Use a local native-media desktop for both, or a hosted audio-only
-study. Microphone files and speech through other participant providers are not
-supported. A template alone cannot add camera support to a kernel without V4L2.
-
-## Runtime maintenance
-
-`runtime/local-firecracker/build.py --media` extends the maintained browser image
-with native devices and the speech worker. The published media image must carry
-`to.humanish.runtime.media=1`; a cached browser image cannot satisfy a media
-request. Source builds can select an already-built media image with
-`HUMANISH_LOCAL_MEDIA_RUNTIME_IMAGE`.
-
-The media worker owns its subprocesses and buffers. Failed speech recognition,
-worker exit and queue overflow stop the media session instead of appearing as
-successful silence. Closing the desktop stops media and reclaims its isolated
-state. No conferencing vendor or room-specific behavior is implemented in core.
-
-Retain the matching media sources and package notices when publishing runtime
-assets. Pass `--media-browser` and `--media-inputs` to the existing
-`runtime/local-firecracker/sources.py` collector alongside its ordinary inputs.
-Hardware capacity and conferencing topology require their own measured proof;
-requesting media does not qualify twenty concurrent participants or TURN.

package/docs/architecture/project-layout.md

@@ -1,62 +0,0 @@
-# Project Layout
-
-`humanish init` gives a project two roots:
-
-```text
-humanish/   # committed lab source
-.humanish/  # ignored runtime state, evidence and local overrides
-```
-
-## Committed lab source: `humanish/`
-
-`init` writes:
-
-```text
-humanish/
-  README.md
-  labs/
-    first-run.yaml          # keyless preview
-    try-live.yaml           # first live lab
-    cua-browser.yaml        # computer-use participants on a hosted desktop
-    local-browser.yaml      # computer-use participants on a local desktop
-    lobby-trivia-3player.yaml
-  personas/
-    synthetic-new-user.yaml
-    skeptical-power-user.yaml
-  scenarios/
-    first-run-smoke.yaml
-    onboarding-regression.yaml
-  coverage-map.md
-  coverage-matrix.md
-```
-
-Labs select their subject, actors, personas, scenarios, tasks, budgets and
-policies. Personas and scenarios are referenced by id. An adopter scorer is an
-`.mjs` module that a lab names under `review.scorer.ref`.
-
-Keep this directory reviewable and reproducible from a clean clone. Everything in
-it is public-safe: synthetic personas and fixtures, env var names without values.
-
-## Ignored runtime state: `.humanish/`
-
-```text
-.humanish/
-  runs/           # run bundles, screenshots, transcripts, Observer output
-  labs/           # private labs; a committed lab with the same id wins
-  local/labs/     # machine-local labs
-  local/personas/ # machine-local personas; a committed persona with the same id wins
-  cache/ tmp/ logs/
-```
-
-Never commit run bundles, raw screenshots, transcripts, local overrides or
-secrets. `init` adds `.humanish/` to `.gitignore`.
-
-## Formats
-
-- `.yaml` for human-authored source: labs, personas, scenarios.
-  Prefer `.yaml` over `.yml`.
-- `.mjs` for executable adopter scorers.
-- `.json` for generated artifacts and synthetic fixtures; `.ndjson` for
-  appendable event and transcript streams.
-- `.yml` only where an outside tool expects it, such as
-  `.github/workflows/*.yml`.

package/docs/architecture/real-email-receiving.md

@@ -1,136 +0,0 @@
-# Real email receiving
-
-A supported browser study can give each participant a fresh AgentMail inbox. The
-application sends real email to that address; humanish polls it on the host and
-publishes a private inbox surface on that participant's desktop. The participant
-can read the original email, switch to a plain view and follow an approved link.
-
-Use local capture when you can redirect the app's send configuration and want to
-avoid hosted mail. Use real receiving when the app must send normally or delivery
-itself is part of the flow. These are separate modes; do not combine their settings.
-SMS and participant outbound mail are not supported.
-
-## Setup
-
-Open `humanish tui`, press **c** for Connections, and choose **Add API key** to add an
-AgentMail key. Hidden entry saves it in the existing user key store and checks
-authentication without creating an inbox; Ctrl+C cancels entry and returns to the TUI.
-The project profile, `.humanish/local/comms.yaml`, stores only the provider and
-environment-variable name.
-Environment and explicit env-file values retain precedence over saved keys.
-A rejected or unavailable authentication check does not delete the saved key.
-Authentication does not prove inbox creation/deletion permissions, quota or delivery.
-This release requires an organization-scoped key.
-
-Connections can preview and save a receiving-enabled local lab copy. The preview
-discloses hosted email, model processing, local review and separate provider charges.
-The original manifest is preserved. Select the new exact path when launching.
-
-The same operations are available to agents:
-
-```bash
-humanish keys set agentmail
-humanish comms connections add agentmail --json
-humanish comms check --online --json
-humanish comms configure --lab humanish/labs/signup.yaml --json
-# Review the returned path, disclosures and planToken, then:
-humanish comms configure --lab humanish/labs/signup.yaml --apply --plan-token <digest> --json
-humanish lab run .humanish/local/labs/signup-receiving.yaml --json --no-open
-```
-
-Direct manifest authoring selects a saved connection:
-
-```yaml
-comms:
-  email:
-    connection: agentmail
-    # Optional: additional trusted email-link destinations, exact origins only.
-    allowedOrigins:
-      - https://accounts.example.test
-```
-
-The target origin is automatically allowed. On provisioned subjects, the declared
-serve origin and optional `linkOrigin` use the existing target-origin rewrite.
-Review additional origins as destinations the participant is allowed to open from
-mail. This policy governs the inbox surface, not all later browser navigation.
-
-Supported execution is hosted computer use with app-url, clone or local-tree
-subjects, including shared-world studies. Local-agent, scripted, terminal, desktop-cli, in-process and local-app routes reject
-real receiving before allocation. Connection mode cannot declare capture options,
-recipients or borrowed mailbox IDs. A fresh address is not an existing account;
-assignments must allow signup or arranging mail to the new identity.
-
-## What a run does
-
-1. Resolve the selected connection and host credential. Reject forwarding that
-   management credential through target environment names, aliases or literals.
-2. Authenticate and durably record each acquisition intent in private host state.
-   Acquire all participant addresses before starting desktops.
-3. Give each participant its address and loopback inbox URL. No management key or
-   other participant's mailbox is installed in its desktop. Each surface has only
-   its own list/message/plain/JSON routes, with no send endpoint or aggregate inbox.
-4. Poll received mail, register scrub targets, sanitize/render and atomically
-   publish the complete inbox snapshot. Repeated reads can fill temporarily missing
-   bodies and inline images without changing local message identity.
-5. Before desktop teardown, perform a bounded final read, save evidence, stop the
-   inbox surface and request deletion. Confirm provider absence; otherwise retain
-   unresolved cleanup for recovery. Provider deletion is not an erasure guarantee.
-
-The original view preserves supported email structure and inline PNG/JPEG/GIF/WebP
-images. Parsed HTML removes active content; response CSP blocks scripts, forms,
-frames and remote assets. Remote images show an explicit unavailable placeholder.
-Links use the same origin policy in original, plain and JSON views. Attachment
-bytes are fetched only through the fixed provider API and its observed CDN host;
-provider authorization never goes to the CDN. General attachments, arbitrary remote
-images and raw-MIME fallback are unsupported. Raster checks are bounded signature
-checks, not a guarantee that every malformed image will decode in a browser.
-
-Collection is bounded by request time, request/page count, bytes, images and a
-100-message retained inbox limit. Limits, failed reads, blocked content and failed
-publication are recorded as coverage limitations. Inbox pages require reload to
-show later messages. No webhook/public mail ingress is required on the host.
-
-## Evidence and publication
-
-`comms/receiving.json` uses `humanish.comms-receiving.v2`. It records local IDs,
-counts, timestamps and lifecycle/coverage status, without raw mail, provider IDs,
-addresses or stable content digests. The final run bundle embeds that projection.
-Receipt, successful inbox publication, participant reading and target success are
-separate claims; analysis receives this distinction and the harness limitations.
-A missing message alone does not establish that the application failed to send.
-Immediate automatic analysis scrubs known exact values from generated narration
-using a bounded, invocation-local registry. It never saves that registry. Later
-analysis cannot reconstruct it; screenshots may still expose mail content, and the
-publication restriction applies to both immediate and later findings.
-
-Mail is hosted by AgentMail. Its content can reach the hosted desktop, actor model,
-screenshots, narration and analysis model. Such runs carry a durable
-`real-communications` publication restriction: verification returns `local_only`,
-public feedback/exposure and shareable exports remain gated, and screenshot
-blurring does not clear the restriction. Local Observer review and explicitly local
-HTML export remain available. Local-only publication is not local-only processing.
-
-## Interrupted-run recovery
-
-Process interruption can bypass normal final reads and teardown. Inspect recovery
-state after stopping a run; do not assume Ctrl+C or killing a process deleted its
-inboxes:
-
-```bash
-humanish comms recover --json
-humanish comms recover --run <run-id> --apply --json
-```
-
-Connections also exposes pending cleanup. Recovery only uses private host journals
-under `$XDG_STATE_HOME/humanish/comms` (default `~/.local/state/humanish/comms`),
-with private directories/files and bound project, connection, account and scope.
-A live or unknown owner blocks takeover. The adapter checks resource/client identity
-before deletion; it cannot delete an inbox named only in a run artifact. Lost
-creation responses can be reconciled through the recorded idempotent client ID.
-Do not delete private journals while resources remain unresolved. Moving/replacing
-the project or changing account/scope can intentionally prevent recovery.
-
-If final evidence persistence fails, the provider inbox is retained as unresolved
-rather than discarding the last retrievable copy. Explicit recovery is a deletion
-operation, not message-history reconstruction. Sandbox reclamation remains a
-separate operation.