@unotest/web 0.42.0 → 0.43.1

package/CHANGELOG.md

@@ -1,5 +1,479 @@
 # Changelog
 
+## [0.43.1] - 2026-09-29
+
+### Patch Changes
+
+- 10e03e9: A debug command written a moment after another is no longer lost. The runner read `commands.jsonl` only on file-change events, and two appends a millisecond apart (`take_wheel`, then `abort_runtime`) could arrive as one event that fired before the second write landed: the second command waited, unread, until the file changed again. The paused run was never stopped, and it kept holding the project. The runner now keeps reading while the file grows, and it also checks the file size every 250 ms.
+- 75799c8: `abort_runtime` no longer answers ok for a stop the runner never took. It used to answer ok as soon as the command was written, so an agent was told a paused run had stopped while the run went on holding the project, and the next `run_test` could not start. It now answers ok once the runner has acted on the stop. A runner that is alive but does not act within ten seconds gets a `stop-not-accepted` error naming the state it is stuck in and what to do next.
+
+  What changes for you: `abort_runtime` may now answer `stop-not-accepted`
+  instead of `ok`; when it does, do what its `next` says.
+
+- fd8a8b6: `box runs`, `box run`, `box queue`, `box screenshot` and `bundle push --run` no longer need `--env` when the box serves a single environment: that one is used. With several, the refusal lists them and asks for `--env <project>/<environment>`; an explicit `--env` works as before. The MCP tools `box_runs`, `box_run`, `box_run_download`, `box_queue` and `box_screenshot` follow the same rule: `environment` may be left out on a box with one environment, and calls that pass it work unchanged.
+- cf3bed9: The page captured on a failure no longer holds what a `<noscript>` element contains. With JavaScript on, a browser keeps that content as plain text, so a value a page repeated there for readers without JavaScript — a secret field's included — reached the capture past the rule that hides secret fields. The element itself is kept, empty, so the page's structure is still visible.
+- 6d83fe9: After `run_test` pauses and auto-attaches, `explore_start` now opens the agent's own browser instead of recording into the run's (which answered every step with `not_your_turn`), and after `release_wheel` the agent can still take screenshots, assert and wait on the run's page.
+- 5433bab: Secret field values no longer leak into failures and replies. An
+  `assertValue` failure on a field marked as a credential (`type="password"`,
+  or `autocomplete` of `current-password`, `new-password` or `one-time-code`)
+  reports only the lengths of the two values, for example
+  `expected ‹hidden, 12 chars›, got ‹hidden, 32 chars›`. The same fields are
+  no longer read by the grounding capture, and show as `‹hidden, N chars›` in
+  a failure's page HTML and in a fill recorded by the viewer. MCP replies now
+  mask registered secrets as `‹secret:NAME›`, as the session journal already
+  did: text, structured content and tool error messages.
+
+  **What to check if you ran 0.43.0 or earlier.** The value of a password or
+  one-time-code field, and the value of a secret from `unotest/.secrets`, could
+  appear in plain text in MCP tool replies (for example `assert_text`,
+  `check_locator`, `assert_value` and the `get_failure_*` tools), in the text
+  of an `assertValue` failure, and in the `page.html` and `failure.json` saved
+  with a failed run. Search your MCP client's transcripts and your saved run
+  failures for your secrets and credentials; if one is there, rotate it.
+
+- 30e45a2: `take_wheel` and `release_wheel` now answer `ok` only once the paused run has
+  actually handed the wheel over; before, they answered as soon as the request
+  was written, and on a busy machine an agent could still click in a run it had
+  just given back. When the run does not apply it, the tools answer
+  `wheel-not-accepted` with what to do next. From the moment `release_wheel` is
+  called, the agent's page-changing steps answer `not_your_turn` until
+  `take_wheel` succeeds again.
+
+  What changes for you: an agent that waited for `ok` from `take_wheel` or
+  `release_wheel` may now get `wheel-not-accepted` instead, and should do what
+  its `next` says — the wheel may simply have gone back to the human, which
+  `inspect_runtime` shows in its `wheel` field. A run with no runner left now
+  answers `no-runner` instead of `ok`. Both are marked as errors, like
+  `abort_runtime`'s `stop-not-accepted`.
+
+- Updated dependencies [10e03e9]
+- Updated dependencies [5433bab]
+  - @unotest/core@0.43.1
+  - @unotest/grounder-client@0.43.1
+  - @unotest/dsl@0.43.1
+  - @unotest/protocol@0.43.1
+  - @unotest/viewer@0.43.1
+
+## [0.43.0] - 2026-09-27
+
+### Minor Changes
+
+- 6fc8140: A run on an environment no longer inherits a host from the base `.env`
+
+  Environment files layer: `unotest/.env` first, then the `unotest/.env.<name>`
+  overlay an active environment selects, the later file winning. That is the
+  right rule for a password or a user name, and the wrong one for a host. A
+  project whose base file points `API_BASE_CHAT` at production, and whose
+  `dev` overlay does not mention it, ran `--env dev` and sent its API calls to
+  production. Nothing in the output said so: the reply reported the `dev`
+  environment, and the requests went elsewhere.
+
+  From this release a variable that becomes a HOST has to come from the active
+  environment's overlay, or from the process environment. Three variables count
+  as hosts: `APP_BASE_URL`, which every relative `goto` resolves against; the
+  name passed as `apiCall(..., {base: "NAME"})`; and a variable used as the URL
+  in `goto(NAME)`. When the value still comes from the base file, the run is
+  refused before the browser starts, and `lint`, `run_test` and `explore_start`
+  refuse identically — with a message that names the variable, both files, and
+  the two ways forward. Every other variable layers exactly as before.
+
+  A base value that really is meant for every environment is declared once, in
+  `unotest.config.{js,mjs,ts}`:
+
+  ```js
+  export default { env: { shared: ["API_BASE_CHAT"] } };
+  ```
+
+  A value the process environment supplies — a shell variable, or the values a
+  box injects into a run — is never affected by this rule: it is a value
+  somebody stated for this run, not one silently inherited from a file the
+  overlay was supposed to replace.
+
+  Migration: a suite that runs with `--env <name>` and keeps its host in the
+  base file will now refuse, naming the variable. Either add the variable to
+  the overlay, which is what most projects meant, or list its name under
+  `env: { shared: [...] }`. A suite that never uses `--env` is unaffected.
+
+- 703185f: A run held at its failure has a screenshot, and the tools answer while it stands
+
+  A run paused on a failure left nothing on disk: no failure bundle, no
+  screenshot, and `get_failure_screenshot` replied "failure bundle not
+  found". The frame only appeared once the run was over — which is the one
+  moment it is least useful, because the browser has closed and the page
+  that broke is gone. Meanwhile the run was sitting right there, still
+  showing it.
+
+  The bundle is now written at the pause, from that page, so
+  `list_failures`, `get_failure_screenshot`, `get_failure_a11y` and the
+  rest answer on the first call. Each record carries `runState`: `paused`
+  while the run is still held — the browser shows the failure, and a
+  resumed run that fails again elsewhere re-takes the frame at the new
+  failure — then `finished` or `aborted` once the run is over. The frame
+  of a finished run stays the one taken at the failure: resuming continues
+  with the next statement, so the page moves on while the verdict does
+  not, and re-taking it at the end would show a page the failure never
+  happened on.
+
+  Also fixed: aborting a run while it was paused left its process alive
+  until the 30-minute inspection TTL expired. The run now ends when it is
+  aborted.
+
+- 7006895: Spending and deleting wait for a person
+
+  A key of a customer account — an agent's key, a signed-in machine's, and a CI
+  key issued before this release — can no longer rent a box, delete one or
+  switch the Picker on by itself. The cloud records what was asked for and answers with a
+  request instead; somebody approves or declines it in the cabinet, on the
+  Approvals tab, and only a signed-in browser can — not the key that asked, and
+  not the link in the email about it. Nothing is created and nothing is charged
+  until that happens.
+
+  For the CLI this is a wait, not a failure. `box create`, `box destroy` and
+  `box picker on` print where to answer and how long the request lives, then
+  carry on with what the cloud finally did and print exactly what they would
+  have printed anyway. Ten minutes with no answer is exit code 75 — nothing was
+  created and nothing was charged, run the command again. A decline is exit code 2. `--yes` does not skip it: the flag says the terminal need not ask, not that
+  the account need not.
+
+  Only the CI key of an operator account, one that unotest runs itself, acts
+  with nobody watching. A pipeline that rents or deletes boxes with a
+  customer's key now waits for somebody to press Approve, or has to rent its
+  box ahead of time.
+
+- 4582091: `box create` with a short balance points to the dashboard instead of starting a top-up
+
+  The cloud's API for agents has no top-up: credit is added by a person, by
+  card, under "Add credit" on the dashboard's home page. `box create` used to
+  start a payment from the terminal when the balance did not cover the first
+  hour, against an endpoint the service does not have, so on the real cloud it
+  failed with a 404.
+
+  Now it stops before renting anything and says what is short: the first hour's
+  price, the balance and the amount missing, and the dashboard page to add it
+  on. It exits 75 — nothing created, nothing charged — and is run again once the
+  credit is there. A key that cannot read the balance (the one `login` issues
+  cannot) gets the price and the page, and no invented shortfall. `--json`
+  prints `{ "needs": "top-up", "firstHourCents", "balanceCents",
+"missingCents", "currency", "url" }`, with `null` for a figure the key may not
+  read.
+
+  The `cloud_box_create` MCP tool answers the same case as
+  `{ state: "top-up-needed" }` with the same figures, instead of an error.
+
+  Migration: the `--topup <eur>` flag of `box create` is removed — top-up moved
+  to the dashboard. A script that passes it is refused with the usage and exit
+  2; drop the flag, and add credit on the dashboard's home page before renting.
+
+- dae29a2: The cloud account as commands and as MCP tools: `box list`, `box logs`, `approvals`, and nine `cloud_*` tools
+
+  An agent could read a box it had been pointed at and nothing more: which
+  boxes the account had, renting one and deleting one lived in a terminal, and
+  the list of boxes appeared only inside an error message. The account is now
+  reachable from both sides through one implementation, so a box reads the same
+  whether a person or an agent asked.
+
+  New commands:
+
+  - `box list` — every box on the account with its state, version and projects.
+    `--json` prints the same objects the `cloud_boxes_list` tool returns.
+  - `box logs [name] [--bootstrap|--updater]` — the end of a box's own log,
+    without logging in to it. A box sends it on its next five-minute check, so
+    the first call says it has been asked and when to run again, with exit 0.
+  - `approvals [id]` — what is waiting for a person on this account, or what
+    became of one request. Answering stays in the cabinet: a terminal holding
+    the key cannot approve its own request.
+
+  New MCP tools, outside the `core` toolset: `cloud_boxes_list`,
+  `cloud_box_status`, `cloud_box_create`, `cloud_box_destroy`,
+  `cloud_box_access`, `cloud_box_update`, `cloud_box_logs`, `cloud_balance`,
+  `cloud_approval_wait`. `cloud_box_access` writes the fresh pair into the
+  project the way `box access` does and answers with the names it wrote, never
+  the values. They answer states an agent can act on instead of
+  errors: `not-logged-in` with the command that fixes it, `approval-pending`
+  with the request to wait on, `insufficient-scope`, and `declined`,
+  `expired` or `still-waiting` from the wait.
+
+  While a rent or a delete waits for approval, the terminal now names it in the
+  words the cabinet and the email use — `Rent a box "acme", size s (€0.09 per
+hour)` — and prints a line when it is approved, not only when it is declined.
+  The sentences live in `@unotest/protocol` (`approvalActionText`,
+  `approvalPrice`), shared by every surface that shows a request.
+
+  `unotest-web --help` and `box --help` list the new commands, say which
+  commands wait for approval, and give one table of exit codes. `box <command>
+--help` now prints that command's own flags wherever `--help` sits on the
+  line, and `approvals` refuses an option it does not know with exit 2.
+
+  Compatibility: every call to the cloud now carries an `X-Unotest-Client`
+  header. The cloud refuses a call that would wait for approval when the header
+  is missing — an older CLI could not read the request it would be handed — with
+  `426 client-too-old` and a message to update. Update `@unotest/web` before
+  renting or deleting boxes with any key of a customer account, a CI key
+  included.
+
+- ba32d73: A config key the package does not know is refused, with the key you probably meant
+
+  `chanel: "chrome"` used to be dropped in silence: the run went ahead on
+  the default channel, printed `1 passed` and exited 0, so the one setting
+  you changed was the one setting that did not apply. Every section of
+  `unotest/unotest.config.*` is now checked by name, before the browser
+  starts:
+
+  ```
+  e2e: config validation failed:
+    unknown key "chanel" — did you mean "channel"?
+    retry: unknown key "cuont" — did you mean "count"?
+  ```
+
+  A key nothing is close to gets the other answer, because it usually
+  comes from a config written for a newer release than the installed
+  package:
+
+  ```
+    unknown key "telemetryEndpoint" — not a config key; check your
+    @unotest/web version if it comes from a newer release
+  ```
+
+  The config `unotest-web init` writes no longer offers a `viewer` section:
+  the viewer's port has always come from `UNOTEST_VIEWER_PORT`, and the
+  section was a suggestion the schema never had. A config generated by an
+  earlier version needs that block removed.
+
+  **Migration.** A config that carries a key this version does not know
+  now fails instead of running: fix the spelling, remove the key, or
+  install the release the key belongs to. Nothing else about the config
+  changes — every known field keeps its name, its default and its merge
+  behaviour, and a partially written section is still merged with the
+  defaults key by key.
+
+- fb12602: A step that takes minutes no longer disappears into the client's background
+
+  Waiting on a slow page — a chat answer that takes four minutes to come
+  back, a report that builds itself — used to be a call your agent never got
+  an answer to: MCP clients stop waiting at about two minutes and carry on,
+  and whatever the step replied after that was lost. The way round it was to
+  cut every wait to under a hundred seconds and repeat the step.
+
+  Now a step still running after 90 seconds answers `{ status: "accepted",
+taskId }` and keeps going: same timeout, same recording into the session.
+  Collect it with the new `explore_step_result({ taskId })` — `running`,
+  `done` with the reply the step would have given, or `failed`. A batch of
+  steps goes to the background as one task, for one id. The `durationMs` of
+  a collected step is the whole step, from its start — there is no threshold
+  to add back by hand.
+
+  While a step is out there, the browser context says so instead of being
+  damaged: another step, `explore_stop` and `close_context` answer `busy`
+  and name the task to wait for, and `explore_state` lists what is pending.
+
+- 82d5920: Signing in to a box with one environment opens its viewer straight away
+
+  A box configured with a single environment used to answer a sign-in with a
+  screen holding one option and a button. There was nothing to choose, so the
+  screen only stood between you and the viewer behind it.
+
+  Now that sign-in lands in the viewer. The **Environments** screen still
+  appears whenever it has something to say — more than one environment to pick
+  from, a box that has not been sent a test suite yet, or a licence in its
+  grace period, whose warning lives there.
+
+  So that skipping the screen does not hide what it carried, the viewer's
+  session menu now offers **box pages**: one link back to the box's own
+  pages — environments, read tokens, and administration for those who have
+  it. It appears when the box tells the viewer where they are, so a viewer
+  and a box on different versions simply do without it.
+
+- 3aee366: take_wheel now points the session at the run it takes the wheel of
+
+  An agent debugging a paused run would call `take_wheel`, take a
+  screenshot, and get a picture of a completely different stand — whatever
+  page the session had been recording on before. Nothing was wrong with the
+  screenshot: the wheel only ever took the control token, while the browser
+  stayed where it was, and the reply said `ok` either way.
+
+  `take_wheel` now also attaches this session to the run's browser, so the
+  next screenshot, snapshot or step reads the page being debugged. Every
+  `explore_step` reply carries `context` — `{kind: "run", runtimeId}` or
+  `{kind: "own"}` — so the source of a frame is stated rather than guessed.
+  A session has exactly one browser: `take_wheel` and
+  `attach_debug_session` point it at a run, `explore_start` and
+  `new_context` at your own, and `explorationId` chooses recording and
+  where a file is filed, never which browser a step runs on.
+  `release_wheel` hands the token back and deliberately leaves the browser
+  on the run.
+
+  Behaviour change for anything parsing the reply: `take_wheel` no longer
+  always answers `ok`. When it cannot join the browser it answers
+  `recording_open` (a live recording would be dropped — nothing is changed,
+  not even the wheel), `no_browser` (the run has not published one yet) or
+  `no_page`, each naming what to do next.
+
+- 9034092: Opening a box's viewer while a suite is being installed no longer looks like a failure
+
+  Sending a new suite to a box replaces that environment's viewer, and for the
+  second or two that takes, anyone holding the page open got a bare `502` — the
+  status that tells a browser nothing and tells a script the box is broken.
+
+  The box now says, while it is happening, that it is replacing that viewer. A
+  browser gets a short page that comes back by itself once the new viewer
+  answers; an agent reading the box with a token gets `503` with `Retry-After`
+  and `unavailable`, which is the box's existing word for "wait and ask again".
+
+  A viewer that stopped for any other reason answers the same way but promises
+  nothing, and the page does not reload itself: nobody is bringing it back, and
+  saying otherwise would be worse than saying nothing.
+
+### Patch Changes
+
+- b41b02e: A cloud that will not show the price list is quoted as such, not as free
+
+  `box create` and `box picker on` quote the hourly price inside the
+  question they ask. When the cloud refused the price list, the question was
+  asked with no price in it at all — and silence there reads as "this is
+  free", with no way for the reader to learn that a price exists and they
+  were not shown it.
+
+  A refusal for want of a permission now says so: `price not visible to this
+key: it needs billing:read`. On a current cloud the list is under `read`,
+  which every key from `login` carries — so this is what an OLDER cloud says
+  to a newer client, which is exactly when a client must not go quiet about
+  money. Every other reason stays silent, because a cloud older still has no
+  price list at all and a command must not fail for want of a courtesy.
+
+- 3e7e3fc: API keys carry permissions
+
+  A key used to be all or nothing: any live key could do everything the API
+  offers. Now every key carries a list of permissions — see the boxes, manage
+  them, read the balance — and every route states the one it needs. A key
+  without it gets `insufficient-scope`, which is a 403 and not a 401: the
+  credential is good, so signing in again would change nothing.
+
+  Where the list comes from depends on the key. In the cabinet you tick the
+  permissions when issuing a key for an agent. Signing a machine in asks for
+  enough to see your boxes and work with them, never your money, and the
+  approval page in the browser lets you narrow that before you approve — the
+  key then has exactly what was left ticked. `login` and `whoami` print what
+  the key may do.
+
+  Keys that already exist keep the permissions they had, with one exception:
+  spending money and deleting with nobody watching. Only the CI key of an
+  operator account, one that unotest runs itself, may do that. A CI key a
+  customer holds from before this release works like an agent's key: renting,
+  deleting and switching the Picker on wait for a person to approve.
+
+  One visible change for a key that cannot read the balance: `whoami` says so
+  on the balance line instead of failing, and signing in with such a key is
+  still recognised as being signed in.
+
+- 8353232: A rental the account cannot pay is refused before anybody is asked to approve it
+
+  A key that may not spend by itself used to get an approval request for a box
+  even when the balance could not cover the first hour: a person was asked to
+  approve it, and the rental then failed at their yes. The money is now checked
+  first, and such a create is answered `402 insufficient-balance` with nothing
+  recorded and nobody written to. The check at approval stays — a balance can
+  move while a request waits — and a request that fails there says so in words:
+  the price of the hour and where to add credit.
+
+  Every `insufficient-balance` carries `topupUrl`, the dashboard page where a
+  person adds credit. A key that may read the account's money also gets
+  `firstHourCents`, `balanceCents`, `missingCents` and `currency`; any other
+  key gets no figures.
+
+  `box create` prints the cloud's own figures and link when the refusal carries
+  them, instead of counting them again.
+
+- 2006bf9: A refused config says which field is wrong, and `channel` takes the same words everywhere
+
+  Any bad value in `unotest/unotest.config.mjs` used to come back as one
+  line — `config validation failed` — with no field, no value and no list of
+  what would have been accepted, though all three were known. Now the
+  refusal names them:
+
+  ```
+  config validation failed:
+    channel: expected one of "chrome" / "msedge" / "chrome-beta" / "chromium" / "bundled" / null, got "bundeld"
+    defaultTimeoutMs: expected number, got string
+  ```
+
+  And `channel: "bundled"` is accepted. `UNOTEST_BROWSER_CHANNEL` has always
+  taken that word — the `.env` template says the variable merely overrides
+  `channel` — while the config refused it. Both inputs now share one
+  vocabulary, and `bundled` means what it has always meant: Playwright's own
+  Chromium, the default.
+
+- e7cdab7: An empty id is refused instead of quietly changing what a tool does
+
+  `explore_step` and `explore_steps` treated `explorationId: ""` as "run
+  this without recording": the step went through, the reply said it had
+  succeeded, and nothing reached the session log. The agent found out at
+  `explore_stop`, with an empty recording and the work already done. The
+  same held for `explore_record`, and for `runtimeId: ""` in the debugger
+  tools, where an empty value silently meant "the session you attached to".
+
+  An empty id is now an input error naming the field, exactly as the
+  neighbouring tools have always answered. Leaving the key out is still how
+  you ask for the ad-hoc mode — absence is the mode, emptiness is a typo.
+
+- a3f89ee: The MCP server reports the version it actually is
+
+  `initialize` answered `serverInfo` with a hard-coded `0.1.0` whatever
+  version of the package was running, while `--version` printed the real
+  number. An editor showed the wrong version in its server list, and nobody
+  checking a session could tell a server started from npm apart from one
+  started out of a working copy.
+
+  Both surfaces now read the package's own manifest through one helper, so
+  they cannot drift apart again. A manifest that cannot be read is an error
+  naming the fault, not a silent `0.0.0` — an invented version reads as a
+  real answer in a protocol reply and in a support transcript.
+
+- f1f3fb1: Existing boxes install the five-minute update check themselves, and report a finished update in the tick that applied it
+
+  A box rented before the five-minute check existed only had the hourly timer:
+  pressing **Update** in the cabinet could take up to an hour and a half to
+  reach it. The updater now installs that pair of systemd units itself when the
+  box does not have them — exactly those two, only when the file is absent, and
+  never replacing a unit an operator edited.
+
+  A finished update is also reported in the tick that applied it, instead of in
+  the next one, so the cabinet card and `box status` stop showing "updating" for
+  a box that is already done.
+
+  **Both start working with the update after this one.** The move onto this
+  version is still carried out by the updater a box runs today: it arrives on
+  the hourly timer — up to an hour and a half — and that first "applied" still
+  comes with the next hourly tick. From there on the new updater is in charge,
+  a pressed **Update** lands within minutes, and the cabinet shows it as done as
+  soon as it is.
+
+- 74a1f9d: The viewer finishes writing its run index before it exits
+
+  On boot, and whenever a run finishes or the environment switches, the viewer
+  rebuilds the derived index it serves history from. Those writes are
+  deliberately not waited for while the server runs — a history months deep
+  must not hold the UI back — but they were not waited for on the way down
+  either. Stopping the viewer returned while files were still landing under the
+  run directory: a directory the caller believed had been released kept growing
+  for a fraction of a second, and anything that removed or archived it right
+  after the viewer stopped could fail or capture a half-written index.
+
+  Shutdown now waits for the index writes that are still in flight, so a
+  stopped viewer is a viewer that has finished writing. A rebuild that takes
+  longer makes the stop take longer, which is the honest cost of not leaving
+  half a file behind.
+
+- Updated dependencies [6fc8140]
+- Updated dependencies [4582091]
+- Updated dependencies [dae29a2]
+- Updated dependencies [82d5920]
+- Updated dependencies [74a1f9d]
+  - @unotest/core@0.43.0
+  - @unotest/protocol@0.43.0
+  - @unotest/viewer@0.43.0
+  - @unotest/dsl@0.43.0
+  - @unotest/grounder-client@0.43.0
+
 ## [0.42.0] - 2026-09-24
 
 ### Minor Changes
