@unotest/web 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,502 @@
 # Changelog
 
+## [0.33.0] - 2026-09-06
+
+### Minor Changes
+
+- 2abfd4d: Box: every run is announced — Slack, Telegram, or a webhook of your own — and the channels are managed from the guard.
+
+  A box now tells people how its runs went, whoever started them: the
+  schedule's ticks, a pull request's check, somebody pressing Run in the
+  viewer, a terminal inside the container. The daemon reads each run's own
+  journal, so the three producers are one source; the run's manifest says
+  what set it off — `trigger: { kind: "schedule" | "ci" | "manual" | "cli",
+by? }`, written by the runner from `UNOTEST_RUN_TRIGGER` /
+  `UNOTEST_RUN_ACTOR` (a box sets them for its scheduled and CI runs, the
+  viewer for a run ordered from its UI; a terminal sets nothing and reads as
+  `cli`).
+
+  A scheduled series is announced on a **change of state**: `failed` after
+  `afterFailures` red ticks in a row, `recovered`, `still-failing` at a rule's
+  `repeatEvery`, `not-run` when the suite could not run at all (no bundle, a
+  bundle that does not install) — daily by default. A run somebody ordered is
+  announced on its own, `failed` or `passed`, every time. A withdrawn or
+  aborted run says nothing; a run whose journal stops and whose heartbeat goes
+  cold is `interrupted`.
+
+  Channels, rules, mutes and quiet hours live on the box and are managed from
+  the guard's `/_guard/notifications` page (or `boxd notify …`): a channel's
+  secret is set once and never shown again, a rule picks environments,
+  triggers, events and channels, a series or the whole project can be muted
+  until a time, and quiet hours hold reminders and `passed` back until the
+  morning. A generic webhook receives the event as JSON (`version: 1`, the
+  box named, the `trigger`) with `X-Unotest-Event` and, when the channel has
+  a secret, `X-Unotest-Signature: sha256=<hex>` — HMAC-SHA256 over the raw
+  body, the scheme GitHub uses — plus any headers the channel declares.
+
+  `@unotest/protocol`: `RunManifest.trigger` and the trigger helpers
+  (`runTriggerFromEnv`, `runTriggerEnv`, `manifestTrigger`); the session-door
+  paths, views and parsers of the notifications API (`boxNotifyProjectPath`,
+  `boxNotifyChannelPath`, `boxNotifyRulePath`, `boxNotifySeriesPath`,
+  `boxNotifyMutePath`, `boxNotifyQuietHoursPath`, `boxNotifyPreviewPath`,
+  `BoxNotifyProjectView`, …). The first draft of this feature (channels
+  declared in the box config, secrets by field) never shipped; this replaces
+  it whole.
+
+### Patch Changes
+
+- 5d1bde3: `lint` and `e2e` no longer fail on a project tree they cannot write to.
+
+  Editor typings (`unotest/jsconfig.json`, `.unotest/types/env.d.ts`) are a
+  convenience for a human with an IDE open, and they were being written on
+  every implicit `lint` / `e2e`. On a box that runs a suite in an isolated
+  container the bundle is mounted read-only, so that write raised `EROFS` /
+  `ENOENT` and every scenario ended as `interrupted` — a suite failing
+  because a cache could not be refreshed.
+
+  The write is now skipped when the tree refuses it (matched on the errno
+  `code`, never on a message), both artifacts report `skipped`, the result
+  carries the reason, and the run carries on; any other failure still
+  throws. `UNOTEST_EDITOR_TYPES=0` turns the whole thing off up front — a
+  box sets it on every run it starts, because there is no editor in a
+  container and the attempt is only noise in the log.
+
+- b3e1220: Judge: the bearer token on `/judge` is compared in constant time, and the
+  docs say what a verdict sends and what it is not.
+
+  `UNOTEST_JUDGE_TOKEN` was checked with a plain string comparison, which
+  returns as soon as one character differs; both sides are now hashed and
+  compared with `timingSafeEqual`. The judge guide and the package README
+  gain a section on what leaves the machine — the one element's rendered
+  text and the rubric, nothing else; the secret redactor does not act on
+  that body; CI defaults to `fake` — and on why a verdict, being a model's
+  reading of the page's own text, is a check on wording and never a
+  security gate.
+
+- b3e1220: Box notifications: a webhook channel's header values are credentials.
+
+  The notifications API and the guard's page now see a webhook's headers
+  as names with `{ set: true }` — the values (the receiver's
+  `Authorization`, most of the time) are never read back, like the signing
+  secret. The edit form lists the names; typing a value after one replaces
+  the set, names alone keep it. `/api/box/notify` is the guard's own route:
+  it is no longer reachable through the session proxy for any role — a
+  readonly session could previously list every project's channels with
+  their headers.
+
+- b3e1220: Box notifications: the webhook signature now covers a timestamp.
+
+  Every webhook delivery carries `X-Unotest-Timestamp` (Unix milliseconds,
+  when it was sent), and `X-Unotest-Signature` is HMAC-SHA256 over
+  `<timestamp>.<raw body>` rather than the body alone — GitHub's scheme
+  with a timestamp in front, so a delivery captured on the wire cannot be
+  replayed to the receiver once its window (five minutes, documented) has
+  passed. The GitHub webhook the box receives is unchanged: that is
+  GitHub's contract.
+
+  The `by` of a CI-triggered run (`push a1b2c3d (branch)`) is cut at 200
+  characters — a branch name is the pusher's input, and it must not balloon
+  the run's manifest and every notification the run produces.
+
+- b5907cf: Pin playwright to the exact release the box image ships.
+
+  `@unotest/web` depended on `playwright ^1.62.0`, so a fresh install of a
+  suite could pick a newer playwright than the browsers inside the box's
+  `mcr.microsoft.com/playwright` image, and every run on the box failed
+  with "Browser 'chromium' is not installed" the day 1.63.0 shipped. The
+  dependency is now the exact version of the image (1.62.1); the two are
+  bumped together, and a guard in the monorepo's `verify` keeps them equal.
+
+- 5d1bde3: Building the runner no longer writes into the project tree.
+
+  `ExplorationService` created `.unotest/explorations/` in its constructor,
+  and the composition root builds it for every entry point — including an
+  `e2e` run. Where the project tree is read-only (a box mounts a pushed
+  bundle that way) the run ended before a browser was asked for. Recording
+  is an MCP activity, so the folder is now created with the first record
+  written instead.
+
+  With the editor-typings fix in the same release, an ordinary `lint` /
+  `e2e` writes nothing under the sources: run artifacts go to
+  `UNOTEST_ARTIFACTS_ROOT` (which the box makes writable), and everything
+  else that writes into the project — recording, authoring, `init`, `env
+set`, `bundle push` — happens on a developer's machine.
+
+- 5d1bde3: Run isolation, stage 1: a box no longer executes a test bundle inside its
+  own daemon.
+
+  box-runner (new, private): the run sidecar — the only service on a box
+  holding the docker socket, and the only one that starts a container. Three
+  authenticated routes on the `box` network (`POST /runs`, `GET
+/runs/:id/stream` NDJSON, `DELETE /runs/:id`), a shared secret compared in
+  constant time, and an API that cannot be told anything about how a
+  container is built: no path, image, network, user, mount or flag. A request
+  names a project, an environment, a bundle, a scenario and the environment's
+  values; the bind sources are derived from the first three, resolved with
+  `realpath` and re-checked against the projects root, and must already
+  exist. The container is created over the Docker Engine API (pinned
+  `v1.43`) straight over the socket — no `docker` binary in the image and no
+  client dependency, and a container that is a JSON document has no place
+  for a value to become a flag. A daemon that refuses or is not there comes
+  back as `502 {reason}` before the run is accepted, or as an `error` event
+  on the stream after — never as a run that "exited with code null". An
+  environment variable the box does not forward is named in the sidecar's
+  log rather than dropped silently. A run gets the bundle tree read-only as its working directory, the
+  environment's `unotest/.runs.<env>` read-write, a `noexec` tmpfs `/tmp`,
+  a read-only rootfs, all capabilities dropped, `no-new-privileges`, its own
+  uid in boxd's group, memory/pids/cpu limits clamped to both the operator's ceilings and the
+  host's own size (docker refuses a container bigger than the machine
+  instead of clamping it), a 512 MB `/dev/shm`
+  (docker's default 64 MB kills Chromium mid-page; the host's IPC namespace
+  is deliberately not borrowed), and the `runs` network only. The container engine is an interface, so every rule is asserted on
+  the container that would have reached docker — including the cases where
+  the answer is no container at all.
+
+  boxd: running the SUITE is its own contract (`IScenarioRunner`), separate
+  from running a command (`ICommandRunner`, still the daemon's own `npm ci`
+  and viewers). `ContainerScenarioRunner` talks to the sidecar,
+  `ProcessScenarioRunner` keeps the old child-process shape for a box without
+  docker; `BOXD_RUNNER_KIND=container|process` chooses, and half a container
+  configuration refuses to start. Reading a bundle's schedules
+  (`unotest-web schedules --json`) executes the project's config module, so it
+  goes the same way. A run's environment is built from named parts
+  (`run-environment.ts`) instead of inheriting `process.env`, and its debug
+  tree is pointed at the run's own directory rather than the read-only
+  sources. New metrics
+  `boxd_run_container_total{outcome}` and `boxd_run_container_start_seconds`.
+  An environment's runs directory is created by the daemon with `2775`, so
+  the run's uid may write into it and the daemon's group may read it back.
+
+  box-kit: `secretsMatch` (constant-time secret comparison, moved out of
+  dist-service), `splitLines`, and `envNumber` / `envPositiveNumber` — the
+  env-reading rule the box-side services share.
+
+  `npm ci` of a bundle is a container of its own (`kind: "install"`): the
+  bundle tree is its only mount and it is writable, there is no environment
+  and no artifacts directory in reach, and a dependency's install scripts
+  RUN — a native module builds or fetches its binary as usual. That is what
+  running them inside the daemon could never allow. The container's last
+  steps, only on success, check the tree against the box's size cap, set
+  the final modes on what the install created and write the install marker
+  — each with an exit code of its own, so the daemon's log names the step
+  that failed — so a killed or oversized
+  install leaves a tree the box will not mount; a failed install takes the
+  tree with it. The daemon no longer passes `--ignore-scripts` and no
+  longer walks the tree afterwards.
+
+  The daemon runs with `umask 002` and clears `node_modules` before each
+  install, so a tree it created is one the install container (another uid
+  in its group) can actually write.
+
+  An install that fails KEEPS the tree, unmarked: nothing mounts it and the
+  next attempt reinstalls in place (`npm ci` wipes `node_modules` itself).
+  And a bundle directory holding a manifest with neither an archive nor a
+  tree behind it no longer counts as "this box has it" — a push of the same
+  content brings it back instead of being answered `already had this exact
+bundle`.
+
+  web: `bundle push` and the docs say that a dependency's install scripts
+  run on a box, in isolation — the earlier advice to vendor them is gone.
+
+  A run ordered in the viewer now goes through the daemon's queue instead
+  of being spawned by the viewer.
+
+  `POST/GET/DELETE /api/box/envs/<project>/<env>/runs[/<runId>]` (paths and
+  wire types in `@unotest/protocol`) takes a `manual` ticket like every
+  other producer. Two callers may use it, and neither is taken on its word:
+  the guard, proving it is the guard with a shared secret from `box-init`
+  (the actor header is read only next to it — a viewer container could
+  otherwise claim to be any admin), and a viewer, with a per-environment
+  token the daemon minted when it started that viewer plus a short-lived
+  single-use ticket the guard signed over WHO clicked. The guard gates the
+  route under `admin` and requires an `Origin` on a mutation; the daemon
+  checks the token's environment, the ticket's environment and its `jti`
+  against the path.
+
+  `@unotest/viewer` gets `BoxdRunner`: on a box the Run button orders and
+  the Stop button asks the daemon, and the progress still comes from the
+  run's journal on disk. A local viewer spawns as it always did — the
+  composition root picks by whether a box handed it credentials.
+
+- 348aba7: Run isolation, stage 2b and 3: an environment's viewer runs in a
+  container of its own, and a box ships the sidecar in its compose stack.
+
+  The viewer was the last thing on a box that executed a bundle's code next
+  to the daemon's state: it runs the UI, the language service and the
+  linter out of the bundle's own `node_modules`. It is now a container the
+  run sidecar starts and the daemon asks for — `POST /viewers`, one per
+  environment, addressed by a name both services derive
+  (`unotest-viewer-<project>-<env>-<8 hex>`, port 7788).
+
+  Each viewer gets a NETWORK of its own with exactly two other containers
+  attached: the guard, which proxies people at it, and the daemon, which it
+  orders runs from. Not the sidecar's network, not the runs network, and
+  above all not another viewer's — a viewer has no authentication of its
+  own, and two on one network would be two containers of untrusted code
+  with a route to each other. That network is INTERNAL: a viewer's server
+  makes no outbound call, so it gets none, while the network a run joins
+  stays open because a test drives an application. The name of a viewer and
+  its network is a function of the project/environment PAIR rather than of
+  the string they join to, so two environments whose names concatenate the
+  same way cannot end up sharing one. Its mounts are the bundle tree read-only and
+  the environment's `unotest/` read-write (the run history it renders and
+  the queue it withdraws tickets from); the environment's secrets and its
+  `current` link sit in the directory above and are mounted by nobody. Its
+  environment is assembled by the daemon — the target, the environment's
+  variables and secrets, its own credential — and the daemon's own
+  `process.env` no longer travels.
+
+  **Editing a suite's files from the viewer on a box no longer works**: the
+  sources are read-only there. Such edits never survived the next `bundle
+push` anyway, which replaced the tree. Everything else in the UI is
+  unchanged.
+
+  Readiness is the docker daemon's own healthcheck, probed inside the
+  container and read through the sidecar — the daemon no longer waits on a
+  lock file, and nothing dials a viewer from the process holding the docker
+  socket. A viewer's output is streamed into the daemon's log and
+  reattached when the stream drops. A container whose bundle and values
+  still match is ADOPTED across a restart of either service, keeping the
+  credential it was born with; one whose environment is gone is stopped,
+  with its network and its token. The sidecar recognises its own containers
+  by label, never by name alone, and enforces its own ceiling on how many
+  viewers may exist (`BOX_RUNNER_MAX_VIEWERS`) — boxd knows how many
+  environments there are right up until boxd is the thing that was
+  compromised.
+
+  A run somebody stopped now ENDS in the viewer instead of hanging.
+  Stopping a run stops its container gracefully (SIGTERM, then SIGKILL
+  after `BOX_RUNNER_STOP_GRACE_SECONDS`, default 10) so the suite writes
+  the terminal event of its own journal; if it could not — the grace ran
+  out, the machine died — the daemon appends it. The same grace applies to
+  a run killed on its timeout, so a run's budget is the timeout plus the
+  grace.
+
+  A viewer that dies is noticed in about a second and replaced: the log
+  stream the daemon holds open ends with the container, and the 404 that
+  answers its immediate reattach is the signal. The route comes out of the
+  table at once — the guard then says the environment has no viewer instead
+  of proxying at a dead address — and a fresh container is started, on the
+  same backoff the daemon uses for everything else it cannot reach.
+
+  A restart of the sidecar is no longer an outage. While it cannot be
+  reached the daemon keeps the routes it published (the viewer containers
+  are up, and the guard reaches them directly) and tries again with a short
+  backoff instead of waiting for its next five-minute sweep. Editing a file
+  in the viewer on a box now answers 403 with the reason — the sources are
+  read-only there — rather than a blank 500.
+
+  The viewer no longer collapses the daemon's refusals into a blank 500:
+  the box's own status and reason reach the browser, so "that click has
+  already been used" (409), "the box cannot verify the caller" (503) and
+  "the box daemon is not answering" (503) are told apart by the person who
+  clicked.
+
+  Deployment: `compose.yaml` gains the `runner` service (the only holder of
+  the docker socket, the release ships its bundled `box-runner.mjs` beside
+  `boxd.mjs`), fixed container names for the guard and the daemon, a
+  `box_secrets` volume whose secrets `box-init` generates, and a one-off
+  migration of the projects tree to the group layout an install container
+  needs. Two values an operator fills in: `BOX_PROJECTS_HOST_DIR` (a bind
+  source is resolved by the docker daemon on the host) and `BOX_DOCKER_GID`.
+  Step by step in the box release's cutover manual.
+
+- 9158968: Viewer: a run that started before the page was reloaded is shown again.
+
+  The live sidebar was rebuilt from WebSocket events only, and those speak
+  from the moment the page connects — a collection already in progress
+  never re-sent its `started` event, so after a reload it was missing from
+  ACTIVE, then reappeared nameless with no scenario list once its next
+  scenario began, while its children showed up one by one. On load, and on
+  an environment or target switch, the viewer now asks the server which
+  runs are live and replays each one's journal into the same state the
+  live stream feeds, so a reload mid-run shows the collection with its
+  name, scenarios and progress.
+
+- b3e1220: Viewer: a session that may not edit variables does not see credential-shaped
+  values, nor the project's absolute path.
+
+  Behind the guard, a readonly session could read `GET /api/variables` and
+  get every box variable's value — `PASSWORD=…` included when the operator
+  had pushed it as a variable rather than a secret. The viewer now reads the
+  capabilities the guard stamps on each request: when the caller cannot edit
+  variables, a value whose name matches `PASSWORD | PASSWD | SECRET | TOKEN |
+KEY | CREDENTIAL` is sent empty and flagged `secret`, and `GET /api/targets`
+  leaves out `projectRoot`. Display-masking by capability, not authorization —
+  a viewer without a proxy in front is unchanged, and the guard still refuses
+  every write.
+
+- bd6b7ba: Viewer: a collection run no longer shows up nameless and without scenarios.
+
+  The journal tailer moved its cursor to the end of the file even when the
+  last line was still being written, so the half already on disk was lost
+  and the other half was later read as garbage. The longest line in a
+  journal is `collection-run:started` with the scenario list, so that was
+  the one it usually caught: the run appeared under its id instead of its
+  collection name, with "collection has no scenarios" and a `2/0 done`
+  counter. The cursor now stops at the last complete line and the rest is
+  read on the next change.
+
+- 8846a06: Viewer: a run started the moment the viewer came up is shown, not lost
+  until the next change.
+
+  Watching a directory becomes live a moment after the watcher reports it
+  is ready, and a run directory created inside that gap was not merely
+  late — it was invisible until something else changed in the same day,
+  which in a quiet environment is the next run. Measured at 1-3% on macOS
+  with a busy machine, and the window is exactly "open the viewer, start a
+  run". The viewer now proves the watch delivers before it declares itself
+  up: it creates a directory of its own and waits to hear about it, so
+  boot completes on evidence rather than on a promise. A tree it cannot
+  write to, or a probe that never comes back, costs a warning in the log
+  and boots as before.
+
+  A directory whose name starts with a dot is never reported as a run — an
+  editor's leftovers, or the watcher's own probe, can no longer appear in
+  the run list as a phantom.
+
+  Run queue: a waiter whose process paused is no longer mistaken for dead
+  — the queue stamps its own files with its own clock.
+
+  A run waiting for a slot proves it is alive by touching its ticket, and
+  what it is judged against was the modification time the filesystem
+  wrote: on a network share that is the server's clock, and against a
+  machine busy enough to keep a process off the CPU, a ticket written a
+  moment ago could look like it belonged to a process that died. The queue
+  now stamps every file it creates with the same clock it judges them by.
+
+- Updated dependencies [2abfd4d]
+- Updated dependencies [b3e1220]
+- Updated dependencies [b3e1220]
+- Updated dependencies [5d1bde3]
+- Updated dependencies [348aba7]
+- Updated dependencies [9158968]
+- Updated dependencies [b3e1220]
+- Updated dependencies [bd6b7ba]
+- Updated dependencies [8846a06]
+  - @unotest/protocol@0.33.0
+  - @unotest/viewer@0.33.0
+  - @unotest/core@0.33.0
+  - @unotest/dsl@0.33.0
+  - @unotest/grounder-client@0.33.0
+
+## [0.32.0] - 2026-09-05
+
+### Minor Changes
+
+- 442fadf: `npx @unotest/web box …` reads a box's results from a terminal: `box envs` lists the environments a read token may look at, `box runs` their history (`--latest` collapses it to one line per scenario with its failing streak), `box run <id>` explains one run — the failure, the soft steps, the judge's verdicts — `box queue` shows who is waiting, and `box screenshot` saves a frame the run captured.
+
+  `box run --download` fetches the run's `*.unotest.zip` into `.unotest/box/` and unpacks its failure bundle into `.unotest/failures/`, where `list_failures`, `get_failure_*` and `agent_fix` already look — so a run that failed on a box is debugged with the commands a local failure is. `--no-screenshots` asks the box itself to leave the step frames out (`GET /api/runs/:id/export?screenshots=0`), which is what makes the download smaller rather than only the disk.
+
+  Reading needs a personal read token in `UNOTEST_BOX_READ_TOKEN`; the project's `UNOTEST_BOX_TOKEN` still pushes bundles and values and cannot read runs.
+
+  The viewer publishes its archive reader as `@unotest/viewer/snapshot`, so the three places that open a `*.unotest.zip` — its server, its browser bundle and now the CLI — share one implementation and one message for a file that is not an archive.
+
+- 69fbea1: Six MCP tools close the loop that `bundle push --run` opens: `box_run` says what became of a run the agent ordered on a box, `box_run_download` unpacks its failure bundle into `.unotest/failures/` so `get_failure_trace`, `get_failure_console`, `get_failure_a11y`, `get_failure_screenshot`, `get_failure_network` and `agent_fix` work on it unchanged, and `box_envs`, `box_runs`, `box_queue` and `box_screenshot` cover the cases where the agent has no run id, no environment name, a run that never started, or a page it would rather see than read about. Their descriptions carry the route, not just the arguments.
+
+  Without a read token the tools refuse with a message saying where to mint one, so an agent meets an instruction rather than an unexplained failure.
+
+- 9099f64: Box: personal read tokens, so an agent can read a box's runs without a browser.
+
+  A user mints a token for themselves on the guard's new **Read tokens** page
+  (`/_guard/tokens`), sees the value once, and points a client at the box with
+  `UNOTEST_BOX_READ_TOKEN`. The token is always `readonly` whatever its owner's
+  role, may only `GET`, and names the environment it means in
+  `X-Unotest-Environment: <project>/<environment>` (`GET /_guard/api/envs` lists
+  them). It is not a machine identity: it follows its owner — revoked, disabled
+  or a lapsed seat all stop it, and the refusal says which. An administrator
+  sees every token on the box and can revoke one that is not theirs; issuing,
+  first use and revocation all land in the audit trail.
+
+  `UNOTEST_BOX_TOKEN` is unchanged: the project token still pushes bundles and
+  environment values, and read tokens cannot — asking with the wrong one now
+  says which token the route wants instead of a bare "unauthenticated".
+
+  A read token is never passed on to the viewer behind the guard, so it cannot
+  end up in the logs of a service that has no use for it. A box whose licence
+  has lapsed, and an environment whose viewer is not up yet, answer a token in
+  the read contract's shape rather than with a page or a bare 503 — "wait" and
+  "renew the licence" are not the same instruction as "your token is wrong".
+
+### Patch Changes
+
+- 5266b30: The agent integration guide's tool catalog matches the server again. It listed fifteen per-action tools (`goto`, `click`, `fill`, `press`, …) that were removed when recording moved into `explore_step`, had no section at all for the ten exploration tools that replaced them, counted the debugger's eleven tools as six, and put the total at 39 when it is 50. An agent reading it as a map — which is exactly what this file is for — would call tools that do not exist and conclude the server is broken. Every name now comes from the list the test suite verifies against the real registry, and the section counts add up to the total.
+- 442fadf: `BoxReadClient` reads a box's runs — environments, run history, one run's whole journal, a collection's children, the queue, a run's export zip and its individual artifacts — over the same HTTP routes a browser uses, authenticated with the personal read token in `UNOTEST_BOX_READ_TOKEN`. Every refusal arrives as a typed `BoxReadError` whose `kind` says what to do next, so throttling is never mistaken for a rejected token and a live run's export says "wait" rather than looking like a broken box. Configuration mistakes surface when a read is attempted rather than at startup, so a stale token in a project's `.env` cannot stop a local run that never touches a box.
+
+  The viewer gains a `@unotest/viewer/wire` entry point exporting its HTTP contract types (the runs page, a run's full snapshot, the queue payload and the snapshot manifest), so a client can name the shapes it parses instead of keeping a second copy of them.
+
+- f770a25: The box address and the read token are resolved from `unotest/.env` and `unotest/.secrets` on every request, not once at startup, and the `box` CLI reads those files directly. `unotest-web box …` runs without loading the project config, so nothing had flattened `unotest/.env` into its environment — the command told people to put the address there and then refused with "no box address". And an MCP server that resolved once meant a token written while it ran was ignored until the editor reconnected it, which is exactly the restart this path exists to avoid. One rule for both settings, from both entry points: a flag, then the environment, then the project's files.
+- 8aa0f30: Protocol contract for reading a box's run results with a personal read token: `UNOTEST_BOX_READ_TOKEN` (distinct from the project's `UNOTEST_BOX_TOKEN`, which stays a write credential for bundles and environment values), the `X-Unotest-Environment: <project>/<environment>` header every bearer request names its own environment with, the `/_guard/api/envs` listing and its `BoxReadEnvironment` entry, and typed refusals (`unauthorized`, `forbidden`, `unknown-environment`, `not-found`, `rate-limited`, `run-in-progress`, `unavailable`, `malformed`) with parsers that reject anything that is not a box answering. Throttling gets a code of its own rather than an `unauthorized` carrying `Retry-After`: a rejected token means mint a new one, a throttled one means wait and resend the same one. The viewer's `ViewerEnvOption` is now that same protocol type rather than a second copy of it. An environment whose viewer is still starting — the common state right after a bundle push — answers `unavailable` rather than looking like an unreachable box, so the advice is to wait rather than to check the address.
+- 8aa0f30: A run exported as `*.unotest.zip` now carries everything needed to diagnose it away from the machine that produced it: `stdout.log` and `stderr.log` (previously dropped, which left the one artifact that explains a runner crash outside the bundle), the failing page's `page.html` reachable through the manifest, and the run's step screenshots — declared in a new `manifest.screenshots` list, because an importer keeps only what the manifest names and a frame absent from it did not survive the round trip.
+- 5266b30: `UNOTEST_BOX_READ_TOKEN` is now read from `unotest/.secrets` as well as from the environment, with an exported value winning. This is what makes the `box_*` tools usable from an agent at all: an MCP server is started by the editor, so a token that exists only in a shell is a token the server never receives — the alternative was editing the editor's own JSON config and reconnecting the server. `unotest/.env` is deliberately not consulted: it travels inside a pushed bundle, while `.secrets` does not. The CLI resolves the token the same way, so one token serves both.
+- 5266b30: `box run` and `box_run` now carry the `{tag}` of a failed soft step, in the JSON and in the printed line (`Rubric [judge-red]`, the shape a local run already prints). A data-driven test runs one `step.soft` over many cases, so its failures all share a label and the tag is the only thing that says which case failed — without it a remote reader saw "Rubric failed" three times and had to tell them apart by line number. The tag was in the run's journal all along; the summary dropped it.
+- ee6bb51: Secrets injected by a box are masked. Masking works by value, and the registry of values was built from `unotest/.secrets` alone — a file that does not exist on a box, where the daemon passes the values as environment variables and names them in `UNOTEST_BOX_SECRET_NAMES`. The registry was therefore empty on every box run, and a password a scenario typed reached the run journal, the run's `stdout.log`, the viewer's System pane and anything an agent downloaded, in the clear. The runner now registers those values alongside the ones it reads from files, so masking no longer depends on where the run happens to be. Nothing changes on a developer's machine, where the variable is not set.
+- 047ca68: Failure text no longer carries terminal colouring into files and replies.
+
+  Playwright paints its call log whenever the environment claims a terminal is
+  watching — `FORCE_COLOR`, which an MCP server inherits from whatever launched
+  it — and that message was copied verbatim into `steps.jsonl`, `runtime.json`
+  and the failure bundle. An agent reading the JSON got an escape sequence in
+  the middle of the sentence it was trying to parse, and the viewer rendered
+  it as a chewed-up word.
+
+  The colouring is dropped where a thrown error becomes our data, so every
+  reader of a failure gets the same clean text. Our own output is unaffected:
+  it paints at print time, which is where colour belongs.
+
+  The same on mobile: a failure's text in the run journal and in the report no
+  longer carries terminal escapes.
+
+- 047ca68: A failure somebody paused on stays a failure, with the evidence to show for it.
+
+  A run driven through the debugger — `run_test` then `resume`, or the viewer's
+  Continue — reported `completed` after a failure it had paused on, wrote no
+  failure bundle and no `failure/` artifacts, and left `list_failures` with
+  nothing to show. Continuing past a failure is how it gets inspected; it was
+  never meant to retract it. The verdict is now decided where the run's own
+  events are seen, so the journal, `runtime.json` and the reply agree, and a
+  debug run leaves the same evidence a plain `unotest-web e2e` run does.
+
+  `abort_runtime` (and Stop, and SIGTERM) now also ends the run in
+  `runtime.json`, not only in `steps.jsonl`: the control file used to keep
+  saying `paused-step` about a run that was over, so anything reading it rather
+  than the journal saw a pause that never ended.
+
+- c5d3cda: README links the documentation site instead of manuals that are not shipped in the package (`guides/manuals/*`), and says what a run on a box cannot reach: `localhost`, port-forwards, host tools, a judge service on your machine — with the recipe for the judge on a box.
+- 442fadf: Secret values registered from `unotest/.secrets` are now masked in what the runner prints, not only in what it writes. The run journal and every failure artifact were redacted; the terminal line was not, and that line is also copied into the run's `stdout.log` / `stderr.log` and streamed to the viewer's System pane. Masking is applied once, where the logger is built, so child loggers and message arguments are covered too. The collection runner is covered by the same rule: its messages go through its logger rather than straight to the stream, and the logger it builds when a caller passes none reads the project's secrets the way the composition root's does.
+- 047ca68: A `step.soft(...)` failure no longer stops a debug run — or goes missing from it.
+
+  Under a debugger (`run_test`, or `e2e --debug`), every soft failure raised
+  the debug wheel: the run stopped on each one and an agent had to `resume`
+  its way through them. Worse, it was then lost — a paused failure is consumed
+  where it paused, so it never reached the `step.soft` envelope that records
+  it, the envelope closed as if the block had passed, and a run with three
+  soft failures could finish green with none of them listed.
+
+  Pausing is now for a failure that ENDS the run. A failure under any
+  enclosing soft step is recorded and stepped over exactly as it is on the
+  command line, and `runtime.json` — which the `run_test` reply is built from —
+  carries every soft failure of the run, not just the last stop.
+
+  A hard failure still pauses: that is what the debugger is for.
+
+  The same holds on mobile: a `step.soft(...)` failure no longer stops a run
+  under the debugger, and every soft failure of a run is now part of its
+  runtime state instead of being lost at the pause.
+
+- Updated dependencies [442fadf]
+- Updated dependencies [442fadf]
+- Updated dependencies [8aa0f30]
+- Updated dependencies [8aa0f30]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+  - @unotest/viewer@0.32.0
+  - @unotest/protocol@0.32.0
+  - @unotest/dsl@0.32.0
+  - @unotest/core@0.32.0
+  - @unotest/grounder-client@0.32.0
+
 ## [0.31.0] - 2026-09-04
 
 ### Minor Changes

