@codedology/code-forge 0.3.1 → 0.4.0

package/src/session/spawn.mjs

@@ -22,7 +22,10 @@
  * and every attempt writes one ledger row (`event: session`) with `tokens_source` `reported` when
  * the CLI's JSON carried usage, else `estimated` (bytes / 4).
  *
- * A coder argv that `isForbidden` matches is refused before anything spawns (§8.4).
+ * A coder argv that `isForbidden` matches is refused before anything spawns (§8.4). A
+ * reviewer/judge/S2/author level on openai is refused too (`closed-book`, B32: Codex always has a
+ * shell); an openai fallback step of such a session is skipped with one stderr line. The opt-in
+ * `review.allow_open_book_codex: true` lifts both and builds Codex's read-only argv.
  *
  * `background: true` (coders, §5.2): the child is started detached with stdout/stderr going to
  * `<run-root>/sessions/<id>/session.log`, its pid written to `<run-root>/sessions/<id>/pid.json`
@@ -36,6 +39,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 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 { buildArgv } from '../engines/builders/index.mjs';
@@ -43,7 +47,8 @@ import { removeCodexHome } from '../engines/codex-home.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { parseSentinel } from '../engines/sentinel.mjs';
 import { parseUsage } from '../engines/usage-parse.mjs';
-import { appendRow } from '../ledger/write.mjs';
+import { budgetUsdOf, checkBudget, priceSession, SPEND_UNREADABLE_MESSAGE } from '../ledger/spend.mjs';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { exec } from '../util/exec.mjs';
 import { isForbidden, mergeForbidden } from '../util/forbidden.mjs';
 import { readStartTime, registerPid, UNKNOWN_START_TIME } from '../util/reaper.mjs';
@@ -59,7 +64,7 @@ export const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
 /** Unavailability reasons that move the ladder to the next step (§5.6). */
 export const UNAVAILABLE_REASONS = Object.freeze(['cli-missing', 'login-expired', 'http-402', 'rate-limited']);
 
-/** An error the spawner raises before anything runs (`code`: `usage`, `forbidden`). */
+/** An error the spawner raises before anything runs (`code`: `usage`, `forbidden`, `closed-book`). */
 export class SessionError extends Error {
   /** @param {string} code @param {string} message */
   constructor(code, message) {
@@ -84,6 +89,125 @@ export function runRootFor(runId, root) {
   return runRoot(runId, { root });
 }
 
+/** How much of a timed-out session's stderr is kept (B30). */
+export const DIAGNOSTIC_TAIL_BYTES = 4096;
+
+/** A timed-out session's stderr over this size keeps no text at all (bounds the redact cost). */
+export const STDERR_MAX_BYTES = 1024 * 1024;
+
+/** How many stdout event types a timed-out session keeps. */
+export const STDOUT_EVENTS_MAX = 20;
+
+/** The longest event type kept. */
+const EVENT_TYPE_MAX = 40;
+
+/**
+ * Packet lines shorter than this are too common to tell apart from ordinary output, so they are
+ * NOT filtered. Accepted risk (B30): a packet line under 16 characters (a brace, `return x;`) can
+ * appear in a stderr tail; such a line carries no meaningful packet content on its own.
+ */
+const PACKET_LINE_MIN = 16;
+
+/** The tail note when the packet cannot be read: no stderr text is kept at all (fail closed). */
+export const TAIL_WITHHELD_PACKET = 'withheld: packet unreadable';
+/** The tail note when stderr is over `STDERR_MAX_BYTES`. */
+export const TAIL_WITHHELD_LARGE = 'stderr too large, withheld';
+/** The tail note when the last 4 KB of stderr is one partial line. */
+export const TAIL_WITHHELD_LONG_LINE = 'one long line, withheld';
+
+/** @param {Buffer} buf @param {number} at @returns {number} the first character start at or after `at`. */
+function charStart(buf, at) {
+  let i = at;
+  while (i < buf.length && (buf[i] & 0xc0) === 0x80) i += 1;
+  return i;
+}
+
+/** @param {unknown} text @returns {string} */
+function asText(text) {
+  return Buffer.isBuffer(text) ? text.toString('utf8') : typeof text === 'string' ? text : '';
+}
+
+const PEM_BEGIN = /-----BEGIN [A-Z0-9 ]*-----/;
+const PEM_END = /-----END [A-Z0-9 ]*-----/;
+
+/**
+ * The stderr tail of a timed-out session (B30), never packet content:
+ *  1. no packet text (unreadable) ⇒ no text: `{tail: null, note: 'withheld: packet unreadable'}`;
+ *     stderr over `STDERR_MAX_BYTES` ⇒ `{tail: null, note: 'stderr too large, withheld'}`;
+ *  2. on the FULL raw text: every PEM block (`-----BEGIN` … `-----END` lines, an unterminated one
+ *     to the end) and every line repeating a packet line (≥ 16 chars) is dropped;
+ *  3. the FULL remaining text goes through B0 `redact`;
+ *  4. over `maxBytes`, the last `maxBytes` bytes are kept, starting on a character, with the first
+ *     (partial) line dropped; when that piece has no line break the tail is withheld.
+ * @param {string | Buffer | null | undefined} text @param {string | null} packetText @param {number} [maxBytes]
+ * @returns {{tail: string | null, note?: string}}
+ */
+export function stderrTail(text, packetText, maxBytes = DIAGNOSTIC_TAIL_BYTES) {
+  if (typeof packetText !== 'string') return { tail: null, note: TAIL_WITHHELD_PACKET };
+  const raw = asText(text);
+  if (raw.length === 0) return { tail: '' };
+  if (Buffer.byteLength(raw) > STDERR_MAX_BYTES) return { tail: null, note: TAIL_WITHHELD_LARGE };
+  const packetLines = [
+    ...new Set(
+      packetText
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length >= PACKET_LINE_MIN),
+    ),
+  ];
+  let inPem = false;
+  /** @type {string[]} */
+  const kept = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (inPem) {
+      if (PEM_END.test(t)) inPem = false;
+      continue;
+    }
+    if (PEM_BEGIN.test(t)) {
+      inPem = !PEM_END.test(t);
+      continue;
+    }
+    if (t.length >= PACKET_LINE_MIN && packetLines.some((p) => t.includes(p))) continue;
+    kept.push(line);
+  }
+  const safe = /** @type {string} */ (redact(kept.join('\n')));
+  const buf = Buffer.from(safe, 'utf8');
+  if (buf.length <= maxBytes) return { tail: safe };
+  const from = charStart(buf, buf.length - maxBytes);
+  const piece = buf.subarray(from).toString('utf8');
+  if (buf[from - 1] === 0x0a) return { tail: piece }; // the cut fell exactly on a line start
+  const nl = piece.indexOf('\n');
+  if (nl === -1) return { tail: '', note: TAIL_WITHHELD_LONG_LINE };
+  return { tail: piece.slice(nl + 1) };
+}
+
+/**
+ * What a timed-out session's stdout says without any of its text (B30): the last
+ * `STDOUT_EVENTS_MAX` event types (JSON lines with a string `type`, each cut to 40 characters and
+ * kept only when it is all `[a-z0-9_.-]`) and the total byte length. Non-JSON stdout gives only
+ * `stdout_bytes`. Event payloads, which can echo the packet, are never kept.
+ * @param {string | Buffer | null | undefined} text
+ * @returns {{stdout_bytes: number, stdout_events?: string[]}}
+ */
+export function stdoutEvents(text) {
+  const raw = asText(text);
+  const bytes = Buffer.byteLength(raw);
+  /** @type {string[]} */
+  const types = [];
+  const lines = raw.split('\n');
+  // scan from the end: stop once enough events are kept, or after a bounded number of lines
+  for (let i = lines.length - 1, scanned = 0; i >= 0 && types.length < STDOUT_EVENTS_MAX && scanned < 5000; i -= 1, scanned += 1) {
+    const line = lines[i].trim();
+    if (!line.startsWith('{')) continue;
+    const event = tryJSON(line);
+    if (!event || typeof event !== 'object' || typeof event.type !== 'string') continue;
+    const type = event.type.slice(0, EVENT_TYPE_MAX);
+    if (/^[a-z0-9_.-]+$/.test(type)) types.unshift(type);
+  }
+  return types.length > 0 ? { stdout_bytes: bytes, stdout_events: types } : { stdout_bytes: bytes };
+}
+
 /** @param {number} bytes */
 export const estimateTokens = (bytes) => Math.ceil(bytes / 4);
 
@@ -317,6 +441,8 @@ function childEnv(/** @type {NodeJS.ProcessEnv} */ env) {
  * @property {Partial<Record<"claude"|"codex"|"grok", string>>} [bins] - replaces argv[0] (tests: the fakes).
  * @property {typeof exec} [exec]
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow]
+ * @property {() => Promise<Array<Record<string, any>>>} [readRows] - the ledger rows the
+ *   `budget.usd` check reads (default: `readAllRows(opts.slug)`).
  * @property {{write: (s: string) => unknown}} [stderr]
  * @property {NodeJS.ProcessEnv} [env]
  */
@@ -432,18 +558,27 @@ export async function spawnSession(opts, deps = {}) {
   const runRootDir = opts.runRoot ?? currentRunRoot();
   if (role === 'facts' && opts.cwd !== undefined) assertFactsCwd(opts.cwd, runRootDir);
   const writeRow = deps.writeRow ?? (opts.slug ? (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: /** @type {string} */ (opts.slug) }) : null);
-  const steps = ladderFor(resolveLevel(cfg, level), role);
+  const ladder = ladderFor(resolveLevel(cfg, level), role);
+  // B32: Codex has no no-tools mode, so it runs no reviewer/judge/S2/author session unless the
+  // config opts in (`review.allow_open_book_codex: true`). Without it, step 0 on openai refuses the
+  // session and an openai fallback step is dropped from the ladder.
+  const openBook = openBookCodexAllowed(cfg); // read ONCE: the refusal and every build use it
+  if (closedBookRefused(ladder[0].provider, role, openBook)) throw new SessionError('closed-book', CODEX_CLOSED_BOOK_REFUSAL);
+  const steps = ladder.filter((step) => !closedBookRefused(step.provider, role, openBook));
+  if (steps.length < ladder.length) writeSafe(stderr, `fallback skipped: ${ladder.length - steps.length} openai step(s) — ${CODEX_CLOSED_BOOK_REFUSAL}\n`);
   if (opts.background) steps.length = 1;
 
   const attempts = [];
   let rateLimitedOnce = false;
   for (let i = 0; i < steps.length; i += 1) {
     const step = steps[i];
+    const refused = await budgetGate(opts, deps, writeRow, stderr);
+    if (refused) return { ...refused, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
     const sessionDir = path.join(runRootDir, 'sessions', `${role}-${Date.now()}-${randomBytes(4).toString('hex')}`);
     mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
     let keep = false;
     try {
-      const built = buildStep(opts, step, sessionDir);
+      const built = buildStep(opts, step, sessionDir, openBook);
       const cli = built.cli;
       built.argv[0] = deps.bins?.[cli] ?? built.argv[0];
       if (role === 'coder') {
@@ -458,7 +593,8 @@ export async function spawnSession(opts, deps = {}) {
         // B4.1: the builder's env (the Codex coder's CODEX_HOME) wins over the caller's; a
         // background session's home stays until the run root is swept.
         const bg = startBackground(built, sessionDir, runRootDir, { ...childEnv(deps.env ?? process.env), ...(built.env ?? {}) });
-        if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started' });
+        // a detached child's tokens are never read back: its price is unknown (use `ledger add coder`)
+        if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started', usd: null, usd_unknown: true });
         return { status: 'started', ...bg, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
       }
 
@@ -471,6 +607,7 @@ export async function spawnSession(opts, deps = {}) {
         tokens_in: attempt.usage.tokens_in,
         tokens_out: attempt.usage.tokens_out,
         tokens_source: attempt.usage.tokens_source,
+        ...sessionUsd(step.provider, level, attempt.usage),
         duration_ms: attempt.duration_ms,
         ...(level === 'L3' && step.fallback_step > 0 ? { l3_fallback: true } : {}),
       };
@@ -491,6 +628,60 @@ export async function spawnSession(opts, deps = {}) {
   throw new Error('spawnSession: unreachable — the ladder always has a step');
 }
 
+/**
+ * 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.
+ * @param {string} provider @param {string} level @param {{tokens_in: number, tokens_out: number}} usage
+ */
+function sessionUsd(provider, level, usage) {
+  const priced = priceSession({ provider, level, tokens_in: usage.tokens_in, tokens_out: usage.tokens_out });
+  return priced.usd_unknown ? { usd: null, usd_unknown: true } : { usd: priced.usd, cost_source: 'estimated' };
+}
+
+/**
+ * B33, R6 — the single budget choke point: before every spawn attempt of every role, a run with
+ * `budget.usd` set reads its spend from the ledger (`deps.readRows`, else the `slug` ledger).
+ * ≥ 80 % prints and records one warning per run; ≥ 100 % refuses with a plain message and a
+ * `budget.refused` row, and nothing is spawned. No `budget.usd` or no `run` ⇒ no check. Fail
+ * closed: with a budget and a run but no way to read the spend (no `readRows`, no `slug`, or the
+ * read throws) the session is refused too. It sits at the top of the ladder loop, so every attempt
+ * — each fallback step, the rate-limit retry of a step, and every `spawnSession` call a caller
+ * makes again (B30's timeout retry) — passes it.
+ * @param {SessionOpts} opts @param {SessionDeps} deps
+ * @param {((row: Record<string, any>) => Promise<unknown>) | null} writeRow
+ * @param {{write: (s: string) => unknown}} stderr
+ * @returns {Promise<SessionResult | null>} the refusal result, or null to go on.
+ */
+async function budgetGate(opts, deps, writeRow, stderr) {
+  const budget = budgetUsdOf(opts.cfg);
+  if (budget === null || typeof opts.run !== 'string' || opts.run.length === 0) return null;
+  /** @type {Array<Record<string, any>> | null} */
+  let rows = null;
+  try {
+    const slug = opts.slug;
+    const read = deps.readRows ?? (slug ? () => readAllRows(slug) : null);
+    const got = read ? await read() : null;
+    rows = Array.isArray(got) ? got : null;
+  } catch {
+    rows = null;
+  }
+  if (rows === null) {
+    // fail closed: a budget we cannot check is never treated as "not reached"
+    writeSafe(stderr, `code-forge: ${SPEND_UNREADABLE_MESSAGE}\n`);
+    if (writeRow) {
+      try {
+        await writeRow({ event: 'budget.refused', run: opts.run, block: opts.block ?? null, role: opts.role, budget_usd: budget, spent_usd: null, reason: 'spend-unreadable' });
+      } catch {
+        // the refusal stands without its row
+      }
+    }
+    return { status: 'unavailable', reason: 'budget', message: SPEND_UNREADABLE_MESSAGE, answer: null, spent_usd: null, budget_usd: budget };
+  }
+  const verdict = await checkBudget({ budget, run: opts.run, rows, block: opts.block ?? null, role: opts.role, writeRow, stderr });
+  if (!verdict.refuse) return null;
+  return { status: 'unavailable', reason: 'budget', message: verdict.message, answer: null, spent_usd: verdict.spent, budget_usd: budget };
+}
+
 /**
  * Build one step's argv; closed-book roles get a fresh empty cwd inside the session dir (the facts
  * role: the caller's snapshot when `opts.cwd` names one), and Codex
@@ -498,8 +689,9 @@ export async function spawnSession(opts, deps = {}) {
  * @param {SessionOpts} opts
  * @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`.
  */
-function buildStep(opts, step, sessionDir) {
+function buildStep(opts, step, sessionDir, openBook) {
   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
@@ -514,6 +706,8 @@ function buildStep(opts, step, sessionDir) {
   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');
+  // 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;
   /** @type {Record<string, any> | null} */
   let compiled = null;
   const strict = variantFor(step.provider) === 'strict';
@@ -570,7 +764,22 @@ async function runForeground(built, opts, deps) {
 
   const unavailable = classifyUnavailable(res, read.parsed);
   if (unavailable) return { status: 'unavailable', reason: unavailable, answer: null, ...common };
-  if (res.timedOut) return { status: 'timeout', reason: `killed after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms`, answer: null, ...common };
+  if (res.timedOut) {
+    // B30: what the CLI printed last, so a hang's cause can be seen — stderr redacted, capped and
+    // packet-free; stdout only as event types and a byte count, never its text
+    /** @type {string | null} */
+    let packetText = input !== undefined ? Buffer.from(input).toString('utf8') : null;
+    if (packetText === null) {
+      try {
+        packetText = readFileSync(opts.promptPath, 'utf8');
+      } catch {
+        packetText = null; // fail closed: no tails without the packet to filter against
+      }
+    }
+    const err = stderrTail(res.stderr, packetText);
+    const tails = { stderr_tail: err.tail, ...(err.note ? { tail_note: err.note } : {}), ...stdoutEvents(res.stdout) };
+    return { status: 'timeout', reason: `killed after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms`, answer: null, ...common, ...tails };
+  }
   if (res.result !== 'ok' || read.parsed?.is_error === true) return { status: 'failed', reason: `exit ${res.code}`, answer: null, ...common };
   if (built.compiled) {
     // validate against the schema the provider was actually given (the cached variant, stable across attempts)

package/src/state/block.mjs

@@ -13,6 +13,7 @@
 
 import { createHash } from 'node:crypto';
 import os from 'node:os';
+import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
 import { StateError } from './paths.mjs';
@@ -125,11 +126,15 @@ function activeBlocks(record) {
 
 /**
  * `block open` — refuses a second open of the same id and any owned set that overlaps another
- * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast.
+ * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast and the
+ * block kind (B34: the declared `kind`, else `blockKind` of the owned files). A docs/contract
+ * block asked for below `levels.coder_floor_docs` (default L1) is opened AT the floor: the entry
+ * and the dispatch row carry the floor level, and the row adds `requested_level` and
+ * `trigger: 'docs_floor'`.
  * @param {{
  *   runId: string, id: string, level: string, owned: string[], acceptance: unknown,
  *   attempt?: number, base?: string, lines?: number, brief?: {path: string, content: Buffer | string},
- *   writeRow: WriteRow, now?: Date,
+ *   kind?: string, cfg?: Record<string, any>, writeRow: WriteRow, now?: Date,
  * }} opts
  * @returns {Promise<{block: Record<string, any>, pointer: string | null}>}
  */
@@ -139,8 +144,11 @@ export async function openBlock(opts) {
   if (typeof level !== 'string' || !LEVEL.test(level)) throw new StateError('bad-level', 'level must be L0..L3');
   if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
   if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
+  if (opts.kind !== undefined && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${BLOCK_KINDS.join(', ')}`);
   const owned = assertOwned(opts.owned);
   const acceptance = assertAcceptance(opts.acceptance);
+  const kind = blockKind({ owned, declared: opts.kind });
+  const dispatched = dispatchLevel({ lane: level, kind, cfg: opts.cfg });
   const pointer = opts.brief ? briefPointer(opts.brief.path, opts.brief.content) : null;
 
   const block = await mutateRun(runId, null, writeRow, async (record) => {
@@ -150,11 +158,12 @@ export async function openBlock(opts) {
       if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
     }
     const baseSha = await resolveCommit(opts.base ?? 'HEAD', record.workspace);
-    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], level, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open' };
+    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open' };
     record.blocks[id] = entry;
+    const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
     return {
       result: entry,
-      rows: [{ event: 'dispatch', block: id, level, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
+      rows: [{ event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
     };
   });
   return { block, pointer };

package/src/state/config-snapshot.mjs

@@ -0,0 +1,150 @@
+/**
+ * The run's config snapshot (issue #2, block B35): `run start` stores the loaded
+ * `.code-forge.yml` in the run record, `run reload` replaces it mid-run, and the worker reviews
+ * every ticket with the snapshot it was enqueued under.
+ *
+ * Shape, in the authoritative run record (`~/.code-forge/runs/<run>.json`):
+ *
+ *   config: {
+ *     hash:      sha256 of the canonical JSON of the snapshot in force,
+ *     snapshots: {<hash>: <config>}   every snapshot a queued ticket may still need,
+ *     pins:      {<ticket id>: <hash>} tickets that were pending at a reload keep the old snapshot,
+ *     reloaded_at?: ISO time of the last reload,
+ *   }
+ *
+ * A ticket is pinned by `run reload` itself (the orchestrator, under the run lock), never by the
+ * coder-writable ticket file, so a coder cannot pick an older (weaker) config for a new ticket.
+ * Messages here name key PATHS only, never values.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Keys that cannot change mid-run, each with why. A change to one is refused by `run reload`
+ * (end the run and start a new one).
+ */
+export const IMMUTABLE_KEYS = Object.freeze({
+  version: 'the config format is fixed for the run',
+  'project.slug': 'the ledger file of the run is chosen at run start',
+  engine: 'the run engine is fixed at run start',
+  'tmp.root': "the worker's run temp root is created at run start",
+  keys: 'the worker resolves keys once, at start',
+  'system1.key': 'the worker resolves the Jev key once, at start',
+});
+
+/** @param {unknown} v @returns {boolean} what `JSON.stringify` drops from an object. */
+const dropped = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
+
+/**
+ * JSON with object keys sorted at every level (arrays keep their order), so the hash does not
+ * depend on key order in the YAML. JSON semantics otherwise: a value with `toJSON` (a `Date` from
+ * a YAML timestamp ⇒ its ISO string) is converted first, and what JSON drops is dropped (`null` in
+ * a list) — so the hash of a config equals the hash of the same config after the run record's
+ * JSON save/read round trip.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalJSON(value) {
+  const v = value !== null && typeof value === 'object' && typeof (/** @type {any} */ (value).toJSON) === 'function' ? /** @type {any} */ (value).toJSON() : value;
+  if (Array.isArray(v)) return `[${v.map((item) => canonicalJSON(dropped(item) ? null : item)).join(',')}]`;
+  if (v !== null && typeof v === 'object') {
+    const obj = /** @type {Record<string, unknown>} */ (v);
+    const keys = Object.keys(obj)
+      .filter((k) => !dropped(obj[k]))
+      .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJSON(obj[k])}`).join(',')}}`;
+  }
+  return dropped(v) ? 'null' : JSON.stringify(v);
+}
+
+/** @param {unknown} cfg @returns {string} sha256 hex of the canonical JSON. */
+export function configHash(cfg) {
+  return createHash('sha256').update(canonicalJSON(cfg)).digest('hex');
+}
+
+/** @param {unknown} v @returns {v is Record<string, unknown>} */
+const isMapping = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The dotted key paths whose value differs between `before` and `after`, sorted. Mappings are
+ * walked key by key; a key present on one side only, a list, or a scalar is one path. A path
+ * segment that is not a plain identifier is written in brackets (`keys["a.b"]`).
+ * @param {unknown} before @param {unknown} after
+ * @returns {string[]}
+ */
+export function changedKeyPaths(before, after) {
+  /** @type {string[]} */
+  const out = [];
+  /** @param {unknown} a @param {unknown} b @param {string} at */
+  const walk = (a, b, at) => {
+    if (isMapping(a) && isMapping(b)) {
+      const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+      for (const k of keys) walk(own(a, k), own(b, k), join(at, k));
+      return;
+    }
+    if (canonicalJSON(a ?? null) !== canonicalJSON(b ?? null) || (a === undefined) !== (b === undefined)) out.push(at);
+  };
+  walk(before, after, '');
+  return out.sort();
+}
+
+/** @param {Record<string, unknown>} obj @param {string} key @returns {unknown} an OWN property only. */
+const own = (obj, key) => (Object.hasOwn(obj, key) ? obj[key] : undefined);
+
+/** @param {string} at @param {string} key */
+function join(at, key) {
+  const seg = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) ? key : `[${JSON.stringify(key)}]`;
+  if (at === '') return seg;
+  return seg.startsWith('[') ? `${at}${seg}` : `${at}.${seg}`;
+}
+
+/**
+ * @param {unknown} cfg @param {string} dotted
+ * @returns {unknown} the value at `dotted`, or undefined.
+ */
+function valueAt(cfg, dotted) {
+  /** @type {unknown} */
+  let cur = cfg;
+  for (const seg of dotted.split('.')) {
+    if (!isMapping(cur)) return undefined;
+    cur = own(cur, seg);
+  }
+  return cur;
+}
+
+/**
+ * The immutable keys whose value differs between the two configs, in {@link IMMUTABLE_KEYS} order.
+ * @param {unknown} before @param {unknown} after
+ * @returns {string[]}
+ */
+export function immutableChanges(before, after) {
+  return Object.keys(IMMUTABLE_KEYS).filter((k) => canonicalJSON(valueAt(before, k) ?? null) !== canonicalJSON(valueAt(after, k) ?? null));
+}
+
+/**
+ * The `config` block for a new run record.
+ * @param {Record<string, any>} cfg
+ */
+export function initialConfigState(cfg) {
+  const hash = configHash(cfg);
+  return { hash, snapshots: { [hash]: cfg }, pins: {} };
+}
+
+/**
+ * The snapshot a ticket is reviewed with: its pin when `run reload` pinned it, else the current
+ * one. Null when the record predates snapshots (the caller keeps the config it booted with).
+ * A snapshot that is missing or does not match its hash throws `config-snapshot`.
+ * @param {Record<string, any>} record @param {string} ticket
+ * @returns {{hash: string, config: Record<string, any>} | null}
+ */
+export function snapshotFor(record, ticket) {
+  const state = record?.config;
+  if (!isMapping(state) || typeof state.hash !== 'string') return null;
+  const pins = isMapping(state.pins) ? state.pins : {};
+  const pin = own(pins, ticket);
+  const hash = typeof pin === 'string' ? pin : state.hash;
+  const snaps = isMapping(state.snapshots) ? state.snapshots : {};
+  const config = own(snaps, hash);
+  if (!isMapping(config) || configHash(config) !== hash) throw new Error('config-snapshot');
+  return { hash, config };
+}

package/src/state/run.mjs

@@ -16,6 +16,7 @@ import { mkdir, readFile, rename, rmdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { exec } from '../util/exec.mjs';
 import { StateError, assertRunId, assertWorkspaceOutsideRuns, mirrorPath, newRunId, runRecordPath, runsDir } from './paths.mjs';
+import { changedKeyPaths, configHash, IMMUTABLE_KEYS, immutableChanges, initialConfigState } from './config-snapshot.mjs';
 import { generateKey, loadKey, signRow } from './signer.mjs';
 
 /** @typedef {(row: Record<string, any>) => Promise<unknown>} WriteRow */
@@ -165,6 +166,9 @@ export async function startRun(opts) {
     status: 'active',
     blocks: {},
     orphans: [],
+    // B35: the config snapshot the worker reviews with (`run reload` replaces it). Only when the
+    // caller passed the loaded config: a record without it keeps the worker on its boot config.
+    ...(opts.config !== undefined ? { config: initialConfigState(config) } : {}),
   };
   return withRunLock(runId, async () => {
     const exists = await readRun(runId).then(
@@ -179,6 +183,88 @@ export async function startRun(opts) {
   });
 }
 
+/**
+ * `run reload` (B35): replace the run's config snapshot with `config` (already loaded and
+ * validated by the caller), entirely under the run lock. Open blocks, their attempts and the
+ * worker pin are untouched.
+ *
+ * `readPending()` (the queue's tickets without a done marker) is called UNDER the lock, right
+ * before the record is saved, so the window in which a ticket could be enqueued unpinned is as
+ * short as it can be (enqueueing itself does not take the run lock). Each pending ticket keeps a
+ * pin whose snapshot is still stored; any other pending ticket — new, or pinned to a snapshot that
+ * has gone missing (never left dangling) — is pinned to the snapshot in force until now. Pins of
+ * tickets no longer pending are dropped, and so are snapshots no pin or the current hash names.
+ *
+ * Fixed keys ({@link IMMUTABLE_KEYS}): every one that changed is refused at once
+ * (`immutable-key`, nothing written). A record from before snapshots (no `config`) is checked
+ * against what it does store: `engine` and the ledger slug (`effectiveSlug`, computed by the
+ * caller the same way `run start` did); it then gets its first snapshot, `changed_keys: null`,
+ * `old_hash: null`.
+ *
+ * No change (same hash) ⇒ nothing written, no row. Otherwise the record is saved FIRST (it is the
+ * source of truth), then one signed `run.reload` row: the changed key PATHS (never values) and
+ * the old/new snapshot hashes. A row that cannot be written leaves the reload in place and is
+ * reported as `rowError`.
+ * @param {{
+ *   runId: string, config: Record<string, any>, readPending?: () => string[], effectiveSlug?: string,
+ *   writeRow: WriteRow, now?: Date,
+ * }} opts
+ * @returns {Promise<{changed: string[] | null, oldHash: string | null, newHash: string, pinned: number, rowError: string | null}>}
+ *   `changed` is `[]` when nothing changed.
+ */
+export async function reloadRun({ runId, config, readPending = () => [], effectiveSlug, writeRow, now = new Date() }) {
+  return withRunLock(runId, async () => {
+    const current = await readRun(runId);
+    if (current.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
+    const state = current.config && typeof current.config === 'object' && typeof current.config.hash === 'string' ? current.config : null;
+    const stored = state && state.snapshots && typeof state.snapshots === 'object' ? state.snapshots : {};
+    const newHash = configHash(config);
+    const oldHash = state ? state.hash : null;
+    if (oldHash === newHash) return { changed: [], oldHash, newHash, pinned: 0, rowError: null };
+    const before = state && Object.hasOwn(stored, state.hash) ? stored[state.hash] : undefined;
+    if (state && (before === null || typeof before !== 'object')) throw new StateError('config-snapshot', `run ${runId}: the current config snapshot is missing from the run record`);
+    /** @type {string[]} */
+    let frozen;
+    if (state) {
+      frozen = immutableChanges(before, config);
+    } else {
+      // no snapshot: compare what the record stores (`run start` wrote engine and the slug)
+      frozen = [];
+      if (effectiveSlug !== undefined && effectiveSlug !== current.project) frozen.push('project.slug');
+      if (typeof current.engine === 'string' && (config.engine ?? 'auto') !== current.engine) frozen.push('engine');
+    }
+    if (frozen.length > 0) {
+      const why = frozen.map((key) => `${key} cannot change mid-run (${IMMUTABLE_KEYS[/** @type {keyof typeof IMMUTABLE_KEYS} */ (key)]})`);
+      throw new StateError('immutable-key', `${why.join('; ')} — put ${frozen.length === 1 ? 'it' : 'them'} back, or end the run and start a new one`);
+    }
+    const changed = state ? changedKeyPaths(before, config) : null;
+    /** @type {Record<string, string>} */
+    const pins = {};
+    const oldPins = state?.pins && typeof state.pins === 'object' ? state.pins : {};
+    for (const ticket of new Set(readPending())) {
+      const hash = Object.hasOwn(oldPins, ticket) ? oldPins[ticket] : undefined;
+      if (typeof hash === 'string' && Object.hasOwn(stored, hash)) pins[ticket] = hash;
+      else if (oldHash !== null) pins[ticket] = oldHash;
+    }
+    /** @type {Record<string, any>} */
+    const snapshots = { [newHash]: config };
+    for (const hash of new Set(Object.values(pins))) snapshots[hash] = stored[hash];
+    current.config = { hash: newHash, snapshots, pins, reloaded_at: now.toISOString() };
+    current.provider = config.provider ?? null;
+    current.levels = config.levels ?? null;
+    current.fallback_mode = config.system1?.fallback ?? 'rules';
+    await saveRun(current);
+    const pinned = Object.keys(pins).length;
+    let rowError = null;
+    try {
+      await writeSigned(runId, writeRow, { event: 'run.reload', changed_keys: changed, old_hash: oldHash, new_hash: newHash, pinned_tickets: pinned });
+    } catch (err) {
+      rowError = err?.code ?? err?.name ?? 'error';
+    }
+    return { changed, oldHash, newHash, pinned, rowError };
+  });
+}
+
 /**
  * `run start --reattach`: re-pin a restarted worker (the orchestrator only — §4.8).
  * @param {{runId: string, workerPid: number, writeRow: WriteRow, probe?: StartTimeProbe}} opts