humanish 0.94.0 → 0.96.0

package/dist/tui-contract.d.ts

@@ -6,6 +6,9 @@ import type { TuiActionResult } from "./tui-actions.js";
 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;
@@ -16,6 +19,22 @@ export interface TuiVersionInfo {
  * one place, and anything absent here is something the TUI simply cannot do.
  */
 export interface TuiCapabilities {
+    /** Optional for older embedders. Credentials are never returned to the view. */
+    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>;
     /**
@@ -62,6 +81,9 @@ export interface TuiCapabilities {
     initProject(cwd: string): Promise<TuiActionResult>;
 }
 export interface TuiOptions {
+    /** Return to setup after the host-owned hidden prompt has finished. */
+    initialScreen?: "connections";
+    connectionNotice?: string;
     /** The project the surface is reading. Already resolved by the CLI. */
     cwd: string;
     version: TuiVersionInfo;
@@ -80,7 +102,10 @@ export interface TuiOptions {
  * Start the surface. Resolves with the process exit code when the operator quits — the TUI owns the
  * screen until then, so the CLI must not write to stdout while this is pending.
  */
-export type StartTui = (options: TuiOptions) => Promise<number>;
+export type TuiHandoff = {
+    action: "agentmail-key";
+};
+export type StartTui = (options: TuiOptions) => Promise<number | TuiHandoff>;
 /** The shape `dist/tui-app.js` exports. Asserted at the load boundary in program.ts. */
 export interface TuiModule {
     startTui: StartTui;

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;AA+FnB,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.94.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.
@@ -265,10 +265,13 @@ A lab is a composition over code primitives, not a hardcoded kind:
   `redactScreenshots: true` (blur unimplemented there) and
   `allowPublicTargets: true` fail-closed rather than ignoring them.
 - `comms` (#297; hosted on the clone/local-tree computer-use lanes and the
-  CONCURRENT shared-world getHost plane — warned inert everywhere else,
-  including app-url/operator-provided subjects and the sequential
-  `concurrency: 1` shared world, neither of which has a catch to host): off-app
-  email/SMS the app itself SENDS, made a persona-driven testable surface.
+  concurrent shared-world getHost plane, or connected to an external catch on
+  app-url/operator-provided subjects; unwired on sequential `concurrency: 1`
+  shared worlds): off-app
+  email the app itself sends, made a persona-driven testable surface. Lab
+  configuration rejects `comms.sms` and unknown channel names; message-bus SMS
+  types do not imply a supported SMS execution route. SMTP capture is supported
+  on per-lane provisioned routes and rejected for shared-world studies.
   `comms.email` = `{ kind: fake, injectEnv?, port?, recipients?, linkOrigin?, external? }`.
   `injectEnv` is the ADOPTER-NAMED env var the app reads for its email-API base
   URL (e.g. `RESEND_API_URL`); the harness sets it to an in-sandbox catch (so it
@@ -310,6 +313,48 @@ A lab is a composition over code primitives, not a hardcoded kind:
   persona saw the email is its screenshots of the inbox page. Requires `python3`
   in the subject sandbox (the stock E2B desktop template has it).
 
+### Communication connection setup
+
+`.humanish/local/comms.yaml` is a project-local, non-secret configuration file:
+
+```yaml
+schema: humanish.comms-connections.v1
+connections:
+  agentmail:
+    provider: agentmail
+    apiKeyEnv: AGENTMAIL_API_KEY
+```
+
+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.
+Adding an existing name with different settings refuses to overwrite it.
+
+`comms connections list --json` returns `humanish.comms-setup.v1`: configured
+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;
+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`,
 `humanish.cua-lab-result.v2`, `humanish.scripted-lab-result.v1`,

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-19. Release baseline: `0.94.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.94.0-reliability.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.94.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 and run library | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
-| Off-app communication | Recipient-scoped synthetic inboxes, supported inline raster images, in-sandbox email/SMS catch and digest-only thread evidence | Scope prevents accidental cross-recipient browsing; it is not tenant authentication or real-provider delivery |
+| 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.94.0` (2026-09-19). 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,6 +47,15 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
+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,
 recipient-scoped synthetic inboxes, route-aware setup checks, decoded capture
@@ -154,11 +163,12 @@ Implemented:
   deterministic proof, while concurrent has deterministic and kept live proof;
 - `subject.source: local-tree`, which packages one selected working tree with a
   content pin before using the same provision-and-serve path as clone subjects;
-- an off-app comms funnel for email/SMS-gated flows: a vendor-neutral in-sandbox
+- an off-app comms funnel for email-gated flows: a vendor-neutral in-sandbox
   catch redirects the app's own send API, a persona reads a minimal inbox surface
   and clicks through, and a digest-only `humanish.comms-thread.v1` artifact
   records the thread with no raw address, link, or code — wired into the
-  computer-use and shared-world routes and live-proven on computer-use;
+  computer-use and concurrent shared-world routes and live-proven on computer-use.
+  SMS is not yet a configured execution route;
 - resolved-persona directives that actually shape the actor prompt on the
   terminal-product route (traits are applied and recorded in the actor trace, not
   decorative), reusing the same `persona.ts` compiler as the computer-use lane;

package/docs/release/0.95.0-connections-setup.md

@@ -0,0 +1,38 @@
+# 0.95.0 — Connections and hidden key entry
+
+Open `humanish tui` and press **c** to configure AgentMail. **Add API key**
+opens a hidden terminal prompt, then returns to Connections. Ctrl+C cancels
+without changing the existing key or profile. Existing keys can be reused or
+replaced. Entry uses the host's key store, outside the TUI rendering contract.
+
+Keys live in the existing user-level store with file mode 0600. Project
+connection metadata lives in `.humanish/local/comms.yaml` and contains only a
+provider name and environment-variable reference. Explicit environment/env-file
+values retain precedence; strict key mode continues to disable discovery.
+The screen identifies those cases instead of claiming a newly stored key is active.
+
+Agents have matching commands:
+
+```bash
+humanish comms providers --json
+humanish keys set agentmail
+humanish comms connections add agentmail --json
+humanish comms connections list --json
+```
+
+This is connection setup only. Authentication, permissions, capacity and
+delivery are unverified, and this version does not acquire mailboxes or enable
+provider-backed email in studies. Unsupported study connection/SMS selectors
+and shared-world SMTP declarations fail before execution. Supported local
+email capture remains available.
+
+The release also includes TUI `--env-file` propagation and route-specific key
+requirements from #793. Dry-run, local-agent and terminal participants no longer
+inherit a hardcoded OpenAI-plus-E2B key requirement.
+
+Validation covers local configuration, containment, credential precedence,
+hidden entry/cancellation/paste, persistence and TUI frames at 80 and 45
+columns. `pnpm tui:connections:proof` drives the built CLI in a real PTY with
+synthetic keys and an isolated store, checking cancellation, replacement,
+restart and absence of credential values from terminal output. It requires
+Python 3 with Unix PTY support; it does not contact AgentMail.

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.94.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": [
@@ -81,7 +81,8 @@
     "observer:browser:proof": "node scripts/observer-browser-proof.mjs",
     "observer:iframe:proof": "node scripts/observer-iframe-proof.mjs",
     "observer:chrome:proof": "node scripts/observer-chrome-proof.mjs",
-    "observer:reliability:proof": "node scripts/observer-reliability-proof.mjs"
+    "observer:reliability:proof": "node scripts/observer-reliability-proof.mjs",
+    "tui:connections:proof": "python3 scripts/tui-connections-proof.py"
   },
   "repository": {
     "type": "git",
@@ -93,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",