clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/docs/SECURITY-OWASP.md

@@ -0,0 +1,298 @@
+# Security mapping: OWASP risks for AI applications
+
+*Each risk on OWASP's two lists for AI systems, what Clearotron does about it, and the file on `main`
+where that lives. Where nothing does, the row says so and why.*
+
+The two lists are the [OWASP Top 10 for LLM Applications 2025](https://genai.owasp.org/llm-top-10/) and
+the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/).
+Who may see which runs, and how a key is checked, is stated once in [SECURITY.md](SECURITY.md). This page
+links there rather than repeating it.
+
+## How a clearance uses AI
+
+A clearance runs as a series of stages. For each stage the driver, which is ordinary code, starts one AI
+program: Anthropic's Claude Code or OpenAI's Codex. The stage gets a written task, the tools named for
+that stage, and its run folder. Code checks every file a stage writes before any other stage reads it.
+The register searches are fixed in a plan before the register stages run, and code runs them. Code also
+renders the report, from the checked files.
+
+## OWASP Top 10 for LLM Applications 2025
+
+### LLM01:2025 Prompt Injection
+
+**Here.** Stages read web pages, marketplace listings and register records, and any of them can carry
+text written to steer the model.
+
+**What Clearotron does.** Each stage's tools are granted by name. The case-law stage is the exception: it is granted every tool its two case-law services offer. A tool outside that
+grant that needs permission is refused. A Claude stage is offered no tool that runs a command. A Codex stage keeps its shell inside Codex's own sandbox, and Codex approves tool
+calls only for the tool servers Clearotron starts for that stage. The AI program starts with a named list
+of settings rather than the install's settings file, so the key that signs access keys is not in it.
+Codex's page-fetching tool refuses loopback, private, link-local and cloud-metadata addresses. It checks
+the address a name resolves to, and checks again on every redirect.
+
+**Where.** `driver/engine/mcp/gather-config.mjs` (the tools each stage holds),
+`driver/engine/anthropic-agent.mjs` (`COMMAND_TOOLS`), `driver/engine/mcp/codex-config.mjs`,
+`driver/engine/engine-env.mjs`, `driver/engine/mcp/public-fetch.mjs`.
+
+**Not covered.** Content from the web is not marked as untrusted in the text a stage reads. That text is
+what the engine reasons from, so changing it is a design decision of its own.
+
+### LLM02:2025 Sensitive Information Disclosure
+
+**Here.** A report, the portal or a connected assistant shows one company's clearances to another, or
+shows the engine's internals to a company's people.
+
+**What Clearotron does.** Every read passes one authorization check, and a person sees only what their
+grant names. A key bound to one run reads that run and writes nothing. The copy of a report a company
+receives drops the staff-only notes. No real company's data is in this repository; run data lives
+in folders the operator owns. CI scans the tree and the built bundle for secrets.
+
+**Where.** [SECURITY.md](SECURITY.md) (the access model), `shared/scope.mjs`, `driver/portal-report.mjs`,
+`.gitleaks.toml`, `.github/workflows/ci.yml`.
+
+**Not covered.** A company's clearances are kept until the operator deletes them: Clearotron sets no
+retention period, because how long they are held is the operator's policy.
+
+### LLM03:2025 Supply Chain
+
+**Here.** A compromised npm package, GitHub Action or engine program.
+
+**What Clearotron does.** Dependabot updates the npm packages and the GitHub Actions. Each release is
+published to npm through trusted publishing, with provenance that ties the package to the commit and the
+build that produced it. A stable release is not published while a code-scanning alert is open. Setup
+installs, and `clearotron doctor` accepts, only an engine program at or above the version this release
+needs.
+
+**Where.** `.github/dependabot.yml`, `.github/workflows/release.yml`,
+`scripts/release-code-scanning-check.mjs`, `driver/driver.config.mjs` (`ENGINE_BINARIES`, each program's
+`floor`).
+
+### LLM04:2025 Data and Model Poisoning
+
+**Here.** Tampering with what the model learns from, so that it concludes wrongly.
+
+**What Clearotron does.** Clearotron trains and fine-tunes no model. The instructions every stage reads
+are versioned in this repository. On the Claude engine a check refuses any write by a stage into those
+instructions, into the company profiles, or into the run's own control folder.
+
+**Where.** `driver/skills/` (the instructions), `driver/engine/deny-authority-write.mjs`,
+`driver/authority-trees.mjs`.
+
+**Not covered.** Codex has no such check. A Codex stage can write anywhere in its run folder, the control
+folder included, because Codex offers no hook at the moment of a write.
+
+### LLM05:2025 Improper Output Handling
+
+**Here.** Model output passed on to something that runs or renders it unchecked.
+
+**What Clearotron does.** A stage's output is a file, and code checks it against that stage's contract
+before anything uses it. A file that fails is retried or fails the stage; it is never passed on. The
+report is rendered by code from checked files, and no file a stage writes runs on the install's machine.
+The common-law search asks the research service to run a search program, on that service's own servers.
+
+**Where.** `driver/gateway.mjs` (`runStage`), `driver/stages.mjs` (each stage's contract),
+`driver/publish/`.
+
+### LLM06:2025 Excessive Agency
+
+**Here.** A stage that can do more than its task needs: run commands, spend, write where it should not.
+
+**What Clearotron does.** Tools are granted per stage, by name. The case-law stage is the exception: it is granted every tool its two case-law services offer. A Claude
+stage is offered no command tool.
+Register searches beyond the fixed plan go through a proposal that code checks and runs. A key issued for
+automation can be limited to named actions. A what-if requested by a company's people is queued for a
+separate process rather than run by the door that received it.
+
+**Where.** `driver/engine/mcp/gather-config.mjs`, `driver/engine/anthropic-agent.mjs`,
+`driver/engine/mcp/supplemental.mjs`, `shared/scope.mjs`, `driver/whatif-worker.mjs`.
+
+**Not covered.** As ASI02: the Claude program also offers a stage built-in tools that act without asking.
+
+### LLM07:2025 System Prompt Leakage
+
+**Here.** The instructions given to the model leak, and with them anything secret they hold.
+
+**What Clearotron does.** The instructions are published in this repository and hold no credential.
+Credentials reach the tool servers through their environment, never through text a model reads.
+
+**Where.** `driver/skills/`, `driver/engine/engine-env.mjs`.
+
+### LLM08:2025 Vector and Embedding Weaknesses
+
+**Not applicable.** Clearotron keeps no vector store and computes no embeddings. The one search over
+finished runs is a word search.
+
+**Where.** `mcp-server/lib/lexsearch.mjs`.
+
+### LLM09:2025 Misinformation
+
+**Here.** A report states a conflict that is not there, or misses one that is.
+
+**What Clearotron does.** Register counts come from the register, never from the model, and a register
+finding names the register record it rests on. A search that could not run is listed in the report as a gap,
+never reported as a clean result. Before a report is published, separate stages argue against its
+conclusions.
+
+**Where.** `driver/register-plan.mjs`, `providers/_shared/execute-plan.mjs`, `driver/stages.mjs`,
+[architecture/07-quality-and-audit.md](architecture/07-quality-and-audit.md).
+
+### LLM10:2025 Unbounded Consumption
+
+**Here.** A run that consumes model time or money without limit.
+
+**What Clearotron does.** Each stage runs under a stall watchdog and a hard time limit, and a failing
+stage stops retrying once a retry would repeat the same failure. An install runs a set number of
+clearances at a time. The connector doors limit requests per identity.
+
+**Where.** `driver/engine/common.mjs`, `driver/engine/anthropic-agent.mjs`, `driver/gateway.mjs`,
+`mcp-server/lib/http-handler.mjs`.
+
+**Not covered.** There is no spend ceiling on a search. By policy, no model is given a time, token or cost
+budget.
+
+## OWASP Top 10 for Agentic Applications 2026
+
+### ASI01 Agent Goal Hijack
+
+**Here.** Text a stage reads redirects it to a goal that is not the clearance.
+
+**What Clearotron does.** The controls under LLM01 above. The stage's task is also fixed by the driver,
+and code checks what the stage hands back against that task's contract.
+
+**Where.** As LLM01, and `driver/stages.mjs`.
+
+**Not covered.** As LLM01: web content is not marked as untrusted.
+
+### ASI02 Tool Misuse
+
+**Here.** A stage uses a legitimate tool for something its task does not need.
+
+**What Clearotron does.** Each stage is granted its tools by name. The case-law stage is the exception: it is granted every tool its two case-law services offer. A tool outside
+that grant that needs permission is refused. Codex's approval covers only the tool servers Clearotron starts for the stage, and
+Codex's fetch tool refuses internal addresses. Register
+calls follow the fixed plan or a proposal code checks. Every tool call is written to the run's tool-call
+log, and each stage's attempt record counts the calls made and the calls refused.
+
+**Where.** `driver/engine/mcp/gather-config.mjs`, `driver/engine/mcp/codex-config.mjs`,
+`driver/engine/mcp/public-fetch.mjs`, `driver/engine/mcp/stdio-server.mjs` (the tool-call log),
+`driver/gateway.mjs` (`toolGauge`).
+
+**Not covered.** The Claude program also offers every stage some of its built-in tools that need no
+permission: starting a subagent, which keeps the stage's restrictions; scheduling a task on the operator's
+Claude account; messaging the account's other sessions; and sending a notification. Clearotron does not
+remove them.
+
+### ASI03 Identity and Privilege Abuse
+
+**Here.** A stage acts with more authority than its task, or takes a credential it can reuse.
+
+**What Clearotron does.** The AI program starts with a named list of settings, and the key that signs
+access keys is not on it. The worker that starts the AI program does not hold that key either, whether
+the install runs in a terminal or under systemd. Access keys are scoped to a run, a company or named
+actions, and one check enforces the scope. On Claude, a stage's file tools can read nothing outside its run folder, its
+instruction folders and any folder the machine's own Claude settings add. On Codex with its sandbox on, a stage's commands can read nothing outside its run folder, its instruction folders, the temporary
+folders, and the system and program files a command needs to run.
+
+**Where.** `driver/engine/engine-env.mjs`, `bin/start.mjs` (`SIGNING_KEY_NAMES`),
+`driver/systemd/clearotron-worker.service`, `shared/scope.mjs`, `driver/engine/anthropic-agent.mjs`
+(`READ_FENCE`), `driver/engine/mcp/codex-config.mjs` (`fenceToml`).
+
+**Not covered.** With Codex's sandbox off, a stage's commands run with every permission of the install's
+account and can read any file it can, the settings file included. With it on, the temporary folders are
+shared by every stage of the install, so a stage's commands can read what another stage left there.
+
+### ASI04 Agentic Supply Chain Vulnerabilities
+
+**Here.** A tool server or engine component that a stage trusts is compromised.
+
+**What Clearotron does.** The tool servers a stage uses are Clearotron's own code in this repository. Two
+of them are bridges Clearotron starts to the case-law services CourtListener and Legal Data Hunter, and
+they pass through the tools those services define. On Codex, the configuration written for each turn lists
+only the servers granted to that stage. The supply-chain controls under LLM03 apply here too.
+
+**Where.** `driver/engine/mcp/`, `providers/oauth-mcp-bridge/bridge.mjs`,
+`driver/engine/mcp/codex-config.mjs`.
+
+### ASI05 Unexpected Code Execution
+
+**Here.** A stage is talked into running code.
+
+**What Clearotron does.** A Claude stage has no tool that runs a command: Bash, PowerShell and Monitor
+are removed by name from every stage. A Codex stage runs its commands inside Codex's own sandbox. They can read nothing outside the stage's own folders, the temporary folders, and the system and program
+files a command needs to run, and write nothing outside its run folder and the temporary folders. Before a search is paid for, a
+check runs one turn through the engine with the settings the search will use.
+
+**Where.** `driver/engine/anthropic-agent.mjs` (`COMMAND_TOOLS`), `driver/engine/openai-agent.mjs`
+(`buildCodexArgs`), `driver/engine/mcp/codex-config.mjs` (`fenceToml`), `driver/engine/probe.mjs`.
+
+**Not covered.** Where Codex's sandbox cannot start on a machine, the setting
+`CLEAROTRON_CODEX_SANDBOX_BYPASS=1` runs Codex without it, and a stage's commands then run with every
+permission of the install's account. The engine check says when a machine needs it.
+
+### ASI06 Memory and Context Poisoning
+
+**Here.** Poisoned content persists and steers later work.
+
+**What Clearotron does.** The engine keeps no memory of its own: every stage starts from its task and its
+run folder, and a retried stage resumes only its own session. What does persist between runs is each
+company's configuration, its profile, risk framework and background notes, which every run reads and which
+only people with Manage can edit in the portal. On the Claude engine a stage cannot write to it.
+
+**Where.** `driver/gateway.mjs` (`runStage`), `driver/profiles.mjs`, [SECURITY.md](SECURITY.md) (who
+holds Manage), `driver/engine/deny-authority-write.mjs`.
+
+**Not covered.** As LLM01: web content that a stage reads, and that a later stage reads in its output, is
+not marked as untrusted.
+
+### ASI07 Insecure Inter-Agent Communication
+
+**Not applicable in its usual sense.** Stages do not message each other. The driver passes files from one
+stage to the next, and checks each one first.
+
+**Where.** `driver/gateway.mjs`, `driver/stages.mjs`.
+
+### ASI08 Cascading Failures
+
+**Here.** One failed stage corrupts the stages after it.
+
+**What Clearotron does.** Code checks each stage's output before the next stage reads it. A stage whose
+retries fail the same way twice stops retrying, and a stage whose every tool call was refused stops after
+one attempt. The engine check before a search refuses a machine that would fail every stage.
+
+**Where.** `driver/gateway.mjs`, `driver/engine/probe.mjs`, `driver/engine/tool-refusal.mjs`.
+
+### ASI09 Human-Agent Trust Exploitation
+
+**Here.** A reader trusts a confident report more than its evidence supports.
+
+**What Clearotron does.** A register finding names the register record it rests on, and every search that
+could not run is listed in the report.
+
+**Where.** `driver/publish/`, `driver/register-plan.mjs`.
+
+### ASI10 Rogue Agents
+
+**Here.** An agent that keeps running, spreads, or acts outside its task.
+
+**What Clearotron does.** No agent outlives its stage. Each stage is one process under a watchdog and a
+hard time limit, and the driver stops its whole process group. The driver records every program it
+starts. On the Claude engine a stage cannot write into the instructions it runs from.
+
+**Where.** `driver/engine/anthropic-agent.mjs`, `driver/engine/common.mjs`,
+`driver/engine/child-record.mjs`, `driver/engine/deny-authority-write.mjs`.
+
+**Not covered.** As LLM04: on Codex, no check refuses a stage's write inside its run folder.
+
+## Repository protections
+
+Measured on 2026-09-23 with the GitHub API.
+
+| Protection | State |
+|---|---|
+| Secret scanning | On |
+| Push protection | On |
+| CodeQL (Actions, JavaScript and TypeScript) | Configured, and a required check on `main` |
+| Code scanning before a stable release | A stable is not published while an alert is open |
+| Private vulnerability reporting | On |
+| npm provenance | Every release, through trusted publishing |
+| Required checks on `main` | Six; force pushes and branch deletion refused |

package/docs/SECURITY.md

@@ -5,6 +5,9 @@
 What protects what, where it is enforced in code, and what the operator must do. Every statement
 here corresponds to shipped behavior; when hardening changes, change this file in the same PR.
 
+Each risk on OWASP's two lists for AI systems, and what Clearotron does about it:
+[SECURITY-OWASP.md](SECURITY-OWASP.md).
+
 ## Surfaces
 
 | Surface | Trust | Guard |
@@ -12,7 +15,7 @@ here corresponds to shipped behavior; when hardening changes, change this file i
 | stdio MCP (`mcp-server/server.mjs`) | local/full ("ops") | OS user boundary — run it AS the operator account; it is the only surface on which `what_if_run` EXECUTES (`visibleTools` keeps what-if out of the HTTP listing for ops, but the CallTool chokepoint gates on `authorize()` alone, which admits it for any ops token not `--verbs`-scoped) |
 | Client MCP (`mcp-server/http-server-client.mjs`) | a company's signed-in person / their access key | `what_if_run` from an `account` principal ENQUEUES rather than executes (ruling 2026-08-27) — it never imports the engine, and `driver/whatif-worker.mjs` spawns the sandbox from an OS service process. A confirmation token is unsigned, so the call must ALSO name its `runId`: the grant check keys on it, and `whatIfEnqueue` refuses a token naming a different run. The `model` argument is refused on this face. |
 | HTTP MCP (`mcp-server/http-server.mjs`) | authenticated remote | auth-BEFORE-data; fail-closed construction; inner scoped tokens |
-| Report "Ask your AI" links | external report recipients | run-bound `user` tokens minted at publish; the plain-language report tools (`clientSafe`) only |
+| Run-bound keys | a report recipient an operator issues one to | a `user` key from `mint-token.mjs`, read-only and bound to one run; the plain-language report tools (`clientSafe`) only |
 | Dev portal (`driver/dev-portal.mjs`) | dev only | loopback-only (throws on any other host); never production serving |
 
 ## Authentication (the outer gate — both faces)
@@ -121,10 +124,9 @@ with access to everything.
 what the mechanism guarantees.*
 
 - One OPERATOR issuance path: `mint-token.mjs` (prints once, stores nothing; `sub` names the
-  principal in every audit line; the `jti` printed at mint time is the revocation handle). Two
-  automatic minters sit beside it on the same `mintToken`: the clearance publisher mints the report
-  link's run-bound `user` token at publish, and `clearotron start` mints the portal's verb-scoped,
-  company-capped ops token in memory at every start. Neither prints, and neither is written down.
+  principal in every audit line; the `jti` printed at mint time is the revocation handle). Three other callers share the same `mintToken`: `clearotron start` mints the portal's verb-scoped,
+company-capped ops token in memory at every start, and neither prints nor stores it; `clearotron connect`
+and the portal's connect screen each mint a person's key for their own assistant.
 - **Revocation**: denylist file checked on every verification; missing file = nothing revoked (the
   denylist can never take all auth down). **Rotation**: two-secret window, flag-day-free.
 - **Rate limits**: per-identity bucket on every request plus a separate lower per-principal bucket
@@ -132,9 +134,10 @@ what the mechanism guarantees.*
 
 ## Audit
 
-Every HTTP tool call appends `{ts, email, sub, tool, args-summary}` to an append-only JSONL
-(`TRADEMARK_MCP_AUDIT_LOG`). Audit is written after scope resolution (so the line names the
-principal) and before dispatch; it is best-effort and never blocks a request.
+Every HTTP tool call appends one line to an append-only JSONL (`TRADEMARK_MCP_AUDIT_LOG`) when the call
+finishes: `{ts, email, sub, method, tool, runId, status, door}`, where `status` is the outcome. It is
+written after scope resolution, so it names the principal. A request refused before any tool runs is
+written too, with the status `refused`. Writing it is best-effort and never blocks a request.
 
 ## Data plane
 
@@ -143,7 +146,8 @@ principal) and before dispatch; it is best-effort and never blocks a request.
   companies only. Run data lives in operator-owned directories outside git (`CLEAROTRON_REPORTS_DIR`,
   workspace root, outbox), backed up by the operator, never committed.
 - Secrets enter only via environment (`.env` on the host); the repo carries `.env*.example` files
-  with placeholders. CI runs a secret scan (gitleaks) on every push.
+  with placeholders. CI runs a secret scan (gitleaks) over the tree and the built bundle on every pull request and every
+push to `main`.
 - Dev instances are isolated by CONFIGURATION and nothing else: a test instance and a live one are the
   same code with different environment — no build flag, no profile constant, no mode switch in the
   source — so the separation holds exactly as far as the operator gives it its own
@@ -160,7 +164,9 @@ Each pipeline stage shells the configured engine binary as the operator account
 picks the adapter install-wide (`anthropic-agent` spawns `claude -p`, `openai-agent` spawns
 `codex exec` with a per-run `CODEX_HOME`), with no per-stage engine and no fallback between them —
 with run-scoped `--add-dir` access and per-provider gather MCP servers whose credentials come from the
-environment. Stage outputs are judged by file-truth validators — the engine's own success claims
+environment. The program starts with a named list of settings rather than the whole environment, so the
+key that signs access keys never reaches it (`driver/engine/engine-env.mjs`). A stage on Claude is
+offered no tool that runs a command; a stage on Codex runs its commands inside Codex's own sandbox. Stage outputs are judged by file-truth validators — the engine's own success claims
 are never trusted. Delivery is a self-contained packet couriered by the integrator; the engine sends
 no messages and holds no channel credentials.
 
@@ -178,9 +184,8 @@ no messages and holds no channel credentials.
 ## Reporting
 
 **[`../SECURITY.md`](../SECURITY.md) is the disclosure path** — the channel, what is in scope, and
-what to expect. It is the only file that names the channel — a monitored `security@` mailbox and
-GitHub's private vulnerability reporting, either one — so there is one place to change if a channel
-ever moves.
+what to expect. It is the only file that names the channels, so there is one place to change if one ever
+moves.
 
 If you run your own deployment, reports about *your* configuration — your auth proxy, your TLS, your
 keys — go to you. This file describes what the code guarantees; it cannot speak for how a given

