clearotron 0.4.1-beta.2 → 0.4.1-beta.3

package/.env.example

@@ -96,6 +96,15 @@ CLEAROTRON_CLAUDE_PATH=claude
 # the copied `.env`, not a choice).
 # effect: setup
 CLEAROTRON_CODEX_PATH=codex
+#
+# How long one tool answer may be before it is handed over in parts, in bytes, counted as a quoted string
+# (shared/answer-parts.mjs). Each engine gives every tool server its own size: 45,000 on Claude, because
+# Claude Code saves an answer longer than 50,000 characters to a file the model must read for itself, and
+# 36,000 on openai-agent, because Codex removes the middle of a tool read longer than about 39,000 bytes.
+# A smaller value here still applies on both; empty leaves the engine's size. The answer itself is
+# unchanged either way; the tool runs once, and a later part is read from the answer the server holds.
+# effect: tuning
+CLEAROTRON_TOOL_ANSWER_BYTES=
 
 CLEAROTRON_WORK_DIR=
 # Customer/project config store (loadProfiles). Unset ⇒ driver's built-in profiles dir.

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "08583753fbde693fdecdc8e16f11781dae789f55",
-  "version": "0.4.1-beta.2"
+  "commit": "38d43f7a215c87092fd2cc233812b3aff17e1e82",
+  "version": "0.4.1-beta.3"
 }

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

@@ -292,7 +292,8 @@ of truncations.
 
 | Var | Default | Meaning |
 |---|---|---|
-| `CLEAROTRON_BAND_RESPONSE_CHARS` | the shape-part size | Characters per band-server response. Floor 4096; defaults to whatever the shape part is set to, so raising one raises both unless this is set too. |
+| `CLEAROTRON_BAND_RESPONSE_CHARS` | five sixths of `CLEAROTRON_TOOL_ANSWER_BYTES`: 37,500 on the Claude engine, 30,000 on the OpenAI engine; 70,000 with no answer size | Characters per band-server response, the band summary's parts included; a summary part is never longer than 70,000 whatever this says. Floor 4096. The sixth left over is room for the quotes and line breaks a printout adds and for a banner, so a band answer is never split again into answer parts. On the OpenAI engine it is at most 30,000; a smaller value set here still applies. |
+| `CLEAROTRON_TOOL_ANSWER_BYTES` | 45,000 on the Claude engine, 36,000 on the OpenAI engine | Bytes per tool answer from every local tool server and the case-law bridge, counted as a quoted string (a quote or line break counts two). A longer answer is served in parts, each naming the next, and the tool runs once: a later part is read from the answer the server holds. Each engine writes its size into every server's entry: Claude Code saves an answer longer than 50,000 characters to a file the model must read for itself, and Codex removes the middle of a tool read longer than about 39,000 bytes. A smaller value set here still applies on both. A server started outside a stage, with no size, serves every answer whole. Floor 8192. |
 
 ### Surfaces beside the driver — portal, demo, e2e harness
 

package/driver/CHANGELOG.md

@@ -1,5 +1,11 @@
 # clearotron-driver
 
+## 0.4.1-beta.3
+
+### Patch Changes
+
+- Fixed: A crowded clearance on the Codex engine no longer stops before its report.
+
 ## 0.4.1-beta.2
 
 ### Patch Changes

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

@@ -20,6 +20,7 @@ import { readFileSync, readdirSync, appendFileSync, existsSync, mkdirSync } from
 import { join, dirname } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { serve } from "./stdio-server.mjs";
+import { answerBudget } from "../../../shared/answer-parts.mjs";
 import { classifyRecord, prepareTargets, SHAPE_TIERS, isLiveRecord } from "../../band-shape.mjs";
 import { recordQids } from "../../named-band.mjs";
 import { normalizeRecordUri } from "../../registry-fidelity.mjs";
@@ -98,7 +99,8 @@ const loadJson = (p) => JSON.parse(readFileSync(p, "utf8"));
 // contract is honest and explicit: an over-size shape announces "part N/M" and names the next call;
 // the common single-part case is served verbatim with no banner. The part size was a test seam with a
 // floor under it so a misconfiguration could never shred the shape into confetti; step 3 deleted
-// the knob, and a constant cannot be misconfigured.
+// the knob, and a constant cannot be misconfigured. A smaller answer size still lowers it
+// (SHAPE_PART_SERVED, below), never under the answer size's own floor.
 const SHAPE_PART_CHARS = 70000;   // step 3 — was a knob; no environment ever set it
 
 // PR-11 — the SAME transport cap bounds the other two tools (they were shipped unbounded): a
@@ -106,7 +108,19 @@ const SHAPE_PART_CHARS = 70000;   // step 3 — was a knob; no environment ever
 // per-tool-output token cap and error the call — killing the reading path exactly where the record
 // volume is highest. band_lookup TRIMS records (the full match count always survives, with an
 // honest note); band_record serves PARTS like band_shape (a record is a document — never trimmed).
