humanish 0.105.0 → 0.106.0

package/docs/contracts/policy.md

@@ -8,10 +8,7 @@ parser, route validation, and verifier determine whether a declared field is
 consumed, rejected, or reported as a warning.
 
 Safety amendment (2026-07-14): beginning with `0.15.1`, stored provider IDs are
-evidence and never authorize core provider mutation. The bundled OSS meta-lab
-is dry-run only; a live request fails before side effects until
-repository-derived instructions have an isolated credential boundary. Any
-historical live-OSS examples below do not override that fail-closed behavior.
+evidence and never authorize core provider mutation.
 
 ## Purpose
 
@@ -37,12 +34,12 @@ status. It never records credential values.
 
 ## Credential Classes
 
-| Class | Examples | May Be Recorded | Must Not Be Recorded |
-| --- | --- | --- | --- |
-| Executor auth | local Codex login, local shell authority, E2B desktop token, browser automation session | class name, env var name, present/missing status, authority level | tokens, cookies, session ids, raw home config, private command history |
-| Product auth | target app test account, synthetic browser state, local fixture login | synthetic fixture id, auth state class, redaction status | real emails, passwords, customer accounts, patient accounts, production cookies |
-| Provider auth | model provider key, desktop provider key, package registry token | env var name, provider class, present/missing status, spend policy | API key values, auth-bearing stream URLs, billing account identifiers |
-| Maintainer auth | GitHub token, npm publish authority, repository admin rights | required/not-required, requested authority, explicit maintainer approval status | tokens, OAuth payloads, private org metadata, mutation authority by implication |
+| Class           | Examples                                                                                | May Be Recorded                                                                 | Must Not Be Recorded                                                            |
+| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Executor auth   | local Codex login, local shell authority, E2B desktop token, browser automation session | class name, env var name, present/missing status, authority level               | tokens, cookies, session ids, raw home config, private command history          |
+| Product auth    | target app test account, synthetic browser state, local fixture login                   | synthetic fixture id, auth state class, redaction status                        | real emails, passwords, customer accounts, patient accounts, production cookies |
+| Provider auth   | model provider key, desktop provider key, package registry token                        | env var name, provider class, present/missing status, spend policy              | API key values, auth-bearing stream URLs, billing account identifiers           |
+| Maintainer auth | GitHub token, npm publish authority, repository admin rights                            | required/not-required, requested authority, explicit maintainer approval status | tokens, OAuth payloads, private org metadata, mutation authority by implication |
 
 Synthetic fixture:
 
@@ -76,14 +73,14 @@ credentials:
 Network policy describes where a run may connect. It is not a hidden allowlist
 for credentials.
 
-| Mode | Meaning | Default For |
-| --- | --- | --- |
-| `no_network` | No external network calls. | contract docs, local unit tests |
-| `local_only` | Localhost and loopback only. | Observer, local fixtures |
-| `public_oss` | Public GitHub clone/fetch of owner/repo slugs only. | disposable OSS smoke |
-| `authorized_private` | Token-backed clone/fetch of repos the maintainer is already authorized to access, with repo labels redacted by default. | local maintainer dogfood only |
-| `provider_substrate` | Explicit provider substrate such as hosted desktop streams. | live routes with an isolated credential boundary and in-process resource handles |
-| `custom_allowlist` | Adapter-declared public hosts. | target-specific adapters |
+| Mode                 | Meaning                                                                                                                 | Default For                                                                      |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `no_network`         | No external network calls.                                                                                              | contract docs, local unit tests                                                  |
+| `local_only`         | Localhost and loopback only.                                                                                            | Observer, local fixtures                                                         |
+| `public_oss`         | Public GitHub clone/fetch of owner/repo slugs only.                                                                     | `clone` subjects that name a public owner/repo                                   |
+| `authorized_private` | Token-backed clone/fetch of repos the maintainer is already authorized to access, with repo labels redacted by default. | local maintainer dogfood only                                                    |
+| `provider_substrate` | Explicit provider substrate such as hosted desktop streams.                                                             | live routes with an isolated credential boundary and in-process resource handles |
+| `custom_allowlist`   | Adapter-declared public hosts.                                                                                          | target-specific adapters                                                         |
 
 Synthetic fixture:
 