package/docs/architecture/02-architecture.md

@@ -214,9 +214,9 @@ mode via `CLEAROTRON_AI_BILLING=api-key` — the scale setting ([04](04-configur
 
 **The second engine** (`engine/openai-agent.mjs`) spawns `codex exec` per stage on the shared
 `engine/common.mjs` substrate: prompt on stdin, `--json` event stream, `--skip-git-repo-check` with a neutral non-repo
-cwd, `--sandbox workspace-write --add-dir <runDir>`, and a per-run `CODEX_HOME` holding a rendered
-`config.toml` (MCP servers + developer instructions) plus, under subscription billing, a seeded
-`auth.json`. It is single-provider like the anthropic engine — one run's stages all execute as GPT —
+cwd, `--add-dir <runDir>`, and a per-run `CODEX_HOME` holding a rendered `config.toml` (MCP servers,
+developer instructions and, with Codex's sandbox on, a permission profile that limits what the stage's
+commands can read and write) plus, under subscription billing, a seeded `auth.json`. It is single-provider like the anthropic engine — one run's stages all execute as GPT —
 so telemetry's model provenance needs no cross-provider bookkeeping. Its abstract tiers all resolve
 to one model id by default; [04](04-configuration-reference.md) records why, and why lowering them
 is not a cost saving.
@@ -254,7 +254,7 @@ primitive is a filesystem primitive chosen for its atomicity:
 | pid+starttime sidecars | claim liveness, slot ownership | survives pid reuse; positive-evidence death only |
 
 The run directory ([03 §7](03-run-lifecycle.md#7--run-directory-anatomy)) is the unit of truth;
-the queue dirs, the known-conflicts store, the outbox, and the publish pool are the only shared
+the queue dirs, the outbox, and the publish pool are the only shared
 locations, and each has a single writer role. This is why horizontal
 scaling is credible: a second driver on a second host needs sharded queues and a shared pool,
 nothing else.
@@ -286,7 +286,7 @@ All paths relative to [`driver/`](../../driver/). The load-bearing seven are mar
 | `rule-shape.mjs` · `reasoning-tripwires.mjs` · `gate-metrics.mjs` | Anti-threshold guard, integrity tripwires (observe-only), gate telemetry. |
 | `predelivery-lint.mjs` · `close-verify.mjs` · `screen-gate.mjs` | Pre-delivery checks, envelope close verification, screen-gate detection. |
 | `common-law-receipts.mjs` · `engagement-receipt.mjs` · `scope-ledger.mjs` | Receipt models for the marketplace grid, engagement, scope. |
-| `senior-rights.mjs` · `own-rights.mjs` · `use-check.mjs` · `known-conflicts.mjs` | Rights closure, self-exclusion, use analysis, recall store. |
+| `senior-rights.mjs` · `own-rights.mjs` · `use-check.mjs` | Rights closure, self-exclusion, use analysis. |
 | `publish/` | Deterministic publication: HTML render, Excel audit workbook, pool admin, regions. |
 | `repairs.mjs` · `repair-digest.mjs` | Recovery decisions, repair budgets, repair digests. |
 | `tokens.mjs` · `provider-usage.mjs` · `progress.mjs` · `status-snapshot.mjs` · `run-activity.mjs` | Token rollup (successor to the deleted `cost.mjs`), billing-grade provider ledger, status surfaces. |

package/docs/architecture/03-run-lifecycle.md

@@ -178,7 +178,7 @@ seeding. Frozen sidecars are never silently re-derived; a corrupt one crashes lo
 flowchart TD
     subgraph HEAD["Phase 1-2 head (fatal)"]
         MF[matter-frame] --> PV[clearance-variants]
-        PV --> DER["code derivations:<br/>scope ledger · form neighbourhood ·<br/>register plan freeze · recall probes"]
+        PV --> DER["code derivations:<br/>scope ledger · form neighbourhood ·<br/>register plan freeze"]
     end
     DER --> GRID["grid spec dictated by code<br/>(terms × platforms × connotation; A1 split)"]
     subgraph GATHER["Gather fan-out (concurrency = CLEAROTRON_GATHER_CONCURRENCY)"]
@@ -189,18 +189,17 @@ flowchart TD
     GRID --> GATHER
     GATHER --> FANIN{{"fan-in barrier (code):<br/>quarantines · must() · half-merge ·<br/>named-band gate · taint chain ·<br/>plan⇄band identity join · grid-ledger gate"}}
     FANIN --> CLOSURE["coverage closure pass<br/>(one supplementary sweep, non-fatal)"]
-    CLOSURE --> PI[placement-inquiry] --> RD[register-digest]
+    CLOSURE --> FD["frame-diff vs blind frame<br/>+ bounded reopen (non-fatal block)"] --> PI[placement-inquiry] --> RD[register-digest]
     RD --> SK["skeptic (non-fatal)"]
     SK --> ESC{"ESCALATE: axis tokens?"}
     ESC -- yes --> RERUN["re-run flagged axes warm ·<br/>byte-diff · one re-digest"] --> ENV
     ESC -- no --> ENV["deadline envelope:<br/>close deferred floors if time allows"]
     ENV --> SG{{"screen-gate: dropped LIVE mark<br/>without fetched record?<br/>fetch → re-digest → else FATAL"}}
-    SG --> FD["frame-diff vs blind frame<br/>+ bounded reopen (non-fatal block)"]
-    FD --> SYN[synthesis]
+    SG --> SYN[synthesis]
     SYN --> PAR["case-law ∥ narrative-refutation<br/>(case-law non-fatal)"]
     PAR --> VG{"verdict gate:<br/>parseVerdict(review)"}
     VG -- "CONDITIONAL / BLOCKING" --> CORR["corrective re-synthesis (fatal) ·<br/>corrections freshness gate ·<br/>verdict re-check (warm)"] --> VG2{"still BLOCKING?"}
-    VG2 -- yes --> FAIL[["FATAL StageFailure('verdict')"]]
+    VG2 -- yes --> DELIV["report DELIVERS (ruling 2026-08-26) ·<br/>runLog verdict-blocking-delivered ·<br/>open points recorded beside the review,<br/>for the reviewing lawyer (ruling 2026-09-24)"] --> CLAMP
     VG2 -- no --> CLAMP
     VG -- CLEAR --> CLAMP["code clamps (raise-only):<br/>legal actions · coverage · frame residual ·<br/>screen gate · register gap · deadline gap"]
     CLAMP --> VS["verdict sidecar _driver/verdict.json<br/>(single label authority; write failure = fatal)"]
@@ -212,7 +211,7 @@ flowchart TD
     PUB --> HANDOFF["delivery packet _driver/delivery.json ·<br/>outbox <runId>.pending · .delivered · archive"]
 
     classDef fatal stroke:#c0392b,stroke-width:2px
-    class MF,PV,PI,RD,SYN,FAIL,VS,CG fatal
+    class MF,PV,PI,RD,SYN,VS,CG fatal
 ```
 
 Reading order for the phases, with what code decides at each:
@@ -222,8 +221,7 @@ Reading order for the phases, with what code decides at each:
    generates the complete mechanical variant floor), freezes the register plan
    (`_driver/register-plan.json`, frozen for the life of *this run* — a resume never re-plans, and a
    fresh run always mints; reproducibility comes from the compiler being pure, not from a store of
-   prior plans), and folds in **recall probes** — prior confirmed conflicts for this mark from the
-   workspace store become deterministic plan entries (cap 10).
+   prior plans).
 2. **Grid dictation** — code writes `_driver/grid-spec.json`: exact terms × platforms, connotation
    queries, batch size, `ledger_required: true`. With ≥2 terms the grid is split across three
    seats — unconditionally since  item 8 deleted the rollback switch: halves`a` and `b` take
@@ -244,29 +242,29 @@ Reading order for the phases, with what code decides at each:
    persistent repair ledger (`_driver/repairs.json`) so no ladder is ever bought twice.
 5. **Coverage closure** — one supplementary sweep for closable coverage-limited cells, idempotent
    by receipt; survivors become a front-matter coverage note, not a halt.
-6. **Placement → register-digest** — both fatal. Every digest pass (fresh, escalation, envelope,
+6. **Frame-diff + bounded reopen** — the blind frame is diffed against the run's own framing;
+   directives (including deterministic mechanical form-gap directives) can reopen register and
+   source arms once, under a fetch ceiling (`CLEAROTRON_REOPEN_MAX_FETCH`, default 150), with
+   per-directive closure verification. The whole block is non-fatal; unclosed directives demote to
+   disclosed deferrals that later clamp the verdict.
+7. **Placement → register-digest** — both fatal. Every digest pass (fresh, escalation, envelope,
    late-bind, stale-repair) goes through the single `runDigest` chokepoint, which drops stale ledgers,
    renders the coverage ledger from the driver-written coverage form the seat submits through
    `record_coverage` — the prose `## Coverage ledger` table and the machine-readable JSON are both
    renders of that one form, so neither can be the thing that drifts (prose parsing survives only as
    the fallback when the derivation throws) — and quarantines rather than ships a ledger that fails
    its validator.
-7. **Skeptic + escalation** — the skeptic is deliberately non-fatal (a checker outage must not bin
+8. **Skeptic + escalation** — the skeptic is deliberately non-fatal (a checker outage must not bin
    a completed gather). Escalation is triggered only by structured `ESCALATE: <axis>` tokens; an
    axis whose every owned ledger row is `coverage-limited` is skipped (documented accepted limit);
    flagged axes re-run warm on their winning session keys, byte-diff guards skip unchanged units,
    then exactly one re-digest. A digest lock forbids escalation after synthesis exists on a resume.
-8. **Deadline envelope** — pure arithmetic: if the deadline leaves room after an estimated close
+9. **Deadline envelope** — pure arithmetic: if the deadline leaves room after an estimated close
    cost plus a one-hour delivery reserve, deferred floors get one warm close attempt, verified by
    re-running the detectors; unverifiable closes are disclosed, never claimed.
-9. **Screen-gate** — an in-scope *live* mark dropped on goods/field grounds without a fetched
-   record is repaired (code fetches the record, one warm re-digest) or the run dies: an
-   unexaminable drop is not shippable.
-10. **Frame-diff + bounded reopen** — the blind frame is diffed against the run's own framing;
-    directives (including deterministic mechanical form-gap directives) can reopen register and
-    source arms once, under a fetch ceiling (`CLEAROTRON_REOPEN_MAX_FETCH`, default 150), with
-    per-directive closure verification. The whole block is non-fatal; unclosed directives demote to
-    disclosed deferrals that later clamp the verdict.
+10. **Screen-gate** — an in-scope *live* mark dropped on goods/field grounds without a fetched
+    record is repaired (code fetches the record, one warm re-digest) or the run dies: an
+    unexaminable drop is not shippable.
 11. **Synthesis** — fatal. Malformed findings get one warm re-emit naming exactly the defective
     objects; still-malformed findings after the ladder are terminal (the old quarantine-and-continue
     is retired). Schema and actions[] upgrades are demanded warm on runs where synthesis actually ran.
@@ -275,12 +273,16 @@ Reading order for the phases, with what code decides at each:
     verdict is parsed by code; a parse failure is **BLOCKING** (fail-safe). CONDITIONAL/BLOCKING
     triggers corrective re-synthesis (fatal if it fails), a freshness gate proving the named
     corrections reached `findings.json`, and a warm verdict re-check. A still-BLOCKING verdict
-    after the degenerate-artifact repair is a fatal run failure — "delivered with open questions"
-    is retired.
+    after the degenerate-artifact repair does **not** fail the run. Ruling 2026-08-26, verbatim:
+    "Deliver always, with open points printed. The refusal on a blocking review goes." The run
+    logs `verdict-blocking-delivered` and carries on to the clamps. Ruling 2026-09-24 settled
+    where the points go: reviewer notes never reach the client page, and a report the reviewer
+    still refuses ships with its rating and nothing added — the open points are recorded beside
+    the review in the run record, for the reviewing lawyer.
 13. **Code clamps** — the coverage floor (`applyCoverageFloor`) only ever *raises* CLEAR to
     CONDITIONAL: typed condition actions, the lawyer's explicit `coverage_judgment.sufficient ===
-    false`, frame residuals, screen-gate gaps, register gaps (from the taint-relabelled ledger),
-    deadline-carry gaps. Execution facts clamp in code regardless of the model's self-report. The
+    false`, frame residuals, screen-gate gaps, register gaps (from the taint-relabelled ledger).
+    Execution facts clamp in code regardless of the model's self-report. The
     **verdict sidecar** (`_driver/verdict.json`) then becomes the single verdict authority for
     everything downstream; failing to write it is fatal.
 14. **Delivery phase** — report overview (fatal), per-finding report cards (fan-out, individually
@@ -292,7 +294,7 @@ Reading order for the phases, with what code decides at each:
     reasoning-integrity receipt (observability only, never a gate — an explicit Goodhart guard).
 15. **Client-gate + publish + handoff** — the client gate is evaluated fail-closed *before*
     anything touches the pool. Publish is deterministic code, idempotent via `.published`. Then the
-    delivery handoff (§4), known-conflicts store upsert, `status.json` flip to `delivered`,
+    delivery handoff (§4), `status.json` flip to `delivered`,
     archive (the run dir is renamed into the archive tree), and the `.delivered` sentinel.
 
 **Fatal vs note-and-continue.** The full lists live in `pipeline.mjs` (the outer catch), but the shape is:
@@ -465,7 +467,7 @@ needs is in it:
 │   ├── profile.json · framework.json · register-plan.json     # frozen per-run config (never re-derived)
 │   ├── grid-spec.json (+ .half-a/b, .supp-*)                  # code-dictated search specs
 │   ├── coverage-enum.json · plan-execution.json               # fail-closed enum sentinel · execution receipt
-│   ├── register-recall.json · register-xcheck.json            # recall probes · cross-check receipts
+│   ├── register-xcheck.json                                   # cross-check receipt (a run before 2026-09-24 may also carry register-recall.json, its recall-search receipt)
 │   ├── register-taint.json · escalation-state.json            # taint chain · escalation/envelope outcome
 │   ├── coverage-closure.json · frame-reopen.json              # closure + reopen receipts
 │   ├── intake-asks.json · instructed-scope.json               # intake derivations (code-authoritative scope)
@@ -486,7 +488,4 @@ needs is in it:
 └── (delivered runs move whole to <archive>/<YYYY-MM>/<slug>/)
 ```
 
-Outside the run dir, a run touches the workspace known-conflicts store
-(`_known-conflicts/<mark>.json` — human-editable; code only adds
-rows, and rewrites exactly one machine field, `terminal`, when a delivered run confirms a leg an
-earlier failed attempt recorded), the outbox (`<runId>.pending`), and the publish pool.
+Outside the run dir, a run touches the outbox (`<runId>.pending`) and the publish pool.

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

@@ -85,7 +85,7 @@ does after the stage's full retry ladder fails ([03 §5](03-run-lifecycle.md#5--
 | 10 | `frame-diff` | sonnet · low | 600 / — | `frame-diff.md` + `frame-diff.json` | non-fatal (no reopen) |
 | 11 | `synthesis` | `CLEAROTRON_SYNTHESIS_MODEL` \|\| opus · high | 2500 / 900 | `narrative.md` + **`findings.json`** (schema v7 — `FINDINGS_SCHEMA_VERSION`, interpolated into the contract the stage message dictates: `findings`, `coverage`, `mark_assessment`, `four_answers`, `actions`, `coverage_judgment` and `rated_under_framework`, plus `context_notes` / `ask_answers` where they apply) | quasi-fatal: unrepaired finding defects are terminal; corrective re-synthesis is fatal on failure |
 | 12 | `case-law` | sonnet · adaptive | 900 / — | `case-law-findings.md` | non-fatal; conditional on the PRODUCT — `decideCaseLaw` (`pipeline.mjs`) runs it on **every** `full-country-search`, because the case-law and opposition reading is what that product IS and `policy.caseLaw` is set from the product spec. A narrative that turns on a precedent or an opposition is the second, redundant arm there; on any other product that reading is recorded as `declined`, never run |
-| 13 | `narrative-refutation` | opus · high | 900 / 600 | `senior-eye-review.md` (verdict on first line) | fatal |
+| 13 | `narrative-refutation` | opus · high | 900 / 600 | `senior-eye-review.md` (verdict on first line) | fatal: the STAGE failing to produce a review. Its **verdict** is not — a still-BLOCKING verdict delivers (ruling 2026-08-26), see [03](03-run-lifecycle.md) step 12 |
 | 14 | `report-overview` | sonnet · low | 900 / — | `report-overview.md` (shell only; cards + "Only you can close these" are code-built) | fatal |
 | 15 | `report-card` | sonnet · low | 600 / — | `report-cards/<ord>.md` | non-fatal per card (structured-only fallback) |
 | 16 | `doubt-closure` | sonnet · low | 300 / — | `doubt-closure.md` (dictated `SETTLED`/`IMMATERIAL`/`OPEN` lines; code re-verifies every quote) | non-fatal (the open doubts and asks ship `OPEN`, as they would without the stage) |
@@ -138,12 +138,6 @@ id is what a dispatch row and a token-rollup row carry as the model *asked for*;
 the turn is recorded beside it, and the report names that. A version here would be a claim about a
 request nobody made, and wrong the day a newer model of the tier shipped.
 
-One consequence, accepted when this was decided: per-model totals are keyed on what was asked for,
-and the native-language lanes call the API directly, where a model id is required and a tier word is
-not accepted. So one model reached by a stage and by those lanes appears under two keys —
-`anthropic/claude-haiku` and `anthropic/claude-haiku-4-5`. They are different requests, and the split
-says so.
-
 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.
 
@@ -199,7 +193,7 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 | `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. |
 | `CLEAROTRON_DATABASE` | **REQUIRED — no default.** `corsearch` \| `clarivate` \| `signa` \| `euipo` \| `uspto-local` \| `free-tier` | Active register provider — one per run, set in the environment the deploy carries, in every environment including production. There is **no default**: unset resolves to `null` and every use of it throws, so a run refuses at start rather than calling a vendor nobody chose (the removed `corsearch` fallback named a vendor the deployment did not choose). Three are paid global sweeps; `euipo` (EU) and `uspto-local` (US) are free single-office sources, and `free-tier` composes those two as one register. Choosing a free value makes every territory outside its coverage a disclosed *deferred* row. Unknown ids throw loudly, and the gather layer throws at stage time for any provider without a built MCP server. |
-| `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox helper bypassed, for hosts where that helper cannot spawn or refuses every tool call (setup and `doctor --probe-engine` report the refusal). It removes a defence: with it set, the run dir is writable by the seat and only the deny-hook stands between a stage and `_driver/`. Set it because the host forces it, never for convenience. |
+| `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox bypassed, for hosts where that sandbox cannot run (setup and `doctor --probe-engine` report it). It removes a defence: with it set, a stage's commands run with every permission of the account Clearotron runs as, not only in the run folder. Codex has no guard against a stage writing into the run's `_driver/` folder, with the sandbox or without it. Set it because the host forces it, never for convenience. |
 
 ## Environment variable reference
 
@@ -248,6 +242,8 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_MAX_CLAIM_AGE_MS` | 172800000 (48 h; 0 disables) | Hard ceiling on a claim's age (from the `.pid` sidecar mtime) — beyond it, re-claim regardless of liveness. |
 | `CLEAROTRON_KNOCKOUT_VARIANT_CAP` | unset (⇒ the lane's own cap) | Ceiling on variants a knockout screens per name. Set only to bound an unusually wide batch; absent means the lane decides. |
 | `CLEAROTRON_KNOCKOUT_RECORD_CAP` | unset (⇒ the lane's own cap) | Ceiling on records a knockout fetches per hit. Same shape as the variant cap: absent is the normal state. |
+| `CLEAROTRON_SIGNA_ANSWER_MEMORY` | `off` | On the Signa register, whether a run reuses an answer it already holds instead of asking again. `off` asks every time. `watch` also asks every time, and records whether a held answer would have matched. `on` reuses held answers. |
+| `CLEAROTRON_CLARIVATE_ANSWER_MEMORY` | `on` | On the Clarivate register, whether a run reuses a count, a search, an owner lookup or a record it already holds instead of asking again. `off` asks every time. |
 
 ### Retries, timeouts, watchdogs
 
@@ -281,10 +277,9 @@ unrecognised policy value that leaves the default behaviour standing.
 
 | Var | Gates |
 |---|---|
-| `CLEAROTRON_RECALL_PROBES` / `CLEAROTRON_RECALL_TRIPWIRE` | Prior-confirmed-conflict plan probes / recall store reads + regression check. |
 | `CLEAROTRON_PLAN_DISPATCH` (`0` or `off` disables) | Pure-code provider `executePlan` repairs at fan-in and reopen. **Never silently inert:** every entry in `PROVIDERS` ships an `executePlan` adapter, and `preflightCredentials` refuses the run before any spend under one that does not — a credential is not a capability. §5.4 of [05-config-governance.md](05-config-governance.md) still lists `signa` as the exception to that and has not been updated since its two missing tools were mounted. |
 | `CLEAROTRON_FRAME_REOPEN` (+ `CLEAROTRON_FRAME_REOPEN_MAX`, default 1) | The bounded frame-diff reopen. |
-| `CLEAROTRON_REGISTER_GAP_CLAMP` | The registerGap + deadline-carry verdict clamp arms. |
+| `CLEAROTRON_REGISTER_GAP_CLAMP` | The registerGap verdict clamp arm. |
 | `CLEAROTRON_REOPEN_MAX_FETCH` (default 150) | Detail-fetch ceiling inside the reopen closure pass. |
 | `CLEAROTRON_UNREACHABLE_SENIOR` (`open-item` \| `clamp`, default `open-item`) | Policy when a verdict-driving senior right can't be retrieved. |