humanish 0.94.0 → 0.95.0

package/dist/tui-contract.d.ts

@@ -6,6 +6,7 @@ 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";
 /** The humanish version string shown in the frame, so a screenshot in a bug report is datable. */
 export interface TuiVersionInfo {
     cli: string;
@@ -16,6 +17,11 @@ 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>;
+    };
     /** Read every run in the project, cheapest source first. */
     readRunIndex(cwd: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;
     /**
@@ -62,6 +68,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 +89,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;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"}

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.95.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,31 @@ 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
+```
+
+Only AgentMail setup is currently supported. 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;
+`comms.email.connection` in a study remains unsupported and is rejected.
+
 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-20. Release baseline: `0.95.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.95.0-connections-setup.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.95.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 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 |
 | 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.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
 `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,11 @@ 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.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 +159,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.94.0",
+  "version": "0.95.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",

package/skills/humanish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humanish
-description: Install and configure Humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email or SMS an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
+description: Install and configure Humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
 ---
 
 # Humanish CLI
@@ -36,10 +36,21 @@ Everything it shows has a machine-readable equivalent, which is what you want:
 | browsing runs | `npx humanish runs --json` |
 | starting a run | `npx humanish lab run <lab> --json --no-open` |
 | a run's outcome | `npx humanish review --run <id> --json` |
+| communication setup | `npx humanish comms providers --json` and `npx humanish comms connections list --json` |
 
 If a human asks you to "open the TUI", tell them the command to type; do not run
 it on their behalf.
 
+For AgentMail credential setup, a human can open `humanish tui`, press `c`,
+and choose **Add API key**. Hidden entry returns to Connections after saving or
+cancelling. The key is stored for that OS user, while the connection profile is
+project-local. Never ask for the key in chat. The CLI alternative is
+`humanish keys set agentmail` (hidden prompt; agents may use `--stdin` from an
+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.
+
 ## Setup Workflow
 
 1. Inspect public target-repo files only: `package.json`, docs, route/app
@@ -203,9 +214,9 @@ npx humanish watch first-run
 npx humanish lab run first-run --json --no-open
 ```
 
-### Off-app email/SMS verification (comms)
+### Off-app email verification (comms)
 
-When a flow is gated behind an email or SMS the app itself SENDS — a signup
+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
@@ -213,6 +224,11 @@ through, and writes a digest-only `humanish.comms-thread.v1` evidence artifact (
 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.
+
 ```yaml
 comms:
   email:
@@ -247,10 +263,15 @@ The app keeps calling its email API normally (Resend/SendGrid-shaped, or a custo
 profile); only the base URL is redirected. Route support: the clone/local-tree
 computer-use route (inbox on the sandbox's own loopback) and the CONCURRENT
 shared-world route (inbox getHost-exposed from the subject sandbox; the default
-since every seat now runs live at once). Declared anywhere else — app-url /
-operator-provided subjects, or a sequential `concurrency: 1` shared world — it is
-warned inert at parse: no catch exists there and no actor hears about an inbox.
-It needs `python3` in the subject sandbox (the stock E2B desktop has it).
+since every seat now runs live at once). SMTP capture is supported on per-lane
+provisioned routes; shared-world SMTP is rejected because it is not wired there.
+For app-url/operator-provided subjects, run `humanish comms catch` on a reachable
+host, point the app's email sends at that catch, and declare
+`comms.email.external.catchBaseUrl` (plus `inboxBaseUrl` if different). A declared
+`authTokenEnv` is an environment variable name, never a credential value.
+Sequential `concurrency: 1` shared-world email remains unwired; do not silently
+change study concurrency to work around that limitation. The in-sandbox catch
+needs `python3` (the stock E2B desktop has it).
 Evidence is digest-only (`humanish.comms-thread.v1` — counts and digests, never
 raw mail); the *readable* proof a persona saw the email is its screenshots of the
 inbox page. See `docs/contracts/schemas.md` for the full `comms:` shape and