clearotron 0.4.0 → 0.4.1-beta.1

package/driver/engine/mcp/supplemental.mjs

@@ -57,6 +57,31 @@ const compactProposal = (p) => ({
 const inPriority = (p, prio) =>
   (Array.isArray(p?.nice_classes) ? p.nice_classes : []).some((c) => prio.has(String(c).trim()));
 
+// A SOUND-ALIKE BATCH GOES AS LISTS where the register takes one (`phoneticOrWidth`, ruled 2026-10-09): up to
+// that many spellings per question, within its word budget, each long enough for the ranked search. A
+// spelling below that floor is its own question, as every name of a batch was before. Each list is one
+// question with one receipt row, so a list that crowds or fails takes no other list down with it. PURE.
+function splitBatch(p, names, capabilities) {
+  const { terms: _batch, ...rest } = p;
+  const single = (t) => ({ ...rest, term: t });
+  const width = Math.floor(Number(capabilities?.phoneticOrWidth));
+  if (String(p?.predicate ?? "") !== "phonetic" || !(width >= 2)) return names.map(single);
+  const floor = Number(capabilities?.rankedMinLength) || 0;
+  const budget = Number(capabilities?.listWordBudget) || Infinity;
+  const words = (t) => t.split(/\s+/).filter(Boolean).length;
+  const folded = (t) => [...t.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/\s+/g, "")].length;
+  const out = [];
+  let list = [];
+  const close = () => { if (list.length) out.push(list.length === 1 ? single(list[0]) : { ...rest, terms: list }); list = []; };
+  for (const t of names) {
+    if (folded(t) < floor) { out.push(single(t)); continue; }
+    if (list.length >= width || list.reduce((n, x) => n + words(x), 0) + words(t) > budget) close();
+    list.push(t);
+  }
+  close();
+  return out;
+}
+
 export function mintSupplementalEntries(axis, proposals, { existingQids = new Set(), perCall = Infinity, axisMax = Infinity, existingCount = 0, capabilities = null, priorityClasses = [] } = {}) {
   const minted = [], reused = [], rejected = [], enriched = [], narrowed = [];
   let budget = Math.max(0, axisMax - existingCount);
@@ -82,7 +107,7 @@ export function mintSupplementalEntries(axis, proposals, { existingQids = new Se
     const names = perName && Array.isArray(p?.terms) ? p.terms.map((t) => String(t ?? "").trim()).filter(Boolean) : [];
     const splitOf = names.length > 1 && names.length <= PLAN_MAX_OR_WIDTH
       ? fingerprint({ axis, predicate: String(p?.predicate ?? "default"), names: [...names].sort(), i }) : null;
-    const byName = splitOf ? names.map((t) => { const { terms: _batch, ...rest } = p; return { ...rest, term: t }; }) : [p ?? {}];
+    const byName = splitOf ? splitBatch(p, names, capabilities) : [p ?? {}];
     return byName.flatMap((q) => {
       const words = perWord && Array.isArray(q?.goods_words) ? q.goods_words.map((w) => String(w ?? "").trim()).filter(Boolean) : [];
       return words.length > 1

package/driver/engine/openai-agent.mjs

@@ -24,6 +24,7 @@
 
 import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync, readFileSync, readdirSync, statSync, symlinkSync, lstatSync, realpathSync } from "node:fs";
 import { everyToolCallRefused } from "./tool-refusal.mjs";
+import { newSessionRecord, noteCodexEvent, sessionSummary, countTool, streamSink, codexEnding } from "./session-record.mjs";   // what the session went through, beside how it ended
 import { writeSecretFile } from "../../shared/secret-file.mjs";   // the rotated login goes back the way every credential is written
 import { tmpdir, homedir } from "node:os";
 import { join, dirname, sep } from "node:path";
@@ -38,11 +39,28 @@ import { resolveEngineProgram } from "../driver.config.mjs";   // — the one pl
 const codexBin = () => { const r = resolveEngineProgram("openai-agent"); return r.resolved ?? r.bin; };
 
 // tier/alias → codex `-m` model id. opus/sonnet/haiku are the driver's abstract tiers (CONTRACT §3). The
-// GPT ids are ENV-OVERRIDABLE and default to three DISTINCT rungs of the codex ladder — `gpt-5.6-sol`,
-// `gpt-5.6-terra`, `gpt-5.6-luna`, all present in the codex CLI as installed — so an out-of-the-box run
+// GPT ids are ENV-OVERRIDABLE and default to the vendor's current models — `gpt-6.1-sol` for the judgment
+// and sweep tiers, `gpt-6-luna` for the cheap tier (the GPT-6 ladder, below) — so an out-of-the-box run
 // uses REAL, current ids rather than invented guesses, and a stage's declared tier means the same thing
-// on both engines. `sol` remains what codex itself reports as its own default (live-probed 2026-07-27:
-// `model: gpt-5.6-sol, provider: openai`), which is why the judgment tier keeps it.
+// on both engines. Until 2026-10-09 they were `gpt-5.6-sol`, `gpt-5.6-terra` and `gpt-5.6-luna`; `sol`
+// was what codex itself reported as its own default (live-probed 2026-07-27: `model: gpt-5.6-sol,
+// provider: openai`), which is why the judgment tier kept it.
+//
+// ── THE GPT-6 LADDER (ruling 2026-10-09) ────────────────────────────────────────────────────────────────
+//
+// The owner asked for the latest models on both engines, cheaper and faster. The vendor's price list,
+// read 2026-10-09 (standard tier, per million tokens in / out): `gpt-6.1-sol` $2 / $10, `gpt-6-luna`
+// $0.10 / $0.50, `gpt-6-astra` $10 / $50. The 5.6 ladder it replaces was sol $4 / $20, terra $2 / $12,
+// luna $0.20 / $1.20. There is no GPT-6 middle model and Sol 6.1 costs less than Terra 5.6, so the sweep
+// tier takes Sol as well; Astra is the premium model, neither cheaper nor faster, and is not a rung.
+//
+// THE CODEX FLOOR MOVED WITH IT. On ChatGPT-account sign-in (subscription billing) codex 0.156.1, 0.157.0
+// and 0.158.0 refuse `gpt-6.1-sol` with a 400 — "not supported when using Codex with a ChatGPT account" —
+// and 0.159.0 to 0.162.0 accept it; `gpt-6-luna` is accepted from 0.156.1. Measured 2026-10-09 with
+// one-word turns on the test box. Below 0.159.0 the judgment tier stops at its first stage, so the floor
+// in ENGINE_BINARIES (driver.config.mjs) is 0.159.0.
+//
+// The August measurement below still names the symptom to watch for when a tier moves to a cheaper model.
 //
 // ── THE THREE TIERS MAP ONTO THE CODEX LADDER (ruling 2026-09-02,) ──────────────────────────
 //
@@ -89,9 +107,9 @@ const codexBin = () => { const r = resolveEngineProgram("openai-agent"); return
 // runs SOMETHING is worse than one that refuses: the arm still produces a number and the number is a
 // story. They fall through to the throw below, which is where they always should have been. Concrete
 // gpt-*/o* ids still pass through.
-const JUDGMENT = process.env.CLEAROTRON_OPENAI_MODEL_JUDGMENT || "gpt-5.6-sol";     // opus   — unchanged
-const SWEEP    = process.env.CLEAROTRON_OPENAI_MODEL_SWEEP    || "gpt-5.6-terra";   // sonnet — was sol
-const CHEAP    = process.env.CLEAROTRON_OPENAI_MODEL_CHEAP    || "gpt-5.6-luna";    // haiku  — was sol
+const JUDGMENT = process.env.CLEAROTRON_OPENAI_MODEL_JUDGMENT || "gpt-6.1-sol";   // opus   — was gpt-5.6-sol
+const SWEEP    = process.env.CLEAROTRON_OPENAI_MODEL_SWEEP    || "gpt-6.1-sol";   // sonnet — was gpt-5.6-terra
+const CHEAP    = process.env.CLEAROTRON_OPENAI_MODEL_CHEAP    || "gpt-6-luna";    // haiku  — was gpt-5.6-luna
 const OPENAI_MODEL = { opus: JUDGMENT, sonnet: SWEEP, haiku: CHEAP };
 export function openaiModel(model) {
   if (!model) return undefined;
@@ -311,8 +329,10 @@ export function parseCodexEvent(line, ev) {
   switch (e?.type) {
     case "thread.started": if (e.thread_id) ev.threadId = e.thread_id; break;
     case "turn.completed": ev.turnCompleted = true; if (e.usage) ev.usage = e.usage; break;
-    case "turn.failed":    ev.turnFailed = e.error?.message || "turn.failed"; break;
-    case "error":          ev.streamError = e.message || "stream error"; break;
+    // The program's own words are kept apart from the placeholders, so the record never shows a word of
+    // ours where it said nothing (session-record.mjs, codexEnding).
+    case "turn.failed":    ev.turnFailed = e.error?.message || "turn.failed"; ev.turnFailedText = typeof e.error?.message === "string" ? e.error.message : null; break;
+    case "error":          ev.streamError = e.message || "stream error"; ev.streamErrorText = typeof e.message === "string" ? e.message : null; break;
     case "item.completed":
       if (e.item?.type === "agent_message" && typeof e.item.text === "string") ev.agentText = e.item.text;
       // A FILE CHANGE CODEX ITSELF REPORTS AS FAILED. Measured on codex-cli 0.156.1 with its sandbox unable
@@ -330,6 +350,7 @@ export function parseCodexEvent(line, ev) {
           ev.commandFailures.push({ command: String(e.item.command ?? ""), output: String(e.item.aggregated_output ?? "") });
       }
       noteMcpToolCall(e.item, ev);
+      noteToolItem(e.item, ev);
       break;
     // ── — AN MCP CALL THAT WAS REFUSED IS NOT A CALL NOBODY MADE ──────────
     //
@@ -352,6 +373,7 @@ export function parseCodexEvent(line, ev) {
     // would double every call.
     case "item.started":
       noteMcpToolCall(e.item, ev);
+      noteToolItem(e.item, ev);
       break;
     default: break;
   }
@@ -377,6 +399,57 @@ export function noteMcpToolCall(item, ev) {
   });
 }
 
+// The item kinds codex reports a tool call as, besides its MCP calls. Its own words, measured on
+// codex-cli 0.150–0.158: a shell command, a file edit, a web search.
+const TOOL_ITEM_KINDS = new Set(["command_execution", "file_change", "web_search"]);
+
+/**
+ * Remember one tool-shaped item by id, for the per-name count. Codex writes each item twice (started,
+ * then its terminal state) under one id, so the id is the unit, exactly as for the MCP gauge.
+ */
+export function noteToolItem(item, ev) {
+  if (!item?.id) return;
+  const name = item.type === "mcp_tool_call" ? `mcp__${item.server ?? "?"}__${item.tool ?? "?"}`
+    : TOOL_ITEM_KINDS.has(item.type) ? item.type : null;
+  if (!name) return;
+  (ev.toolItems ??= new Map()).set(item.id, name);
+}
+
+/**
+ * The turn's tool calls by name, in the shape anthropic-agent records: an MCP call under
+ * `mcp__<server>__<tool>`, and codex's own tool items under its own word for them. Counted once per item
+ * id. An OBJECT is a measurement (`{}` = none observed).
+ */
+export function codexToolCallsByName(ev) {
+  const byName = Object.create(null);
+  for (const name of ev?.toolItems?.values() ?? []) countTool(byName, name);
+  return { ...byName };
+}
+
+/**
+ * The commands codex ran this turn: its `command_execution` items, counted once per item id, a failed one
+ * included, since a command that exited non-zero still ran. A NUMBER is a measurement (0: none ran). PURE.
+ */
+export function codexCommandCalls(ev) {
+  let n = 0;
+  for (const name of ev?.toolItems?.values() ?? []) if (name === "command_execution") n += 1;
+  return n;
+}
+
+/**
+ * The tool-server calls of this turn that came back as an error, by tool name, in the shape
+ * anthropic-agent records: a call that reached its server and `failed` there, which codex writes with no
+ * `error.message` (a call codex refused itself carries one, and `toolCallsRefused` counts those). Counted
+ * once per item id. An OBJECT is a measurement (`{}`: none). PURE.
+ */
+export function codexToolServerErrors(ev) {
+  const byName = Object.create(null);
+  for (const c of ev?.mcpCalls?.values() ?? []) {
+    if (c.status === "failed" && !c.message) countTool(byName, `mcp__${c.server ?? "?"}__${c.tool ?? "?"}`);
+  }
+  return { ...byName };
+}
+
 /**
  * The MCP tool-call gauge for this turn: what completed, what was REFUSED, and why.
  *
@@ -540,11 +613,16 @@ function settleTuple({ r, ev, resumeRef }) {
   const failed = overflow || killed || !ev.turnCompleted || !!ev.turnFailed;
   const usage = mapUsage(ev.usage);
   const text = ev.agentText || "";
-  const json = buildEnvelope({
-    text, ok: !failed, killed, usage,
-    summary: ev.turnFailed ? "failed" : (ev.turnCompleted ? "success" : undefined),
-    runId: ev.threadId,
-  });
+  const json = {
+    ...buildEnvelope({
+      text, ok: !failed, killed, usage,
+      summary: ev.turnFailed ? "failed" : (ev.turnCompleted ? "success" : undefined),
+      runId: ev.threadId,
+    }),
+    // What ended the turn, in the program's own words when it failed (session-record.mjs, codexEnding):
+    // the same three fields the Claude adapter writes. Recorded only; `ok` above is unchanged.
+    ...codexEnding(ev),
+  };
   const stderrOut = overflow
     ? (r.stderr + `\nopenai-agent output overflow: stdout/stderr exceeded ${r.maxBuffer} chars — killed the tree and failed the turn (truncated tail never parsed)`)
     : (stallKill ? (r.stderr + "\nrequest timed out (openai-agent stall-watchdog: 0 streamed tokens)") : r.stderr);
@@ -585,10 +663,14 @@ function settleTuple({ r, ev, resumeRef }) {
     // still cannot report a whole-turn tool count, so `toolCalls` stays null, which is the house rule
     // for "this engine does not report" rather than "it called nothing".
     ...mcpToolGauge(ev),
-    // The refused count under the name the attempt row reads on both engines. Codex keeps its shell, and this
-    // adapter reads its commands only for failures (below), so it reports no command-tool count: null, never zero.
+    // The refused count under the name the attempt row reads on both engines. Codex keeps its shell, and every
+    // command it runs is a `command_execution` item: counted once per item id, failed ones included.
     toolCallsRefused: mcpToolGauge(ev).mcpToolCallsRefused,
-    commandToolCalls: null,
+    commandToolCalls: codexCommandCalls(ev),
+    // The per-name split of the calls codex reports (see codexToolCallsByName), what the session went
+    // through (session-record.mjs: every turn ending and stream error, in order), and the raw stream.
+    toolCallsByName: codexToolCallsByName(ev), toolCallsErroredByName: codexToolServerErrors(ev),
+    session: sessionSummary(ev.session), stream: ev.stream ?? null,
     writesFailed: ev.writesFailed ?? 0,
     commandsFailed: ev.commandsFailed ?? 0,
     commandFailures: ev.commandFailures ?? [],
@@ -624,6 +706,8 @@ function errResult(t0, e, resumeRef) {
     code: 1, killed: false, wall: (Date.now() - t0) / 1000, stdout: "",
     stderr: `openai-agent error: ${e?.message ?? e}`, laneWaitMs: 0,
     json: null, usage: null, modelWire: null, sessionRef: resumeRef ?? null,
+    // No session ran: nothing to have been interrupted, no stream.
+    toolCallsByName: null, toolCallsErroredByName: null, session: null, stream: null,
   };
 }
 
@@ -652,7 +736,7 @@ export const openaiAgentEngine = {
   // `thread/resume failed: no rollout found for thread id ... (code -32600)`, exit 1 — with the control
   // (same id, same binary, its own home) resuming cleanly. So every warm-patch retry and every
   // form-repair sub-turn on the codex arm has been failing.
-  async runTurn({ message, model, thinking, timeoutSec, resumeRef, mcpConfig, allowedTools, cwd, skillsDir, skillsGrantRoots, profilesDir, resolveSkill, runDir, stallSec, codexHome: providedHome } = {}) {
+  async runTurn({ message, model, thinking, timeoutSec, resumeRef, mcpConfig, allowedTools, cwd, skillsDir, skillsGrantRoots, profilesDir, resolveSkill, runDir, stallSec, codexHome: providedHome, streamFile = null } = {}) {
     if (!message) throw new Error("openai-agent.runTurn: message is required");
     const t0 = Date.now();
     let codexHome;
@@ -703,16 +787,25 @@ export const openaiAgentEngine = {
       // Stamped HERE, not at function entry: everything above is file writes that can take a moment, and
       // a floor set too early would let a previous turn's rollout back in on a shared home.
       const spawnedAtMs = Date.now();
-      const ev = { threadId: null, usage: null, agentText: "", turnCompleted: false, turnFailed: null, streamError: null, model: null, mcpCalls: new Map() };
+      const ev = { threadId: null, usage: null, agentText: "", turnCompleted: false, turnFailed: null, streamError: null, model: null, mcpCalls: new Map(),
+        session: newSessionRecord() };
+      // The raw stream, one file per session beside its dispatch; every line codex wrote on stdout.
+      const sink = streamSink(streamFile);
       const r = await runStreamingChild({
         bin: codexBin(), args, input, runDir,
         // — the run dir, not a shared tmpdir. codex makes cwd a workspace root, writable under the
         // stage's profile, so this tightens the writable surface onto the run rather than widening it.
         cwd: resolveSpawnCwd({ cwd, runDir }),
         env, stallSec, timeoutSec,
-        onStdoutLine: (line) => parseCodexEvent(line, ev),
+        onStdoutLine: (line) => {
+          sink.write(`${line}\n`);
+          parseCodexEvent(line, ev);
+          let e; try { e = JSON.parse(line); } catch { return; }
+          noteCodexEvent(ev.session, e, Date.now() - t0);
+        },
         stderrIsLiveness: true,   // codex streams progress on STDERR → it is liveness for the stall watchdog
       });
+      ev.stream = sink.close();
       if (r.spawnError) return errResult(t0, r.spawnError, resumeRef);
       // The stream said no model (it never does — see readServedModel); the rollout under THIS run's
       // CODEX_HOME did. Read here, inside the try, because the finally below deletes that dir.

package/driver/engine/session-record.mjs

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// engine/session-record.mjs — what a model session went through, kept beside what it ended with.
+//
+// ── why this exists ──────────────────────────────────────────────────────────────────────────────────
+//
+// Both engines read the program's stream in memory and kept the LAST result. A session the vendor's
+// classifier cut off mid-answer, or one the API refused and a restart recovered, ended in an ordinary
+// successful result and was recorded as a clean session. A cut drops the tool calls that had not
+// finished, so a stage that lost calls mid-answer looked exactly like one that finished.
+//
+// Measured on the bench's saved-data replays (2026-09-28, 50 Claude sessions): 23 were cut and carried
+// on; in 8 the API then refused; one of the 8 still answered, because a background helper restarted the
+// session and the last result was a success. The program's own words for each event, read off a saved
+// stream with the content left out:
+//
+//   cut          a `user` event, `isSynthetic: true`, whose text block says the response "was stopped by
+//                a safety classifier"
+//   refusal      a `system` event, subtype `model_refusal_no_fallback`, carrying `api_refusal_category`
+//                and `original_model`; then an `assistant` message with `stop_reason: "refusal"`
+//   restart      a second `system` / `init` event in the same stream
+//   results      one `result` event per answer, each with `result_index`, `is_error`, `stop_reason`,
+//                `terminal_reason` and, for one a helper's notice started, `origin.kind`
+//
+// So nothing here is inferred: every row is an event the program wrote, with when it arrived. The
+// record answers "was this session interrupted, refused or restarted, and when" from the run directory,
+// and it never decides anything — the retry policy reads the last result exactly as before.
+//
+// ── what is NOT recorded ─────────────────────────────────────────────────────────────────────────────
+//
+// No text in the session record. The cut message, the refusal's explanation and every result's answer
+// carry the model's or the vendor's words about client matter; a row carries the event's kind, its time
+// and its codes. The raw stream, which does carry the words, goes to its own file in the run directory
+// (streamSink below), where the dispatch text already sits.
+//
+// ONE EXCEPTION, and it sits beside the record rather than in it: when a session ENDED IN AN ERROR, the
+// program's own words for that error go on the attempt row (`errorText`, see "how the session ended"
+// below). An expired sign-in recorded `stop_sequence` six times and nothing else, while the program had
+// said in plain words that the session had expired. On a healthy ending that field is the model's answer
+// and stays off the row.
+
+import { mkdirSync, openSync, writeSync, closeSync, statfsSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** The program's words for a classifier cut, as it writes them into the session. Matched, never quoted. */
+export const CLASSIFIER_CUT_RE = /stopped by a safety classifier/i;
+
+// A row list is a record, not a log: a session that is cut fifty times has said what it needs to say by
+// the fiftieth, and the count beside the list keeps saying how many there were.
+const ROWS_CAP = 50;
+
+/** An empty record. `starts` counts the program's own session starts (`system`/`init`). */
+export function newSessionRecord() {
+  return { starts: 0, results: [], classifierCuts: [], refusals: [], refusalStops: 0, dropped: 0 };
+}
+
+const push = (rec, list, row) => {
+  if (list.length < ROWS_CAP) list.push(row);
+  else rec.dropped += 1;
+};
+
+/** The text a `user` event carries outside its tool results: a string, or its `text` blocks. */
+function userText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+}
+
+/**
+ * Fold one parsed Claude stream event into the record. `atMs` is milliseconds since the spawn. PURE
+ * over its arguments; the caller owns the clock.
+ */
+export function noteClaudeEvent(rec, ev, atMs) {
+  if (!rec || !ev || typeof ev !== "object") return;
+  if (ev.type === "system" && ev.subtype === "init") { rec.starts += 1; return; }
+  if (ev.type === "system" && ev.subtype === "model_refusal_no_fallback") {
+    push(rec, rec.refusals, {
+      atMs, category: typeof ev.api_refusal_category === "string" ? ev.api_refusal_category : null,
+      model: typeof ev.original_model === "string" ? ev.original_model : null,
+    });
+    return;
+  }
+  if (ev.type === "assistant") {
+    if (ev.message?.stop_reason === "refusal") rec.refusalStops += 1;
+    return;
+  }
+  if (ev.type === "user") {
+    if (CLASSIFIER_CUT_RE.test(userText(ev.message?.content))) push(rec, rec.classifierCuts, { atMs, synthetic: ev.isSynthetic === true });
+    return;
+  }
+  if (ev.type === "result") {
+    push(rec, rec.results, {
+      atMs,
+      index: Number.isFinite(ev.result_index) ? ev.result_index : rec.results.length + rec.dropped,
+      subtype: typeof ev.subtype === "string" ? ev.subtype : null,
+      isError: ev.is_error === true,
+      stopReason: typeof ev.stop_reason === "string" ? ev.stop_reason : null,
+      terminalReason: typeof ev.terminal_reason === "string" ? ev.terminal_reason : null,
+      origin: typeof ev.origin?.kind === "string" ? ev.origin.kind : null,
+    });
+  }
+}
+
+/**
+ * Fold one parsed Codex `exec --json` event into the record. Codex states no refusal category and no
+ * classifier cut on its stream (measured, codex-cli 0.150–0.158), so what it can say is said: how the
+ * turn ended, every time it ended, and every stream error.
+ */
+export function noteCodexEvent(rec, ev, atMs) {
+  if (!rec || !ev || typeof ev !== "object") return;
+  if (ev.type === "thread.started") { rec.starts += 1; return; }
+  if (ev.type === "turn.completed" || ev.type === "turn.failed" || ev.type === "error") {
+    push(rec, rec.results, {
+      atMs, index: rec.results.length + rec.dropped, subtype: ev.type,
+      isError: ev.type !== "turn.completed", stopReason: null, terminalReason: null, origin: null,
+    });
+  }
+}
+
+/** True when any result the session reached was an error, whatever the last one said. */
+export const anyResultErrored = (rec) => Array.isArray(rec?.results) && rec.results.some((r) => r?.isError === true);
+
+/**
+ * The record as the attempt row carries it. `interrupted` is the one-word answer a reader filters on: the
+ * session was cut, refused, restarted, or reached an error result, at least once.
+ */
+export function sessionSummary(rec) {
+  if (!rec) return null;
+  const interrupted = rec.classifierCuts.length > 0 || rec.refusals.length > 0 || rec.refusalStops > 0
+    || rec.starts > 1 || anyResultErrored(rec);
+  return {
+    interrupted, starts: rec.starts, results: rec.results.map((r) => ({ ...r })),
+    classifierCuts: rec.classifierCuts.map((r) => ({ ...r })), refusals: rec.refusals.map((r) => ({ ...r })),
+    refusalStops: rec.refusalStops, ...(rec.dropped ? { rowsDropped: rec.dropped } : {}),
+  };
+}
+
+// ── how the session ended, in the program's own words ──────────────────────────────────────────────────
+//
+// The stop reason alone misleads on an error. Measured on an expired sign-in: the Claude program reported
+// `subtype: "success"`, `is_error: true`, `stop_reason: "stop_sequence"` (the stop of its OWN synthetic
+// message, whose model reads `<synthetic>`) and `terminal_reason: "api_error"`, with the reason in the
+// result text: "Failed to authenticate: OAuth session expired and could not be refreshed". Six retries of
+// one stage journalled six identical `stop_sequence` rows and said nothing about why. The stop reason stays
+// verbatim, because on an error it describes the program's synthetic message and rewriting it would be
+// inventing; these three go beside it, on both engines:
+//
+//   terminalReason   the kind of ending, as the program states it. null when it states none (Codex never does).
+//   apiErrorStatus   the vendor's status when it gave one. null when it did not, which is not zero.
+//   errorText        the program's words for the error, ONLY when the session ended in one, cut to a length a
+//                    person reads. Never a word of ours in their place: an error that carried none reads null.
+//
+// The verdict does not move: `fail`, the retry ladder and the envelope's status read exactly what they
+// read before. These record; they decide nothing.
+export const ERROR_TEXT_CAP = 300;
+
+const words = (t) => (typeof t === "string" && t.trim() ? t.slice(0, ERROR_TEXT_CAP) : null);
+
+/** Claude: from the session's LAST result event (the one the verdict reads), or nulls when none arrived. */
+export function claudeEnding(resultEvent) {
+  const r = resultEvent && typeof resultEvent === "object" ? resultEvent : null;
+  return {
+    terminalReason: typeof r?.terminal_reason === "string" ? r.terminal_reason : null,
+    apiErrorStatus: r?.api_error_status ?? null,
+    errorText: r?.is_error === true ? words(r.result) : null,
+  };
+}
+
+/**
+ * Codex: no terminal kind and no status on its stream. Its words are the failed turn's own message, or the
+ * stream error when the turn never completed; an `error` it recovered from (a reconnect, then a completed
+ * turn) is not why it ended. Reads the raw messages `parseCodexEvent` keeps, never its placeholders.
+ */
+export function codexEnding(ev) {
+  const failed = ev?.turnFailedText ?? null, stream = ev?.streamErrorText ?? null;
+  const said = ev?.turnFailed ? words(failed) : (ev?.turnCompleted ? null : words(stream));
+  return { terminalReason: null, apiErrorStatus: null, errorText: said };
+}
+
+/** The three as an attempt row carries them: written every time, null where the engine said nothing. */
+export function endingFields(json) {
+  return { terminalReason: json?.terminalReason ?? null, apiErrorStatus: json?.apiErrorStatus ?? null, errorText: json?.errorText ?? null };
+}
+
+/** A per-tool-name call count, folded one name at a time. */
+export function countTool(byName, name) {
+  const k = String(name ?? "?") || "?";
+  byName[k] = (byName[k] ?? 0) + 1;
+}
+
+// ── the raw stream ───────────────────────────────────────────────────────────────────────────────────
+//
+// Every byte the program wrote on its protocol channel, one file per session, beside the dispatch that
+// started it. Kept while the disk holding the run has room: below STREAM_FLOOR_BYTES free it is not
+// written, and the record says so rather than leaving a file that stops halfway. A write that fails
+// mid-session closes the file and says so too. Neither ever fails the turn.
+export const STREAM_FLOOR_BYTES = 5 * 1024 ** 3;
+
+/**
+ * Open a sink for `file`. Returns `{ write(chunk), close() }`; `close()` returns what landed:
+ * `{ file, bytes, present: true }`, or `{ file, present: false, reason }`. A null file is a null sink.
+ */
+export function streamSink(file, { floorBytes = STREAM_FLOOR_BYTES, freeBytes = null } = {}) {
+  if (!file) return { write() {}, close: () => null };
+  let fd = null, bytes = 0, reason = null;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    const free = freeBytes ?? (() => { const s = statfsSync(dirname(file)); return Number(s.bavail) * Number(s.bsize); })();
+    if (free < floorBytes) reason = `not written: the disk holding the run had ${Math.round(free / 1024 ** 2)} MiB free, under the ${Math.round(floorBytes / 1024 ** 3)} GiB floor`;
+    else fd = openSync(file, "w", 0o600);
+  } catch (e) { reason = `not written: ${String(e?.message ?? e).slice(0, 120)}`; }
+  return {
+    write(chunk) {
+      if (fd === null) return;
+      try { bytes += writeSync(fd, typeof chunk === "string" ? chunk : Buffer.from(chunk)); }
+      catch (e) { try { closeSync(fd); } catch { /* already gone */ } fd = null; reason = `cut short after ${bytes} bytes: ${String(e?.message ?? e).slice(0, 120)}`; }
+    },
+    close() {
+      if (fd !== null) { try { closeSync(fd); } catch { /* the bytes are on disk or they are not; bytes says which */ } fd = null; }
+      return reason ? { file, present: bytes > 0, bytes, reason } : { file, present: true, bytes };
+    },
+  };
+}

package/driver/enqueue-schema.mjs

@@ -730,8 +730,8 @@ export function validateJob(job, { atClaim = false } = {}) {
     warnings.push(...fit.warnings);
   }
   // platforms — marketplaces to sweep IN ADDITION to the account's own. ADDITIVE ONLY, and enforced as
-  // such where the union happens: a client's platforms are a client MANDATE (the 2026-07-18 Racers
-  // Paradise run searched house platforms instead of the client's), so a per-run list can widen the grid
+  // such where the union happens: a client's platforms are a client MANDATE (the 2026-07-18 Drivers
+  // Haven run searched house platforms instead of the client's), so a per-run list can widen the grid
   // and can never shrink it. Same per-entry rules as a profile's, shared via platformEntryErrors.
   if (job.platforms != null) {
     if (!Array.isArray(job.platforms)) errs.push("platforms must be an array of bare store domains (e.g. [\"gnc.com\"]) — they are ADDED to the account's marketplaces, never a replacement for them");

package/driver/findings-model.mjs

@@ -1780,7 +1780,7 @@ function validateNet(f, ord, mode) {
 //     `findings?_` and would aim the repair turn at register-coverage-ledger.json — forbidding the model
 //     to rewrite the only file that could fix it.
 // It reaches the wire as a validator `reason` (verify.mjs checkFindingsSibling), which is the only shape
-// gateway.mjs:525 mints as `invalid_file:<path>:<token>`; a bespoke throw would match nothing.
+// gateway.mjs:1200 judgeArtifacts mints as `invalid_file:<path>:<token>`; a bespoke throw would match nothing.
 // The precedent is one line up the file: findings_mark_assessment_* was named plural for the same
 // routing reason.
 //
@@ -1942,14 +1942,14 @@ function recordUrlOrigin(value) {
  *. `checkRecordUrlHost` asks whether a link points at the wrong register, and `recordUrlOrigin`
  * returns null for anything with no host — so the host gate returns CLEAN for `#`. That is right for its
  * own purpose and it means nothing in the findings path was asking whether the link is a link. A value of
- * `#` then composes `- Source: [EUIPO · 018575624](#)` — the delivered R5 shape is about, byte for
+ * `#` then composes `- Source: [EUIPO · 099999992](#)` — the delivered R5 shape is about, byte for
  * byte, reached through a path nothing rejected.
  *
  * ABSENT IS NOT DEAD, and the distinction is the whole predicate. `null` and `""` are the sanctioned way
  * to say "this provider publishes no per-record page" — validateSource documents `""` in its own message
  * and renderSourceBullet composes nothing for it. Rejecting those would break the legitimate case this
  * issue exists to protect. Anything else that is not an http(s) URL is a value a seat typed in place of a
- * link: `#`, `#details/trademarks/018575624`, a bare path, or whitespace that only looks like a value.
+ * link: `#`, `#details/trademarks/099999992`, a bare path, or whitespace that only looks like a value.
  *
  * IT ENUMERATES RATHER THAN ASKING "IS THIS AN http(s) URL", and a shipped test is why. ` an
  * unparseable or non-http value is not a host claim and is left to the shape rules` deliberately ACCEPTS
@@ -2179,7 +2179,7 @@ export function projectCoverageJudgment(cj) {
   const rows = Array.isArray(cj.rows) ? cj.rows : [];
   if (!rows.length) return cj;
   // — the READER's name leads, and falls back to the identifier when the driver had nothing to
-  // add. This string is printed on report.html ("Coverage read"), which is why it reads the label.
+  // add. renderHtml receives this string and leaves it off report.html, so no page prints it; the label leads anyway.
   const shown = rows.slice(0, COVERAGE_JUDGMENT_ROW_CAP);
   const hidden = rows.length - shown.length;
   const rowText = shown.map((r) => `${trimDot(r.areaLabel || r.area)}: ${trimDot(r.note)}`).join("; ");

package/driver/flag-snapshot.mjs

@@ -425,7 +425,8 @@ export function registerCanCountFor(snapshot) {
  *
  * The trap is `covered ?? []`, which turns both "unrestricted" and "unknown" into "nothing" and offers
  * a client zero territories on a production deployment. It is written down at
- * providers/corsearch/src/capabilities.js:66-68 as well: "Never read as 'covers nothing'".
+ * the `covered` entry of CAPABILITIES in providers/corsearch/src/capabilities.js as well: "Never read as
+ * 'covers nothing'".
  */
 export function registerTerritoriesFor(snapshot) {
   if (!snapshot?.register || !("territories" in snapshot.register)) return undefined;

package/driver/form-neighbourhood.mjs

@@ -288,8 +288,8 @@ export function formNeighbourhood(element, { markets = [], scripts = SUPPORTED_S
 
   // exactQueries = the strings dispatched as OR-stacked exact/near name searches (deduped, original excluded).
   //
-  // Deduped ON THE DIACRITIC FOLD, not the raw string. The registers fold diacritics, so `paradisè`,
-  // `paradisé`, `paradisê`, `paradisë` and `paradiše` are ONE query, not five — and one already covered by the
+  // Deduped ON THE DIACRITIC FOLD, not the raw string. The registers fold diacritics, so `havensidè`,
+  // `havensidé`, `havensidê`, `havensidë` and `havenšide` are ONE query, not five — and one already covered by the
   // element itself. Drivers Haven 2026-07-17 dispatched exactly those five as distinct terms; each returned
   // the same 424 hits, together they exhausted the run's record budget, all five stayed `unenumerated`, and
   // `coverage_clean_unverified_incomplete:primary-sweep` then blocked delivery six times on a gate that could
@@ -399,8 +399,8 @@ export function coverageGaps(band, { dispatched = [], explained = [] } = {}) {
 // `model` is the VALIDATED variant-manifest.json (variant-manifest-model.mjs). When supplied it is
 // AUTHORITATIVE for the dominant element and the prose is used only for the formative root — because the prose
 // parse is unsafe. `dominantElementFromManifest` captures to the first `.`/`;`/`(`/newline, so a manifest that
-// writes "Dominant element: HYDRA — the stem a family of marks shares" yields the whole clause, which
-// normalizeElement then compacts to `hydrathestemafamilyofmarksshares`. That pseudo-element got a full
+// writes "Dominant element: AQUA — the stem a family of marks shares" yields the whole clause, which
+// normalizeElement then compacts to `aquathestemafamilyofmarksshares`. That pseudo-element got a full
 // exhaustive edit-1 neighbourhood: 1,736 junk exact queries on AquaPlus 2026-07-17, 4,524 on the 07-16 run.
 // Measured 2026-07-18: 10 of 20 recent runs carried one of these. The JSON field is a validated scalar and
 // cannot swallow a sentence.
@@ -478,7 +478,7 @@ export function renderFormNeighbourhoodJson(manifestMd, { markets = [], scripts
 // line variantCompletenessGaps' per-script floor draws when it says it VALIDATES, NEVER GENERATES.
 
 // A seed longer than this is a prose-parse artifact, not an element. The measured shape is the
-// swallowed clause — "hydrathestemafamilyofmarksshares", 32-36 characters against a 5-char element —
+// swallowed clause — "aquathestemafamilyofmarksshares", 31-35 characters against a 4-char element —
 // which took a full exhaustive edit-1 neighbourhood and put 1,736 junk exact queries on the wire
 // (AquaPlus 2026-07-17). isStemOfNamedElement already rejects that shape for the formative root by
 // measuring it against the named elements; this is the same measure for a seed with nothing to
@@ -691,7 +691,7 @@ export function variantFloorFamilies(elements, { mark = "", droppedAxes = [], mi
       // MEASURED, not assumed (2026-08-03): the register compiler's `norm` and the shared `formKey`
       // both strip separators, so every member of this family keys IDENTICALLY to the mark and is
       // already searched as the mark's own exact entry — which is why compileRegisterPlan does not
-      // re-dispatch them, and why doing so would be the PARADISE shape (five spellings, one result
+      // re-dispatch them, and why doing so would be the Drivers Haven shape (five spellings, one result
       // set, the run's record budget spent). Enumerated here because the family is genuinely
       // mechanical and the surfaces that do NOT fold spacing — the common-law grid, the connotation
       // sweep — are real; those consumers are NOT wired to it by this change.
@@ -794,7 +794,7 @@ export function mergeVariantFloor(floorFamilies, modelVariants, { rejectedSeeds
 /**
  * Is `root` a plausible formative root, or a prose-parse artifact?
  *
- * A stem is never LONGER than the element it stems from — VOLEM(5) for ZOLEMA(6), HYDR(4) for HYDRA(5),
+ * A stem is never LONGER than the element it stems from — VOLEM(5) for ZOLEMA(6), AQU(3) for AQUA(4),
  * VELTRI(6) for VELTRIN(7). Substring containment is NOT the test: a real root can differ in its leading
  * character (ZOLEMA → VOLEM reaches the VOLEMA family), which is exactly the widening the root exists for.
  * The swallowed-sentence artifacts are always the element PLUS a clause — 32-36 characters against a 5-char

package/driver/frame-diff-model.mjs

@@ -70,7 +70,7 @@ export function parseFrameDiff(raw) {
     if (d.remedy != null) out.remedy = parseRemedy(d.remedy);
     // ── THE ASK CONTRACT AT ASK-RAISE (charter P2e) ───────────────────────────────────────────────
     // A firing directive is a REQUEST TO SEARCH SOMETHING. Until now the parser accepted one whose
-    // item was a display label ("TAKIS (famous cpg snack, …)") with no remedy, and the refusal came
+    // item was a display label ("WAVA (famous cpg snack, …)") with no remedy, and the refusal came
     // hours later at reopen — by which time the session that could have restated it had exited. Four
     // of the five directives on the 2026-07-29 run died exactly there: loud (coverage rows, the clamp,
     // the audit trail) but terminal, with the head noun of a perfect one-query term sitting in the
@@ -143,7 +143,7 @@ export function undispatchableThrow(offenders) {
  * Every FIRING directive in a frame-diff document that cannot be dispatched — read LENIENTLY, from
  * raw text or an already-parsed object. This is the enumeration the gateway hint and the pipeline's
  * exhausted-ladder disclosure both run against the artifact ON DISK, because the fail string they
- * would otherwise scrape is cut at 160 characters (verify.mjs:381) and cannot carry more than the
+ * would otherwise scrape is cut at 160 characters (checkJson() in verify.mjs) and cannot carry more than the
  * first offender. Lenient on purpose: the artifact reaching these two callers has ALREADY failed
  * validation, so it may also carry an unknown key or a bad gap flag — refusing to enumerate then
  * would lose exactly the disclosures this exists to keep. Returns [{item, layer, severity, why}].
@@ -190,7 +190,7 @@ export function firingDirectivesLenient(rawOrDoc) {
  *
  * SCOPE IS DELIBERATELY THE VARIANT LAYER (plus any layer's own remedy):
  *   * VARIANT — the evidenced class. The directive says "search this near-form", so its item stands
- *     where a mark term stands, and a label there ("TAKIS (famous cpg snack, …)") is the whole defect:
+ *     where a mark term stands, and a label there ("WAVA (famous cpg snack, …)") is the whole defect:
  *     it dispatches as a nil search that reads CLEAN, or it dies unasked at reopen.
  *   * FIELD — untouched. A class-gap directive whose item names no parseable class already has a
  *     principled ending: deriveDirectiveRemedy returns null and the directive is DISCLOSED rather