tracegrove 0.0.0-stage → 0.3.0

package/docs/browser-driver.md

@@ -0,0 +1,148 @@
+# Local browser driver
+
+`BrowserDriver` runs real Chromium in a fresh, nonpersistent context. It does
+not connect to an existing browser profile. Install its pinned browser before
+running browser tests or using the driver:
+
+```sh
+npm ci
+PLAYWRIGHT_SKIP_BROWSER_GC=1 npx --no-install playwright install chromium
+npm test -- tests/browser-driver.test.ts
+```
+
+Linux CI uses `playwright install --with-deps chromium` to install the browser
+and its system libraries.
+
+Run the packaged browser sample through the same low-level CLI as an API case:
+
+```sh
+npm run build
+node dist/cli/main.js sample-config --sample notes-browser --output /tmp/notes-browser
+node dist/cli/main.js plan --config /tmp/notes-browser/verification/workflow.yaml --output /tmp/notes-browser-request.json
+node dist/cli/main.js run --request /tmp/notes-browser-request.json
+```
+
+Use fresh output paths: sample generation refuses to overwrite a project. The
+run prints its execution ID and bundle path. Pass that path to
+`node dist/cli/main.js verify-bundle --bundle <path>` for independent verification.
+The sample shares its real app, personas, fixture recipes, and cleanup with
+`notes-api`; only its browser runner, binding, and case differ.
+
+The exported `BrowserCommand`, `BrowserLocator`, and `BrowserObservation` Zod
+schemas also have generated JSON Schemas. Commands navigate, click, fill, or
+read visible text. Locators use exact roles, labels, or test IDs. Arbitrary
+scripts and selectors are not accepted. Observations contain browser facts;
+the driver does not decide whether a scenario passes.
+
+Each operation has a deadline. Cancellation or a failed mutating operation closes the
+context and browser before returning. Calls on one driver are serialized by
+rejecting concurrent operations. Closing is idempotent. A closure acknowledgement
+does not prove cleanup of an operating-system process tree after controller death.
+
+Page requests must stay on the admitted origin. Chromium's CDP Fetch interception
+checks every redirect hop while retaining native response streaming. Service
+workers and WebSockets are disabled, and extra pages are closed. This is page
+request filtering, not an operating system network sandbox; arbitrary application
+code, workers, and popups require a host network boundary for full confinement.
+
+`collectVideo()` closes the browser, flushes the WebM recording, and reads at
+most 32 MiB from a regular file without following a final symlink. `dispose()`
+removes the private temporary recording directory. Recordings and DOM text are
+raw and may contain application data; callers must apply their evidence access
+and retention policy before storing or sharing them. This driver does not issue
+credentials or copy an owner's authenticated session.
+
+The real-browser tests submit a local form, check an independent server receipt,
+read the resulting DOM, and inspect the flushed recording. Separate tests cover
+cross-origin paths, page requests and redirects, cancellation, timeout, invalid
+commands, and expired startup.
+
+The core runner profile accepts `adapter: browser`. A typed `ui.navigate` step
+has a path; `ui.action` carries a click or fill command; `ui.observe` carries a
+semantic target, predicate, and poll interval. DOM predicates address
+`browser.text` or `browser.url` through the `browser.observation/1` oracle.
+HTTP steps and fixtures can run in the same case for independent readback.
+
+Each poll counts against `maxBrowserActions`. Case method and resource-prefix
+rules filter page requests; read-only cases allow only GET and HEAD. Persona
+viewport, locale, timezone, and reduced motion are passed to the browser. Pointer
+activation uses clicks, keyboard activation uses focus with Enter or Space for toggles, and touch
+activation uses taps. Host-issued bearer credentials are added only to admitted
+page requests, never expanded into filled values or recorded commands.
+Network events record methods, paths, and response statuses without request
+headers or query strings. Recording more than 512 network events invalidates
+collection. Required traces and declared redaction policies remain blocked.
+
+Before closing a successful session, collection completes a layout-aware
+screenshot, then requests another capture and waits for a frame presented after
+the first capture through Playwright’s public screencast callback. Only then
+does it stop and flush the encoder. A fresh frame delivered during the first
+capture can still contain older pixels. This uses the cleanup deadline, not an
+arbitrary recording delay. Collection failures name their capture, frame, or
+flush phase without exposing page text or Playwright diagnostics.
+The controller seals the recording bytes into the portable bundle and records
+browser duration and artifact bytes. Verification reproduces the frozen runner
+capabilities, independently reduces browser assertions, and checks video hashes
+and byte counts. A required recording cannot be satisfied by an event log alone.
+
+The integrated native tests cover pointer, keyboard, and 375px simulated touch,
+combining an authenticated UI, DOM observation,
+independent API assertions, fixture cleanup, video capture, and portable bundle
+verification. A decoded-frame test checks the recorded terminal visual state.
+This proves local behavior. Hosted admission, staging personas, and
+controller-death browser cleanup remain open; no production qualification is claimed.
+
+## Short flows and Grove
+
+The packaged sample also includes a short browser flow. From the repository root:
+
+```sh
+node dist/cli/main.js test --config /tmp/notes-browser/tracegrove.config.yaml --grep notes.browser
+node dist/cli/main.js ui --dir /tmp/notes-browser
+```
+
+Open the printed loopback address and select the browser scenario. Its step
+panel shows expected and observed text plus native recording controls. The
+player supports keyboard playback and byte-range seeking, and preserves its
+position when changing steps. Each media request verifies one immutable bundle
+snapshot and binds the digest to that run and scenario. Corrupt, unbound, or
+symlinked recordings are refused.
+
+Browser commands reuse the core command and locator schemas:
+
+```yaml
+title: Show the seeded note
+given: { existing: existing-note }
+browser:
+  allowPaths: [/ui, /notes]
+  allowMethods: [GET, HEAD]
+steps:
+  - browser: { kind: navigate, path: /ui }
+    expect: { status: 200 }
+  - browser: { kind: click, target: { by: role, role: button, name: Refresh } }
+  - browser: { kind: read, target: { by: testId, name: notes } }
+    expect: { text: Existing note }
+```
+
+`fill` accepts a semantic `target` and string `value`. Browser reads require
+`expect.text` and poll until it holds. Click/fill steps assert completion; add a
+DOM read or independent API readback to establish the effect. Browser steps use
+the default persona, and browser flows require a recording. Set `maxActions`
+and `maxArtifactBytes` inside the flow's `browser` block to tune their budgets.
+Its allowed paths and methods combine with those derived from HTTP steps and
+fixtures into the flow's effect envelope.
+
+Persona configuration accepts optional `viewport`, `inputMode`, `locale`,
+`timezone`, and `reducedMotion` fields alongside `subject`. Simulated touch
+does not qualify a physical mobile device. Required traces, executable
+redaction policies, and non-browser native surfaces remain unsupported.
+
+Read-only observation timeouts preserve the browser for final evidence collection.
+Browser polling retains its last completed observation at the deadline so an
+unmet expectation keeps its observed value and remains an assertion failure.
+Cancellation and actual browser errors still propagate; failed mutating actions
+close the browser to revoke late effects.
+
+Capture failures remain infrastructure failures with no accepted video. The sealed `browser.failed` event includes a bounded driver `cause` and `phase` (`capture`, `frame`, or `flush`) when available; unknown exceptions expose neither their message nor arbitrary fields.
+
+Recordings use the persona viewport at native size, rounded up to even dimensions for VP9 (at most one padding pixel per edge), instead of scaling mobile content into a desktop canvas. Fresh-frame and encoder-flush checks remain required.

package/docs/cleanup-followups.md

@@ -0,0 +1,74 @@
+# Signed cleanup follow-ups
+
+An executing worker's cleanup report cannot release a hosted persona. A separate
+collector may sign a follow-up after observing the execution-owned resources.
+The follow-up is a new immutable record; it does not rewrite the attempt receipt.
+
+The ownership ledger supplies a `CleanupExpectation` containing the exact scope,
+attempt, worker, fencing generation, coordination version, admitted effects,
+unresolved effects and owned resource identities. HTTP absence and host stop are
+distinct obligations. The collector signs the canonical follow-up with an
+Ed25519 key kept outside the executing worker. Its scope-bound observer grant
+comes from protected control-plane configuration, not from the submitted proof.
+
+`verifyCleanupFollowup` validates the signature against that configuration and
+the complete expected manifest. It rejects unknown/revoked keys, executing-worker
+signers, altered bindings, changed resource/effect closure, unresolved effects,
+missing or wrong-kind observations, duplicate identities and stale/future evidence.
+The evidence window is at most five minutes. Status-only HTTP absence requires a
+GET/HEAD observation returning 404 or 410; a 200 response cannot qualify.
+
+The signature includes the algorithm, key ID and follow-up under the
+`tracegrove.signed-cleanup-followup/v1` domain separator. The signature field is
+excluded from signed bytes; the returned proof digest covers the complete envelope.
+The expectation digest includes every expectation field. Base64url signatures
+must use canonical unpadded encoding. Key IDs select configured public keys;
+the verifier never trusts a public key carried by the proof itself.
+
+`deriveCleanupExpectation` combines the current coordination snapshot with the
+protected ownership record. Missing host inventory prevents derivation. Admitted
+effects without independent resolution remain unresolved; extra effects and
+duplicate resources are refused. Takeover derives the current worker and fence
+while retaining prior resource identities. `ownershipLedgerHeadDigest` anchors
+the expectation to the exact canonical ledger event, including issuer receipts.
+The helper cannot establish that caller-supplied files came from that ledger.
+
+## Offline inspection
+
+```sh
+workflow-verify verify-cleanup --proof followup.json \
+  --expectation expected.json --trust observers.json --json
+```
+
+The trust file uses this shape, containing public keys only:
+
+```json
+{
+  "schemaVersion": "workflow.cleanup-observers/v1",
+  "observers": [{
+    "keyId": "configured-collector-key",
+    "scopeId": "workspace-scope",
+    "observerId": "independent-collector",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
+  }]
+}
+```
+
+Exit 0 means the supplied files pass signature and expectation checks. Exit 2
+means validation failed. JSON output always reports `hostedReleaseAdmitted: false`.
+Inputs are limited to 4 MiB per file. A local trust file is useful for inspection
+and cannot configure a hosted authority or provision a signing key.
+
+## Remaining hosted requirements
+
+The control plane must independently establish ownership and provider receipts,
+qualify the collector and provision/revoke its protected signing authority.
+The storage owner must load the current expectation and lease, recheck time and
+fencing under its admission lock, then append cleanup admission and persona
+release atomically. This verifier does not implement that storage transaction,
+prove provider absence from a digest alone, or authorize compensation actions.
+Worker release through the ordinary coordination port remains refused.
+
+Local tests use ephemeral keys. One native HTTP case rejects observed presence,
+deletes an owned test resource and verifies a separately observed absence; it is
+local conformance evidence, not a qualified staging or provider receipt.

