humanish 0.110.0 → 0.110.1

package/dist/verify/liveness.d.ts

@@ -1,7 +1,23 @@
 import type { RunBundle } from "../run/bundle.js";
 import type { PreparedRunArtifactPaths } from "../run/paths.js";
+/** What verify can say about a run that is not finished. */
+export interface UnfinishedRun {
+    liveness: "running" | "interrupted";
+    /**
+     * clean: the run's reclaim receipt records every sandbox gone and a finished search of E2B by
+     * the run's tags. unconfirmed: it records a sandbox not confirmed gone, or the run journaled one
+     * it does not cover. unknown: there is no reclaim receipt, or it records no finished tag search
+     * (written by humanish 0.110.0 or earlier, or by a reclaim that did not finish), so a sandbox whose
+     * id never reached a receipt could still run.
+     */
+    sandboxes: "clean" | "unconfirmed" | "unknown";
+}
 /**
- * One warning when the run is not finished, by the run index's rule: its status record when it
- * has a usable one, else a participant still `running` in its bundle's `simulations[]`. Empty for a finished run.
+ * One warning, and the unfinished-run facts, when the run is not finished, by the run index's
+ * rule: its status record when it has a usable one, else a participant still `running` in its
+ * bundle's `simulations[]`. Nothing for a finished run.
  */
-export declare function runNotFinishedWarnings(runPaths: PreparedRunArtifactPaths, bundle: RunBundle, nowMs?: number): Promise<string[]>;
+export declare function runNotFinished(runPaths: PreparedRunArtifactPaths, bundle: RunBundle, nowMs?: number): Promise<{
+    warnings: string[];
+    unfinished?: UnfinishedRun;
+}>;

package/dist/verify/liveness.js

@@ -1,6 +1,7 @@
-// `humanish verify`'s RUN_NOT_FINISHED warning. Verify checks the integrity of what a run wrote,
-// and a run killed mid-way leaves an in-progress bundle that passes those checks. The warning says
-// what verify saw on disk, so `ok: true` is not read as "the run finished". It never flips `ok`.
+// `humanish verify`'s RUN_NOT_FINISHED warning and the unfinished-run facts its one-line output
+// leads with. Verify checks the integrity of what a run wrote, and a run killed mid-way leaves an
+// in-progress bundle that passes those checks. The warning says what verify saw on disk, so
+// `ok: true` is not read as "the run finished" or "its sandboxes stopped". It never flips `ok`.
 import { sandboxIdDigest } from "../evidence/redaction.js";
 import path from "node:path";
 import { readRunJsonIfExists, readRunTextIfExists } from "../run/locate.js";
