clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/docs/architecture/04-configuration-reference.md

@@ -29,7 +29,7 @@ time, so all of them honour a mid-process env flip — the file's own NOTE besid
 `./driver.config.mjs` resolves to ONE cached module instance across the offline test fleet, so
 import-time captures silently pinned every test to the first test's env. What IS frozen at first import
 is the module-level declarations beside it — the consts `REGISTER_PROVIDER` and
-`UNREACHABLE_SENIOR_POLICY`, and `MODELS.azure`, a plain property reading `CLEAROTRON_AZURE_MODEL`.
+`UNREACHABLE_SENIOR_POLICY`.
 Because the driver runs as a systemd **oneshot** (a fresh process per activation), editing the
 deployment's `.env` takes effect on the next queue-triggered run with no deploy and no restart — that is the
 supported way to change caps and A/B toggles. One trap: `synthesis.model` reads
@@ -74,7 +74,7 @@ does after the stage's full retry ladder fails ([03 §5](03-run-lifecycle.md#5--
 | # | Stage | Model · effort | Timeout / stall | Gated output (file truth) | Fatality |
 |---|---|---|---|---|---|
 | 1 | `matter-frame` | opus · high | 300 / 300 | `matter-context.md` | fatal |
-| 2 | `prelim-variants` | opus · high | 600 / 450 | `variant-manifest.md` (+ `.json` sibling, strict-parsed) | fatal |
+| 2 | `clearance-variants` | opus · high | 600 / 450 | `variant-manifest.md` (+ `.json` sibling, strict-parsed) | fatal |
 | 3 | `blind-frame` | opus · high | 600 / 450 | `blind-frame-model.json` (strict-parsed; the prose twin was retired 2026-08-03 — nothing read it) | non-fatal (frame-diff skipped this run) |
 | 4 | `common-law` | haiku · low | 2250 / 1100 | `common-law-findings.md` (+ grid ledger, plugin-written) | fatal at fan-in |
 | 5 | `common-law-half` | per seat: `COMMON_LAW_SEAT_TIER` — halves `a`/`b` haiku · low; meaning seat `m` `CLEAROTRON_MEANING_SEAT_MODEL` \|\| haiku · low | 2250 / 1100 | `common-law-findings.half-{a,b,m}.md` (+ per-seat grid ledgers) | fatal at fan-in; one-half transient quarantine allowed |
@@ -130,17 +130,22 @@ through anything containing `/`):
 | gemini | `google/gemini-3.1-pro-preview` |
 | gemini-flash | `google/gemini-3-flash-preview` |
 | deepseek-v4-pro | `together/deepseek-ai/DeepSeek-V4-Pro` |
-| azure | `CLEAROTRON_AZURE_MODEL` (default `azure-openai/gpt-5.4`) |
+| azure | `azure-openai/gpt-5.4` |
 
 The bottom four are **legacy names that no stage declares and no engine can run** — they resolve at
 level 1 and then throw at level 2 (below). They are catalogue entries, not available tiers.
 
 **Level 2 — the active engine** maps aliases to the CLI's own model names. On `anthropic-agent`
-(`CLAUDE_MODEL` in `engine/anthropic-agent.mjs`): **opus and sonnet are pinned** to `claude-opus-5`
-and `claude-sonnet-5` so neither drifts with what the CLI currently calls "opus"/"sonnet"; `haiku`
-and `fable` pass through as aliases. A bare or dated Anthropic id (`claude-haiku-4-5-20251001`)
-still resolves to its family — that is a naming form of a model the CLI can run, not a substitution
-of a different one.
+(`CLAUDE_MODEL` in `engine/anthropic-agent.mjs`): `opus`, `sonnet`, `haiku` and `fable` pass through
+as aliases, so each tier follows the vendor's newest model; to hold one still, set
+`ANTHROPIC_DEFAULT_OPUS_MODEL` (or `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`,
+`ANTHROPIC_DEFAULT_FABLE_MODEL`).
+The catalog ids `anthropic/claude-opus-5` and `anthropic/claude-sonnet-5` are passed as those
+concrete models; `anthropic/claude-haiku-4-5` goes over as the `haiku` alias, so it follows the
+vendor the same way. A bare or dated Anthropic id (`claude-haiku-4-5-20251001`) still resolves to
+its family — that is a naming form of a model the CLI can run, not a substitution of a different
+one. Telemetry keeps the level-1 catalog id as the model asked for, and the attempt row records the
+id the program reports it served.
 
 **Anything else throws.** There is no regex fall-through to sonnet and no cross-provider
 substitution: the `gemini`/`gemini-flash`/`deepseek-v4-pro`/`azure` mappings are gone with the
@@ -170,8 +175,8 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 | Setting | Values | Effect |
 |---|---|---|
 | `CLEAROTRON_AI` | `anthropic-agent` (default) \| `openai-agent` | Compute engine (a registered provider adapter). `anthropic-agent` = `claude -p`; `openai-agent` = `codex exec` (both off-gateway, same normalized contract). An **unregistered** value — a typo, or the gateway-runtime adapter removed in the extraction — **fails loud**: no silent wrong-provider run. Production default is unchanged. |
-| `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`. **Fail-loud either way:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws, and never silently bills the subscription. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`). |
-| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH` | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a box that runs both sets both — they were one variable until it met a box needing two different paths. Give it an **absolute** path if the binary is not on `PATH` — stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. |
+| `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` \| `cloud` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback; **`cloud`** bills Claude per use through the reader's own cloud account, named by the Claude program's own switch — `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` or `CLAUDE_CODE_USE_BEDROCK`, or `ANTHROPIC_BASE_URL` alone for a gateway (see the credentials table below) — and deletes `ANTHROPIC_API_KEY` as subscription does. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`; `cloud` is refused. **Fail-loud, never a guess, never the subscription in its place:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws; on `anthropic-agent`, `cloud` with two switches on, or with none and no `ANTHROPIC_BASE_URL`, throws, and so does a switch left on under `subscription` or `api-key`, because the program bills that cloud whatever this says; a value that is none of the three throws on both engines. `clearotron start` and `clearotron doctor` report each refusal against the settings the services read, naming a value that is not a billing mode by its setting and never quoting it, and the runner refuses the search when it is ordered, before anything is spent. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`, and `cloud`, null when no cloud bills), and the attempt row also carries `providerReported`, the program's own word for who served the turn. |
+| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH`, then the copy Clearotron installed | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a machine that runs both sets both — they were one variable until it met a machine needing two different paths. A path set here must be **absolute**: stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. **Unset**, or set to the bare word `claude` / `codex` (which means the same), the engine uses the program on `PATH` when the machine has one, and otherwise the copy Clearotron installed in `~/.local/share/clearotron/engines`: `clearotron install` offers to put the chosen engine's program there (`@anthropic-ai/claude-code` or `@openai/codex`, this platform's build only), and `clearotron update` refreshes it. Nothing is bundled into the package. A value naming anything else is used as given and never falls back. `clearotron doctor` says which copy it found, and its version when npm installed that copy. |
 | `CLEAROTRON_OPENAI_AUTH_FILE` | `~/.codex/auth.json` | The credentials file seeded into the per-run `CODEX_HOME` under subscription billing. Was exempted from the August 2026 rename as an `openai-agent` internal rather than an install-surface name; the owner's 2026-09-04 ruling **reversed that exemption** and renamed the whole namespace, so it carries the house prefix like everything else. One spelling, no exceptions. |
 | `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
 | ↳ why they are three, and what the old measurement still says | superseded 2026-09-02, not erased | The three defaulted to `sol` alone on a MEASUREMENT, never a placeholder: on 2026-08-11/12, with `SWEEP=gpt-5.6-terra` / `CHEAP=gpt-5.6-luna`, every codex clearance died on structural-output gates — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` — over 2 scenarios × 3 stage families, **byte-identically on retry**, so no retry budget rescued it. That measurement stands for the code and the codex CLI **of that date**, and it is why the judgment tier keeps `sol`. Three weeks of stage-contract work and several codex minor versions sit between it and the 2026-09-02 ruling that split the three. **The symptom to match against this cause is unchanged**: those same three gates, as a fail row in`_driver/<stage>.jsonl`, inside the first few dispatches of a clearance and identical on every retry — a model incapable of a contract is not flaky at it. It reads as an engine bug when the only fault is this configuration. A cheap-tier experiment still belongs in the three constants in `driver/engine/openai-agent.mjs` where a reviewer sees it, not in an untraceable env line. |
@@ -196,8 +201,8 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_REPORTS_DIR` | **none — set it** | Publish pool (web-served). **No default since: unset refuses and names the variable.** It read`/srv/trademark-archive` — a deployed server's real archive — so a forgotten export published into somebody else's clearances, and two entry points already carried hand-written defences against exactly that (`bin/onboard.mjs`, `bin/example.mjs`). Same shape as `CLEAROTRON_DATABASE` and `scripts/purge-runs.mjs`: guessing wrong is expensive, so it does not guess. Read-only surfaces (flag snapshot, status page, MCP options) degrade to "no pool" instead of throwing; anything that writes refuses. `driver/production-pool-guard.mjs` still names `/srv/trademark-archive` on purpose — that constant is a fact about where the archive is, not a default. |
 | `CLEAROTRON_REPORTS_URL` | **none — set it** | Pool base URL used in notification links. No placeholder default: unset ⇒ the link is omitted and the runner logs `deployment config MISSING` at activation. It does not gate the queue (a missing hostname costs a link, not the deliverable), so treat that log line as the alarm. |
 | `CLEAROTRON_ACCESS_DOMAIN` | unset (note omitted) | Identity domain named in the delivery email's access note ("sign in with a `<domain>` account"). Unset ⇒ the note is omitted rather than naming the wrong domain. |
-| `CLEAROTRON_RUN_LOCK_DIR` | `<workspaceRoot>/prelim-run-locks` | Run-slot lock dir (turn locks under `…/turns`). |
-| `CLEAROTRON_OUTBOX_DIR` | `<workspaceRoot>/prelim-outbox` | Delivery outbox (`<runId>.pending` wake markers). |
+| `CLEAROTRON_RUN_LOCK_DIR` | `<workspaceRoot>/clearance-run-locks` | Run-slot lock dir (turn locks under `…/turns`). |
+| `CLEAROTRON_OUTBOX_DIR` | `<workspaceRoot>/clearance-outbox` | Delivery outbox (`<runId>.pending` wake markers). Renamed from `clearance-outbox`; when this variable is unset the old directory is still READ, so a box that never pinned it does not orphan markers it has already written. Writers use the new name only. |
 | `CLEAROTRON_OAUTH_BRIDGE` | module-relative `providers/oauth-mcp-bridge/bridge.mjs` | Case-law MCP bridge script. (Portable since the module-relative default; set explicitly only for a bridge outside the repo tree.) |
 | `CLEAROTRON_REGISTER_CALL_LOG` | `~/trademark/telemetry/register-calls.jsonl`, or the existing file wherever it already is | Billing-grade provider-call ledger, shared by whichever ONE register provider is wired — not a vendor artifact. Every read site derives the default from`homedir()` at call time (2026-07-19: two sites had hardcoded a literal home directory, splitting the ledger under any other service account — guarded by `test/deployment-hostnames.test.mjs`). |
 | `CLEAROTRON_REGISTER_RECORD_LOG` | **runtime-injected per run**: `<runDir>/_driver/register-record-bodies.jsonl` | Citation-fidelity log: the BODY of every fetched official record. ** moved it INTO the run** — created with the run, unioned into the run's`_records/`, archived and purged with it. There is no retention setting and no cleanup job, because it no longer grows on the box: held globally it reached 432 MB in 61 days on production and needed a rotation timer on every install. **Do not set this by hand** — a fixed value pins every run's bodies to one file and restores the problem. A box upgraded across still holds its old global file; nothing writes or reads it, the driver names it once per process on stderr, and archiving it is one`mv`. An empty log cannot read as verified: the run's successful `record_fetch` rows in the (still global) call ledger are compared against the assembled record set, and a gap is reported as a failure. |
@@ -207,6 +212,7 @@ deployment may override (verify live values per deployment).
 | `USPTO_LOCAL_DB` | **none — set it to use `uspto-local`** | The local USPTO index (`node:sqlite` + FTS5) that `bin/uspto-sync.mjs` builds and the free US register reads. Named in `.env.example`; this is the reference row. |
 | `CLEAROTRON_JX_SUBCLASS_DB` | unset ⇒ the lane refuses by name | Path to the built similar-group database the JX subclass lane reads, produced by `providers/jx-subclass/load-public.mjs` from the committed public tables. It names WHERE the table lives; what the table says is the build's. Absence is a refusal rather than an empty answer — a clearance that silently found no similar groups is indistinguishable from one where the file was missing. |
 | `CLEAROTRON_SUITE_TELEMETRY_DIR` | unset ⇒ the box's ledger | Redirects the provider telemetry ledger into a suite run's own temp root, so a suite never writes the box's ledger and never inherits it. Sits BELOW an explicitly-named ledger file: a test naming its own path is being deliberate, and this exists for the runs that name nothing. |
+| `CLEAROTRON_ENGINES_DIR` | unset ⇒ `~/.local/share/clearotron/engines` | The folder `clearotron install` installs the chosen engine's program into, `clearotron update` refreshes, and the engine resolver reads as its last step after the explicit setting and `PATH`: an npm project holding `node_modules/@anthropic-ai/claude-code` or `node_modules/@openai/codex`, where an empty directory means there is none. The test suite points it at an empty directory, so a test never reaches a program the developer's own setup installed. |
 | `FEEDBACK_GH_TOKEN` | unset ⇒ `gh`'s own auth | GitHub token for the unattended feedback minter (`scripts/feedback-mint.mjs`), for a service account with no `gh auth` login. Present ⇒ exported to `gh` as `GH_TOKEN` for that call only. A credential: it is not a placeholder value and must not be committed. |
 | `USPTO_API_KEY` | unset ⇒ the download path refuses | API key for the USPTO bulk download path in `bin/uspto-sync.mjs`. The INGEST path needs no key and says so; only the download half reads this. A credential. |
 
@@ -297,6 +303,8 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `CLEAROTRON_UPDATER_STAMP` | `_updater-identity.json` beside the update script, in the directory the updater runs from | The full path of the file in which the updater that deploys this box records which copy of itself ran. The updater writes it and deploy health reads it under this one name, so a box that moves the stamp sets it once for both. On a box with no updater unit, setting it says an updater exists elsewhere and is to be judged. Effect class `deployment`. |
 | `CLEAROTRON_CUT_REF` | `HEAD` | Which ref the cut decision reads the version from. **Read only by the release workflow, never set on a deployment.** The jobs that ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref and `HEAD` there is that ref rather than the branch they are deciding about. A job that asks the wrong subject gets a confident wrong answer. |
 | `CLEAROTRON_RELEASE_WAIT_MS` | 25 minutes | How long a requested cut waits for the version pull request to merge itself before giving up. **Read only by the release workflow.** A rehearsal sets it to `0` so the wiring is exercised without holding a runner. Giving up is a quiet success by design — the scheduled run underneath catches a cut whose wait expired — so this budget failing shows up as a slow job rather than a red one. |