package/docs/developer-ux.md

@@ -0,0 +1,315 @@
+# Tracegrove developer UX redesign
+
+Status: phase 1 is implemented in the draft PR (see Phasing). Node, FastAPI and Django samples pass end to end through it.
+
+## The problem today
+
+Writing one HTTP test for the notes sample takes **19 YAML files across 13 folders** (`workflow.yaml`, suite, case, persona, auth recipe, component profile with a hand-pinned sha256, environment plan, host plan, runner, surface pack, surface binding, fidelity profile, intelligence policy, action registry, seed recipe, fixture plan, a materialized payload with a pinned digest, …). Every file carries `schemaVersion`, `ref.id` and `ref.revision`. Running it is four commands (`doctor`, `plan --output request.json`, `run --request`, `verify-bundle`) and the results land in `.workflow-verify/executions/<uuid>/`, a folder name nobody can find again.
+
+The kernel underneath (frozen corpus, digests, independent readback, owned cleanup, sealed bundles) is the valuable part, and it stays exactly as it is. What is missing is a front door.
+
+## Design principles
+
+1. **One config, one file per test.** Everything else is derived, with an escape hatch to the strict v1 corpus when you need it.
+2. **Convention over configuration.** Paths, ids, names and defaults come from where files live. Nothing has an id you have to invent.
+3. **Compile, don't replace.** The new files compile into the existing `workflow.*/v1` documents, so every guarantee (digests, attestation, cleanup proof, `verify-bundle`) still holds and the evidence is identical in kind.
+4. **One command to run.** `tracegrove test` plans, runs, reports and verifies. The frozen request is still written, just not by you.
+5. **Framework presets, not framework plugins.** FastAPI, Django and Node are a few lines of launch defaults, not a dependency on the user's stack.
+6. **Results you can find.** Human-named run folders, a `latest` pointer, Markdown + JSON + JUnit next to the sealed bundle.
+
+## What a user's repo looks like
+
+```text
+my-app/
+  tracegrove.config.yaml          # the only config file
+  tracegrove/                     # tests live here (configurable: testDir)
+    notes/
+      create-read-delete.flow.yaml
+      authz.flow.yaml
+    fixtures/
+      existing-note.fixture.yaml
+  .tracegrove/                    # generated, gitignored
+    runs/
+      2026-10-16T14-22-03Z_pass_3f9a1c/
+        summary.md  summary.json  junit.xml  bundle/
+      latest -> 2026-10-16T14-22-03Z_pass_3f9a1c
+    compiled/                     # the derived v1 corpus, for inspection or ejection
+    state/                        # ledger
+```
+
+## Naming conventions
+
+| Thing | Convention | Derived id |
+| --- | --- | --- |
+| Test file | `tracegrove/<area>/<behavior>.flow.yaml`, kebab-case | case id `<area>.<behavior>` |
+| Fixture file | `tracegrove/fixtures/<name>.fixture.yaml` | entity key `<name>` |
+| Step | `name:` in plain words, optional | `snake_case(name)`, else `<method>_<n>` |
+| Assertion | from a step's `expect:` | `<step>.expect` |
+| Persona | key under `personas:` | credential `<persona>_token` |
+| Saved value | `save: { noteId: note.id }` | referenced as `{noteId}` anywhere later |
+| Fixture output | `{existing.noteId}` | input from fixture `existing`, output `noteId` |
+| Tags | `tags: [smoke, authz]` | coverage tags; filter with `--tag` |
+| Run folder | `<UTC timestamp>_<outcome>_<short execution id>` | sortable, greppable |
+
+## The config file
+
+```yaml
+# tracegrove.config.yaml
+project: notes
+app:
+  adapter: node                 # node | fastapi | django | command
+  entry: app/app.mjs            # node: script; fastapi: module:app; django: manage.py dir
+  health: /health
+  sources: [app/**]             # files whose digest is attested as "what was tested"
+  env:
+    NOTES_BUILD: sample
+  inject:                       # where tracegrove hands the app its port, data dir and tokens
+    port: PORT
+    dataDir: NOTES_DIR
+    tokens: NOTES_TOKENS
+personas:
+  owner: { subject: alice }     # first persona is the default caller
+  intruder: { subject: bob }
+```
+
+Defaults when omitted: `testDir: tracegrove`, `inject` = `PORT`, `TRACEGROVE_DATA_DIR`, `TRACEGROVE_TOKENS`, `health: /health`, deadline 60 s, sources = all tracked-looking files under the app dir excluding `node_modules`, `.venv`, `__pycache__`, `.git`, `.tracegrove`.
+
+## Adapter presets
+
+| `adapter` | Launch it compiles to | Notes |
+| --- | --- | --- |
+| `node` | `node <entry>` with `PORT` set | Any Express/Fastify/Hono/Nest app that reads `PORT`. |
+| `fastapi` | `<python> -m uvicorn <entry> --host 127.0.0.1 --port {port}` | `python:` defaults to `.venv/bin/python` if present, else `python3`. |
+| `django` | `<python> manage.py migrate --noinput && <python> manage.py runserver 127.0.0.1:{port} --noreload` | Point `DATABASES` at `TRACEGROVE_DATA_DIR` for a fresh database per run (the sample does). |
+| `command` | Reserved for a qualified application-runtime adapter | Currently BLOCKED: a shell wrapper cannot attest the application interpreter. |
+
+`{port}` and `{dataDir}` are substituted in `args` and `env` values. Tracegrove picks a free loopback port itself (the "assigned" port mode), so apps no longer need to print `listening <port>`.
+
+**Auth hook.** Tracegrove issues a random bearer token per persona per run and passes `{token: subject}` as JSON in the `tokens` env var. The app adds about five lines in test mode to accept them:
+
+```python
+# FastAPI
+tokens = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
+def current_user(authorization: str = Header("")):
+    sub = tokens.get(authorization.removeprefix("Bearer "))
+    if not sub: raise HTTPException(401)
+    return sub
+```
+
+```python
+# Django middleware
+TOKENS = json.loads(os.environ.get("TRACEGROVE_TOKENS", "{}"))
+def tracegrove_auth(get_response):
+    def mw(request):
+        sub = TOKENS.get(request.headers.get("Authorization", "").removeprefix("Bearer "))
+        if sub: request.user = User.objects.get_or_create(username=sub)[0]
+        return get_response(request)
+    return mw
+```
+
+```js
+// Express
+const tokens = JSON.parse(process.env.TRACEGROVE_TOKENS ?? '{}');
+app.use((req, _res, next) => { req.user = tokens[(req.headers.authorization ?? '').slice(7)]; next(); });
+```
+
+`tracegrove init` prints the right snippet for the detected framework.
+
+## A test
+
+```yaml
+# tracegrove/notes/create-read-delete.flow.yaml
+title: Create a note, read it back, keep other notes intact, delete it
+risk: critical                  # critical | standard (default) | exploratory
+tags: [notes]
+given:
+  existing: existing-note       # tracegrove/fixtures/existing-note.fixture.yaml
+steps:
+  - name: create
+    POST: /notes
+    json: { title: Fresh note, body: Written through the real API. }
+    expect: { status: 201 }
+    save: { noteId: note.id }
+
+  - name: read back
+    GET: /notes/{noteId}
+    observe: true               # independent readback, polled until it holds
+    expect: { status: 200, json: { note.title: Fresh note } }
+
+  - name: intruder is denied
+    GET: /notes/{noteId}
+    as: intruder
+    expect: { status: 403, absent: [note] }
+
+  - name: delete
+    DELETE: /notes/{noteId}
+    expect: { status: 204 }
+
+  - name: gone
+    GET: /notes/{noteId}
+    observe: true
+    expect: { status: 404 }
+
+  - name: existing note untouched
+    GET: /notes/{existing.noteId}
+    observe: true
+    expect: { status: 200, json: { note.title: Existing note } }
+```
+
+Rules: one HTTP verb key per step; use block style (or quotes) for values containing `{` or `[`, because YAML reads them as inline maps and lists; `json:` is the request body; `expect.json` keys are dot paths into the response body; `absent` lists paths that must not exist; the effect envelope (allowed methods, path prefixes, max creates) is derived from the steps and fixtures, so the safety rails stay on without being written by hand.
+
+## A fixture
+
+```yaml
+# tracegrove/fixtures/existing-note.fixture.yaml
+create:
+  POST: /notes
+  json: { title: Existing note, body: { words: 6 } }
+  expect: 201
+save: { noteId: note.id }
+readback:
+  GET: /notes/{noteId}
+  expect: { status: 200, json: { note.title: Existing note } }
+cleanup:
+  DELETE: /notes/{noteId}
+  expect: 204
+  gone: { GET: "/notes/{noteId}", status: 404 }
+```
+
+`{ words: 6 }` uses the deterministic generator; the logical payload is materialized at compile time, so there is no digest to paste.
+
+## TypeScript authoring
+
+Use `tracegrove.config.ts` instead of the YAML config for editor completion and
+shared constants. Flows and fixtures can independently use `.flow.ts` and
+`.fixture.ts`; YAML and TypeScript files can coexist when their logical names
+differ. They all compile through the same Zod schemas into the same corpus.
+
+```ts
+// tracegrove.config.ts
+import { defineConfig } from 'workflow-verify/authoring';
+
+export default defineConfig({
+  project: 'notes',
+  app: { adapter: 'node', entry: 'app/app.mjs' },
+  personas: { owner: { subject: 'alice' } },
+});
+```
+
+```ts
+// tracegrove/notes/health.flow.ts
+import { flow } from 'workflow-verify/authoring';
+
+export default flow({
+  title: 'The application is ready',
+  steps: [{ GET: '/health', expect: 200 }],
+});
+```
+
+`fixture({...})` supplies the same editor types for fixture recipes. The helpers
+preserve input values; the ordinary compiler validates and fills defaults. Run
+your TypeScript checker for editor contracts and `tracegrove check` for canonical
+runtime validation. `test`, `list`, `compile`, discovery and Grove use either
+config format. `init` preserves an existing TypeScript config.
+
+TypeScript authoring executes trusted project code, including during `check` and
+discovery; it is outside the application sandbox. Each module loads in a fresh
+Node process so edits to imported helpers are seen on the next compilation.
+Evaluation is limited to five seconds and a 1 MiB JSON-compatible default export.
+Console output does not contaminate CLI JSON. Errors report the failing module
+without forwarding arbitrary module diagnostics.
+
+Use Node 22's erasable TypeScript: include extensions on relative imports and use
+`import type` for types. Enums, parameter properties, JSX, and tsconfig path aliases
+are not transformed. The package's Node version requirement still applies. Keep
+one project config; discovery rejects competing YAML and TypeScript configs.
+An explicit `--config` on `test`, `list`, or `compile` selects a format when both
+are intentionally present.
+
+## Command reference
+
+```text
+tracegrove init                     detect FastAPI / Django / Node, write config + an example flow + .gitignore entry
+tracegrove test [--grep notes] [--tag smoke] [--json]
+                                    compile, plan, run, write the run folder, verify the bundle
+tracegrove list                     list flows with their derived ids, tags and steps
+tracegrove show [--run latest]      print a run's summary
+tracegrove compile                  write the derived v1 corpus to .tracegrove/compiled (to inspect or eject)
+```
+
+Exit codes are unchanged (0 pass, 1 assertion failure, 2 blocked, 3 infrastructure, 4 cancelled). `workflow-verify` and all of its low-level commands keep working; the compiled folder is a normal `workflow.yaml` project, so `workflow-verify plan --config .tracegrove/compiled/workflow.yaml` still works.
+
+## Output a human reads first
+
+```text
+tracegrove · notes · app sha 3e8d13bc9bd1
+
+  PASS    notes.create-read-delete   6 steps  28 ms
+  FAIL    notes.authz                3 steps  14 ms
+          step "intruder is denied": expected status 403, got 200
+          GET /notes/9c1e… -> 200 {"note":{"id":"9c1e…","title":"Fresh note"}}
+  ERROR   notes.crud                 5 steps   0 ms
+          (app startup): application exited before becoming ready; last app output:
+          | ERROR:    Error loading ASGI app. Could not import module "app.mian".
+
+1 passed, 1 failed · run .tracegrove/runs/2026-10-16T14-22-03Z_fail_3f9a1c
+```
+
+`summary.md` carries the same table plus per-step request/response excerpts; `junit.xml` lets GitHub Actions, GitLab and Buildkite annotate failures with no plugin.
+
+## Forking it into your own repo
+
+1. `npm i -D tracegrove` once it is published (today: install the packed archive, as the `tracegrove-notes-api` repo does).
+2. `npx tracegrove init` writes `tracegrove.config.yaml`, `tracegrove/example.flow.yaml` and adds `.tracegrove/` to `.gitignore`.
+3. Paste the printed auth snippet into the app's test-mode auth.
+4. `npx tracegrove test`.
+5. CI: one step, `npx tracegrove test`, then upload `.tracegrove/runs/latest` as an artifact.
+
+## Phasing
+
+| Phase | Scope | In the draft PR |
+| --- | --- | --- |
+| 1 | Config + flow + fixture compiler, node/fastapi/django presets, assigned port mode, app-output-on-startup-failure, `test`/`list`/`compile`/`show`/`init`, run folders with summary.md/json/junit, Node/FastAPI/Django samples | Yes; generic command host remains unqualified |
+| 2 | `lanes:` with an offline mock lane compiled from recorded responses; `--update-snapshots` to record them | No |
+| 3 | `tracegrove.config.ts` with `defineConfig`, `flow()` and `fixture()` for editor completion; canonical JSON Schema for YAML | Implemented through the shared compiler; no alternative executor |
+| 4 | Login-recipe personas (POST /login, cookie or token capture) for apps whose auth can't be patched; external `url:` targets with declared, unverified identity | No |
+| 5 | Browser surface using shared typed `browser:` commands, independent DOM/API checks, and verified Grove recording playback | Implemented locally; staging qualification remains open |
+
+## Structured command failures
+
+An uncaught command failure with `--json`, `--json true` or `--json=true` writes one
+`tracegrove.cli-error/v1` result to stdout and no exception diagnostic to stderr. The strict
+schema is exported as `schema/tracegrove_cli-error_v1.json` and `CliErrorReport` from the
+protocol package. For example, `tracegrove run --json` returns exit 2 and:
+
+```json
+{"schemaVersion":"tracegrove.cli-error/v1","command":"run","errorClass":"blocked","exitCode":2,"reasons":[{"code":"missing_argument","message":"A required option or option value is missing.","recovery":"Run tracegrove help and correct the command options."}],"omittedReasonCount":0}
+```
+
+Messages and recovery actions come from a controlled public vocabulary. Raw exception text,
+stacks, supplied argument values, configuration contents and arbitrary internal reason codes
+are omitted. At most 32 reasons are returned; `omittedReasonCount` reports any remainder.
+Unknown prerequisites use `prerequisite_unavailable`. Unknown command names become `command: null`.
+This trades detailed candidate diagnostics for a bounded machine result; keep private evidence
+under its existing access policy when investigating a failure.
+
+Existing process exit statuses are preserved: blocked/conflict/schema failures use 2;
+infrastructure and unexpected failures use 3. A top-level JSON parse failure retains its legacy
+exit 3 with `errorClass: invalid_input` and `invalid_json`. The report's exit code equals the
+process status. It does not assert that execution never started or authorize a retry: a failure
+can follow partial effects, and uncertain ownership must be reconciled before replay.
+
+Doctor retains `tracegrove.doctor/v1`. Completed test/run results and assertion failures retain
+their existing JSON and exit codes 0/1/2/3/4. Returned check/verification results keep their existing
+schemas. `--json false` and `--json=false` keep prose errors, and `--jsonl` keeps its existing event
+stream and top-level error behavior. Successful reports, doctor reports and artifacts are outside
+this error envelope's omission policy; this change establishes no artifact redaction guarantee.
+
+## Found along the way
+
+- The bundle verifier re-derived "infrastructure failed" only from step reason codes, so any run whose app never started produced a bundle that failed its own verification. The PR fixes this by also reading the sealed `host.failed` event; that evidence can only move a cell away from passed.
+
+## Open questions for Hope
+
+- Package and binary name: `tracegrove` for both (recommended), keeping `workflow-verify` as an alias.
+- Default test folder: `tracegrove/` (recommended) versus `tests/tracegrove/` to sit beside pytest/jest.