package/README.md

@@ -7,6 +7,11 @@ and commit.**
 MCP server + CLI runner + JavaScript DSL + semantic DOM snapshots +
 structured failure bundles.
 
+Full documentation — manuals, the box, CI, the judge — lives at
+[docs.unotest.com](https://docs.unotest.com). This README is the short
+tour; the package ships only `guides/dsl-reference.md` and
+`guides/agent-integration.md` alongside it.
+
 ---
 
 ## 1. Setup
@@ -151,8 +156,11 @@ step. Secrets stay behind: `unotest/.env*` and `.secrets*` never travel,
 because environment values belong to the environment and are injected
 over the bundle when it runs. Install hooks (`postinstall`, `prepare`,
 ...) are removed from the packed `unotest/package.json`: a box installs
-the suite's dependencies, it does not run a checkout's hooks. Dependency
-install scripts (native modules) run as normal.
+the suite's dependencies, it does not run a checkout's hooks. Your
+DEPENDENCIES' install scripts do run — a native module builds or fetches
+its binary as usual — because on a box that install happens in a
+container of its own, with the bundle tree as its only writable mount
+and none of the box's state in reach.
 
 What would break on the box is refused here instead — a scenario that
 reads a file outside `unotest/`, a missing `unotest/package-lock.json`,
@@ -170,7 +178,7 @@ a suite takes minutes, and a request held open that long is a timeout,
 not a result. Watch them in the viewer, or let the box report the checks
 back to GitHub. `--pr` makes a newer push withdraw the older runs of the
 same pull request that are still waiting, so three pushes in five minutes
-cost one suite. Recipe: `guides/manuals/ci-setup.md`.
+cost one suite. Recipe: [Pushing suites → A minimal CI job](https://docs.unotest.com/box/pushing-suites/#a-minimal-ci-job).
 
 The values a suite runs with on the box — `APP_BASE_URL`, its `.env`
 settings, its secrets — are sent separately, from the same files a local
@@ -184,7 +192,66 @@ printf '%s' "$KEY" | npx @unotest/web env set dev API_KEY --secret
 `.env*` become the environment's variables, `.secrets*` its secrets,
 `APP_BASE_URL` its target; `UNOTEST_*` stay home. A value never prints.
 The token must be minted with `--values` on the box. Admins also see and
-change them on the box's admin page. Manual: `guides/manuals/box-values.md`.
+change them on the box's admin page. Manual: [An environment's values on a
+box](https://docs.unotest.com/box/environments-and-values/).
+
+A run on the box happens inside the box's own container: nothing on your
+machine is reachable from it — no `localhost`, no `kubectl port-forward`,
+no tools installed on your laptop. Preconditions must probe the
+environment's public URL, and `assertJudge` runs its judge in-process there
+(`UNOTEST_JUDGE_MODE=local`, `@unotest/judge` in the suite's
+`package.json`, the API key as a secret). Details:
+[Judge on a box](https://docs.unotest.com/guides/judge/#on-a-box) and
+[What a box cannot reach](https://docs.unotest.com/box/troubleshooting/#what-a-box-cannot-reach).
+
+### Reading results from a box
+
+`bundle push --run` gives you a run id. Read what became of it from the
+same terminal — no browser, no shell on the box:
+
+```sh
+npx @unotest/web box runs --env acme/test --latest
+npx @unotest/web box run checkout-mqf3pwr1 --env acme/test
+```
+
+`box run` prints the failure, the results of soft steps and the judge's
+verdicts. When you want the artifacts too:
+
+```sh
+npx @unotest/web box run checkout-mqf3pwr1 --env acme/test --download
+```
+
+That saves the run's `*.unotest.zip` under `.unotest/box/` and unpacks its
+failure bundle into `.unotest/failures/` — where `list_failures`,
+`get_failure_*` and `agent_fix` already look, so your agent debugs a box
+failure with the commands it uses for a local one. Add `--no-screenshots`
+to leave the step frames on the box; they are usually most of the bytes.
+
+Reading uses a **personal** read token, not the project one. Put it in
+`unotest/.secrets`, next to your other project secrets:
+
+```sh
+UNOTEST_BOX_READ_TOKEN=ubr_...
+```
+
+and the box's address in `unotest/.env` as `UNOTEST_BOX_URL`. Both files
+are read directly, so this works the same from the terminal and from your
+agent. Exporting either value in your shell works too and wins over the
+file; `--box` and `--token` win over both.
+
+The token is never read from `unotest/.env` — that file travels inside a
+pushed bundle, and `.secrets` does not.
+
+Keeping it in the file is what lets your agent read runs: an MCP server is
+started by your editor, so a token that only exists in your shell is a
+token the agent never sees. A token added while the server is running is
+picked up on the next call — nothing to restart.
+
+You mint it for yourself on the box's guard ("Read tokens"), it is shown
+once, and it is revocable. It is read-only whatever your role on the box — it cannot start
+a run or change a value. `UNOTEST_BOX_TOKEN` is the project's push
+credential and cannot read runs. `box envs` lists the environments a token
+may look at.
 
 ## 5. Watch it run — the viewer
 

package/dist/config/schema.d.ts

@@ -30,10 +30,10 @@ declare const RetryConfigSchema: z.ZodObject<{
     on: z.ZodArray<z.ZodEnum<["transient", "network", "crash"]>, "many">;
 }, "strip", z.ZodTypeAny, {
     count: number;
-    on: ("transient" | "network" | "crash")[];
+    on: ("network" | "transient" | "crash")[];
 }, {
     count: number;
-    on: ("transient" | "network" | "crash")[];
+    on: ("network" | "transient" | "crash")[];
 }>;
 type RetryConfig = z.infer<typeof RetryConfigSchema>;
 declare const FailureBundleConfigSchema: z.ZodObject<{
@@ -276,10 +276,10 @@ declare const UnotestConfigSchema: z.ZodObject<{
         on: z.ZodArray<z.ZodEnum<["transient", "network", "crash"]>, "many">;
     }, "strip", z.ZodTypeAny, {
         count: number;
-        on: ("transient" | "network" | "crash")[];
+        on: ("network" | "transient" | "crash")[];
     }, {
         count: number;
-        on: ("transient" | "network" | "crash")[];
+        on: ("network" | "transient" | "crash")[];
     }>;
     failureBundle: z.ZodObject<{
         /** Tier 1 is always on by D-16. Schema lock — not user-toggleable. */
@@ -461,7 +461,7 @@ declare const UnotestConfigSchema: z.ZodObject<{
     };
     retry: {
         count: number;
-        on: ("transient" | "network" | "crash")[];
+        on: ("network" | "transient" | "crash")[];
     };
     failureBundle: {
         tier1: true;
@@ -523,7 +523,7 @@ declare const UnotestConfigSchema: z.ZodObject<{
     };
     retry: {
         count: number;
-        on: ("transient" | "network" | "crash")[];
+        on: ("network" | "transient" | "crash")[];
     };
     failureBundle: {
         tier2: boolean;