@@ -818,7 +1292,7 @@ picker on` fetches this project's own access and writes the three grounder
 
   That screen named one command:
 
-            npx @unotest/web bundle push --run --env ENVIRONMENT
+                npx @unotest/web bundle push --run --env ENVIRONMENT
 
   In a project that has just been created, the command refuses with `no box
 address` before it does anything: the project holds neither the box's address
@@ -827,8 +1301,8 @@ address` before it does anything: the project holds neither the box's address
 
   The screen now names both steps, in the order they have to happen:
 
-            npx @unotest/web box access larch
-            npx @unotest/web bundle push --run --env ENVIRONMENT
+                npx @unotest/web box access larch
+                npx @unotest/web bundle push --run --env ENVIRONMENT
 
   The box's own name is filled in when its licence carries one. `box access`
   with no name refuses, and its refusal offers to create a box — to somebody who

package/README.md

@@ -152,15 +152,47 @@ npx @unotest/web box create   # rents a box named after the project, size S
 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
+`APP_BASE_URL`), 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.
+does it on demand. `box list` shows every box on the account, `box status`
+one of them, and `box logs` the end of a box's own log without logging in to
+it; `box destroy` does what it says, and `whoami` and `logout` complete the
+set. In CI, export `UNOTEST_CLOUD_TOKEN` instead of signing in.
+
+Credit is added in the cabinet, by card, under "Add credit" on its home page
+— never from the terminal. When the balance does not cover a new box's first
+hour, `box create` says how much is missing (as far as the key may read the
+balance) and where to add it, and exits 75 with nothing created and nothing
+charged; run it again once the credit is there.
+
+Anything that spends money or cannot be undone — creating a box, deleting
+one, switching the Picker on — **waits for a person** unless the key is a CI
+key. The CLI prints where to approve it and how long the request lives, waits
+there, and then carries on exactly as if the call had gone straight through.
+Nobody answers in ten minutes: exit code 75, nothing created and nothing
+charged, run the command again. Somebody declines: exit code 2. `--yes` does
+not change any of this — the flag says the terminal need not ask, not that
+the account need not.
+`approvals` lists what is waiting, and `approvals <id>` says what became of
+one.
+
+An agent does the same through the MCP server's `cloud_*` tools — listing,
+renting, deleting, logs, the balance — with the same key and the same rules:
+a rent or a delete comes back as a request to wait on, and
+`cloud_approval_wait` waits for the person's answer.
+
+A key carries **permissions**. `login` asks for enough to see the
+account's boxes and work with them, never its money, and the approval
+page in the browser is where you can narrow that further; `login` and
+`whoami` print what the key ended up with. A key that may not read the
+balance is still a working key — `whoami` says the balance is not
+visible to it instead of failing — and a call it may not make comes
+back as `insufficient-scope`, which no amount of signing in again will
+change. Keys for an agent are issued in the cabinet, with the
+permissions ticked there.
 
 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,