@@ -112,12 +109,12 @@ labels, ignored artifact paths, and verifier status.
 
 Spend policy names when provider costs may be incurred.
 
-| Mode | Meaning |
-| --- | --- |
-| `no_spend` | No provider calls that can bill. |
-| `dry_run_only` | Only local contract proof; no live substrate. |
+| Mode                     | Meaning                                                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `no_spend`               | No provider calls that can bill.                                                                   |
+| `dry_run_only`           | Only local contract proof; no live substrate.                                                      |
 | `explicit_live_provider` | Provider calls allowed because required env var names are present and operator intent is explicit. |
-| `maintainer_approved` | Reserved for publish, billing, or high-risk mutation workflows. |
+| `maintainer_approved`    | Reserved for publish, billing, or high-risk mutation workflows.                                    |
 
 Synthetic fixture:
 
@@ -129,7 +126,7 @@ providerClasses:
   - model
   - desktop_substrate
 operatorIntent:
-  command: humanish lab run oss --json --no-open
+  command: humanish lab run my-lab --json --no-open
   explicit: true
 budget:
   limit: unspecified
@@ -165,11 +162,11 @@ Required redaction gates:
 `humanish verify` separates bundle validity from public promotion with
 `shareSafety`:
 
-| Status | Meaning |
-| --- | --- |
-| `share_ready` | The bundle passed verification and has no known local-only evidence posture. Feedback commands may render public issue drafts. |
-| `local_only` | The bundle passed verification and is useful local evidence, but should not be shared as-is. Current example: full-fidelity raw screenshots. |
-| `blocked` | Verification or public-safety checks failed. The bundle must not be promoted. |
+| Status        | Meaning                                                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `share_ready` | The bundle passed verification and has no known local-only evidence posture. Feedback commands may render public issue drafts.                                              |
+| `local_only`  | The bundle passed verification and is useful local evidence, but should not be shared as-is. Examples: full-fidelity raw screenshots, or a file verify cannot read as text. |
+| `blocked`     | Verification or public-safety checks failed. The bundle must not be promoted.                                                                                               |
 
 Feedback commands fail closed unless `shareSafety.status` is `share_ready`.
 This keeps the default raw-screenshot capture useful for local review without
@@ -224,7 +221,7 @@ Not allowed by default:
 - use maintainer tokens from the environment.
 
 Maintainer automation can be built later as a separate, token-explicit,
-dry-run-first tool. It must not be required for ordinary Humanish feedback.
+dry-run-first tool. It must not be required for ordinary humanish feedback.
 
 Synthetic fixture:
 
@@ -249,7 +246,7 @@ Examples:
 - human edits the target repo during the run;
 - human copies hidden browser state into a fixture;
 - human clicks through product UI while the actor only observes;
-- operator restarts a provider substrate lane and continues the same run;
+- operator restarts a participant's provider substrate and continues the same run;
 - support staff or private upstream context resolves the blocker.
 
 Assisted runs can produce useful observations, but they are non-comparable to

package/docs/contracts/run-bundle.md

@@ -3,7 +3,8 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: `humanish.run-bundle.v1` is the shipped evidence contract. The
-TypeScript shape and fail-closed verification in `src/run.ts` are
+TypeScript shape in `src/run/bundle.ts` (with `streams[]` in `src/run/streams.ts` and
+`sharedWorld` as `SharedWorldEvidence` in `src/run/shared-world-evidence.ts`) and fail-closed verification in `src/verify/verify.ts` are
 authoritative; this document explains the stable public fields and extension
 rules rather than independently versioning the runtime.
 
@@ -47,6 +48,20 @@ lifecycle:
   - at: "<ISO timestamp>"
     event: "run.created"
     message: "<public-safe message>"
