@unotest/web 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,501 @@
 # Changelog
 
+## [0.35.0] - 2026-09-15
+
+### Minor Changes
+
+- 86da16e: A remote grounder can now say "this account has spent its month", and a client
+  can tell that apart from a bad token.
+
+  A grounder running on an external model provider meters what each account
+  costs and stops at a ceiling. At the ceiling the two routes that call a model —
+  indexing a page and resolving an intent — answer HTTP **402** with
+  `grounder-budget-exhausted`. Money, not permission: the token is perfectly
+  good, nothing is re-minted over this, and a client that treats it as an auth
+  failure would retry forever. The body carries no amount and nothing about any
+  other account; the figure is an estimate of a bill we do not issue, and a
+  customer would rightly check it against the provider's own.
+
+  What a ceiling stops is **writing** tests, not running them, and every text
+  about it says so: only the MCP server asks the grounder — `ground_element`,
+  and an intent locator inside `explore_step` / `find_element`. A scenario
+  carries the locator it was written with, so suites, their runs on a box and
+  the viewer are untouched by a cap.
+
+  `ErrorResponse.code` names it, and gains `revocation-list-unavailable` at the
+  same time: a grounder has been answering with that code since signed tokens
+  arrived, and the union never learned about it — a client written from the type
+  could not discriminate a refusal it was already receiving. `retryAfterSeconds`
+  joins the shape for it, matching the `Retry-After` header that was already
+  being sent.
+
+  Nothing changes for a grounder running on our own GPU: nothing is metered
+  there, so nothing can be refused for money.
+
+- 7ffa4ae: `box picker on|off`: the Picker, switched on a box you already have
+
+  The Picker is an hourly surcharge on top of the box, and until now it could
+  only be chosen when the box was rented — with `box create --picker`, a flag
+  most people met for the first time in `--help`.
+
+  - **`unotest-web box picker on|off [name]`** switches it on a live box, with
+    no re-creating and no re-pushing. `on` mints the box's tokens the way
+    `box access` does and writes the Picker's three keys —
+    `UNOTEST_GROUNDER_MODE=remote` and `UNOTEST_GROUNDER_REMOTE_URL` into
+    `unotest/.env`, `UNOTEST_GROUNDER_REMOTE_TOKEN` into `unotest/.secrets`.
+    `off` clears the three again, but only when they name that box's grounder:
+    a project pointing at a grounder of its own, or at another box's, keeps it
+    and is told so. Either way the charge follows at the next hourly tick,
+    because a started hour is charged at the rate it started with.
+  - **`box create` asks** about the Picker on a terminal when `--picker` was not
+    given, quoting the hourly surcharge from the cloud's own price list rather
+    than a number kept in the CLI. `--yes`, `--json` and a run with no terminal
+    answer no without asking.
+  - **`box status`** says whether the Picker is on.
+  - **`run_test` offers it once.** A project that has a box but grounds intents
+    nowhere remote gets `pickerSuggestion` (`{state: "no-picker", next, why}`)
+    after the first run that passes — exactly once per MCP server session, on
+    the same terms as `boxSuggestion`, and never both: with no box there is
+    nothing to put a Picker on.
+  - **A refusal for money reads as one.** A remote grounder answering
+    `grounder-budget-exhausted` (HTTP 402) means the account's estimated spend
+    for the month has reached its ceiling, not that the token went bad: nothing
+    is re-minted over it, and the CLI and MCP replies name both ways out — top
+    up the balance, or `box picker off` to stop the Picker and ground locally
+    again. No amount is quoted: the figure estimates a bill we do not issue.
+
+### Patch Changes
+
+- 79c99ab: A box can now say "I cannot judge this token yet" instead of "your token is
+  wrong".
+
+  A box rented from the fleet accepts tokens the cloud signed for it, and it
+  checks every one against the operator's revocation list. Until that list has
+  reached the box — the minutes between it coming up and its first update tick
+  — there is nothing to check against, so such a token is refused. That is not
+  the same refusal as a bad credential: the answer is to send the SAME token
+  again shortly, never to mint another.
+
+  `BoxReadErrorCode` gains `revocation-list-unavailable` for it, and a refusal
+  body may carry `retryAfterSeconds` (the box sends `Retry-After` with the same
+  number). The push and run answers gain the same code, plus `ambiguous-project`
+  for a cloud-minted push token that names no project on a box that serves
+  several. Nothing changes for the tokens a person or a CI job mints on the box
+  itself.
+
+- 1584ce2: `box status` says where the Picker grounds
+
+  A box whose Picker is on now prints one more line: `Grounding: Our GPU` or
+  `Grounding: External provider (Gemini)` — which models the cloud resolves
+  intent locators with. It is the answer to a question a customer could not
+  check before, only read on a web page.
+
+  The line appears only while the Picker is on. With it off, intents are
+  resolved on the machine the tests run from, and naming our models under that
+  box would describe somebody else's. A cloud that has not heard from its own
+  grounder sends nothing and the CLI prints nothing: a mode we have not been
+  told is not a mode to invent.
+
+  On the wire the field is `grounding`, not `grounderMode`. `UNOTEST_GROUNDER_MODE`
+  already means something else and belongs to the reader — whether THEIR machine
+  grounds locally, remotely or not at all — and in `box status` the two would
+  have met a line apart. It is optional, so an older cloud simply says nothing.
+
+- dee96a1: A box can now say "this token has expired" instead of "your token is wrong".
+
+  Tokens the cloud signs for a rented box live thirty days. Until now a box
+  refused an expired one with the same blanket `unauthorized` it gives a
+  forgery, so the CLI could not tell "ask the cloud for another pair and
+  retry" from "this credential will never work", and an expired pair looked
+  revoked.
+
+  The read, push, run and values answers gain the code `expired` for it. A box
+  sends it only for a token its operator key really signed, of the right kind,
+  for that box — the signature, the kind and the box are all checked before
+  the expiry is — so nothing a guesser sends can produce it. It is also
+  decided before the revocation list is consulted: a box that has not received
+  a list yet still answers `expired` rather than asking for the same dead
+  token again.
+
+  Two codes that a box could already send are now accepted when parsing a run
+  or values answer, which had been left out of those two readers:
+  `revocation-list-unavailable` and `ambiguous-project`.
+
+- 220bf37: Fake cloud: two access pairs that arrive without a `client_name` no longer
+  replace each other. A machine whose hostname the contract's charset refuses
+  sends no name at all, so two such machines were evicting one another from a
+  box — the fake now replaces a pair only when a name actually matches. Its
+  refusal for a box that is not ready is worded like the rest of the service
+  ("That box is deleted."), so a client sees the same sentence from the fake
+  and from the real cloud.
+- 067cb3d: The Picker comes with the box, and the CLI says so
+
+  The Picker used to be priced as a factor on the box's own rate, which made
+  its surcharge a different number for every size and made "what does it cost"
+  a sum rather than a price. It is now a fixed hourly price per size — and, for
+  now, one nobody pays: it is included in the price of the box.
+
+  `box create`'s question, `box picker on|off` and `box status` all say it the
+  same way, with the number the cloud sends and never one of this CLI's own:
+  "included in the price of the box (normally €0.05/h)". The list price stays
+  visible on purpose. "Included", alone, reads as "cheap now, billed later" —
+  and what is actually charged is the number a client should quote, so
+  `GET /rates` sends both: `picker` is what will be added to the bill (zero
+  while it is included) and the new `pickerList` is what it lists at, beside
+  `pickerIncluded`.
+
+  A cloud that does not send the two new fields is quoted the old way, from
+  `picker` alone — nothing to strike through, and no invented number.
+
+- 417369a: `box picker off` now takes the token away, not just the surcharge
+
+  Until now `off` stopped the hourly charge and cleared the Picker's keys from
+  this project's files. A copy of the token already on another machine — a
+  teammate's laptop, a CI secret — went on working until the box's licence ran
+  out, grounding intents on our grounder that nobody was paying for.
+
+  Switching the Picker off now revokes that box's Picker tokens, all of them:
+  the cloud writes their ids into the operator's signed revocation list, and
+  the grounder stops accepting them once it has re-read
+  that list. The command says so, and says the minute rather than promising an
+  instant. Clearing the files is now the convenience it always was; the
+  revocation is what ends the access.
+
+  Two smaller things follow from it. `off` asks the cloud to revoke even when
+  the Picker was already off, so repeating the command is how you finish the
+  job if it failed once. And a revocation the cloud cannot write is a refusal
+  you see — the surcharge stops either way, but a token still in the wild is
+  not something to leave in a log.
+
+- Updated dependencies [79c99ab]
+- Updated dependencies [dee96a1]
+- Updated dependencies [86da16e]
+- Updated dependencies [7ffa4ae]
+  - @unotest/protocol@0.35.0
+  - @unotest/grounder-client@0.35.0
+  - @unotest/viewer@0.35.0
+  - @unotest/core@0.35.0
+  - @unotest/dsl@0.35.0
+
+## [0.34.0] - 2026-09-07
+
+### Minor Changes
+
+- c6b91bb: From `init` to a paid box without copying a token: `login`, `box create`,
+  and the tokens that keep themselves fresh.
+
+  Three new commands sign this machine in to unotest cloud — the account
+  that rents boxes — and rent one:
+
+  - `login` runs the device flow (RFC 8628): it prints a link and a code,
+    opens the browser when there is one, and waits for the approval. The
+    key is kept in `~/.config/unotest/credentials.json` (mode 0600,
+    `XDG_CONFIG_HOME` honoured) and is never printed, not even with
+    `--json`. `UNOTEST_CLOUD_TOKEN` in the environment wins over the file,
+    which is how a CI job signs in. `logout` revokes the key on the server
+    when the cloud can be reached and removes it locally always; `whoami`
+    says who, where the key came from, and the balance (exit 77 when not
+    signed in).
+  - `box create [name] [--size s|m|l] [--topup <eur>]` creates a box named
+    after the project (its package name, as a slug), with the environments
+    the project runs locally (`unotest/.env` and every `unotest/.env.<name>`,
+    their `APP_BASE_URL` or the config's `baseUrl` as the target). When the
+    balance will not cover the first hour it prints a Stripe Checkout link,
+    opens it when it can, and waits for the payment. Then it waits for the
+    box, mints its cloud-signed push and read tokens, writes
+    `UNOTEST_BOX_URL` to `unotest/.env` and `UNOTEST_BOX_TOKEN` +
+    `UNOTEST_BOX_READ_TOKEN` to `unotest/.secrets` (through the same
+    structure-preserving writer the viewer's Variables panel uses, with
+    `.gitignore` guarded the way `init` guards it), pushes the suite —
+    retrying with backoff while a fresh box has no revocation list yet —
+    and prints the viewer's address. Exit codes for an agent driving it
+    without a terminal: 75 the payment was not confirmed in time (nothing
+    created, nothing charged), 76 the terms of service are not accepted
+    (a person must, in a browser), 77 not signed in. No prompt is ever
+    shown without a TTY.
+    `--picker` rents the box with the Picker; `UNOTEST_GROUNDER_MODE=remote`
+    and `UNOTEST_GROUNDER_REMOTE_URL` then go to `unotest/.env` and
+    `UNOTEST_GROUNDER_REMOTE_TOKEN` to `unotest/.secrets` — the names the MCP
+    server reads — so intents ground on the box with no further setup. A
+    box without the Picker leaves those keys alone. The last line of
+    `create` is the next step: the complete `bundle push --run --env …
+--collection …` when the project has exactly one environment and one
+    collection, the viewer's address plus the command with placeholders
+    otherwise.
+  - `box access [name]` re-mints the pair and rewrites the two files;
+    `box status` and `box destroy` (asks on a terminal, `--yes` elsewhere)
+    are thin wrappers. The name defaults to the box `UNOTEST_BOX_URL`
+    points at (`acme.box.unotest.com` → `acme`).
+
+  Cloud-signed box tokens live thirty days. When a box answers that one
+  has expired, `bundle push` and the `box …` read commands re-mint the
+  pair through the cloud and retry once, provided a cloud login is at
+  hand; without one they say to run `login && box access`. The box a
+  re-mint is for is the one the project points at, named from its address
+  or, when the address spells no name (a stand behind an IP), by the same
+  default `create` used — so a lab box re-mints like any other. A `--box`
+  naming somewhere else is said to be somewhere else rather than blamed on
+  a missing login. A box that has
+  not yet received its revocation list is told apart from a real refusal
+  and retried; a token the box calls revoked is never re-minted quietly.
+  `bundle push` now also reads the push token from `unotest/.secrets`,
+  where `box create` puts it (then `unotest/.env`, for suites set up by
+  hand), so nothing has to be exported after the setup.
+
+  The MCP server knows the state too. While the project points at no box,
+  `box_envs`, `box_runs`, `box_run` and the other box tools answer
+  `{state: "no-box", next, why}` instead of an error, and `run_test`
+  carries the same `boxSuggestion` exactly once per server — after the
+  first local run that passes — so an agent offers the box at the moment
+  it is worth something and never nags. The box tools re-mint an expired
+  cloud-signed read token the way the CLI does, through the composition
+  root, and `unotest/.secrets` is read on every call: a pair written by
+  `box create` while the server runs is used by the next call. On a
+  Picker box, `ground_element` (and intent locators) whose picker token
+  the grounder refuses re-mint it once through the cloud and hand the new
+  token to the running client; a refusal that cannot be mended answers
+  `{state: "picker-token-refused", next: "npx @unotest/web box access",
+why}`, and a grounder that has not read its revocation list yet answers
+  `{state: "retry-shortly", retryAfterSeconds}`. Box tokens are checked
+  before the network: cloud-signed ones by their whole shape (`unos_…`), a
+  push token in the read variable (and the reverse) is named as the wrong
+  kind, anything else as not a token.
+
+  A renewal the cloud itself refuses is its own answer, not the cloud's.
+  When a box or the grounder says a cloud-signed token is stale and the
+  `/access` call that would replace it is refused in turn — no such box,
+  the box not ready, too many live pairs, the cloud unreachable — every
+  surface says that the credentials could not be renewed and keeps the
+  cloud's refusal as the cause. The CLI prints one line and exits with the
+  code that refusal earns; the grounding tools answer
+  `{state: "picker-token-refused", next, why}` as before, so an intent is
+  never answered with a sentence about boxes.
+
+  `init` ends with one line saying how to run the suite on a box; the
+  "mint a read token in the guard" advice in the box commands' refusals
+  now points at `login` and `box access` instead. `UNOTEST_CLOUD_URL`
+  points the CLI at a stand or a fake cloud; nobody sets it otherwise.
+
+  `@unotest/protocol`: `replaceEnvVar` (an in-place value replacement the
+  new upsert builds on), `BOX_PUSH_TOKEN_PREFIX` / `BOX_SIGNED_TOKEN_PREFIX`
+  / `BOX_SIGNED_TOKEN`, and `UNOTEST_BOX_URL`, `UNOTEST_GROUNDER_MODE`,
+  `UNOTEST_GROUNDER_REMOTE_URL` listed among the runner-config keys so they
+  file under the Runner section of `unotest/.env`.
+
+  `@unotest/grounder-client`: `GrounderHttpClientOptions.token` may be a
+  function yielding the current bearer; `GrounderRemoteError` carries the
+  grounder's `retryAfterSeconds`, and the error codes gain
+  `revocation-list-unavailable`.
+
+### Patch Changes
+
+- d68538f: A box refusing a token now answers with the words the box actually
+  sends, and with the step that fits the token you presented.
+
+  The CLI knew five refusal codes; a box sends three. `expired` still
+  re-mints through the cloud and retries once, `revocation-list-unavailable`
+  still means the same token, later. Everything a retry cannot fix —
+  revoked, bad signature, wrong door — arrives as one `unauthorized`, and
+  that is deliberate on the box side: a refusal that names WHICH check
+  failed is an oracle. The three codes written ahead of the box and never
+  sent by anything are gone.
+
+  What you see changes in two ways:
+
+  - the sentence is the box's own reason, never a stock phrase of ours.
+    A code this CLI does not know (a box newer than the CLI) reaches you
+    with the box's message too, instead of a generic line about a token.
+  - the suggested fix follows the KIND of token: a cloud-signed pair is
+    re-minted with `npx @unotest/web box access`; a token you minted
+    yourself on a box you run is re-minted in that box's guard, because
+    there is no cloud behind it to point at.
+
+  The MCP `box_*` tools return this as a state rather than an error, the
+  way they already do for a project with no box: `{state:
+"box-token-refused", next, why}` — `why` is what the box said, `next`
+  is the command that fixes it.
+
+  `pnpm fake:cloud --box-refusal <code>` makes the fake box refuse with
+  any code, including one the CLI does not know, so both paths can be
+  exercised without a real box.
+
+- 565d1b3: Secrets no longer travel with the page capture that grounding reads.
+
+  `UNOTEST_BOX_SECRET_NAMES` and `unotest/.secrets` masked what the runner
+  said out loud — logs, the debug log, the recorded session — but not the
+  capture `ground_element` and intent locators send to the grounder, and in
+  the hosted mode on to a model provider. Only the field TYPE was filtered
+  there: a `password` or `hidden` input was dropped by the page walker,
+  while an API token in a plain text input, a one-time code, a card number,
+  a whole textarea, a login, or a key the application printed on the page
+  went out verbatim.
+
+  Both modes come through one place now, and it cleans the capture twice
+  over before the content hash is taken:
+
+  - every registered secret value is replaced by `‹secret:NAME›` wherever it
+    occurs — a control's value, a text node, an accessible name, the page
+    title. Masking is by EXACT value: the same secret written in another
+    case is not recognised, deliberately, because matching loosely would
+    mask ordinary words and the noise would land in what grounding reads.
+  - the page URL and every link keep scheme, host and path; query, fragment
+    and `user:pass@` are dropped. That is where a password-reset token, a
+    signed link or a session id lives, and no list of known secrets can
+    cover those. A link made of nothing BUT a fragment (`#main`) keeps it —
+    that fragment is the whole label, and there is no path to name instead;
+    a fragment hanging off a real address (`/invite#SECRET`) is dropped like
+    any other. `data:`, `blob:` and `javascript:` keep their scheme alone:
+    there the document, or the code of a call with its arguments, sits
+    where the path would be. `mailto:` and `tel:` stay whole — there the
+    path is the addressee, which is a label like any other.
+
+  The masking is what the grounder is given, so it is also what the content
+  hash is taken of — two visits that differ only in a link's one-time token
+  are correctly one page to the index cache, not two.
+
+  The graph's own vocabulary is untouched: `kind`, `tag`, `role`, `ref` and
+  `testId` are structure, not content, and a secret whose value happens to
+  be `button` no longer has anywhere to do damage. Everything else in a
+  capture is masked, including a field added to it later.
+
+  Loading a secret shorter than six characters now warns, once, naming the
+  variable and its length and never its value. Nothing changes about how it
+  is masked — the warning exists because masking by value has no notion of
+  length, so `admin` as a password also masks the word wherever a page
+  writes it, and grounding can get worse on a page that has nothing to do
+  with the secret.
+
+  Still not covered, and worth saying plainly: a value the run was never
+  told is a secret. A key the application itself renders on the page — the
+  "copy it now" screen — is in no registry, and goes out with the capture.
+
+- 32a495e: Failure artifacts survive a run that is isolated from its own artifact root.
+
+  A run executed inside a container sees only what is mounted into it. The
+  failure bundle's directory is derived from the artifact root, which on such
+  a run is not one of those mounts — so it could not be created, and a failed
+  test produced no screenshot, no trace and no page HTML at all. Worse, that
+  one error took the always-on copies in the run directory down with it: both
+  sinks shared a single try, so the artifact that does not depend on the
+  bundle was lost too.
+
+  Two changes. `UNOTEST_FAILURES_ROOT` now says where bundles live, for
+  whoever spawns the run to point at a directory it can actually write
+  (unset, everything behaves exactly as before). And the two sinks are
+  independent: an unusable bundle root no longer costs you the run
+  directory's screenshot and page HTML.
+
+  The viewer serves failure assets from either layout, so a bundle written
+  inside the environment's runs tree renders like a local one.
+
+- 2416abf: `init` no longer rewrites a config the project had already edited, and
+  `--help` no longer runs the command it is asking about.
+
+  Two defects, one outcome. `init` wrote the channel into
+  `unotest/unotest.config.mjs` unconditionally at the end of every run, on
+  the assumption that the file was the placeholder it had written seconds
+  earlier. In a project that had run `init` before, that file is the
+  project's own: it was replaced by the template with no `--force`, no
+  warning, and an `already present` line printed about it. And because the
+  option loop ignored anything it did not recognise, `init --help` — the
+  first thing a person types when a command is unfamiliar — fell through
+  into a real run in the current directory, scaffolding the layout and
+  taking the config with it.
+
+  What changes:
+
+  - an existing file stays exactly as it is; the channel is patched only
+    into a config this run created itself. A re-run reports `already
+present` and changes nothing.
+  - `--force` still takes the templates, and now keeps what it replaced
+    next to it as `<file>.bak`. Being overruled is not the same as losing
+    the work.
+  - the package-owned copies `init` keeps in sync — the test-authoring
+    skill, the agent-trace hook — are still synced without `--force`, but a
+    copy that diverged is now kept as `<file>.bak` too. "Nobody edits
+    these" is an assumption about a file in your repository, and it costs
+    nothing to be wrong about it safely.
+  - `--help` / `-h` works on every command, prints the usage, and does
+    nothing else — answered before the workspace is even resolved, so a
+    question touches no files anywhere.
+  - an option a command does not recognise is refused with its usage and
+    exit **2**, instead of being dropped silently. `init` reads its options
+    against the list of what it knows, so the next flag added cannot fall
+    through the same hole.
+
+- 9daaaf7: `init` writes files that pass the project's own `prettier --check`.
+
+  The block `init` maintains in `CLAUDE.md` now has a blank line between
+  each marker and the text inside, and the JSON it writes — `.mcp.json`,
+  `.claude/settings.json` — keeps a short array on one line (`"allow":
+["mcp__unotest-web"]`) instead of one element per line. Both are what
+  prettier produces, so a repository whose CI runs `format:check` no longer
+  goes red on files it did not write itself. A file `init` merges into is
+  re-emitted by the same rules, including the entries the user had there.
+
+  `AGENTS.md` too: its DSL examples now sit in fences prettier does not
+  reformat, and every list has the blank line before it that prettier's
+  Markdown rules want.
+
+- 50b1d4d: The search text sent for grounding is masked the same way the page
+  capture already is.
+
+  Masking the capture cleaned what the PAGE said. The other half of a
+  grounding call — the intent, the thing being searched for — went out
+  untouched: to the grounding service, into the picker's prompt and the
+  embedder's query, and in the hosted mode on to a model provider. A
+  scenario that puts a variable into the search (`intent("the row for " +
+LOGIN)`) sent its value verbatim, while the same value was masked
+  everywhere else in the run.
+
+  Now every registered secret is replaced by `‹secret:NAME›` across the
+  whole intent, not only its text: the predicate's field description and
+  its value too, which is where a value is most literally the thing being
+  searched for. Only the structural keys are kept — the comparison
+  operator, the kind of unit wanted back, the kind of ordinal — so a field
+  added to the contract later is masked by default rather than forgotten.
+
+  A numeric secret is masked as well, and only on an exact match: a
+  one-time code arrives as a number, and a number has no text for a value
+  to hide inside, so `447213` masks while `4472130` and every ordinary
+  quantity are left alone.
+
+  This happens in one place for both grounding modes — local and remote —
+  so a value cannot escape through whichever mode a project runs.
+
+  The honest cost, because it is real: masking is by exact value. Where the
+  page rendered the same secret in another form — a different case, a
+  percent-encoded path, a value split by an invisible character — the mask
+  now lands on the intent alone, and the correspondence between what you
+  searched for and what the page shows is lost for that one case.
+  Grounding can get worse there. It is the same boundary already stated
+  about masking generally: the exact value is what is recognised, not the
+  secret "in any form".
+
+- Updated dependencies [32a495e]
+- Updated dependencies [c6b91bb]
+
+  - @unotest/protocol@0.34.0
+  - @unotest/viewer@0.34.0
+  - @unotest/grounder-client@0.34.0
+  - @unotest/core@0.34.0
+  - @unotest/dsl@0.34.0
+
+- Named late, and it should have been named in 0.33.0: on a box the pushed
+  suite is mounted **read-only**. Since run isolation (0.33.0) a run sees
+  its bundle at `/box/sources` and cannot write next to its own files —
+  a `prepare` script that seeded a database beside the fixtures, or a
+  helper that kept a scratch file under `unotest/.tmp`, now fails with
+  `EROFS` / `ENOENT` before a single scenario runs. The places a run may
+  write are `/tmp` (the container's own, gone with the run) and the run's
+  artifact directory under `UNOTEST_ARTIFACTS_ROOT`; `os.tmpdir()` in
+  Node and `$TMPDIR` in a shell both land in the former. Migration for a
+  suite that wrote beside its sources: pick the scratch directory by
+  whether `UNOTEST_ARTIFACTS_ROOT` is set — `unotest/.tmp` locally,
+  `/tmp/<suite>` on a box — and point the seed, the fixture and the
+  scenario at the same helper. Our own dogfood suite failed on exactly
+  this for a day.
+
 ## [0.33.0] - 2026-09-06
 
 ### Minor Changes

package/README.md

@@ -134,6 +134,56 @@ bundle, so if your config computes `schedules` from its environment, the
 box notices the difference and says so instead of silently arming
 another set.
 
+### Run on a box
+
+Three commands, no token to copy:
+
+```sh
+npx @unotest/web login        # a link and a code; approve in the browser
+npx @unotest/web box create   # rents a box named after the project, size S
+```
+
+`login` signs this machine in to unotest cloud — the account that rents
+boxes — and keeps the key in `~/.config/unotest/credentials.json`
+(mode 0600). `box create` creates the box with the environments the
+suite already runs locally (each `unotest/.env.<name>` and its
+`APP_BASE_URL`), asks for a top-up when the balance is short (it prints
+the Checkout link and waits for the payment), waits for the box, writes
+`UNOTEST_BOX_URL` to `unotest/.env` and the push and read tokens to
+`unotest/.secrets`, pushes the suite and prints the viewer's address.
+The tokens live thirty days; `bundle push` and `box …` re-mint them
+through the cloud when a box says they have expired, and `box access`
+does it on demand. `box status` and `box destroy` do what they say;
+`whoami` and `logout` complete the set. In CI, export
+`UNOTEST_CLOUD_TOKEN` instead of signing in.
+
+The **Picker** — grounding intent locators on the box's grounder — comes
+with the box today: it lists at €0.05–€0.13 an hour depending on size,
+and that is struck through, nothing is added to the bill. It is still
+never switched on quietly, because that will not always be true.
+`box create --picker` rents the box with it; without the flag a terminal
+is asked once, with the price read from the cloud's own list — the CLI
+has no price of its own — and the answer defaults to no. On a box you already have, `box picker on` and
+`box picker off` switch it without re-creating anything: `on` writes
+`UNOTEST_GROUNDER_MODE=remote` and `UNOTEST_GROUNDER_REMOTE_URL` to
+`unotest/.env` and `UNOTEST_GROUNDER_REMOTE_TOKEN` to `unotest/.secrets`,
+`off` clears the three again — unless they name a grounder that is not
+this box's, which is left alone and reported. `off` also revokes the
+box's Picker token, so a copy of it on another machine stops working
+too: the grounder refuses it once it has re-read the operator's
+revocation list — how often it does that is the operator's own setting. Either way the charge follows at the
+next hourly tick, because a started hour is charged at the rate it
+started with. `box status` says which state a box is in, and — while the
+Picker is on — which models the cloud grounds with: `Our GPU` or
+`External provider (Gemini)`. That is our grounder, not your
+`UNOTEST_GROUNDER_MODE`; a cloud that has not heard from its grounder
+prints nothing rather than a guess.
+
+An agent can drive all of it without a terminal: no prompt is shown
+without a TTY, and the exit codes say what happened — 75 the payment was
+not confirmed in time, 76 the terms of service need accepting (a person
+must, in a browser), 77 not signed in.
+
 ### Sending the suite to a box
 
 If your team runs a box (a machine that keeps the environments, the
@@ -247,11 +297,13 @@ 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.
+With a box rented through `box create`, the token is minted for you —
+`box access` re-mints it — and lives thirty days. On a box set up by
+hand you mint it for yourself on the box's guard, where it is shown once
+and can be revoked. Either way 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