clearotron 0.2.3 → 0.2.4

package/driver/README.md

@@ -1,4 +1,4 @@
-# clearotron-driver — deterministic driver for the prelim-search trademark workflow
+# clearotron driver — deterministic orchestration for the trademark clearance workflow
 
 Orchestration in **code**; the LLM does only judgment leaves. Each pipeline stage is **one blocking
 engine turn** (default engine: `anthropic-agent`, shelling `claude -p` per stage); fan-out/fan-in/
@@ -18,8 +18,7 @@ the gather MCP servers live.
 ```
 integrator ──job JSON (enqueue CLI / start_run / queue file)──┐
                                                               ▼
-                    systemd .path (watches every queue) ──▶ prelim-driver.service
-                    systemd .timer (~90s fallback re-drain) ─▶ (same oneshot)
+                    clearotron-worker.service (the built-in worker, watches every queue)
    └─ node runner.mjs ─▶ for each queue: claim ─▶ pipeline(job, {agent}) ─▶ runStage() ─▶
                          engine turn (`claude -p`, blocking) ─▶ leaf turn
 ```
@@ -42,8 +41,28 @@ identity ran it. Headless deployments with no per-agent workspaces use one expli
   delivered report, run failure, intake rejection, duplicate skip, late-bind ack — is a
   self-contained packet in the outbox (`outbox.mjs`). Integrators consume events over the ops MCP
   (`list_outbox_events` → `get_delivery_packet` → send → `mark_sent`/`ack_event`) and never touch the
-  driver's filesystem. `deliver-trigger.sh` + `systemd/prelim-outbox.*` are the reference wake-up for
-  an agent-based integrator.
+  driver's filesystem. `deliver-trigger.sh` is the reference wake-up for an
+  agent-based integrator. The outbox units beside it are retired — see the units row below.
+
+## What a file name tells you
+
+Eleven suffixes carry a meaning across the whole directory. They are a naming convention rather than
+a framework — nothing enforces them — but they are consistent enough that the suffix tells you what
+kind of thing a module is before you open it.
+
+| suffix | what the module is |
+|---|---|
+| `-model` | a pure parser or shape: text or JSON in, a validated structure out, no I/O |
+| `-record` | a recording transport — the typed call a stage makes and the row it writes |
+| `-form` | a driver-written form a stage fills in, with its own validation |
+| `-io` | the reader and writer for a form's file, kept apart from the form's shape |
+| `-union` | the accumulator that merges many writes into one form |
+| `-call` | the model-call half of a pair: what the stage is asked to send |
+| `-tool` | the driver-write half of the same pair: what the driver does with what came back |
+| `-duty` | an obligation check — was something the run owed actually done |
+| `-gate` | a refusal: a condition that stops a run or a stage rather than reporting on it |
+| `-ledger` | an append-only account of what happened, read back for coverage and audit |
+| `-verdict` | a pure function from evidence to a stated answer, with its reason |
 
 ## Files
 
@@ -63,7 +82,7 @@ identity ran it. Headless deployments with no per-agent workspaces use one expli
 | `coverage-ledger.mjs` | Machine coverage-ledger contract: strict JSON-mirror parser (token-first throws), prose parser, `REGISTER_AXES`/`decideAxes`. |
 | `enqueue-schema.mjs` | Job-file shape + `validateJob`. |
 | `dev-portal.mjs` | Loopback-only dev-instance UI (static pool + `/profiles/*` proxy) for dry-run testing — see `../docs/E2E.md` Tier 1b. |
-| `systemd/*` | Reference units: `prelim-driver.path` (watches the queues) + `prelim-driver.timer` (fallback re-drain) → `prelim-driver.service` (oneshot drain); `prelim-outbox.*` (outbox wake). |
+| `systemd/*` | `clearotron-worker.service` is the live worker and what a deployment runs. The path/timer/oneshot drain units and the outbox-wake units beside them are RETIRED: the built-in worker replaced that posture. Their files stay until the production rebuild — `unit-inventory.mjs` records the ruling and the reason, and reports a retired unit's absence as expected rather than as a fault. They keep their original names because a deployed box still holds them under those names. |
 
 ## Key engine facts
 

package/driver/connotation-search.mjs