+persona:
+  id: "<persona id>"
+  name: "<persona name>"
+  source: "<persona source>"
+  sourceDigest: "<sha256>"
+scenario:
+  id: "<scenario id>"
+  title: "<scenario title>"
+  goal: "<scenario goal>"
+  source: "<scenario source>"
+  sourceDigest: "<sha256>"
+simulations: [] # simCount entries, each paired with its streams
+streams: []
+events: []
 artifacts:
   run: "run.json"
   reviewJson: "review.json"
@@ -56,6 +71,9 @@ artifacts:
 review:
   schema: humanish.review.v1
   verdict: "contract_proof_only|pass|fail|blocked|timed_out"
+redaction:
+  status: "passed"
+  notes: "<public-safe note>"
 adapterScore:
   schema: humanish.adapter-score.v1
   namespace: "<adapter namespace>"
@@ -88,9 +106,16 @@ responses, but durable run bundles use the public-safe `[target-cwd]` marker.
 An actor trace may include `stopCause` alongside its unchanged `status`,
 `completionReason` and verbatim `reason`. Computer-use sessions distinguish
 `provider_output_limit`, `provider_token_limit`, `time_limit`, `spend_limit`,
-`study_spend_limit`, `adapter_limit`, `provider_incomplete`, `provider_status`, and
-`harness_aborted`. Absence means the route or recording did not retain this
-precise field; it does not mean the participant finished.
+`study_spend_limit`, `adapter_limit`, `provider_incomplete`, `provider_status`,
+`provider_refused_prompt`, `harness_aborted`, and `usage_unreported`. Absence means the route or
+recording did not retain this precise field; it does not mean the participant
+finished.
+
+`provider_refused_prompt` records that the model provider refused the request
+under its usage policy (OpenAI `400 invalid_prompt`). The session ends as
+`failed` / `actor_error`, not `harness_error`, and the harness does not send the
+same prompt again. The provider's refusal message is not recorded, since it can
+echo the prompt.
 
 Observer projects this as optional `streams[].ending` with a `cause` and readable
 `label`. Older `budget_reached` traces without a recognized machine notice say
