clearotron 0.4.0-beta.3 → 0.4.1-beta.0

package/driver/engine/mcp/recording-server.mjs

@@ -5,7 +5,7 @@
 // ── WHAT THIS CATEGORY IS FOR, AND WHY IT IS NOT A RETRIEVAL GRANT ──────────────────────────────────
 //
 // The two-box model conflates "may reach the outside world" with "may hand back structure"
-// (gather-config.mjs:246-268). A stage converted to a typed return needs the second and not the first.
+// (gather-config.mjs:246-268 RECORDING). A stage converted to a typed return needs the second and not the first.
 // This server carries ONLY the second: it writes the calling stage's own artifact into the calling
 // stage's own run directory, and it dials nothing.
 //
@@ -55,7 +55,7 @@ import { PROVIDERS, REGISTER_PROVIDER } from "../../driver.config.mjs";
 // already written against them; this conversion is the consumption their headers said was still owed.
 import { recordClosures } from "../../doubt-closure-tool.mjs";
 import { MAX_CLOSURES_PER_CALL, CLOSURE_KINDS } from "../../doubt-closure-call.mjs";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs"; import { FROZEN_METHOD_FILE } from "../../framework-method.mjs";
 import { join } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { VARIANT_CATEGORIES } from "../../variant-manifest-model.mjs";
@@ -398,7 +398,7 @@ serve({
               item: {
                 type: "string",
                 description:
-                  "For a FIRING variant directive this must be a mark-shaped search term (TAKIS, CORAL " +
+                  "For a FIRING variant directive this must be a mark-shaped search term (WAVA, CORAL " +
                   "MAGIC) or carry a remedy. A label — a parenthetical, an enumeration, more than about " +
                   "four words — dispatches as a nil search that reads CLEAN, and is refused here.",
               },
@@ -1134,6 +1134,9 @@ serve({
     handler: record_synthesis,
   }, {
     name: "record_knockout_assess",
+    // The framework's `inputs` fields are offered only on a run whose framework states a method: a session
+    // offered a field it may not use can fill it, and the check that refuses it runs after the whole step.
+    schemaNow: (schema) => knockoutAssessSchemaFor(schema, process.env.CLEAROTRON_BAND_RUN_DIR),
     description:
       "Hand back THIS CHUNK's rated assessment as VALUES. The driver serializes knockout-assess-<n>.json, " +
       "so you never format JSON and never write the file. WHICH CHUNK IS NOT YOURS TO SAY — the driver " +
@@ -1392,7 +1395,7 @@ serve({
         },
         batch: {
           type: "object",
-          required: ["productContext", "inUseAs", "places"],
+          required: ["productContext", "inUseAs"],   // places are per name (ruling 570): the batch list is optional, as in the acceptor and the manual
           properties: {
             productContext: { type: "string", description: "One sentence: what the batch is for. Every mark's contextFraming is read against it." },
             inUseAs: { type: "string", description: "The kinds of use off the register that could conflict in this client's field, as one phrase completing \"Is this name already in use as …?\". The places the batch is searched on include the sites where these uses are listed." },
@@ -1439,3 +1442,27 @@ serve({
     handler: record_knockout_frame,
   }],
 });
+
+/**
+ * The knockout save tool's schema for the run this server serves. The framework's `inputs` fields are
+ * offered only where the run's framework states a method, which is when its frozen copy
+ * (`_driver/framework-method.json`) exists: a run with no method has none, since the mint removes it. A
+ * session offered a field it may not use can fill it, and the check that refuses it runs only after the
+ * whole step. With no run to read, the schema is the one declared. Read when the tools are listed.
+ */
+export function knockoutAssessSchemaFor(schema, runDir) {
+  if (!runDir || existsSync(driverDir(String(runDir), FROZEN_METHOD_FILE))) return schema;
+  const strip = (s) => {
+    if (Array.isArray(s)) return s.map(strip);
+    if (!s || typeof s !== "object") return s;
+    const out = {};
+    for (const [k, v] of Object.entries(s)) {
+      if (k === "properties" && v && typeof v === "object" && !Array.isArray(v)) {
+        out.properties = Object.fromEntries(Object.entries(v).filter(([name]) => name !== "inputs").map(([name, sub]) => [name, strip(sub)]));
+      } else if (k === "required" && Array.isArray(v)) out.required = v.filter((name) => name !== "inputs");
+      else out[k] = strip(v);
+    }
+    return out;
+  };
+  return strip(schema);
+}

package/driver/engine/mcp/stdio-server.mjs

@@ -115,8 +115,11 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
   // it must be read-only. Nothing here needs to claim a write is a read to get called, and a
   // `readOnlyHint: true` on a tool that writes a ledger would be a lie told to a sandbox for
   // convenience — the exact thing annotations exist to prevent.
-  const list = tools.map((t) => ({
-    name: t.name, description: t.description, inputSchema: t.inputSchema,
+  // Listed when asked, not at start: a tool may give the schema for the run it serves (`schemaNow`), read
+  // at call time like every per-run read here. A tool without one lists its declared schema, as before.
+  const list = () => tools.map((t) => ({
+    name: t.name, description: t.description,
+    inputSchema: typeof t.schemaNow === "function" ? t.schemaNow(t.inputSchema) : t.inputSchema,
     ...(t.annotations ? { annotations: t.annotations } : {}),
   }));
   const send = (m) => process.stdout.write(JSON.stringify(m) + "\n");
@@ -137,7 +140,7 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
       } else if (method === "ping") {
         ok(id, {});
       } else if (method === "tools/list") {
-        ok(id, { tools: list });
+        ok(id, { tools: list() });
       } else if (method === "tools/call") {
         const tool = byName.get(params?.name);
         if (!tool) return ok(id, { isError: true, content: [{ type: "text", text: `unknown tool: ${params?.name}` }] });
@@ -167,7 +170,7 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
           // interpolate a mark, and this row's own contract is the call and never its content. A row that
           // copied the message would leak the day one of them does; a row that copies `unmet` cannot.
           logToolEvent({ event: "settled", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}), ok: false,
-            reason: `missing_required:${unmet.join(",")}` });
+            failure: "schema", reason: `missing_required:${unmet.join(",")}` });
           return ok(id, { isError: true, content: [{ type: "text", text:
             `${tool.name}_missing_required:${unmet.join(",")} — the schema you were handed declares `
             + `${unmet.length === 1 ? "this field" : "these fields"} REQUIRED and the call did not carry `
@@ -177,13 +180,19 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
         try { out = await tool.handler(params?.arguments || {}); }
         catch (e) {
           // A THROWN tool error SETTLES. It returned an answer — a wrong one, but the model saw it and
-          // could act on it. Recording it as unsettled would attribute a live failure to a timeout.
-          logToolEvent({ event: "settled", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}), ok: false });
+          // could act on it. Recording it as unsettled would attribute a live failure to a timeout. The
+          // row names the error's class and never its message, which can carry whatever the tool was given.
+          logToolEvent({ event: "settled", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}), ok: false,
+            failure: "threw", reason: `threw:${errorClass(e)}` });
           return ok(id, { isError: true, content: [{ type: "text", text: `${tool.name} error: ${e?.message ?? e}` }] });
         }
         const isError = typeof out === "object" && out?.isError === true;
         const text = typeof out === "string" ? out : (out?.text ?? JSON.stringify(out));
-        logToolEvent({ event: "settled", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}), ok: !isError });
+        // A tool that answered with an error rejected the call itself, after the schema let it past. The row
+        // says so, and carries the complaint's own code when the text opens with one, never the text.
+        const code = isError ? complaintCode(text) : null;
+        logToolEvent({ event: "settled", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}), ok: !isError,
+          ...(isError ? { failure: "server", ...(code ? { reason: code } : {}) } : {}) });
         ok(id, { isError: isError || undefined, content: [{ type: "text", text }] });
       } else if (id != null) {
         err(id, -32601, `method not found: ${method}`);
@@ -205,3 +214,32 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
   // so `claude --mcp-config` reports a connected server whose tool calls return a clear isError.
   process.on("uncaughtException", (e) => { process.stderr.write(`[mcp:${name}] ${e?.stack ?? e}\n`); });
 }