@@ -9,19 +10,21 @@ import { RECLAIM_RECEIPT_ARTIFACT } from "../run/reclaim.js";
 import { runLiveness } from "../run/run-index.js";
 import { parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { RUN_STATUS_FILE } from "../run/status.js";
+import { plural } from "../run/text.js";
 /** The stable code every RUN_NOT_FINISHED warning starts with. */
 const RUN_NOT_FINISHED = "RUN_NOT_FINISHED";
 const GONE_STATES = new Set(["killed", "already-gone"]);
 /**
- * One warning when the run is not finished, by the run index's rule: its status record when it
- * has a usable one, else a participant still `running` in its bundle's `simulations[]`. Empty for a finished run.
+ * One warning, and the unfinished-run facts, when the run is not finished, by the run index's
+ * rule: its status record when it has a usable one, else a participant still `running` in its
+ * bundle's `simulations[]`. Nothing for a finished run.
  */
-export async function runNotFinishedWarnings(runPaths, bundle, nowMs = Date.now()) {
+export async function runNotFinished(runPaths, bundle, nowMs = Date.now()) {
     const runId = path.basename(runPaths.absoluteRunRoot);
     const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
     const { liveness, record } = runLiveness(runId, status, bundle, nowMs);
     if (liveness === "finished")
-        return [];
+        return { warnings: [] };
     const seen = [];
     if (record === undefined) {
         const running = bundle.simulations.filter((simulation) => simulation.status === "running");
@@ -39,30 +42,48 @@ export async function runNotFinishedWarnings(runPaths, bundle, nowMs = Date.now(
     const runningStreams = bundle.streams.filter((stream) => stream.status === "running").length;
     seen.push(`${runningStreams} of ${bundle.streams.length} streams are still running`);
     const reclaim = await reclaimState(runPaths, runId);
-    return [
-        `${RUN_NOT_FINISHED}: ${seen.join("; ")}.${reclaim === "" ? "" : ` ${reclaim}`} Verify ok covers the integrity of what was written; it does not mean the run finished.`,
-    ];
+    return {
+        warnings: [
+            `${RUN_NOT_FINISHED}: ${seen.join("; ")}. ${reclaim.text} Verify ok covers the integrity of what was written; it does not mean the run finished.`,
+        ],
+        unfinished: { liveness, sandboxes: reclaim.sandboxes },
+    };
 }
-/** What the reclaim receipt says about the sandboxes this run journaled, or what to run. */
+/** What the reclaim receipt says about this run's sandboxes, and what to run. */
 async function reclaimState(runPaths, runId) {
     const journal = await readRunTextIfExists(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
     // Matched by digest: a reclaim receipt names each sandbox by digest, and one written before it
     // did holds the raw id, which is digested here.
     const journaled = new Set((journal === null ? [] : parseSandboxReceipts(journal)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
-    const receipt = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
-    const outcomes = reclaimOutcomes(receipt, runId);
-    if (outcomes !== undefined) {
-        const gone = outcomes.filter((outcome) => GONE_STATES.has(outcome.state)).length;
-        const reclaimed = new Set(outcomes.map((outcome) => outcome.digest));
-        const missing = [...journaled].filter((id) => !reclaimed.has(id)).length;
-        return `${RECLAIM_RECEIPT_ARTIFACT} records ${gone} of ${outcomes.length} sandboxes gone${missing === 0 ? "" : `, and ${missing} journaled sandboxes are not in it`}.`;
-    }
-    if (journaled.size === 0)
-        return "";
-    return `It has no ${RECLAIM_RECEIPT_ARTIFACT}; \`humanish reclaim --run ${runId}\` stops the ${journaled.size} sandboxes it journaled.`;
+    const command = `\`humanish reclaim --run ${runId}\``;
+    const receipt = reclaimReceipt(await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT), runId);
+    if (receipt === undefined)
+        return {
+            sandboxes: "unknown",
+            text: `Sandboxes unknown: it has no ${RECLAIM_RECEIPT_ARTIFACT} and journaled ${plural(journaled.size, "sandbox", "sandboxes")}; ${command} stops those and searches E2B by this run's tags for any whose id never reached a receipt.`,
+        };
+    const { outcomes } = receipt;
+    const gone = outcomes.filter((outcome) => GONE_STATES.has(outcome.state)).length;
+    const reclaimed = new Set(outcomes.map((outcome) => outcome.digest));
+    const missing = [...journaled].filter((id) => !reclaimed.has(id)).length;
+    const recorded = `${RECLAIM_RECEIPT_ARTIFACT} records ${gone} of ${outcomes.length} sandboxes gone${missing === 0 ? "" : `, and ${missing} journaled sandboxes are not in it`}`;
+    if (gone < outcomes.length || missing > 0)
+        return {
+            sandboxes: "unconfirmed",
+            text: `Sandboxes unconfirmed: ${recorded}; ${command} retries.`,
+        };
+    if (receipt.state === "clean")
+        return {
+            sandboxes: "clean",
+            text: `Sandboxes clean: ${recorded}, and E2B listed none still tagged with this run.`,
+        };
+    return {
+        sandboxes: "unknown",
+        text: `Sandboxes unknown: ${recorded}, but it records no finished search of E2B by this run's tags; ${command} searches.`,
+    };
 }
-/** The outcomes of a reclaim receipt written for this run, or undefined when there is none. */
-function reclaimOutcomes(receipt, runId) {
+/** A reclaim receipt written for this run, or undefined when there is none. */
+function reclaimReceipt(receipt, runId) {
     if (!isRecord(receipt) || receipt.runId !== runId || !Array.isArray(receipt.outcomes))
         return undefined;
     const outcomes = [];
@@ -75,5 +96,5 @@ function reclaimOutcomes(receipt, runId) {
         const digest = typeof recorded === "string" ? recorded : sandboxIdDigest(sandboxId);
         outcomes.push({ digest, state });
     }
-    return outcomes;
+    return typeof receipt.state === "string" ? { state: receipt.state, outcomes } : { outcomes };
 }

package/dist/verify/verify.d.ts

@@ -1,4 +1,5 @@
 import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import { type UnfinishedRun } from "./liveness.js";
 export declare const VERIFY_SCHEMA = "humanish.verify-result.v1";
 export interface VerifyResult {
     schema: typeof VERIFY_SCHEMA;
@@ -21,6 +22,8 @@ export interface VerifyResult {
         }>;
     };
     warnings: string[];
+    /** Present when the run is not finished: its liveness and what is known of its sandboxes. */
+    unfinished?: UnfinishedRun;
     error?: {
         code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE";
         message: string;

package/dist/verify/verify.js

@@ -13,7 +13,7 @@ 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 { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
 import { sharedWorldEvidenceFindings } from "./shared-world.js";
@@ -137,13 +137,16 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             message: "Derived analysis contains sensitive text or unsafe artifact paths; sharing is blocked, original recording remains independently verifiable.",
         });
     const ok = checks.every((check) => check.ok);
+    const notFinished = isRunBundle(bundle)
+        ? await runNotFinished(runPaths, bundle)
+        : { warnings: [], unfinished: undefined };
     const warnings = isRunBundle(bundle)
         ? [
             ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
             ...undeclaredSubjectStateWarnings(bundle),
             ...desktopGeometryWarnings(bundle),
             ...flatContextWarnings(bundle),
-            ...(await runNotFinishedWarnings(runPaths, bundle)),
+            ...notFinished.warnings,
         ]
         : [];
     const shareSafety = isRunBundle(bundle)
@@ -175,6 +178,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         checks,
         shareSafety,
         warnings,
+        ...(notFinished.unfinished === undefined ? {} : { unfinished: notFinished.unfinished }),
         ...(ok
             ? {}
             : {

package/docs/architecture/actor-contract.md

@@ -444,7 +444,8 @@ traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }`
      receives them as thread/start `baseInstructions` (`threadStartParams` in
      `src/actors/codex/restricted-launch.ts`), on an ephemeral read-only thread whose only
      dynamic tool is `humanish_ui`. A local-agent Claude Code runs one `claude -p`
-     stream-json session with `--allowedTools Read`; the instructions open its first user
+     stream-json session restricted to Read in its folder (`claudeParticipantFlags` in
+     `src/actors/local-agent/claude-participant.ts`); the instructions open its first user
      message (`promptFor` in `src/actors/local-agent/cli.ts`), and later turns rely on the
      session's memory. `HUMANISH_LOCAL_AGENT_ONE_SHOT` instead spawns one `claude -p` per
      turn, which resends the instructions every turn.

package/docs/architecture/observer.md

@@ -93,10 +93,23 @@ Served data may also include `runtime` with `state`, `observedAt`, and
 `source: "local-run-status"`. This is a current observation of a contained,
 matching `status.json`; it never changes the run's recorded verdict or participant
 outcomes. A fresh heartbeat means running, an explicitly finalized record means
-finished, and stale or invalid timing means unknown. Missing, malformed, or
-mismatched records omit the observation. A stale heartbeat alone does not prove
-interruption, and stored PIDs are neither probed nor returned. Static rendering
-and export do not create this served-only observation.
+finished, a record the CLI's signal handler wrote means interrupted, and stale or
+invalid timing means unknown. Missing, malformed, or mismatched records omit the
+observation. A stale heartbeat alone does not prove interruption, and stored PIDs
+are neither probed nor returned. Static rendering and export do not create this
+served-only observation.
+
+`run.display` says whether the run passed: `{ state, label, tone, reason? }` from
+`runDisplay` (`src/run/display.ts`), the function every surface that shows a run's
+result calls. `state` is `passed` only when `run.status` (the verdict) is `pass` and
+`run.json`'s `outcome` does not record the run as failed. A run whose execution
+failed under a pass verdict is `failed`, with the first failure in `reason`.
+`blocked`, `timed_out`, `no_verdict`, `interrupted`, `running`, `dry_run` and
+`unknown` are the other states. For a `run.json` without an `outcome`, the served
+Observer and `observe` read `status.json` for liveness and, on a run recorded
+before `run.json` carried an outcome, for its ok. The sidebar's dot is the pass
+accent only for `passed`. observer-data.json written before `display` existed
+keeps the verdict reading.
 
 Watch is deliberately distinct from `humanish observe --all`. Watch serves one
 attached run, and the process that created it may inject runtime stream URLs
@@ -167,9 +180,11 @@ origin-dependent scripts and modules in those artifacts may require independent
 hosting. See the [CSP sandbox standard](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox).
 
 History entries may include `runtimeState` from the same contained local status
-read as the Observer. Their existing `status` remains the recorded verdict.
-Running filters should use runtime state when present, preserving the difference
-between an active study and its provisional evidence outcome.
+read as the Observer, and `display` from the run's Observer data. Their existing
+`status` remains the recorded verdict. The library's pip color and the sidebar's
+label read `display`. Running filters should use runtime state when present,
+preserving the difference between an active study and its provisional evidence
+outcome.
 
 ## UI Shape
 

package/docs/architecture/task-protocol-support.md

@@ -5,20 +5,20 @@ participant; hidden success criteria go only to the observation tracker. A route
 that cannot carry both halves refuses the declaration before execution. Removing
 `tasks` is an explicit choice to run a mission-only study, not an automatic fallback.
 
-| Execution path                                        | Task support | Mechanism                                                                                     |
-| ----------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
-| CUA, app-url, one participant or fan-out              | Supported    | The participant prompt composer renders goals; the CUA loop tracks observations               |
-| CUA, provisioned clone or local-tree, separate worlds | Supported    | Same prompt composer and loop                                                                 |
-| CUA, local-app with caller executor/provider          | Supported    | Same loop; the caller supplies observations                                                   |
-| CUA, desktop-cli                                      | Supported    | Same prompt and tracker; unavailable criterion inputs remain unmeasured                       |
-| Shared-world, provisioned or external-public          | Rejected     | Actor specs omit the protocol before CUA session dispatch                                     |
-| Terminal-product                                      | Rejected     | Terminal prompt and result contract do not implement tasks                                    |
-| Scripted-browser, local or provisioned                | Rejected     | Scenario steps drive the participant; no task protocol is consumed                            |
-| Synthetic (`this-repo`)                               | Rejected     | Study dispatch does not pass task declarations to the dry-run engine                          |
-| Any second or later `actors[]` entry                  | Rejected     | Current runners consume only the first actor; declare every participant under the first actor |
+| Execution path                                        | Task support | Mechanism                                                                       |
+| ----------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| CUA, app-url, one participant or fan-out              | Supported    | The participant prompt composer renders goals; the CUA loop tracks observations |
+| CUA, provisioned clone or local-tree, separate worlds | Supported    | Same prompt composer and loop                                                   |
+| CUA, local-app with caller executor/provider          | Supported    | Same loop; the caller supplies observations                                     |
+| CUA, desktop-cli                                      | Supported    | Same prompt and tracker; unavailable criterion inputs remain unmeasured         |
+| Shared-world, provisioned or external-public          | Rejected     | Actor specs omit the protocol before CUA session dispatch                       |
+| Terminal-product                                      | Rejected     | Terminal prompt and result contract do not implement tasks                      |
+| Scripted-browser, local or provisioned                | Rejected     | Scenario steps drive the participant; no task protocol is consumed              |
+| Preview (`this-repo`)                                 | Rejected     | Study dispatch does not pass task declarations to the dry-run engine            |
 
-Both registered CUA actors (`openai-computer-use` and `local-agent`) share the CUA
-session loop. Their task support does not depend on which provider chooses actions.
+A study has one `actor`, and its participants go in `participants`, so every participant
+gets the same tasks. Both registered CUA actors (`openai-computer-use` and `local-agent`) share
+the CUA session loop. Their task support does not depend on which provider chooses actions.
 Custom session hooks remain caller-owned implementations of that same contract;
 this preflight does not certify arbitrary hook behavior.
 

package/docs/architecture/terminal-product-route.md

@@ -33,7 +33,7 @@ fail-closed cross-validation, and forward-declared warnings.
 | `execution.runtimeAuth`           | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                               |
 | `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                     |
 | `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                          |
-| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                     |
+| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused: no adopter cost source exists until issue 347 lands                    |
 | `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                                |
 | `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                       |
 | route                             | `terminal` → `runTerminalProductStudy` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |

package/docs/contracts/run-bundle.md

@@ -70,6 +70,15 @@ artifacts:
 review:
   schema: humanish.review.v1
   verdict: "contract_proof_only|pass|fail|blocked|timed_out"
+outcome: # optional, additive: how the run ended (Run Outcome below)
+  state: "finished"
+  ok: false
+  execution:
+    succeeded: false
+    failures:
+      - kind: "harness|provider-cleanup|provider-policy|sandbox-cleanup|evidence|cap|run"
+        message: "<public-safe message>"
+    warnings: [] # omitted when empty
 redaction:
   status: "passed"
   notes: "<public-safe note>"
@@ -100,6 +109,59 @@ Persisted `run.json` files must not contain absolute local target paths. Runtime
 commands may return the caller's working directory in process-local JSON
 responses, but durable run bundles use the public-safe `[target-cwd]` marker.
 
+## Run Outcome
+
+`outcome` records how the run ended as an execution. `review.verdict` is what the
+participants experienced; `outcome.ok` is the route result's `ok`, which
+`humanish run --json` prints as `runOk`. The two differ: a terminal run whose agent passed but whose sandbox
+teardown is unproven has verdict `pass` and `ok: false`.
+
+```yaml
+# Run.finish published the final bundle.
+outcome:
+  state: finished
+  ok: true
+  execution:
+    succeeded: true
+    failures: []
+    warnings: # omitted when empty
+      - kind: sandbox-cleanup
+        message: "lane-01: Sandbox release is unconfirmed. Reclaim it by recorded id with `humanish reclaim --run <id>`."
+---
+# The CLI's signal handler stopped the run before it finished.
+outcome:
+  state: interrupted
+  ok: false
+  signal: SIGINT # or SIGTERM, SIGHUP
+  at: "<ISO timestamp>"
+```
+
+`Run.finish` (`src/run/run.ts`) writes `finished` with the route's `ok` and its
+execution outcome (`judgeExecution` in `src/run/judge.ts`). Each route's policy in
+`OUTCOME_POLICIES` decides which failure kinds fail the run and which only warn.
+An Observer that does not render is an `evidence` failure known only after
+`run.json` is on disk: `FinishedRun.renderObserver` adds it to `outcome` and to
+`status.json` before the route returns, and no Observer page exists that could
+show the run without it. Messages pass the same redaction and sandbox id scrub
+as the rest of the bundle.
+
+When a signal stops a live run, the handler writes `interrupted` into the last
+flushed `run.json`, and every later write of that run keeps it. A run stopped
+before its first flush has no `run.json`; its `status.json` is the record.
+
+`outcome` is absent while a run is in progress, when its process died without
+writing it, and on runs recorded before the field existed. For those, readers
+take liveness from `status.json` and, for an older finished run, its `ok` and
+`execution` from `status.json`'s `outcome`. That record is the only copy of an
+older run's `ok`; for a run with `outcome` in `run.json`, `status.json` copies it.
+
+Every surface that shows whether a run passed calls `runDisplay`
+(`src/run/display.ts`) with the run's liveness, verdict and `ok`: the Observer
+(`observer-data.json` `run.display`), its run library, the served Observer,
+`humanish runs`, `humanish review`, `humanish stats`, the TUI and `review.md`'s
+`outcome` line. A run
+shows as `passed` only when its verdict is `pass` and its `ok` is not false.
+
 ## Recorded session stop causes
 
 An actor trace may include `stopCause` alongside its unchanged `status`,
@@ -543,12 +605,19 @@ writing; an older one reads as interrupted. The warning names what verify saw:
 - the record's state and its last `updatedAt`, or the running `simulations[]` entries when
   there is no usable record;
 - how many streams are still `running`;
-- what `reclaim-receipt.json` records: how many of the run's sandboxes are gone
-  (killed or already gone), and how many journaled sandboxes it does not cover. It
-  matches its outcomes to the receipts by `sandboxIdDigest`; a reclaim receipt from
-  before 0.110 names raw ids, which are digested to match;
-- with journaled sandboxes and no reclaim receipt, the command that stops them:
-  `humanish reclaim --run <id>`.
+- the sandbox state, and what `reclaim-receipt.json` records: how many of the run's
+  sandboxes are gone (killed or already gone), and how many journaled sandboxes it does
+  not cover. It matches its outcomes to the receipts by `sandboxIdDigest`; a reclaim
+  receipt from before 0.110 names raw ids, which are digested to match;
+- with no reclaim receipt, the command that stops the journaled sandboxes and searches
+  E2B by the run's owner tags: `humanish reclaim --run <id>`.
+
+The result also carries `unfinished: { liveness, sandboxes }`, and the one-line output
+leads with it, for example `verified <id> (interrupted, sandboxes unknown) · share_ready`.
+`sandboxes` is `clean` only when the reclaim receipt records every sandbox gone and its
+`state` is `clean`, which means the search by tag finished. It is `unconfirmed` when the
+receipt records a sandbox not gone or misses a journaled one, and `unknown` otherwise,
+including a receipt from humanish 0.110.0 or earlier, which did not search by tag.
 
 The local-evidence check includes screenshots declared only by
 `streams[].actor.items[].screenshotRef` or `streams[].liveActor.items[].screenshotRef`,

package/docs/contracts/schemas.md

@@ -37,6 +37,7 @@ workflow without leaking private upstream truth into core.
 | Review                            | `humanish.review.v1`                                                                                                                                                           | `contract-proof-review`                                                             |
 | Study analysis                    | `humanish.study-analysis.v1`                                                                                                                                                   | see [study analysis](study-analysis.md) and synthetic analysis fixtures in `tests/` |
 | Study analysis correction         | `humanish.study-analysis-correction.v1`                                                                                                                                        | see [study analysis](study-analysis.md#human-review-and-sharing)                    |
+| Analysis findings view            | `humanish.analysis-findings.v1` (`review --json` field `analysis`; read-only projection of the selected analysis)                                                              | see [study analysis](study-analysis.md#reading-findings)                            |
 | Analysis execution receipt        | `humanish.analysis-execution.v1`                                                                                                                                               | see [study analysis](study-analysis.md#durable-records)                             |
 | Analysis execution start          | `humanish.analysis-execution-start.v1`                                                                                                                                         | see [study analysis](study-analysis.md#durable-records)                             |
 | Verification                      | `humanish.verify-result.v1`                                                                                                                                                    | `five-check-verify`                                                                 |
@@ -300,10 +301,11 @@ instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` bec
   wall-clock kill; `maxUsd`/`maxJobs` are enforced fail-closed against the cost
   ledger after the session (a run whose known spend exceeds the cap fails closed,
   `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core records Codex provider spend as
-  unpriced tokens, so without a cost probe no line can trip a positive `maxUsd`:
-  a live run refuses `maxUsd > 0` before creating a sandbox
-  (`HUMANISH_TERMINAL_UNPRICED_CAP`) unless the caller passes a `costProbe`
-  hook. The sandbox's server-side timeout is the steps before the
+  unpriced tokens and measures no product, media or payment spend, so no line can trip a
+  positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
+  (`HUMANISH_TERMINAL_UNPRICED_CAP`). A terminal `maxUsd` cap has no adopter cost source
+  until [issue 347](https://github.com/danielgwilson/humanish/issues/347) lands;
+  `StudyDeps.costProbe` is a test seam. The sandbox's server-side timeout is the steps before the
   codex command (Node bootstrap, runtime version check, and product setup when
   `subject.product.install` is declared) plus `maxMinutes` plus a 5-minute
   teardown buffer; a live run refuses a `maxMinutes` that would take it past
@@ -1088,8 +1090,8 @@ discipline** that distinguishes three states and never conflates them:
 and is never coerced to `0`); `fullyMeasured` is true only when no line is null.
 Core meters only the `provider` line, populated from the actor trace's
 `tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment`
-remain `null` unless an adapter supplies those signals through the shipped
-cost-probe seam. The terminal route records the model as `codex` and does not pin Codex's
+remain `null`, because no adopter can supply those signals until
+[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. The terminal route records the model as `codex` and does not pin Codex's
 model, so a measured token count stays `usd: null` with `source: unpriced-token-usage`, and
 `knownTotalUsd: 0` with `fullyMeasured: false` means no line of this ledger was priced. E2B
 time for the terminal sandbox is not a line of this ledger, whose lines are checked against
@@ -1149,9 +1151,13 @@ finished | interrupted, mode, study?, pid, startedAt, updatedAt, completedAt?,
 signal?, outcome? }`. A record written by 0.108 or earlier also has `lab`, with the same value as
 `study`, and readers accept it.
 `outcome` carries the bundle's `verdict`, `participants`, `estimatedCostUsd` and
-`estimatedCostComplete` when the run finishes, then the result's `ok` and `execution: { succeeded,
-failures: [{ kind, message }], warnings? }` once the Observer has rendered. The
-verdict is what the participants experienced; `execution` is whether the run
+`estimatedCostComplete` when the run finishes, with `ok` and `execution: { succeeded,
+failures: [{ kind, message }], warnings? }` copied from `run.json`'s `outcome`
+([Run Outcome](run-bundle.md#run-outcome)) in the same publication. An Observer
+that does not render adds its `evidence` failure to both files. A record written
+before `run.json` carried an outcome got `ok` and `execution` after the Observer
+rendered and is the only copy of that run's `ok`; readers use it for such a run
+only. The verdict is what the participants experienced; `execution` is whether the run
 worked as an execution (`kind` is `harness`, `provider-cleanup`,
 `provider-policy`, `sandbox-cleanup`, `evidence`, `cap` or `run`), and `ok`
 reads both under the route's policy (`OUTCOME_POLICIES` in `src/run/judge.ts`).
@@ -1177,10 +1183,13 @@ and the estimate is a lower bound. A record without it, as every record before
 
 `interrupted` with `signal` (`SIGINT`, `SIGTERM` or `SIGHUP`) is written by
 the CLI's run command when that signal stops a live run outside post-run
-analysis. It then kills the E2B sandboxes the run's `sandbox-receipts.ndjson`
-names, writes `reclaim-receipt.json` as `humanish reclaim` does, and exits
-128+n. The bundle is not finished: run.json keeps its last live flush, and no
-`outcome` is written. A `running` record that stopped refreshing still reads as
+analysis. It first prints one line saying it is stopping and refuses any further sandbox
+create. It then kills the E2B sandboxes the run's `sandbox-receipts.ndjson` names, each sandbox
+a create in flight reports as its id arrives, and each one E2B lists with the run's owner tags,
+writes `reclaim-receipt.json` as `humanish reclaim` does, and exits
+128+n. The bundle is not finished: run.json keeps its last live flush, with
+`outcome: { state: interrupted, ok: false, signal, at }` when the run had
+flushed one, and status.json gets no `outcome`. A `running` record that stopped refreshing still reads as
 interrupted once stale. A library caller of `runStudy` gets no signal handling. A
 humanish older than this field rejects the state and falls back to the bundle's
 own liveness.
@@ -1192,8 +1201,10 @@ nothing at all until they completed.
 
 It is a derived index, not evidence. `run.json` remains the evidence-of-record;
 `verify` never gates on `status.json`, nothing in it is a claim about what a
-participant did, and when the two disagree the bundle wins and the record is
-rebuildable from it. A `running` record whose `updatedAt` is older than three
+participant did, and when the two disagree the bundle wins. Fields that cannot be
+rebuilt from `run.json`: `pid`, `startedAt`, `updatedAt` and `completedAt`, which
+no bundle records, and, on a record written before `run.json` carried an
+`outcome`, `outcome.ok` and `outcome.execution`. A `running` record whose `updatedAt` is older than three
 touch intervals is interrupted, not alive. A dropped connection or a killed
 terminal leaves exactly that shape, so the record reads as interrupted
 (`classifyRunStatus` is the one shared definition). Fields are
@@ -1210,16 +1221,20 @@ them is a claim about what a participant did.
 `humanish.run-index.v1` is the listing projection. One entry per run, read
 cheapest-source-first: the `status.json` record, else the bundle, else the run
 directory alone. `{ runId, derivedFrom: status | bundle | directory, liveness,
-mode?, pid?, study?, startedAt?, updatedAt?, completedAt?, verdict?,
-participants?, estimatedCostUsd?, estimatedCostComplete?, analysisCost?,
-durationMs? }`. The point is cost: walking
+mode?, pid?, study?, startedAt?, updatedAt?, completedAt?, verdict?, ok?,
+failure?, participants?, estimatedCostUsd?, estimatedCostComplete?,
+analysisCost?, durationMs? }`. `ok` and `failure` (the first execution failure)
+are the run's own outcome; `runDisplay` (`src/run/display.ts`) reads them with
+`liveness` and `verdict`, so the TUI and `humanish stats` show a run with
+`ok: false` as failed whatever its verdict. The point is cost: walking
 every run tree and parsing every bundle measured 167ms on a 25-run project,
 against 16ms cold and 2.8ms warm here, which is what makes a surface that
 refreshes on a cadence affordable. `derivedFrom` is reported so a surprising row
 can be traced to the file it came from. A run with receipts and no outcome is
 `interrupted` (the shape a dropped connection leaves), and so is an
 in-progress bundle reached without a status record: there is no freshness to
-judge, and nothing in it says the run finished.
+judge, and nothing in it says the run finished. A bundle with an `outcome` reached
+without a status record takes its liveness from `outcome.state`.
 
 `estimatedCostUsd` is the participants-and-desktops figure from the status
 record or bundle and excludes analysis. `estimatedCostComplete` says whether that
@@ -1378,7 +1393,7 @@ usage is known or bounded:
 - A request lost without a reply (it stalled, or the OpenAI provider's
   transport threw) is booked at its worst case before it is sent again: the
   latest reported request's input at the model's highest input rate plus
-  `actors[].maxOutputTokens` at its output rate, both from `src/run/pricing.ts`.
+  `actor.maxOutputTokens` at its output rate, both from `src/run/pricing.ts`.
   The reply to the resent request replaces that input with its own. The
   request is sent again only when the estimate with that charge stays within
   `maxUsd` and the study budget. Otherwise the session ends `budget_reached`
@@ -1566,7 +1581,7 @@ of it fails.
 | `SubjectPhaseEvent`                                                                                                                            | the `subject-phase` `StudyEvent` through `onEvent`. Its `type` is `"subject-phase"`; the phase that was `type` is `name`, and `target` is `{ kind: "subject" }` or `{ kind: "participant", participant }`. `message`, `at`, `ok` and `durationMs` are unchanged                                                                                |
 | `StudyOutcome.backend`, `LabBackend`                                                                                                           | `outcome.route`                                                                                                                                                                                                                                                                                                                                |
 | `selectLabBackend`, the `routesTo*` predicates, `actorResolvesToTerminal`                                                                      | `routeOf(config)`                                                                                                                                                                                                                                                                                                                              |
-| `resolveStudyDryRun`                                                                                                                           | `RunStudyOptions.dryRun`; without it, `scenario.mode` decides                                                                                                                                                                                                                                                                                  |
+| `resolveStudyDryRun`                                                                                                                           | `RunStudyOptions.dryRun`; without it, `mode` decides                                                                                                                                                                                                                                                                                           |
 | `cuaLaneCount`                                                                                                                                 | the `plan` `StudyEvent`, which lists every participant                                                                                                                                                                                                                                                                                         |
 | `resolveSeatUrl`                                                                                                                               | `parseStudy`, which refuses a participant entry that is not same-origin loopback; build the URL with `new URL(entry, serveUrl)`                                                                                                                                                                                                                |
 | `cuaLaneValidationReason`, `sharedWorldValidationReason`, `concurrentSharedWorldValidationReason`, `externalPublicSharedWorldValidationReason` | `parseStudy`, which returns the same reason                                                                                                                                                                                                                                                                                                    |
@@ -1682,7 +1697,9 @@ the stream shape, the meaningful-use rubric, and hard-failure rules.
 Review summarizes whether evidence supports the claim. It does not replace
 verification or maintainer acceptance.
 
-`verdict` is the run gate result. `participants.reachedGoal` retains the count of
+`verdict` is what the participants experienced, collapsed to one word. Whether
+the run passed also reads `run.json`'s `outcome.ok` ([Run Outcome](run-bundle.md#run-outcome)):
+a run whose execution failed shows as failed beside a `pass` verdict. `participants.reachedGoal` retains the count of
 recorded successful sessions; it is not an independent adjudication of their
 claims. Computer-use review and Observer labels distinguish a participant's
 reported completion from a recorded `stopWhen` or dwell condition match. A

package/docs/contracts/study-analysis.md

@@ -288,6 +288,51 @@ companion project validated records; generic HTTP serving of producer-owned raw
 analysis/correction JSON, execution receipts, atomic write temporaries and locks
 is disabled. Existing adapter captures and logs retain their contained routes.
 
+## Reading findings
+
+`humanish review` prints a run's analysis findings after its participant review, and
+`humanish analyze show` prints them alone. Each finding shows its title, impact, confidence and
+recovery, the participants it affected out of those exposed, the frames its evidence cites with
+their time since the first retained capture, the capture files, its next step and the latest
+human review note. A live run's human output ends with up to three findings, one line each, and
+the `review` command that prints all of them. `analyze show --json` prints the validated
+analysis record and its corrections, as before. Reading findings never starts an analysis.
+
+`review --json` carries the same view as its `analysis` field, schema
+`humanish.analysis-findings.v1`, built in `src/cli/findings.ts`:
+
+| Field                                                                          | Meaning                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`                                                                       | `humanish.analysis-findings.v1`.                                                                                                                                                                                                                                                                                                              |
+| `runId`                                                                        | The run the view reads.                                                                                                                                                                                                                                                                                                                       |
+| `state`                                                                        | `ready`, `stale`, `running`, `none`, `skipped`, `failed`, `dry_run` or `unavailable`. Only `ready` and `stale` carry findings.                                                                                                                                                                                                                |
+| `reason`                                                                       | The stable code behind a state other than `ready`, or null: an automatic analysis reason such as `AUTOMATIC_ANALYSIS_KEY_MISSING`, a failed attempt's error code, or a load warning such as `ANALYSIS_SOURCE_CHANGED`.                                                                                                                        |
+| `message`                                                                      | What happened, in words.                                                                                                                                                                                                                                                                                                                      |
+| `next`                                                                         | The command that gets findings for this run, or null when no command can, as for a dry run or a run whose participants left no evidence.                                                                                                                                                                                                      |
+| `analysisId`, `status`, `provider`, `model`, `completedAt`, `estimatedCostUsd` | The analysis version `analyze show` selects: the newest ready one, else the newest stale one. Null without one.                                                                                                                                                                                                                               |
+| `runPath`, `path`                                                              | The run directory and the version's `analysis.json`, relative to the project directory.                                                                                                                                                                                                                                                       |
+| `summary`, `limitations`                                                       | The analysis's own summary and limitations.                                                                                                                                                                                                                                                                                                   |
+| `findings[]`                                                                   | Highest priority first: `id`, `title`, `summary`, `impact` (`blocked_task`, `friction`, `recovery`, `uncertain`), `confidence` (`low`, `medium`, `high`), `recovery` (`recovered`, `not_observed`, `unknown`), `affected[]` (`streamId`, `label`), `exposedCount`, `evidence[]`, `nextStep` and `correction`.                                 |
+| `findings[].evidence[]`                                                        | Each cited item once: `id`, `streamId`, `kind`, `bases` (how the observations used it), `frame` (the latest retained capture's index from 0, null before any capture), `elapsedMs` (time since the first retained capture, not a video offset), `at` and `capture` (the file relative to the project directory, null for nonvisual evidence). |
+| `findings[].correction`                                                        | The latest `analyze correct` note on that finding version (`status`, `reason`, `replacementClaim`), or null.                                                                                                                                                                                                                                  |
+| `warnings`                                                                     | Load warnings for the selected version.                                                                                                                                                                                                                                                                                                       |
+
+The states without findings:
+
+- `running`: the automatic analysis is queued or running. `next` is `review` again.
+- `skipped`: the automatic analysis was skipped or refused, for example without
+  `OPENAI_API_KEY`. `next` is `analyze --max-cost 3`.
+- `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`
+  reruns it with the same analyst, `--provider codex` for the Codex account analyst.
+- `none`: no analysis ran for this live run, for example with `review.analysis: false`.
+- `dry_run`: a dry run has no participant evidence to analyze.
+- `unavailable`: the run or its analysis records could not be read or checked, or the analysis
+  text matched a sensitive-text pattern (`ANALYSIS_SENSITIVE_TEXT_QUARANTINED`), which the
+  Observer withholds too.
+
+`stale` lists the findings with a warning: the run's evidence changed after the analysis, and
+`next` requests a new one. `analyze show` without `--json` exits 2 when the JSON form would.
+
 ## Human review and sharing
 
 ```bash