@codedology/code-forge 0.3.2 → 0.5.0

package/src/review/fixloop.mjs

@@ -14,7 +14,10 @@
  *     round (`review.late_findings: sweep`, default; `block` makes it an open finding instead).
  *  3. Strictly shrinking: open(n) ≥ open(n−1) ⇒ `trigger: review_stall` ⇒ +1 level now (rule 2b).
  *  4. Ladder: `escalation.review_rounds_per_level` (2) exhausted with an open finding ⇒ +1 level
- *     (rule 2); the next rounds are coded at that level by a fresh session (`deps.fix`).
+ *     (rule 2); the next rounds are coded at that level by a fresh session (`deps.fix`). Below L2,
+ *     `escalation.after_rounds_with_warnings` (1) heavy rounds at the level — an open set with
+ *     ≥ `escalation.warning_threshold` (2) warnings or any `critical` — climb at once (rule 2c,
+ *     B34: `trigger: review_warnings`); `warn_rounds_at_level` counts them and resets on a climb.
  *  5. Cap: `review.max_rounds_per_file` (4) reached with an open finding ⇒ the L3 patch rung
  *     (rule 6; once per block — shared with rule 5's ceiling), whose `patch_check` round is
  *     OUTSIDE the cap. The rung is also rule 5: rule 2/2b at the running ceiling (L2 — L3 is never
@@ -49,13 +52,14 @@
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
-import { escalationAfterAttempt, reviewRoundStalled } from '../decide/escalation.mjs';
+import { escalationAfterAttempt, heavyRound, reviewRoundStalled } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
 import { assemblePacket, assertPacketPath, readFileDiff } from './packet.mjs';
 import { cameFromJudge, resolvedBand, triageFindings } from './triage.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
+import { spawnWithTimeoutRetry } from './session-retry.mjs';
 
 /** @typedef {import('./triage.mjs').Finding} Finding */
 /** @typedef {import('./context.mjs').Hunk} Hunk */
@@ -74,6 +78,7 @@ import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.
  * @property {string} level - the level the file's fixes are coded at now.
  * @property {number} round - rounds counted so far (patch_check rounds excluded).
  * @property {number} rounds_at_level
+ * @property {number} [warn_rounds_at_level] - heavy rounds at the current level (rule 2c, B34); absent in a state saved before B34 ⇒ 0.
  * @property {Finding[]} open - the open `fix_now` set.
  * @property {Finding[]} late
  * @property {string | null} reviewed_content - the content the last counted round reviewed.
@@ -119,6 +124,8 @@ function settings(cfg) {
     scope: r.recheck_scope === 'file' ? 'file' : 'fix_hunks',
     late: r.late_findings === 'block' ? 'block' : 'sweep',
     perLevel: int(e.review_rounds_per_level, 2),
+    warnAfter: int(e.after_rounds_with_warnings, 1),
+    warnThreshold: e.warning_threshold, // heavyRound falls back to 2 for anything but an integer ≥ 1
     stopAt: typeof e.stop_at === 'string' ? e.stop_at : 'L3',
     l3Mode: e.l3_mode === 'code' ? 'code' : 'patch',
   };
@@ -129,7 +136,7 @@ function settings(cfg) {
  * @returns {FileState}
  */
 export function newFileState({ file, level, l3RungUsed = false }) {
-  return { file, level, round: 0, rounds_at_level: 0, open: [], late: [], reviewed_content: null, l3_rung_used: l3RungUsed, status: 'open', next: null, last_packet: null, pending_kind: null };
+  return { file, level, round: 0, rounds_at_level: 0, warn_rounds_at_level: 0, open: [], late: [], reviewed_content: null, l3_rung_used: l3RungUsed, status: 'open', next: null, last_packet: null, pending_kind: null };
 }
 
 /** @param {string} repoRoot @param {string} file @returns {{rel: string, content: string, hash: string}} */
@@ -209,11 +216,18 @@ async function recheckSession(packet, deps) {
   /** @type {Record<string, any> | null} */
   let res = null;
   try {
+    // a `timeout` is spawned once more on the same packet and level (B30)
     res = deps.spawn
-      ? await deps.spawn({ level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn } })
+      ? (
+          await spawnWithTimeoutRetry(
+            deps.spawn,
+            { level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn } },
+            (row) => note(deps, row),
+          )
+        ).res
       : null;
   } catch {
-    res = null;
+    res = null; // the helper never throws; if it ever did, it is still an `exit` failure
   } finally {
     rmSync(promptPath, { force: true });
   }
@@ -246,12 +260,17 @@ function decideNext(state, openBefore, s, kind) {
     openFixNowFinding: true,
     reviewRoundsAtLevel: state.rounds_at_level,
     reviewRoundsPerLevel: s.perLevel,
+    warningRoundsAtLevel: state.warn_rounds_at_level ?? 0,
+    afterRoundsWithWarnings: s.warnAfter,
     stopAt: s.stopAt,
     l3Mode: /** @type {'patch' | 'code'} */ (s.l3Mode),
     l3RungAlreadyUsed: state.l3_rung_used,
   });
   if (esc.action === 'escalate' && esc.level) {
-    if (esc.level !== state.level) state.rounds_at_level = 0;
+    if (esc.level !== state.level) {
+      state.rounds_at_level = 0;
+      state.warn_rounds_at_level = 0;
+    }
     state.level = esc.level;
     return { action: 'fix', level: state.level, trigger: esc.trigger };
   }
@@ -390,10 +409,13 @@ export async function runRound(state, deps, opts = {}) {
   if (kind !== 'patch_check') {
     draft.round += 1;
     draft.rounds_at_level += 1;
+    // THIS round's open set, after triage: only the warnings still open count
+    if (heavyRound(draft.open, s.warnThreshold)) draft.warn_rounds_at_level = (draft.warn_rounds_at_level ?? 0) + 1;
   } else {
     // the block continues at L2 after the rung with a fresh round counter (§3.6) — also here, not
     // only in `converge`, because the worker runs the patch_check from its own ticket
     draft.rounds_at_level = 0;
+    draft.warn_rounds_at_level = 0;
   }
   draft.reviewed_content = current.content;
   draft.last_packet = packetInfo;
@@ -456,6 +478,7 @@ export async function converge(state, deps) {
     if (next.action === 'patch') {
       state.l3_rung_used = true;
       state.rounds_at_level = 0;
+      state.warn_rounds_at_level = 0;
       await deps.patch?.({ file: state.file, level: 'L3', open: [...state.open] });
       await runRound(state, deps, { kind: 'patch_check' });
       continue;

package/src/review/session-retry.mjs

@@ -0,0 +1,69 @@
+/**
+ * One review session with ONE automatic retry on `timeout` (block B30, issue #2).
+ *
+ * Field data: a reviewer CLI can hang for the whole `review.session_timeout_s` with almost no
+ * output, while the same packet reviews in seconds on a second try. So a session whose status is
+ * `timeout` is spawned once more with the SAME options (same packet file, same level, same lens);
+ * only when the second attempt times out too does the review report `unavailable: timeout`. Any
+ * other failure (exit, schema, unavailable…) is never retried here.
+ *
+ * Both attempts are recorded: `spawnSession` writes one ledger `session` row per spawn as always,
+ * and every timed-out attempt adds a `review.session_timeout` note `{lens, role, level, provider,
+ * model, attempt, retried, duration_ms, stderr_tail, tail_note?, stdout_bytes, stdout_events}`:
+ * the last 4 KB of the session's stderr, packet-free and redacted (`stderrTail`; null with a
+ * `tail_note` when withheld), and stdout only as its byte count and last event types
+ * (`stdoutEvents`) — never stdout text. The helper never throws: a throwing spawn is returned as
+ * `res: null` and a failed note is ignored. `onAttempt(n)` is told each attempt as it starts.
+ */
+
+import { logWarning } from '../util/error-log.mjs';
+
+/** How many times a timed-out session is spawned again. */
+export const TIMEOUT_RETRIES = 1;
+
+/**
+ * @param {(opts: Record<string, any>) => Promise<Record<string, any>>} spawn
+ * @param {Record<string, any>} opts - the spawn options; passed unchanged to every attempt.
+ * @param {(row: Record<string, any>) => Promise<unknown>} note - best-effort ledger note.
+ * @param {(attempt: number) => void} [onAttempt] - told the attempt number as each one starts.
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number}>} the last attempt's result
+ *   (`null` when the spawn threw) and how many attempts ran.
+ */
+export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () => {}) {
+  let attempts = 0;
+  for (;;) {
+    attempts += 1;
+    onAttempt(attempts);
+    /** @type {Record<string, any> | null} */
+    let res;
+    try {
+      res = await spawn(opts);
+    } catch {
+      return { res: null, attempts }; // a throw is an `exit` failure, never retried
+    }
+    if (res?.status !== 'timeout') return { res, attempts };
+    const retried = attempts <= TIMEOUT_RETRIES;
+    try {
+      await note({
+        event: 'review.session_timeout',
+        lens: opts?.rowExtra?.lens ?? null,
+        role: opts?.role ?? null,
+        level: opts?.level ?? null,
+        provider: res.provider ?? null,
+        model: res.model ?? null,
+        attempt: attempts,
+        retried,
+        duration_ms: typeof res.duration_ms === 'number' ? res.duration_ms : null,
+        stderr_tail: typeof res.stderr_tail === 'string' ? res.stderr_tail : null,
+        ...(typeof res.tail_note === 'string' ? { tail_note: res.tail_note } : {}),
+        stdout_bytes: typeof res.stdout_bytes === 'number' ? res.stdout_bytes : null,
+        stdout_events: Array.isArray(res.stdout_events) ? res.stdout_events : [],
+      });
+    } catch {
+      // a failed note never stops the retry or the result
+    }
+    if (!retried) return { res, attempts };
+    // B37: the retry is a recoverable problem: one warning line in the local error log
+    await logWarning({ warning: 'review_retry', message: 'a review session timed out; it was retried once' }).catch(() => null);
+  }
+}

package/src/review/triage.mjs

@@ -18,6 +18,7 @@
 import { buildQuestionPayload, isQuestionDisabled } from '../decide/questions.mjs';
 import { bandFinding, bandResolved } from '../decide/thresholds.mjs';
 import { alwaysResidue } from '../decide/fallback-rules.mjs';
+import { logWarning } from '../util/error-log.mjs';
 
 /**
  * @typedef {{id: string, file?: string, line_start: number, line_end: number, severity: 'critical' | 'warning' | 'nit', category?: string, claim?: string, evidence?: string, fix?: string}} Finding
@@ -37,6 +38,27 @@ async function note(writeRow, row) {
   }
 }
 
+/**
+ * The reasons a fallback warning may name: Jev client failure kinds (`jev-client.mjs`) plus
+ * `error` (the call threw) and `invalid_answer` (ok, but no probability). Anything else is `other`.
+ */
+const FALLBACK_REASONS = new Set(['unauthorized', 'invalid_request', 'rate_limited', 'unavailable', 'network', 'timeout', 'unexpected_status', 'invalid_response', 'error', 'invalid_answer']);
+
+/**
+ * B37: Jev was asked and gave no usable answer, so §3.5's fallback decides: one warning line in the
+ * local error log (once per reason per process). The reason is a word from a fixed list, never
+ * Jev's text. Never throws: a logging failure cannot change the fallback.
+ * @param {unknown} reason
+ */
+async function fellBack(reason) {
+  const word = typeof reason === 'string' && FALLBACK_REASONS.has(reason) ? reason : 'other';
+  try {
+    await logWarning({ warning: 's1_fallback', message: `System 1 (Jev) gave no answer (${word}); fell back to the rules` }).catch(() => null);
+  } catch {
+    // the fallback stands without its warning line
+  }
+}
+
 /** @param {Finding} f @returns {'fix_now' | 'nit'} the verdict a judge's severity means. */
 export const severityVerdict = (f) => (f.severity === 'nit' ? 'nit' : 'fix_now');
 
@@ -53,10 +75,13 @@ export async function askNoul(id, state, { jev, cfg = {} }) {
   try {
     res = await jev({ state, questions: buildQuestionPayload([id], cfg) });
   } catch {
+    await fellBack('error');
     return null;
   }
   const p = res?.ok === true ? res.answers?.[id]?.noul : undefined;
-  return typeof p === 'number' && Number.isFinite(p) && p >= 0 && p <= 1 ? p : null;
+  if (typeof p === 'number' && Number.isFinite(p) && p >= 0 && p <= 1) return p;
+  await fellBack(res?.ok === true ? 'invalid_answer' : res?.kind);
+  return null;
 }
 
 /**

package/src/review/validate-review.mjs

@@ -7,14 +7,15 @@
  *  3. `reviewed_hunks` equals the packet's hunk headers EXACTLY and IN ORDER;
  *  4. `tokens_out ≥ review.min_tokens_out` (120).
  * Anything else is `unavailable` with one reason — `timeout`, `exit`, `schema`,
- * `hunks_mismatch`, `too_short` — and is never approval. There is no "approve on missing output":
+ * `hunks_mismatch`, `too_short`, or `budget` (B33: the spawner refused at `budget.usd`) — and is
+ * never approval. There is no "approve on missing output":
  * no answer is a `schema` failure, no session is an `exit` failure.
  */
 
 import { readFileSync } from 'node:fs';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 
-export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_mismatch', 'too_short', 'timeout']);
+export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_mismatch', 'too_short', 'timeout', 'budget']);
 
 export const DEFAULT_MIN_TOKENS_OUT = 120;
 
@@ -48,7 +49,7 @@ export function minTokensOut(cfg) {
  * @property {boolean} ok
  * @property {Record<string, any>} [review]
  * @property {number} [tokens_out]
- * @property {'exit' | 'schema' | 'hunks_mismatch' | 'too_short' | 'timeout'} [reason]
+ * @property {'exit' | 'schema' | 'hunks_mismatch' | 'too_short' | 'timeout' | 'budget'} [reason]
  * @property {string} [detail]
  */
 
@@ -60,6 +61,8 @@ export function minTokensOut(cfg) {
 export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT, smallDiff = false }) {
   if (!session || typeof session !== 'object') return { ok: false, reason: 'exit', detail: 'no session result' };
   if (session.status === 'timeout') return { ok: false, reason: 'timeout', detail: 'killed at the session timeout' };
+  // B33: the spawner refused the session because the run reached `budget.usd` — nothing ran
+  if (session.status === 'unavailable' && session.reason === 'budget') return { ok: false, reason: 'budget', detail: String(session.message ?? 'budget.usd reached') };
   const exitCode = session.exit_code;
   if (session.status === 'failed' || session.status === 'unavailable' || (exitCode !== undefined && exitCode !== 0)) {
     return { ok: false, reason: 'exit', detail: `session ${session.status}${exitCode === undefined ? '' : ` (exit ${exitCode})`}` };

package/src/session/author.mjs

@@ -20,6 +20,7 @@ import { estimateCostUsd } from '../ledger/prices.mjs';
 import { writeSafe } from '../util/redact.mjs';
 import { currentRunRoot } from '../util/tmp.mjs';
 import { checkSheetFresh } from './facts.mjs';
+import { authorHeadingRules } from './plan-sections.mjs';
 import { spawnSession } from './spawn.mjs';
 
 export const JOBS = Object.freeze(['plan', 'harden']);
@@ -58,8 +59,11 @@ export const AUTHOR_LENS =
 const JOB_RULES = {
   plan: [
     'Write the plan draft in markdown. Its §0 is the facts sheet below, VERBATIM (header lines included).',
-    'Include a section titled "Acceptance clauses the facts sheet cannot back": every clause that cites a claim the sheet',
-    'marks NOT-FOUND or UNVERIFIABLE, each with a tolerance naming the block; write `none` when there is none.',
+    ...authorHeadingRules(),
+    'The level column of the block table is the lane recorded for each block by `forge jev ask lane --block <id> --plan <plan>`',
+    '(or `--rules`, the deterministic fallback, when Jev is unavailable): L0 trivial · L1 a plain feature following a pattern ·',
+    'L2 money, dates, tenancy, migrations, concurrency. It is never a block category. Leave it as `L?` when no lane is given in',
+    'the message; plan check refuses a level that differs from the recorded lane.',
   ],
   harden: [
     'Harden the draft: close every gap you can from the material given; for each decision only the human can make,',