+
+// ── WHAT REFUSED A CALL, as the settled row names it ───────────────────────────────────────────────────
+//
+// (At the end of this file so that adding it moved no line another file cites.)
+//
+// A settled row with `ok: false` carries `failure`, one of three words for where the call stopped:
+//   schema   the call did not carry a field the tool's schema requires; refused before the tool ran
+//   threw    the tool ran and threw
+//   server   the tool ran and answered with an error of its own
+// So a call refused before its tool ever ran is told apart from one the tool rejected without knowing
+// that the first leaves no call file behind. `reason` is never the message: a message can quote what the
+// tool was given. It is the missing fields, the error's class, or the complaint's own code.
+
+/** An error's class name, never its message. PURE. */
+export function errorClass(e) {
+  const n = typeof e?.name === "string" && /^[A-Za-z][A-Za-z0-9]*$/.test(e.name) ? e.name : "";
+  return n || "Error";
+}
+
+/**
+ * The code a tool's complaint opens with, as the acceptors write them (`knockoutframe_classes_plain: …`,
+ * `judgment_record_not_held:1:…`): a lower-case word with at least one underscore, read up to the first
+ * character that is not part of it. `null` when the text opens any other way, so prose never reaches the
+ * row. PURE.
+ */
+export function complaintCode(text) {
+  const m = /^([a-z][a-z0-9]*(?:_[a-z0-9]+)+)(?=$|[^a-z0-9_])/.exec(String(text ?? ""));
+  return m ? m[1] : null;
+}

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,47 @@ 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 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 +603,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);
@@ -589,6 +657,10 @@ function settleTuple({ r, ev, resumeRef }) {
     // adapter reads its commands only for failures (below), so it reports no command-tool count: null, never zero.
     toolCallsRefused: mcpToolGauge(ev).mcpToolCallsRefused,
     commandToolCalls: null,
+    // 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 +696,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 +726,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 +777,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