@codedology/code-forge 0.15.1 → 0.15.3

package/src/review/gate-check.mjs

@@ -92,7 +92,7 @@ import { ownsFile } from '../state/registry.mjs';
 import { sameStamp, treeStamp } from '../state/block.mjs';
 import { verifyRow } from '../state/signer.mjs';
 import { tierFor } from '../proof/tiers.mjs';
-import { DELETED_HASH, contentHash, gitChildEnv } from '../worker/ticket.mjs';
+import { DELETED_HASH, contentHash, gitChildEnv, readRegularFileNoFollow } from '../worker/ticket.mjs';
 import { verifyResult } from '../worker/queue.mjs';
 import { stopExitsLine } from './stop-exits.mjs';
 import { checkFileForm, checkFindingId } from './verb-forms.mjs';
@@ -915,6 +915,44 @@ export async function blockFileSet({ repoRoot, base, owned, ownedKinds, matchOwn
   return all.filter((f) => isOwned(f)).map((file) => ({ file, content_hash: currentHash(repoRoot, file) }));
 }
 
+/** Safety check for npm locks excluded from model review; other formats are not parsed.
+ * @param {string} repoRoot @param {string} file @param {Record<string, any> | null} cfg
+ * @returns {string | null} refusal detail, or null for a safe (or deleted) lock
+ */
+export function lockfileProblem(repoRoot, file, cfg) {
+  if (!['package-lock.json', 'npm-shrinkwrap.json'].includes(path.posix.basename(file))) return null;
+  let lock;
+  try {
+    const bytes = readRegularFileNoFollow(repoRoot, file);
+    if (bytes === null) return null;
+    lock = JSON.parse(bytes.toString('utf8'));
+  } catch { return 'cannot read valid lock JSON'; }
+  if (!lock || typeof lock !== 'object' || Array.isArray(lock)) return 'expected a lock object';
+  const hosts = cfg?.review?.lockfile_registries ?? ['registry.npmjs.org'];
+  /** @param {any} entries @param {string} prefix @param {boolean} recursive @returns {string | null} */
+  function checkEntries(entries, prefix, recursive) {
+    if (!entries || typeof entries !== 'object' || Array.isArray(entries)) return `${prefix} must be an object`;
+    for (const [name, pkg] of Object.entries(entries)) {
+      const entry = `${prefix}.${name}`;
+      if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg)) return `${entry} must be an object`;
+      if (pkg.link !== true && pkg.resolved !== undefined) {
+        let url;
+        try { url = new URL(pkg.resolved); } catch { return `${entry}.resolved must be an HTTPS URL on an allowed host`; }
+        if (url.protocol !== 'https:' || !hosts.includes(url.host)) return `${entry}.resolved must be HTTPS on review.lockfile_registries`;
+        if (typeof pkg.integrity !== 'string' || !pkg.integrity.trim()) return `${entry} has no integrity`;
+      }
+      if (recursive && pkg.dependencies !== undefined) {
+        const problem = checkEntries(pkg.dependencies, `${entry}.dependencies`, true);
+        if (problem) return problem;
+      }
+    }
+    return null;
+  }
+  const problem = checkEntries(lock.packages ?? {}, 'packages', false);
+  if (problem) return problem;
+  return lock.dependencies === undefined ? null : checkEntries(lock.dependencies, 'dependencies', true);
+}
+
 /**
  * Every changed tracked file since `base` (deletions included) ∪ every untracked, not ignored
  * file, through `repoRelativePath`, sorted — the set {@link blockFileSet} filters to the block.

package/src/review/lenses/full.md

@@ -19,6 +19,7 @@ Code or tests beyond what the change needs (unused options, extra layers, specul
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A finding that claims something is missing or wrong across the project must say in `evidence` which related file it could not see, e.g. "assumes no rule in src/styles/base.css".
 - A test named in `## paired` exists; do not report it as unseen; use `needs_file` when its body matters.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order. A review whose `reviewed_hunks` does not match is discarded.

package/src/review/lenses/quick.md

@@ -17,6 +17,7 @@ Code or tests beyond what the change needs (unused options, extra layers, specul
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A finding that claims something is missing or wrong across the project must say in `evidence` which related file it could not see, e.g. "assumes no rule in src/styles/base.css".
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order. A review whose `reviewed_hunks` does not match is discarded.
 - Answer with ONE JSON object that matches the answer schema: `passed`, `summary` (≤ 300 chars), `reviewed_hunks`, `findings[]`, and `needs_file[]` (empty when you need nothing).

package/src/review/packet.mjs

@@ -10,7 +10,8 @@
  *   ## project rules   the rules digest (≤ 60 lines)
  *   ## facts           the facts-sheet excerpt
  *   ## context         the current file (whole, or hunk windows — `context.mjs`)
- *   ## paired          optional paired-file names and summary (B97), dropped first over budget
+ *   ## related files (not shown)  optional related paths only, dropped first over budget
+ *   ## paired          optional paired-file names and summary (B97), dropped next over budget
  *   ## moved code      only when code moved to/from another file of the block (`moved.mjs`, B56)
  *   ## diff            `file:`, the `hunks:` list the reviewer must echo, then the diff
  *
@@ -21,7 +22,7 @@
  * Budget (§4.3): `review.budgets.full_in` (`quick_in` for the quick lens), in tokens estimated as
  * bytes / 4. A diff that alone exceeds it ⇒ `split_required` (a Markdown file is then reviewed
  * section by section — `sections.mjs`, B54). Otherwise over budget ⇒ the context shrinks to
- * ± `min_context_lines` (`minimal`) after dropping paired, then the digest is trimmed from the end; the diff is
+ * ± `min_context_lines` (`minimal`) after dropping related files, then paired, then the digest is trimmed from the end; the diff is
  * never cut. The `## moved code` section (B56) is part of that measure: it is counted in the diff-only
  * size (`diffOnlyTokens`, `split_required`) and never trimmed.
  *
@@ -38,6 +39,7 @@ import { fileURLToPath } from 'node:url';
 import { exec } from '../util/exec.mjs';
 import { assertInsideRoot, assertRowPath, gitChildEnv, readRegularFileNoFollow, WorkerError } from '../worker/ticket.mjs';
 import { buildContext, parseDiff, splitLines } from './context.mjs';
+import { relatedFiles } from './related.mjs';
 
 export const LENSES = Object.freeze(['quick', 'full', 'recheck', 'A', 'B', 'judge']);
 
@@ -137,6 +139,7 @@ export function assertPacketPath(repoRoot, file) {
  * @property {import('./context.mjs').Hunk[]} hunks
  * @property {number} plusCount
  * @property {number} minusCount
+ * @property {string[]} [related] - related file names, never their content.
  */
 
 /**
@@ -171,7 +174,19 @@ export async function readFileDiff({ repoRoot, file, base }) {
   const res = await exec(argv, { cwd: repoRoot, env, timeoutMs: GIT_TIMEOUT_MS, ...(kind === 'new' ? { okExitCodes: [0, 1] } : {}) });
   if (res.result !== 'ok') throw new PacketError('git', `git diff failed for ${rel} (exit ${res.code})`);
   const content = onDisk ? readRepoText(repoRoot, rel) : null;
-  return { file: rel, kind, diffText: res.stdout, content, ...parseDiff(res.stdout) };
+  const related = res.stdout.trim().length === 0 ? [] : await relatedFiles({
+    repoRoot, file: rel,
+    listFiles: async () => {
+      const tracked = await exec(['git', 'ls-files', '-z'], { cwd: repoRoot, env, timeoutMs: GIT_TIMEOUT_MS });
+      return tracked.result === 'ok' ? tracked.stdout.split('\0').filter(Boolean) : [];
+    },
+    readFile: (full) => {
+      const candidate = path.relative(repoRoot, full).split(path.sep).join('/');
+      if (isSecretLike(candidate)) return null;
+      return readRepoText(repoRoot, assertPacketPath(repoRoot, candidate));
+    },
+  });
+  return { file: rel, kind, diffText: res.stdout, content, related, ...parseDiff(res.stdout) };
 }
 
 /**
@@ -206,7 +221,13 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   let digest = splitLines(rulesDigest).slice(0, DIGEST_MAX_LINES);
   let ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: contextMode });
   let pairedSection = boundedPaired(paired, budgetFor(cfg, 'full_in'));
-  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection);
+  const names = ['quick', 'full'].includes(lens) ? (diff.related ?? []) : [];
+  let relatedSection = names.length > 0 ? `## related files (not shown)\n${names.join('\n')}` : '';
+  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection, relatedSection);
+  if (estimateTokens(text) > limit && relatedSection.length > 0) {
+    relatedSection = '';
+    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection);
+  }
   if (estimateTokens(text) > limit && pairedSection.length > 0) {
     pairedSection = '';
     text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
@@ -234,7 +255,12 @@ export function assembleLightPacket({ diffs, cfg, rulesDigest = '', factsExcerpt
   const context = (mode) => diffs.map((diff) => `### ${diff.file}\n${buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode }).text}`).join('\n\n');
   let contextMode = 'auto';
   let ctx = context(contextMode);
-  let text = render(lens, digest, factsExcerpt, ctx, diffText);
+  const shown = new Set(diffs.map((diff) => diff.file));
+  const related = [...new Set(diffs.flatMap((diff) => diff.related ?? []))].filter((file) => !shown.has(file)).sort().slice(0, 12);
+  let text = render(lens, digest, factsExcerpt, ctx, diffText, '', '', related.length > 0 ? `## related files (not shown)\n${related.join('\n')}` : '');
+  if (estimateTokens(text) > budget && related.length > 0) {
+    text = render(lens, digest, factsExcerpt, ctx, diffText);
+  }
   if (estimateTokens(text) > budget) {
     contextMode = 'minimal';
     ctx = context(contextMode);
@@ -293,8 +319,9 @@ function diffSectionOf(diff) {
  * @param {string} lensText @param {string[]} digest @param {string} facts @param {string} context
  * @param {string} diffSection @param {string} [moved] - the `## moved code` section (heading included), '' for none.
  * @param {string} [paired] - the bounded `## paired` section (heading included).
+ * @param {string} [related] - the names-only related files section (heading included).
  */
-function render(lensText, digest, facts, context, diffSection, moved = '', paired = '') {
+function render(lensText, digest, facts, context, diffSection, moved = '', paired = '', related = '') {
   return [
     '# code-forge review packet',
     '## lens',
@@ -305,6 +332,7 @@ function render(lensText, digest, facts, context, diffSection, moved = '', paire
     facts.trim().length > 0 ? facts.trimEnd() : '(none)',
     '## context',
     context.length > 0 ? context : '(none)',
+    ...(related.length > 0 ? [related] : []),
     ...(paired.length > 0 ? [paired] : []),
     ...(moved.length > 0 ? [moved] : []),
     '## diff',

package/src/review/related.mjs

@@ -0,0 +1,112 @@
+/** Best-effort local import relationships; I/O is supplied by the packet reader. */
+import path from 'node:path';
+
+const EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts', '.css', '.scss', '.html', '.htm', '.astro', '.vue'];
+const STYLES = new Set(['.css', '.scss']);
+
+/** @param {string} file */
+function safePath(file) {
+  return typeof file === 'string' && !path.posix.isAbsolute(file) &&
+    !/[\\\x00-\x1f\x7f]/.test(file) &&
+    !file.split('/').some((part) => ['', '.', '..', '.git', '.code-forge'].includes(part));
+}
+
+/** @param {string} text @param {string} file @returns {string[]} */
+function specifiers(text, file) {
+  const ext = path.posix.extname(file).toLowerCase();
+  const found = [];
+  // CSS and HTML use relative URLs without requiring JS's leading ./ or ../.
+  const url = (value) => {
+    if (!/^(?:[a-z][a-z\d+.-]*:|\/|[?#])/i.test(value)) found.push(/^\.\.?\//.test(value) ? value : `./${value}`);
+  };
+  if (!STYLES.has(ext)) {
+    // Keep strings as single tokens, discard comments/templates, and never interpret a string's
+    // contents as code. This also handles imports in Astro frontmatter and Vue script blocks.
+    const tokens = [...text.matchAll(/\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|`(?:\\[\s\S]|[^`\\])*`|'(?:\\[\s\S]|[^'\\])*'|"(?:\\[\s\S]|[^"\\])*"|[\w$]+|[^\s]/g)]
+      .map((match) => match[0]).filter((token) => !token.startsWith('//') && !token.startsWith('/*') && !token.startsWith('`'));
+    const quoted = (token) => token?.startsWith('"') || token?.startsWith("'");
+    for (let i = 0; i < tokens.length; i += 1) {
+      const token = tokens[i];
+      if (token !== 'import' && token !== 'require') continue;
+      if (tokens[i - 1] === '.') continue;
+      if (tokens[i + 1] === '(' && quoted(tokens[i + 2]) && tokens[i + 3] === ')') found.push(tokens[i + 2].slice(1, -1));
+      else if (token === 'import') {
+        if (quoted(tokens[i + 1])) found.push(tokens[i + 1].slice(1, -1));
+        else {
+          for (let j = i + 1; j < tokens.length && ![';', 'import', 'require', '('].includes(tokens[j]); j += 1) {
+            if (tokens[j] === 'from' && quoted(tokens[j + 1])) { found.push(tokens[j + 1].slice(1, -1)); break; }
+          }
+        }
+      }
+    }
+  }
+  if (STYLES.has(ext) || ['.html', '.htm', '.astro', '.vue'].includes(ext)) {
+    const markup = text.replace(/\/\*[\s\S]*?\*\/|<!--[\s\S]*?-->/g, '');
+    for (const match of markup.matchAll(/@import\s+(?:url\(\s*(?:'([^']+)'|"([^"]+)"|([^\s)]+))\s*\)|'([^']+)'|"([^"]+)")/gi)) {
+      url(match.slice(1).find((value) => value !== undefined));
+    }
+    if (!STYLES.has(ext)) {
+      for (const tag of markup.matchAll(/<(link|script)\b[^>]*>/gi)) {
+        const attr = tag[1].toLowerCase() === 'link' ? 'href' : 'src';
+        const match = tag[0].match(new RegExp(`\\s${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|([^\\s>]+))`, 'i'));
+        if (match) url(match[1] ?? match[2] ?? match[3]);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Names only: outgoing imports, tracked importers (at most 2000 candidates), and a stylesheet's
+ * cascade siblings. A missing/unreadable file is not a relationship. No source text is returned.
+ * `listFiles` lists tracked repo-relative paths; `readFile` reads an absolute path or returns null.
+ * @param {{repoRoot: string, file: string,
+ *   listFiles: (repoRoot: string) => string[] | Promise<string[]>,
+ *   readFile: (file: string) => string | null | Promise<string | null>}} opts
+ * @returns {Promise<string[]>}
+ */
+export async function relatedFiles({ repoRoot, file, listFiles, readFile }) {
+  if (!safePath(file) || !EXTENSIONS.includes(path.posix.extname(file).toLowerCase())) return [];
+  const cache = new Map();
+  const read = async (rel) => {
+    if (!safePath(rel)) return null;
+    if (!cache.has(rel)) {
+      try { cache.set(rel, await readFile(path.resolve(repoRoot, rel))); }
+      catch { cache.set(rel, null); }
+    }
+    return cache.get(rel);
+  };
+  const imports = async (rel) => {
+    const text = await read(rel);
+    const resolved = new Set();
+    if (text === null) return resolved;
+    for (const specifier of specifiers(text, rel)) {
+      if (!/^\.\.?\//.test(specifier)) continue;
+      const target = path.posix.normalize(path.posix.join(path.posix.dirname(rel), specifier.split(/[?#]/)[0]));
+      if (!safePath(target)) continue;
+      const candidates = [target];
+      if (!path.posix.extname(target)) candidates.push(...EXTENSIONS.map((ext) => target + ext), ...EXTENSIONS.map((ext) => `${target}/index${ext}`));
+      for (const candidate of candidates) {
+        if (await read(candidate) !== null) { resolved.add(candidate); break; }
+      }
+    }
+    return resolved;
+  };
+  const related = await imports(file);
+  let tracked = [];
+  try { tracked = [...new Set(await listFiles(repoRoot))].filter((rel) => safePath(rel) && EXTENSIONS.includes(path.posix.extname(rel).toLowerCase())); }
+  catch { /* Outgoing imports still help when listing is unavailable. */ }
+  if (tracked.length <= 2000) {
+    for (const importer of tracked) {
+      if (importer === file) continue;
+      const targets = await imports(importer);
+      if (!targets.has(file)) continue;
+      related.add(importer);
+      if (STYLES.has(path.posix.extname(file).toLowerCase())) {
+        for (const sibling of targets) if (STYLES.has(path.posix.extname(sibling).toLowerCase())) related.add(sibling);
+      }
+    }
+  }
+  related.delete(file);
+  return [...related].sort().slice(0, 12);
+}

package/src/review/reopen.mjs

@@ -192,9 +192,10 @@ export function reopenRowFor(rows, { runId, block, file, key, status, state, seq
  *     contentHash: (file: string) => string,
  *     readFile?: (file: string) => Buffer | null,
  *     clearDone: (file: string) => boolean,
+ *     enqueue?: (file: string, row: Record<string, any>) => string | undefined,
  *   },
  * }} opts
- * @returns {Promise<{row: Record<string, any>, cleared: boolean, existing: boolean}>}
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean, existing: boolean, ticket?: string}>}
  * @throws {StateError} `usage` or a refusal code (see the module doc).
  */
 export async function reopenFile({ runId, id, file, reason, record, rows, key, writeRow, writeSigned, io, agent }) {
@@ -255,7 +256,7 @@ export async function reopenFile({ runId, id, file, reason, record, rows, key, w
   // so a failed row write leaves at worst a re-run that returns the same stop, never a row with a
   // stale marker
   const cleared = io.clearDone(file);
-  if (earlier !== null) return { row: earlier, cleared, existing: true };
+  if (earlier !== null) return { row: earlier, cleared, existing: true, ticket: io.enqueue?.(file, earlier) };
   const row = { event: REOPENED_EVENT, block: id, file, from, stop_reason: stopReason, at_seq: loaded.seq, from_hash: fromHash, to_hash: current, reason: reason.trim(), by: agent ? 'agent' : 'human', ...(agent ? { verdict } : {}) };
   /** @type {Record<string, any> | null} */
   let written = null;
@@ -285,5 +286,5 @@ export async function reopenFile({ runId, id, file, reason, record, rows, key, w
     if (threw) Object.defineProperty(refused, 'cause', { value: failure, enumerable: false, configurable: true, writable: true });
     throw refused;
   }
-  return { row: written, cleared, existing: false };
+  return { row: written, cleared, existing: false, ticket: io.enqueue?.(file, written) };
 }

package/src/review/session-retry.mjs

@@ -32,10 +32,69 @@
  */
 
 import { logWarning } from '../util/error-log.mjs';
+import { resolveLevel } from '../config/known-ids.mjs';
+import { closedBookRefused, openBookCodexAllowed } from '../config/closed-book.mjs';
 
 /** How many times a timed-out session is spawned again. */
 export const TIMEOUT_RETRIES = 1;
 
+/**
+ * A broken answer gets one retry on its model, then the next distinct, runnable model of the
+ * level's ladder. Pin each retry to one model so provider-error fallback cannot consume the
+ * ladder before the same-model retry. A valid negative answer stops just like a valid positive.
+ * The packet and the original config are unchanged throughout.
+ * @param {(opts: Record<string, any>) => Promise<{res: Record<string, any> | null, attempts: number}>} spawn
+ * @param {Record<string, any>} opts
+ * @param {(res: Record<string, any> | null) => boolean} isBroken
+ * @param {(res: Record<string, any> | null, cfg: Record<string, any>) => Promise<unknown>} [onBroken]
+ * @param {{res: Record<string, any> | null, attempts: number}} [initial] - reuse a completed
+ *   attempt, including any provider fallback it already took, rather than spawning it again.
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number, to?: BrokenTry['to'], usage: {tokens_in: number | null, tokens_out: number | null}}>}
+ */
+export async function spawnWithBrokenFallback(spawn, opts, isBroken, onBroken = async () => {}, initial) {
+  const resolved = resolveLevel(opts.cfg, opts.level);
+  const models = [resolved, ...resolved.fallback];
+  const startAt = initial ? Math.max(0, models.findIndex((entry) => entry.model === initial.res?.model
+    && (entry.provider ?? resolved.provider) === initial.res?.provider)) : 0;
+  let pending = initial;
+  const seen = new Set();
+  let attempts = 0;
+  /** @type {Record<string, any> | null} */
+  let res = null;
+  /** @type {BrokenTry['to'] | undefined} */
+  let to;
+  /** @type {{tokens_in: number | null, tokens_out: number | null}} */
+  const usage = { tokens_in: null, tokens_out: null };
+  for (const [index, entry] of models.entries()) {
+    if (index < startAt) continue;
+    const provider = entry.provider ?? resolved.provider;
+    const key = `${provider}\0${entry.model}`;
+    if (seen.has(key) || closedBookRefused(provider, opts.role, openBookCodexAllowed(opts.cfg))) continue;
+    seen.add(key);
+    const cfg = { ...opts.cfg, levels: { ...opts.cfg.levels, [opts.level]: {
+      provider, model: entry.model, ...(entry.effort !== undefined ? { effort: entry.effort } : {}), fallback: [],
+    } } };
+    if (index > 0) to = { level: `levels.${opts.level}.fallback`, provider, model: entry.model };
+    for (let n = 0; n < 2; n++) {
+      try {
+        const out = pending ?? await spawn({ ...opts, cfg });
+        pending = undefined;
+        res = out.res;
+        attempts += out.attempts;
+      } catch {
+        res = null;
+        attempts++;
+      }
+      for (const field of /** @type {const} */ (['tokens_in', 'tokens_out'])) {
+        if (typeof res?.usage?.[field] === 'number') usage[field] = (usage[field] ?? 0) + res.usage[field];
+      }
+      if (!isBroken(res)) return { res, attempts, ...(to ? { to } : {}), usage };
+      await onBroken(res, cfg);
+    }
+  }
+  return { res, attempts, ...(to ? { to } : {}), usage };
+}
+
 /**
  * @typedef {{res: Record<string, any> | null, attempts: number, to: {level: string, provider: string, model: string}}} BrokenTry -
  *   the outcome of a second-level try started by a timed-out attempt (`afterSchemaMiss`).

package/src/session/facts.mjs

@@ -777,7 +777,8 @@ function ruleBroken(row, claim, ctx) {
 }
 
 /**
- * Validate the delegate's answer (step 3). Only a schema-invalid answer is refused. A row answers
+ * Validate the delegate's answer (step 3). Null commands/excerpts are normalized on a copy and
+ * their matched claims downgraded; every other schema-invalid answer is refused. A row answers
  * claim `F<n>` when its fact_id is `F<n>` and its kind is the claim's kind (the id is the anchor,
  * the claim text may be reworded); failing that, when its echoed claim ({@link echoedClaim})
  * equals the claim token and its fact_id is `F<n>` or its kind is the claim's kind. Claims the
@@ -794,11 +795,23 @@ function ruleBroken(row, claim, ctx) {
  * @throws {FactsError} `refused` when the answer does not match the schema.
  */
 export function validateFacts(answer, claims, opts = {}) {
-  if (!validateFile(answer)) {
+  const normalized = structuredClone(answer);
+  /** @type {Map<object, string[]>} */
+  const nullFields = new Map();
+  if (normalized && typeof normalized === 'object' && 'facts' in normalized && Array.isArray(normalized.facts)) {
+    for (const row of normalized.facts) {
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const fields = ['command', 'output_excerpt'].filter((field) => row[field] === null);
+      if (fields.length === 0) continue;
+      for (const field of fields) row[field] = '';
+      nullFields.set(row, fields);
+    }
+  }
+  if (!validateFile(normalized)) {
     const where = (validateFile.errors ?? []).map((e) => `${e.instancePath || '/'} ${e.message}`).slice(0, 5);
     throw new FactsError('refused', `facts answer does not match facts.schema.json: ${where.join('; ')}`);
   }
-  const rows = /** @type {{facts: Fact[]}} */ (answer).facts;
+  const rows = /** @type {{facts: Fact[]}} */ (normalized).facts;
   /** @type {Fact[]} */
   const facts = [];
   /** @type {Downgrade[]} */
@@ -828,7 +841,8 @@ export function validateFacts(answer, claims, opts = {}) {
       return;
     }
     const base = { fact_id: id, claim: redact(claim.token), kind: claim.kind, command: redact(row.command), output_excerpt: claim.kind === 'env' ? '' : redact(row.output_excerpt) };
-    const broken = ruleBroken(row, claim, opts);
+    const fields = nullFields.get(row);
+    const broken = fields ? `delegate returned null ${fields.join(', ')}` : ruleBroken(row, claim, opts);
     if (broken) {
       const reason = redact(broken);
       downgraded.push({ fact_id: id, reason });

package/src/session/spawn.mjs

@@ -51,6 +51,7 @@ import { Ajv2020 } from 'ajv/dist/2020.js';
 import { CODEX_CLOSED_BOOK_REFUSAL, closedBookRefused, isNoToolRole, openBookCodexAllowed } from '../config/closed-book.mjs';
 import { resolveLevel } from '../config/known-ids.mjs';
 import { compileSchema } from '../config/schema-compile.mjs';
+import { blockTaskLines, ContextError, readBlockBrief } from '../context/pack.mjs';
 import { buildArgv } from '../engines/builders/index.mjs';
 import { removeCodexHome } from '../engines/codex-home.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
@@ -61,6 +62,7 @@ import { budgetUsdOf, checkBudget, estimateSessionUsd, priceSession, reservedUsd
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { categoryGate, categoryPlan, RECORD_UNKNOWN_MESSAGE } from '../autopilot/limits.mjs';
 import { StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
 import { exec } from '../util/exec.mjs';
 import { isForbidden, mergeForbidden } from '../util/forbidden.mjs';
 import { semaphore } from '../util/locks.mjs';
@@ -68,6 +70,7 @@ import { readStartTime, registerPid, UNKNOWN_START_TIME } from '../util/reaper.m
 import { asText, stderrTail } from '../util/diagnostic-tail.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { currentRunRoot, pidsDir, runRoot, tmpBase, untrustedReason } from '../util/tmp.mjs';
+import { assertBlockId, mainRootOf } from '../worker/ticket.mjs';
 
 export const ROLES = Object.freeze(['coder', 'reviewer', 'judge', 's2', 'author', 'facts', 'delegate']);
 export const LEVELS = Object.freeze(['L0', 'L1', 'L2', 'L3']);
@@ -538,6 +541,8 @@ export async function spawnSession(opts, deps = {}) {
   if (!LEVELS.includes(level)) throw new SessionError('usage', `level must be one of ${LEVELS.join(', ')}`);
   if (!ROLES.includes(role)) throw new SessionError('usage', `role must be one of ${ROLES.join(', ')}`);
   if (typeof promptPath !== 'string' || !path.isAbsolute(promptPath)) throw new SessionError('usage', 'promptPath must be an absolute path');
+  /** @type {string | null} */
+  let coderPrompt = null;
   const stderr = deps.stderr ?? process.stderr;
   const runRootDir = opts.runRoot ?? currentRunRoot();
   if (role === 'facts' && opts.cwd !== undefined) assertFactsCwd(opts.cwd, runRootDir);
@@ -570,6 +575,9 @@ export async function spawnSession(opts, deps = {}) {
       // in the `finally` below on every other exit path (a throw, a background start)
       const releaseReservation = gate.release;
       try {
+        // Budget refusals take precedence over task loading, including legacy runs without
+        // this block. A failed context load must still release the accepted reservation.
+        if (role === 'coder' && opts.block && coderPrompt === null) coderPrompt = await coderPromptFor(opts);
         const outcome = await runAttempt(step, i + 1 === steps.length, releaseReservation);
         if (outcome.result) return outcome.result;
         waitMs = outcome.waitMs;
@@ -602,7 +610,7 @@ export async function spawnSession(opts, deps = {}) {
     mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
     let keep = false;
     try {
-      const built = buildStep(opts, step, sessionDir, openBook);
+      const built = buildStep(opts, step, sessionDir, openBook, coderPrompt);
       const cli = built.cli;
       built.argv[0] = deps.bins?.[cli] ?? built.argv[0];
       if (role === 'coder') {
@@ -659,6 +667,42 @@ export async function spawnSession(opts, deps = {}) {
   }
 }
 
+/**
+ * Add the recorded task and completion contract without overwriting the caller's brief.
+ * @param {SessionOpts} opts @returns {Promise<string>}
+ */
+async function coderPromptFor(opts) {
+  let blockId;
+  let original;
+  try {
+    blockId = assertBlockId(opts.block);
+    original = readFileSync(opts.promptPath, 'utf8');
+  } catch (err) {
+    throw new SessionError('usage', err instanceof Error ? err.message : 'the coder brief cannot be read');
+  }
+  let task = [];
+  if (opts.run) {
+    let record;
+    try {
+      record = await readRun(opts.run);
+    } catch (err) {
+      if (!(err instanceof StateError && err.code === 'no-run')) throw err;
+    }
+    if (record) {
+      const block = record.blocks?.[blockId];
+      if (!block) throw new SessionError('usage', `run ${opts.run} has no block ${blockId}`);
+      try {
+        const repoRoot = await mainRootOf(record.workspace);
+        task = blockTaskLines({ brief: readBlockBrief(repoRoot, block), acceptance: block.acceptance }, original);
+      } catch (err) {
+        if (err instanceof ContextError) throw new SessionError('usage', err.message);
+        throw err;
+      }
+    }
+  }
+  return `${original.trimEnd()}\n\n${task.length ? `${task.join('\n')}\n\n` : ''}Report the changed files and pass/fail counts. Print TESTS <command> exit=<n> on its own line before the sentinel. On success, print this exact sentinel as your last line:\n===BLOCK ${blockId} COMPLETE===\n`;
+}
+
 /**
  * B33: a session row's dollars from its tokens and the static price table — `{usd, cost_source:
  * 'estimated'}`, or `{usd: null, usd_unknown: true}` when the provider/level has no price.
@@ -812,8 +856,9 @@ async function checkGate(opts, deps, writeRow, stderr, budget, estimate) {
  * @param {{provider: string, model: string, effort?: string, flagFallback?: {provider: string, model: string}}} step
  * @param {string} sessionDir
  * @param {boolean} openBook - B32: `review.allow_open_book_codex`, read once by `spawnSession`.
+ * @param {string | null} [coderPrompt]
  */
-function buildStep(opts, step, sessionDir, openBook) {
+function buildStep(opts, step, sessionDir, openBook, coderPrompt = null) {
   const closedBook = opts.role !== 'coder';
   // B9b.1: the facts delegate may run in the caller's read-only project snapshot; nobody else may
   const snapshot = opts.role === 'facts' && opts.cwd !== undefined ? realpathSync(path.resolve(opts.cwd)) : null; // validated by assertFactsCwd
@@ -823,11 +868,17 @@ function buildStep(opts, step, sessionDir, openBook) {
   if (cli === undefined) throw new SessionError('usage', `provider "${step.provider}" has no CLI mapping`);
   /** @type {Record<string, any>} */
   const params = { provider: step.provider, role: opts.role, model: step.model, promptPath: opts.promptPath, cwd };
+  if (coderPrompt !== null) {
+    params.promptPath = path.join(sessionDir, 'coder-brief.md');
+    writeFileSync(params.promptPath, coderPrompt, { mode: 0o600 });
+  }
   if (step.effort) params.effort = step.effort;
   if (step.flagFallback) params.fallback = [step.flagFallback];
   if (cli === 'claude' && opts.maxBudgetUsd !== undefined) params.maxBudgetUsd = opts.maxBudgetUsd;
   if (closedBook && opts.systemPromptText !== undefined && cli !== 'codex') params.systemPromptText = opts.systemPromptText;
   if (cli === 'codex') params.outPath = path.join(sessionDir, 'out.json');
+  // The session owns this home: a named run must not use the spawning process's lazy root.
+  if (cli === 'codex' && !closedBook) params.runRoot = opts.runRoot ?? currentRunRoot();
   // B32 opt-in: only a no-tools role needs it; coder and facts build exactly as without it
   if (cli === 'codex' && openBook && isNoToolRole(opts.role)) params.allowOpenBook = true;
   // B93: the Codex coder's sandbox profile; no `coder.sandbox` key builds exactly today's argv
@@ -903,7 +954,7 @@ async function runForeground(built, opts, deps) {
     });
   } finally {
     // B4.1: the Codex coder's per-session CODEX_HOME (rules + auth copy) dies with the session.
-    if (built.env?.CODEX_HOME) removeCodexHome(built.env.CODEX_HOME);
+    if (built.env?.CODEX_HOME) removeCodexHome(built.env.CODEX_HOME, opts.runRoot);
   }
   const duration_ms = Date.now() - started;
   /** @type {string | null} */