clearotron 0.5.0-beta.2 → 0.5.0-beta.4

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

@@ -60,6 +60,7 @@ import { MAX_ROWS_PER_CALL } from "../../disposition-call.mjs";
 // The lane's second statement, and a different one: which coverage units were searched to what end. Its
 // own module and its own file, never a row in the disposition form — see record_coverage_status below.
 import { recordCoverageStatus, COMMON_LAW_COVERAGE_STATUSES } from "../../common-law-coverage-status.mjs";
+import { insideRun } from "../../../shared/inside-run.mjs";   // a path a tool is handed is served only inside this run
 
 // ── B — THE TYPED DISPOSITION TRANSPORT ─────────────────────────────────────────────────────────────
 //
@@ -76,11 +77,17 @@ function specFrom(params) {
   const { grid_spec_path } = params ?? {};
   if (!grid_spec_path)
     return { error: "ERROR: grid_spec_path is required — it is the same driver-written spec path the grid tool was given. Do not compose a path." };
+  // THIS RUN'S SPEC AND LEDGER ONLY (shared/inside-run.mjs): the run folder is the one the driver wired, never the call's.
+  const runDir = process.env.CLEAROTRON_BAND_RUN_DIR || "";
+  if (runDir && !insideRun(runDir, grid_spec_path))
+    return { error: "ERROR: grid_spec_path is outside this run's folder. The driver writes the spec inside the run; use the path it gave you." };
   let spec;
   try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
   catch (err) { return { error: `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.` }; }
   if (!underStudioSegment(spec.output_path))   // either spelling: an install keeps the studio segment it has
     return { error: `ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}` };
+  if (runDir && !insideRun(runDir, spec.output_path))
+    return { error: "ERROR: the grid spec's output_path is outside this run's folder. The driver writes the spec inside the run; use the path it gave you." };
   return { spec };
 }
 

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

@@ -28,6 +28,7 @@
 //   `GET /trademarks/{n}/image` answers 200 with real image bytes. The tool returns metadata + the
 //   Vienna figurative-element codes rather than the bytes; see the core for why.
 import { serve } from "./stdio-server.mjs";
+import { sendUntilFromEnv } from "../../../providers/_shared/send-until.mjs";
 import { crowdNoteFor } from "./crowd-note.mjs";   // how the unit decides on a crowd, beside an answer that carries one
 import {
   CAPABILITIES, CRED_ENV, doSearch, doRecordFetch, doBatchScreen, doImageFetch,
@@ -51,6 +52,7 @@ const tctx = (kind) => ({
   agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
+  sendUntilMs: sendUntilFromEnv(),   // this turn's time to stop sending (providers/_shared/send-until.mjs)
 });
 const passthrough = (r) => (r && typeof r === "object" ? (r.text ?? JSON.stringify(r)) : String(r));
 const guard = (fn) => async (args) => {

package/driver/engine/mcp/free-tier-server.mjs

@@ -30,6 +30,7 @@
 // Telemetry: the core writes CLEAROTRON_REGISTER_CALL_LOG / CLEAROTRON_REGISTER_RECORD_LOG (the SHARED register
 // ledger) under the provider id `free-tier`, keyed by the gateway session key.
 import { serve } from "./stdio-server.mjs";
+import { sendUntilFromEnv } from "../../../providers/_shared/send-until.mjs";
 import { crowdNoteFor } from "./crowd-note.mjs";   // how the unit decides on a crowd, beside an answer that carries one
 import {
   CAPABILITIES, doSearch, doRecordFetch, doBatchScreen, doImageFetch, doEnumerate, doExecutePlan,
@@ -47,6 +48,7 @@ const tctx = (kind) => ({
   agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
+  sendUntilMs: sendUntilFromEnv(),   // this turn's time to stop sending (providers/_shared/send-until.mjs)
 });
 const passthrough = (r) => (r && typeof r === "object" ? (r.text ?? JSON.stringify(r)) : String(r));
 const CAPABILITY_OFFICES = CAPABILITIES.offices.covered.join("+");

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

@@ -900,6 +900,21 @@ function serverEnv({ sessionKey, agent, runDir, recordAxis, bandGroups = false }
 
 // Build the mcp-config object for a set of groups. Returns { config: <object>, servers: [...] } or null if
 // the groups need no MCP server (e.g. caselaw-only EUR-Lex via WebFetch needs no server but the bridges do).
+/**
+ * The stage's tool config for ONE turn, with that turn's time to stop sending handed to every server
+ * (providers/_shared/send-until.mjs). Built per turn, because each attempt has its own deadline. The config
+ * is the JSON string the engines take; anything that is not one is returned as it came. PURE.
+ */
+export function withSendUntil(mcpConfigJson, sendUntilMs) {
+  if (typeof mcpConfigJson !== "string" || !Number.isFinite(Number(sendUntilMs))) return mcpConfigJson;
+  let cfg;
+  try { cfg = JSON.parse(mcpConfigJson); } catch { return mcpConfigJson; }
+  if (!cfg?.mcpServers || typeof cfg.mcpServers !== "object") return mcpConfigJson;
+  for (const server of Object.values(cfg.mcpServers))
+    if (server && typeof server === "object") server.env = { ...(server.env ?? {}), CLEAROTRON_GATHER_SEND_UNTIL_MS: String(Math.floor(Number(sendUntilMs))) };
+  return JSON.stringify(cfg);
+}
+
 export function buildGatherMcpConfig(groups = [], { sessionKey, agent, runDir, recordAxis, bandGroups = false } = {}) {
   const localKeys = new Set(), bridgeKeys = new Set();
   for (const g of groups) { const r = resolveGroup(g); r.local.forEach((k) => localKeys.add(k)); r.bridges.forEach((k) => bridgeKeys.add(k)); }

package/driver/engine/mcp/held-answers.mjs

@@ -15,7 +15,8 @@
 // is the same as one naming them. Owner names are compared as written, never merged. A different scope is a
 // different question, and an earlier answer that failed is no answer: both are asked again. A question that timed out
 // at the gateway is the one failure held, by the executor rather than here: its timeout stands until the envelope
-// close asks it once more (execute-plan.mjs, timedOutBefore).
+// close asks it once more (execute-plan.mjs, timedOutBefore). An answer in a slice the run took out of its band
+// because a check could not prove it ran is asked again too, whatever wrote the band since.
 
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -23,6 +24,7 @@ import { driverDir } from "../../../shared/driver-dir.mjs";
 import { OUTSTANDING_REASON } from "../../../providers/_shared/follow-up-searches.mjs";
 import { awaitsReadingTurn } from "../../../providers/_shared/plan-guards.mjs";
 import { releasedFamilyQids } from "../../withheld-families.mjs";
+import { bandWithSlicesOut, slicesTakenOutByAxis } from "../../../shared/slices-taken-out.mjs";
 
 const QUESTION_FIELDS = ["predicate", "term", "terms", "romanizedTerms", "term_literal", "nice_classes", "regions", "goods_text", "owner", "expected_kind"];
 const sorted = (v) => [...v].map((x) => String(x)).sort();
@@ -88,7 +90,9 @@ export function refuseHeldQuestions(entries, held, planRegions = []) {
 }
 
 // The run's questions and answers as its files hold them: the frozen plan, each worker's supplemental plan, and every
-// band's blocks by qid. IMPURE.
+// band's blocks by qid, with the slices the searches record took out read as the open slices they were delivered as
+// (shared/slices-taken-out.mjs). They are read out after the cache, which knows a band's size and time and not the
+// record's. IMPURE.
 function readRunQuestions(runDir) {
   const units = join(runDir, "register-units");
   const blocksByQid = new Map();
@@ -96,8 +100,12 @@ function readRunQuestions(runDir) {
   try { plans.push({ axis: null, plan: JSON.parse(readFileSync(driverDir(runDir, "register-plan.json"), "utf8")) }); } catch { /* no frozen plan */ }
   let files = [];
   try { files = readdirSync(units); } catch { files = []; }
+  const takenOut = slicesTakenOutByAxis(runDir);
   for (const f of files) {
-    if (f.endsWith("-band.json")) for (const b of readBlocks(join(units, f))) if (b?.qid) blocksByQid.set(String(b.qid), b);
+    if (f.endsWith("-band.json")) {
+      const { blocks } = bandWithSlicesOut(readBlocks(join(units, f)), takenOut.get(f.slice(0, -"-band.json".length)));
+      for (const b of blocks) if (b?.qid) blocksByQid.set(String(b.qid), b);
+    }
     if (f.endsWith("-supplemental-plan.json")) {
       try { plans.push({ axis: f.slice(0, -"-supplemental-plan.json".length), plan: JSON.parse(readFileSync(join(units, f), "utf8")) }); } catch { /* torn: skipped */ }
     }

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

@@ -29,7 +29,8 @@ import { parsePrRiskResults, connotationObligations, renderConnotationObligation
 // What stays is the GRID path's own need — the obligations sidecar written beside the grid's ledger.
 import { obligationsSidecarPath } from "../../disposition-tool.mjs";
 import { writeGridProvenance } from "./grid-provenance.mjs";   // — what served the grid, beside the ledger
-import { keepResearchAnswer } from "../../research-answers.mjs";   // each answer's text, kept for a later attempt of its stage
+import { insideRun } from "../../../shared/inside-run.mjs";   // a path a tool is handed is served only inside this run
+import { keepResearchAnswer, researchReplayOn, savedResearchAnswer } from "../../research-answers.mjs";   // each answer's text, kept for a later attempt of its stage; a replay answers from them
 
 const API_KEY = process.env.PERPLEXITY_API_KEY || "";
 
@@ -219,14 +220,21 @@ function judgeBlock(cands, part, gridSpecPath, reserve = 0) {
 }
 
 async function research(params) {
+  // A REPLAY SENDS NOTHING OUT, so it is answered before the key is asked for: an offline replay needs none.
+  if (researchReplayOn(RUN_DIR)) return replayResearch(params);
   if (!API_KEY) return "ERROR: PERPLEXITY_API_KEY not set — marketplace research unavailable.";
   const { task, depth, model: modelOverride, allow_fetch = false, domain_filter, enable_sandbox = false, response_schema, schema_name, grid_spec_path, part } = params;
 
   // ── Deterministic grid mode: the caller dictates the cells; the tool runs + captures them. ──
   if (grid_spec_path) {
+    // THIS RUN'S SPEC, WRITING THIS RUN'S LEDGER: a spec, or a ledger it names, in another run's folder is never served.
+    if (RUN_DIR && !insideRun(RUN_DIR, grid_spec_path))
+      return "ERROR: grid_spec_path is outside this run's folder. The driver writes the spec inside the run; use the path it gave you.";
     let spec;
     try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
     catch (err) { return `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.`; }
+    if (RUN_DIR && !insideRun(RUN_DIR, spec.output_path))
+      return requiredLedgerRefusal("ERROR: the grid spec's output_path is outside this run's folder. The driver writes the spec inside the run; use the path it gave you.", { spec, gridSpecPath: grid_spec_path });
     if (!underStudioSegment(spec.output_path))   // either spelling: an install keeps the studio segment it has
       return requiredLedgerRefusal(`ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}`, { spec, gridSpecPath: grid_spec_path });
     // — already recorded and complete? Answer from the ledger; do not buy the grid twice. This is also
@@ -309,6 +317,26 @@ async function research(params) {
   }
 }
 
+// ── A REPLAY: THE RUN'S OWN ANSWER, OR NOTHING ─────────────────────────────────────────────────────────
+//
+// In the experiment sandbox under `--research replay` (research-answers.mjs), a question the run already asked
+// gets the answer the run got, and any other question, a grid among them, is refused: nothing goes out to the
+// research service. Both are logged as a lookup is, marked as a replay, so the arm's reading log says which.
+function replayResearch(params) {
+  const { task, grid_spec_path } = params ?? {};
+  if (grid_spec_path) {
+    logCall("perplexity_research", { task: task ?? "", grid: true, replay: true }, { ok: false, error: "replay: grid not replayed" });
+    return "ERROR: replay — this replays the run's saved research answers and runs no grid; nothing was sent to the research service.";
+  }
+  const saved = savedResearchAnswer(RUN_DIR, task);
+  if (!saved) {
+    logCall("perplexity_research", { task: task ?? "", replay: true }, { ok: false, error: "replay: no saved answer" });
+    return "ERROR: replay — the run asked no question worded exactly like this one, so there is no saved answer to give; nothing was sent to the research service.";
+  }
+  logCall("perplexity_research", { task, replay: true }, { ok: true, bytes: saved.text.length, replayed: true });
+  return saved.text;
+}
+
 serve({
   name: "perplexity", version: "0.1.0",
   tools: [{

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

@@ -1046,7 +1046,10 @@ serve({
       "are. The driver renders narrative.md and findings.json. Your coverage rows are joined to this " +
       "run's plan-execution receipt as you send them, so a clean claim over a slice that did not run is " +
       "refused here — in this turn, where restating it is free — rather than at a gate that can only " +
-      "re-ask the whole stage. The answer tells you what was stored, or names the exact defect token.",
+      "re-ask the whole stage. The answer tells you what was stored, or names the exact defect token. " +
+      "Save each finding as you complete it, alone or a few at a time, with `save_findings`: each is checked as " +
+      "the record checks a finding and kept the moment it passes, so a stopped attempt loses none of them. The " +
+      "call that sends the whole record takes every saved finding for a position it does not carry itself.",
     inputSchema: {
       type: "object",
       // ── NO BLANKET `required`, AND THAT IS THE FIX FOR ─────────────────────────
@@ -1079,6 +1082,18 @@ serve({
       // reads the run's own accepted-call record rather than trusting the shape. That check is older
       // than this change and is the reason relaxing `required` costs nothing.
       properties: {
+        // A COMPLETED FINDING, KEPT BEFORE THE WHOLE RECORD EXISTS (synthesis-record.mjs, `saveFindings`). Its items
+        // are findings as the record carries them, declared from the same key ladder as a patch row.
+        save_findings: {
+          type: "array",
+          description:
+            "COMPLETED FINDINGS, saved before the whole record exists. Send one or a few complete finding objects as the findings record carries them, and nothing else on the call. Each is checked as the record checks a finding and kept as soon as it passes; one that is refused leaves the others saved. A finding saved again for the same position replaces the earlier one. Saving writes no report: the record is complete only when you send `narrative` with `findings`, and that call takes every saved finding for a position it does not carry.",
+          items: {
+            type: "object",
+            description: "One complete finding object, as the findings record carries it.",
+            properties: Object.fromEntries(FINDING_KEYS_CURRENT.map((k) => [k, { description: `Part of the finding record; see findings-model.mjs for what \`${k}\` carries.` }])),
+          },
+        },
         findings_patch: {
           type: "array",
           description:

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

@@ -9,6 +9,7 @@
 // keyed by the GATEWAY session key (tctx.sessionKey) — we thread the run's session key via
 // CLEAROTRON_GATHER_SESSION_KEY so the $0 provider-usage diff still attributes calls to the run.
 import { serve } from "./stdio-server.mjs";
+import { sendUntilFromEnv } from "../../../providers/_shared/send-until.mjs";
 import { crowdNoteFor } from "./crowd-note.mjs";   // how the unit decides on a crowd, beside an answer that carries one
 import { doSearch, doRecordFetch, doEnumerate, doExecutePlan, DEFAULT_BASE } from "../../../providers/signa/src/core.js";
 import { proposeSupplemental } from "./supplemental.mjs";
@@ -22,6 +23,7 @@ const tctx = (kind) => ({
   agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
+  sendUntilMs: sendUntilFromEnv(),   // this turn's time to stop sending (providers/_shared/send-until.mjs)
 });
 const passthrough = (r) => (r && typeof r === "object" ? (r.text ?? JSON.stringify(r)) : String(r));
 const guard = (fn) => async (args) => {

package/driver/engine/mcp/supplemental.mjs

@@ -34,8 +34,10 @@ import { dirname, join } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { PLAN_PREDICATES, PLAN_MAX_OR_WIDTH, PLAN_MAX_NAME_LENGTH, planExactOrWidth, planPhoneticOrWidth, fingerprint, ownerIntersectionGap, goodsTextGap, resolveRegions, houseElementOf, withoutHouseElementTerms, containsFormSubstitution } from "../../register-plan.mjs";
 import { entryTermIssues } from "../../../providers/_shared/term-shape.mjs";
-import { OUTSTANDING_REASON } from "../../../providers/_shared/follow-up-searches.mjs";
+import { OUTSTANDING_REASON, runDriverDirOf } from "../../../providers/_shared/follow-up-searches.mjs";
+import { pathInRun } from "../../../shared/inside-run.mjs";   // the band path is served only inside this run
 import { heldAnswers, questionKey } from "./held-answers.mjs";
+import { bandWithSlicesOut, slicesTakenOutByAxis } from "../../../shared/slices-taken-out.mjs";
 import { readWithheldFamilies } from "../../withheld-families.mjs";
 import { addedClassBound, boundAddedClasses } from "../../frame-diff-model.mjs";   // an added class takes one question, the identical mark
 import { scriptQuestionsByMarket } from "../../registration-scripts.mjs";   // one script question per market on the plan's list
@@ -390,6 +392,10 @@ export async function proposeSupplemental(params, tctx, deps) {
   const proposals = Array.isArray(params?.proposals) ? params.proposals : null;
   if (!axis || !outPath || !proposals || !proposals.length)
     return { type: "text", text: "ERROR: axis, output_path and a non-empty proposals[] are all required." };
+  // The supplemental plan is written beside the band, so the band path must be this run's before anything is written.
+  const runOf = runDriverDirOf(tctx?.recordLog);
+  if (runOf && pathInRun(dirname(runOf), outPath) === null)
+    return { type: "text", text: "ERROR: output_path is outside this run's folder. Use the band path the driver gave you." };
 
   const suppPath = join(dirname(outPath), `${axis}-supplemental-plan.json`);
   // ── the supplemental plan INHERITS the frozen plan's regions (review findings 4/12) ───────────────
@@ -573,11 +579,13 @@ export async function proposeSupplemental(params, tctx, deps) {
   }
 
   // A question this worker re-proposes that already holds an answer is not run again: the answer stands. One with no
-  // answer, a failed one, or one this call enriched or gave its markets runs as before.
+  // answer, a failed one, one whose slice the run took out of the band because a check could not prove it ran
+  // (shared/slices-taken-out.mjs), or one this call enriched or gave its markets runs as before.
   let reusedHeld = [];
   try {
     const own = new Map();
-    for (const b of JSON.parse(readFileSync(outPath, "utf8"))) if (b?.qid) own.set(String(b.qid), b);
+    const { blocks } = bandWithSlicesOut(JSON.parse(readFileSync(outPath, "utf8")), slicesTakenOutByAxis(dirname(dirname(outPath))).get(axis));
+    for (const b of blocks) if (b?.qid) own.set(String(b.qid), b);
     reusedHeld = reused.filter((q) => { const b = own.get(String(q)); return b && b.error !== true && !enrichedQids.includes(q) && !staleOnDisk; });
   } catch { reusedHeld = []; }
   const qids = [...minted.map((e) => e.qid), ...reused.filter((q) => !reusedHeld.includes(q))];

package/driver/engine/mcp/uspto-local-server.mjs

@@ -32,6 +32,7 @@
 // visible where a spawn and a reviewer each actually look — the tool list here, the REGISTER_SERVERS
 // filter in gather-config.mjs, and the exact-six pin in driver/test/engine.gather.test.mjs.
 import { serve } from "./stdio-server.mjs";
+import { sendUntilFromEnv } from "../../../providers/_shared/send-until.mjs";
 import { crowdNoteFor } from "./crowd-note.mjs";   // how the unit decides on a crowd, beside an answer that carries one
 import {
   CAPABILITIES, DEFAULT_DB_ENV, doSearch, doRecordFetch, doBatchScreen, doEnumerate, doExecutePlan,
@@ -48,6 +49,7 @@ const tctx = (kind) => ({
   agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
+  sendUntilMs: sendUntilFromEnv(),   // this turn's time to stop sending (providers/_shared/send-until.mjs)
 });
 const passthrough = (r) => (r && typeof r === "object" ? (r.text ?? JSON.stringify(r)) : String(r));
 const guard = (fn) => async (args) => {

package/driver/engine/openai-agent.mjs

@@ -317,8 +317,10 @@ export function sweepStaleCodexHomes(root, { now = Date.now(), alive = processAl
   for (const e of entries) {
     if (!e.isDirectory() || !/^(?:stage|turn)-/.test(e.name)) continue;
     const dir = join(root, e.name);
-    if (OWNED.has(dir)) continue;
-    const maker = e.name.match(MAKER_RE);
+    // A home's working folder is judged by its home's name, and goes when its home's maker has ended.
+    const home = e.name.endsWith(WORK_SUFFIX) ? e.name.slice(0, -WORK_SUFFIX.length) : e.name;
+    if (OWNED.has(join(root, home))) continue;
+    const maker = home.match(MAKER_RE);
     let stale;
     if (maker) stale = Number(maker[1]) !== process.pid && !alive(Number(maker[1]));
     else { try { stale = now - statSync(dir).mtimeMs > STALE_UNMARKED_MS; } catch { stale = false; } }
@@ -329,7 +331,7 @@ export function sweepStaleCodexHomes(root, { now = Date.now(), alive = processAl
 }
 
 const removeOwned = () => {
-  for (const dir of OWNED) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  for (const dir of OWNED) for (const d of [dir, workFolderOf(dir)]) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ } }
   OWNED.clear();
 };
 
@@ -363,13 +365,46 @@ export function makeCodexHome(prefix) {
   return dir;
 }
 
-/** Remove a home this process made. Best-effort: never throws. */
+/** Remove a home this process made, and its working folder. Best-effort: never throws. */
 export function releaseCodexHome(dir) {
   if (!dir) return;
   OWNED.delete(dir);
-  try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  for (const d of [dir, workFolderOf(dir)]) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ } }
 }
 
+// ── A STAGE'S TEMPORARY FILES ARE ITS OWN ─────────────────────────────────────────────────────────────
+//
+// The stage's profile granted the account's temp folder and `/tmp`, both shared by every stage of every run on
+// the machine, and nothing removed what a stage left there. In a test run of a crowded matter, 2026-10-27, the
+// writer's commands found and read the working notes, a state file with ratings, and a families file that an
+// earlier run's writer had left in `/tmp` the day before. A run must read nothing from another run.
+//
+// So each home has one working folder of its own, beside it and never inside it (the home holds the sign-in,
+// which the profile never names). The turn's TMPDIR, TMP and TEMP name it, and the profile grants it in place
+// of the shared folders. It lives as long as its home: a stage's ladder shares one home across its attempts,
+// its warm resumes and its repair turns, so they keep the notes they made, and the folder goes when the ladder
+// settles. A home whose maker has ended takes its working folder with it in the sweep.
+const WORK_SUFFIX = ".work";
+/** The working folder of a Codex home. PURE. */
+export const workFolderOf = (home) => `${home}${WORK_SUFFIX}`;
+/** Make a home's working folder if it is not there yet, private to the account. Returns its path. */
+export function ensureWorkFolder(home) {
+  const dir = workFolderOf(home);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+/** The turn's environment with every temp-folder name pointing at the home's working folder. PURE. */
+export function withWorkFolder(env, dir) {
+  return { ...env, TMPDIR: dir, TMP: dir, TEMP: dir };
+}
+
+// WHAT THE MODEL IS TOLD, as the design ruling of 2026-10-27 approved it (its section on isolation). It describes the
+// mechanism and replaces nothing: the profile is what keeps another run's files out of reach. Codex alone carries it,
+// since only a Codex stage runs commands and only a Codex turn has a working folder of its own.
+export const TEMP_FOLDER_RULE = "Keep temporary working files in the directory given by TMPDIR. Use only this run's supplied evidence and accepted work.";
+/** The instructions every Codex turn carries: the output rule, then the temp-folder rule. */
+export const CODEX_DEVELOPER_INSTRUCTIONS = `${WRITE_DISCIPLINE} ${TEMP_FOLDER_RULE}`;
+
 /**
  * The folder holding codex's own programs, which the stage's profile must let it read. codex runs every
  * shell command through a helper of its own inside the sandbox, so a profile that cannot read the helper
@@ -884,7 +919,10 @@ export const openaiAgentEngine = {
     let authMaster = null, seeded = null;
     try {
       // Auth toggle (may throw loud on api-key-without-key — a config error, not a retryable failure).
-      const { env, mode } = spawnEnv(process.env, codexHome);
+      const { env: baseEnv, mode } = spawnEnv(process.env, codexHome);
+      // The home's own working folder, as the turn's temp folder, with the sandbox on or off.
+      const workDir = ensureWorkFolder(codexHome);
+      const env = withWorkFolder(baseEnv, workDir);
       if (mode === "subscription") {
         const af = authFilePath(process.env);
         if (!existsSync(af))
@@ -906,16 +944,17 @@ export const openaiAgentEngine = {
       // backstop if a tool consumes the lot.
       //
       // — the fence: with the sandbox on, the stage's commands read only the instruction trees, the run
-      // folder and the temp folders (codex-config.mjs, `fenceToml`). The same roots claude's file tools get.
+      // folder and the home's working folder (codex-config.mjs, `fenceToml`). The same roots claude's file
+      // tools get, and a working folder claude needs none of, since no claude stage runs a command.
       //
       // — what those commands inherit: none of the register and research keys the program holds for its
       // tool servers, and not the Codex key (engine-env.mjs, `codexCommandWithheld`), with codex's shell
       // snapshot off because it replays them (codex-config.mjs, `commandEnvToml`). With the sandbox on or
       // off, since the bypass builds no fence and a command could otherwise print them.
       const fence = codexSandboxBypassed() ? null
-        : { runDir, readRoots: [...(skillsGrantRoots?.length ? skillsGrantRoots : [skillsDir]), codexProgramRoot(codexBin())].filter(Boolean) };
+        : { runDir, workDir, readRoots: [...(skillsGrantRoots?.length ? skillsGrantRoots : [skillsDir]), codexProgramRoot(codexBin())].filter(Boolean) };
       writeFileSync(join(codexHome, "config.toml"),
-        renderCodexConfigToml({ mcpConfig, allowedTools, developerInstructions: WRITE_DISCIPLINE, toolTimeoutSec: timeoutSec, fence,
+        renderCodexConfigToml({ mcpConfig, allowedTools, developerInstructions: CODEX_DEVELOPER_INSTRUCTIONS, toolTimeoutSec: timeoutSec, fence,
           withheldFromCommands: codexCommandWithheld() }));
 
       const input = absolutizeSkillRefs(message, skillsDir, resolveSkill);

package/driver/envelope-settle.mjs

@@ -37,6 +37,7 @@
 import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { isCapabilityGapReason } from "./coverage-ledger.mjs";
 import { fullyDeferredAxes } from "./register-plan.mjs";
+import { readPartNotCompleted } from "./parts-not-completed.mjs";
 
 export const SETTLE_SCHEMA_VERSION = 1;
 
@@ -194,9 +195,18 @@ export function settleTriedAfter(prior, dispatched, planVersion) {
   return [...out.values()];
 }
 
-/** The run's sticky capability gaps, by qid → row. Absent or unreadable decision ⇒ none. */
+/**
+ * The run's sticky gaps, by qid → row: the capability gaps it accepted, and the slices a check could not prove ran,
+ * which the searches' record took out of the band once their recovery was spent (parts-not-completed.mjs). Neither is
+ * sent to the provider again, settled again or re-run to close. Absent or unreadable decision and record ⇒ none.
+ */
 export function readStickyGaps(P) {
-  return new Map((readEnvelopeDecision(P)?.sticky_gaps ?? []).map((g) => [String(g?.qid ?? ""), g]).filter(([q]) => q));
+  const out = new Map((readEnvelopeDecision(P)?.sticky_gaps ?? []).map((g) => [String(g?.qid ?? ""), g]).filter(([q]) => q));
+  for (const s of (P?.runDir ? readPartNotCompleted(P.runDir, "searches")?.slices : null) ?? []) {
+    const qid = String(s?.qid ?? "");
+    if (qid && !out.has(qid)) out.set(qid, { qid, axis: String(s.axis ?? ""), reason: String(s.reason ?? "").slice(0, 400) });
+  }
+  return out;
 }
 
 /** One history entry per superseded decision. Returns the prior history with the old decision appended. */
@@ -225,7 +235,7 @@ export function supersede(prior, source) {
 export async function settleReceipt({ P, plan, receipt, dispatch = null, rejoin = null, now = null }) {
   const deferred = receipt?.deferred ?? [];
   const prior = readEnvelopeDecision(P);
-  const sticky = new Set((prior?.sticky_gaps ?? []).map((g) => String(g?.qid ?? "")));
+  const sticky = new Set(readStickyGaps(P).keys());
   let { accepted, suspect } = partitionReceiptDeferrals(plan, receipt, { sticky });
   const closed = [], closeFailed = [];
   const tried = new Map((prior?.settle_tried ?? []).map((t) => [String(t?.qid ?? ""), t]));

package/driver/findings-model.mjs

@@ -2670,3 +2670,20 @@ export function topKeysForVersion(schemaVersion) {
   const v = typeof schemaVersion === "number" ? schemaVersion : 1;
   return [...topKeysFor({ v4: v >= 4, v5: v >= 5, v6: v >= 6, v7: v >= 7 })];
 }
+
+/**
+ * ONE FINDING, CHECKED AS THE WHOLE RECORD CHECKS IT, before the record exists. The writer saves a completed finding as
+ * it completes it, and a saved finding must pass exactly what it would pass inside the record, under the schema the
+ * record is written at and the run's frozen framework and method. The record-wide rules (an empty record, ordinals
+ * unique across the record, the actions and the coverage) belong to the record and are checked when it is complete.
+ * Returns the finding as validated; throws the record's own token-first refusal. PURE.
+ */
+export function validateFindingForSave(f, opts = {}) {
+  const schemaVersion = FINDINGS_SCHEMA_VERSION;
+  const mode = { v4: schemaVersion >= 4, v5: schemaVersion >= 5, v6: schemaVersion >= 6, v7: schemaVersion >= 7, manifest: opts.manifest ?? null,
+    method: "method" in opts ? (opts.method ?? null) : undefined,
+    recordOrigins: Array.isArray(opts.recordOrigins) ? opts.recordOrigins : null, foreignLinks: Array.isArray(opts.recordOrigins) ? [] : null };
+  const out = validateFinding(f, 0, new Set(), mode);
+  throwForeignLinks(mode);
+  return out;
+}

package/driver/gateway.mjs

@@ -224,7 +224,8 @@ export function toolWrittenArtifact(p) {
     ?? TOOL_WRITTEN_PATTERNS.find((r) => r.re.test(base))
     ?? null;
 }
-import { buildGatherMcpConfig, allowedToolsFor, toolGroupsForStage, recordAxisFor, seatWritesForGroups } from "./engine/mcp/gather-config.mjs";
+import { buildGatherMcpConfig, allowedToolsFor, toolGroupsForStage, recordAxisFor, seatWritesForGroups, withSendUntil } from "./engine/mcp/gather-config.mjs";
+import { sendReserveMs } from "../providers/_shared/send-until.mjs";   // each turn's plan calls stop sending ahead of its deadline
 import { everyToolCallRefused } from "./engine/tool-refusal.mjs";   // one definition, shared with the engine probe
 export { everyToolCallRefused };
 // The profiles STORE root, for the write boundary only — read from the module that owns it, never
@@ -297,11 +298,11 @@ export function isEmbeddedFallback(json, stderr = "") {
 // nonzero exit (the v14 delivery failure, previously mislabelled `nonzero_exit_1`); (3) any nonzero
 // exit whose wall already reached the configured budget. Distinguished from transient errors so the
 // retry policy can give a slow stage ONE longer shot instead of 3 identical doomed attempts.
-export function isTimeout({ killed, code, wall, stderr = "", timeoutSec }) {
-  if (killed) return true;
-  if (/EmbeddedAttemptSessionTakeoverError|request timed out|\bETIMEDOUT\b/i.test(stderr)) return true;
-  if (code !== 0 && wall >= timeoutSec) return true;
-  return false;
+export const isTimeout = (facts) => timeoutCause(facts) !== null;
+export function timeoutCause({ killed, code, wall, stderr = "", timeoutSec }) {   // which signal fired, or null
+  if (killed) return "killed";
+  if (/EmbeddedAttemptSessionTakeoverError|request timed out|\bETIMEDOUT\b/i.test(stderr)) return "stderr";
+  return code !== 0 && wall >= timeoutSec ? "wall" : null;
 }
 
 // A LANE WEDGE: a timeout whose turn moved ZERO tokens — the gateway never admitted it to a command lane (the
@@ -942,6 +943,9 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
       }
     }
   }
+  // EACH TURN'S OWN COPY of the stage's tool config, carrying that turn's time to stop sending: ahead of the turn's
+  // deadline by the reserve, so a plan call returns what it holds while the turn can still write it (send-until.mjs).
+  const turnConfig = (sec) => withSendUntil(gatherMcpConfig, Date.now() + sec * 1000 - sendReserveMs(sec));
   let lastFail;
   // — WHAT ACTUALLY RAN, carried out to the caller. The attempt rows have held the truth all along
   // (`modelActual` from the wire, `modelUsed` from the engine's own resolver); the ladder simply never
@@ -1125,13 +1129,14 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
     // the snapshot, which only widens the window by their own time: an earlier attempt's refusals all
     // precede its own settle, so they stay outside it.
     const dispatchedAt = Date.now();
+    const mcpConfig = turnConfig(effTimeout);   // this turn's copy, with its time to stop sending
     for (const line of describeMethodologyDrift(witnessStageMethodology(runDir, name, effMessage, engineResolveSkill)))
       note(`[${name}] ${line}`);
     // — the frozen judged-by set, hashed into THIS PROCESS'S MEMORY before the seat runs. Never
     // written to disk before the comparison, so the thing being watched cannot reach it. See
     // run-integrity.mjs for why it is not a manifest file and why the append-only journals are excluded.
     const integrityBefore = frozenSnapshot(runDir);
-    const turn = await engine.runTurn({ agent, sessionKey: key, message: effMessage, grantDispatch: base, model, thinking, timeoutSec: effTimeout, resumeRef: warm ? lastSessionRef : undefined, codexHome: stageCodexHome, mcpConfig: gatherMcpConfig, allowedTools: gatherAllowedTools, seatWrites: gatherSeatWrites, skillsDir: engineSkillsDir, skillsGrantRoots: engineSkillsGrantRoots, profilesDir: profilesStoreDir, resolveSkill: engineResolveSkill, runDir, stallSec,
+    const turn = await engine.runTurn({ agent, sessionKey: key, message: effMessage, grantDispatch: base, model, thinking, timeoutSec: effTimeout, resumeRef: warm ? lastSessionRef : undefined, codexHome: stageCodexHome, mcpConfig, allowedTools: gatherAllowedTools, seatWrites: gatherSeatWrites, skillsDir: engineSkillsDir, skillsGrantRoots: engineSkillsGrantRoots, profilesDir: profilesStoreDir, resolveSkill: engineResolveSkill, runDir, stallSec,
       progressFiles: files,   // the no-progress watchdog's artifact-advance signal (anthropic-agent; other adapters ignore it)
       // The raw stream of this session, beside its dispatch record (engine/session-record.mjs). The engines
       // keep it while the disk has room and say on the tuple's `stream` what landed.
@@ -1282,7 +1287,10 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
     let fail = null;
     let stampedQuantity = null;   //: a validator's own exact count, when it stamped one (see below)
     let failingFile = null;       //: the artifact the validator rejected — the repair's only target
-    if (isTimeout({ killed, code, wall, stderr, timeoutSec: effTimeout })) fail = "timeout";
+    // A TURN THAT COMPLETED IS JUDGED ON WHAT IT WROTE, whatever its stderr says about a request inside it
+    // (attemptTimedOut). Which signal fired is kept on the row either way.
+    const timedOutBy = timeoutCause({ killed, code, wall, stderr, timeoutSec: effTimeout });
+    if (attemptTimedOut({ cause: timedOutBy, code, json })) fail = "timeout";
     else if (isEmbeddedFallback(json, stderr)) fail = "embedded_fallback";
     else if (code !== 0) fail = `nonzero_exit_${code}`;
     else if (!json) fail = "unparseable_json";
@@ -1354,7 +1362,7 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
       // under the run dir to win the grant back, and warmPatchMessage renders the target through rel();
       // a relative path there would silently strip the write root off the one turn that needs it most.
       const rt = await engine.runTurn({ agent, sessionKey: key, message: repairMessage, model, thinking,
-        timeoutSec: effTimeout, resumeRef: repairRef, codexHome: stageCodexHome, mcpConfig: gatherMcpConfig, allowedTools: gatherAllowedTools,
+        timeoutSec: effTimeout, resumeRef: repairRef, codexHome: stageCodexHome, mcpConfig: turnConfig(effTimeout), allowedTools: gatherAllowedTools,
         skillsDir: engineSkillsDir, skillsGrantRoots: engineSkillsGrantRoots, profilesDir: profilesStoreDir, resolveSkill: engineResolveSkill, runDir, stallSec,
         progressFiles: files, streamFile: streamFilePath(runDir, name, attempt, formRepairsUsed + 1) });
       repairRef = rt.sessionRef ?? repairRef;
@@ -1819,6 +1827,7 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
         // `followup` matters too: a followup success PATCHES the prior session's output, it never
         // supersedes a taint the way a fresh full pass does.
         killed: killed || undefined,
+        timeoutCause: timedOutBy ?? undefined,   // — which of the three timeout signals fired: killed, stderr or wall
         signals: turn.signals ?? undefined,
         //: how long every declared artifact had been untouched when the turn settled. Present on any
         // hard-wall kill the wall rescue looked at — INCLUDING the ones it refused, so "considered and
@@ -1899,7 +1908,7 @@ async function runStageLadder(name, opts, stageCodexHome = null) {
           cliVersion: cli.version, cliVersionProbe: cli.probe, ...(cli.why ? { cliVersionWhy: cli.why } : {}), cliSource: cli.source,
         cliFloor: cli.floor ?? null, cliBelowFloor: cli.belowFloor ?? null,
           wrote, warm: warm || undefined, warmEscalated: attempt === warmEscalatedAt || undefined,
-          rescued: rescued ?? undefined, killed: killed || undefined,
+          rescued: rescued ?? undefined, killed: killed || undefined, timeoutCause: timedOutBy ?? undefined,
           quiescentMs: Number.isFinite(quiescentMs) ? Math.round(quiescentMs) : undefined,   // — see the per-stage row
           rescueRefused: rescueRefused ?? undefined,   // — the cause, when the rescue looked and refused
           rescueRefusedFile: rescueRefusedFile ?? undefined, rescueRefusedReason: rescueRefusedReason ?? undefined,
@@ -3735,3 +3744,15 @@ function toolCallCounts(turn) {
   return { toolCallsRefused: n(turn?.toolCallsRefused), commandToolCalls: n(turn?.commandToolCalls), mcpToolCalls: n(turn?.mcpToolCalls),
     toolCallsErroredByName: errored && typeof errored === "object" && !Array.isArray(errored) ? { ...errored } : null };
 }
+
+/**
+ * IS THIS ATTEMPT A TIMEOUT? A kill and a run past the limit with a non-zero exit always are. A timed-out request named
+ * in stderr is one only when the turn did not complete: a turn that exited 0 with its engine's status ok outlived the
+ * request, which was a call inside it (a web lookup, a tool), and is judged on what it wrote like any finished turn.
+ * Recorded as a timeout, it was run again whole: on one test run a writer finished in 14.7 minutes of its 43, exited 0
+ * with its output written, and paid a second attempt of 20.3 minutes. `cause` is `timeoutCause`'s answer. PURE.
+ */
+export function attemptTimedOut({ cause, code, json }) {
+  if (!cause) return false;
+  return !(cause === "stderr" && code === 0 && json?.status === "ok");
+}

package/driver/package.json

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