humanish 0.104.3 → 0.106.0

package/CHANGELOG.md

@@ -0,0 +1,502 @@
+# Changelog
+
+Newest first. Each entry is the opening paragraph of that version's release notes; the link holds
+the full notes. Versions not listed here (0.1.1 through 0.65.0 except 0.20.0, and 0.81.0) are
+tagged without notes.
+
+The Unreleased section holds the full notes for the next version until it is tagged.
+
+## Unreleased
+
+## 0.106.0: Node 22.19, a smaller library API and stricter share safety (2026-10-01)
+
+humanish needs Node 22.19.0 or later. The library entry point exports 83 names, down from 377:
+`runLab` runs a lab, and the release notes list the 300 removed names and how to migrate. Sequential
+shared-world studies, the OSS meta-lab, `run --actor` and `run --app-url` are removed, so a
+shared-world lab with `execution.concurrency: 1` fails at parse. Local Codex participants run only
+on the Codex CLI releases admitted for their host, and `humanish doctor` names the release it found.
+`humanish verify` judges share safety by file contents. It finds secrets in base64, hex and escaped
+text, and it grades a run that holds an image or archive it cannot account for `local_only`.
+`serve --safe` re-verifies a run whose files changed before serving it.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.106.0)
+
+## 0.105.0: Rich participant backgrounds (2026-09-28)
+
+Personas now support a multiline `background` for relevant history, habits, motivations and constraints. It preserves paragraphs up to 32 KiB and rejects oversized context instead of silently truncating it. Missing files, unsupported fields and shortened legacy fields now produce diagnostics.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.105.0)
+
+## 0.104.3: SMTP capture for local app studies (2026-09-28)
+
+`humanish comms catch --smtp-port 1025` now supports SMTP verification mail for apps hosted by the study operator. The command previously rejected its documented SMTP option. It now validates the port and fails startup if SMTP cannot bind, instead of leaving misleading healthy HTTP status.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.104.3)
+
+## 0.104.2: Preserve desktop capture timestamps (2026-09-28)
+
+Desktop recordings now preserve the capture input’s microsecond timestamps and explicitly use variable-frame-rate output across local and E2B FFmpeg versions. This avoids dropping closely spaced captured frames or filling genuine gaps with duplicates. Existing recordings are unchanged.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.104.2)
+
+## 0.104.1: Recording startup (2026-09-28)
+
+Mixed desktop recording no longer waits behind the recording mix's default
+two-second PulseAudio buffer. Its null sink now uses the supported no-rewind mode,
+which bounds that buffer to 50 ms. FFmpeg settings, timestamps, startup ordering
+and resource ownership are unchanged; screen-only recording uses the same path
+as before.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.104.1)
+
+## 0.104.0: Local captured inboxes (2026-09-28)
+
+Local browser participants can now create an account, open their assigned inbox
+and follow a verification link without mailbox-provider credentials. Start
+`humanish comms catch`, configure the app to send email to that catch, and declare
+`comms.email.external.catchBaseUrl` in the local lab. Doctor checks the catch's
+recipient routes and explains setup failures before a participant starts.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.104.0)
+
+## 0.103.2: Adjacent ending evidence for analysis (2026-09-28)
+
+A participant can inspect a result and then scroll or navigate before ending.
+Analysis now prioritizes the preceding screenshot alongside the final view,
+after beginning and explicit failure context. Previously, session sampling
+could omit that nearby result while retaining a final heading or navigation page.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.103.2)
+
+## 0.103.1: Fairer analysis capture allocation (2026-09-27)
+
+Analysis now gives reclaimed screenshot slots to eligible participants with
+fewer admitted images. Previously, a participant whose images exceeded its
+initial byte reservation could receive only its ending capture while other
+participants received extra captures, even with enough image bytes remaining.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.103.1)
+
+## 0.103.0: Optional desktop video and audio recording (2026-09-27)
+
+Computer-use studies can retain an MP4 alongside screenshots, actions,
+participant feedback and analysis:
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.103.0)
+
+## 0.102.0: Optional participant camera and speech (2026-09-26)
+
+Codex participants can listen and speak while using a conferencing app. The same
+continuing conversation handles browser actions and spoken replies on local
+Firecracker and hosted E2B desktops. No separate conversational agent or speech
+API key is required. Codex inference still uses the selected remote account.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.102.0)
+
+## 0.101.0: Shared Codex UI tools (2026-09-25)
+
+Codex participants now interact through a native Humanish UI tool. One continuing
+Codex conversation can call the tool repeatedly, inspect each new screenshot,
+and give its final feedback. Humanish executes and records the inputs, including
+rejected or skipped actions, before returning their actual status to Codex.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.101.0)
+
+## 0.100.1: Participant conversation continuity (2026-09-25)
+
+Local Codex participants now keep one conversation for their entire study,
+including closing feedback. Previously, each screenshot started a new thread
+with only eight turns of summarized history. Earlier observations, actions and
+participant context now remain in the Codex conversation, with Codex managing
+context compaction.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.100.1)
+
+## 0.100.0: Local study setup and startup reliability (2026-09-25)
+
+Configure a local browser study during setup:
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.100.0)
+
+## 0.99.1: Recover from rejected browser input (2026-09-24)
+
+A participant can now recover when the desktop explicitly rejects an action
+before sending any input. For example, typing without an editable field focused
+previously ended a local browser study with a harness error, even though the
+browser remained usable.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.99.1)
+
+## 0.99.0: Local browser studies on Apple Silicon Macs (2026-09-24)
+
+Local browser studies now run on supported Apple Silicon Macs using Lima and ARM64 Firecracker desktops, with the same participants, Observer recordings and automatic analysis as Linux.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.99.0)
+
+## 0.98.0: Local browser studies on Linux (2026-09-24)
+
+Explicit local browser labs now run from the installed CLI and TUI. On Linux
+x64 with Docker/KVM and a supported Codex ChatGPT login, isolated Firecracker
+participants use the normal scheduler, recordings, Observer and automatic
+analysis without E2B or OpenAI API keys. Codex inference remains remote and
+consumes account quota; dollar cost is unknown.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.98.0)
+
+## 0.97.0: Codex account reports on Linux (2026-09-23)
+
+Saved studies can use an existing Codex ChatGPT login for their separate
+findings report. Select it explicitly:
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.97.0/docs/release/0.97.0-codex-account-analysis.md)
+
+## 0.96.1: Preserve browser navigation (2026-09-20)
+
+Hosted browser studies now measure physical client bounds with `xwininfo`.
+The older `xdotool` build on hosted desktops can count window decorations twice,
+incorrectly reporting that a visible browser extends beyond the captured screen.
+That false reading could trigger fullscreen, hiding the tabs and address bar
+participants use to move between an application and their study inbox.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.96.1/docs/release/0.96.1-browser-navigation.md)
+
+## 0.96.0: Real email receiving (2026-09-21)
+
+Browser studies can now receive real email through AgentMail, with a fresh inbox for each participant.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.96.0)
+
+## 0.95.0: Connections setup (2026-09-20)
+
+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.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.95.0)
+
+## 0.94.0: Reliability (2026-09-18)
+
+Long analysis requests now honor Humanish's configured deadline instead of
+ending early at the HTTP client's header timeout. The default deadline is ten
+minutes. Omitted output settings use up to 32,768 tokens when the existing
+declared budget admits that allowance, otherwise retaining 16,384. Explicit
+output settings remain exact. This adds no retries or automatic budget increase.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.94.0/docs/release/0.94.0-reliability.md)
+
+## 0.93.1: Observer review controls (2026-09-17)
+
+Findings now starts with a compact overview: finding count, participants
+included, analyzed outcomes, and sampled captures. The original narrative
+remains under **Study summary**. Coverage notes, methodology and separate
+automatic-attempt status are available under **Coverage & analysis details**.
+A failed automatic attempt no longer replaces the status of a usable report.
+Running or unknown execution, changed evidence, and exceeded admission limits
+remain visible. Outcome counts are analysis judgments, not verified success
+rates; stale reports do not use current recordings as their denominators.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.93.1/docs/release/0.93.1-observer-review-controls.md)
+
+## 0.93.0: Global playback (2026-09-16)
+
+The Observer uses one study clock across the participant grid and individual
+recordings. Seek halfway through a study, open a participant, then scrub back:
+returning to the grid shows every participant at that same time. Playback also
+continues through ordinary participant navigation and browser Back/Forward.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.93.0/docs/release/0.93.0-global-playback.md)
+
+## 0.92.0: Grid playback (2026-09-16)
+
+Play and scrub all recorded participants together in the Observer grid.
+The transport includes pause, playback speed and a shared recording timeline.
+Opening a displayed capture lands on its exact frame; returning restores the
+grid's time and participant page, paused.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.92.0/docs/release/0.92.0-grid-playback.md)
+
+## 0.91.1: Study review polish (2026-09-15)
+
+Study cost summaries include retained analysis attempts alongside participant
+and desktop estimates. Reusing a saved analysis does not add another charge;
+separate retries do. Missing prices and incomplete histories remain explicit.
+The existing stats JSON fields keep their original participant-and-desktop
+meaning; additive cost fields provide the combined retained estimate.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.91.1/docs/release/0.91.1-study-review-polish.md)
+
+## 0.91.0: Analysis quality and defaults (2026-09-15)
+
+Supported live studies now request analysis when the recording finishes, using
+`gpt-6-astra` with high reasoning and a separate $3 admission estimate limit.
+The CLI, preflight and TUI disclose that budget. Set `review.analysis: false` to
+disable the extra request, or supply an analysis mapping with `maxCostUsd` to
+customize it. The estimate is additional to participant and desktop costs and
+is not a provider billing cap. Missing default credentials record a skip while
+preserving a successful recording; explicit analysis failures remain failures.
+Startup failures with no retained participant activity skip default analysis.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.91.0/docs/release/0.91.0-analysis-quality-and-defaults.md)
+
+## 0.90.0: Findings after live studies (2026-09-14)
+
+Labs can opt into independent analysis after their recording finishes with
+`review.analysis.maxCostUsd`. The command waits for the result; the TUI and
+Observer show analysis separately from participant execution and task outcomes.
+Without the setting, run behavior stays unchanged.
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.90.0/docs/release/0.90.0-automatic-analysis.md)
+
+## 0.89.1: Finished analysis notice (2026-09-15)
+
+Observer now labels a partial analysis result **“Analysis finished with
+limitations.”** The previous notice described findings as covering evidence
+“included so far,” which could make a finished analysis appear to be running.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.89.1)
+
+## 0.89.0: Evidence-linked study findings (2026-09-14)
+
+Completed studies can now produce ranked findings with links to the participant
+events and captures that support them. Observer keeps Participants and Findings
+inside the same study shell, with the recording grid, original participant
+feedback and playback controls available throughout the review.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.89.0)
+
+## 0.88.2: Sequential study model thresholds (2026-09-14)
+
+Sequential shared-world studies now apply the model-spend thresholds they previously accepted without enforcing. The fix covers computer-use participants sharing a clone or local-tree subject with concurrency 1.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.88.2)
+
+## 0.88.1: Completion evidence and a runnable local-app example (2026-09-12)
+
+When a computer-use participant says it finished, Humanish now labels that completion as **participant-reported**. A recorded `stopWhen` match or completed dwell window identifies a **recorded completion condition**. Missing, malformed or conflicting detail is labeled unavailable; zero completions use **0/N recorded completions**.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.88.1)
+
+## 0.88.0: See what ended a study (2026-09-11)
+
+Computer-use studies now show a diagnostic category and recorded stop cause in CLI output. Fan-out results preserve each participant's ending, and newly generated review summaries use the same recorded causes. Successful dry-runs are identified as contract previews.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.88.0)
+
+## 0.87.0: Participant endings and phone review (2026-09-10)
+
+Humanish 0.87.0 makes participant endings easier to interpret and saved recordings easier to review on a phone.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.87.0)
+
+## 0.86.1: Task preflight and saved recordings (2026-09-09)
+
+Humanish now refuses a task protocol when the chosen execution path cannot run
+it. Previously, a shared-world, terminal, scripted or synthetic lab could accept
+`actors[0].tasks` and then omit those tasks during execution. Preflight now names
+the unsupported field before creating a run or starting hooks, processes,
+desktops or model requests. Remove `tasks` only when you intend a mission-only
+study, or choose a supported per-lane computer-use route.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.86.1)
+
+## 0.86.0: Participant assignments and exact action review (2026-09-09)
+
+The Observer now shows each participant's assigned mission and lane focus.
+Expand **Assigned task** in the player or participant details to read the
+instructions. Computer-use runs also include their participant-facing task
+goals. Hidden success checks and runtime access details stay outside this
+assignment. Older recordings explicitly say when an assignment was not recorded.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.86.0)
+
+## 0.85.1: Observer review continuity (2026-09-09)
+
+The Observer review flow now carries the selected evidence between views:
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.85.1)
+
+## 0.85.0: Watch and review complete screens (2026-09-09)
+
+Observer now shows portrait and desktop captures at their original proportions,
+with equal-height grid previews and a compact caption below each screen. Live
+labels and controls leave the captured pixels clear. A stable Info button opens
+participant details, labeled Pin/Compare actions and recorded notices.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.85.0)
+
+## 0.84.1: Run feedback checks from exported evidence (2026-09-07)
+
+Generated feedback commands now work from a standalone exported evidence workspace:
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.84.1)
+
+## 0.84.0: Share evidence and keep readable originals (2026-09-07)
+
+Keep readable local evidence and export a separate shareable workspace:
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.84.0)
+
+## 0.83.2 (2026-09-07)
+
+Concurrent computer-use studies now preserve declared reasoning effort, output-token limits and the shared actor-model budget. Host startup failures report their actual cause instead of a misleading handoff timeout. Linux browser profiles use system window decorations, with a measured fullscreen fallback for narrow desktops.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.83.2)
+
+## 0.83.1 (2026-09-06)
+
+Desktop CLI studies that leave product installation to the participant now prepare Node/npm before the terminal opens. Two fresh hosted desktops verified the runtime becomes available while the subject product remains uninstalled.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.83.1)
+
+## 0.83.0 (2026-09-06)
+
+Humanish 0.83.0 adds a per-response output limit and fixes three ways harness behavior could distort a computer-use study.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.83.0)
+
+## 0.82.1 (2026-09-05)
+
+Humanish 0.82.1 corrects computer-use sessions that were cut short by provider output limits. A response with no remaining actions no longer counts as successful completion when the provider explicitly says it is incomplete. Usage and partial text are preserved; actions and debrief are skipped.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.82.1)
+
+## 0.82.0 (2026-09-05)
+
+Humanish 0.82.0 makes repeated studies easier to reproduce and their evidence easier to interpret.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.82.0)
+
+## 0.80.0 (2026-09-04)
+
+v0.80.0 — the observation window on every desktop route, and a sandbox request that cannot exceed the cap
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.80.0)
+
+## 0.79.0 (2026-09-04)
+
+v0.79.0 — a study can hold and watch, and a participant can have a camera
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.79.0)
+
+## 0.78.0 (2026-09-04)
+
+v0.78.0 — the CLI no longer lingers after a run: @e2b/desktop 2.3.3, and doctor says which SDK you have
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.78.0)
+
+## 0.77.0 (2026-09-04)
+
+v0.77.0 — a phone participant's later tab is a phone tab too; a transient sandbox error is retried once
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.77.0)
+
+## 0.76.0: A phone participant at a real 414 px viewport, with touch and a mobile user agent (2026-09-03)
+
+v0.76.0 — a phone participant at a real 414 px viewport, with touch and a mobile user agent
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.76.0)
+
+## 0.75.0: The task funnel measures every desktop, installs retry once, Sol priced at the live sheet (2026-09-03)
+
+v0.75.0 — the task funnel measures every desktop, installs retry once, Sol priced at the live sheet
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.75.0)
+
+## 0.74.0: Run and watch write the same bundle (2026-09-01)
+
+`humanish run` renders observer/index.html after a successful run, the way
+`watch` does, so the same lab produces the same bundle whichever command
+ran it. A render failure is a warning on the result, never a failed run.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.74.0)
+
+## 0.73.0: A run bundle exports (2026-09-01)
+
+humanish export renders the Observer for a bundle that has none, which is
+every bundle `run` writes, so the everyday command's bundles can be sent.
+Found by the 0.72.0 release:dogfood participant on its first export.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.73.0)
+
+## 0.72.0: The cold-start Claude path works again, and is measured (2026-09-01)
+
+The one-shot Claude participant had been failing on turn one since its
+prompt sat after --allowedTools; fixed with --, kept reachable as
+HUMANISH_LOCAL_AGENT_ONE_SHOT=1 for measurement, session stays the default.
+Receipt: no difference on the two-table starter lab, 3 of 3 each; on a
+harder mission, session 4 of 4 against one-shot 0 of 4 in 300 s and 1 of 4
+in 600 s.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.72.0)
+
+## 0.71.0: A taken port is named, and a lingering process can be too (2026-09-01)
+
+A port somebody already holds reports HUMANISH_PORT_IN_USE (serve:
+HUMANISH_SERVE_PORT_IN_USE) with the port and whether another humanish
+process holds it, instead of HUMANISH_UNEXPECTED. HUMANISH_DEBUG_HANDLES=1
+prints Node's active resources after a command settles, for the run whose
+CLI lingered sixteen minutes past its result.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.71.0)
+
+## 0.70.0: An export says what verify said (2026-09-01)
+
+humanish export writes verify's share status into the file it produces
+(publicSafety.share, additive and optional on the frozen observer-data
+schema), and the Observer's chip renders it, so a share_ready export no
+longer reads local_only.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.70.0)
+
+## 0.69.0: Export, the closing line, and reports that count as friction (2026-09-01)
+
+`humanish export --run <id>` writes one self-contained Observer with
+screenshots inlined, after verify and the share gate; --local-only
+watermarks. Free-text computer-use participants label their own ending
+(REACHED THE GOAL. / DID NOT REACH THE GOAL. / BLOCKED.) and the trace
+records it; adherence 6 of 6 on the benchmark rerun, with recall and
+precision unchanged (14 of 15, 0 invented). A finished participant's report
+of defects or confusion now counts as friction and becomes a feedback
+candidate. drawDB precision arm: 11 of 12 claims confirmed in source.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.69.0)
+
+## 0.68.0: Stats, the participant's own word, and no person profile (2026-09-01)
+
+`humanish stats` rolls up cost, outcomes, and durations across run history
+with estimates labelled and unknown costs counted as unknown. A
+schema-constrained participant declares reached / not_reached / blocked on
+its final turn and the lane reads that before the closing paragraph
+(verified live). "blocked" no longer reads as "blocked on an approval".
+Every telemetry event asks for no person profile.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.68.0)
+
+## 0.67.0: The scan stops refusing finished runs, and a hung turn is named (2026-09-01)
+
+Five of five completed live runs were refused as "not a credible pass" on
+sentences like "I could not read the full description"; the verdict scan
+now strips perception verbs after "can't" and reads "encountered no ..." as
+a negation. A hung provider turn is retried once and then ends the lane as
+harness_error with its name on it; a hung wait is skipped with a notice.
+Claude Code participants keep one session per run. The study-participant
+telemetry marker is actually set.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.67.0)
+
+## 0.66.0: The funnel tells us what a study was, and a refused lane stays refused (2026-09-01)
+
+Telemetry now reports what a study was: mode, outcome, starter lab, brain
+route, and our own error code, with ok meaning exit 0. Every event asks the
+receiver not to derive a location, and the project discards client IPs.
+1,359 study events before this release carried none of that.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.66.0)
+
+## 0.20.0: External-public shared-world plane + CDP lobby-code handoff (2026-08-02)
+
+Additive minor release. No breaking change to the provisioned-getHost path, its schema, or its verify
+asserts (byte-stable; a snapshot regression pins it).
+
+[Release notes](https://github.com/danielgwilson/humanish/blob/v0.20.0/docs/release/0.20.0-external-public-shared-world.md)

package/CONTEXT.md

@@ -0,0 +1,51 @@
+# Glossary
+
+Use one word per concept. Docs and new code use the terms in the first table. Some lab, bundle and
+output fields keep older spellings; the second table maps them.
+
+| Term         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| study        | The prose word for everything one `humanish run <lab>` produces: participants, evidence and analysis. Each study writes one run.                                                                                                                                                                                                                                                                                                                                                                                                  | No type of its own; see run.                                                                                                                                                                                                                                                                                                                                                                              |
+| run          | One execution on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                              | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                            |
+| lab          | A YAML manifest that declares a study: `humanish/labs/<id>.yaml`, schema `humanish.lab.v2`.                                                                                                                                                                                                                                                                                                                                                                                                                                       | `src/lab/`; `LabConfig` in `src/lab/types.ts`, parsed by `parseLabConfig` in `src/lab/config.ts`                                                                                                                                                                                                                                                                                                          |
+| participant  | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the lab config with `computerUseParticipants` (`src/lab/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/lab/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
+| persona      | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/lab/persona.ts`, `src/lab/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                        |
+| mission      | The free-form brief a model-driven participant receives: `actors[].mission`. `actors[].tasks[]` adds discrete tasks: each has a `goal` the participant sees and an optional `success` check it does not.                                                                                                                                                                                                                                                                                                                          | `LabActor` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                          |
+| assignment   | What one participant was asked to do: the mission, a `lanes[]` entry's `instruction` or `laneFocus.instruction` (recorded as `focus`), and the tasks. Each stream records it as `streams[].assignment`.                                                                                                                                                                                                                                                                                                                           | `participantAssignment` in `src/lab/participant-assignment.ts`; `RunParticipantAssignment` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                        |
+| scenario     | Two things share the word. The lab's `scenario` block holds run settings: `mode` (`dry-run` or `live`), `caps`, and an optional `ref`. The `ref` names a scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. Only the scripted-browser route executes those steps. A model-driven participant follows its mission.                                                                                                                                                | `LabScenario` in `src/lab/types.ts`; `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                                        |
+| surface      | One browser viewport that a scripted run replays its journey on: `desktop` or `mobile`. A scripted lab runs the desktop surface by default, and `actors[0].count: 2` adds the mobile one. Each surface writes `actor-<surface>.json` and `traces/<surface>.json`.                                                                                                                                                                                                                                                                 | `BrowserSurface` and `browserSurfaces` in `src/actors/scripted-browser/types.ts`; the plan's `surfaces` in `src/routes/scripted/plan.ts`                                                                                                                                                                                                                                                                  |
+| journey      | A scenario's `browser.steps` parsed into ordered steps with a goal and a start path. The scripted route replays it once on each surface, and each surface's session reports the first step that did not pass.                                                                                                                                                                                                                                                                                                                     | `BrowserPersonaJourney` in `src/actors/scripted-browser/types.ts`; `parseBrowserPersonaJourneyFromScenario` in `src/actors/scripted-browser/journey.ts`                                                                                                                                                                                                                                                   |
+| subject      | The product under study, declared by `subject.source`: `clone`, `app-url`, `local-tree`, `terminal-product`, `desktop-cli`, `local-app` or `this-repo`. `run.json` records its provenance under `subject`.                                                                                                                                                                                                                                                                                                                        | `LabSubject` in `src/lab/types.ts`, parsed in `src/lab/parse/subject.ts`                                                                                                                                                                                                                                                                                                                                  |
+| actor        | The model or program that drives a participant, declared by `actors[0].type`, e.g. `openai-computer-use`, `local-agent`, `scripted-browser`, `codex-exec`.                                                                                                                                                                                                                                                                                                                                                                        | `src/actors/`; `actorRegistry` in `src/actors/registry.ts` lists every one; `ActorTrace` in `src/actors/contract.ts` is its record                                                                                                                                                                                                                                                                        |
+| adapter      | Product-specific code kept out of core. A lab names a scorer module in `review.scorer.ref`, or the CLI passes `--scorer`, and a library caller passes the same functions as `RunLabOptions.scorer`: `score`, `deriveFeedback` and `deriveArtifacts`. Their output is stored under the adapter's namespace in `run.json` (`adapterScore`, `adapterArtifacts` and a feedback candidate's `adapter`).                                                                                                                                | `AdapterScorerModule` in `src/lab/adapter-scorer-loader.ts`; `applyBrowserAdapterHooks` in `src/lab/adapter-extension.ts`; fixture sets in `adapters/`                                                                                                                                                                                                                                                    |
+| computer use | A model drives a participant by reading screenshots of a desktop and acting with mouse and keyboard. `openai-computer-use` and `local-agent` are the computer-use actors. CUA is the short form the code and CLI output use: the backend name `cua`, the `HUMANISH_CUA_LAB_*` error codes and names such as `CuaExecutor`.                                                                                                                                                                                                        | `src/routes/computer-use/`, `src/actors/computer-use/`                                                                                                                                                                                                                                                                                                                                                    |
+| fan-out      | A computer-use run with more than one participant, each on its own desktop, or any rerun. It writes the fan-out bundle shape and passes only when every expected participant passes. One participant without a rerun keeps the single-participant shape.                                                                                                                                                                                                                                                                          | `buildCuaFanoutBundle` in `src/routes/computer-use/fanout-bundle.ts`; `judgeComputerUseRun` in `src/routes/computer-use/bundle.ts`                                                                                                                                                                                                                                                                        |
+| route        | The execution path for a lab: `computer-use`, `shared-world`, `scripted`, `terminal` or `preview`. `preview` writes a dry-run bundle for `this-repo` subjects with no live participant.                                                                                                                                                                                                                                                                                                                                           | `routeOf` and `LabRoute` in `src/lab/plan.ts`; predicates in `src/lab/routing.ts`; one folder or file per route in `src/routes/`                                                                                                                                                                                                                                                                          |
+| plan         | What `planLab` decides about a lab before anything runs: the lab id, whether it is a dry run, the analysis settings and the keys, connections and env vars the run needs, plus the route's participants, caps and own fields. There is one variant per route. `planLab` returns a plan, or a refusal with the route's error code, and the route's run function (`runComputerUsePlan` and the others) takes the plan.                                                                                                              | `LabPlan` in `src/lab/plan-types.ts`; `planLab` in `src/lab/plan.ts`; each route's planner in its `plan.ts`                                                                                                                                                                                                                                                                                               |
+| substrate    | Where a participant's desktop or shell runs: a hosted E2B sandbox, or a local Firecracker VM (inside Lima on macOS).                                                                                                                                                                                                                                                                                                                                                                                                              | `src/substrates/e2b/`, `src/substrates/local/`                                                                                                                                                                                                                                                                                                                                                            |
+| receipt      | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to, and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                                          | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                          |
+| topology     | Whether participants share one instance of the subject. `subject.topology` is `per-lane-worlds` (the default, one each) or `shared-world` (one for all).                                                                                                                                                                                                                                                                                                                                                                          | `LabSubjectTopology` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                |
+| plane        | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the lab names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                          | `SharedWorldPlane` in `src/lab/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
+| stream       | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                      | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                       |
+| Observer     | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                               | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                             |
+| evidence     | Files a run keeps: screenshots, traces, transcripts, recordings. `verify` checks them and grades share-safety.                                                                                                                                                                                                                                                                                                                                                                                                                    | `src/evidence/`; `verifyRun` in `src/verify/verify.ts`                                                                                                                                                                                                                                                                                                                                                    |
+| finding      | A result of study analysis, with citations to evidence in the run. Each finding groups the observations that support it.                                                                                                                                                                                                                                                                                                                                                                                                          | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
+| observation  | One claim in study analysis with its basis, evidence ids and limitation. `concernReviews[]` gives each material concern's observation a disposition: `finding`, `context` or `unsupported`.                                                                                                                                                                                                                                                                                                                                       | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
+
+## Read these field spellings as the concept they name
+
+Fields documented in [docs/contracts/](docs/contracts/schemas.md), in `TELEMETRY.md` and in the
+library exports of `src/index.ts` are API, so they keep their spelling. Prose and new code use the
+concept word.
+
+| Spelling                                                    | Where it appears                                                                                                                                                                                                                                                                                                                        | Concept                       |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `lanes`, `laneFocus`, `laneId`, `laneWindows`, `laneGroups` | `actors[0].lanes[]` and `actors[0].laneFocus` in a lab; `streams[].laneId` and `sharedWorld.laneWindows` in `run.json`; `laneGroups` in Observer data                                                                                                                                                                                   | participant                   |
+| `roles`, `roleId`, `roleCount`                              | `run.json` `sharedWorld`: `roleCount`, and `roleId` on `laneWindows`, `outcomes` and the older sequential records                                                                                                                                                                                                                       | participant in a shared world |
+| seat                                                        | The deprecated `resolveSeatUrl` export in `src/index.ts`, comments in `src/lab/warnings.ts`, and the dated records under `docs/goals/`. The shared-world planner's records are `ProvisionedParticipant` and `ExternalPublicParticipant` (`src/lab/plan-participants.ts`). No lab or `run.json` field uses the word.                     | participant in a shared world |
+| `simulations`, `simId`, `simCount`                          | `simulations[]` in `run.json` (one per participant), `simId` on streams and shared-world records, `simCount` in `run.json` and Observer data                                                                                                                                                                                            | participant                   |
+| `streams`, `streamId`                                       | `streams[]` in `run.json`; `streamId` on shared-world records                                                                                                                                                                                                                                                                           | stream                        |
+| `backend`                                                   | The `backend` field of `humanish.lab-preflight-result.v1`, beside `route`; `LabBackend` in `src/index.ts`; `selectLabBackend` and `LabOutcome.backend`, deprecated for `routeOf` and `LabOutcome.route`. The values are older route names: `cua` is computer-use, `concurrent-shared-world` is shared-world and `synthetic` is preview. | route                         |
+| `cua`                                                       | The backend name for computer-use and the `HUMANISH_CUA_LAB_*` error codes                                                                                                                                                                                                                                                              | computer use                  |
+| `CONCURRENT` in `HUMANISH_CONCURRENT_SHARED_WORLD_LAB_*`    | The shared-world route's error codes. The word dates from when a sequential shared-world route also existed; its codes, `HUMANISH_SHARED_WORLD_LAB_*`, go in 0.106.0, so new shared-world codes keep `CONCURRENT_` rather than reuse that prefix                                                                                        | shared world                  |
+| `brain`                                                     | The telemetry property: `provider-key`, `local-agent` or `none`                                                                                                                                                                                                                                                                         | how the actor gets its model  |