@@ -769,7 +769,7 @@ export function segmentBinding({ segment_index, fragment } = {}, candidate) {
   //
   // SO THE MEASUREMENT SURVIVES THE ENFORCEMENT. A fragment that arrives is still weighed and still
   // matched, and the verdict rides out on `fragmentState` for the receipts histogram — which is how the
-  // transcription-quality signal scruffy used to settle this stays measurable after the duty that
+  // transcription-quality signal testing used to settle this stays measurable after the duty that
   // produced it is gone. Never charge for it: an unbound fragment is a fact about the model, and the
   // seat's ruling is not worse for it.
   const frag = String(fragment ?? "").trim();

package/driver/contract-audit.mjs

@@ -276,7 +276,11 @@ export const E3_BACKLOG_KINDS = [...E3_KINDS, "other"];
 
 const E3_PATTERNS = [
   { kind: "literal-json-skeleton", re: /```json|\{\s*"[a-z_]+"\s*:/i },
-  { kind: "exactly-these-keys", re: /EXACTLY (?:these|one of|the)|keys EXACTLY|EXACTLY \{|closed enum|key set is closed|additionalProperties/i },
+  // `EXACTLY the` USED TO STAND ALONE, and it is ordinary English: "puts its noise on exactly the
+  // report that matters most" is prose about a report, not a dictated key set, and the pattern is
+  // case-insensitive so the lower-case form matched too. The alternative now names what may follow it,
+  // which is the only form that dictates a set. Everything else in this pattern is byte-identical.
+  { kind: "exactly-these-keys", re: /EXACTLY (?:these|one of)|EXACTLY the (?:following|keys|fields)|keys EXACTLY|EXACTLY \{|closed enum|key set is closed|additionalProperties/i },
   // A quoted or backticked template carrying a <placeholder>, close to an instruction to emit it. The
   // placeholder class is deliberately loose (`<comma-separated DOMAINS>`, `<N>`, `<one record URI>`) —
   // the tell is a shape dictated for a parser to read back, not the casing inside the angle brackets.

package/driver/contract-e3-baseline.json

@@ -17,7 +17,7 @@
     },
     "common-law": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 3,
+      "exactly-these-keys": 2,
       "dictated-line-shape": 0
     },
     "common-law-half": {
@@ -52,7 +52,7 @@
     },
     "synthesis": {
       "literal-json-skeleton": 10,
-      "exactly-these-keys": 9,
+      "exactly-these-keys": 8,
       "dictated-line-shape": 5
     },
     "case-law": {
@@ -114,7 +114,7 @@
     },
     "skills/prelim-common-law/SKILL.md": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 2,
+      "exactly-these-keys": 1,
       "dictated-line-shape": 2
     },
     "skills/prelim-register/SKILL.md": {
@@ -129,7 +129,7 @@
     },
     "skills/placement-inquiry/SKILL.md": {
       "literal-json-skeleton": 1,
-      "exactly-these-keys": 4,
+      "exactly-these-keys": 3,
       "dictated-line-shape": 1
     },
     "skills/prelim-register/digest.md": {
@@ -139,7 +139,7 @@
     },
     "skills/prelim-search/phase2-execution.md": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 2,
+      "exactly-these-keys": 0,
       "dictated-line-shape": 3
     },
     "skills/frame-diff/SKILL.md": {
@@ -149,12 +149,12 @@
     },
     "skills/prelim-search/synthesis-rules.md": {
       "literal-json-skeleton": 1,
-      "exactly-these-keys": 7,
+      "exactly-these-keys": 1,
       "dictated-line-shape": 2
     },
     "skills/prelim-search/firm-wide-reasoning.md": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 2,
+      "exactly-these-keys": 0,
       "dictated-line-shape": 0
     },
     "skills/prelim-search/risk-framework.md": {
@@ -164,7 +164,7 @@
     },
     "skills/prelim-search/worked-examples.md": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 1,
+      "exactly-these-keys": 0,
       "dictated-line-shape": 1
     },
     "skills/prelim-search/report-prose.md": {
@@ -179,7 +179,7 @@
     },
     "skills/narrative-refutation/SKILL.md": {
       "literal-json-skeleton": 0,
-      "exactly-these-keys": 3,
+      "exactly-these-keys": 2,
       "dictated-line-shape": 1
     },
     "skills/prelim-search/delivery-contract.md": {
@@ -189,7 +189,7 @@
     }
   },
   "totals": {
-    "stages": 47,
-    "files": 78
+    "stages": 45,
+    "files": 64
   }
 }

package/driver/doubt-selection.mjs

@@ -100,7 +100,7 @@ export function doubtsForClosure({ doubts = null, doubtClosure = null } = {}) {
   // The event exists to answer whether a cut is WORTH giving a value, before any row has one: if most
   // doubts carry no tier the cut saves nothing. A count written only when the cut is live needs the cut
   // to exist in order to measure whether the cut should exist — the circularity pipeline.mjs's own
-  // comment says this event prevents. Found by role-e2e eggie on the R2 artifacts.
+  // comment says this event prevents. Found in review on the R2 artifacts.
   //
   // `keepSet` null means "keep everything": nothing is ever dropped, `ids` is discarded below, and the
   // dispatch stays byte-identical. Only the COUNTS change.

package/driver/drainer-identity.mjs

@@ -136,7 +136,7 @@ export function drainerVerdict({ stamp, headCommit, isAlive, processes, ppidOf =
     : "";
 
   if (!alive) {
-    // ── THE ONE BRANCH THE POSTURE DECIDES (tracker issue 206, ruled by overwatch 2026-09-06).
+    // ── THE ONE BRANCH THE POSTURE DECIDES (decided 2026-09-06).
     //
     // The same empty answer means two opposite things. Where a worker holds the queue open, a gone
     // drainer is the outage: nothing is executing runs and nothing will start one. Where the box drains

package/driver/effort-model.mjs

@@ -218,7 +218,7 @@ export const costBand = (i) => Math.max(1, Math.min(5, Math.ceil(effortUnits(i)
 // range is the thing this section was rebuilt to remove; do not reintroduce one without a new ruling.
 
 /**
- * THE QUOTED BOUNDS. ONE SOURCE — owner ruling, 2026-08-23, relayed by overwatch.
+ * THE QUOTED BOUNDS. ONE SOURCE — owner ruling, 2026-08-23.
  *
  * WHAT THIS REPLACED, and why a constant beat a model. The old quote was a base plus one adder per lane:
  * 1.5h, +0.5 for case law, +0.5 for a native-language lane, +0.5 for a single territory. It missed the
@@ -264,7 +264,7 @@ export const quoteBoundsFor = (l) => TURNAROUND_QUOTE[deriveMode(l) === "knockou
 /**
  * The bounds for THIS job. The ruled range, and NOTHING is done to it.
  *
- * — OWNER RULING, 2026-08-26, relayed by overwatch: "No compute. We just say 1.5–2.5 hours for
+ * — OWNER RULING, 2026-08-26: "No compute. We just say 1.5–2.5 hours for
  * big reports, period. Keep it simple." The question put to him was which run-slot cap the quote should
  * divide by, and he removed the division instead of answering it.
  *

package/driver/engine/probe.mjs

@@ -123,7 +123,13 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
   if (!tuple) return v("failed", "none", `${id} returned nothing`, "The adapter settled no tuple — this is a driver bug, not a configuration one.");
   const s = tuple.signals ?? {};
   const text = `${tuple.stderr ?? ""}\n${tuple.stdout ?? ""}`;
-  const detail = tail(tuple.stderr);
+  // READ FROM THE SAME STREAMS THE CLASSIFICATION IS. Every branch below matches over `text`, which is
+  // stderr AND stdout, while this carried stderr alone — so a CLI that reports its failure on stdout
+  // produced a verdict with its evidence dropped, and the reader got a headline with nothing under it.
+  // stderr stays FIRST because that is where a diagnostic belongs and where these CLIs put theirs; the
+  // fallback exists so that "the engine said nothing" is a claim about the engine rather than about
+  // which pipe this happened to look at.
+  const detail = tail(tuple.stderr) ?? tail(tuple.stdout);
 
   if (tuple.code === 0) return { ok: true, engine: id, mode: "ok", basis: "completed-turn", headline: `${id} completed a turn`, fix: null, detail: null };
 
@@ -249,13 +255,47 @@ export function probeWeatherWarning(verdict) {
  * whatever the operator's shell happens to have set and report a pass for the wrong engine — the same
  * frozen-provider trap `preflightCandidate` works around one file over.
  *
- * ONLY the engine-selection keys are applied. Credentials and billing-mode variables are deliberately
- * NOT copied: the probe must bill exactly the way a run on this box would, and moving a spend variable
- * to make a probe pass is the one thing this must never do.
+ * THE SPEND VARIABLES ARE APPLIED TOO, and the rule this replaces had it backwards. It said they were
+ * deliberately not copied, so that "the probe must bill exactly the way a run on this machine would" —
+ * the aim is right and withholding them defeated it. The caller supplies the lane and the credential
+ * precisely because they are not in the environment yet; not copying them left the probe billing the
+ * way the operator's shell happened to be set, while the run that followed billed the way the reader
+ * had just chosen. The probe proved a lane nobody was going to use. Measured: an API-key install failed
+ * as "not signed in" because the adapter removes the key under any mode that is not the API-key one,
+ * and the mode it read was the unset one.
+ *
+ * WHAT IS STILL NEVER DONE, which is the sentence that was worth keeping: nothing here defaults,
+ * repairs, invents or falls back. It copies what the caller passed and nothing else, so a probe cannot
+ * pass on a credential a run would not have — the caller is the wizard about to write these very values
+ * to disk, or a command reading the values already there.
+ *
+ * AND IT PUTS EVERYTHING BACK. Widening what this writes onto the process widens what it must remove
+ * again; a credential outliving the check that borrowed it would be a worse defect than the one this
+ * fixed, and a check drives the restore rather than trusting it.
  */
 function applyEngineEnv(env) {
   if (!env || env === process.env) return () => {};
-  const keys = ["CLEAROTRON_AI", ...Object.values(ENGINE_BINARIES).map((s) => s.env)];
+  // EVERY VARIABLE THAT DECIDES WHAT THE SPAWN IS, not only the ones that decide WHICH BINARY.
+  //
+  // This list used to carry CLEAROTRON_AI and the binary paths. It did not carry the billing mode or
+  // the API key — so a caller could hand this function a correct api-key environment, watch
+  // `resolveAuthMode` accept it, and then have `runTurn` read `process.env`, where neither had arrived.
+  // `anthropic-agent.spawnEnv` deletes ANTHROPIC_API_KEY under any mode that is not api-key, and the
+  // mode it read was unset, so it deleted the key the reader had just typed. The turn then failed as
+  // "not signed in" — correctly, about an environment nobody had asked for.
+  //
+  // Reported from a real WSL2 install, 2026-09-09: the setup wizard's api-key lane, a valid key, and a
+  // sign-in failure the reader could only get past by exporting the key into their own shell.
+  //
+  // A SET, AND THE DUPLICATE IS NOT HYPOTHETICAL. Both engines name the same billing variable, so this
+  // list contains CLEAROTRON_AI_BILLING twice — and the save below is `saved.set(k, process.env[k])`
+  // inside the same loop that writes. On the second visit it saved the value the FIRST visit had just
+  // written, so the restore put that back instead of deleting it, and the mode leaked into the rest of
+  // the process. Caught by the arm that exists to prove the restore, which is the only reason widening
+  // this list was safe to do at all.
+  const keys = [...new Set(["CLEAROTRON_AI", ...Object.values(ENGINE_BINARIES)
+    .flatMap((s) => [s.env, s.authEnv, s.apiKeyEnv, s.headless?.tokenEnv])
+    .filter(Boolean)])];
   const saved = new Map();
   for (const k of keys) {
     saved.set(k, process.env[k]);

package/driver/gateway.mjs

@@ -909,8 +909,8 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
   // until the wall. ONE free rung per ladder is the concession; a second zero-usage warm turn in the
   // same ladder is charged, and the record says so rather than leaving the difference to be inferred.
   //
-  // PROVISIONAL, and deliberately one line to change: the number below is a routed parameter (2026-08-22,
-  // overwatch), not a measured optimum. Nobody has yet counted how often a second free rung would have
+  // PROVISIONAL, and deliberately one line to change: the number below is a routed parameter (2026-08-22),
+  // not a measured optimum. Nobody has yet counted how often a second free rung would have
   // converted, and until someone does, 1 is the smallest concession that closes the defect.
   //
   // THE CHARGING BRANCH CANNOT FIRE TODAY, and that is stated rather than left to be discovered. `warm`

package/driver/outbox-backoff.mjs

@@ -274,7 +274,7 @@ export function settleProgress(agent, now = Date.now()) {
 // disposed of on the box.
 //
 // **Owner ruling, 2026-08-24, SUPERSEDING THIS SWEEP'S HALF OF IT: failed runs' notification packets get
-// the same re-drop cover as delivered ones.** (Relayed by role-overwatch.)
+// the same re-drop cover as delivered ones.**
 //
 // BOTH ARE KEPT BECAUSE BOTH ARE STILL TRUE, and reading them as a reversal is the mistake to avoid. A
 // failed run owes the CLIENT no report — that is 2026-08-22, and `scripts/e2e.mjs`'s delivery assertion

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {