humanish 0.95.0 → 0.96.0

package/dist/tui-contract.d.ts

@@ -7,6 +7,8 @@ import type { TuiProjectState } from "./tui-project.js";
 import type { ReadRunIndexOptions, RunIndexResult } from "./run-index.js";
 import type { LaunchRunOptions, LaunchRunResult } from "./tui-launch.js";
 import type { CommsSetupResult, CommsSetupStatus } from "./comms-connections.js";
+import type { CommsCheckResult, CommsConfigureResult } from "./comms-setup.js";
+import type { CommsRecoveryEntry } from "./comms-receiving.js";
 /** The humanish version string shown in the frame, so a screenshot in a bug report is datable. */
 export interface TuiVersionInfo {
     cli: string;
@@ -21,6 +23,17 @@ export interface TuiCapabilities {
     comms?: {
         read(): Promise<CommsSetupStatus>;
         save(): Promise<CommsSetupResult>;
+        check?(): Promise<CommsCheckResult>;
+        labs?(): Promise<{
+            title: string;
+            path: string;
+        }[]>;
+        configure?(lab: string, apply: boolean, planToken?: string): Promise<CommsConfigureResult>;
+        recovery?(): Promise<CommsRecoveryEntry[]>;
+        recover?(runId: string, connectionName: string): Promise<{
+            ok: boolean;
+            message: string;
+        }>;
     };
     /** Read every run in the project, cheapest source first. */
     readRunIndex(cwd: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;

package/dist/tui-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"tui-contract.js","sourceRoot":"","sources":["../src/tui-contract.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,gGAAgG;AAChG,mGAAmG;AACnG,6DAA6D;AAC7D,EAAE;AACF,mGAAmG;AACnG,mBAAmB;AAyGnB,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,gBAAwB,OAAO,CAAC,OAAO;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,kBAAkB,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAKtC;IACC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,+BAA+B,kBAAkB,cAAc,KAAK,CAAC,WAAW,mCAAmC,CAAC;IAC7H,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,OAAO,8GAA8G,CAAC;IACxH,CAAC;IACD,OAAO,KAAK,CAAC,WAAW;QACtB,CAAC,CAAC,yEAAyE;QAC3E,CAAC,CAAC,kJAAkJ,CAAC;AACzJ,CAAC"}
+{"version":3,"file":"tui-contract.js","sourceRoot":"","sources":["../src/tui-contract.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6FAA6F;AAC7F,mGAAmG;AACnG,+EAA+E;AAC/E,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,gGAAgG;AAChG,mGAAmG;AACnG,6DAA6D;AAC7D,EAAE;AACF,mGAAmG;AACnG,mBAAmB;AAgHnB,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,gBAAwB,OAAO,CAAC,OAAO;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,kBAAkB,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAKtC;IACC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,+BAA+B,kBAAkB,cAAc,KAAK,CAAC,WAAW,mCAAmC,CAAC;IAC7H,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,OAAO,8GAA8G,CAAC;IACxH,CAAC;IACD,OAAO,KAAK,CAAC,WAAW;QACtB,CAAC,CAAC,yEAAyE;QAC3E,CAAC,CAAC,kJAAkJ,CAAC;AACzJ,CAAC"}

package/dist/tui-launch.d.ts

@@ -4,6 +4,8 @@ export interface LaunchRunOptions {
     cwd: string;
     /** The manifest handle (filename stem), as `humanish lab run` takes it. */
     lab: string;
+    /** Exact selected manifest, avoiding a same-name committed lab shadowing a local copy. */
+    manifestPath?: string;
     mode: "dry-run" | "live";
     /** Injected in tests; defaults to the real spawn. */
     spawn?: typeof spawn;

package/dist/tui-launch.js

@@ -15,6 +15,7 @@ import { constants as fsConstants } from "node:fs";
 import { open } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveLabManifest } from "./labs.js";
 import { prepareManagedHumanishOutputDirectory } from "./selected-output-paths.js";
 /**
  * A lab handle is the manifest FILENAME, which is what `humanish lab run` resolves. Restricted to
@@ -49,6 +50,13 @@ export async function launchRun(options) {
         };
     }
     const cwd = path.resolve(options.cwd);
+    let selectedLab = options.lab;
+    if (options.manifestPath !== undefined) {
+        const resolved = await resolveLabManifest(cwd, options.manifestPath);
+        if (!resolved.ok)
+            return { ok: false, error: { code: "HUMANISH_LAUNCH_INVALID_LAB", message: "The selected lab path could not be read safely. Refresh the lab list." } };
+        selectedLab = path.relative(cwd, path.resolve(cwd, resolved.path)).replace(/\\/g, "/");
+    }
     const now = options.now ?? (() => new Date());
     const spawnFn = options.spawn ?? spawn;
     const launchedAt = now().toISOString();
@@ -88,7 +96,7 @@ export async function launchRun(options) {
         ...(options.mode === "dry-run" ? ["--dry-run"] : []),
         // `--` ends option parsing, so the handle can only ever be read as the positional argument.
         "--",
-        options.lab
+        selectedLab
     ];
     const spawnOptions = {
         cwd,

package/dist/tui-launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"tui-launch.js","sourceRoot":"","sources":["../src/tui-launch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tui-launch.js","sourceRoot":"","sources":["../src/tui-launch.ts"],"names":[],"mappings":"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"}

package/docs/architecture/comms-inbox.md

@@ -1,5 +1,9 @@
 # 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,

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

@@ -0,0 +1,135 @@
+# 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**, and add an AgentMail key. Hidden entry saves it
+in the existing user key store and checks authentication without creating an inbox.
+The project profile 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 concurrent shared-world studies. Sequential shared-world,
+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.

package/docs/contracts/run-bundle.md

@@ -468,7 +468,7 @@ bundle is safe to promote into a public issue. Public promotion should branch on
 `shareSafety.status`:
 
 - `share_ready`: feedback draft commands may render public issue payloads;
-- `local_only`: keep the run local or generate a redacted replacement bundle;
+- `local_only`: keep the run local; only supported redaction-only cases can produce a shareable derivative;
 - `blocked`: fix the verification or public-safety failure first.
 
 The local-evidence check includes screenshots declared only by
@@ -487,6 +487,14 @@ over a blurred declaration. Missing or unknown per-frame metadata retains the
 existing permissive compatibility behavior; verification does not infer pixel
 privacy from that absence.
 
+Real email receiving adds `publication.restrictions: [real-communications]` and
+an optional `commsReceiving` projection using `humanish.comms-receiving.v2`.
+Either field contributes `REAL_COMMUNICATIONS` and keeps the run `local_only`.
+This applies to interrupted bundles and after screenshot blurring: real mail can
+appear in text and analysis as well as pixels. Malformed receiving metadata fails
+bundle validation. The projection holds counts, local IDs and lifecycle/coverage
+status; private provider identities and cleanup authority are kept outside the run.
+
 ## Redacted Derivative Workspace
 
 `humanish export --run RUN --format bundle --redact-screenshots --out DIRECTORY`

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.95.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.96.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.
@@ -325,7 +325,7 @@ connections:
     apiKeyEnv: AGENTMAIL_API_KEY
 ```
 
-Only AgentMail setup is currently supported. Connection names use lowercase
+AgentMail supports setup and fresh per-participant email receiving. Connection names use lowercase
 letters, digits and hyphens, beginning with a letter, up to 48 characters.
 `apiKeyEnv` names an environment variable; it never contains its value.
 Invalid fields, unsupported providers and unsafe filesystem paths are rejected.
@@ -336,7 +336,24 @@ profiles and local key presence/source, not provider authentication or delivery.
 `comms providers --json` returns `humanish.comms-providers.v1` with explicit
 setup/receiving availability. The key store accepts `humanish keys set agentmail`.
 Saving a connection neither modifies a lab nor creates a provider resource;
-`comms.email.connection` in a study remains unsupported and is rejected.
+a supported study explicitly selects `comms.email: { connection: agentmail }`.
+Optional `allowedOrigins` lists exact additional HTTP(S) origins; `linkOrigin`
+participates in the existing provisioned-subject origin rewrite. Connection
+selection cannot be combined with capture settings, recipients or provider options.
+The derived internal kind is `real`; do not write `kind` beside a connection.
+
+`comms check --online --json` returns `humanish.comms-check.v1`. Authentication,
+credential presence, unknown permissions/capacity and untested delivery are separate.
+`comms configure` previews/saves an ignored local manifest; `comms recover`
+inspects or explicitly recovers privately owned interrupted leases.
+
+Real receiving writes `humanish.comms-receiving.v2` count-only evidence with
+participant-local message IDs, observation/publication timestamps, limitations,
+acquisition and cleanup status. It contains no raw addresses, bodies, provider IDs
+or content digests. `run.json` embeds the final projection as `commsReceiving` and
+carries `publication.restrictions: [real-communications]`. Verification keeps the
+run local-only regardless of screenshot redaction. See the
+[receiving contract](../architecture/real-email-receiving.md).
 
 Lab backends report results in their own schemas (`humanish.run-result.v1`,
 `humanish.oss-lab-result.v1`, `humanish.oss-meta-lab-result.v1`,

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-20. Release baseline: `0.95.0`.
+Status date: 2026-09-21. Release baseline: `0.96.0`.
 
 This page guides work on current merged source. Published behavior is described
-in the [release notes](../release/0.95.0-connections-setup.md).
+in the [release notes](../release/0.96.0-real-email-receiving.md).
 The [September 9 history](https://github.com/danielgwilson/humanish/blob/main/docs/goals/current-history-2026-09-09.md)
 preserves the former status log; its queues do not supersede this page.
 
@@ -88,7 +88,7 @@ requires decision-equivalent retained evidence and a real deletion branch.
 No first-party deletion branch has met that gate. Public demonstrations do not
 substitute for it.
 
-## Current Program Truth (source `0.95.0`)
+## Current Program Truth (source `0.96.0`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -100,8 +100,8 @@ substitute for it.
 | Observer | Live/recorded views, shared grid and participant playback, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment |
 | Review and feedback | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication |
 | Study findings | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links | Model interpretation needs review; bounded selection and source truncation limit coverage; opening Observer never dispatches analysis |
-| TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail connection/key setup | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
-| Off-app communication | Recipient-scoped synthetic email inboxes, supported inline raster images, email capture and digest-only thread evidence | Scope prevents accidental cross-recipient browsing; it is not tenant authentication or real-provider delivery. AgentMail setup does not enable receiving; SMS is not a configured execution route |
+| TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail setup, authentication and lab configuration | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
+| Off-app communication | Recipient-scoped local capture and fresh real AgentMail receiving, supported inline raster images, bounded collection and host-owned recovery | Real mail uses isolated participant surfaces and remains local-only for publication. Hosted mail/model processing, bounded fidelity and interrupted-run recovery are explicit; local-agent, borrowed inboxes and SMS are unsupported |
 | Mobile and media | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed; a synthetic video-only call with separate hosted peers is proven | Audio, TURN, provider-specific rooms, physical-device and touch fidelity remain unproven; unsupported media declarations are rejected |
 
 Use the [task support matrix](../architecture/task-protocol-support.md),

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.95.0` (2026-09-20). 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.96.0` (2026-09-21). 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
@@ -47,10 +47,14 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
-The [0.95.0 release note](../release/0.95.0-connections-setup.md) describes
-AgentMail connection setup, hidden key entry and return to the TUI, matching
-CLI setup commands, and truthful credential status. Real email receiving is
-still unavailable; saved connections cannot be used in studies yet.
+The [0.96.0 release note](../release/0.96.0-real-email-receiving.md) describes
+fresh per-participant AgentMail inboxes, isolated desktop mail views, host-owned
+cleanup/recovery, local-only evidence publication, and authentication/configuration
+in Connections. SMS and local-agent receiving remain unsupported.
+
+The [0.95.0 release note](../release/0.95.0-connections-setup.md) introduced
+connection profiles and hidden key entry; 0.96.0 makes those connections usable
+in supported browser studies.
 
 The [0.94.0 release note](../release/0.94.0-reliability.md) describes analysis
 request deadlines and budget-aware output, smaller portable recordings,

package/docs/release/0.96.0-real-email-receiving.md

@@ -0,0 +1,47 @@
+# 0.96.0 — Real email receiving
+
+Supported browser studies can now give each participant a fresh AgentMail inbox.
+The application sends normally; participants open their own inbox, read the email
+and follow its confirmation link. Local capture remains a separate option for
+apps whose send configuration can point at a test catch.
+
+Connections checks authentication after hidden key entry and offers lab
+configuration and pending cleanup. Lab configuration previews a separate ignored
+copy, preserves the original, checks for stale previews and launches by exact
+selected path. Agents have matching `comms check`, `comms configure` and
+`comms recover` commands.
+
+Provider credentials remain on the host. Participants receive isolated loopback
+mail surfaces with original/plain views, supported inline raster images and a
+consistent allowed-origin link policy. Remote images and active HTML are blocked;
+missing content is explicit. Collection and publication are bounded and distinct
+from a participant reading mail. Later reads can fill temporarily missing content.
+
+Fresh mailbox ownership is recorded privately before acquisition. Normal teardown
+saves evidence and confirms provider deletion. Interrupted runs have explicit,
+project/account-bound recovery; mutable recording IDs cannot authorize deletion.
+Evidence-write failures retain the inbox as unresolved.
+
+Real mail may reach hosted desktops, actor/analysis models and recordings. These
+runs have a durable `local_only` publication restriction; blurring screenshots
+does not make them shareable. Immediate analysis uses the run's temporary scrub
+registry for generated narration, without saving raw secret values. Later analysis
+cannot reconstruct that registry and remains subject to the same publication gate.
+
+This release supports hosted computer-use app-url, clone and local-tree routes,
+including concurrent shared worlds. It rejects local-agent and unsupported routes
+before allocation. SMS, outbound participant mail, borrowed inboxes, arbitrary
+attachments and raw-MIME fallback remain unavailable.
+
+See [setup, behavior and recovery](../architecture/real-email-receiving.md) for
+configuration, processing disclosures and limits.
+
+Validation includes captured provider-wire contracts, crash/recovery and credential
+isolation tests, outer-runner tests for clone/local-tree and concurrent shared-world
+routes, inbox browser checks at desktop/phone widths, and hidden-key TUI proof.
+A retained live app-url study, `real-email-57ed0512-218d-4e58-9f76-c540541d0b56`,
+had two concurrent participants receive separate emails, follow their own links,
+reach the target dashboard and finish automatic analysis. Provider absence was
+confirmed for both participant inboxes and the synthetic sender. Raw mail and
+recordings remain private. This does not establish delivery for every target app
+or live-provider coverage of every execution route.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -94,6 +94,7 @@
   "homepage": "https://github.com/danielgwilson/humanish#readme",
   "dependencies": {
     "commander": "^14.0.3",
+    "parse5": "^8.0.1",
     "playwright-core": "^1.60.0",
     "pngjs": "^7.0.0",
     "undici": "^6.28.1",

package/skills/humanish/SKILL.md

@@ -49,7 +49,11 @@ project-local. Never ask for the key in chat. The CLI alternative is
 authorized credential source), followed by
 `humanish comms connections add agentmail --json`. Existing env/file precedence
 and `HUMANISH_STRICT_KEYS=1` still apply. Read installed provider capabilities:
-this release supports setup only, not authenticated checks or real email delivery.
+use `humanish comms check --online --json` for read-only authentication.
+Authentication does not establish mailbox permissions, capacity or delivery.
+`humanish comms configure --lab <path> --json` previews an ignored lab copy;
+add `--apply --plan-token <digest>` to save the reviewed version. Launch its
+exact returned path, not a basename that could resolve to another manifest.
 
 ## Setup Workflow
 
@@ -216,18 +220,34 @@ npx humanish lab run first-run --json --no-open
 
 ### Off-app email verification (comms)
 
-When a flow is gated behind an email the app itself sends — a signup
-verification link, a one-time code, a magic link — add a `comms:` block. The
-harness redirects the app's email-API sends into a catch INSIDE the sandbox (no
-mail leaves the machine), gives the persona a synthetic inbox to open and click
-through, and writes a digest-only `humanish.comms-thread.v1` evidence artifact (no
-raw address/link/code persists). Reach for this whenever a persona must read mail
-the app sent it to finish a step.
-
-Lab execution supports email capture only. `comms.sms`, saved connection
-selectors and unknown channel names are rejected. AgentMail connection/key
-setup is available separately; it does not enable real receiving yet. Real SMS
-delivery is also unavailable; a message-bus type does not establish route support.
+When a flow needs an email from the app — a verification link, one-time code or
+magic link — configure an inbox so the participant can read and use that message.
+Humanish supports local capture and fresh hosted receiving, with different setup
+and privacy behavior.
+
+Choose the transport to match the app:
+
+- **Local capture** (below): app send configuration can point at a test catch;
+  no external mail service is needed. It tests the email flow without proving
+  real delivery.
+- **Real AgentMail receiving**: use `comms.email: { connection: agentmail }`.
+  Humanish acquires one fresh hosted inbox per participant before desktops start.
+  The app sends normally. Requires a configured organization-scoped key and
+  app-url/clone/local-tree hosted computer-use participants; concurrent shared
+  worlds work, sequential shared worlds and local-agent do not. Do not combine
+  connection with capture settings or substitute fresh addresses for existing
+  account identities. `allowedOrigins` can name additional trusted link origins.
+
+Real mail can reach hosted desktops, actor models and analysis models. Screenshots
+can contain it. Such runs remain `local_only` even after screenshot blurring;
+this is a publication restriction, not local-only processing. Provider charges
+and model charges are separate. Use `humanish comms recover --json` after an
+interrupted run, then `humanish comms recover --run <id> --apply --json` for its
+privately recorded resources. Never derive deletion authority from run artifacts.
+SMS, participant sending, borrowed inboxes and other providers remain unavailable.
+See `docs/architecture/real-email-receiving.md` for limits and recovery.
+
+The following configuration selects **local capture**:
 
 ```yaml
 comms: