clearotron 0.5.0-beta.3 → 0.5.0-beta.4

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "9a5ba90756f37ddefaee2a21ab79e9f7a374667a",
-  "version": "0.5.0-beta.3"
+  "commit": "7c6882de2e3c147992a6667bbce24de9fffb5206",
+  "version": "0.5.0-beta.4"
 }

package/docs/architecture/03-run-lifecycle.md

@@ -438,6 +438,7 @@ node pipeline.mjs --job <file.json> [--agent <id>]        # cold run (still take
 node pipeline.mjs --resume <codename>                     # idempotent resume: valid outputs skip
 node pipeline.mjs --resume <codename> --from <stage>      # force re-run from a stage ordinal
 node pipeline.mjs --resume <codename> --experiment <stage> [--label <t>]                  # shadow dir
+node pipeline.mjs --resume <codename> --experiment synthesis --research replay           # research from the run's own answers
 ```
 
 - **Resume** refuses a delivered run (any of the three delivered markers above — re-handing off a
@@ -448,6 +449,11 @@ node pipeline.mjs --resume <codename> --experiment <stage> [--label <t>]
 - **`--experiment`** runs one stage in a shadow dir (`_experiments/<ts>-<tag>/`) on copies of its
   inputs, under a `clearance-exp-…` session key that is excluded from the run's provider-usage
   attribution. The canonical run is untouched.
+- **`--research replay`** answers the arm's research from the answers the run saved
+  (`_driver/research-answers.jsonl`, copied into the shadow dir). A question the run asked gets the
+  run's latest answer to it; a question it did not ask, and any grid, is refused, and nothing is sent
+  to the research service. It is refused for a stage that holds no research tool, or a run that saved
+  no answers. The arm's `experiment-context.json` records `research: {mode, answers}`.
 - **Orphan self-resume**: a manually resumed run that parks has no queue sidecars; the runner scans
   run dirs for due, payload-complete `.postponed` sentinels not owned by any queue and resumes them
   (claim = atomic rename to `.resuming`).

package/driver/CHANGELOG.md

@@ -1,5 +1,15 @@
 # clearotron-driver
 
+## 0.5.0-beta.4
+
+### Patch Changes
+
+- Fixed: On the Codex engine, a clearance no longer sees temporary files that another clearance left on the same machine.
+- Fixed: A report's copy for the client is no longer held back when a live finding shares its mark and owner with a finding the review withdrew.
+- Fixed: A register entry the engine decided to keep as background now appears in the report's context table, instead of being left out of it.
+- Fixed: When the report's writing step is interrupted, the next attempt continues from the findings it had already finished instead of starting again.
+- Fixed: On a crowded field, the report is written from the work the clearance has already done, without reading every register result again.
+
 ## 0.5.0-beta.3
 
 ### Patch Changes

package/driver/band-shape.mjs

@@ -1135,18 +1135,26 @@ export const AN_UNREAD_LISTS_FLOOR = "Place each floor here, or set it aside by
 // alone, as its other orders are: every other stage keeps the markers as evidence and is not told of a fate.
 export const AN_UNREAD_LINE_IS_CHECKED = 'A line marked "on file, not readable", "cut by the register, no goods word found", "goods held; completeness not established" or "no goods text held; completeness not established" must be checked with band_record before its fate. Read the evidence held for it, keeping its source and goods completeness clear. A line marked "no goods on file", "fetch failed, no goods on file" or "the register\'s record lists no goods" has no goods text on file. Missing goods do not establish that the goods are unrelated.';
 export const PLACEMENT_LINE_ORDERS = Object.freeze([FLOORS_BY_NAME_HERE, A_CROWDS_ONE_ROW, A_CROWDS_ROW_COVERS_A_READ_FLOOR, AN_UNREAD_CROWDS_ONE_ROW, AN_UNREAD_CROWDS_FLOOR, AN_UNREAD_LISTS_FLOOR, AN_UNREAD_LINE_IS_CHECKED]);
+// AND THE SIZE RULE'S ORDERS TO READ (ruled 2026-10-27). A list's size sentence tells placement how much of it to read,
+// and only placement owes the lines that read. Every other stage is served the shape without these orders too: the
+// writer is told the groups are a way to find evidence, never a list it must read to completion. Each list's count,
+// what it holds and the fact that a crowded one prints its first page stay.
+export const READ_THEM_ALL = "Fifty? Read them all.";
+export const READ_EVERY_LINE = ": read every line.";
+export const READ_THE_LIVE_ONES_FIRST = "A few hundred? Read the live ones in the ordered classes first.";
 const SHAPE_LISTS = ["a", "b", "c", "d", "rest", "no_goods"];
 const pageEveryOtherLine = (g) => `; page every other line with ${groupPageCall(g)}`;
 const pageWhereALineNeedsIt = (g) => `; page with ${groupPageCall(g)} only where a line needs reading`;
 const pageTheFloorsLeft = (g) => `Where more floors are counted than this page shows, page the rest with ${groupPageCall(g)}; they come first.`;
 /**
- * The shape as every stage but placement is served it: placement's orders and its group-page commands removed,
+ * The shape as every stage but placement is served it: placement's orders, its size rule's orders to read and its group-page commands removed,
  * each with the space before it, inside its line, so no line moves and the line each listed mark is printed on
  * still holds. A crowded group's "The first N lines are below" stays, as a fact about what is printed. PURE.
  */
 export function withoutPlacementOrders(text) {
   let t = String(text ?? "");
-  for (const order of [...PLACEMENT_GROUP_ORDERS, ...PLACEMENT_LINE_ORDERS, ...SHAPE_LISTS.map(pageTheFloorsLeft)]) t = t.split(` ${order}`).join("").split(order).join("");
+  for (const order of [...PLACEMENT_GROUP_ORDERS, ...PLACEMENT_LINE_ORDERS, ...SHAPE_LISTS.map(pageTheFloorsLeft), READ_THEM_ALL, READ_THE_LIVE_ONES_FIRST]) t = t.split(` ${order}`).join("").split(order).join("");
+  t = t.split(READ_EVERY_LINE).join(".");
   for (const g of SHAPE_LISTS) t = t.split(pageEveryOtherLine(g)).join("").split(pageWhereALineNeedsIt(g)).join("");
   return t;
 }
@@ -1200,16 +1208,16 @@ function renderGroupsMd(md, groups, rows = []) {
     md.push(`### ${heading(g)}`, "");
     if (!grp.lines) { md.push("(none)", ""); continue; }
     const crowded = grp.records >= groups.crowded_at;
-    const readA = "These are the identical and near-identical marks live in the ordered classes for the client's goods: read every line.";
+    const readA = `These are the identical and near-identical marks live in the ordered classes for the client's goods${READ_EVERY_LINE}`;
     md.push(g === "a"
       ? (crowded
         ? `${count(grp)}. ${readA} ${firstPage}${pageEveryOtherLine(g)}. ${FLOORS_BY_NAME_HERE}`
-        : grp.lines <= READ_ALL_LINES ? `${count(grp)}. Fifty? Read them all.` : `${count(grp)}. ${readA}`)
+        : grp.lines <= READ_ALL_LINES ? `${count(grp)}. ${READ_THEM_ALL}` : `${count(grp)}. ${readA}`)
       : crowded
         ? `${count(grp)}. A thousand or more? The field is crowded. These are ${crowd[g]}. ${A_CROWDS_ONE_ROW} ${firstPage}${pageWhereALineNeedsIt(g)}.${
           g === "b" ? ` ${A_CROWDS_ROW_COVERS_A_READ_FLOOR} ${pageTheFloorsLeft(g)}` : ""}`
         : grp.lines <= READ_ALL_LINES
-          ? `${count(grp)}. Fifty? Read them all.`
+          ? `${count(grp)}. ${READ_THEM_ALL}`
           : `${count(grp)}. ${SORT_THE_NEAR_ONES}`, "");
     md.push(...head);
     for (const l of crowded ? grp.list.slice(0, groups.first_page) : grp.list) { rows.push([md.length, l.key]); md.push(row(l)); }
@@ -1223,7 +1231,7 @@ function renderGroupsMd(md, groups, rows = []) {
   md.push(`**The rest: ${count(rest)}${outside}** — every record in none of (a) to (d) above. ${!rest.lines ? ONE_SET_ASIDE_ROW
     : restCrowded
       ? `A thousand or more? The field is crowded. ${A_CROWDS_ONE_ROW} ${firstPage}${pageWhereALineNeedsIt("rest")}.`
-      : `${rest.lines <= READ_ALL_LINES ? "Fifty? Read them all." : SORT_THE_NEAR_ONES} ${ONE_SET_ASIDE_ROW}`}`);
+      : `${rest.lines <= READ_ALL_LINES ? READ_THEM_ALL : SORT_THE_NEAR_ONES} ${ONE_SET_ASIDE_ROW}`}`);
   if (rest.lines) {
     md.push("", ...head);
     for (const l of restCrowded ? rest.list.slice(0, groups.first_page) : rest.list) { rows.push([md.length, l.key]); md.push(row(l)); }
@@ -1240,7 +1248,7 @@ function renderGroupsMd(md, groups, rows = []) {
       : `**Goods the test could not read: ${count(ng)}.**`;
     md.push("", crowded
       ? `${lead} A thousand or more? ${firstPage}, the floors first, then the live ones in the ordered classes. ${AN_UNREAD_CROWDS_ONE_ROW} ${AN_UNREAD_CROWDS_FLOOR} ${pageTheFloorsLeft("no_goods")}`
-      : `${lead} ${ng.lines <= READ_ALL_LINES ? "Fifty? Read them all." : "A few hundred? Read the live ones in the ordered classes first."} ${A_FATE_BY_NAME}${tested.source === "none" ? "" : ` ${AN_UNREAD_LINE_IS_CHECKED}`} ${AN_UNREAD_LISTS_FLOOR}`, "");
+      : `${lead} ${ng.lines <= READ_ALL_LINES ? READ_THEM_ALL : READ_THE_LIVE_ONES_FIRST} ${A_FATE_BY_NAME}${tested.source === "none" ? "" : ` ${AN_UNREAD_LINE_IS_CHECKED}`} ${AN_UNREAD_LISTS_FLOOR}`, "");
     md.push(...head);
     for (const l of crowded ? ng.list.slice(0, groups.first_page) : ng.list) { rows.push([md.length, l.key]); md.push(row(l)); }
   }

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

@@ -280,9 +280,9 @@ function bandShape(params) {
     ...(read ? { served_lines: read.keys[part - 1], group_parts: read.groupParts } : {}) });
   const head = format === "json"
     ? `[band_shape part ${part}/${total} of the json; concatenate the parts before parsing it.]`
-    : `[band_shape part ${part}/${total}. Read each group by the size sentence at its head; the next part continues the groups.]`;
+    : `[band_shape part ${part}/${total}. ${GROUP_PAGES ? "Read each group by the size sentence at its head; the next part continues the groups." : "The next part continues the groups."}]`;
   const tail = part < total
-    ? `\n[end of part ${part}/${total} — call band_shape again with {"part": ${part + 1}} for the next part]`
+    ? `\n[end of part ${part}/${total} — part ${part + 1} is available with {"part": ${part + 1}}]`
     : `\n[end of the shape]`;
   return head + "\n" + parts[part - 1] + tail;
 }
@@ -351,7 +351,7 @@ function groupLookup(params) {
   const body = () => JSON.stringify({
     group: g, lines_total: lines.length, returned: page.length, ...(offset ? { offset } : {}),
     ...(lines.length > offset + page.length ? { next_offset: offset + page.length,
-      note: `call again with offset: ${offset + page.length} for the next lines of group ${g}` } : {}),
+      note: `the next lines of group ${g} are available with offset: ${offset + page.length}` } : {}),
     lines: page.map(({ _key, ...l }) => l),
   }, null, 2);
   let out = body();
@@ -440,8 +440,8 @@ function bandLookup(params = {}) {
   const body = () => JSON.stringify({
     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` } : {}),
+    ...(matched > offset + hits.length ? { note: `capped at ${hits.length} — the next page is available with offset: ${offset + hits.length}; the count above is the full match` } : {}),
+    ...(byteCapped ? { byte_cap_note: `${byteCapped} matched record(s) withheld to fit one tool response — the rest are available with offset: ${offset + hits.length}` } : {}),
     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` : "")
@@ -515,7 +515,7 @@ function bandRecord(params = {}) {
     logRead("band_record", { record_id: uri, part, parts: total }, { ok: true, bytes: parts[part - 1].length, total_bytes: text.length, ...resolution, ...served.audit });
     const head = `[band_record part ${part}/${total}. This record is served in ${total} parts; the next part continues it.]`;
     const tail = part < total
-      ? `\n[end of part ${part}/${total} — call band_record again with {"record_id": "${uri}", "part": ${part + 1}} for the next part]`
+      ? `\n[end of part ${part}/${total} — part ${part + 1} is available with {"record_id": "${uri}", "part": ${part + 1}}]`
       : `\n[end of the record]`;
     return head + "\n" + parts[part - 1] + tail;
   }
@@ -537,7 +537,7 @@ function bandRecord(params = {}) {
     const part = Number.isInteger(wanted) && wanted >= 1 && wanted <= parts.length ? wanted : 1;
     logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, via: "ledger", part, parts: parts.length, ...served.audit });
     return { type: "text", text: `[record ${uri} — part ${part}/${parts.length}]\n` + parts[part - 1]
-      + (part < parts.length ? `\n[end of part ${part}/${parts.length} — call band_record again with {"record_id": "${uri}", "part": ${part + 1}}]` : "") };
+      + (part < parts.length ? `\n[end of part ${part}/${parts.length} — part ${part + 1} is available with {"record_id": "${uri}", "part": ${part + 1}}]` : "") };
   }
 
   // A GENUINE miss — neither materialised NOR in this run's ledger. Now the sentence below is true.
@@ -581,7 +581,7 @@ function bandRecord(params = {}) {
     ...(parts.length > 1 ? { part, parts: parts.length } : {}), ...(failed ? { fetch_failed: true } : {}) });
   if (parts.length === 1) return { isError: true, text };
   return { isError: true, text: `[record ${uri} — part ${part}/${parts.length}]\n` + parts[part - 1]
-    + (part < parts.length ? `\n[end of part ${part}/${parts.length} — call band_record again with {"record_id": "${uri}", "part": ${part + 1}}]` : "") };
+    + (part < parts.length ? `\n[end of part ${part}/${parts.length} — part ${part + 1} is available with {"record_id": "${uri}", "part": ${part + 1}}]` : "") };
 }
 
 // The band row a record id names, from the band file, read once per server. null where the band holds none.
@@ -610,10 +610,10 @@ const GROUP_PAGES = process.env.CLEAROTRON_BAND_GROUPS === "1";
 // served the shape without them (the owner's ruling, 2026-10-14). Each is removed with the space before it, inside
 // its line, so no line moves and the line each listed mark is printed on, which `linesByPart` reads, still holds.
 // (band-shape.mjs `withoutPlacementOrders` removes them, with the shape's other placement-only orders and its group-page commands.)
-const 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, goods (words: records whose goods contain any of them, as whole words, singular or plural; a record with no goods on file matches too), group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), limit (default 20, max 100), offset (default 0: where in the matching records or lines to start — a capped answer names the next offset, so a large band or group is read page by page). On each record served, `goods_words` gives the client's goods words its goods hold, as the shape tests them (k of N: the words), or null where its goods cannot be read; `goods_from` says what those goods rest on: official record; official record, cut by the register; official record, completeness not established; official record, no goods listed; search answer; search answer, cut by the register; search answer, completeness not established; fetch failed; or nothing held. The goods text is in band_record. Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.";
+const 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, goods (words: records whose goods contain any of them, as whole words, singular or plural; a record with no goods on file matches too), group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), limit (default 20, max 100), offset (default 0: where in the matching records or lines to start — a capped answer names the offset where the next page starts). On each record served, `goods_words` gives the client's goods words its goods hold, as the shape tests them (k of N: the words), or null where its goods cannot be read; `goods_from` says what those goods rest on: official record; official record, cut by the register; official record, completeness not established; official record, no goods listed; search answer; search answer, cut by the register; search answer, completeness not established; fetch failed; or nothing held. The goods text is in band_record. Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.";
 const LOOKUP_GROUP_CLAUSE = "group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), ";
-const LOOKUP_OFFSET_GROUPS = "offset (default 0: where in the matching records or lines to start — a capped answer names the next offset, so a large band or group is read page by page)";
-const LOOKUP_OFFSET_BAND = "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)";
+const LOOKUP_OFFSET_GROUPS = "offset (default 0: where in the matching records or lines to start — a capped answer names the offset where the next page starts)";
+const LOOKUP_OFFSET_BAND = "offset (default 0: where in the matching records to start — a capped answer names the offset where the next page starts)";
 /** The lookup's description as a stage is offered it: whole where it reads the groups, without them elsewhere. PURE. */
 const lookupDescription = (groupPages) => (groupPages ? LOOKUP_DESCRIPTION
   : LOOKUP_DESCRIPTION.replace(LOOKUP_GROUP_CLAUSE, "").replace(LOOKUP_OFFSET_GROUPS, LOOKUP_OFFSET_BAND));
@@ -623,7 +623,7 @@ serve({
   tools: [
     {
       name: "band_shape",
-      description: "The deterministic shape of this run's merged register band: totals, mechanical tiers, the floors (every live in-class identical/near-identical record), each marked on its line in the band in the lawyer's order, class/status/registry/recency census, owner concentrations, crowd descriptors (with crowd-context joins) and blind spots. Read this FIRST, then pull what it names via band_lookup/band_record. A large shape is served in parts, each naming the next call. Every call is logged to the run's reading audit.",
+      description: "The deterministic shape of this run's merged register band: totals, mechanical tiers, the floors (every live in-class identical/near-identical record), each marked on its line in the band in the lawyer's order, class/status/registry/recency census, owner concentrations, crowd descriptors (with crowd-context joins) and blind spots. What it names can be looked up with band_lookup and band_record. A large shape is served in parts, and the end of each part names the next one. Every call is logged to the run's reading audit.",
       inputSchema: { type: "object", properties: { format: { type: "string", enum: ["md", "json"], description: "md (default, readable) or json (machine shape)" }, part: { type: "number", description: "1-based part number when the shape is served in parts (default 1)" } } },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: bandShape,

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

@@ -275,10 +275,15 @@ export function featuresToml(withheld = []) {
 // codex's `workspace-write` sandbox confines where a command WRITES and lets it read the whole disk, the
 // install's settings files and the program's own sign-in included. A permission profile confines reading
 // too (the vendor's Permissions guide, a beta feature since 0.138.0; the floor was 0.154.0 when this was written and is 0.159.0 now, for the judgment tier's model — driver.config.mjs): a stage's
-// commands read the platform's own paths, the instruction trees and the temp folders, and write the run
-// folder, their working folder and the temp folders. Nothing else is readable, so a page a stage fetched
-// cannot get a command to print the account's files. The temp folders stay writable because
-// `workspace-write` let commands use them and stages write their output through the shell.
+// commands read the platform's own paths and the instruction trees, and write the run folder, their
+// working folder and their Codex home's working folder. Nothing else is readable, so a page a stage
+// fetched cannot get a command to print the account's files.
+//
+// NO SHARED TEMP FOLDER. The profile granted `:tmpdir` and `:slash_tmp`, which every stage of every run on
+// the machine shares, and a later run's commands read what an earlier run left in `/tmp` (measured on codex
+// 0.162.0 with that profile: a command read a file planted in `/tmp` and wrote another beside it). The
+// turn's TMPDIR, TMP and TEMP now name its home's working folder (openai-agent.mjs, `withWorkFolder`), and
+// this grants that folder, named, in their place.
 //
 // ONLY WITH THE SANDBOX ON. Under the bypass codex builds no sandbox, so a profile would enforce nothing;
 // the caller passes no `fence` then, and the file stays what it was. With the sandbox on the command line
@@ -297,10 +302,10 @@ export function featuresToml(withheld = []) {
 // wins over the run folder's: measured on codex 0.162.0 with this profile, a write into the run folder
 // succeeded, a read of `_driver/` succeeded, and a write or an append there was refused.
 export const FENCE_PROFILE = "clearotron-stage";
-export function fenceToml({ runDir = null, readRoots = [] } = {}) {
+export function fenceToml({ runDir = null, workDir = null, readRoots = [] } = {}) {
   const key = (p) => tomlString(p);
-  const out = [`[permissions.${FENCE_PROFILE}.filesystem]`,
-    `":minimal" = "read"`, `":tmpdir" = "write"`, `":slash_tmp" = "write"`];
+  const out = [`[permissions.${FENCE_PROFILE}.filesystem]`, `":minimal" = "read"`];
+  if (workDir) out.push(`${key(workDir)} = "write"`);
   for (const r of [...new Set(readRoots.filter(Boolean))]) out.push(`${key(r)} = "read"`);
   if (runDir) out.push(`${key(runDir)} = "write"`, `${key(driverDir(runDir))} = "read"`);
   out.push("", `[permissions.${FENCE_PROFILE}.filesystem.":workspace_roots"]`, `"." = "write"`, "");

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/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/supplemental.mjs

@@ -34,7 +34,8 @@ 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";
@@ -391,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) ───────────────

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/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/package.json

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