@@ -121,9 +146,9 @@ assignment:
 ```
 
 `mission` is the authored mission, or the runner's default when omitted. `focus` is the
-original lane/role instruction when one was supplied. `tasks` contains only the IDs and
+participant's original instruction when one was supplied. `tasks` contains only the IDs and
 goals actually composed into participant instructions; hidden success criteria are excluded.
-Computer-use single/fan-out, sequential/concurrent shared-world, and terminal-product
+Computer-use single/fan-out, shared-world, and terminal-product
 runners record assignments in dry-run and live bundles. Current shared-world and terminal
 prompts do not consume task protocols, so their assignments omit `tasks`.
 
@@ -178,7 +203,7 @@ different facts separate:
   `screen.requested` because the rendered width was floored to Chrome's ~500px window minimum.
   `verified` compares the floored number with itself and reports a match, so a matching
   `verified` block is NOT evidence that the preset width rendered. When `declared` is present,
-  it did not: a `mobile` (414) and a `small-mobile` (360) seat both render at 500 and are
+  it did not: a `mobile` (414) and a `small-mobile` (360) participant both render at 500 and are
   indistinguishable by rendered width;
 - `browserWindow`: measured browser bounds after the window-fill attempt; physical X client
   bounds (`source: xwininfo`) take precedence over page-reported outer bounds (`source: cdp`),
@@ -187,12 +212,12 @@ different facts separate:
 - `viewport`: the page's CSS layout viewport and device-pixel ratio measured through CDP on
   Chromium-family hosted browsers.
 
-Before participant actions, hosted computer-use lanes check measured X bounds against every
+Before participant actions, hosted computer-use participants check measured X bounds against every
 edge of the captured desktop. If a browser is clipped, a bounded move-and-fit correction
 remeasures the client origin after each of up to two resize attempts, preserving browser
 controls when they fit. A fullscreen fallback remains for minimum-width windows that cannot
 fit a narrow desktop. A window that remains clipped, or whose repair
-cannot be verified, ends the lane before participant actions. A fully contained smaller window
+cannot be verified, ends the participant before it acts. A fully contained smaller window
 can run. Missing X measurements are explicitly unverified; an emulated CSS viewport cannot
 establish physical containment. Final capture observes geometry without resizing the app.
 
@@ -207,12 +232,12 @@ exactly; this hosted-desktop rule does not change that contract.
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for
-what the computer-use backend actually drove (code pin plus state story). It
+what the computer-use, shared-world or scripted-browser backend actually drove (code pin plus state story). It
 is absent on pre-existing bundles and on bundles from backends that have not
 adopted it. The field shape, its three sources (`clone`, `app-url`,
 `local-tree`), and the `humanish verify` checks that guard it are the schema doc's
 job, not this one: see the `subject` entry under
-[`schemas.md`](schemas.md#contract-schema-index). In short, `clone` carries a
+[`schemas.md`](schemas.md#run-bundle). In short, `clone` carries a
 `repo`/`commit` pin, `local-tree` carries an `archiveSha256`/`dirty` pin
 instead (a dirty working tree cannot be commit-pinned), and `app-url` carries
 no code pin at all. No path, basename, or other host-machine string ever
@@ -221,21 +246,33 @@ enters this field; identity is digests, a sha, a boolean, and counts.
 ## Cost Estimate (advisory)
 
 `cost` is optional and additive (`humanish.run-cost-summary.v1`): the
-computer-use lane's run-level cost ESTIMATE — the sum of each lane's
+computer-use, shared-world, scripted-browser or terminal-product run's cost ESTIMATE: the sum of each participant's
 token-derived model cost plus E2B desktop compute lines. New independent CUA runs
-emit one line per owned desktop, keyed by public lane ID and carrying observed CPU/memory,
-resource source, host-measured minutes, and the derived per-second rate. Older
-single aggregate desktop lines remain valid. Missing resource metadata stays
+emit one line per owned desktop, keyed by public participant ID and carrying observed CPU/memory,
+resource source, host-measured minutes, and the derived per-second rate. Concurrent
+shared-world runs carry the same lines for each participant, plus a desktop line with
+`laneId: subject` for a provisioned plane; an external-public plane is not a humanish
+desktop and has no line. Older single aggregate desktop lines remain valid. Missing resource metadata stays
 unpriced; unconfirmed cleanup adds an unknown remaining-lifetime line. It is an
 ESTIMATE, never authoritative: every dollar is a rate-table multiply from the
-operator-editable `src/pricing.ts`, carries the pricing `ratesAsOf` date and
-`source`, and is surfaced with the "estimated (rates as of `<date>`)" label —
-never a bare charge. It follows the same **declared-absent** discipline as the
+operator-editable `src/run/pricing.ts`, carries the pricing `ratesAsOf` date and
+`source`, and is surfaced with the "estimated (rates as of `<date>`)" label. It is
+never shown as a bare charge. It follows the same **declared-absent** discipline as the
 terminal cost ledger: an unpriceable line stays present with
 `estimatedCostUsd: null` + a `reason` and contributes nothing;
 `estimatedTotalUsd` is `null` iff every line is null (never coerced to `0`).
-Dry-runs and lanes that spend nothing omit `cost` entirely, so pre-existing
-bundles stay byte-stable. Each lane's own estimate also rides its
+Dry runs omit `cost`. A live run that spends nothing records an explicit zero: no
+`breakdown` lines, `estimatedTotalUsd: 0`, `ratesAsOf: null` and `fullyEstimated: true`.
+A local scripted run (no model request, no hosted desktop) is such a run; a scripted run on
+a provisioned clone records the clone's desktop as a `laneId: subject` line. A live bundle
+without `cost` has an unmeasured spend. A live terminal run's `cost` prices the E2B terminal
+sandbox as a `desktop-minutes` line from its acquired-to-cleanup span and `e2b.getInfo` size.
+Its Codex `model-tokens` line stays `null` (`no_rate_for_model` with model `codex`, or
+`no_token_usage` when Codex reported none): the participant prices against its provider id `codex`
+even when `actors[0].model` is passed as `--model`, and `terminal-ledgers.json` counts those
+tokens without a price.
+So a terminal total is a lower bound (`fullyEstimated: false`), and the unpriced tokens are
+not $0. Each participant's own estimate also rides its
 `stream.actor.estimatedCost` (`humanish.actor-estimated-cost.v1`), kept distinct
 from the reserved provider-returned `tokenUsage.costUsd`. See
 [`schemas.md`](schemas.md) → Run Cost Summary And Estimated Actor Cost.
@@ -247,7 +284,7 @@ gaps across run costs and analysis attempts. See [study cost statistics](study-c
 `humanish verify` treats cost as ADVISORY on magnitude and FAIL-CLOSED on
 labeling: absence passes, but a claimed dollar figure without its `ratesAsOf`
 date + `source`, or a total that does not match its known lines, fails. Verify
-never inspects the magnitude — a correctly-labeled large estimate still passes.
+never inspects the magnitude, so a correctly-labeled large estimate still passes.
 
 ## Adapter Score
 
@@ -256,7 +293,8 @@ its own product-specific rubric without adding product nouns to core schemas.
 Core validates only `schema`, `namespace`, `status`, `score`, `summary`, and
 that optional `data` is a record.
 
-Terminal-product runs record `adapterScore` additively. Browser/computer-use
+Terminal-product runs record a library scorer's `adapterScore` additively; a
+config-declared scorer's `status: fail` flips the verdict as below. Browser/computer-use
 runs treat `status: fail` as product-red: the route result returns `ok: false`,
 the persisted `review.verdict` becomes `fail` when it was pass-like, and a
 generic adapter gap is appended. The bundle remains valid evidence for
@@ -266,7 +304,7 @@ not corrupt evidence.
 ## Adapter Artifacts
 
 `adapterArtifacts` is optional and namespaced. It lets a downstream adapter
-attach product/state proof outputs to the Humanish bundle without making the
+attach product/state proof outputs to the humanish bundle without making the
 payload shape a core concept. Core validates only:
 
 - `schema: humanish.adapter-artifact.v1`;
@@ -280,9 +318,9 @@ stores those references, Observer links them, and `humanish verify` fails closed
 when any referenced file is missing. The adapter owns the artifact payload schema
 under its namespace.
 
-## Lane Grouping Metadata
+## Participant Grouping Metadata
 
-Multi-lane browser/shared-world routes may carry optional lane grouping metadata:
+Multi-participant browser/shared-world routes may carry optional participant grouping metadata:
 
 ```yaml
 actors:
@@ -294,7 +332,7 @@ actors:
         caseGroup: case-001
 ```
 
-For repeated lanes, authors can use compact roster groups. The parser expands
+For repeated participants, authors can use compact roster groups. The parser expands
 each group into deterministic `lanes[]` before the engine runs:
 
 ```yaml
@@ -310,40 +348,40 @@ actors:
         device: desktop
 ```
 
-The generated lane ids are `<group.id>-01`, `<group.id>-02`, and so on. `roster`
+The generated participant ids are `<group.id>-01`, `<group.id>-02`, and so on. `roster`
 is mutually exclusive with explicit `lanes`, homogeneous `count`, and
 `laneFocus`; it is an authoring convenience, not a second runtime shape.
 
 These fields are adapter-owned labels, not core enums. They let downstream
 projects express "N actors of M app-defined types across S surfaces" without
-teaching Humanish private product nouns. Values must be public-safe tokens and
+teaching humanish private product nouns. Values must be public-safe tokens and
 are projected into:
 
-- the preflight lane plan;
+- the preflight participant plan;
 - shared-world `laneWindows[]` and `outcomes[]`;
 - Observer `laneGroups[]`;
 - human-readable Observer stream labels.
 
 `actorType` is deliberately separate from `actors[0].type`. The latter selects
-the Humanish execution actor, such as `openai-computer-use` or `scripted-browser`.
+the humanish execution actor, such as `openai-computer-use` or `scripted-browser`.
 The former is the app-defined simulated user bucket, such as `viewer`,
 `maintainer`, or a downstream adapter's own role label.
 
 ## Completion And Meaningful-Use Verdicts
 
-Each live stream may include `completion` when the harness has enough evidence
-to judge the lane. Completion state is deliberately compact and public-safe:
-it records actor/app/nested-Observer status, terminal tails that have already
-passed redaction, and optional setup-quality evidence.
+Only older bundles carry `completion`. The OSS meta-lab wrote it, and that lab
+was removed. No current route writes the field. `RunStream` in
+`src/run/streams.ts` still accepts it, so those bundles stay readable.
 
-`completion.meaningfulUse` is the first-class scored verdict for meta-lab
-lanes where a coding agent is asked to set up Humanish inside another project.
-It is a rubric over already-redacted evidence, not a raw transcript dump.
+In those bundles, `completion` is compact and public-safe. It records
+actor/app/nested-Observer status, terminal tails that have already passed
+redaction, and optional setup-quality evidence. `completion.meaningfulUse` scored
+a coding agent setting up humanish inside another project.
 
 ```yaml
 completion:
   status: "running|passed|failed|blocked|timed_out"
-  reason: "<public-safe lane summary>"
+  reason: "<public-safe participant summary>"
   actorStatus: "not_started|running|passed|failed|blocked|timed_out|suspended|unknown"
   appStatus: "not_started|running|blocked|failed|missing|unknown"
   nestedObserverPresent: true
@@ -364,11 +402,11 @@ completion:
         detail: "<public-safe detail>"
 ```
 
-The current OSS meta-lab rubric totals 100 points:
+The meta-lab's rubric totalled 100 points:
 
 - setup correctness: 15;
 - filesystem evidence: 10;
-- nested Humanish evidence: 20;
+- nested humanish evidence: 20;
 - actor activity: 15;
 - product surface: 15;
 - feedback quality: 25.
@@ -376,8 +414,8 @@ The current OSS meta-lab rubric totals 100 points:
 A score of 80 or higher is `pass` only when no hard failure is present and
 every rubric component passes. Scores from 45 through 79, or scores of 80 or
 higher with any non-passing component, are `partial`. Scores below 45,
-failed/timed-out bootstraps, missing nested Humanish proof, required actor
-failure, or completed lanes without a running visible product surface are
+failed/timed-out bootstraps, missing nested humanish proof, required actor
+failure, or completed participants without a running visible product surface are
 `fail`.
 
 ## Relative Artifact Layout
@@ -398,10 +436,12 @@ URLs are not part of the core layout.
 
 ## Filesystem Evidence
 
-Filesystem setup evidence is first-class when a lane asks an actor to install
-or configure Humanish inside another project. It is not a repo dump.
+Filesystem setup evidence came from the removed meta-lab, which asked an actor to
+install or configure humanish inside another project. Only bundles from that lab
+carry it; no current route writes it and `src/run/bundle.ts` no longer types it. It
+was not a repo dump.
 
-The durable artifact kind is `filesystem`. The current schema is:
+The durable artifact kind was `filesystem`. Its last schema was:
 
 ```yaml
 schema: humanish.setup-quality.v1
@@ -441,17 +481,17 @@ humanish:
   gitignoreContainsRuntimeIgnore: true
 ```
 
-For public OSS runs, previews may include allowlisted setup files such as
+For public OSS runs, previews could include allowlisted setup files such as
 `package.json`, `.gitignore`, `humanish/config.ts`, and
 `humanish/labs/*.yaml` / `humanish/personas/*.yaml` /
 `humanish/scenarios/*.yaml`. For token-backed or private maintainer runs, raw
-previews are suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
-browser profiles, `node_modules`, `.humanish/`, and arbitrary source files are
-not included. `studyQuality` is deliberately structural: it stores booleans,
-checks, and a rating so private runs can preserve the useful quality signal
+previews were suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
+browser profiles, `node_modules`, `.humanish/`, and arbitrary source files were
+not included. `studyQuality` was deliberately structural: it stored booleans,
+checks, and a rating so private runs could preserve the useful quality signal
 without committing raw private persona, scenario, or coverage text.
 
-## Latest And History
+## Latest Pointer
 
 The latest pointer is a small local index:
 
@@ -462,20 +502,6 @@ path: ".humanish/runs/<run-id>"
 updatedAt: "<ISO timestamp>"
 ```
 
-History entries use:
-
-```yaml
-schema: humanish.run-history-entry.v1
-runId: "<run-id>"
-createdAt: "<ISO timestamp>"
-lab: # optional, additive: which manifest produced this run
-  id: "<lab id>"
-  path: "humanish/labs/<lab id>.yaml"
-  origin: "committed|ignored|explicit"
-mode: "dry-run|live"
-path: ".humanish/runs/<run-id>"
-```
-
 The latest pointer may move. Run bundle directories should not.
 
 ## Verify Result Share Safety
@@ -490,7 +516,7 @@ shareSafety:
   status: "share_ready|local_only|blocked"
   reasons:
     - code: "RAW_SCREENSHOTS"
-      message: "Full-fidelity screenshots are present ..."
+      message: "Full-fidelity screenshots, or frames with no redaction claim, are present ..."
 ```
 
 `ok: true` means the bundle is valid evidence. It does not necessarily mean the
@@ -501,6 +527,23 @@ bundle is safe to promote into a public issue. Public promotion should branch on
 - `local_only`: keep the run local; only supported redaction-only cases can produce a shareable derivative;
 - `blocked`: fix the verification or public-safety failure first.
 
+`ok: true` also does not mean the run finished. A run killed mid-way leaves an
+in-progress bundle that can pass every check. When the run is not finished,
+`warnings[]` carries one entry starting with the stable code `RUN_NOT_FINISHED`.
+`ok` and `shareSafety` do not change. Verify decides "not finished" by the run
+index's rule, which the TUI and `humanish stats` use: the run's `status.json` when
+it is well formed and names the run, else a simulation still `running` in the
+bundle. A `running` record updated within the stale window reads as still
+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 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;
+- with journaled sandboxes and no reclaim receipt, the command that stops them:
+  `humanish reclaim --run <id>`.
+
 The local-evidence check includes screenshots declared only by
 `streams[].actor.items[].screenshotRef` or `streams[].liveActor.items[].screenshotRef`,
 as well as every feedback candidate's evidence. Actor frame paths are relative
@@ -510,12 +553,55 @@ may be an empty regular file, consistent with feedback verification, but that
 permission cannot relax another consumer's nonempty-file requirement. The
 qualified zero-event terminal-log exception remains unchanged.
 
-An explicit `screenshotRef.redaction: none` on either final or live actor items
-contributes the existing `RAW_SCREENSHOTS` reason and keeps otherwise valid
-evidence `local_only`. Either an aggregate raw declaration or a raw frame wins
-over a blurred declaration. Missing or unknown per-frame metadata retains the
-existing permissive compatibility behavior; verification does not infer pixel
-privacy from that absence.
+A frame counts as redacted only when its bytes have the redactor's output shape
+and a redaction claim covers it. The shape is IHDR, IDAT and IEND chunks only,
+an empty IEND that ends the file, and a width of at most 128 pixels. The claim is
+`screenshotRef.redaction: blurred`, or no `redaction` while the stream's final
+`actor.redaction.screenshots` is `blurred` (bundles from before per-frame
+claims). Every other frame is raw: it contributes `RAW_SCREENSHOTS` and keeps
+otherwise valid evidence `local_only`. That includes `none`, any other value,
+an unclaimed frame on a raw, silent or live-only trace, and `ocr_scrubbed`, which
+the trace contract reserves but no writer produces. An aggregate raw declaration
+wins over every frame claim.
+
+A screenshot is a non-interlaced PNG whose first chunk is a 13-byte IHDR, whose
+IEND is empty, and which holds image data only. A chunk outside IHDR, PLTE, IDAT,
+IEND, tRNS, cHRM, gAMA, sBIT, sRGB, pHYs and bKGD (text chunks, ICC profiles,
+Exif, timestamps, private chunks) fails verification. The harness writers drop
+those chunks before writing a frame.
+
+The public-safety scan classifies a run file by its bytes, not its name. It scans
+a file for secret and path patterns only when the bytes are strict UTF-8 with no
+control bytes other than tab, line feed and carriage return, the rule bundle
+export uses for text. `RAW_SCREENSHOTS` and `CONTINUOUS_MEDIA` grade the stream
+screenshots that actor traces reference under `screenshots/`, where the harness
+writes every frame, and the recordings `streams[].recording` registers. Every other file the scan cannot read as text, or cannot read at all,
+contributes `UNSCANNED_ARTIFACT`. The reason's message lists the paths, and it keeps
+otherwise valid evidence `local_only`. This includes images that only feedback
+candidates, adapter artifacts or stream artifact entries cite, and a PNG an actor
+trace references outside `screenshots/`. An unregistered
+`.mp4`, and a file or directory whose name contains `\`, are public-safety
+findings and block the run.
+
+Before matching, the scan undoes JSON and JS escapes, percent-encoding and HTML
+character references, the decoding bundle export applies (`decodeEscapes`), and
+then JSON whitespace escapes and quoted-printable. It reads inside base64 runs of
+16 characters or more in the standard or URL-safe alphabet, including base64
+wrapped across lines, and inside hex runs of 32 characters or more:
+
+- a run that decodes to UTF-8 text, or to mostly-ASCII UTF-16 in either byte
+  order, is scanned in turn, up to three levels of base64 deep;
+- the printable stretches of a run that decodes to other binary are scanned too;
+- a base64 run that decodes to an archive (gzip, zip, 7z, bzip2, xz, zstd), at
+  any length, or to other binary of 128 characters or more with at least 16
+  distinct characters, contributes `UNSCANNED_ARTIFACT`.
+
+`observer/index.html` is exempt from that base64 rule: serve renders it from
+`run.json`, export regenerates it, and it embeds the Observer's own base64 fonts.
+Its text is still scanned. Known limits: base64 split across separate strings,
+nesting deeper than three levels, and encodings a pattern scan cannot undo (such
+as encryption) still grade `share_ready`. `tests/verify/encoding-coverage.test.ts`
+records each case.
 
 Real email receiving adds `publication.restrictions: [real-communications]` and
 an optional `commsReceiving` projection using `humanish.comms-receiving.v2`.
@@ -547,7 +633,11 @@ The receipt describes the transformation; it does not attest that a participant'
 finding is true. Its own bytes are not included in its hash inventory. Feedback
 commands can subsequently generate new derivative-local artifacts.
 
-PNG files are re-encoded as blurred thumbnails, including unreferenced images.
+PNG files that actor traces reference as stream screenshots are re-encoded as
+blurred thumbnails. A PNG that nothing in `run.json` cites is omitted and
+inventoried. Export refuses a run whose feedback candidates, adapter artifacts or
+stream artifact entries cite a PNG that is not a stream screenshot, since verify
+cannot read that image and dropping it would change the evidence.
 Known actor screenshot declarations describe export-time blur while retaining the
 original redaction notes. Observer is rebuilt; old feedback outputs, local process
 status and the operational sandbox journal are omitted and inventoried. A derivative
@@ -556,16 +646,12 @@ inline image payloads, invalid evidence and references to omitted files are refu
 The original and derivative are independently verified. Text still requires human
 review before sharing; screenshot blur does not certify natural-language privacy.
 
-## Contract Fixture Proof
-
-The core fixture proves:
+## Git Provenance
 
-- deterministic run ids from explicit inputs;
-- stable relative artifact paths;
-- latest/history/lifecycle/timing records;
-- git status counts without branch names, remotes, file names, file paths, or
-  absolute directories;
-- no environment-specific nouns in `src/core`.
+`captureGitState` (`src/run/git-state.ts`) records git status as counts, without
+branch names, remotes, file names, file paths or absolute directories. It
+refuses a forged gitdir file and unsafe linked-worktree metadata before running
+git. `tests/run/git-state.test.ts` covers these cases.
 
 Proof commands: