@codedology/code-forge 0.8.0 → 0.9.0

package/src/doctor/index.mjs

@@ -1,9 +1,9 @@
 /**
  * `code-forge doctor` (plan §2.3; block B13b): every row, in print order. `--quick` = the three
  * rows the skill's preflight needs (config, harness links, Jev key resolution); the full run adds
- * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, the provider CLI probes (presence,
- * version, flags, one call per role builder, isolation, path deny, Codex rules), the worker
- * start/stop, the signer key and the `signer: same-user boundary only` line.
+ * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, `review state` (B69), the provider
+ * CLI probes (presence, version, flags, one call per role builder, isolation, path deny, Codex
+ * rules), the worker start/stop, the signer key and the `signer: same-user boundary only` line.
  */
 
 import { randomBytes } from 'node:crypto';
@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkTmp, checkTools } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
 import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -68,6 +68,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
   rows.push(...checkTmp(cfg));
+  rows.push(...(await checkReviewState(cfg)));
   rows.push(checkReviewConcurrency(cfg));
   if (!cfg) {
     rows.push(row('probes', 'FAIL', 'probes', 'skipped: no valid config'));

package/src/doctor/local.mjs

@@ -1,7 +1,8 @@
 /**
  * Doctor rows that need no provider CLI (plan §2.3; block B13b): config, harness links, Jev key
  * resolution (the three `--quick` rows), `code-forge` on PATH, Solo, gate commands, the live Jev
- * call, ledger writability and the `tmp` row. Every check returns rows; none throws.
+ * call, ledger writability, the `tmp` row and (B69) the `review state` row. Every check returns
+ * rows; none throws.
  */
 
 import { constants, readdirSync } from 'node:fs';
@@ -17,10 +18,16 @@ import { missingTools } from '../install/tools.mjs';
 import { OP_MESSAGES } from '../keys/onepassword.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { ledgerDir } from '../ledger/paths.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { DEFAULT_PROVIDER_CONCURRENCY, providerLimit } from '../session/spawn.mjs';
+import { snapshotFor } from '../state/config-snapshot.mjs';
+import { assertRunId, runsDir } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { loadKey } from '../state/signer.mjs';
 import { listEntries } from '../util/reaper.mjs';
-import { ownerState, tmpBase } from '../util/tmp.mjs';
+import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
+import { missingStateFiles } from '../worker/review-state.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
@@ -192,6 +199,86 @@ export function checkTmp(cfg) {
   return [row('tmp', roots + pids > 0 ? 'WARN' : 'OK', 'tmp', roots + pids > 0 ? `${detail} (the next code-forge run start removes them)` : detail)];
 }
 
+/** B69: the most missing state files the `review state` row names. */
+export const LISTED_MAX = 10;
+
+/**
+ * B69: one WARN row per ACTIVE run (its record's `status` is `active`, as `run end` and the worker
+ * decide it) whose ledger has `review.state` anchors whose latest state file is missing — neither
+ * at `<code-forge home>/runs/<run>/review-state/` nor at the old temp-root path. The row counts the
+ * files the ledger can rebuild (the latest anchor carries `state_body`) and the lost ones (no body:
+ * the next ticket is refused `review-state-lost`; the owner needs `code-forge block reopen`), and
+ * names the first {@link LISTED_MAX} blocks and files (then `… and K more`). No row when nothing
+ * is missing. When the old temp location cannot be named (`tmp.root` not absolute), nothing is
+ * counted and the row says so; when an anchor of the run does not verify, the row says the review
+ * state was not checked. Each project's ledger is read once. Never throws: a run whose record, key
+ * or ledger cannot be read is skipped. No file content is read or printed.
+ * @param {Record<string, any> | null} cfg
+ * @returns {Promise<Row[]>}
+ */
+export async function checkReviewState(cfg) {
+  let names = [];
+  try {
+    names = readdirSync(runsDir()).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  /** @type {Row[]} */
+  const rows = [];
+  /** @type {Map<string, Array<Record<string, any>>>} the ledger rows per project, read once */
+  const ledgers = new Map();
+  for (const name of names.sort()) {
+    const runId = name.slice(0, -'.json'.length);
+    try {
+      assertRunId(runId);
+      const record = await readRun(runId);
+      if (record?.status !== 'active' || typeof record.project !== 'string') continue;
+      const key = await loadKey(runId);
+      let ledger = ledgers.get(record.project);
+      if (ledger === undefined) {
+        ledger = await readAllRows(record.project);
+        ledgers.set(record.project, ledger);
+      }
+      const atNew = missingStateFiles({ runId, key, rows: ledger });
+      if (atNew === null) {
+        rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: review.state anchors do not verify; review state not checked`));
+        continue;
+      }
+      let root;
+      try {
+        root = snapshotFor(record, '')?.config?.tmp?.root;
+      } catch {
+        root = undefined;
+      }
+      if (typeof root !== 'string') root = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
+      let runRootDir;
+      try {
+        runRootDir = runRootPath(runId, root === undefined ? {} : { root });
+      } catch {
+        runRootDir = undefined;
+      }
+      if (runRootDir === undefined) {
+        // the old place cannot be named: nothing is counted as missing, the row says why
+        if (atNew.length > 0) {
+          rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: the old temp location could not be checked (tmp.root is not an absolute path); review state files are not counted`));
+        }
+        continue;
+      }
+      const missing = missingStateFiles({ runId, key, rows: ledger, runRootDir });
+      if (missing === null || missing.length === 0) continue;
+      const rebuildable = missing.filter((m) => m.rebuildable).length;
+      const lost = missing.length - rebuildable;
+      const shown = missing.slice(0, LISTED_MAX).map((m) => `${m.block} ${m.file} (${m.rebuildable ? 'rebuildable' : 'lost'})`).join(', ');
+      const more = missing.length > LISTED_MAX ? ` … and ${missing.length - LISTED_MAX} more` : '';
+      rows.push(row('review-state', 'WARN', 'review state',
+        `run ${runId}: ${missing.length} state file(s) missing — ${rebuildable} rebuildable from the ledger, ${lost} lost (needs code-forge block reopen): ${shown}${more}`));
+    } catch {
+      // an unreadable record, key or ledger: not this row's business
+    }
+  }
+  return rows;
+}
+
 /**
  * B44: the `review concurrency` INFO row — how many review tickets run at once and each provider's
  * session slots, from the effective config (defaults when a key is unset). Never throws.

package/src/ledger/write.mjs

@@ -53,9 +53,14 @@ function normalizeRow(row) {
 /**
  * Claim `<base>.<n>.jsonl` for `n = 1, 2, ...` atomically via `link()` (hardlink the still-full
  * file under the rotated name, then unlink the original) instead of `rename()`.
+ *
+ * `hooks.afterLink` is a test seam only: when given, it is awaited with the claimed candidate path
+ * right after a successful `link()` and before this call's `unlink()` of the source, so a test can
+ * force another racer's unlink into exactly that window. Production callers pass nothing.
  * @param {string} file @param {string} dir @param {string} base
+ * @param {{ afterLink?: (candidate: string) => Promise<void> | void }} [hooks]
  */
-export async function claimRotatedName(file, dir, base) {
+export async function claimRotatedName(file, dir, base, hooks = {}) {
   let n = 1;
   for (;;) {
     const candidate = path.join(dir, `${base}.${n}.jsonl`);
@@ -70,6 +75,7 @@ export async function claimRotatedName(file, dir, base) {
       if (err.code === 'ENOENT') return; // `file` vanished before we could link it — a racer already rotated it out
       throw err;
     }
+    if (hooks.afterLink) await hooks.afterLink(candidate);
     try {
       await unlink(file);
       return;

package/src/review/answers.mjs

@@ -0,0 +1,445 @@
+/**
+ * B71 (issue #9 b): an answers ticket — `review-file <answering file> --block <id> --answers <ids>
+ * --of <source>` — asks ONE fresh L2 reviewer session whether the answering file (`by_file`)
+ * resolves the open findings `<ids>` of the source file. The worker runs it through the engine
+ * seam (`reviewTicket` dispatches here on `kind: 'answers'`); `loop.mjs` has already checked the
+ * ticket's run, its tree and that the source still has the ticket's hash.
+ *
+ * Checks here (the ones that count; `review-file` only pre-checks the same rules, unverified):
+ *  - both files are owned by the block (`answers-not-owned`) and they are two files
+ *    (`answers-same-file`);
+ *  - each file is read ONCE: the answering file's bytes must hash to the ticket's `by_hash` (else
+ *    `stale`, `answering-file-changed`; absent or unreadable: `answers-file-missing`) and the
+ *    source's to its `content_hash` (else `stale`, `source-changed`); the packet is built from
+ *    those same bytes, so the row's `by_hash` is the hash of what the reviewer saw;
+ *  - every id is open on the source's CURRENT hash by the signed rows and not waived or answered
+ *    yet — `answerableFindings`, the close's own rules (`answers-not-open`).
+ * A refusal runs no session. The packet holds each finding (file, lines, severity, claim, evidence,
+ * fix — from the source's signed fix-loop state; only id and severity when the state has none),
+ * the source lines around it, and the answering file's diff against the block base (its full
+ * content when it is new). The reviewer answers per id `resolved` or `not_resolved` with a reason;
+ * a missing, repeated or broken verdict is `not_resolved`, and a session that fails (no result,
+ * not `ok`, a non-zero exit, a thrown spawn error: `session-error`) makes the ticket `unavailable`
+ * with no row. A packet that cannot be built (B79: a secret-like source or answering file too) is
+ * `packet-unreadable`; the whole packet stays within the `full_in` budget, and one whose fixed text
+ * alone is over it is refused `packet-too-large`. One that cannot be written to the work dir is
+ * `packet-write-failed`. All three are refusals (`unavailable`: never approval, no session, no row). For each resolved id the
+ * worker writes one signed `review.answered {block, file: source, content_hash: source hash,
+ * finding, by_file, by_hash, ticket}` row (`ctx.writeRow` stamps the block, the source and its
+ * hash). The ticket's result is `status: 'answers'`, never an approval: the gate never reads it
+ * as a verdict on the source (`neverReviewed`), the answering file still needs its own approval,
+ * and the source's fix-loop state is not touched.
+ *
+ * The worker's file and state readers come in through `io` (the worker passes its own
+ * `readRegularFileNoFollow`, `loadState` and `assertAnswers`), so this review-side module imports
+ * nothing from `src/worker/`.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ownsFile } from '../state/registry.mjs';
+import { exec } from '../util/exec.mjs';
+import { redact } from '../util/redact.mjs';
+import { ANSWERED_EVENT, ANSWERS_STATUS, answerableFindings, ticketAnswered } from './gate-check.mjs';
+import { fixHunkDiff } from './fixloop.mjs';
+import { assertPacketPath, budgetFor, isSecretLike, plainGitEnv, reviewGitEnv } from './packet.mjs';
+import { spawnWithTimeoutRetry } from './session-retry.mjs';
+
+/** The answer the reviewer gives: one verdict per finding id. */
+export const ANSWERS_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    verdicts: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          verdict: { type: 'string', enum: ['resolved', 'not_resolved'] },
+          reason: { type: 'string' },
+        },
+        required: ['id', 'verdict', 'reason'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['verdicts'],
+  additionalProperties: false,
+});
+
+/** The system prompt of the answers session. */
+export const ANSWERS_LENS =
+  'You are a code reviewer for code-forge, judging whether a change in one file resolves findings a review raised about another file. ' +
+  'You have no tools and no files; everything you may use is in the message. Answer once, with a JSON object that matches the schema.';
+
+/** Lines of the source shown before and after each finding. */
+const AROUND = 5;
+
+/** A reason longer than this is cut (the reviewer's free text). */
+const REASON_MAX = 500;
+
+/** B79: what a part cut at the packet budget ends with. */
+export const TRUNCATED_MARKER = '[... truncated at the packet budget]';
+
+/** B79: what a cut part shows when its cap is too small for {@link TRUNCATED_MARKER}. */
+export const SHORT_MARKER = '[cut]';
+
+/** B79: the packet's fixed text (headings, labels, fences) alone is over the budget. */
+class PacketTooLarge extends Error {}
+
+/**
+ * @typedef {object} AnswersOutcome
+ * @property {string} status - `answers`, `stale` or `unavailable`.
+ * @property {boolean} approved - always false.
+ * @property {string} engine
+ * @property {string} [reason]
+ * @property {string} kind - `answers`.
+ * @property {Array<{id: string, severity: unknown, verdict: 'resolved' | 'not_resolved', reason: string}>} [findings]
+ * @property {Array<Record<string, any>>} sessions
+ */
+
+/**
+ * The ticket fields an answers ticket carries (`worker/queue.mjs` `enqueueAnswers`).
+ * @typedef {object} AnswersTicket
+ * @property {string} ticket
+ * @property {string} block
+ * @property {string} file - the source.
+ * @property {string} content_hash - the source's hash.
+ * @property {string} [by_file]
+ * @property {string} [by_hash]
+ * @property {string[]} [answers]
+ */
+
+/**
+ * What the worker's review context gives an answers ticket.
+ * @typedef {object} AnswersContext
+ * @property {string} repoRoot
+ * @property {string | null} [contentRoot] - the block's tree, when it has one.
+ * @property {string} runId
+ * @property {string} [runRootDir]
+ * @property {Buffer | null} [key]
+ * @property {Parameters<typeof budgetFor>[0]} cfg
+ * @property {Parameters<typeof spawnWithTimeoutRetry>[0]} spawn
+ * @property {() => Promise<Array<Record<string, any>>>} [readRows]
+ * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow]
+ */
+
+/**
+ * The worker's readers (injected, see the module doc).
+ * @typedef {object} AnswersIo
+ * @property {(root: string, file: string) => Buffer | null} readFile - no symlinks; null when absent.
+ * @property {(opts: Record<string, any>) => {status: string, state?: Record<string, any> | null}} loadState - the signed fix-loop state, read only.
+ * @property {(answers: unknown) => string[]} assertAnswers - the queue's id-list rule (sorted, unique); throws when the list is bad.
+ */
+
+/**
+ * @param {string} status @param {string} reason @param {Array<Record<string, any>>} [sessions]
+ * @returns {AnswersOutcome}
+ */
+const outcome = (status, reason, sessions = []) => ({ status, reason, approved: false, engine: 'adaptive', kind: 'answers', sessions });
+
+/**
+ * Run one answers ticket.
+ * @param {AnswersTicket} ticket - `kind: 'answers'`.
+ * @param {AnswersContext} ctx - `contentRoot` is the block's tree.
+ * @param {{entry: {base: string | null, owned: string[], ownedKinds?: Record<string, string>}, workDir: string, io: AnswersIo}} opts
+ * @returns {Promise<AnswersOutcome>}
+ */
+export async function reviewAnswers(ticket, ctx, { entry, workDir, io }) {
+  const root = ctx.contentRoot ?? ctx.repoRoot;
+  const source = ticket.file;
+  const byFile = /** @type {string} */ (ticket.by_file);
+  // the id list, checked here too by the queue's own rule: 1 to 10 well-formed ids, none twice
+  /** @type {string[]} */
+  let ids;
+  try {
+    ids = io.assertAnswers(ticket.answers);
+  } catch {
+    return outcome(ANSWERS_STATUS, 'usage');
+  }
+  if (!Array.isArray(ticket.answers) || ids.length !== ticket.answers.length) return outcome(ANSWERS_STATUS, 'usage');
+  if (!ctx.key || !ctx.readRows || !ctx.writeRow) return outcome('unavailable', 'no-ledger');
+  if (typeof byFile !== 'string' || path.posix.normalize(byFile) === path.posix.normalize(source)) return outcome(ANSWERS_STATUS, 'answers-same-file');
+  if (!ownsFile(entry.owned, source, entry.ownedKinds) || !ownsFile(entry.owned, byFile, entry.ownedKinds)) return outcome(ANSWERS_STATUS, 'answers-not-owned');
+  // each file is read ONCE; the hashes and the packet come from these bytes
+  /** @type {Buffer | null} */
+  let byBytes;
+  /** @type {Buffer | null} */
+  let srcBytes;
+  try {
+    byBytes = io.readFile(root, byFile);
+  } catch {
+    byBytes = null;
+  }
+  if (byBytes === null) return outcome(ANSWERS_STATUS, 'answers-file-missing');
+  const byHash = hashOf(byBytes);
+  if (byHash !== ticket.by_hash) return outcome('stale', 'answering-file-changed');
+  try {
+    srcBytes = io.readFile(root, source);
+  } catch {
+    srcBytes = null;
+  }
+  if (srcBytes === null || hashOf(srcBytes) !== ticket.content_hash) return outcome('stale', 'source-changed');
+
+  let rows;
+  try {
+    rows = (await ctx.readRows()).filter((r) => r?.run === ctx.runId);
+  } catch {
+    return outcome('unavailable', 'ledger-unreadable');
+  }
+  const current = new Map([
+    [source, ticket.content_hash],
+    [byFile, byHash],
+  ]);
+  // this ticket's own rows do not close an id: a retry after a partial write finishes the rest
+  const open = answerableFindings({ block: ticket.block, runId: ctx.runId, rows, key: ctx.key, file: source, hash: ticket.content_hash, current, ticket: ticket.ticket });
+  if (!ids.every((id) => open.has(id))) return outcome(ANSWERS_STATUS, 'answers-not-open');
+
+  let text;
+  try {
+    text = await packetText({ ticket, ctx, rows, root, entry, open, io, ids, srcBytes, byBytes, workDir });
+  } catch (err) {
+    // B79: a packet whose fixed text alone is over the budget is refused like an unreadable one:
+    // never approval, no session, no row
+    if (err instanceof PacketTooLarge) return outcome('unavailable', 'packet-too-large');
+    return outcome('unavailable', 'packet-unreadable');
+  }
+  const promptPath = path.join(workDir, `answers-${randomBytes(6).toString('hex')}.md`);
+  try {
+    mkdirSync(workDir, { recursive: true, mode: 0o700 });
+    writeFileSync(promptPath, text, { mode: 0o600 });
+  } catch {
+    return outcome('unavailable', 'packet-write-failed');
+  }
+
+  const note = async (/** @type {Record<string, any>} */ row) => {
+    try {
+      await ctx.writeRow?.(row);
+    } catch {
+      // a note is best-effort
+    }
+  };
+  let res;
+  try {
+    ({ res } = await spawnWithTimeoutRetry(ctx.spawn, { level: 'L2', role: 'reviewer', promptPath, schema: ANSWERS_SCHEMA, systemPromptText: ANSWERS_LENS, rowExtra: { lens: 'answers' } }, note));
+  } catch {
+    // a spawn or adapter error is no verdict: retry the ticket
+    return outcome('unavailable', 'session-error');
+  } finally {
+    rmSync(promptPath, { force: true });
+  }
+  const sessions = [{ lens: 'answers', role: 'reviewer', level: 'L2', provider: res?.provider ?? null, model: res?.model ?? null, tokens_in: res?.usage?.tokens_in ?? null, tokens_out: res?.usage?.tokens_out ?? null }];
+  // a spawn that threw (`spawnWithTimeoutRetry` gives null) is `session-error`, like a throw above
+  if (!res) return outcome('unavailable', 'session-error', sessions);
+  if (res.status !== 'ok' || (res.exit_code !== undefined && res.exit_code !== 0)) return outcome('unavailable', typeof res.status === 'string' && res.status !== 'ok' ? res.status : 'exit', sessions);
+
+  const verdicts = verdictsOf(res.answer, ids);
+  /** @type {NonNullable<AnswersOutcome['findings']>} */
+  const findings = ids.map((id) => {
+    const v = verdicts.get(id) ?? { verdict: /** @type {const} */ ('not_resolved'), reason: 'no valid verdict' };
+    return { id, severity: open.get(id) ?? null, verdict: v.verdict, reason: v.reason };
+  });
+  // every verdict is built before any row is written; an id this ticket already answered (an
+  // earlier attempt whose later write failed) gets no second row, so a retry ends with one per id
+  const done = ticketAnswered({ block: ticket.block, runId: ctx.runId, rows, key: ctx.key, file: source, current, ticket: ticket.ticket });
+  for (const f of findings) {
+    if (f.verdict !== 'resolved' || done.has(f.id)) continue;
+    try {
+      await ctx.writeRow({ event: ANSWERED_EVENT, finding: f.id, by_file: byFile, by_hash: byHash, ticket: ticket.ticket });
+    } catch {
+      return outcome('unavailable', 'ledger-write-failed', sessions);
+    }
+  }
+  return { status: ANSWERS_STATUS, approved: false, engine: 'adaptive', kind: 'answers', findings, sessions };
+}
+
+/**
+ * The reviewer's verdict per requested id: only `{id, verdict: 'resolved' | 'not_resolved',
+ * reason: string}` entries count; an id given twice, an unknown id or a broken entry gives no
+ * verdict for that id (the caller reads it as `not_resolved`).
+ * @param {unknown} answer @param {string[]} ids
+ * @returns {Map<string, {verdict: 'resolved' | 'not_resolved', reason: string}>}
+ */
+export function verdictsOf(answer, ids) {
+  /** @type {Map<string, {verdict: 'resolved' | 'not_resolved', reason: string}>} */
+  const out = new Map();
+  let value = answer;
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return out;
+    }
+  }
+  const list = value && typeof value === 'object' && Array.isArray(/** @type {any} */ (value).verdicts) ? /** @type {unknown[]} */ (/** @type {any} */ (value).verdicts) : [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  /** @type {Set<string>} */
+  const repeated = new Set();
+  for (const v of list) {
+    const e = /** @type {Record<string, unknown>} */ (v);
+    if (!e || typeof e !== 'object' || typeof e.id !== 'string' || !ids.includes(e.id)) continue;
+    if (seen.has(e.id)) repeated.add(e.id);
+    seen.add(e.id);
+    if ((e.verdict === 'resolved' || e.verdict === 'not_resolved') && typeof e.reason === 'string') out.set(e.id, { verdict: e.verdict, reason: e.reason.slice(0, REASON_MAX) });
+  }
+  for (const id of repeated) out.delete(id);
+  return out;
+}
+
+/** The worker's content hash of bytes it read (`worker/ticket.mjs` `contentHash`: sha256, hex). */
+const hashOf = (/** @type {Buffer} */ bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/**
+ * The answering file's change, built from the bytes that were hashed (never a second read): its
+ * diff against its text at the block base (`entry.base`, else HEAD), or its full content when the
+ * base has no such file. A secret-like path or a git failure throws (`packet-unreadable`).
+ * @param {{root: string, file: string, base: string | null, bytes: Buffer, workDir: string}} opts
+ * @returns {Promise<{kind: 'new' | 'tracked', text: string}>}
+ */
+async function answeringChange({ root, file, base, bytes, workDir }) {
+  const rel = assertPacketPath(root, file);
+  if (isSecretLike(rel)) throw new Error('secret-like path');
+  const ref = base ?? 'HEAD';
+  if (typeof ref !== 'string' || ref.length === 0 || ref.startsWith('-')) throw new Error('the base must be a commit id');
+  const git = { cwd: root, timeoutMs: 30000 };
+  const listed = await exec(['git', 'ls-tree', '-z', ref, '--', rel], { ...git, env: reviewGitEnv() });
+  if (listed.result !== 'ok') throw new Error(`git ls-tree failed (exit ${listed.code})`);
+  const current = bytes.toString('utf8');
+  if (listed.stdout.length === 0) return { kind: 'new', text: current };
+  const shown = await exec(['git', 'show', `${ref}:${rel}`], { ...git, env: plainGitEnv() });
+  if (shown.result !== 'ok') throw new Error(`git show failed (exit ${shown.code})`);
+  const diff = await fixHunkDiff({ file: rel, previous: shown.stdout, current, workDir });
+  return { kind: 'tracked', text: diff.diffText };
+}
+
+/**
+ * B79: `text` cut to at most `max` UTF-8 bytes, marker included — never more. The bytes are cut on
+ * the Buffer and the cut moves back to a character boundary (never half a character); a cut text
+ * ends with a newline and {@link TRUNCATED_MARKER}. When `max` is too small for that marker, the
+ * part's text is dropped for {@link SHORT_MARKER} (or for nothing, when even that does not fit).
+ * A text that fits is returned as it is.
+ * @param {string} text @param {number} max @returns {string}
+ */
+export function capBytes(text, max) {
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.length <= max) return text;
+  const tail = `\n${TRUNCATED_MARKER}`;
+  const tailBytes = Buffer.byteLength(tail);
+  if (max < tailBytes) return max >= Buffer.byteLength(SHORT_MARKER) ? SHORT_MARKER : '';
+  let end = max - tailBytes;
+  // a UTF-8 continuation byte (10xxxxxx) never starts a character: step back to the lead byte
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString('utf8')}${tail}`;
+}
+
+/** The free-text fields of a finding the packet shows. */
+const FIELDS = /** @type {const} */ (['claim', 'evidence', 'fix']);
+
+/**
+ * The packet: the findings, the source lines around each, and the answering file's change — all
+ * from the bytes `reviewAnswers` read and hashed. Neither file may be secret-like (both refused the
+ * same way: `packet-unreadable`). B79: the WHOLE packet stays within the budget (`full_in` × 4
+ * bytes). Its fixed text (headings, labels, fences) is counted first — over the budget alone it is
+ * {@link PacketTooLarge}. Of the room left, the findings get half — per finding, each of claim,
+ * evidence and fix a fifth of its share and the source excerpt the rest — and the answering file's
+ * change what the findings leave. Each part is redacted BEFORE it is cut (a secret is never cut
+ * into a prefix redaction misses), and cut by {@link capBytes}: one marker per cut part, never over
+ * its cap. The fixed text is redacted before it is measured, so the joined packet is never cut: it
+ * ends with the change's closing fence. A joined packet redaction would still change (a secret
+ * across a part boundary) is refused, never cut — `packet-unreadable`.
+ * @param {{ticket: AnswersTicket, ctx: AnswersContext, rows: Array<Record<string, any>>, root: string, entry: {base: string | null}, open: Map<string, unknown>, io: AnswersIo, ids: string[], srcBytes: Buffer, byBytes: Buffer, workDir: string}} opts
+ * @returns {Promise<string>}
+ */
+async function packetText({ ticket, ctx, rows, root, entry, open, io, ids, srcBytes, byBytes, workDir }) {
+  const source = ticket.file;
+  const byFile = /** @type {string} */ (ticket.by_file);
+  if (isSecretLike(assertPacketPath(root, source))) throw new Error('secret-like path');
+  const details = findingDetails({ ticket, ctx, rows, root, io });
+  const lines = srcBytes.toString('utf8').split('\n');
+  const diff = await answeringChange({ root, file: byFile, base: entry.base, bytes: byBytes, workDir });
+  const limit = budgetFor(ctx.cfg, 'full_in') * 4;
+  // each finding: its fixed lines, and its free text (null: not recorded) and source excerpt (null: none)
+  const findings = ids.map((id) => {
+    const f = details.get(id) ?? null;
+    const start = Number.isInteger(f?.line_start) ? /** @type {number} */ (f?.line_start) : null;
+    const end = Number.isInteger(f?.line_end) ? /** @type {number} */ (f?.line_end) : start;
+    // the fixed text is redacted before it is measured: the joined packet never grows past its count
+    const head = [`## Finding ${id}`, '', `- file: ${source}`, `- lines: ${start === null ? 'unknown' : `${start}-${end}`}`, `- severity: ${String(f?.severity ?? open.get(id) ?? 'unknown')}`].map(redact);
+    /** @type {Record<typeof FIELDS[number], string | null>} */
+    const text = { claim: null, evidence: null, fix: null };
+    for (const k of FIELDS) text[k] = typeof f?.[k] === 'string' ? redact(f[k]) : null;
+    /** @type {{label: string, text: string} | null} */
+    let excerpt = null;
+    // a range recorded backwards (start after end) shows no lines, whatever the lines around it
+    if (start !== null && end !== null && start <= end && lines.length > 0) {
+      const from = Math.max(1, start - AROUND);
+      const to = Math.min(lines.length, end + AROUND);
+      // a recorded range past the end of the source, or a backwards one, shows no lines
+      if (from <= to) excerpt = { label: redact(`Source lines ${from}-${to}:`), text: redact(lines.slice(from - 1, to).map((l, i) => `${from + i}: ${l}`).join('\n')) };
+    }
+    return { head, text, excerpt };
+  });
+  const intro = [
+    '# Answered findings',
+    '',
+    `A review of \`${source}\` left the findings below open. The coder says the change in \`${byFile}\` resolves them.`,
+    'For EACH finding id, decide whether that change resolves it: `resolved` only when the change clearly removes the problem the finding names; otherwise `not_resolved`. Give a short reason for each.',
+    'Reply with ONE JSON object: {"verdicts": [{"id": string, "verdict": "resolved" | "not_resolved", "reason": string}]}, one entry per id below.',
+    '',
+  ].map(redact);
+  const changeHead = [`## The change in ${byFile}`, '', diff.kind === 'new' ? '(a new file: its full content)' : `(its diff against the block base)`, '```'].map(redact);
+  /**
+   * The packet with these part texts (`parts[i]`: finding i's fields and excerpt) and change.
+   * @param {Array<{claim: string, evidence: string, fix: string, excerpt: string}>} parts @param {string} change
+   */
+  const render = (parts, change) => {
+    const out = [...intro];
+    findings.forEach((f, i) => {
+      out.push(...f.head);
+      for (const k of FIELDS) out.push(`- ${k}: ${f.text[k] === null ? '(not recorded)' : parts[i][k]}`);
+      out.push('');
+      if (f.excerpt !== null) out.push(f.excerpt.label, '```', parts[i].excerpt, '```', '');
+    });
+    out.push(...changeHead, change, '```', '');
+    return out.join('\n');
+  };
+  const fixed = Buffer.byteLength(render(findings.map(() => ({ claim: '', evidence: '', fix: '', excerpt: '' })), ''));
+  if (fixed > limit) throw new PacketTooLarge('the packet fixed text is over the budget');
+  const share = Math.floor((limit - fixed) / 2 / Math.max(1, findings.length));
+  const textCap = Math.floor(share / 5);
+  const sourceCap = share - FIELDS.length * textCap;
+  const parts = findings.map((f) => ({
+    claim: capBytes(f.text.claim ?? '', textCap),
+    evidence: capBytes(f.text.evidence ?? '', textCap),
+    fix: capBytes(f.text.fix ?? '', textCap),
+    excerpt: capBytes(f.excerpt?.text ?? '', sourceCap),
+  }));
+  // the change gets what the fixed text and the findings leave
+  const used = Buffer.byteLength(render(parts, ''));
+  const packet = render(parts, capBytes(redact(diff.text), limit - used));
+  // every piece is redacted and counted: the packet is never cut here, only refused (fail closed)
+  if (Buffer.byteLength(packet) > limit) throw new PacketTooLarge('the packet is over the budget');
+  if (redact(packet) !== packet) throw new Error('a secret across a part boundary');
+  return packet;
+}
+
+/**
+ * The open findings' details from the source's signed fix-loop state (read only, never moved or
+ * restored here). A state that does not load gives none: the packet then names id and severity.
+ * @param {{ticket: AnswersTicket, ctx: AnswersContext, rows: Array<Record<string, any>>, root: string, io: AnswersIo}} opts
+ * @returns {Map<string, Record<string, any>>}
+ */
+function findingDetails({ ticket, ctx, rows, root, io }) {
+  /** @type {Map<string, Record<string, any>>} */
+  const out = new Map();
+  try {
+    const loaded = io.loadState({ runRootDir: ctx.runRootDir, runId: ctx.runId, block: ticket.block, file: ticket.file, key: /** @type {Buffer} */ (ctx.key), rows, contentRoot: root, migrate: false });
+    if (loaded.status !== 'ok' && loaded.status !== 'restored') return out;
+    for (const f of [...(loaded.state?.open ?? []), ...(loaded.state?.late ?? [])]) if (typeof f?.id === 'string' && !out.has(f.id)) out.set(f.id, f);
+  } catch {
+    // no details: id and severity only
+  }
+  return out;
+}