@codedology/code-forge 0.3.2 → 0.4.0

package/src/cli/ledger.mjs

@@ -6,13 +6,20 @@
  *   ledger calibration --slug <slug> [--question <id>]
  *   ledger outcome --scan-git --slug <slug> [--cwd <dir>] [--days <n>]
  *   ledger outcome --pr <n> --ci red|green|reverted --slug <slug>
- *   ledger tail --slug <slug> [--n <count>]
+ *   ledger tail --slug <slug> [--n <count> | -n <count>]
+ *   ledger add coder --run <r> --block <b> --usd <n> [--note "..."]
+ *
+ * B33: `ledger add coder` records manual/cloud coder spend (a session code-forge never saw) as a
+ * signed `session` row (`role: coder, manual: true, usd, cost_source: manual`) in the run's
+ * ledger, so `report` and the `budget.usd` check count it. The slug is the run record's project.
  */
 
 import { writeSafe } from '../util/redact.mjs';
 import { buildCalibration } from '../ledger/calibration.mjs';
 import { recordCiOutcome, reviewedEntriesFromRows, scanGitAndRecord } from '../ledger/outcome.mjs';
-import { readAllRows } from '../ledger/write.mjs';
+import { roundUsd, runSpend } from '../ledger/spend.mjs';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
+import { readRun, writeSigned } from '../state/run.mjs';
 
 /**
  * @param {string[]} args @param {string} flag
@@ -56,9 +63,10 @@ export async function runLedger(args, deps = {}) {
   const { stdout = process.stdout, stderr = process.stderr } = deps;
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
-  const usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]\n');
+  const usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]  (tail: [--n|-n <count>]) | add coder --run <r> --block <b> --usd <n> [--note "..."]\n');
 
   const [sub] = args;
+  if (sub === 'add') return addSpend(args.slice(1), { out, err });
   const slug = flagValue(args, '--slug');
   if (!slug) {
     usage();
@@ -126,15 +134,22 @@ export async function runLedger(args, deps = {}) {
     }
 
     if (sub === 'tail') {
-      const nFlag = readOptionalFlag(args, '--n');
-      if (!nFlag.ok) {
-        err('ledger tail: --n requires a value\n');
+      // `-n` is the spelling everyone types from `tail(1)`; before B31 it was not recognised, so
+      // `ledger tail -n 3` silently printed the default 20 rows (issue #2, field note 8).
+      const longN = readOptionalFlag(args, '--n');
+      const shortN = readOptionalFlag(args, '-n');
+      if (!longN.ok || !shortN.ok) {
+        err(`ledger tail: ${longN.ok ? '-n' : '--n'} requires a value\n`);
+        return 2;
+      }
+      if (longN.value !== undefined && shortN.value !== undefined) {
+        err('ledger tail: give the count once, as --n <count> or -n <count>\n');
         return 2;
       }
-      const nArg = nFlag.value ?? '20';
+      const nArg = longN.value ?? shortN.value ?? '20';
       const n = parseNonNegativeInt(nArg);
       if (n === null) {
-        err(`ledger tail: --n must be a non-negative integer, got "${nArg}"\n`);
+        err(`ledger tail: --n/-n must be a non-negative integer, got "${nArg}"\n`);
         return 2;
       }
       const rows = await readAllRows(slug);
@@ -154,6 +169,82 @@ export async function runLedger(args, deps = {}) {
   return 2;
 }
 
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_NOTE_CHARS = 500;
+
+/**
+ * `ledger add coder --run <r> --block <b> --usd <n> [--note "..."]` (B33).
+ * @param {string[]} args - after `add`.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io
+ * @returns {Promise<number>}
+ */
+async function addSpend(args, { out, err }) {
+  const usage = () => err('usage: code-forge ledger add coder --run <r> --block <b> --usd <n> [--note "..."]\n');
+  const [role] = args;
+  const run = flagValue(args, '--run');
+  const block = flagValue(args, '--block');
+  const usdArg = flagValue(args, '--usd');
+  if (role !== 'coder' || !run || !block || usdArg === undefined) {
+    usage();
+    return 2;
+  }
+  const note = readOptionalFlag(args, '--note');
+  if (!note.ok) {
+    err('ledger add: --note requires a value\n');
+    return 2;
+  }
+  if (!ID.test(run)) {
+    err('ledger add: --run must be a run id (letters, digits, ".", "_", "-")\n');
+    return 2;
+  }
+  if (!ID.test(block)) {
+    err('ledger add: --block must be a block id (letters, digits, ".", "_", "-")\n');
+    return 2;
+  }
+  // rounded to the ledger's 4 decimals FIRST, then checked: 0.00001 rounds to 0 and is refused
+  const usd = /^\d+(\.\d+)?$/.test(usdArg) ? roundUsd(Number(usdArg)) : Number.NaN;
+  if (!Number.isFinite(usd) || usd <= 0) {
+    err(`ledger add: --usd must be a number > 0 (at 4 decimals), got "${usdArg}"\n`);
+    return 2;
+  }
+  if (note.value !== undefined && note.value.length > MAX_NOTE_CHARS) {
+    err(`ledger add: --note is longer than ${MAX_NOTE_CHARS} characters\n`);
+    return 2;
+  }
+  try {
+    const { project } = await readRun(run);
+    const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: project });
+    const row = {
+      event: 'session',
+      role: 'coder',
+      manual: true,
+      block,
+      provider: null,
+      level: null,
+      tokens_in: null,
+      tokens_out: null,
+      usd,
+      cost_source: 'manual',
+      ...(note.value !== undefined ? { note: note.value } : {}),
+    };
+    await writeSigned(run, writeRow, row);
+    // the row is written: from here on nothing may throw or change the exit code
+    /** @type {number | null} */
+    let total = null;
+    try {
+      const spent = runSpend(await readAllRows(project), run).usd;
+      total = Number.isFinite(spent) ? spent : null;
+    } catch {
+      total = null;
+    }
+    out(`recorded coder spend $${usd.toFixed(4)} for run ${run} block ${block} · run total ${total === null ? 'unknown' : `$${total.toFixed(4)}`}\n`);
+    return 0;
+  } catch (thrown) {
+    err(`ledger add: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function ledger(args) {
   return runLedger(args);

package/src/cli/logs.mjs

@@ -6,7 +6,19 @@
  *   logs summary [--days N] [--json]  one row per fingerprint over the last N days (default 30): "seen N times"
  *   logs clear [--yes]                delete the log after one yes
  *   logs path                         print the log path
- *   logs report [--last N] [--kind K] [--verb V] [--note "text"] [--no-ai] [--allow-old] [--dry-run] [--yes]
+ *   logs report [--last N] [--kind K] [--verb V] [--note "text"] [--include-warnings] [--with-doctor] [--no-ai] [--allow-old] [--force] [--dry-run] [--yes]
+ *
+ * B38: known fixes (`util/known-fixes.mjs`, the shipped `known-fixes.json`). `logs` marks a
+ * known-fixed line `[fixed in x.y.z]`. `report`, before anything else (no npm, no AI, nothing
+ * built): a selected error whose fix shipped in a newer version than the one running is printed
+ * with the upgrade command and left out of the report — none left is exit 0 — unless `--force`;
+ * when the running version already has the fix, the report notes a possible regression.
+ *
+ * B37: warnings (`kind: 'warning'`, recoverable problems) are listed marked `[warning]`, counted
+ * apart in `summary`, and reported only with `--include-warnings`. Each reported error names the
+ * commands run before it (`before`, names only). `--with-doctor` adds a "Setup check" section:
+ * `code-forge doctor --json` run as a child (60 s at most, error logging off), each row's id,
+ * status and a short detail only, cleaned like the rest; a doctor that cannot run is a note.
  *
  * `report` (B28 order): a version check (`npm view`; an old version is warned and asked about,
  * default no, `--yes` included; without a terminal it stops unless `--allow-old`) → the
@@ -27,8 +39,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { exec as realExec } from '../util/exec.mjs';
-import { capBytes, createScrubber, describeCounts, errorLogPath, fingerprintOf, mergeCounts, packageVersion, readErrorLog, readProjectSlug } from '../util/error-log.mjs';
-import { writeSafe } from '../util/redact.mjs';
+import { NO_ERROR_LOG_ENV, capBytes, createScrubber, describeCounts, errorLogPath, fingerprintOf, isWarning, mergeCounts, packageVersion, readErrorLog, readProjectSlug } from '../util/error-log.mjs';
+import { compareVersions, fixStatus, loadKnownFixes } from '../util/known-fixes.mjs';
+import { redact, writeSafe } from '../util/redact.mjs';
 import { currentRunRoot } from '../util/tmp.mjs';
 import { SECRET_LOOKING_PATTERNS } from '../config/secret-patterns.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
@@ -36,22 +49,48 @@ import { AI_REPORT_MAX_BYTES, applyItems, describeAiCounts, runAiScrub } from '.
 
 const USAGE =
   'usage: code-forge logs [--last N] [--json] | logs summary [--days N] [--json] | logs clear [--yes] | logs path\n' +
-  '       code-forge logs report [--last N] [--kind K] [--verb V] [--note "text"] [--no-ai] [--allow-old] [--dry-run] [--yes]\n';
+  '       code-forge logs report [--last N] [--kind K] [--verb V] [--note "text"] [--include-warnings] [--with-doctor] [--no-ai] [--allow-old] [--force] [--dry-run] [--yes]\n';
 
 const PACKAGE_JSON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
 
 /** A prefilled issue link longer than this is cut (browsers and GitHub refuse very long URLs). */
 export const MAX_URL_LENGTH = 7500;
 
-/** Printed before every report preview. */
-export const DISCLOSURE =
-  'What you will share (public on GitHub): code-forge, Node and OS versions; command names and flag NAMES; exit codes; error types; error messages and crash reports after cleaning.\n' +
-  'Never shared: flag values, file contents, your code, keys or tokens, your home folder, project folder or project name.\n';
+/**
+ * Printed before every report preview: every kind of data the report holds.
+ * @param {{warnings?: boolean, doctor?: boolean}} [o] - whether the report holds warnings / setup check results.
+ * @returns {string}
+ */
+export function disclosure({ warnings = false, doctor = false } = {}) {
+  const shared = [
+    'code-forge, Node and OS versions',
+    'command names and flag NAMES',
+    'the names of the last commands you ran (no flags or values)',
+    'exit codes',
+    'error types',
+    'error messages and crash reports after cleaning',
+    ...(warnings ? ['warnings (problems code-forge recovered from) after cleaning'] : []),
+    ...(doctor ? ["the setup check results (each check's name, status and a short detail, after cleaning)"] : []),
+  ];
+  return (
+    `What you will share (public on GitHub): ${shared.join('; ')}.\n` +
+    'Never shared: flag values, file contents, your code, keys or tokens, your home folder, project folder or project name.\n'
+  );
+}
+
+/** The disclosure of a report with errors only. */
+export const DISCLOSURE = disclosure();
 
 export const CONFIRM_MESSAGE = 'This will be public on GitHub. Send it?';
 
 const GH_TIMEOUT_MS = 60_000;
 const NPM_TIMEOUT_MS = 10_000;
+/** `code-forge doctor --json` for `--with-doctor` gets at most this long. */
+export const DOCTOR_TIMEOUT_MS = 60_000;
+/** A setup check row's detail is cut to this many bytes. */
+export const DOCTOR_DETAIL_MAX_BYTES = 120;
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'code-forge.mjs');
 
 /** The npm package a version check looks up. */
 export const PACKAGE_NAME = '@codedology/code-forge';
@@ -72,6 +111,8 @@ export const PACKAGE_NAME = '@codedology/code-forge';
  * @property {() => Date} [now]
  * @property {any} [pkg] - the package.json object the issue repository is read from (default: this package's).
  * @property {{version: string, node: string, os: string}} [system] - the versions a report names.
+ * @property {Map<string, import('../util/known-fixes.mjs').KnownFix>} [knownFixes] - the known-fix table
+ *   by fingerprint (default: the shipped `util/known-fixes.json`).
  * @property {(argv: string[], env: NodeJS.ProcessEnv) => Promise<{code: number|null, error?: string}>} [runEditor] - runs
  *   the editor on the terminal (default: argv only, stdio inherited, never a shell).
  */
@@ -196,13 +237,17 @@ function fenced(text) {
 /**
  * The issue title and Markdown body for `entries` (newest first), with the sections of the issue
  * form (`.github/ISSUE_TEMPLATE/error-report.yml`): what you were doing, versions, error details.
- * The fingerprint section is {@link reportFooter}, added after cleaning.
+ * The fingerprint section is {@link reportFooter}, added after cleaning. With `setup` (B37) a
+ * "Setup check" section follows the error details: the rows, or why the check could not run.
  * @param {ErrorEntry[]} entries
  * @param {{version: string, node: string, os: string, latest?: string|null}} system
  * @param {string|null} note
+ * @param {SetupCheck|null} [setup]
+ * @param {Map<string, string>} [fixNotes] - by fingerprint: a line added to that error's section
+ *   (B38: a known fix; see {@link fixNote}).
  * @returns {{title: string, body: string, fps: string[]}} `fps`: distinct fingerprints, newest first.
  */
-export function buildReport(entries, system, note) {
+export function buildReport(entries, system, note, setup = null, fixNotes = new Map()) {
   const pairs = new Set(entries.map((e) => `${e.verb}\u0000${e.kind}`));
   const title = pairs.size === 1 ? `[error report] ${entries[0].verb} ${entries[0].kind}` : `[error report] ${entries.length} errors`;
   const fps = entries.map(fingerprintOf);
@@ -233,10 +278,13 @@ export function buildReport(entries, system, note) {
       '',
       `- when: ${e.ts}`,
       `- flags: ${Array.isArray(e.flags) && e.flags.length > 0 ? e.flags.map((f) => `\`${f}\``).join(' ') : 'none'}`,
+      ...(Array.isArray(e.before) ? [`- commands before (oldest first): ${e.before.length > 0 ? e.before.map((c) => `\`${c}\``).join(', ') : 'none'}`] : []),
       `- exit: ${e.exit}`,
       `- kind: ${e.kind}`,
+      ...(isWarning(e) && typeof e.warning === 'string' ? [`- warning: ${e.warning}`] : []),
       `- fingerprint: ${fps[i]}`,
       `- code-forge ${e.version}, Node ${e.node}, ${e.platform} ${e.arch}`,
+      ...(fixNotes.has(fps[i]) ? ['', /** @type {string} */ (fixNotes.get(fps[i]))] : []),
       '',
       'message:',
       '',
@@ -244,9 +292,58 @@ export function buildReport(entries, system, note) {
     );
     if (e.stack) out.push('', 'stack:', '', fenced(e.stack));
   });
+  if (setup !== null) {
+    out.push('', '### Setup check', '');
+    if ('why' in setup) {
+      out.push(`(the setup check could not run: ${setup.why})`);
+    } else {
+      out.push('| check | status | detail |', '|---|---|---|');
+      for (const r of setup.rows) out.push(`| ${cell(r.id)} | ${cell(r.status)} | ${cell(r.detail)} |`);
+    }
+  }
   return { title, body: `${out.join('\n')}\n`, fps: [...new Set(fps)] };
 }
 
+/** @typedef {{rows: Array<{id: string, status: string, detail: string}>} | {why: string}} SetupCheck */
+
+/** The statuses a doctor row may have. */
+const DOCTOR_STATUSES = new Set(['OK', 'WARN', 'FAIL', 'INFO']);
+
+/**
+ * Run `code-forge doctor --json` as a child (argv only, 60 s at most, with error logging off so
+ * the check adds no log line or breadcrumb) and keep only each row's `id`, `status` and the first
+ * line of its `detail`, redacted, cleaned by `scrub` and then cut to {@link DOCTOR_DETAIL_MAX_BYTES}
+ * — never its label or anything else. A doctor that finds a FAIL exits 1 and still prints its rows; no rows at all is
+ * `{why}` (`timed out`, `doctor exit n`, `doctor gave no result`, `doctor did not run`).
+ * @param {typeof realExec} exec @param {NodeJS.ProcessEnv} env @param {string} cwd
+ * @param {(text: string) => string} scrub - the report's deterministic scrub.
+ * @returns {Promise<SetupCheck>}
+ */
+export async function runSetupCheck(exec, env, cwd, scrub) {
+  let res;
+  try {
+    res = await exec([process.execPath, BIN, 'doctor', '--json'], { cwd, env: { ...env, [NO_ERROR_LOG_ENV]: '1' }, timeoutMs: DOCTOR_TIMEOUT_MS });
+  } catch {
+    return { why: 'doctor did not run' };
+  }
+  if (res.timedOut) return { why: 'timed out' };
+  let doc;
+  try {
+    doc = JSON.parse(res.stdout);
+  } catch {
+    doc = null;
+  }
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.rows)) {
+    return { why: res.code === null ? 'doctor did not run' : res.code === 0 ? 'doctor gave no result' : `doctor exit ${res.code}` };
+  }
+  const rows = [];
+  for (const r of doc.rows) {
+    if (typeof r?.id !== 'string' || !/^[A-Za-z0-9_.:-]{1,64}$/.test(r.id) || !DOCTOR_STATUSES.has(r.status)) continue;
+    rows.push({ id: r.id, status: r.status, detail: capBytes(scrub(redact(firstLine(typeof r.detail === 'string' ? r.detail : ''))), DOCTOR_DETAIL_MAX_BYTES) });
+  }
+  return { rows };
+}
+
 /**
  * The last section of every report: `Fingerprint: <fp>` (the newest error's) and one hidden
  * `<!-- code-forge-fp: <fp> -->` line per distinct fingerprint, so a later report finds it.
@@ -276,41 +373,8 @@ export function capReport(title, body, maxBytes) {
   return { body: `${capBytes(body, Math.max(0, room))}${note}`, cut: true };
 }
 
-/**
- * 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 = re.exec(a.trim());
-  const pb = re.exec(b.trim());
-  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;
-}
+/** Re-exported: the version comparison lives in `util/known-fixes.mjs` (B38). */
+export { compareVersions };
 
 /** @returns {{version: string, node: string, os: string}} */
 function currentSystem() {
@@ -336,7 +400,7 @@ export async function runLogs(args, deps = {}) {
     summary: { values: ['days'], booleans: ['json'] },
     clear: { booleans: ['yes'] },
     path: {},
-    report: { values: ['last', 'kind', 'verb', 'note'], booleans: ['dry-run', 'yes', 'no-ai', 'allow-old'] },
+    report: { values: ['last', 'kind', 'verb', 'note'], booleans: ['dry-run', 'yes', 'no-ai', 'allow-old', 'include-warnings', 'with-doctor', 'force'] },
   });
   const name = sub ?? 'list';
   if (!Object.hasOwn(specs, name) || (name === 'list' && sub !== null)) {
@@ -367,7 +431,7 @@ export async function runLogs(args, deps = {}) {
   const entries = await readErrorLog(file);
   if (name === 'clear') return clear(file, entries, flags, deps, out, err);
   if (entries === null || entries.length === 0) {
-    out(flags.json ? `${JSON.stringify(name === 'summary' ? { days: n ?? 30, counts: [] } : { errors: [] })}\n` : 'no errors logged\n');
+    out(flags.json ? `${JSON.stringify(name === 'summary' ? { days: n ?? 30, counts: [], warnings: [] } : { errors: [] })}\n` : 'no errors logged\n');
     return 0;
   }
   const newest = [...entries].reverse();
@@ -375,7 +439,19 @@ export async function runLogs(args, deps = {}) {
   if (name === 'list') {
     const shown = newest.slice(0, n ?? 10);
     if (flags.json) out(`${JSON.stringify({ errors: shown })}\n`);
-    else for (const e of shown) out(`${e.ts}  ${command(e)}  ${e.exit}  ${e.kind}  ${fingerprintOf(e)}  ${firstLine(e.message)}\n`);
+    else {
+      const fixes = deps.knownFixes ?? loadKnownFixes();
+      for (const e of shown) {
+        const fp = fingerprintOf(e);
+        const fix = fixes.get(fp);
+        const fpCell = fix ? `${fp} [fixed in ${fix.fixed_in}]` : fp;
+        out(
+          isWarning(e)
+            ? `${e.ts}  [warning] ${command(e)}  ${typeof e.warning === 'string' ? e.warning : 'warning'}  ${fpCell}  ${firstLine(e.message)}\n`
+            : `${e.ts}  ${command(e)}  ${e.exit}  ${e.kind}  ${fpCell}  ${firstLine(e.message)}\n`,
+        );
+      }
+    }
     return 0;
   }
 
@@ -384,22 +460,38 @@ export async function runLogs(args, deps = {}) {
     const since = (deps.now ?? (() => new Date()))().getTime() - days * 86_400_000;
     /** @type {Map<string, {fp: string, verb: string, sub: string|null, kind: string, count: number}>} */
     const counts = new Map();
+    /** @type {Map<string, {fp: string, verb: string, sub: string|null, warning: string, count: number}>} */
+    const warns = new Map();
     for (const e of newest) {
       const t = Date.parse(e.ts);
       if (!(t >= since)) continue;
       const fp = fingerprintOf(e);
+      if (isWarning(e)) {
+        const w = warns.get(fp) ?? { fp, verb: e.verb, sub: e.sub ?? null, warning: typeof e.warning === 'string' ? e.warning : 'warning', count: 0 };
+        w.count += 1;
+        warns.set(fp, w);
+        continue;
+      }
       const c = counts.get(fp) ?? { fp, verb: e.verb, sub: e.sub ?? null, kind: e.kind, count: 0 };
       c.count += 1;
       counts.set(fp, c);
     }
     const rows = [...counts.values()].sort((a, b) => b.count - a.count || a.verb.localeCompare(b.verb) || a.kind.localeCompare(b.kind) || a.fp.localeCompare(b.fp));
+    const warnRows = [...warns.values()].sort((a, b) => b.count - a.count || a.verb.localeCompare(b.verb) || a.warning.localeCompare(b.warning) || a.fp.localeCompare(b.fp));
+    const times = (/** @type {number} */ c) => `seen ${c} ${c === 1 ? 'time' : 'times'}`;
     if (flags.json) {
-      out(`${JSON.stringify({ days, counts: rows })}\n`);
-    } else if (rows.length === 0) {
+      out(`${JSON.stringify({ days, counts: rows, warnings: warnRows })}\n`);
+      return 0;
+    }
+    if (rows.length === 0) {
       out(`no errors in the last ${days} days\n`);
     } else {
       out(`errors in the last ${days} days:\n`);
-      for (const r of rows) out(`${r.fp}  ${r.sub ? `${r.verb} ${r.sub}` : r.verb}  ${r.kind}  seen ${r.count} ${r.count === 1 ? 'time' : 'times'}\n`);
+      for (const r of rows) out(`${r.fp}  ${r.sub ? `${r.verb} ${r.sub}` : r.verb}  ${r.kind}  ${times(r.count)}\n`);
+    }
+    if (warnRows.length > 0) {
+      out(`warnings in the last ${days} days:\n`);
+      for (const r of warnRows) out(`${r.fp}  ${r.sub ? `${r.verb} ${r.sub}` : r.verb}  ${r.warning}  ${times(r.count)}\n`);
     }
     return 0;
   }
@@ -511,11 +603,45 @@ async function report(newest, last, flags, deps, out, err) {
   const home = env.HOME ?? '';
   const kind = typeof flags.kind === 'string' ? flags.kind : null;
   const verb = typeof flags.verb === 'string' ? flags.verb : null;
-  const selected = newest.filter((e) => (kind === null || e.kind === kind) && (verb === null || e.verb === verb)).slice(0, last);
-  if (selected.length === 0) {
+  // warnings only with --include-warnings (B37)
+  const withWarnings = flags['include-warnings'] === true;
+  const picked = newest.filter((e) => (withWarnings || !isWarning(e)) && (kind === null || e.kind === kind) && (verb === null || e.verb === verb)).slice(0, last);
+  if (picked.length === 0) {
     out('no matching errors to report\n');
     return 0;
   }
+  const system = deps.system ?? currentSystem();
+
+  // 0. known fixes (B38), before anything is asked or built: an error fixed in a newer version
+  // than the one running is left out (unless --force); one the running version already has the
+  // fix for gets a "may be a regression" note
+  const fixes = deps.knownFixes ?? loadKnownFixes();
+  /** @type {Map<string, string>} */
+  const fixNotes = new Map();
+  /** @type {Set<string>} */
+  const fixedAway = new Set();
+  for (const fp of new Set(picked.map(fingerprintOf))) {
+    const fix = fixes.get(fp);
+    if (!fix) continue;
+    const status = fixStatus(fix, system.version);
+    if (status === 'older') {
+      out(`This error is fixed in ${fix.fixed_in}: ${fix.summary.replace(/\.$/, '')}. Upgrade with: npm install -g ${PACKAGE_NAME}@latest\n`);
+      if (flags.force === true) {
+        out(`--force: reporting ${fp} anyway.\n`);
+        fixNotes.set(fp, `Note: a fix for this shipped in ${fix.fixed_in}; this report is from an older version (sent with --force).`);
+      } else {
+        fixedAway.add(fp);
+      }
+    } else if (status === 'has-fix') {
+      fixNotes.set(fp, `Note: a fix for this shipped in ${fix.fixed_in}; it may be a regression.`);
+    }
+  }
+  const selected = picked.filter((e) => !fixedAway.has(fingerprintOf(e)));
+  if (selected.length === 0) {
+    out('not filed: upgrade first (pass --force to report it anyway)\n');
+    return 0;
+  }
+  if (fixedAway.size > 0) out(`left out of the report (fixed in a newer version): ${[...fixedAway].join(', ')}\n`);
   const repo = issueRepo(deps.pkg);
   if (repo === null) {
     err('logs: package.json names no GitHub repository to report to\n');
@@ -525,7 +651,6 @@ async function report(newest, last, flags, deps, out, err) {
   const tty = deps.isTTY ?? process.stdin.isTTY === true;
   const dryRun = flags['dry-run'] === true;
   const yes = flags.yes === true;
-  const system = deps.system ?? currentSystem();
 
   // 1. version check: an old version gets a warning and a default-no question
   const npm = await latestOnNpm(exec, env);
@@ -548,17 +673,27 @@ async function report(newest, last, flags, deps, out, err) {
     }
   }
 
-  // 2. deterministic scrub, the 16 KB cap, the AI pass, the deterministic scrub again
   const cwd = deps.cwd ?? process.cwd();
   const scrubber = createScrubber({ home, cwd, slug: await readProjectSlug(cwd) });
+
+  // 1b. the setup check (--with-doctor, B37): a doctor that cannot run is a note, never a stop
+  /** @type {SetupCheck|null} */
+  let setup = null;
+  if (flags['with-doctor'] === true) {
+    setup = await runSetupCheck(exec, env, cwd, (t) => scrubber.scrub(t));
+    if ('why' in setup) out(`Could not run the setup check (${setup.why}); the report goes on without it.\n`);
+  }
+  const shared = disclosure({ warnings: selected.some(isWarning), doctor: setup !== null && 'rows' in setup });
+
+  // 2. deterministic scrub, the 16 KB cap, the AI pass, the deterministic scrub again
   const note = typeof flags.note === 'string' ? flags.note : null;
-  const built = buildReport(selected, { ...system, latest }, note);
+  const built = buildReport(selected, { ...system, latest }, note, setup, fixNotes);
   let title = scrubber.scrub(built.title);
   let body = capReport(title, scrubber.scrub(built.body), AI_REPORT_MAX_BYTES).body;
   const blocked = () => {
     const hit = findSecret(`${title}\n${body}`);
     if (hit === null) return false;
-    out(DISCLOSURE);
+    out(shared);
     err(`Possible secret found in the report (${hit.rule}, report line ${hit.line}; the title is line 1); not sent. Find it with code-forge logs --json and remove it with code-forge logs clear.\n`);
     return true;
   };
@@ -583,7 +718,7 @@ async function report(newest, last, flags, deps, out, err) {
 
   // 3. the final secret check, then what is shared and the full text
   if (blocked()) return 1;
-  out(DISCLOSURE);
+  out(shared);
   const aiLine =
     ai.status === 'ok'
       ? describeAiCounts(ai.counts)

package/src/cli/plan.mjs

@@ -1,7 +1,11 @@
 /**
- * `code-forge plan check <plan-file> [--facts <sheet>]` (plan §3.8 rule 4, §3.2; block B9b) —
- * the deterministic harden exit. Prints every failing row on stderr, one per line, and exits 1
- * when there is any; prints `plan check: ok (<n> blocks)` and exits 0 otherwise; 2 on usage.
+ * `code-forge plan check <plan-file> [--facts <sheet>] [--slug <slug>]` (plan §3.8 rule 4, §3.2;
+ * block B9b) — the deterministic harden exit. Prints every failing row on stderr, one per line, and
+ * exits 1 when there is any; prints `plan check: ok (<n> blocks)` and exits 0 otherwise; 2 on usage.
+ * WARN lines (a required section found by its position under a near-miss heading) go to stderr and
+ * never fail the check. Either way stdout ends with the lane recorded per block (B36):
+ * `lanes: B1 L1 (jev) · B2 none` — read from the project's ledger (`--slug`, else `project.slug`,
+ * else the directory-name slug `run`, `author` and `jev ask` use).
  * Limits come from `.code-forge.yml` when there is one (`caps.coders`, `budget.block_cases`,
  * `budget.block_lines`), else the plan defaults.
  */
@@ -9,12 +13,15 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { loadProjectConfig } from '../config/load.mjs';
+import { ledgerPath } from '../ledger/paths.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { checkPlan } from '../session/plan-check.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
 import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
 
-const USAGE = 'usage: code-forge plan check <plan-file> [--facts <sheet>]\n';
+const USAGE = 'usage: code-forge plan check <plan-file> [--facts <sheet>] [--slug <slug>]\n';
 
 /**
  * @param {string[]} args
@@ -26,7 +33,7 @@ export async function runPlanVerb(args, deps = {}) {
   const stderr = deps.stderr ?? process.stderr;
   const cwd = deps.cwd ?? process.cwd();
   try {
-    const { flags, positionals } = parseFlags(args, { values: ['facts'] });
+    const { flags, positionals } = parseFlags(args, { values: ['facts', 'slug'] });
     if (positionals.length !== 2 || positionals[0] !== 'check') {
       writeSafe(stderr, USAGE);
       return 2;
@@ -48,13 +55,22 @@ export async function runPlanVerb(args, deps = {}) {
       writeSafe(stderr, `plan: ${loaded.message}\n`);
       return 2;
     }
-    const result = checkPlan(text, { planPath, factsPath, factsText, cfg: loaded.ok ? loaded.config : undefined });
-    if (!result.ok) {
-      for (const line of result.errors) writeSafe(stderr, `${line}\n`);
-      return 1;
+    const cfg = loaded.ok ? loaded.config : undefined;
+    // the same ledger as the rest of the tool (and `jev ask`): --slug, else project.slug, else the directory name
+    const slug = typeof flags.slug === 'string' ? flags.slug : slugFor(cfg, cwd);
+    try {
+      ledgerPath(slug);
+    } catch {
+      throw new StateError('usage', '--slug must be lowercase letters, digits and hyphens');
     }
-    writeSafe(stdout, `plan check: ok (${result.blocks} blocks)\n`);
-    return 0;
+    // a missing ledger is no rows (every block `none`); any other read error propagates as itself
+    const decisions = await readAllRows(slug);
+    const result = checkPlan(text, { planPath, factsPath, factsText, cfg, decisions });
+    for (const line of result.warnings) writeSafe(stderr, `${line}\n`);
+    for (const line of result.errors) writeSafe(stderr, `${line}\n`);
+    if (result.ok) writeSafe(stdout, `plan check: ok (${result.blocks} blocks)\n`);
+    if (result.lanes.length > 0) writeSafe(stdout, `lanes: ${result.lanes.map((l) => `${l.block} ${l.lane === null ? 'none' : `${l.lane} (${l.source})`}`).join(' · ')}\n`);
+    return result.ok ? 0 : 1;
   } catch (err) {
     if (err instanceof StateError) {
       writeSafe(stderr, `plan: ${err.message}\n`);

package/src/cli/report.mjs

@@ -4,7 +4,7 @@
  */
 
 import { writeSafe } from '../util/redact.mjs';
-import { buildReport } from '../ledger/report.mjs';
+import { buildReport, buildSpend } from '../ledger/report.mjs';
 import { exportReportSections } from '../ledger/export.mjs';
 import { readAllRows } from '../ledger/write.mjs';
 
@@ -60,6 +60,7 @@ export async function runReport(args, deps = {}) {
     for (const [name, data] of Object.entries(sections)) {
       out(`== ${name} ==\n${JSON.stringify(data, null, 2)}\n`);
     }
+    out(spendLines(buildSpend(rows)));
     return 0;
   } catch (err_) {
     err(`report: ${err_?.message ?? String(err_)}\n`);
@@ -67,6 +68,19 @@ export async function runReport(args, deps = {}) {
   }
 }
 
+/**
+ * B33: the running spend per run (open blocks included), after the 13 sections. Unknown-price
+ * sessions are named, never priced.
+ * @param {ReturnType<typeof buildSpend>} spend @returns {string}
+ */
+export function spendLines({ runs, total }) {
+  const unknown = (/** @type {number} */ n) => (n > 0 ? ` · ${n} with unknown price (not counted)` : '');
+  const lines = ['spend per run (estimated USD, open blocks included):'];
+  for (const r of runs) lines.push(`  run ${r.run ?? '(none)'}: $${r.usd.toFixed(4)} · ${r.sessions} session(s)${unknown(r.unknown)}`);
+  lines.push(`  total: $${total.usd.toFixed(4)} · ${total.sessions} session(s)${unknown(total.unknown)}`);
+  return `${lines.join('\n')}\n`;
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function report(args) {
   return runReport(args);