@codedology/code-forge 0.3.2 → 0.5.0

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

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 @@
+[]