-const RESPONSE_CHARS = Math.max(4096, Number(process.env.CLEAROTRON_BAND_RESPONSE_CHARS) || SHAPE_PART_CHARS);
+// Given an answer size and no band size of its own, the band answers in five sixths of it: the rest is room
+// for the quotes and line breaks a printout adds (up to 13% on band answers) and for a banner, so a band
+// answer is never split a second time (shared/answer-parts.mjs). 37,500 on Claude, 30,000 on codex.
+const RESPONSE_CHARS = Math.max(4096, Number(process.env.CLEAROTRON_BAND_RESPONSE_CHARS)
+  || (answerBudget() ? Math.floor(answerBudget() / 1.2) : SHAPE_PART_CHARS));
+
+// The shape is split at the smaller of its own part size and the answer size, because codex cuts the
+// middle out of a read over about 39,000 bytes and is given a smaller answer size for that
+// (engine/mcp/codex-config.mjs, CODEX_BAND_ANSWER_CHARS). Measured in testing, 2026-10-11: a GPT model that
+// printed a 70,269-character shape part to read it named 11 of its 24 marker rows, and in one attempt of a
+// real run four of five shape reads were that long. Never larger than the constant,
+// so a larger answer size cannot push a part past Claude's limit; with no size set, nothing changes.
+const SHAPE_PART_SERVED = Math.min(SHAPE_PART_CHARS, RESPONSE_CHARS);
 
 /** Split text into parts of ≤ budget chars, cutting only at line boundaries (an over-budget single
  *  line still ships whole — never cut mid-line). Concatenating the parts with "\n" restores the
@@ -216,7 +230,7 @@ function bandShape(params) {
   if (!RUN_DIR) { logRead("band_shape", { format }, { ok: false }); return { isError: true, text: "ERROR: CLEAROTRON_BAND_RUN_DIR not set — band tools are wired per run by the driver." }; }
   if (!existsSync(p)) { logRead("band_shape", { format }, { ok: false }); return { isError: true, text: `ERROR: ${p} not found — the driver derives it after the register fan-in; if the band exists but the shape does not, report this as a driver defect (do NOT slice the raw band instead).` }; }
   const text = readFileSync(p, "utf8");
-  const parts = splitAtLines(text, SHAPE_PART_CHARS);
+  const parts = splitAtLines(text, SHAPE_PART_SERVED);
   const total = parts.length;
   if (total === 1) {                                    // the common case — served verbatim, no banner
     logRead("band_shape", { format }, { ok: true, bytes: text.length });
@@ -240,6 +254,11 @@ function bandLookup(params = {}) {
   try { band = loadJson(bandPath()); } catch (e) { logRead("band_lookup", params, { ok: false }); return { isError: true, text: `ERROR: band unreadable (${e.message}) — a driver-side defect; report it, never hand-repair the band.` }; }
   const { record_id, owner, nice_class, tier, qid, query, text, status, live_only = false } = params;
   const limit = Math.max(1, Math.min(Number(params.limit) || 20, 100));
+  // PAGING. A large band is read page by page from `offset`, in the band's own order, and a capped answer
+  // names the next offset. Without it the only way to see every record was to slice the band by owner or
+  // text fragments, and a seat told to judge the complete band read it many times over (1,423 records,
+  // 2,287 lookups, 65.8 MB, until the engine's output cap stopped the turn).
+  const offset = Math.max(0, Math.floor(Number(params.offset) || 0));
   if (tier && !SHAPE_TIERS.includes(tier)) return { isError: true, text: `ERROR: tier must be one of ${SHAPE_TIERS.join(" | ")}.` };
 
   // tier filtering classifies against the SHAPE's own frozen targets — same classifier, same result.
@@ -270,7 +289,7 @@ function bandLookup(params = {}) {
     if (text && !norm(r?.mark_text).includes(norm(text))) continue;
     if (prepared && classifyRecord(r?.mark_text, prepared).tier !== tier) continue;
     matched++;
-    if (hits.length < limit) hits.push(project(r));
+    if (matched > offset && hits.length < limit) hits.push(project(r));
   }
   // matching crowd descriptors ride along (a lookup that lands in an un-enumerated zone must SEE that).
   const crowds = (Array.isArray(band?.crowds) ? band.crowds : []).filter((c) => {
@@ -301,9 +320,10 @@ function bandLookup(params = {}) {
   // The full `matched` count always ships, and the note says exactly how many records were withheld.
   let byteCapped = 0;
   const body = () => JSON.stringify({
-    matched, returned: hits.length,
-    ...(matched > hits.length ? { note: `capped at ${hits.length} — narrow the filters${byteCapped ? "" : " (or raise limit ≤100)"} to see the rest; the count above is the full match` } : {}),
-    ...(byteCapped ? { byte_cap_note: `${byteCapped} matched record(s) withheld to fit one tool response — narrow the filters (owner / nice_class / tier / qid) and look them up in smaller slices` } : {}),
+    matched, returned: hits.length, ...(offset ? { offset } : {}),
+    ...(matched > offset + hits.length ? { next_offset: offset + hits.length } : {}),
+    ...(matched > offset + hits.length ? { note: `capped at ${hits.length} — call again with offset: ${offset + hits.length} for the next page; the count above is the full match` } : {}),
+    ...(byteCapped ? { byte_cap_note: `${byteCapped} matched record(s) withheld to fit one tool response — call again with offset: ${offset + hits.length} for the rest` } : {}),
     records: hits,
     ...(crowds.length ? { matching_crowds: crowds, crowd_note: "these matching slices were NOT enumerated — records under them may exist that no lookup can return; weigh the descriptor, never treat this result as their clean"
       + (refusedCrowds ? ` — and ${refusedCrowds} of them was/were NEVER ANSWERED at all (see "refusal"): no count exists for those, so they are unsearched rather than empty, and nothing about them can be read off a zero` : "")
@@ -405,11 +425,11 @@ serve({
     },
     {
       name: "band_lookup",
-      description: "Look up enumerated records in this run's frozen register band (read-only; logged to the reading audit). Filters AND together: record_id (exact uri), owner (substring), nice_class, tier (identical|near-identical|same-family|other|unclassifiable — classified against the shape's frozen targets), qid (exact plan-entry id — the plan-execution ledger join; a record surfaced by several slices matches under EVERY one of them), query (the _query slice that surfaced the record), text (substring of mark_text), status (substring), live_only, limit (default 20, max 100). Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.",
+      description: "Look up enumerated records in this run's frozen register band (read-only; logged to the reading audit). Filters AND together: record_id (exact uri), owner (substring), nice_class, tier (identical|near-identical|same-family|other|unclassifiable — classified against the shape's frozen targets), qid (exact plan-entry id — the plan-execution ledger join; a record surfaced by several slices matches under EVERY one of them), query (the _query slice that surfaced the record), text (substring of mark_text), status (substring), live_only, limit (default 20, max 100), offset (default 0: where in the matching records to start — a capped answer names the next offset, so a large band is read page by page). Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.",
       inputSchema: { type: "object", properties: {
         record_id: { type: "string" }, owner: { type: "string" }, nice_class: { type: "string" },
         tier: { type: "string", enum: SHAPE_TIERS }, qid: { type: "string" }, query: { type: "string" }, text: { type: "string" },
-        status: { type: "string" }, live_only: { type: "boolean" }, limit: { type: "number" },
+        status: { type: "string" }, live_only: { type: "boolean" }, limit: { type: "number" }, offset: { type: "number" },
       } },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: bandLookup,

package/driver/engine/mcp/codex-config.mjs

@@ -50,6 +50,30 @@ export const TOOL_SERVER_SETTINGS = Object.freeze([
   "OAUTH_BRIDGE_CREDS_DIR", "OAUTH_BRIDGE_CLIENT_NAME",
 ]);
 
+// CODEX CUTS THE MIDDLE OUT OF A LONG READ. It shows a model at most 10,000 tokens of the text a tool call
+// puts in front of it, from its start and its end, counting 4 bytes a token, with "…N tokens truncated…"
+// between them. For the GPT models, which call tools only from code (5.6 and 6.x), that text is what the
+// code prints, and a quoted print adds a byte for each quote and line break: up to 13% on real band answers.
+// Measured in testing, 2026-10-11, on codex 0.162.0 with gpt-6.1-sol: a model that printed a 68,752-character
+// band page to read it named 14 of its 30 records, and at 32,000 characters it named every one. The band
+// server sizes its answers for Claude's limit (70,000 characters, under 25,000 tokens). The vendor's settings
+// for a larger budget (`tool_output_token_limit`, a tool's `output_token_limit`) changed nothing on that
+// version, written in this file or given on the command line. So here the band server answers in 30,000
+// characters: printed with its escapes and banner it stays under the general answer size below, and so under
+// the cut. An install's own smaller size still wins.
+export const CODEX_BAND_ANSWER_CHARS = 30000;
+export const codexBandAnswerChars = (env = process.env) =>
+  Math.min(CODEX_BAND_ANSWER_CHARS, Number(env.CLEAROTRON_BAND_RESPONSE_CHARS) || CODEX_BAND_ANSWER_CHARS);
+
+// AND EVERY OTHER ANSWER: each server here, the case-law bridges and the page fetcher included, is given an
+// answer size, and an answer longer than that, counted as a quoted string, is served in parts, the tool
+// running once (shared/answer-parts.mjs). 36,000 bytes leaves room under the cut for the engine's own
+// wrapping (about 840 bytes); the band server's own answers stay under it and are never split again. An
+// install's own smaller size still wins.
+export const CODEX_TOOL_ANSWER_BYTES = 36000;
+export const codexToolAnswerBytes = (env = process.env) =>
+  Math.min(CODEX_TOOL_ANSWER_BYTES, Number(env.CLEAROTRON_TOOL_ANSWER_BYTES) || CODEX_TOOL_ANSWER_BYTES);
+
 // ── TOML value escaping (basic strings) ──────────────────────────────────────────────────────────────
 // One encoder for every TOML block the product writes; re-exported so this module's callers keep their import.
 export { tomlString };
@@ -121,7 +145,7 @@ export function webFetchRequested(allowedTools) {
 // stays the backstop. Absent/0/negative ⇒ emit nothing and leave codex's default alone, so this is inert
 // for any caller that does not thread a budget.
 export function renderCodexConfigToml({ mcpConfig, allowedTools, developerInstructions, nodeBin = process.execPath, credEnvForward = [...CRED_ENV_FORWARD, ...TOOL_SERVER_SETTINGS], toolTimeoutSec, fence = null, withheldFromCommands = [],
-  platform = process.platform } = {}) {
+  platform = process.platform, bandAnswerChars = codexBandAnswerChars(), toolAnswerBytes = codexToolAnswerBytes() } = {}) {
   const servers = parseClaudeMcpServers(mcpConfig);
   const enabled = enabledToolsByServer(allowedTools);
   const toolTimeout = Number(toolTimeoutSec) > 0 ? Math.floor(Number(toolTimeoutSec)) : undefined;
@@ -167,11 +191,15 @@ export function renderCodexConfigToml({ mcpConfig, allowedTools, developerInstru
     lines.push("");
   };
 
-  for (const [name, s] of Object.entries(servers)) emitServer(name, { ...s, enabledTools: enabled[name] }, { forwardCreds: true });
+  // Every server answers under codex's cut, the band server in its own way too (CODEX_TOOL_ANSWER_BYTES,
+  // CODEX_BAND_ANSWER_CHARS, above); `env` wins over a forwarded name.
+  const answers = { CLEAROTRON_TOOL_ANSWER_BYTES: String(toolAnswerBytes) };
+  for (const [name, s] of Object.entries(servers)) emitServer(name, { ...s, enabledTools: enabled[name],
+    env: { ...s.env, ...answers, ...(name === "band" ? { CLEAROTRON_BAND_RESPONSE_CHARS: String(bandAnswerChars) } : {}) } }, { forwardCreds: true });
 
   // WebFetch → the engine-local fetch server (codex has no built-in). Needs no creds (no env_vars).
   if (webFetchRequested(allowedTools))
-    emitServer("fetch", { command: nodeBin, args: [FETCH_SERVER], env: {}, enabledTools: ["fetch_url"] }, { forwardCreds: false });
+    emitServer("fetch", { command: nodeBin, args: [FETCH_SERVER], env: { ...answers }, enabledTools: ["fetch_url"] }, { forwardCreds: false });
 
   if (fence) lines.push(...fenceToml(fence));
   // ON WINDOWS, CODEX'S SANDBOX IS ON ONLY WHEN THIS NAMES IT. With no `[windows] sandbox` and no feature

package/driver/engine/mcp/gather-config.mjs

@@ -834,9 +834,21 @@ function resolveGroup(group) {
   }
 }
 
+// CLAUDE'S ANSWER SIZE. Claude Code replaces a tool answer longer than 50,000 characters, or 25,000 tokens,
+// with a message naming a file it saved the answer to, and the model must read that file itself, the
+// first read refused when the file is past 25,000 tokens (the vendor's MCP page; measured in testing,
+// 2026-10-11, on 2.1.286 and 2.1.295: 49,159 characters arrived whole, 51,189 were replaced). So every
+// server is given this size, and a longer answer comes in the parts shared/answer-parts.mjs serves, the
+// banners the same on both engines. 45,000 bytes counted as a quoted string is under 50,000 characters, and
+// under 25,000 tokens for any text a register or a search returns. The codex config writes its own, smaller
+// size over this one (codex-config.mjs). An install's own smaller size still wins.
+export const CLAUDE_TOOL_ANSWER_BYTES = 45000;
+export const claudeToolAnswerBytes = (env = process.env) =>
+  Math.min(CLAUDE_TOOL_ANSWER_BYTES, Number(env.CLEAROTRON_TOOL_ANSWER_BYTES) || CLAUDE_TOOL_ANSWER_BYTES);
+
 // The mcp-config server env carries ONLY the per-run, non-secret values (session key + ledger paths +
-// agent + the run dir the band tools serve). Creds (CORSEARCH_SESSION_KEY / PERPLEXITY_API_KEY /
-// EUIPO_*) are inherited from the engine env.
+// agent + the run dir the band tools serve, and the answer size above). Creds (CORSEARCH_SESSION_KEY /
+// PERPLEXITY_API_KEY / EUIPO_*) are inherited from the engine env.
 function serverEnv({ sessionKey, agent, runDir, recordAxis }) {
   const e = {};
   // — see buildGatherMcpConfig: a register server without a run is refused there, so by the time
@@ -881,6 +893,7 @@ function serverEnv({ sessionKey, agent, runDir, recordAxis }) {
   if (runDir) e.CLEAROTRON_REGISTER_RECORD_LOG = runRecordLogPath(runDir);
   for (const v of ["CLEAROTRON_GATHER_SESSION_ID", "EUIPO_ENVIRONMENT"])
     if (process.env[v]) e[v] = process.env[v];
+  e.CLEAROTRON_TOOL_ANSWER_BYTES = String(claudeToolAnswerBytes());   // CLAUDE_TOOL_ANSWER_BYTES, above
   return e;
 }
 
@@ -935,6 +948,8 @@ export function buildGatherMcpConfig(groups = [], { sessionKey, agent, runDir, r
   if (runDir) auditEnv.CLEAROTRON_BAND_RUN_DIR = runDir;
   if (sessionKey) auditEnv.CLEAROTRON_GATHER_SESSION_KEY = sessionKey;
   if (agent) auditEnv.CLEAROTRON_GATHER_AGENT = agent;
+  // In a run, a fourth: the answer size, because a case-law answer is served in parts like any other.
+  if (Object.keys(auditEnv).length) auditEnv.CLEAROTRON_TOOL_ANSWER_BYTES = String(claudeToolAnswerBytes());
   for (const k of bridgeKeys) mcpServers[k] = { command: NODE, args: [BRIDGE, "--server", k], connectionTimeoutMs: 60000, ...(Object.keys(auditEnv).length ? { env: auditEnv } : {}) };
   return Object.keys(mcpServers).length ? { mcpServers } : null;
 }

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

@@ -10,6 +10,7 @@ import { dirname, basename } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { underStudioSegment } from "../../../shared/path-seps.mjs";   // Windows builds the path with "\"
 import { serve } from "./stdio-server.mjs";
+import { answerBudget } from "../../../shared/answer-parts.mjs";
 import {
   isKnownPreset, questionPresetFor, buildRequestBody, callAgentAPI, formatResponse, formatSandboxResponse,
   validateGridSpec, buildGridProgramTask, captureGridFromResponse, requiredLedgerRefusal,
@@ -194,7 +195,10 @@ function tellObligations(spec, ledgerJson) {
 // and a grid's candidates grow with its results per cell. So they are served in parts, split between
 // cells, as band_shape serves an oversize shape, with the same part size. A later part is read from the
 // saved ledger: nothing is searched again.
-const GRID_PART_CHARS = 70000;
+// Smaller when this server was given an answer size (codex cuts the middle out of a longer read;
+// shared/answer-parts.mjs): three quarters of it, which leaves room for the rest of the reply and for the
+// quotes and line breaks a printout adds, so a part of the grid is never split again on its way to the model.
+const GRID_PART_CHARS = answerBudget() ? Math.min(70000, Math.floor(answerBudget() * 0.75)) : 70000;
 
 // `reserve` is what part 1's reply also carries (the meaning obligations): part 1 is that much smaller,
 // and every call passes the same reserve for the same ledger, so every call splits it the same way.

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

@@ -12,6 +12,7 @@ import { createInterface } from "node:readline";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
+import { answerBudget, answerPieces, servedPart, partNotHeld, takePart, heldAnswers, withAnswerPart } from "../../../shared/answer-parts.mjs";
 
 // ── half 2 — THE TOOL CALL LOG, so a killed call is a FACT and not an inference ────────────────
 //
@@ -88,6 +89,10 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
   // reader must key on (server, seq) and never on seq alone.
   let callSeq = 0;
   const byName = new Map(tools.map((t) => [t.name, t]));
+  // A LONG ANSWER IS SERVED IN PARTS when this server was given an answer size (shared/answer-parts.mjs):
+  // the handler runs once, the answer is held here, and a later part is read from it. No size, no change.
+  const budget = answerBudget();
+  const held = heldAnswers();
   // ── — THE ANNOTATIONS TRAVEL, BECAUSE A TOOL MUST BE ABLE TO SAY WHAT IT DOES ──
   //
   // This line used to pick three fields and drop the rest, so a tool that declared `annotations` had
@@ -117,9 +122,10 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
   // convenience — the exact thing annotations exist to prevent.
   // 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 schemaOf = (t) => (typeof t.schemaNow === "function" ? t.schemaNow(t.inputSchema) : t.inputSchema);
   const list = () => tools.map((t) => ({
     name: t.name, description: t.description,
-    inputSchema: typeof t.schemaNow === "function" ? t.schemaNow(t.inputSchema) : t.inputSchema,
+    inputSchema: budget ? withAnswerPart(schemaOf(t)) : schemaOf(t),
     ...(t.annotations ? { annotations: t.annotations } : {}),
   }));
   const send = (m) => process.stdout.write(JSON.stringify(m) + "\n");
@@ -144,11 +150,20 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
       } 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}` }] });
+        // A later part of a held answer is read from it, and the tool does not run: no started/settled pair,
+        // one row of its own, so a count of the tool's runs stays a count of its runs.
+        const { args, part } = budget ? takePart(params?.arguments) : { args: params?.arguments, part: null };
+        const kept = part ? held.get(tool.name, args) : null;
+        if (part && (kept || part > 1)) {
+          logToolEvent({ event: "answer-part", server: name, tool: tool.name, part, ...(kept ? { of: kept.length } : { held: false }) });
+          return ok(id, kept ? { content: [{ type: "text", text: servedPart(tool.name, kept, part) }] }
+            : { isError: true, content: [{ type: "text", text: partNotHeld(tool.name, part) }] });
+        }
         // — STAMPED BEFORE THE WORK, settled after it, and the pair is the whole mechanism. A
         // process killed mid-call cannot write anything, so "started with no settled" is the only shape
         // that can record a call that never returned.
         const seq = ++callSeq;
-        const axis = typeof params?.arguments?.axis === "string" ? params.arguments.axis : null;
+        const axis = typeof args?.axis === "string" ? args.axis : null;
         logToolEvent({ event: "started", seq, server: name, tool: tool.name, ...(axis ? { axis } : {}) });
         // ── — THE ONE SEAM EVERY TYPED CALL PASSES THROUGH ───────────────────────
         //
@@ -157,7 +172,7 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
         // re-check by hand, which made "this field is required" a property of one author's diligence
         // rather than of the contract. The refusal names the fields in the acceptors' own token shape so
         // a seat can act on it in the turn it happens.
-        const unmet = requiredFieldViolations(tool.inputSchema, params?.arguments);
+        const unmet = requiredFieldViolations(tool.inputSchema, args);
         if (unmet.length) {
           // THE REASON THE ROW HAD IN SCOPE AND THREW AWAY. A settled row with
           // `ok: false` and nothing else asserts a failure and withholds everything that would let a
@@ -177,7 +192,7 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
             + `${unmet.length === 1 ? "it" : "them"}. Send the field itself, not null and not a placeholder.` }] });
         }
         let out;
-        try { out = await tool.handler(params?.arguments || {}); }
+        try { out = await tool.handler(args || {}); }
         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. The
@@ -193,6 +208,11 @@ export function serve({ name, version = "0.1.0", tools = [] }) {
         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 } : {}) } : {}) });
+        const pieces = budget && !isError ? answerPieces(text, budget, tool.name) : null;
+        if (pieces && pieces.length > 1) {
+          held.hold(tool.name, args, pieces);
+          return ok(id, { content: [{ type: "text", text: servedPart(tool.name, pieces, 1) }] });
+        }
         ok(id, { isError: isError || undefined, content: [{ type: "text", text }] });
       } else if (id != null) {
         err(id, -32601, `method not found: ${method}`);

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.4.1-beta.2",
+  "version": "0.4.1-beta.3",
   "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": {

package/driver/suite-census.json

@@ -766,8 +766,8 @@
           "todos": 0
         },
         "a-large-grid-is-served-in-parts-under-the-tool-cap.test.mjs": {
-          "tests": 4,
-          "asserts": 19,
+          "tests": 5,
+          "asserts": 23,
           "skips": 0,
           "todos": 0
         },
@@ -795,6 +795,18 @@
           "skips": 0,
           "todos": 0
         },
+        "a-long-answer-reaches-a-gpt-model-in-parts.test.mjs": {
+          "tests": 5,
+          "asserts": 39,
+          "skips": 0,
+          "todos": 0
+        },
+        "a-long-case-law-answer-reaches-a-gpt-model-in-parts.test.mjs": {
+          "tests": 2,
+          "asserts": 7,
+          "skips": 0,
+          "todos": 0
+        },
         "a-mark-name-cannot-lie-about-how-it-reads.test.mjs": {
           "tests": 9,
           "asserts": 38,
@@ -1365,6 +1377,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-seat-reads-the-band-page-by-page.test.mjs": {
+          "tests": 4,
+          "asserts": 25,
+          "skips": 0,
+          "todos": 0
+        },
         "a-secret-file-is-compared-not-printed.test.mjs": {
           "tests": 5,
           "asserts": 16,
@@ -2020,8 +2038,8 @@
           "todos": 0
         },
         "band-server.test.mjs": {
-          "tests": 24,
-          "asserts": 126,
+          "tests": 26,
+          "asserts": 136,
           "skips": 0,
           "todos": 0
         },
@@ -3088,8 +3106,8 @@
           "todos": 0
         },
         "engine.codex-config.test.mjs": {
-          "tests": 20,
-          "asserts": 70,
+          "tests": 23,
+          "asserts": 89,
           "skips": 0,
           "todos": 0
         },

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-artifacts-mcp
 
+## 0.4.1-beta.3
+
+No changes in this release.
+
 ## 0.4.1-beta.2
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.4.1-beta.2",
+  "version": "0.4.1-beta.3",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron",
   "mcpName": "io.github.CordilleraSarl/clearotron",
   "type": "module",
-  "version": "0.4.1-beta.2",
+  "version": "0.4.1-beta.3",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.4.1-beta.2",
+  "version": "0.4.1-beta.3",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.4.1-beta.3
+
+No changes in this release.
+
 ## 0.4.1-beta.2
 
 No changes in this release.

package/providers/oauth-mcp-bridge/bridge.mjs

@@ -30,6 +30,7 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { driverDir } from "../../shared/driver-dir.mjs";   //
+import { answerBudget, answerPieces, servedPart, partNotHeld, takePart, heldAnswers, withAnswerPart } from "../../shared/answer-parts.mjs";
 import { RefreshLock } from "./refresh-lock.mjs";
 import { exitOnStdinClose } from "./stdin-guard.mjs";
 
@@ -327,6 +328,19 @@ async function main() {
     { capabilities: { tools: {} } },
   );
 
+  // A LONG ANSWER IS SERVED IN PARTS when the bridge was given an answer size (shared/answer-parts.mjs). An
+  // answer made of text alone is split; one carrying anything else is passed on as it came.
+  const budget = answerBudget();
+  const held = heldAnswers();
+  const partedResult = (tool, args, res) => {
+    const blocks = Array.isArray(res?.content) ? res.content : [];
+    if (!blocks.length || !blocks.every((c) => c?.type === "text")) return res;
+    const pieces = answerPieces(blocks.map((c) => String(c.text ?? "")).join("\n"), budget, tool);
+    if (pieces.length === 1) return res;
+    held.hold(tool, args, pieces);
+    return { content: [{ type: "text", text: servedPart(tool, pieces, 1) }] };
+  };
+
   downstream.setRequestHandler(ListToolsRequestSchema, async () => {
     const upstreamResp = await upstream.listTools();
     const upstreamTools = upstreamResp?.tools ?? [];
@@ -339,7 +353,7 @@ async function main() {
         `[oauth-bridge:${serverName}] filtered ${dropped.length} unlisted upstream tool(s) from ListTools: ${dropped.join(", ")}\n`,
       );
     }
-    return { ...upstreamResp, tools };
+    return { ...upstreamResp, tools: budget ? tools.map((t) => ({ ...t, inputSchema: withAnswerPart(t.inputSchema) })) : tools };
   });
 
   downstream.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -353,12 +367,20 @@ async function main() {
         `Tool "${name}" is not in the bridge allowlist for ${serverName}. To enable it, add the unprefixed upstream name to ALLOWED_TOOLS in bridge.mjs and restart.`,
       );
     }
+    // A later part of a held answer is read from it; the upstream server is not asked again.
+    const { args, part } = budget ? takePart(req.params.arguments) : { args: req.params.arguments, part: null };
+    const kept = part ? held.get(name, args) : null;
+    if (part && (kept || part > 1)) {
+      logCall(serverName, name, args, kept ? { ok: true, answer_part: part, of: kept.length } : { ok: false, answer_part: part, held: false });
+      return kept ? { content: [{ type: "text", text: servedPart(name, kept, part) }] }
+        : { isError: true, content: [{ type: "text", text: partNotHeld(name, part) }] };
+    }
     try {
-      const res = await upstream.callTool({ name, arguments: req.params.arguments });
+      const res = await upstream.callTool({ name, arguments: args });
       const refused = toolError(res);
       if (refused === null) logCall(serverName, name, req.params.arguments, { ok: true, bytes: resultBytes(res) });
       else logCall(serverName, name, req.params.arguments, { ok: false, error: refused });
-      return res;
+      return budget && refused === null ? partedResult(name, args, res) : res;
     } catch (err) {
       // A FAILED CALL IS LOGGED TOO, and it is the half that matters: without it, "the search ran and
       // found nothing" and "the search errored" leave the same trace — the ambiguity is about.

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.4.1-beta.2",
+  "version": "0.4.1-beta.3",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/scripts/e2e-first-time.mjs

@@ -222,7 +222,7 @@ export const NOT_COUNTED_EVENTS = {
     "stale-repair-entry", "taint-disclose", "unsettled-inputs", "verdict-2", "verdict-3",
   ],
   "read from its own record: the stage records, the dispatch records and the tool-call log": [
-    "attempt", "stage", "settled", "started",
+    "answer-part", "attempt", "stage", "settled", "started",
   ],
   "the portal's, the profile store's or the config store's audit log, never a run log": [
     "compose-read", "demo-order", "family-group", "family-ungroup", "other", "person-add", "person-change",

package/shared/answer-parts.mjs

@@ -0,0 +1,127 @@
+// 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
+//
+// answer-parts.mjs — a tool answer longer than the engine carries whole, served in parts.
+//
+// Codex shows a model at most 10,000 tokens of the text a tool call puts in front of it, counting 4 bytes a
+// token, and puts "…N tokens truncated…" where the middle was. That text is the tool's answer itself, or,
+// for the GPT models that call tools only from code (all of 5.6 and 6.x), what that code prints, and code
+// that prints an answer as a quoted string adds a byte for each quote and line break. Measured in testing,
+// 2026-10-11, on codex 0.162.0 with gpt-6.1-sol and on codex 0.156.1 with gpt-5.6-sol: a model that
+// printed a 42,560-byte answer to read it saw its start and end only. Register searches, research answers,
+// fetched pages and case-law results all run past that size on real matters. So when a server is given an
+// answer size (CLEAROTRON_TOOL_ANSWER_BYTES, set for codex in engine/mcp/codex-config.mjs), an answer
+// longer than that, counted as a quoted string, is split into parts, each with a banner naming the next
+// call. The tool runs ONCE: the whole answer is held in the server's process and a later part is read from
+// it, so nothing is searched, fetched or written again. With no size given, nothing here runs and every
+// answer is served as it always was.
+//
+// Two places use it, because every tool answer the engine reads passes through one of them: serve() in
+// driver/engine/mcp/stdio-server.mjs, for every local server, and the OAuth bridge, for the case-law servers.
+
+/** The argument a later part is asked for by. No tool uses this name for anything else. */
+export const ANSWER_PART_ARG = "answer_part";
+
+/** Room left in each part for its banner; a tool's name is counted on top. */
+const BANNER_RESERVE = 400;
+
+/** The answer size this server was given, in bytes, or 0 when none was. Never under 8 KB. */
+export function answerBudget(env = process.env) {
+  const n = Number(env.CLEAROTRON_TOOL_ANSWER_BYTES);
+  return n > 0 ? Math.max(8192, Math.floor(n)) : 0;
+}
+
+/** What a character costs once the text is a quoted string: its UTF-8 bytes, or its escape. PURE. */
+function quotedCost(code) {
+  if (code === 0x22 || code === 0x5c || code === 0x0a || code === 0x0d || code === 0x09 || code === 0x08 || code === 0x0c) return 2;
+  if (code < 0x20) return 6;
+  return code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+}
+
+/** The size of text as a quoted string, in bytes, quotes not counted: never less than its own bytes. PURE. */
+export function quotedBytes(text) {
+  let n = 0;
+  for (const ch of String(text)) n += quotedCost(ch.codePointAt(0));
+  return n;
+}
+
+/**
+ * Split text into consecutive pieces of at most `budget` bytes, counted as a quoted string. PURE. A piece
+ * ends after its last line break when it holds one, so a line is cut only when it is longer than a piece;
+ * every cut falls between characters. Joining the pieces with nothing between them gives the text back.
+ */
+export function splitAnswer(text, budget) {
+  const chars = Array.from(String(text));
+  const pieces = [];
+  let start = 0;
+  while (start < chars.length) {
+    let cost = 0, end = start, lastBreak = -1;
+    while (end < chars.length) {
+      const c = quotedCost(chars[end].codePointAt(0));
+      if (cost + c > budget && end > start) break;
+      cost += c;
+      if (chars[end] === "\n") lastBreak = end;
+      end++;
+    }
+    if (end < chars.length && lastBreak >= start) end = lastBreak + 1;
+    pieces.push(chars.slice(start, end).join(""));
+    start = end;
+  }
+  return pieces.length ? pieces : [""];
+}
+
+/** The pieces of an answer too long for one response; one piece when it fits. PURE. */
+export function answerPieces(text, budget, tool) {
+  if (!budget || quotedBytes(text) <= budget) return [String(text)];
+  return splitAnswer(text, Math.max(1024, budget - BANNER_RESERVE - 2 * quotedBytes(String(tool))));
+}
+
+/** Part `part` of `pieces`, between the banners that say what it is and how to read the next one. PURE. */
+export function servedPart(tool, pieces, part) {
+  const total = pieces.length;
+  const p = Math.min(Math.max(1, Math.floor(Number(part)) || 1), total);
+  const head = `[${tool} answer part ${p}/${total} — this answer exceeds one tool response, so it is served in ${total} parts.`
+    + ` It is COMPLETE only once ALL ${total} parts are read — never reason from a partial answer.]`;
+  const tail = p < total
+    ? `[end of part ${p}/${total} — call ${tool} again with the same arguments plus {"${ANSWER_PART_ARG}": ${p + 1}} for the next part]`
+    : `[end of part ${total}/${total} — the answer is complete once parts 1..${total} are all read]`;
+  return `${head}\n${pieces[p - 1]}\n${tail}`;
+}
+
+/** What a part request is told when this process no longer holds that answer. PURE. */
+export function partNotHeld(tool, part) {
+  return `${tool}: no answer for these arguments is held, so part ${part} cannot be served — `
+    + `call ${tool} again without "${ANSWER_PART_ARG}" for the whole answer.`;
+}
+
+/** The arguments of a call without the part it asks for, and that part (null when it asks for none). PURE. */
+export function takePart(args) {
+  if (!args || typeof args !== "object" || !(ANSWER_PART_ARG in args)) return { args: args || {}, part: null };
+  const { [ANSWER_PART_ARG]: asked, ...rest } = args;
+  const part = Math.floor(Number(asked));
+  return { args: rest, part: part >= 1 ? part : null };
+}
+
+const canonical = (v) => (Array.isArray(v) ? v.map(canonical)
+  : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])])) : v);
+
+/** The answers this process holds, by tool and arguments; the oldest goes once `limit` are held. */
+export function heldAnswers(limit = 16) {
+  const held = new Map();
+  const key = (tool, args) => `${tool}\u0000${JSON.stringify(canonical(args ?? {}))}`;
+  return {
+    hold(tool, args, pieces) {
+      const k = key(tool, args);
+      held.delete(k);
+      held.set(k, pieces);
+      while (held.size > limit) held.delete(held.keys().next().value);
+    },
+    get: (tool, args) => held.get(key(tool, args)) ?? null,
+  };
+}
+
+/** A tool's input schema with the part argument added, for a server that was given an answer size. PURE. */
+export function withAnswerPart(schema) {
+  const s = schema && typeof schema === "object" ? schema : { type: "object" };
+  return { ...s, properties: { ...(s.properties || {}), [ANSWER_PART_ARG]: { type: "number" } } };
+}

package/shared/names-in-force.mjs

@@ -177,6 +177,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_SYNTHESIS_MODEL",
   "CLEAROTRON_TAINT_CHAIN",
   "CLEAROTRON_TEST_FIXTURE_PROFILES",
+  "CLEAROTRON_TOOL_ANSWER_BYTES",
   "CLEAROTRON_TURN_CAP",
   "CLEAROTRON_TURN_LOCK_POLL_MS",
   "CLEAROTRON_UNREACHABLE_SENIOR",