humanish 0.107.0 → 0.108.0

package/dist/verify/verify.js

@@ -8,8 +8,10 @@ import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA } from "../run/bundle.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
 import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
+import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
 import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, } from "./artifacts.js";
+import { flatContextWarnings } from "./context-growth.js";
 import { runNotFinishedWarnings } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
@@ -57,26 +59,16 @@ export function invalidRunStorageVerifyResult(cwd, runInput) {
 export async function verifyResolvedRun(cwd, runInput, runPaths) {
     const checks = [];
     if (!runPaths) {
+        const message = await runNotFoundMessage(cwd, runInput);
         return {
             schema: VERIFY_SCHEMA,
             ok: false,
             cwd,
             run: runInput,
             checks,
-            shareSafety: {
-                status: "blocked",
-                reasons: [
-                    {
-                        code: "VERIFY_FAILED",
-                        message: `Run not found: ${runInput}`,
-                    },
-                ],
-            },
+            shareSafety: { status: "blocked", reasons: [{ code: "VERIFY_FAILED", message }] },
             warnings: [],
-            error: {
-                code: "HUMANISH_RUN_NOT_FOUND",
-                message: `Run not found: ${runInput}`,
-            },
+            error: { code: "HUMANISH_RUN_NOT_FOUND", message },
         };
     }
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
@@ -84,7 +76,10 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     const cleanupJson = await readRunJsonIfExists(runPaths, "cleanup.json");
     const reviewJson = await readRunJsonIfExists(runPaths, "review.json");
     const reviewMarkdown = await readRunTextIfExists(runPaths, "review.md");
-    checks.push(...bundlePresenceChecks(bundle, reviewJson !== null && reviewMarkdown !== null));
+    checks.push(...bundlePresenceChecks(bundle, {
+        json: reviewJson !== null,
+        markdown: reviewMarkdown !== null,
+    }));
     const derivedPublicSafetyFindings = [];
     const unscannedArtifacts = [];
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
@@ -104,7 +99,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         name: "public-safety scan",
         ok: publicSafetyFindings.length === 0,
         message: publicSafetyFindings.length === 0
-            ? "run text artifacts and public-proof paths must not match known secret or browser-profile patterns"
+            ? "no run text artifact or public-proof path matches a known secret or browser-profile pattern"
             : `public-safety findings: ${publicSafetyFindings.slice(0, 5).join(", ")}`,
     });
     const missingEvidenceArtifacts = isRunBundle(bundle)
@@ -118,7 +113,9 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         name: "local evidence artifacts exist",
         ok: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0,
         message: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0
-            ? "referenced local screenshot/trace/log/filesystem artifacts are present"
+            ? isRunBundle(bundle)
+                ? "every referenced screenshot, trace, log and filesystem artifact is present"
+                : SHAPE_UNCHECKED
             : invalidEvidenceReferences.length > 0
                 ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
                 : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
@@ -137,6 +134,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
             ...undeclaredSubjectStateWarnings(bundle),
             ...desktopGeometryWarnings(bundle),
+            ...flatContextWarnings(bundle),
             ...(await runNotFinishedWarnings(runPaths, bundle)),
         ]
         : [];
@@ -189,33 +187,76 @@ export async function verifyRunPrepared(cwdInput, runInput, runPaths) {
     }
     return verifyResolvedRun(cwd, runInput, runPaths);
 }
-/** Whether run.json, its schema, shape and redaction, and the review artifacts are present. */
-function bundlePresenceChecks(bundle, reviewArtifactsExist) {
+/** The top-level run.json sections the shape guard requires. */
+const REQUIRED_SECTIONS = [
+    "source",
+    "persona",
+    "scenario",
+    "lifecycle",
+    "simulations",
+    "streams",
+    "events",
+    "artifacts",
+    "review",
+    "redaction",
+    "feedbackCandidates",
+];
+/**
+ * Whether run.json, its schema, shape and redaction, and the review artifacts are present. Each
+ * check says what it found, so a failing row never prints the rule it enforces.
+ */
+function bundlePresenceChecks(bundle, review) {
+    const record = isRecord(bundle) ? bundle : undefined;
+    const schema = record?.schema;
+    const schemaOk = schema === RUN_BUNDLE_SCHEMA;
+    const redactionRecord = record?.redaction;
+    const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
+    const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
+    const missingReview = [
+        ...(review.json ? [] : ["review.json is missing or not valid JSON"]),
+        ...(review.markdown ? [] : ["review.md is missing"]),
+    ];
     return [
         {
             name: "run.json exists",
             ok: bundle !== null,
-            message: bundle === null ? "run.json missing" : "run.json present",
+            message: bundle === null ? "run.json is missing or not valid JSON" : "run.json is present",
         },
         {
             name: "run schema",
-            ok: isRecord(bundle) && bundle.schema === RUN_BUNDLE_SCHEMA,
-            message: "run bundle schema is humanish.run-bundle.v1",
+            ok: schemaOk,
+            message: schemaOk
+                ? `run.json declares ${RUN_BUNDLE_SCHEMA}`
+                : record === undefined
+                    ? "no readable run.json, so no schema"
+                    : `run.json declares ${typeof schema === "string" ? schema : "no schema"}; verify reads ${RUN_BUNDLE_SCHEMA}`,
         },
         {
             name: "run bundle shape",
             ok: isRunBundle(bundle),
-            message: "run bundle must include source, persona, scenario, lifecycle, simulations, streams, events, artifacts, review, and feedback candidates",
+            message: isRunBundle(bundle)
+                ? "run.json has every required section"
+                : record === undefined
+                    ? "no readable run.json, so no sections"
+                    : missingSections.length > 0
+                        ? `run.json is missing ${missingSections.join(", ")}`
+                        : schemaOk
+                            ? "one or more run.json sections have the wrong shape"
+                            : "sections not checked, because the schema differs",
         },
         {
             name: "redaction passed",
-            ok: isRecord(bundle) && isRecord(bundle.redaction) && bundle.redaction.status === "passed",
-            message: "redaction status must be passed",
+            ok: redaction === "passed",
+            message: redaction === "passed"
+                ? "redaction passed"
+                : `redaction did not pass (status: ${typeof redaction === "string" ? redaction : "missing"})`,
         },
         {
             name: "review artifacts exist",
-            ok: reviewArtifactsExist,
-            message: "review.json and review.md must exist",
+            ok: missingReview.length === 0,
+            message: missingReview.length === 0
+                ? "review.json and review.md are present"
+                : missingReview.join("; "),
         },
     ];
 }
@@ -242,38 +283,46 @@ async function applyAnalysisSharing(runPaths, warnings, shareSafety) {
         shareSafety.status = "local_only";
 }
 /** Passes when `findings` is empty; otherwise lists them after `failLabel`. */
-function findingsCheck(name, findings, okMessage, failLabel, failSuffix = "") {
+function findingsCheck(name, findings, okMessage, failLabel) {
     return {
         name,
         ok: findings.length === 0,
-        message: findings.length === 0 ? okMessage : `${failLabel}: ${findings.join(", ")}${failSuffix}`,
+        message: findings.length === 0 ? okMessage : `${failLabel}: ${findings.join(", ")}`,
     };
 }
+/**
+ * The pass message of a check that reads bundle content when run.json failed its shape guard. The
+ * check has no findings and stays ok; the shape check is the failure.
+ */
+const SHAPE_UNCHECKED = "not checked, because run.json failed the shape check";
 /** The bundle-content checks, in report order. A bundle that fails its shape guard has no findings. */
 async function evidenceChecks(runPaths, bundle, cleanupJson) {
     const valid = isRunBundle(bundle) ? bundle : null;
+    const pass = (message) => (valid ? message : SHAPE_UNCHECKED);
     const checks = [
-        findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], "live terminal-product streams either are absent or carry the substrate/cleanup/interventions/cost ledgers + a ledger-derived no-spend proof + redacted terminal evidence, with proven teardown and known spend within the declared cap", "terminal-product findings"),
-        findingsCheck("codex app-server evidence", valid ? await validateCodexAppServerEvidence(runPaths, valid) : [], "live Codex app-server streams either are absent or include valid redacted trace evidence", "codex app-server findings"),
-        findingsCheck("actor engagement", valid ? noEngagementActorFindings(valid) : [], "live actor traces that claim goal_satisfied carry at least one action or message", "no-engagement findings", " — a hollow run is not credible evidence"),
-        findingsCheck("actor verdict consistency", valid ? actorVerdictConsistencyFindings(valid) : [], "live pass verdicts do not hide failed, blocked, or timed-out actor traces", "actor verdict findings"),
-        findingsCheck("subject state provenance", valid ? subjectStateFindings(valid) : [], "subject state claims match the recorded seed/external evidence (or the subject block is honestly absent)", "subject state findings"),
-        findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], "live shared-world runs either are absent or carry well-formed evidence for their mode (concurrent participant windows, state series and outcomes covering every role, or an older run's sequential timeline), single-plane provenance, digest-only checkpoints and the mandatory attributionLimits", "shared-world findings"),
+        findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], pass("live terminal-product evidence is complete (ledgers, redacted output, proven teardown, known spend within the cap), or the run has none"), "terminal-product findings"),
+        findingsCheck("codex app-server evidence", valid ? await validateCodexAppServerEvidence(runPaths, valid) : [], pass("live Codex app-server traces are valid and redacted, or the run has none"), "codex app-server findings"),
+        findingsCheck("actor engagement", valid ? noEngagementActorFindings(valid) : [], pass("every live actor that claims its goal took at least one action or sent a message"), "no-engagement findings"),
+        findingsCheck("actor verdict consistency", valid ? actorVerdictConsistencyFindings(valid) : [], pass("no live pass verdict hides a failed, blocked or timed-out actor"), "actor verdict findings"),
+        findingsCheck("subject state provenance", valid ? subjectStateFindings(valid) : [], pass("subject state claims match the recorded seed and external evidence, or the run makes none"), "subject state findings"),
+        findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], pass("live shared-world evidence is well formed for its mode, with single-plane provenance, digest-only checkpoints and attributionLimits, or the run has none"), "shared-world findings"),
         {
             name: "cleanup receipt",
             ok: cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok),
             message: cleanupJson === null
-                ? "cleanup receipt not present; cleanup was not requested"
-                : isCleanupResult(cleanupJson) && cleanupJson.ok
-                    ? "cleanup receipt is present and successful"
-                    : "cleanup receipt is present but malformed or failed",
+                ? "no cleanup.json; cleanup was not requested"
+                : !isCleanupResult(cleanupJson)
+                    ? "cleanup.json is malformed"
+                    : cleanupJson.ok
+                        ? "cleanup.json records a successful cleanup"
+                        : "cleanup.json records a failed cleanup",
         },
-        findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], "rerun bundles either are absent or link selected participants to their prior status and a fan-out rerun event", "rerun lineage findings"),
-        // Cost is ADVISORY on magnitude, FAIL-CLOSED on labeling/provenance (claims match mechanism).
-        // Absence PASSES (fail-open on display); a claimed dollar figure without its ratesAsOf date +
-        // source, or a total that does not match its known lines, FAILS. Magnitude is never inspected —
+        findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], pass("rerun participants link to their prior status and a fan-out rerun event, or this run is not a rerun"), "rerun lineage findings"),
+        // Cost is advisory on magnitude and fail-closed on labeling/provenance (claims match mechanism).
+        // Absence passes (fail-open on display); a claimed dollar figure without its ratesAsOf date +
+        // source, or a total that does not match its known lines, fails. Magnitude is never inspected:
         // a correctly-labeled huge estimate still passes.
-        findingsCheck("cost estimate labeling", valid ? costAndReceiptFindings(valid) : [], "cost figures are absent, or every claimed estimate carries its ratesAsOf date + source and the total matches its known lines (estimates never presented as exact)", "cost labeling findings"),
+        findingsCheck("cost estimate labeling", valid ? costAndReceiptFindings(valid) : [], pass("every cost estimate carries its ratesAsOf date and source and the total matches its lines, or the run claims no cost"), "cost labeling findings"),
     ];
     return checks;
 }

package/docs/README.md

@@ -1,31 +1,17 @@
 # Find the right doc
 
-Start with the reading order in [CONTRIBUTING.md](../CONTRIBUTING.md#read-these-in-order). This page
-sorts everything under `docs/` by what it is for. Nothing here moves files; a folder that holds more
-than one kind is split file by file.
+User guides live at [humanish.dev/docs](https://humanish.dev/docs). This page sorts the contributor
+reference under `docs/` by what it is for. To make a first change, start with
+[CONTRIBUTING.md](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#make-your-first-change).
 
 ## Follow a guide to do a task
 
-- [ramp/README.md](ramp/README.md): current state, how to pick work and the quality bar.
-- [architecture/local-browser-runtime.md](architecture/local-browser-runtime.md): run a study in a
-  local Firecracker browser.
-- [architecture/real-email-receiving.md](architecture/real-email-receiving.md) and
-  [architecture/comms-inbox.md](architecture/comms-inbox.md): give participants real or captured
-  inboxes.
-- [architecture/participant-media.md](architecture/participant-media.md) and
-  [architecture/desktop-recording.md](architecture/desktop-recording.md): add a camera, speech or
-  a desktop video.
-- [architecture/observer-review.md](architecture/observer-review.md): watch and review a study.
-- [architecture/project-layout.md](architecture/project-layout.md): the `humanish/` and
-  `.humanish/` folders `init` creates.
-- [product/lobby-trivia-3player-external-public.md](product/lobby-trivia-3player-external-public.md):
-  a worked example of the external-public shared-world lab.
-- [release/open-source-readiness.md](release/open-source-readiness.md): the release gates and the
-  publish procedure. Its opening audit is a dated snapshot.
+- [ramp/README.md](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md): current state, how to pick work and the quality bar.
+- [release/publish.md](https://github.com/danielgwilson/humanish/blob/main/docs/release/publish.md): check a release candidate, tag it and publish it.
 
 ## Look up what the code does now
 
-- [contracts/](contracts/schemas.md): bundle, lab, policy, feedback, analysis and cost contracts.
+- [contracts/](contracts/README.md): bundle, study, policy, feedback, analysis and cost contracts.
   Documented fields are API. [contracts/schemas.md](contracts/schemas.md) indexes every schema.
 - [architecture/observer.md](architecture/observer.md), [architecture/serve.md](architecture/serve.md):
   the Observer and the run library server.
@@ -33,35 +19,42 @@ than one kind is split file by file.
   [architecture/browser-control.md](architecture/browser-control.md),
   [architecture/guest-desktop.md](architecture/guest-desktop.md): hosted desktops, the browser
   control protocol and the guest runtime.
-- [architecture/state-driven-executor.md](architecture/state-driven-executor.md): the `CuaExecutor`
+- [architecture/state-driven-executor.md](architecture/state-driven-executor.md): the `ComputerUseExecutor`
   library path.
 - [architecture/task-protocol-support.md](architecture/task-protocol-support.md): which routes
-  accept `actors[0].tasks`.
+  accept `actor.tasks`.
 - [architecture/external-public-shared-world.md](architecture/external-public-shared-world.md) and
   [architecture/terminal-product-route.md](architecture/terminal-product-route.md): two routes in
-  depth. Both keep dated slice notes beside the current rules.
+  depth.
 - [architecture/restricted-codex-analysis.md](architecture/restricted-codex-analysis.md) and
   [product/automatic-analysis.md](product/automatic-analysis.md): study analysis.
-- [release/public-readiness-standard.md](release/public-readiness-standard.md): what may appear in
+- [release/public-readiness-standard.md](https://github.com/danielgwilson/humanish/blob/main/docs/release/public-readiness-standard.md): what may appear in
   the public repository and the npm package.
 
 ## Read why the code is shaped this way
 
-- [principles/](principles/engineering.md): engineering, invariants and defaults, actor fidelity,
-  the three roles and the self-driving harness.
+- [principles/engineering.md](principles/engineering.md),
+  [principles/invariants-and-defaults.md](principles/invariants-and-defaults.md),
+  [principles/actor-fidelity.md](principles/actor-fidelity.md),
+  [principles/three-roles.md](principles/three-roles.md) and
+  [principles/self-driving-harness.md](principles/self-driving-harness.md): engineering,
+  invariants and defaults, actor fidelity, the three roles and the self-driving harness.
 - [decisions/](decisions/README.md): one record per decision, each naming the code or test that
   enforces it.
 - [architecture/actor-contract.md](architecture/actor-contract.md) and
   [architecture/github-feedback-loop.md](architecture/github-feedback-loop.md): design records with
   their context and open items.
-- [product/open-source-install-experience.md](product/open-source-install-experience.md): the
-  product target for install and first run.
 
-## Treat these folders as history
+## Check the current state and the evidence behind it
 
-`goals/`, `plans/` and `roadmap/` hold dated plans, status logs and receipts. They may name files
+- [status.md](https://github.com/danielgwilson/humanish/blob/main/docs/status.md): what ships today, by surface, and the work that is gated.
+- [evidence/](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/README.md): dated study records that the README, the site and these pages
+  cite. `docs:check` covers them.
+
+## Treat history as history
+
+[history/](https://github.com/danielgwilson/humanish/blob/main/docs/history/README.md) holds dated goal packets, plans and the roadmap. They may name files
 that have since moved, so `docs:check` skips them (`HISTORY_DIRECTORIES` in
-[scripts/lib/doc-paths.ts](../scripts/lib/doc-paths.ts)). One file there is current:
-[goals/current.md](goals/current.md), the live status page.
+[scripts/lib/doc-paths.ts](https://github.com/danielgwilson/humanish/blob/main/scripts/lib/doc-paths.ts)).
 
 `assets/` holds images that ship in the npm package, such as the README hero.

package/docs/architecture/actor-contract.md

@@ -1,32 +1,29 @@
 # Actor Contract
 
-Date: 2026-06-06 (current-state note updated 2026-09-30)
-
-Status: accepted contract with a partially open extension surface. Shipped: the evidence
-schema `humanish.actor-trace.v1` (`src/actors/contract.ts`) and a closed first-party
-registry of five descriptors (`src/actors/registry.ts`: `codex-app-server`,
-`openai-computer-use`, `local-agent`, `scripted-browser`, `codex-exec`). `actors[0].type`
-is a real dispatch key on the computer-use, scripted-browser, and terminal-product routes.
-Product scoring, feedback, and artifact hooks are extension seams, but public out-of-tree
-actor registration and its conformance certification are not shipped. Also not shipped: the
-full `Actor.run(input)` interface, `ApprovalPolicy`, `StagehandCuaActor`, and the
-`persona-fidelity` verify check. `RedactionHooks` ships in `src/evidence/redaction.ts`, and
-the computer-use loop takes it; the other adapters do not take it yet. Of the capabilities,
-routing checks `lanes` and `producesScreenshots` (`src/lab/routing.ts`): an actor that
-declares no screenshots cannot run on the computer-use or scripted-browser route. Decision
-6's capture-time screenshot stance was recanted in 0.6.0; see the inline notes and the
+Part of this contract ships and part is still open. Shipped: the evidence schema
+`humanish.actor-trace.v1` (`src/actors/contract.ts`) and a closed first-party registry of five
+descriptors (`src/actors/registry.ts`: `codex-app-server`, `openai-computer-use`, `local-agent`,
+`scripted-browser`, `codex-exec`). `actor.type` is a real dispatch key on the computer-use,
+scripted-browser, and terminal-product routes. Product scoring, feedback, and artifact hooks are
+extension seams, but public out-of-tree actor registration and its conformance certification are not
+shipped. Also not shipped: the full `Actor.run(input)` interface, `ApprovalPolicy`,
+`StagehandCuaActor`, and the `persona-fidelity` verify check. `RedactionHooks` ships in
+`src/evidence/redaction.ts`, and the computer-use loop takes it; the other adapters do not take it
+yet. Of the capabilities, routing checks `lanes` and `producesScreenshots` (`src/lab/routing.ts`):
+an actor that declares no screenshots cannot run on the computer-use or scripted-browser route.
+Decision 6's capture-time screenshot stance was recanted in 0.6.0; see the inline notes and the
 capture-vs-publish rule in
 [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md).
 
-`codex-exec` is a real dispatch key for terminal-product labs, but the exported
+`codex-exec` is a real dispatch key for terminal-product studies, but the exported
 descriptor `runSession` is a fail-closed compatibility entry. Live execution is
 owned by `runTerminalProductLab`, which coordinates sandbox creation,
 command-scoped runtime auth, evidence, caps, and by-id cleanup.
 
-#955 removed the `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and
-the `in-process-sdk` protocol. No lab route dispatched either descriptor, and a
-lab that names one now fails to parse. A signed-in Claude Code drives computer-use studies
-through `local-agent`, which plugs into the provider-neutral `CuaProvider` port
+The `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and the
+`in-process-sdk` protocol were removed. No study route dispatched either descriptor, and a
+study that names one now fails to parse. A signed-in Claude Code drives computer-use studies
+through `local-agent`, which plugs into the provider-neutral `ComputerUseProvider` port
 (`src/actors/computer-use/loop/types.ts`, re-exported from `loop.ts`).
 
 ## Context
@@ -64,7 +61,7 @@ API surface.
    Agent SDK, Stagehand). The existing Codex app-server integration is the
    reference adapter. `pi-agent-core` was planned as the first in-process-SDK
    adapter to prove both shapes early; it shipped only as a trace mapper with no
-   route, and #955 removed it.
+   route, and was removed.
 
 2. **One normalized evidence schema: `humanish.actor-trace.v1`.** Four producers map
    their records onto one `ActorTrace` with a typed `items[]`:
@@ -81,7 +78,7 @@ API surface.
    The Codex app-server still writes its own `humanish.codex-app-server-trace.v1` record
    (`CodexAppServerTrace` in `src/actors/codex/app-server-trace.ts`), which
    `codexResultToActorTrace` converts. The Claude Agent SDK `ToolUse`/`ToolResult` and pi
-   `tool_execution_*` mappers went with their adapters in #955.
+   `tool_execution_*` mappers were removed with their adapters.
 
 3. **A run is multi-turn within one trace; it stops on goal, abandonment, unrecoverable
    failure, or a wall-clock safety timeout, never on a turn cap.** Turn count is explicitly
@@ -96,7 +93,7 @@ API surface.
 4. **Redaction is injected once, never re-implemented per adapter.** Every
    adapter receives `RedactionHooks` (the shared secret/path/prompt-digest
    redaction, plus screenshot redaction) and must route all persisted evidence
-   through it. This is also where the remaining consolidation of #107 lands.
+   through it.
 
 5. **The registry refuses capability mismatches.** Each adapter declares
    `ActorCapabilities`. A scenario that needs `producesScreenshots` (a GUI
@@ -287,27 +284,27 @@ export interface Actor {
   public-safe: redacted message, coarse loop phase, last normalized UI action,
   and last screenshot reference only. Do not persist raw stacks, env values,
   target URLs, or unredacted provider payloads in the trace.
-- **Capabilities.** Declare them honestly. Routing refuses an actor whose `lanes` or
+- **Capabilities.** Declare only what the actor does. Routing refuses an actor whose `lanes` or
   `producesScreenshots` do not fit the route; the other capabilities are not checked.
-- **Cost (estimate vs. charge).** `tokenUsage.costUsd` stays RESERVED for a
+- **Cost (estimate vs. charge).** `tokenUsage.costUsd` stays reserved for a
   real, provider-returned charge (the codex path); a bare `costUsd`
   always means "the provider billed this". The optional `estimatedCost`
-  (`humanish.actor-estimated-cost.v1`) is a SEPARATE, differently-named field: a
+  (`humanish.actor-estimated-cost.v1`) is a separate, differently-named field: a
   token-derived rate-table multiply from the operator-editable `src/run/pricing.ts`,
-  labeled honestly as an estimate and projected up into `RunBundle.cost` (see
+  labeled as an estimate and projected up into `RunBundle.cost` (see
   [`../contracts/schemas.md`](../contracts/schemas.md) → Run Cost Summary And
-  Estimated Actor Cost). The CUA lab computes and attaches `estimatedCost` at the
-  lab boundary before persisting the trace, so the pure computer-use loop never
+  Estimated Actor Cost). The CUA study computes and attaches `estimatedCost` at the
+  study boundary before persisting the trace, so the pure computer-use loop never
   depends on the pricing table. An unknown model yields
   `estimatedCostUsd: null` + a `reason`, never a guessed charge.
 
-## The scripted-browser route (shipped)
+## The scripted-browser route
 
 `scripted-browser` is the deterministic, model-free browser-actuation route, distinct from
 `computer-use` (raw pixels + a model deciding actions). The registered
 `scripted-browser` actor (`src/actors/scripted-browser/`) replays a committed scenario's
-browser steps with playwright against a loopback app; the steps ARE the behavior, so
-`byoModel: false` means there is NO model, and `tokenUsage` records zeros as an affirmative
+browser steps with playwright against a loopback app; the steps are the behavior, so
+`byoModel: false` means there is no model, and `tokenUsage` records zeros as an affirmative
 $0 declaration that is true by mechanism (no provider client is importable from that code
 path). Its trace keeps the concrete driver name `provider: "browser-persona"` (matching the
 native `humanish.browser-persona-trace.v1` it also emits) with `protocol: "scripted-steps"`.
@@ -322,16 +319,16 @@ has no persona patience and no approvals.
 
 ### The time budget vs. a stuck timeout (`budget_reached`)
 
-`execution.timeoutMs` is a GENEROUS wall-clock SAFETY cap, not a goal. An open-ended
+`execution.timeoutMs` is a generous wall-clock safety cap, not a goal. An open-ended
 "watch it play" session has no success predicate, because productive play is the outcome. So
 the computer-use loop distinguishes two ways to hit the cap:
 
-- **`budget_reached`**: the deadline was reached AFTER at least one material (non-idle)
+- **`budget_reached`**: the deadline was reached after at least one material (non-idle)
   action, or a spend, adapter or token limit ended the session. This maps to `ActorStatus:
 "incomplete"`: the participant did not reach the goal, and the harness did not fail.
   `participantOutcomeOk` is false, the verdict is `fail`, and the CLI exits `2`. The trace
   `reason` and optional `stopCause` say which limit ended the session.
-- **`timed_out`**: the deadline was reached with ZERO material actions (a hung provider, an
+- **`timed_out`**: the deadline was reached with zero material actions (a hung provider, an
   idle-only stall). This maps to `ActorStatus: "timed_out"`, `participantOutcomeOk` is false, the
   verdict is `timed_out`, and the CLI exits `2`.
 
@@ -342,7 +339,7 @@ switch with no default, so a new completion reason forces a compile-time decisio
 status. ~30 min (`1_800_000`) is a reasonable default for open-ended watch; the persona
 still stops early on `goal_satisfied`/`gave_up`/`stopWhen`.
 
-Actuation-vs-spend gate: on the scripted lab route `scenario.mode: live` is still required
+Actuation-vs-spend gate: on the scripted route `mode: live` is still required
 even though provider spend is $0 by mechanism. The gate's justification there is actuation,
 not cost: a live scripted run drives a real browser against a real running app
 (state-mutating effects on the operator's app), which deserves the same affirmative
@@ -351,8 +348,8 @@ this paragraph is the record of that decision.
 
 ## Optional closing report
 
-`CuaProvider.debrief` is an optional read-only request after a structured
-`stopWhen` or dwell stop. It returns a `CuaTurn` with `closingReport` containing
+`ComputerUseProvider.debrief` is an optional read-only request after a structured
+`stopWhen` or dwell stop. It returns a `ComputerUseTurn` with `closingReport` containing
 `summary` and `frictionReports`; an empty friction list is valid. The loop rejects
 actions, pending safety checks, and invalid report shapes. It redacts accepted
 reports, records them in `ActorTrace.debrief`, and projects one readable message
@@ -367,39 +364,40 @@ from interaction turns, and reported usage contributes to aggregate cost.
 
 The OpenAI implementation makes one request with tools disabled and structured
 output; no HTTP or policy retries. Stateless/ZDR mode does not offer retrospective
-reporting because it does not retain the required session history. The
-[paired live receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/structured-closing-report-2026-09-05.md)
+reporting: its client-carried conversation summarizes its oldest turns past a token
+budget, so it may not hold the whole session a retrospective report needs. The
+[paired live receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/structured-closing-report-2026-09-05.md)
 records both report recovery and control failures in the separate legacy parser.
 
-## The state-driven executor seam (shipped)
+## The state-driven executor seam
 
-The `CuaExecutor` / `CuaProvider` ports are the concrete realization of the "plural harnesses /
+The `ComputerUseExecutor` / `ComputerUseProvider` ports are the concrete realization of the "plural harnesses /
 transport-agnostic" intent above: the computer-use loop does not require a screen or a vision
 model. A library caller can drive an **already-running local app** through its in-process JS
-contract (`window.app.getState()` etc.) with a custom `CuaExecutor` (screenshot optional,
-`appState` as the progress signal) paired with a **non-vision** `CuaProvider` (`requiresFrame`
-falsey), keeping the whole lab composition with NO E2B desktop and NO clone. See
+contract (`window.app.getState()` etc.) with a custom `ComputerUseExecutor` (screenshot optional,
+`appState` as the progress signal) paired with a **non-vision** `ComputerUseProvider` (`requiresFrame`
+falsey), keeping the whole study composition with no E2B desktop and no clone. See
 [`state-driven-executor.md`](./state-driven-executor.md) for the port, both entry points
-(`runComputerUseLoop` and `runLab` + `inProcess`/`createProvider`), the `subject.source:
+(`runComputerUseLoop` and `runStudy` + `inProcess`/`createProvider`), the `subject.source:
 local-app` config surface, the `requiresFrame` provider-authoring contract, and the
 appState-is-runtime-only stance.
 
-## The product-adapter extension seam (shipped in the terminal-product route, layer 6)
+## The product-adapter extension seam
 
-The terminal-product route carries the proof-roadmap layer-6 deliverable: a product adopter
-attaches product-specific scoring + feedback as a THIN in-repo extension WITHOUT forking
+The terminal-product route has a product-adapter extension seam: a product adopter
+attaches product-specific scoring + feedback as a thin in-repo extension without forking
 core. The seam is exported contract types (`RunBundle`, `RunFeedbackCandidate`,
 `RunAdapterScore`, `ActorTrace`, `AdapterScorerModule` and the terminal-route
-`TerminalProductScoringContext`) plus a registrable scorer module, `RunLabOptions.scorer`,
+`TerminalProductScoringContext`) plus a registrable scorer module, `RunStudyOptions.scorer`,
 with optional `score` and `deriveFeedback`. The older `terminalHooks` and `cuaHooks` bags were
-removed from `RunLabOptions`. The adapter records its product nouns ONLY
-under an adapter-NAMESPACED block (`RunFeedbackCandidate.adapter` /
+removed from `RunStudyOptions`. The adapter records its product nouns only
+under an adapter-namespaced block (`RunFeedbackCandidate.adapter` /
 `RunAdapterScore.{namespace,data}`), so core's enums stay product-agnostic: no adopter noun
 is hardcoded into a core enum. Default (no hook) behavior is unchanged. See
-[`terminal-product-route.md`](./terminal-product-route.md#slice-4-the-product-adapter-extension-seam-layer-6)
+[`terminal-product-route.md`](./terminal-product-route.md#the-product-adapter-extension-seam)
 for the full seam and the thin-adapter conformance proof.
 
-## Making personas load-bearing
+## Making personas change the actor's behavior
 
 The original bug, now fixed: `loadDryRunInputs` (`src/run/dry-run-inputs.ts`) parsed
 persona YAML down to `{ id, name, source, sourceDigest }` and discarded `summary`,
@@ -459,7 +457,7 @@ traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }`
    - Stagehand remains roadmap. This rule once planned a pi binding (`systemPrompt` +
      `beforeToolCall`) and a Claude Agent SDK one (`systemPrompt` + `allowedTools`). pi
      shipped only as a trace mapper, the Claude Agent SDK descriptor never had a route, and
-     #955 removed both.
+     both were removed.
 
    None of these uses a `max_turns`-style cap as the persona stop condition.
 
@@ -513,7 +511,7 @@ Non-obvious tradeoffs to revisit with real-run data:
 - `persona-fidelity` treats a `gave_up` with no cited friction as a fidelity
   failure, not an accepted stop, so the model cannot quietly quit for no reason.
 
-This keeps patience load-bearing and reproducible without ever using elapsed
+So patience decides when a run stops, reproducibly, without ever using elapsed
 turns as a stop signal.
 
 ## Capability matrix (target adapters)
@@ -525,41 +523,12 @@ turns as a stop signal.
 | claude-agent-sdk (removed)                                                                    | yes (SDK + `-p` stream-json) | typed ToolUse/ToolResult + cost           | OS sandbox + dontAsk/allowedTools    | Anthropic-centric       | SDK MIT (CLI proprietary) | code, app    |
 | stagehand-cua (roadmap, not shipped; `openai-computer-use` is the shipped computer-use actor) | yes (SDK, mode:'cua')        | structured results + replay               | Playwright/Browserbase isolation     | OpenAI/Anthropic/Google | MIT                       | computer-use |
 
-## Sequencing
-
-1. This document.
-2. Shared `RedactionHooks` module (completes the remaining #107 criterion) plus
-   the `Actor` contract types, with the Codex integration refactored to implement
-   `Actor` and emit `ActorTrace` behind the back-compat alias. Add an
-   `actorRegistry`; generalize `RunStream.codex` to `RunStream.actor`.
-3. Personas load-bearing: `ResolvedPersona`, `personaToDirectives`, harness turn
-   budget, and the `persona-fidelity` verify check.
-4. `pi-agent-core` adapter (proves the contract against a non-Codex protocol;
-   local-model dogfood for ~$0). Landed in two slices: first the pure
-   `piSessionToActorTrace` mapper + registry generalization (discriminated
-   `ActorDescriptor` union + `getActor` overloads) + a fixture conformance test,
-   with no pi dependency and no model key required (proves the evidence contract
-   is provider-neutral); then a follow-up live SDK shim behind a DI seam, deferred
-   until the package identity (`@earendil-works/pi-agent-core` vs
-   `@mariozechner/pi-coding-agent`) and the Node `>=22.19` vs engines `>=20` gap
-   are pinned against an installed build. The live shim never landed, and #955
-   removed the mapper-only descriptor because no route dispatched it.
-5. `claude-agent-sdk` adapter (the `app` run kind). It shipped as a descriptor with
-   a live session but no route, and #955 removed it along with the `app` run kind.
-6. Computer-use route. (Shipped as `openai-computer-use`: registered 0.3.0,
-   lab-dispatched 0.4.0; `stagehand-cua` as a multi-provider front remains
-   not-yet-shipped roadmap.)
-7. Cross-harness conformance test: one persona x scenario through every adapter,
-   asserting identical trace shape, completion vocabulary, and redaction status.
-8. The proof point: run the harness-plural loop against popular OSS repos and turn
-   real, merged issues into the receipt.
-
 ## Risks
 
 - Protocol/version drift across four moving harnesses. Pin every binary/SDK and
   assert the init handshake; the registry refuses an actor whose declared
   capabilities do not satisfy the scenario.
-- Screenshot PII in the computer-use route. Redaction binds the PUBLISH
+- Screenshot PII in the computer-use route. Redaction binds the publish
   boundary, not capture (0.6.0): raw frames stay local in gitignored
   `.humanish/` and are never emitted by a publish command (this repo's CI
   binary-asset scan also blocks them from commit);
@@ -578,4 +547,4 @@ turns as a stop signal.
 
 - Self-driving harness principles: `docs/principles/self-driving-harness.md`.
 - Observer architecture: `docs/architecture/observer.md`.
-- Related issues: shared redaction module (#107), PII/PHI detector (#108).
+- Open issue: [a PII/PHI detector for the redaction gate](https://github.com/danielgwilson/humanish/issues/108).