+| `CLEAROTRON_CUT_REQUESTED` | unset (⇒ not dispatched) | Whether this release run was dispatched to cut. **Read only by the release workflow, never set on a deployment.** The workflow sets `true` on a dispatch that is not a rehearsal. Set, a wait that expires with no version published is a failure that names why; a push or the schedule leaves expiry a quiet success. Effect class `tuning`. |
+| `CLEAROTRON_CUT_PR` | unset | The number of the version pull request the same run opened. **Read only by the release workflow, never set on a deployment.** A failed wait reads why that pull request did not merge from it. Unset or not a whole number, a dispatched wait says it found no pull request to wait on. Effect class `tuning`. |
 | `ACTIONS_APPROVE_TOKEN` | unset | A GitHub token with Actions read and write, used to approve the version pull request's parked CI run so a cut does not wait for a person. **Read only by the release workflow, never set on a deployment.** The built-in token cannot approve a run — GitHub blocks self-approval — so this is a second, separate credential. Unset is the ordinary case and not an error: the script names the absent token and exits successfully, and the version run waits for a person as it did before. Actions write is broader than approval alone — it also dispatches workflows, cancels any run in the repository and deletes run logs. |
 | `CLEAROTRON_AGENT_MCP_URL` | unset (⇒ `null`) | The API-key MCP door advertised to a signed-in person. Null until that door is deployed, and the UI keeps its honest empty state rather than inventing a URL. |
 | `CLEAROTRON_AGENTS` | derived | Comma-separated agent ids for `scripts/purge-runs.mjs` to sweep. |
@@ -317,7 +325,14 @@ cannot be read as one list.
 
 | Var | Consumer |
 |---|---|
-| `ANTHROPIC_API_KEY` | Engine child env in `api-key` mode only (deleted in subscription mode). |
+| `ANTHROPIC_API_KEY` | Engine child env in `api-key` mode only (deleted in subscription and cloud modes). |
+| `CLAUDE_CODE_OAUTH_TOKEN` | The headless subscription sign-in's token, printed by `claude setup-token` on any machine that can sign in. Read by the Claude program itself: the engine's stage process inherits it untouched in every billing mode, which is how a browserless server authenticates the subscription lane. Setup names it as the token to paste. |
+| `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY` / `CLAUDE_CODE_USE_BEDROCK` | **Read by the Claude program**, which sends every turn to that cloud; `1`, `true`, `yes` or `on` switches one on. Clearotron reads them to name the cloud under `CLEAROTRON_AI_BILLING=cloud` and to refuse a switch left on under `subscription` or `api-key`. Under `CLEAROTRON_AI_BILLING=cloud`, `clearotron start --background` carries the switch that is on, and every setting in the five rows below that is set, the model pins included, into `~/.env` (a switch that is set and not on stays behind); under `subscription` or `api-key` it carries none. It adds only a line `~/.env` lacks, and names any of these on which that file and its own configuration differ. A missing switch is reported by `clearotron start` and `clearotron doctor`, and refuses a search when it is ordered. Doctor and setup's proof turn carry these and the five rows below from the settings file a search reads, which is the one at the old location while an install is still configured there (`CLOUD_SETTINGS` in `driver/engine/auth.mjs`). A value in the shell wins over the file's: setup's proof turn keeps a blank one, as a run does, where doctor passes over it and takes the file's. In setup, an answer given wins over both. A run takes the whole file. |
+| `ANTHROPIC_VERTEX_PROJECT_ID` / `CLOUD_ML_REGION` / `GOOGLE_APPLICATION_CREDENTIALS` | Vertex AI's project, region and service-account key, read by the Claude program. Without the key file it uses gcloud's sign-in. |
+| `ANTHROPIC_FOUNDRY_RESOURCE` / `ANTHROPIC_FOUNDRY_API_KEY` | The Foundry resource and its key, read by the Claude program. Without the key it uses the machine's Azure sign-in. |
+| `AWS_REGION` / `AWS_PROFILE` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` | Bedrock's region, optionally the AWS profile, and the standard AWS key variables (the session token only for temporary credentials), read by the Claude program. Without the keys it uses the machine's other AWS credentials, such as an instance role. |
+| `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` | A gateway in front of a cloud, and its token, read by the Claude program. With no cloud switch, `ANTHROPIC_BASE_URL` is the gateway form of `CLEAROTRON_AI_BILLING=cloud`; the gateway's credential must then be the token, because `ANTHROPIC_API_KEY` is deleted. |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `ANTHROPIC_DEFAULT_FABLE_MODEL` | The model each tier's alias resolves to, read by the Claude program: on Foundry, the deployment names; anywhere, a way to hold a tier still. Set the fable one to your Fable deployment's name if you set `CLEAROTRON_SYNTHESIS_MODEL=fable`; setup does not ask for it. |
 | `OPENAI_API_KEY` | **Read only to be DELETED.** The `openai-agent` adapter strips it from the `codex exec` environment under subscription billing, so an unrelated key exported on the box cannot spoil a clean subscription bill. It is never the api-key credential for this product — that is `CODEX_API_KEY`. Listed because a reader who has one set needs to know it is removed. |
 | `CORSEARCH_SESSION_KEY` | Register provider auth (session cookie). **Preflighted at run start — a missing credential fails fast before any model spend.** |
 | `CLARIVATE_API_KEY` / `CLARIVATE_API_BASE` | Clarivate adapter — on the engine path: `clarivate-server.mjs` in `gather-config.mjs`'s stage-grant table, plus driver-side `recordFetch` / `countHits` / `listRecords` / `executePlan`. `CLARIVATE_API_BASE` overrides the core's `DEFAULT_BASE`. |
@@ -341,7 +356,6 @@ cannot be read as one list.
 | `CLEAROTRON_SYNTHESIS_MODEL` | unset (⇒ opus) | Stage-specific synthesis model override — the live A/B toggle (e.g. `fable`). Alias must be registered in the engine map or the dispatch REFUSES by name (; it used to run sonnet silently and log the alias asked for). Read at module load; effective per fresh oneshot process. |
 | `CLEAROTRON_MEANING_SEAT_MODEL` | unset (⇒ `haiku`) | The common-law MEANING seat's model (`COMMON_LAW_SEAT_TIER[MEANING_SEAT]`, `stages.mjs`). The default moved sonnet → haiku on measured evidence: 2 attempts / 423 s against 1 attempt / 1674 s for the same outcome. **Margin:** sufficient at every load the test suite exercises, but at its densest scenario haiku used the last rung of the retry ladder — suspect this variable first if a dense matter's meaning seat goes terminal. Set`sonnet` to roll back with no code change. The thinking budget is NOT overridable (one variable, by design). |
 | `CLEAROTRON_STAGE_THINKING` | unset (⇒ each stage's declared tier) | Per-stage thinking-tier override, `<stage>=<tier>[,…]` (e.g. `register-digest=high`) — the A/B instrument, so a suite arm needs no code fork or redeploy between runs. Thinking only: models are deliberately not overridable here, so one arm can never move two variables. **The env override is a dev/test instrument**; a permanent change edits the tier in `stages.mjs` and ships. Unknown stage or tier **throws** — `effortFor()` falls back to `medium`, so a typo would otherwise run a stage at a tier nobody chose and every number measured against it would be wrong. Read per call, so an arm can flip mid-process. |
-| `CLEAROTRON_AZURE_MODEL` | `azure-openai/gpt-5.4` | Target of the `azure` alias — a legacy catalogue entry no engine can run (see model tiers above). |
 | `CLEAROTRON_DUMP_JSON` | unset | Dump each attempt's raw engine envelope to `_driver/<stage>.attempt<N>.rawjson.json`. Opt-in: any value except `0`/`off`/`false`/`no`/empty arms it. |
 | `CLEAROTRON_DISPATCH_RECORD` | **on** | Write the verbatim message of every stage dispatch to `_driver/<stage>.attempt<N>[.repair<M>].dispatch.txt`, with `{file, sha, bytes, chars, kind}` on the attempt row. **Default ON** — `0`/`off`/`false`/`no` disarms it. Unlike `CLEAROTRON_DUMP_JSON` beside it, this is opt-OUT: the question it answers ("was the model given this?") is asked *after* the run that raised it, so a flag someone had to remember would be off on exactly the run that needed it. The files carry the company's identity verbatim and are deliberately not in the artifact table. |
 | `CLEAROTRON_GATHER_SESSION_KEY` / `CLEAROTRON_GATHER_AGENT` / `CLEAROTRON_GATHER_SESSION_ID` | set per stage | Telemetry attribution into the provider-call ledger (set by the gather config; not operator-set). |
@@ -356,8 +370,12 @@ The settings below were deleted. Nothing in any environment set them, so each be
 had always resolved to. **They are listed because an operator whose `.env` still carries one needs to
 know it is inert** — an unread setting is indistinguishable from a setting that works.
 
+`CLEAROTRON_AZURE_MODEL` left for a different reason, on 2026-09-15: it retargeted the `azure` alias,
+which no stage names and no engine runs, so no run ever used its value.
+
 | Was | Now fixed at |
 |---|---|
+| `CLEAROTRON_AZURE_MODEL` | `azure-openai/gpt-5.4`, the target of the `azure` alias (see model tiers above) |
 | `CLEAROTRON_BAND_SHAPE_PART_CHARS` | 70000 characters per shape part |
 | `CLEAROTRON_DEDUP_WINDOW_HOURS` | 24 hours, and the window can no longer be disabled |
 | `CLEAROTRON_FETCH_MAX_CHARS` | 200000 characters per fetched page |

package/docs/architecture/05-config-governance.md

@@ -91,7 +91,7 @@ product doc.
 | **Job spec** (per matter): id, forwarder(+email/domain), markName/marks[], classes\|goods/use, ref, profileKey, projectKey, searchLevel/recipeKey, deliveryRoute, `customer`(+Unknown), deliverableSpec, commercialFlexibility, priorUse, dupOverride, deadline, brief | T1 | agent conversation → `start_run` MCP verb (ops token) → queue; validated by `enqueue-schema.mjs` | queue → run dir | LIVE (conversational; portal `run/plan`+`run` API exists) |
 | **Company profile** (17 keys — identity/rating/provenance: name, matchDomains, selfExclusionOwners, frameworkPath, workedExamplesPath, allowedRecipes, jxPolicy, runCaps, demoData (`true` marks the record as demo data; a real clearance is refused at the runner's admission wall); overlayable: platforms, defaultClasses, defaultJurisdictions, marketplaceDensity, delivery, riskAppetite, industry, defaultProduct) | T2 (staff) + T1 (a company's people edit its own via portal §C) | profile-service UI (staff, `/profiles/*`); the portal (own profile) | config store, git auto-commit | LIVE. Merge law: project **replaces** every overlayable key except `platforms`, which **unions** (the company's floor is never subtractable) |
 | **Project overlays** (8 overlayable keys) | T2 | profile-service UI | config store `profiles/projects/<cust>/` | LIVE. The project form deliberately withholds `defaultProduct` and both `delivery` sub-keys — for the first the sparse save path has no `""` ⇒ clear branch, so the control could only ever be turned on; for the second the engine replaces `delivery` wholesale, so a partial overlay would silently drop the company's other sub-keys. Both are company-level controls until the server side changes |
-| **Frameworks / skills** (risk-framework-<key>.md + .manifest.json, worked examples, SKILL.md) | T2 (senior-lawyer content) | git edits in the config store (deliberate — the prose deck is the rating authority) | config store `skills/prelim-search/` | LIVE via git; no UI by design |
+| **Frameworks / skills** (risk-framework-<key>.md + .manifest.json, worked examples, SKILL.md) | T2 (senior-lawyer content) | git edits in the config store (deliberate — the prose deck is the rating authority) | config store `skills/clearance-search/` | LIVE via git; no UI by design |
 | **Recipes / saved searches** (base level + component toggles + emailTable/defaultDeadlineDays/standingInstructions) | T2 | recipe-service UI | `<recipesDir>/<cust>/<slug>.json`, git | **DARK** — code complete, no unit deployed. A saved search is honoured wherever it resolves (the `CLEAROTRON_RECIPES_MODE` door was retired 2026-07-27) |
 | **Run curation** (archive folds, republish, index regen) | T2 | `pool-admin.mjs` CLI only | pool `archive-tags.json` | LIVE, CLI-only |
 | **Allowlist** (`{version, grants:[{email, customer}]}`) | T2 | git + PR on the `CLIENT_ACCESS_MAP` file | see §2 row 4 | LIVE, file-only; surfaced read-only at `admin.access` |
@@ -159,13 +159,19 @@ structural, or dev seam); [dev] = dev/test seam, never set in prod.
 ### 5.2 Engine & models — T3
 
 `CLEAROTRON_AI` (anthropic-agent | openai-agent; default anthropic-agent), `CLEAROTRON_AI_BILLING`
-(subscription|api-key), `CLEAROTRON_AI_BILLING` (subscription|api-key), `CLEAROTRON_CODEX_PATH`,
+(subscription|api-key|cloud; cloud is Claude only), `CLEAROTRON_CODEX_PATH`,
 `CLEAROTRON_OPENAI_AUTH_FILE`, `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` /
 `CLEAROTRON_OPENAI_MODEL_CHEAP` (all gpt-5.6-sol),
-`CLEAROTRON_CLAUDE_PATH` (claude), `CLEAROTRON_AZURE_MODEL`,
+`CLEAROTRON_CLAUDE_PATH` (claude on PATH, then the copy Clearotron installed),
 `CLEAROTRON_SYNTHESIS_MODEL` (opus), `CLEAROTRON_KNOCKOUT_MODEL` (opus),
 `CLEAROTRON_KNOCKOUT_PRESET` (pro-search), `CLEAROTRON_MAX_BUDGET_USD` (unset).
 
+The Claude program's own cloud settings — `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_VERTEX` and
+`CLAUDE_CODE_USE_BEDROCK`, each cloud's own settings, the gateway pair and the model pins — are the
+vendor's names, not this tier's; the configuration reference's credentials table lists them. Written out
+rather than as one wildcard: a guard reads these documents for the names they govern, and a trailing `*`
+matches nothing it can check, so a name hidden behind one reads as governed while being invisible.
+
 ### 5.3 Concurrency, admission, retries, walls — T3 (walls are load-bearing; change deliberately)
 
 `CLEAROTRON_MAX_CONCURRENT_RUNS` (2), `CLEAROTRON_GATHER_CONCURRENCY` (7), `CLEAROTRON_CARD_CONCURRENCY` (8),
@@ -472,6 +478,12 @@ It must be **asked for**: a real deployment behind its upstream still reports be
 blank value is not a declaration, and the doctor names this variable in its output when it obeys it. Set
 it in CI and nowhere else — on a deployed box it silences the one check that notices the box is stale.
 
+Engines folder: `CLEAROTRON_ENGINES_DIR` — where setup installs the chosen engine's program, where
+`clearotron update` refreshes it, and where the engine resolver in `driver/driver.config.mjs` looks for it
+after the explicit setting and `PATH`. Unset on a deployment, where it is
+`~/.local/share/clearotron/engines`. The suite runner points it at an empty directory, so a test never
+reaches a program the developer's own setup installed.
+
 > **Write every name out. No `*`, no `{A,B}`, no `/_SUFFIX`.** The enforcement test matches a name on
 > a word boundary, so shorthand documents a variable to a human and hides it from the guard. This row
 > is where that was found: `*_AUTH_DISABLED`, `*_DEV` and `CLEAROTRON_REPLAY_SNAPSHOT`/`_ROOTS` left five
@@ -483,11 +495,9 @@ it in CI and nowhere else — on a deployed box it silences the one check that n
 > see `providers/oauth-mcp-bridge/README.md`) were listed there for years and read by nothing, which
 > made a reader configure a variable and get no behaviour.
 >
-> `COURTLISTENER_TOKEN` is gone. The four`AZURE_OPENAI_*` names are **still there and stay**:
-> they are a reconstructed external contract, the file says so in place and tells a reader to verify
-> the spellings against the platform that consumes them. Naming a foreign contract is not the same
-> defect as inviting someone to set a variable this product reads — the rule above is about the
-> second.
+> Both are gone. The four `AZURE_OPENAI_*` names left `.env.example` on 2026-09-15: on a page that
+> explains paying for Claude through an Azure account, four Azure variables nothing in Clearotron reads
+> looked like that setup's settings, and they are not.
 
 `portal-ui/` has **zero** env config (no `VITE_*`, no `import.meta.env`) — the SPA talks to its
 origin; all portal config lives server-side in portal-service.
@@ -517,6 +527,11 @@ up is a quiet success by design and the scheduled run underneath catches what it
 is wrong shows up as a slow job rather than a red one — which is why it is written down rather than left
 to be inferred from a timeout.
 
+`CLEAROTRON_CUT_REQUESTED` and `CLEAROTRON_CUT_PR` — whether this run was dispatched to cut, and the
+version pull request it opened. The workflow sets both; nothing on a deployment reads either. Together they
+separate a run that set nothing in motion, whose expired wait stays a quiet success, from a dispatched cut
+that published nothing, which fails and names why the pull request did not merge.
+
 ## 6. Drift patterns — values that are mirrored by design
 
 Wherever one value must exist in more than one place, name every copy and rotate them in one

package/docs/architecture/05-customer-profiles.md

@@ -16,7 +16,7 @@ rating is refused by pattern guards and by stage-level firewalls.
 ## The bundle
 
 A company = one git-owned JSON file `profiles/<key>.json`, plus optionally: a prose context pack
-(`<key>.context.md`), a per-company rating framework pair in `skills/prelim-search/`
+(`<key>.context.md`), a per-company rating framework pair in `skills/clearance-search/`
 (`risk-framework-<key>.md` + its `.manifest.json`, plus worked examples), and per-engagement
 project overlays under `profiles/projects/<key>/`.
 
@@ -182,7 +182,7 @@ this source tree.
   `matchDomains` for forwarder-based fallback. A profile with empty `matchDomains` is reachable by
   profileKey only.
 - **Per-company framework** (optional; git-only, legal-team work — the UI cannot set it): add the
-  deck + manifest + worked examples under `skills/prelim-search/`, set the two paths in the profile
+  deck + manifest + worked examples under `skills/clearance-search/`, set the two paths in the profile
   JSON via git. Until then the company rates under the Generic default.
 - **Per-engagement overlay** (optional): `profiles/projects/<key>/<slug>.json` with the 8
   overlayable keys; intake stamps `job.projectKey` to select it.

package/docs/architecture/06-operations-runbook.md

@@ -112,7 +112,7 @@ and the environment file holding the secrets.
   `XDG_RUNTIME_DIR` must be set for `systemctl --user` to work from cron.
 - **Pin the agent id before upgrading an install made before 0.2.2.** The default agent id changed
   from `clawdi` to `localagent`, and that id is a path segment: runs live under
-  `<workspaceRoot>/workspace-<agent>/studio/prelim-search/`. An install that never set one starts
+  `<workspaceRoot>/workspace-<agent>/studio/clearance-search/`. An install that never set one starts
   reading an empty workspace, and empty reads as "no runs" rather than as an error. Set **both**
   variables in the environment file — the gather servers read their own:
 
@@ -129,7 +129,7 @@ and the environment file holding the secrets.
 
 | Surface | What it tells you |
 |---|---|
-| `systemctl --user status prelim-driver.{path,timer,service} prelim-outbox.{path,timer,service} profile-service` | Trigger health; remember "activating = draining" |
+| `systemctl --user status prelim-driver.{path,timer,service} clearance-outbox.{path,timer,service} profile-service` | Trigger health; remember "activating = draining" |
 | `journalctl --user -u prelim-driver.service -f` | Runner notes (stderr): claims, dedup parks, preflight failures, orphan reclaims |
 | Run dir `status.json` / `run.jsonl` | Per-run state + the append-only decision trace; grep keys: `axes`, `profile`, `verdict`, `escalation`, `postponed`, `delivered`, `profile-mismatch` |
 | `_driver/<stage>.jsonl` | Per-attempt telemetry: status, fail token, kill signals, wall, tokens |
@@ -173,7 +173,7 @@ survive until terminal state.
 | Run parked with `*.tainted-N` artifacts | Timeout-taint convergence loop ([07 §3](07-quality-and-audit.md#3--completed-coverage-honesty-in-code)) | Let it converge; repeated signature goes terminal honestly |
 | Chat failure ping never arrived for a failed run | By design: nothing here sends. The failure packet IS the notice, and an integrator consumes it | Check `_driver/failure.json` + the outbox lane (the guaranteed notice) |
 | Deploy refused because a run is in flight | The in-flight guard above | Wait for the run. A force-restart of the gateway is not the answer — that is for a wedged gateway |
-| Everything quiet after a deploy abort | Should not happen (EXIT trap restarts triggers) — if it does: `systemctl --user start prelim-driver.{path,timer} prelim-outbox.{path,timer}` and file it |
+| Everything quiet after a deploy abort | Should not happen (EXIT trap restarts triggers) — if it does: `systemctl --user start prelim-driver.{path,timer} clearance-outbox.{path,timer}` and file it |
 
 ## Selftest — retired
 

package/docs/architecture/08-development-guide.md

@@ -144,7 +144,7 @@ The reasoning layer dictates what it needs; a thin adapter supplies it. Concrete
    preflighted at run start. Add the id to `KNOWN_REGISTER_PROVIDERS` too, or the error message that
    tells an operator what to set will omit it. Selection is `CLEAROTRON_DATABASE` in every
    environment, production included; there is no committed default to flip.
-4. **Skill doc**: `skills/prelim-register/providers/<provider>.md` — the provider-specific craft
+4. **Skill doc**: `skills/clearance-register/providers/<provider>.md` — the provider-specific craft
    the register stages read.
 5. **The empirical verification checklist** — the real work is not code volume: operator
    vocabulary and composition semantics, pagination behaviour to `has_more:false`, status-enum
@@ -157,8 +157,8 @@ The reasoning layer dictates what it needs; a thin adapter supplies it. Concrete
 
 The methodology lives in the driver's `skills/` tree — 12 top-level directories, nearly all of it
 Markdown carrying **prose only**, no executable code. The machine-parsed
-exceptions are the four framework manifests (`skills/prelim-search/risk-framework*.manifest.json`); one
-further non-Markdown file rides along, `skills/prelim-search/templates/search-request-form.html`, named
+exceptions are the four framework manifests (`skills/clearance-search/risk-framework*.manifest.json`); one
+further non-Markdown file rides along, `skills/clearance-search/templates/search-request-form.html`, named
 only in `publish/index.mjs`.
 The engine reads skills **in place from the git-deployed driver tree**: `absolutizeSkillRefs`
 rewrites `skills/…` tokens to absolute paths and grants `--add-dir`. Code comments saying skills
@@ -168,8 +168,8 @@ What to know before editing:
 
 - **Which stage reads what** is dictated solely by each stage message's `reads([...])` in
   `stages.mjs` — read it there rather than trusting this summary. Broadly: matter-frame,
-  prelim-variants (+ `transliteration-scripts.md`), blind-frame, prelim-common-law (every grid seat),
-  prelim-register spine + `unit.md` *xor* `digest.md` (mode-routed — a unit must never read
+  clearance-variants (+ `transliteration-scripts.md`), blind-frame, clearance-common-law (every grid seat),
+  clearance-register spine + `unit.md` *xor* `digest.md` (mode-routed — a unit must never read
   digest doctrine and vice versa) + the active provider's `providers/<name>.md`,
   placement-inquiry, `phase2-execution.md` §skeptic (that one section only), frame-diff,
   synthesis (synthesis-rules + per-profile framework + worked examples + conditionally
@@ -186,7 +186,7 @@ What to know before editing:
 - Several skill files are **legacy and not stage-read** (email/Excel templates, the formatting
   reference). Verify a file appears in some stage's `reads([...])` before treating its claims as
   live; where a legacy file and the code disagree, the code and `stages.mjs` win.
-- The pharma module (`skills/prelim-search/field-doctrine-pharma.md`, loaded by a code predicate on
+- The pharma module (`skills/clearance-search/field-doctrine-pharma.md`, loaded by a code predicate on
   pharma-shaped matters) ships behind a named legal reviewer's sign-off — doctrine edits in
   regulated verticals go through the practitioner, not just review.
 

package/docs/configuration.md

@@ -95,7 +95,7 @@ A framework is two files that travel together:
 | `risk-framework.manifest.json` | A small sidecar carrying the framework's **vocabulary**: band labels, their severity order, the entity label, provenance. |
 
 The Generic default ships at
-[`driver/skills/prelim-search/risk-framework.md`](../driver/skills/prelim-search/risk-framework.md)
+[`driver/skills/clearance-search/risk-framework.md`](../driver/skills/clearance-search/risk-framework.md)
 with bands Very High · High · Moderate · Manageable.
 
 **Replace it with your own.** Write your rubric as prose, add a manifest naming your bands,
@@ -174,14 +174,14 @@ prints what they declare, and where the deck and the manifest disagree it names
 the deck did not do. It creates nothing, rates nothing and contacts nobody.
 
 ```
-clearotron framework skills/prelim-search/your-framework.md
+clearotron framework skills/clearance-search/your-framework.md
 ```
 
 ```
-Framework: skills/prelim-search/your-framework.md
-  deck      /srv/clearotron-config/skills/prelim-search/your-framework.md
+Framework: skills/clearance-search/your-framework.md
+  deck      /srv/clearotron-config/skills/clearance-search/your-framework.md
             read from the configured store
-  manifest  /srv/clearotron-config/skills/prelim-search/your-framework.manifest.json
+  manifest  /srv/clearotron-config/skills/clearance-search/your-framework.manifest.json
             read from the configured store
 
 It declares itself "Your firm's clearance risk framework" (your-firm-2026), a bands-shaped

package/docs/decisions/0003-credential-model.md

@@ -32,7 +32,7 @@ disclosure are both acceptable; degrading in silence is not. Which one applies i
 | Register | refuses at preflight, by name | An unconfigured register that answered "no conflicts found" is the most dangerous output this system can produce |
 | Case law (Full country search) | runs without the bridge, and the run's ledger records that the sweep did not dispatch | Access is free but auth breaks in practice. `driver/verify.mjs` plus `case-law-citations.json` stop any report claiming "no adverse case law" when nothing was read — the disclosure is the guard |
 | Native-script lane | degrades and says so | Reached only on CJK territories |
-| Research sweep (open web / marketplaces) | **on a Knockout search: degrades and says so.** On the three clearance searches: **refuses at preflight, by name** | acceptance 6, 2026-08-20. A knockout carries`registerProbe: true`, so its register half is a whole product without the sweep — refusing the screen threw away an answer the deployment could give. The three clearances carry `commonLawGrid: true` and their unregistered-use half is not severable, so nothing there degrades quietly into a clearance with a missing half. -6, 2026-08-20: that clearance failure MOVED to preflight — it used to happen at the common-law stage, after every register stage had been paid for. Same outcome, no spend.`preflightResearchCredential` gates on the component, never on the pipeline: `prelim-register-only` is a clearance carrying `commonLawGrid: false` and is not refused |
+| Research sweep (open web / marketplaces) | **on a Knockout search: degrades and says so.** On the three clearance searches: **refuses at preflight, by name** | acceptance 6, 2026-08-20. A knockout carries`registerProbe: true`, so its register half is a whole product without the sweep — refusing the screen threw away an answer the deployment could give. The three clearances carry `commonLawGrid: true` and their unregistered-use half is not severable, so nothing there degrades quietly into a clearance with a missing half. -6, 2026-08-20: that clearance failure MOVED to preflight — it used to happen at the common-law stage, after every register stage had been paid for. Same outcome, no spend.`preflightResearchCredential` gates on the component, never on the pipeline: `clearance-register-only` is a clearance carrying `commonLawGrid: false` and is not refused |
 
 ## Consequences
 

package/docs/writing-standard.md

@@ -83,3 +83,7 @@ their problem.
 `enforcement.md` lists the classes a CI check refuses in a diff. Tone is not one of them, and no word
 list will ever catch it: a reviewer reads the rendered page as someone who has never seen this product,
 against `writing-rules.md`, and asks what they would think each sentence means.
+
+A stylesheet that is inlined into a delivered document is delivered with it, comments included — the
+reader receives the file, so a class name in a CSS comment is engineering vocabulary on a page they can
+open, exactly as it would be in prose.

package/driver/CHANGELOG.md

@@ -1,5 +1,129 @@
 # clearotron-driver
 
+## 0.3.2-beta.9
+
+### Patch Changes
+
+- 09f51e0: Fixed: A country named in words now reaches its register, and naming one in words and by code no longer counts as two places.
+- 09f51e0: Fixed: A search that failed can be picked up again with its codename alone. The command the engine prints when a search stops no longer names a job file that is no longer on the machine.
+- 09f51e0: For operators: Resuming a failed search by its codename now works without the original job file, and refuses by name when the run's record is incomplete.
+- 09f51e0: Fixed: A knockout report no longer scrolls sideways on a phone when a finding cites a long web address.
+- 09f51e0: Fixed: a knockout report's Registers counted row reads "186 registers, on" the register service, without a list of territories folded under it.
+- 09f51e0: New: A knockout search now delivers the engine's own assessment and findings alongside the report, as a full clearance already did.
+- 09f51e0: Fixed: A report no longer says the local-language investigation did not run when the run's own record shows it did.
+- 09f51e0: Fixed: On a phone, the rights-holder panel now shows a scrollbar when its rows run past the right edge.
+  
+  Fixed: "Web and marketplace names" lists names again. Readings of what a mark means are carried by the connotation section, where they were already stated in full.
+- 09f51e0: Fixed: when a register reports only that it holds more than a figure, the knockout counts table and workbook show that figure, not "not available".
+- 09f51e0: Fixed: Preliminary searches on one register now report the registered marks the assessment found, instead of a register section left empty.
+  
+  Fixed: A search whose register assessment cannot be recorded now stops with an error instead of delivering a report silent on the register.
+- 09f51e0: Fixed: A report's section links now sit in the header and stay on screen while you read, instead of scrolling away.
+- 09f51e0: Fixed: A report no longer reads "Case-law research could not be completed for ." when the search covered a register that does not publish per-country records.
+- 09f51e0: New: A report states whether the local-language investigation ran at the depth configured for the matter.
+- 09f51e0: Fixed: On a knockout report, the risk band marker no longer overlaps the words above it.
+- 09f51e0: Fixed: A running search now reports the stage it is on, not the last one finished, so progress no longer appears to go backwards.
+- 09f51e0: Fixed: A knockout report no longer states, for each name, whether that name should proceed to a full clearance search. It reports what the screen found.
+- 09f51e0: New: A report table that continues past the right edge now shows a scrollbar, so it is clear there is more to see.
+- 09f51e0: Fixed: When a register search did not finish, the verdict's condition no longer names the engine's internal label for the unfinished part.
+- 09f51e0: New: a worldwide search names the register service that searches it, on the New clearance form and on the report's coverage line.
+- 09f51e0: Fixed: Worldwide searches on a register that keeps no record archive now show how many register records were read and in which countries.
+- 09f51e0: Fixed: Searches of a named company's own trademark portfolio now run on every register. On one register they were refused before the search was sent, and the report told the reader those holdings could not be reached.
+- 09f51e0: Fixed: After upgrading, existing companies, past clearances and queued searches stay visible, with no folder to rename and no company file to edit.
+  
+  Fixed: A company file that cannot be read no longer empties the company list; that company is named with the reason instead.
+- 09f51e0: Fixed: each finding's "Ask AI about this finding" button in a report now opens Ask AI, with that finding's number in the question.
+- 09f51e0: New: Searches no longer look up ordinary English words one letter away from the mark that sound different, such as CODE beside CORE.
+- 09f51e0: Before you upgrade: reports left waiting in the delivery folder's old name are found and sent again. Nothing needs moving, and none is sent twice.
+- 09f51e0: Fixed: The forward-decisions section of a clearance report is headed "What happens next", as the approved design heads it.
+- 09f51e0: New: A clearance report carries a section strip along the top, so a reader can jump to the findings, the next steps or what was searched.
+- 09f51e0: New: The new clearance form now offers every country a supported register can search, not a fixed list of 37.
+- 09f51e0: Fixed: The new clearance form no longer repeats in paragraphs what each product row and each place already say.
+- 09f51e0: Fixed: on a phone, the list of clearances made the whole page slide sideways instead of scrolling the table. The table now scrolls on its own and the page stays put.
+- 09f51e0: Fixed: on a narrow window the buttons at the end of each clearance row pushed the page sideways, and every date broke onto two lines. The buttons now fit the space they are given and the date stays on one line.
+- 09f51e0: Before you upgrade: the folder a finished report waits in while it is sent has been renamed. If you have never set that folder yourself, nothing needs moving. Reports already waiting in the old folder are still sent.
+- 09f51e0: Fixed: Knockout reports no longer print a caveat line under the register counts table.
+- 09f51e0: New: A knockout report carries a section strip along the top, so a reader can jump to the conflicts, the filings or the next steps.
+- 09f51e0: Fixed: A mark whose official record could not be retrieved is no longer listed as a condition on the verdict. The report still names it where the search's coverage is set out.
+- 09f51e0: Fixed: Installs inside WSL now show a second setup command, for an assistant running inside WSL as well as one on Windows.
+- 09f51e0: Fixed: a clearance report's "What was searched" section shows register totals, counts per country and a link to the audit workbook, as designed.
+
+## 0.3.2-beta.8
+
+### Patch Changes
+
+- d194d41: Fixed: A knockout search now covers the territories the form is showing you, rather than searching the whole world instead of them.
+  
+  Fixed: A new clearance recommends and preselects a search when the form is showing your company's own territories. It previously offered none and said no search was picked, beside a summary naming those same countries.
+- d194d41: Fixed: A report opened on a phone fits the screen instead of scrolling sideways.
+- d194d41: Fixed: A knockout search that is running says it usually takes 5 to 10 minutes. It previously showed 1.5 to 2.5 hours, which is how long a full clearance takes.
+- d194d41: Fixed: A running search says which step it is on, such as "Register sweeps", rather than "Register sweeps · 3 of 9". How many steps a search has varies with what it needs to do, so the number did not mean what it looked like.
+- d194d41: New: Each search in your list now says which of the four searches it was.
+- d194d41: Fixed: A new clearance now offers only the territories your register can search. Before, it offered countries your register cannot reach, and choosing one stopped the search from starting.
+  
+  Fixed: You can now remove one of your company's default territories on the clearance form. Before, if your register could not search one of them, nothing on that screen let you take it off and carry on.
+- d194d41: Fixed: A report now gives the specific reason each name was set aside. Before, every such name carried the same general sentence, and the reason the search actually recorded for it was not shown.
+- d194d41: Fixed: A search naming a territory your trademark register does not cover is now refused before it starts, and says which territory to remove. Before, the search ran and that territory was reported as not searched at the end.
+- d194d41: New: Pay for Claude through your own Google Cloud, Microsoft Azure or Amazon Bedrock account with `CLEAROTRON_AI_BILLING=cloud`. Tested on Microsoft Azure; Google Cloud and Amazon Bedrock use the Claude program's own settings.
+  
+  New: Each run records which cloud account paid for it, and `clearotron doctor` names the cloud account it charges.
+  
+  New: Setup asks how Claude is paid for, and for a cloud account asks which cloud and checks it with one turn.
+  
+  New: `clearotron start`, when no billing is set, names a cloud account for Claude beside a subscription and an API key.
+  
+  New: `clearotron start --background` carries the cloud account's settings to the background services.
+  
+  New: `clearotron doctor` says how the background services pay, and warns when your own configuration sets a different way of paying.
+  
+  New: Global config's Engine row names the cloud account that pays, and turns red, naming the setting to change, when searches would be refused.
+  
+  Fixed: An install that pays with an API key and runs as background services now hands the services its key. Before, every search stopped after it was ordered.
+  
+  Fixed: A subscription install signed in with a long-lived token from `claude setup-token` now hands that token to its background services.
+  
+  Fixed: `clearotron start` now reports a billing setting that would stop every search, such as an API key that is not set. `clearotron doctor` also checks the settings the background services read.
+  
+  For operators: `clearotron start --background` names each setting on which `~/.env` and Clearotron's settings disagree, such as a rotated key, without printing values. It adds only settings `~/.env` lacks and never replaces one, so change a setting in both files.
+  
+  Before you upgrade: A billing setting Clearotron does not recognise now stops a search before it starts, where it used to bill the subscription. Run `clearotron doctor` after upgrading.
+  
+  Before you upgrade: On a Claude install, a cloud's own switch left on, such as `CLAUDE_CODE_USE_FOUNDRY`, now stops a search unless `CLEAROTRON_AI_BILLING=cloud`.
+- d194d41: Fixed: Connect your AI now sits last in the sidebar, under Company settings. It used to sit second, directly under Home.
+- d194d41: Fixed: `clearotron doctor` and `clearotron start --background` look for Claude Code or the Codex CLI on the PATH the background services use. They used to say every search would be refused on a machine whose searches found the program and ran.
+- d194d41: Fixed: When a background service's unit and its settings file set the same value, `clearotron doctor` and `clearotron connect` take the file's, as systemd does.
+  
+  Fixed: `clearotron doctor` and `clearotron connect` read a doubled percent sign (`%%`) in a background service's unit as one, as systemd does.
+- d194d41: Fixed: When the background services found the reasoning program and this machine cannot, `clearotron doctor` now suggests installing it here with setup. It used to suggest installing it where the services could already see it.
+  
+  New: If a restart does not help the background services find the reasoning program, `clearotron doctor` says how to point them at it.
+- d194d41: New: `clearotron doctor --probe-engine` tries Claude with the cloud settings in Clearotron's settings file, the Amazon keys included, as a search does.
+- d194d41: Fixed: A search on a short or common word could return so many unrelated marks that one query filled most of the results. Any single query now contributes at most a fixed number of records. Anything beyond that is reported as a crowd, with its full count, rather than left out silently.
+- d194d41: Fixed: A report made before this summer, reopened today, states its conditions in the same words as a new one.
+- d194d41: New: The sign-in command from setup, `clearotron doctor` and a starting search names the copy setup installed, which is not on the PATH.
+- d194d41: New: Setup's test turn tries Claude with the cloud settings in Clearotron's settings file, the Amazon keys included, as a search does.
+- 6c7c7f1: For operators: the offline test suite runs in four parallel shards, so a change is checked in about a quarter of the time it used to take.
+- d194d41: Fixed: A search covering a very large number of register records could finish with no findings document at all. Those records are now accounted for in fixed batches instead of all at once. An interrupted attempt resumes from the records still outstanding, rather than starting again.
+- d194d41: New: A knockout report has an Export button, so anyone who opens the file can save it as a PDF.
+- d194d41: New: Claude steps run on the newest Opus and Sonnet as soon as they ship, unless a setting holds a tier at one model.
+- d194d41: New: Setup offers to install the reasoning program your engine uses. Before it asks, it says how much space the program takes and how to remove it.
+  
+  New: Setup asks which AI should run your searches, Claude or Codex, and says what it found on this computer.
+  
+  New: Claude Code or the Codex CLI already on the machine is still used first. `clearotron update` keeps the installed one current, and `clearotron doctor` says which copy runs, and its version when the program reports one.
+  
+  New: Outside Windows, in demo mode, `clearotron doctor` points to setup to install the reasoning program.
+  
+  New: When the reasoning program cannot be found, Global config's Engine row and the search screen name the setup command that installs it.
+- d194d41: New: Each report names the models that did the work, including those behind the Chinese, Japanese and Korean language steps.
+  
+  New: Through a cloud account, a report names the Claude model or its tier, never your organisation's own name for its deployment.
+- d194d41: New: When a cloud account refuses the credentials, setup, `clearotron doctor` and a starting search name that cloud and the settings to check.
+  
+  Fixed: When an API key is refused, setup, `clearotron doctor` and a starting search name the key to check, rather than asking for a sign-in.
+- d194d41: Fixed: When you have used all of today's searches, the screen names the person to ask for another. On an installation with no name set it read "ask your the operator contact to run this one for you".
+- d194d41: Fixed: A report's verdict now lists every condition it is conditional on. It used to name the first and close with "(and 2 more)". The rest sat in a separate list below it, so a reader could see that conditions existed without reading them.
+
 ## 0.3.2-beta.7
 
 ### Patch Changes

package/driver/README.md

@@ -89,7 +89,7 @@ kind of thing a module is before you open it.
 - The `anthropic-agent` engine shells `claude -p` per stage (stream-json, blocking to the final
   result); warm retries `--resume` the same session, fresh retries start clean — see
   `engine/CONTRACT.md §3` for the model-tier map and `§8` for runtime caveats.
-- Stage identity keys are `prelim-<slug>-<codename>-<stage>`; telemetry ledgers record every attempt.
+- Stage identity keys are `clearance-<slug>-<codename>-<stage>`; telemetry ledgers record every attempt.
 - A stage's output is judged by **file truth** (the validator on the written artifact), never by the
   engine's own success claim.
 - Retries never re-dispatch the same second an attempt failed: every retry waits
@@ -114,8 +114,8 @@ conformance → paid run).
 
 ## Single path
 
-prelim-search runs **only** via this driver — every intake path lands a job JSON in a queue and the
+clearance-search runs **only** via this driver — every intake path lands a job JSON in a queue and the
 driver does the rest. There is no legacy spawn path and no enable/dormant flag. (The old
 LLM-orchestrator `sessions_yield` WAIT/PROCEED/SUPPRESS machinery was stripped from
-`skills/prelim-search/phase2-execution.md` — only the historical removal note at its head remains;
+`skills/clearance-search/phase2-execution.md` — only the historical removal note at its head remains;
 the file is live methodology the stages read.)

package/driver/band-size.mjs

@@ -64,3 +64,62 @@ export function bandSizeForStage(stage, paths, io) {
   if (!BAND_READING_STAGES.has(stage)) return undefined;
   return bandSizeAtDispatch(paths, io);
 }
+
+// ── A STAGE'S TIME LIMIT IS DERIVED FROM WHAT IT IS HANDED, NEVER A FIXED CONSTANT ────────────────
+//
+// THE DEFECT. The two stages that read the register band carried per-stage constants — numbers chosen
+// once, against a band nobody recorded beside them. On a dense matter both died at their wall having
+// written nothing: the placement attempt at 2,765s against a 2,700s budget, the digest at 2,470s
+// against 2,400s. Both sat exactly AT the ceiling, so what ended them was the budget expiring rather
+// than any guard firing; the stall guards had half an hour of quiet to fire in and could not, because
+// tokens were still moving. Nothing malfunctioned. The number was simply sized for a different matter.
+//
+// THE TWO MEASUREMENTS THESE CONSTANTS ARE SET AGAINST, named here because a budget without the band
+// it was measured at is the thing being fixed:
+//   · 2026-09-16, the dense matter: an 8 MB merged band; the placement attempt needed more than 2,765s
+//     and was killed at 2,700s. The derived limit at that size must exceed what the attempt took.
+//   · Every ordinary matter before it: a band at or under REFERENCE_MB, where 2,700s was sufficient and
+//     is what those runs are verified at. At or below that size the derivation must return the base
+//     unchanged, so no existing run's budget moves and no archived verdict is re-decided.
+export const LIMIT_REFERENCE_MB = 2;
+export const LIMIT_GROWTH_PER_MB = 0.03;
+// The band size above which a stage is refused at dispatch rather than started. A limit past this is
+// not a budget, it is a prediction that the stage will die: the 177 MB band measured on an earlier
+// round would derive past an hour and a half, and starting it spends that hour and a half to arrive
+// where the refusal already is. Refusing NAMES the size, which is the finding; being killed does not.
+export const LIMIT_CEILING_SEC = 5400;
+
+/**
+ * The time limit for this dispatch, derived from the band it is handed. PURE.
+ *
+ * ABOVE THE REFERENCE SIZE ONLY. A band at or under the reference returns the stage's own base
+ * unchanged — that is what every run before this is verified at, and a derivation that moved those
+ * numbers would re-decide archived verdicts to fix a defect they never had.
+ *
+ * AN UNMEASURABLE BAND RETURNS THE BASE, and says so through `basis`. The alternatives are worse in
+ * both directions: guessing a bigger number spends a client's money on an input nobody measured, and
+ * guessing a smaller one kills a stage for a band that might have been ordinary. The base is what the
+ * run would have used anyway, so an absent measurement changes nothing rather than changing something
+ * arbitrary.
+ */
+export function derivedLimitSec(baseSec, bandSize) {
+  const base = Number.isFinite(baseSec) && baseSec > 0 ? baseSec : null;
+  if (base === null) return { sec: null, inputBytes: null, basis: "no base for this stage" };
+  const bytes = Number.isFinite(bandSize?.bytes) ? bandSize.bytes : null;
+  if (bytes === null) return { sec: base, inputBytes: null, basis: bandSize?.absent ? `band unmeasured: ${bandSize.absent}` : "no band for this stage" };
+  const mb = bytes / (1024 * 1024);
+  const over = Math.max(0, mb - LIMIT_REFERENCE_MB);
+  const sec = Math.round(base * (1 + LIMIT_GROWTH_PER_MB * over));
+  return { sec, inputBytes: bytes, basis: over > 0 ? `derived from ${mb.toFixed(1)} MB` : `at or under the ${LIMIT_REFERENCE_MB} MB reference` };
+}
+
+/** Is this derived limit past the point where starting the stage only buys a later kill? PURE. */
+export function limitExceedsCeiling(sec) {
+  return Number.isFinite(sec) && sec > LIMIT_CEILING_SEC;
+}
+
+/** The refusal a dispatch past the ceiling carries — it NAMES the size, which is the finding. PURE. */
+export function ceilingRefusal(stage, derived) {
+  const mb = Number.isFinite(derived?.inputBytes) ? (derived.inputBytes / (1024 * 1024)).toFixed(1) : "an unmeasured";
+  return `stage_input_over_ceiling:${stage} was handed a ${mb} MB band, which derives a ${derived?.sec}s limit against a ${LIMIT_CEILING_SEC}s ceiling — the stage is refused at dispatch rather than started, because a limit past the ceiling is a prediction that it will be killed and starting it spends the whole budget to arrive at the same place. The band size is the finding: a band this size is the defect, not the budget`;
+}