@codedology/code-forge 0.3.2 → 0.4.0

package/src/util/breadcrumbs.mjs

@@ -0,0 +1,145 @@
+/**
+ * Breadcrumbs (B37): the names of the last commands run, for the error log's `before` field.
+ *
+ * `bin/code-forge.mjs` calls {@link noteCommand} once per known verb, before it runs. It keeps the
+ * last {@link BREADCRUMB_MAX} commands in `~/.code-forge/logs/breadcrumbs.json` (a JSON array of
+ * strings, oldest first; folder 0700, file 0600, written to a temp file and renamed). A command is
+ * the verb name plus its subcommand word only when that word is one of the verb's own words
+ * (`keys test`, `init`): never a flag, a flag value or any other positional — the same rule as the
+ * error log's `sub`. The list as it was BEFORE this command is kept in memory
+ * ({@link previousCommands}), so an error or warning logged by this process names the commands
+ * that came before it.
+ *
+ * Best effort: never throws, never changes the verb's outcome. `CODE_FORGE_NO_ERROR_LOG=1` turns it
+ * off (checked here too: nothing is read or written); no HOME means no file. A file that does not
+ * parse, or entries that are not command names, are dropped. An existing logs folder is set to
+ * 0700 (best effort).
+ */
+
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * The subcommand words each verb knows (the error log's `sub` uses the same table); a word is
+ * recorded only when it is one of these (anything else could be a user value: a path, an id, a name).
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const SUBCOMMANDS = Object.freeze({
+  block: ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'],
+  gates: ['detect', 'run', 'secret-scan', 'safe-edit', 'scope', 'acceptance', 'transcript-grep'],
+  jev: ['ask'],
+  keys: ['list', 'set', 'test', 'remove'],
+  ledger: ['calibration', 'outcome', 'tail'],
+  logs: ['summary', 'clear', 'path', 'report'],
+  plan: ['check'],
+  proof: ['tier', 'export', 'lock', 'unlock', 'restore', 'red-green'],
+  run: ['start', 'status', 'end'],
+  tools: ['install'],
+});
+
+/** The opt-out variable (the same one the error log reads). */
+const NO_LOG_ENV = 'CODE_FORGE_NO_ERROR_LOG';
+
+/** @param {NodeJS.ProcessEnv} env @returns {boolean} */
+function off(env) {
+  const flag = env[NO_LOG_ENV];
+  return typeof flag === 'string' && flag !== '' && flag !== '0';
+}
+
+/** How many commands the file keeps. */
+export const BREADCRUMB_MAX = 5;
+
+/** A command name: a verb, optionally one subcommand word (`keys test`). */
+export const CRUMB = /^[a-z][a-z0-9-]{0,39}(?: [a-z][a-z0-9-]{0,39})?$/;
+
+/** @type {{verb: string, sub: string|null, before: string[]} | null} */
+let current = null;
+
+/**
+ * @param {string|null|undefined} home
+ * @returns {string|null} the breadcrumb file, or null without a home.
+ */
+export function breadcrumbPath(home) {
+  return typeof home === 'string' && home.length > 0 ? path.join(home, '.code-forge', 'logs', 'breadcrumbs.json') : null;
+}
+
+/**
+ * The commands in the file, oldest first: only command-shaped strings, at most the last
+ * {@link BREADCRUMB_MAX}; [] when there is no file or it does not parse.
+ * @param {string|null} file
+ * @returns {Promise<string[]>}
+ */
+export async function readBreadcrumbs(file) {
+  if (file === null) return [];
+  try {
+    const parsed = JSON.parse(await readFile(file, 'utf8'));
+    return cleanList(parsed);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {unknown} list
+ * @returns {string[]} the command-shaped strings of `list`, the last {@link BREADCRUMB_MAX}.
+ */
+export function cleanList(list) {
+  if (!Array.isArray(list)) return [];
+  return list.filter((c) => typeof c === 'string' && CRUMB.test(c)).slice(-BREADCRUMB_MAX);
+}
+
+/**
+ * Record one command (called by the router before the verb runs). Never throws.
+ * @param {object} o
+ * @param {string} o.verb - a known verb name.
+ * @param {string|null} o.sub - its subcommand word; dropped unless it is one of the verb's own
+ *   words in {@link SUBCOMMANDS}.
+ * @param {NodeJS.ProcessEnv} [o.env]
+ * @returns {Promise<boolean>} whether the file was written.
+ */
+export async function noteCommand({ verb, sub, env = process.env }) {
+  try {
+    if (typeof verb !== 'string' || !CRUMB.test(verb)) {
+      current = null;
+      return false;
+    }
+    const known = Object.hasOwn(SUBCOMMANDS, verb) ? SUBCOMMANDS[verb] : [];
+    const word = typeof sub === 'string' && known.includes(sub) ? sub : null;
+    const crumb = word ? `${verb} ${word}` : verb;
+    current = { verb, sub: word, before: [] };
+    if (off(env)) return false;
+    const file = breadcrumbPath(env.HOME);
+    if (file === null) return false;
+    const before = await readBreadcrumbs(file);
+    current.before = before;
+    const next = [...before, crumb].slice(-BREADCRUMB_MAX);
+    const tmp = `${file}.tmp-${process.pid}`;
+    try {
+      await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+      await chmod(path.dirname(file), 0o700).catch(() => {}); // an older folder may be 0755
+      await writeFile(tmp, `${JSON.stringify(next)}\n`, { encoding: 'utf8', mode: 0o600 });
+      await rename(tmp, file);
+      return true;
+    } catch {
+      await rm(tmp, { force: true }).catch(() => {});
+      return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+/** @returns {string[]} the commands run before this one (oldest first); [] when none was noted. */
+export function previousCommands() {
+  return current ? [...current.before] : [];
+}
+
+/** @returns {{verb: string, sub: string|null} | null} the command this process runs, when noted. */
+export function currentCommand() {
+  return current ? { verb: current.verb, sub: current.sub } : null;
+}
+
+/** Forget the noted command (tests). */
+export function resetBreadcrumbs() {
+  current = null;
+}

package/src/util/error-hint.mjs

@@ -5,7 +5,7 @@
  *    {@link AGENT_ENV_VARS}, the same names `src/install/agent-env.mjs` checks — copied here
  *    because the router may only load `src/util`; a test keeps the two lists equal);
  *  - the entry has a well-formed fingerprint (12 hex characters);
- *  - the exit is not 2 (a usage error says what to fix already);
+ *  - the exit is not 2 (a usage error says what to fix already) and the entry is no warning (B37);
  *  - the same fingerprint got no hint in the last 24 hours. The time of each hint is kept in
  *    `~/.code-forge/logs/hints.json` (`{"<fp>": "<ISO time>"}`, 0600, older ones dropped).
  * Never throws; a broken state file only means the hint may show again.
@@ -40,7 +40,7 @@ function agentMode(env) {
 
 /**
  * @param {object} o
- * @param {{fp?: string}|null} o.entry - the entry the log just took (null: nothing was logged).
+ * @param {{fp?: string, kind?: string}|null} o.entry - the entry the log just took (null: nothing was logged).
  * @param {number} o.exit
  * @param {boolean} o.isTTY - whether stderr is a terminal.
  * @param {NodeJS.ProcessEnv} [o.env]
@@ -52,6 +52,7 @@ export async function maybeHint(o) {
   try {
     const env = o.env ?? process.env;
     const fp = o.entry?.fp;
+    if (o.entry?.kind === 'warning') return false;
     if (typeof fp !== 'string' || !FP.test(fp) || o.exit === 2 || o.isTTY !== true || agentMode(env)) return false;
     const file = hintStatePath(env.HOME);
     if (file === null) return false;

package/src/util/error-kind.mjs

@@ -8,8 +8,8 @@
 /** A kind is a short snake_case word; anything else is ignored. */
 const KIND = /^[a-z][a-z0-9_]{0,39}$/;
 
-/** Kinds the router sets itself; a verb reporting one of these is ignored. */
-const RESERVED = new Set(['crash', 'usage', 'error']);
+/** Kinds the router (and `logWarning`, B37) set themselves; a verb reporting one of these is ignored. */
+const RESERVED = new Set(['crash', 'usage', 'error', 'warning']);
 
 /** @type {string|null} */
 let current = null;

package/src/util/error-log.mjs

@@ -12,6 +12,12 @@
  *
  * Logging never throws and never changes the verb's exit code. `CODE_FORGE_NO_ERROR_LOG=1` turns
  * it off; no HOME means no log. The file is cut to its newest half when it grows over 1 MB.
+ *
+ * B37: every entry carries `before`, the names of up to 5 commands run before this one (oldest
+ * first; `util/breadcrumbs.mjs`, noted by the router through {@link noteVerb}), and
+ * {@link logWarning} writes a `kind: 'warning'` line for a recoverable problem (a 1Password call
+ * retried, a review session retried, System 1 falling back to rules, a budget warning) — the same
+ * scrub, cap and fingerprint, `warning` naming what happened, once per fingerprint per process.
  */
 
 import { createHash } from 'node:crypto';
@@ -19,6 +25,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { appendFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { SUBCOMMANDS, cleanList, currentCommand, noteCommand, previousCommands } from './breadcrumbs.mjs';
 import { redact } from './redact.mjs';
 
 export const ERROR_LOG_MAX_BYTES = 1024 * 1024;
@@ -29,22 +36,10 @@ export const NO_ERROR_LOG_ENV = 'CODE_FORGE_NO_ERROR_LOG';
 const PACKAGE_JSON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
 
 /**
- * The subcommand words each verb knows; the first positional is logged as `sub` only when it is
- * one of these (anything else could be a user value: a path, an id, a name).
- * @type {Readonly<Record<string, readonly string[]>>}
+ * The subcommand words each verb knows (kept in `breadcrumbs.mjs`, which needs the same table); the
+ * first positional is logged as `sub` only when it is one of these.
  */
-export const SUBCOMMANDS = Object.freeze({
-  block: ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'],
-  gates: ['detect', 'run', 'secret-scan', 'safe-edit', 'scope', 'acceptance', 'transcript-grep'],
-  jev: ['ask'],
-  keys: ['list', 'set', 'test', 'remove'],
-  ledger: ['calibration', 'outcome', 'tail'],
-  logs: ['summary', 'clear', 'path', 'report'],
-  plan: ['check'],
-  proof: ['tier', 'export', 'lock', 'unlock', 'restore', 'red-green'],
-  run: ['start', 'status', 'end'],
-  tools: ['install'],
-});
+export { SUBCOMMANDS };
 
 /**
  * The scrub rules, in the order a summary lists them. `label` is singular and plural.
@@ -84,6 +79,8 @@ export const SCRUB_PLACEHOLDERS = Object.freeze(['<project>', '<slug>', '<email>
  * @property {string|null} stack
  * @property {CleanCount[]} cleaned
  * @property {string} [fp] - the fingerprint (B28); entries written before B28 have none.
+ * @property {string[]} [before] - the commands run before this one, oldest first (B37).
+ * @property {string} [warning] - for `kind: 'warning'`: what happened (`op_retry`…) (B37).
  */
 
 /** @param {string} s */
@@ -353,6 +350,7 @@ export async function appendLine(file, line, maxBytes = ERROR_LOG_MAX_BYTES) {
  * @property {NodeJS.ProcessEnv} [env]
  * @property {string} [cwd]
  * @property {Date} [now]
+ * @property {string[]} [before] - the commands run before (default: the ones the router noted).
  */
 
 const KIND_WORD = /^[a-z][a-z0-9_]{0,39}$/;
@@ -394,12 +392,15 @@ export function normalizeMessage(message) {
 }
 
 /**
- * The first 12 hex characters of sha256(verb, sub, kind, normalized message) (B28).
- * @param {{verb: string, sub?: string|null, kind: string, message?: string|null}} e
+ * The first 12 hex characters of sha256(verb, sub, kind, normalized message) (B28); a warning
+ * (B37) adds what happened, so two warnings with the same text stay apart.
+ * @param {{verb: string, sub?: string|null, kind: string, message?: string|null, warning?: string}} e
  * @returns {string}
  */
 export function fingerprint(e) {
-  const text = [e.verb, e.sub ?? '', e.kind, normalizeMessage(e.message)].join('\n');
+  const parts = [e.verb, e.sub ?? '', e.kind, normalizeMessage(e.message)];
+  if (typeof e.warning === 'string') parts.push(e.warning);
+  const text = parts.join('\n');
   return createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 12);
 }
 
@@ -455,9 +456,99 @@ export async function buildEntry(input) {
     stack,
     cleaned: scrubber.counts(),
     fp: fingerprint({ verb: verbName, sub, kind, message }),
+    before: cleanList(input.before ?? previousCommands()),
   };
 }
 
+/**
+ * Note the command this process runs (the router, once, before the verb): its name and known
+ * subcommand word go to the breadcrumb file — never a flag or a value. Async: always a Promise,
+ * which never rejects.
+ * @param {string} verb @param {string[]} args @param {NodeJS.ProcessEnv} [env]
+ * @returns {Promise<boolean>} whether the breadcrumb file was written.
+ */
+export async function noteVerb(verb, args, env = process.env) {
+  try {
+    return await noteCommand({ verb, sub: subcommandOf(verb, args), env });
+  } catch {
+    return false;
+  }
+}
+
+/** Fingerprints of the warnings this process already logged (one line each per process). */
+const warned = new Set();
+
+/** Forget which warnings were logged (tests). */
+export function resetWarnings() {
+  warned.clear();
+}
+
+/**
+ * @typedef {object} WarningInput
+ * @property {string} [verb] - default: the command the router noted, else `unknown`.
+ * @property {string} warning - what happened: a short snake_case word (`op_retry`); else `warning`.
+ * @property {string} message - plain text; never a value (it is cleaned and capped anyway).
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {string} [cwd]
+ * @property {Date} [now]
+ */
+
+/**
+ * Log one recoverable problem as a `kind: 'warning'` line (B37): the same cleaning, 2 KB cap and
+ * fingerprint as an error, `exit: 0`, no flags, no stack, `warning` naming what happened. The same
+ * warning (fingerprint) is written once per process (remembered only after the line was
+ * appended). Never throws or rejects; never shows a hint.
+ * @param {WarningInput} input
+ * @returns {Promise<ErrorEntry|null>} the entry written, or null (logging off, no HOME, a repeat, an error).
+ */
+export async function logWarning(input) {
+  try {
+    const env = input?.env ?? process.env;
+    if (loggingOff(env)) return null;
+    const file = errorLogPath(env.HOME);
+    if (file === null) return null;
+    const cwd = input.cwd ?? process.cwd();
+    const scrubber = createScrubber({ home: env.HOME ?? null, cwd, slug: await readProjectSlug(cwd) });
+    const clean = (/** @type {string} */ s) => scrubber.scrub(redact(s));
+    const noted = currentCommand();
+    const verbName = typeof input.verb === 'string' && input.verb.length > 0 ? clean(input.verb) : noted?.verb ?? 'unknown';
+    const sub = typeof input.verb === 'string' && input.verb.length > 0 && input.verb !== noted?.verb ? null : noted?.sub ?? null;
+    const warning = typeof input?.warning === 'string' && KIND_WORD.test(input.warning) ? input.warning : 'warning';
+    const message = capBytes(clean(safeString(() => input.message).trim()), MESSAGE_MAX_BYTES);
+    const fp = fingerprint({ verb: verbName, sub, kind: 'warning', message, warning });
+    if (warned.has(fp)) return null;
+    /** @type {ErrorEntry} */
+    const entry = {
+      ts: (input.now ?? new Date()).toISOString(),
+      version: packageVersion(),
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      verb: verbName,
+      sub,
+      flags: [],
+      exit: 0,
+      kind: 'warning',
+      warning,
+      message,
+      stack: null,
+      cleaned: scrubber.counts(),
+      fp,
+      before: cleanList(previousCommands()),
+    };
+    await appendLine(file, JSON.stringify(entry));
+    warned.add(fp); // only after the line is written: a failed write may be retried later
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {{kind?: unknown}|null|undefined} e @returns {boolean} whether a log entry is a warning (B37). */
+export function isWarning(e) {
+  return e?.kind === 'warning';
+}
+
 /**
  * Log one failed verb. Never throws; returns the entry written, or null when nothing was written
  * (exit 0, logging off, no HOME, or a write error).

package/src/util/forbidden.mjs

@@ -256,8 +256,10 @@ export const FORBIDDEN = Object.freeze(
         ['forge', 'worker'],
         ['code-forge', 'run', 'start'],
         ['forge', 'run', 'start'],
+        ['code-forge', 'run', 'reload'],
+        ['forge', 'run', 'reload'],
       ],
-      description: 'Start a worker or a run (forge worker / code-forge worker / run start) from a coder — the orchestrator only',
+      description: 'Start a worker or a run, or reload its config (forge worker / code-forge worker / run start / run reload) from a coder — the orchestrator only',
     },
     {
       id: 'code-forge-reviews-write',

package/src/util/known-fixes.json

@@ -0,0 +1 @@
+[]

package/src/util/known-fixes.mjs

@@ -0,0 +1,153 @@
+/**
+ * Known fixes (B38): a small table shipped in the package, `src/util/known-fixes.json`, that maps
+ * an error fingerprint (`util/error-log.mjs` `fingerprint`) to the version that fixed it.
+ *
+ *   [{ "fp": "<12 hex>", "fixed_in": "x.y.z", "summary": "<one plain line>", "issue": <number|null> }]
+ *
+ * `code-forge logs` marks a known-fixed line `[fixed in x.y.z]`; `logs report` does not file an
+ * error that is fixed in a newer version than the one running (unless `--force`) and notes a
+ * possible regression when the running version already has the fix. The maintainer adds entries
+ * with `npm run known-fix -- add …` (`scripts/known-fix.mjs`, which uses {@link validateKnownFixes});
+ * `.github/workflows/error-triage.yml` reads the same file to comment on new error reports.
+ *
+ * Reading never throws: a missing or unreadable table is empty, and an entry that does not
+ * validate is left out (a broken table must never hide a report).
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The shipped table. */
+export const KNOWN_FIXES_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'known-fixes.json');
+
+/** A summary longer than this is refused (it is one plain line). */
+export const SUMMARY_MAX_CHARS = 200;
+
+const FP_RE = /^[0-9a-f]{12}$/;
+const VERSION_RE = /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/;
+const KEYS = Object.freeze(['fp', 'fixed_in', 'summary', 'issue']);
+
+/** @typedef {{fp: string, fixed_in: string, summary: string, issue: number|null}} KnownFix */
+
+/**
+ * Compare two semver versions: `x.y.z`, then a pre-release is older than its release
+ * (`1.2.0-beta.1` < `1.2.0`) and pre-releases compare part by part (numbers as numbers, numbers
+ * before words). Build metadata (`+…`) is ignored.
+ * @param {string} a @param {string} b
+ * @returns {number|null} >0 when a is newer, <0 when older, 0 when equal; null when unreadable.
+ */
+export function compareVersions(a, b) {
+  const re = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+  const pa = typeof a === 'string' ? re.exec(a.trim()) : null;
+  const pb = typeof b === 'string' ? re.exec(b.trim()) : null;
+  if (!pa || !pb) return null;
+  for (let i = 1; i <= 3; i += 1) {
+    const d = Number(pa[i]) - Number(pb[i]);
+    if (d !== 0) return d;
+  }
+  if (pa[4] === undefined || pb[4] === undefined) return pa[4] === pb[4] ? 0 : pa[4] === undefined ? 1 : -1;
+  const xa = pa[4].split('.');
+  const xb = pb[4].split('.');
+  for (let i = 0; i < Math.max(xa.length, xb.length); i += 1) {
+    if (xa[i] === undefined) return -1;
+    if (xb[i] === undefined) return 1;
+    const na = /^\d+$/.test(xa[i]);
+    const nb = /^\d+$/.test(xb[i]);
+    if (na && nb) {
+      const d = Number(xa[i]) - Number(xb[i]);
+      if (d !== 0) return d;
+    } else if (na !== nb) {
+      return na ? -1 : 1;
+    } else if (xa[i] !== xb[i]) {
+      return xa[i] < xb[i] ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * The problems of one entry, each naming the key only (never its value).
+ * @param {unknown} e
+ * @returns {string[]} empty when the entry is valid.
+ */
+export function entryProblems(e) {
+  if (e === null || typeof e !== 'object' || Array.isArray(e)) return ['not an object'];
+  const o = /** @type {Record<string, unknown>} */ (e);
+  const problems = [];
+  for (const k of Object.keys(o)) if (!KEYS.includes(k)) problems.push(`unknown key ${JSON.stringify(k)}`);
+  if (typeof o.fp !== 'string' || !FP_RE.test(o.fp)) problems.push('fp must be 12 lowercase hex characters');
+  if (typeof o.fixed_in !== 'string' || !VERSION_RE.test(o.fixed_in)) problems.push('fixed_in must be a version x.y.z');
+  if (typeof o.summary !== 'string' || o.summary.trim().length === 0) problems.push('summary must be a non-empty string');
+  else if (o.summary !== o.summary.trim() || /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/.test(o.summary)) problems.push('summary must be one plain line (no line breaks, tabs, control or text-direction characters, or leading/trailing spaces)');
+  else if ([...o.summary].length > SUMMARY_MAX_CHARS) problems.push(`summary must be at most ${SUMMARY_MAX_CHARS} characters`);
+  if (!Object.hasOwn(o, 'issue') || !(o.issue === null || (Number.isSafeInteger(o.issue) && /** @type {number} */ (o.issue) > 0))) {
+    problems.push('issue must be a positive issue number or null');
+  }
+  return problems;
+}
+
+/**
+ * Validate a whole table: an array of valid entries, each fingerprint once.
+ * @param {unknown} data
+ * @returns {string[]} the problems (`entry 2: fp must be …`); empty when the table is valid.
+ */
+export function validateKnownFixes(data) {
+  if (!Array.isArray(data)) return ['the table must be a JSON array'];
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  data.forEach((e, i) => {
+    for (const p of entryProblems(e)) problems.push(`entry ${i + 1}: ${p}`);
+    const fp = /** @type {any} */ (e)?.fp;
+    if (typeof fp === 'string' && FP_RE.test(fp)) {
+      if (seen.has(fp)) problems.push(`entry ${i + 1}: fp is already listed in entry ${seen.get(fp)}`);
+      else seen.set(fp, i + 1);
+    }
+  });
+  return problems;
+}
+
+/**
+ * The valid entries of the table at `file`, by fingerprint (first one wins). Never throws.
+ * @param {string} [file]
+ * @returns {Map<string, KnownFix>}
+ */
+export function loadKnownFixes(file = KNOWN_FIXES_FILE) {
+  let data;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return new Map();
+  }
+  return knownFixMap(data);
+}
+
+/**
+ * The valid entries of `data`, by fingerprint (first one wins); anything else is left out.
+ * @param {unknown} data
+ * @returns {Map<string, KnownFix>}
+ */
+export function knownFixMap(data) {
+  /** @type {Map<string, KnownFix>} */
+  const out = new Map();
+  if (!Array.isArray(data)) return out;
+  for (const e of data) {
+    if (entryProblems(e).length > 0 || out.has(e.fp)) continue;
+    out.set(e.fp, { fp: e.fp, fixed_in: e.fixed_in, summary: e.summary, issue: e.issue });
+  }
+  return out;
+}
+
+/**
+ * How a known fix relates to the running version: `older` (the fix is in a newer version than the
+ * one running), `has-fix` (the running version is the fixed one or newer: a possible regression),
+ * or `unknown` (the running version cannot be read).
+ * @param {KnownFix} fix @param {string} running
+ * @returns {'older'|'has-fix'|'unknown'}
+ */
+export function fixStatus(fix, running) {
+  const c = compareVersions(running, fix.fixed_in);
+  if (c === null) return 'unknown';
+  return c < 0 ? 'older' : 'has-fix';
+}

package/src/worker/engine.mjs

@@ -36,6 +36,7 @@
 
 import { rmSync } from 'node:fs';
 import path from 'node:path';
+import { blockKind } from '../decide/escalation.mjs';
 import { askJev } from '../decide/jev-client.mjs';
 import { planAndRecord, tierOf } from '../review/budget.mjs';
 import { budgetFor } from '../review/packet.mjs';
@@ -89,14 +90,17 @@ import { assertTicketId } from './ticket.mjs';
  * `block-unknown`; a record that cannot be read or parsed throws `run-record-unreadable`, and a
  * block entry without a base `block-base-missing` — a guessed base could let a change escape review.
  * @param {string} runId @param {string} block
- * @returns {Promise<{base: string | null, level: string, owned: string[], acceptance?: unknown}>}
+ * The block's kind (B34) is the recorded `kind` when `block open` stored one, else `blockKind`
+ * of its owned files.
+ *   With no run record the kind is null: `reviewTicket` takes the ticket file's kind.
+ * @returns {Promise<{base: string | null, level: string, owned: string[], acceptance?: unknown, kind: string | null}>}
  */
 export async function blockEntryFor(runId, block) {
   let record;
   try {
     record = await readRun(runId);
   } catch (err) {
-    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], acceptance: undefined };
+    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], acceptance: undefined, kind: null };
     throw new Error('run-record-unreadable');
   }
   if (!record || typeof record !== 'object' || !record.blocks || typeof record.blocks !== 'object') throw new Error('run-record-unreadable');
@@ -105,7 +109,7 @@ export async function blockEntryFor(runId, block) {
   const sha = entry?.base_sha;
   if (typeof sha !== 'string' || sha.length === 0) throw new Error('block-base-missing');
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files.filter((f) => typeof f === 'string') : [];
-  return { base: sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, acceptance: entry.acceptance };
+  return { base: sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, acceptance: entry.acceptance, kind: blockKind({ owned, declared: entry.kind }) };
 }
 
 /** The acceptance line written when the block's clauses cannot be read. */
@@ -189,14 +193,15 @@ export async function reviewTicket(ticket, ctx) {
   } catch (err) {
     return { status: 'unavailable', reason: err instanceof Error ? err.message : 'run-record-unreadable', approved: false, engine: 'adaptive', sessions: [] };
   }
+  if (entry.kind === null) entry = { ...entry, kind: blockKind({ owned: [ticket.file] }) };
   try {
     if (!ctx.key) {
       return await reviewFile(
-        { repoRoot: ctx.repoRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) },
+        { repoRoot: ctx.repoRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, kind: entry.kind, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) },
         { spawn: ctx.spawn, ...(ctx.writeRow ? { writeRow: ctx.writeRow } : {}) },
       );
     }
-    return await fixLoopRound(ticket, ctx, { base: entry.base, level: entry.level, owned: entry.owned, key: ctx.key, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) });
+    return await fixLoopRound(ticket, ctx, { base: entry.base, level: entry.level, owned: entry.owned, blockKindOf: entry.kind, key: ctx.key, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) });
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -205,10 +210,10 @@ export async function reviewTicket(ticket, ctx) {
 /**
  * One fix-loop round for the ticket (see the module doc).
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{base: string | null, level: string, owned: string[], key: Buffer, workDir: string, factsExcerpt: string}} opts
+ * @param {{base: string | null, level: string, owned: string[], blockKindOf: string, key: Buffer, workDir: string, factsExcerpt: string}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function fixLoopRound(ticket, ctx, { base, level, owned, key, workDir, factsExcerpt }) {
+async function fixLoopRound(ticket, ctx, { base, level, owned, blockKindOf, key, workDir, factsExcerpt }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
   let rows;
   try {
@@ -276,7 +281,7 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, key, workDir, fac
         factsExcerpt,
         ...(jev ? { jev } : {}),
         review: async () => {
-          engineOutcome = await reviewFile({ repoRoot: ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, workDir, factsExcerpt }, { spawn: ctx.spawn, writeRow });
+          engineOutcome = await reviewFile({ repoRoot: ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, kind: blockKindOf, workDir, factsExcerpt }, { spawn: ctx.spawn, writeRow });
           return engineOutcome;
         },
         spawn: async (opts) => {