wachiman 1.12.0 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +132 -101
  2. package/bin/wachiman.js +1 -1
  3. package/package.json +2 -3
  4. package/skills/wachiman-loop/SKILL.md +91 -0
  5. package/skills/wachiman-review/SKILL.md +2 -2
  6. package/src/call-message.ts +26 -3
  7. package/src/cli.ts +113 -18
  8. package/src/config.ts +99 -32
  9. package/src/connectors/local-git.ts +102 -14
  10. package/src/cost.ts +48 -1
  11. package/src/doctor/checks.ts +1 -1
  12. package/src/engine.ts +910 -89
  13. package/src/estimate.ts +64 -0
  14. package/src/fidelity/block.ts +263 -0
  15. package/src/fidelity/claims-call.ts +172 -0
  16. package/src/fidelity/claims.ts +69 -0
  17. package/src/fidelity/digest.ts +80 -0
  18. package/src/fidelity/grade.ts +242 -0
  19. package/src/fidelity/inert.ts +25 -0
  20. package/src/fidelity/rules.ts +166 -0
  21. package/src/fidelity/sink.ts +135 -0
  22. package/src/fidelity/summary.ts +16 -0
  23. package/src/fidelity/types.ts +93 -0
  24. package/src/formats.ts +16 -3
  25. package/src/history/fingerprint.ts +1 -1
  26. package/src/history/store.ts +44 -6
  27. package/src/init/options.ts +1 -1
  28. package/src/ledger.ts +306 -0
  29. package/src/local.ts +23 -5
  30. package/src/loop/command.ts +441 -0
  31. package/src/loop/state.ts +88 -0
  32. package/src/loop/stop-rule.ts +98 -0
  33. package/src/providers/claude-code.ts +48 -13
  34. package/src/providers/codex.ts +8 -7
  35. package/src/providers/index.ts +6 -3
  36. package/src/providers/types.ts +13 -3
  37. package/src/sinks/common.ts +3 -3
  38. package/src/sinks/json.ts +13 -2
  39. package/src/skills/install.ts +4 -4
  40. package/src/status/command.ts +1 -1
  41. package/src/store/command.ts +109 -0
  42. package/src/store/figures.ts +153 -0
  43. package/src/store/html.ts +138 -0
  44. package/src/store/index.ts +298 -0
  45. package/templates/caller-workflow.yml +84 -57
  46. package/templates/wachiman-review-caller.yml +13 -0
package/src/engine.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * itself (flags, binary, hardening) lives in `src/providers/`.
5
5
  *
6
6
  * Every kept file is accounted for: reviewed, retried, or listed with a closed reason. Files
7
- * nobody reviews (lockfiles, build output, generated code, `AGENT_REVIEW_EXCLUDE` matches) are
7
+ * nobody reviews (lockfiles, build output, generated code, `WACHIMAN_EXCLUDE` matches) are
8
8
  * dropped first and never read. The rest are scored by risk (`riskScore`) and packed into
9
9
  * batches of about 1,000 changed lines (`planBatches`), riskiest first; each batch is one provider call with its diff
10
10
  * inside the prompt. A batch that leaves files unaccounted for is re-run once with only those
@@ -20,19 +20,35 @@
20
20
  * and the operator's replies and answers in each thread. It never resolves one.
21
21
  *
22
22
  * What to look for beyond the defaults comes from `.github/wachiman.md` when the repository
23
- * has one (`.github/agent-review.md` and `.github/claude-review.md` are still read, with a notice).
23
+ * has one (`.github/claude-review.md` is still read, with a notice).
24
24
  *
25
25
  * The engine holds the GitHub token and posts; the agent only reads and gets no token. The engine
26
26
  * throws, posting nothing, when the provider says any text to post holds a credential. That is
27
27
  * best-effort, not a sandbox: it relies on the consumer repository's trust assumption (only trusted people push).
28
28
  * The command-line entry point is `src/cli.ts`.
29
29
  */
30
- import { NO_USAGE, addUsage, costLine, costLogLine, type CallCost, type Operation, type TokenUsage } from "./cost";
30
+ import { ESTIMATE_NOTE, NO_USAGE, addUsage, costLine, costLogLine, isEstimate, ledgerCall, type CallCost, type Operation, type TokenUsage } from "./cost";
31
31
  import { spawnSync } from "node:child_process";
32
32
  import { closeSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, rmSync, writeFileSync } from "node:fs";
33
33
  import { tmpdir } from "node:os";
34
34
  import { join } from "node:path";
35
- import { isAutomatic, operatorProblem, type EngineConfig, type Trigger } from "./config";
35
+ import { estimateReview, sizeGate, suggestedBudget, type ReviewEstimate } from "./estimate";
36
+ import { isAutomatic, operatorProblem, type EngineConfig, type LimitMode, type Trigger } from "./config";
37
+ import {
38
+ LedgerBadAnswer,
39
+ LedgerNotPermitted,
40
+ LedgerRefused,
41
+ LedgerUnavailable,
42
+ defaultCurl,
43
+ receiptFooter,
44
+ record as ledgerRecord,
45
+ requestIdToken,
46
+ reserve as ledgerReserve,
47
+ settle as ledgerSettle,
48
+ type CurlFn,
49
+ type LedgerEnv,
50
+ type Refusal,
51
+ } from "./ledger";
36
52
  import {
37
53
  EVIDENCE_CAPS,
38
54
  addedLinesOf,
@@ -72,6 +88,24 @@ import {
72
88
  type VerifierVerdict,
73
89
  } from "./verify";
74
90
  import { validate as validateSchema } from "./json-schema";
91
+ import {
92
+ ASSIGNMENTS_SCHEMA,
93
+ CLAIMS_BUDGET_USD,
94
+ CLAIMS_SCHEMA,
95
+ assembleClaims,
96
+ buildClaimsPrompt,
97
+ claimsParagraph,
98
+ claimsTextTruncated,
99
+ parseClaimList,
100
+ type ClaimAssignment,
101
+ type ProposedClaim,
102
+ } from "./fidelity/claims-call";
103
+ import { checkClaims } from "./fidelity/claims";
104
+ import { claimsDigest, claimsInput, stripBlock } from "./fidelity/digest";
105
+ import { buildFidelity } from "./fidelity/grade";
106
+ import { fidelitySummary } from "./fidelity/summary";
107
+ import { publishConfidence } from "./fidelity/sink";
108
+ import type { Fidelity } from "./fidelity/types";
75
109
  import type { ProviderErrorClass } from "./providers/errors";
76
110
  import type { Effort, ProviderAdapter } from "./providers/types";
77
111
  import { renderDataPathQuestions, selectQuestions, type DataPathQuestion } from "./questions";
@@ -197,6 +231,8 @@ export interface ReviewOutput {
197
231
  risk_facts?: RiskFact[];
198
232
  /** The batch's judgement items (ADR 0031). Absent or empty when none apply. */
199
233
  judgement?: JudgementItem[];
234
+ /** The batch's claim assignments (ADR 0033), asked for only when PR Confidence is on; checked by `assembleClaims`. */
235
+ claim_assignments?: ClaimAssignment[];
200
236
  thread_replies: { comment_id: number; status: "addressed" | "still_open"; reply: string }[];
201
237
  summary: string;
202
238
  }
@@ -213,7 +249,8 @@ export interface Review {
213
249
  comments: InlineComment[];
214
250
  }
215
251
 
216
- export type Command = { kind: "review"; paths: string[] } | { kind: "answer" };
252
+ /** `force` is `--force` after `review`: spend past a spent limit. Only the operator's comment may honour it. */
253
+ export type Command = { kind: "review"; paths: string[]; force: boolean } | { kind: "answer" };
217
254
 
218
255
  export const DEFAULT_EXCLUDE = [
219
256
  "**/bun.lock",
@@ -231,8 +268,8 @@ export const DEFAULT_EXCLUDE = [
231
268
  "**/worker-configuration.d.ts",
232
269
  ];
233
270
 
234
- // The old marker is still read so repositories reviewed before the rename keep their incremental state.
235
- const MARKER_SOURCE = "<!-- (?:agent-review|claude-review) sha=([A-Za-z0-9]+) -->";
271
+ // `claude-review` is still read so repositories reviewed under that name keep their incremental state.
272
+ const MARKER_SOURCE = "<!-- (?:wachiman|claude-review) sha=([A-Za-z0-9]+) -->";
236
273
  const short = (sha: string) => sha.slice(0, 7);
237
274
  /**
238
275
  * `Important · 🟠📝 **Fix · docs: stale cell (confidence high)**`: the tier word, both emojis, then
@@ -265,7 +302,7 @@ export const DEFAULT_MENTION = "/wachiman";
265
302
  * earlier handles. Only the default is documented. `/wachi` does not match `/wachiman`, since a
266
303
  * keyword must end a word, so both are listed.
267
304
  */
268
- export const MENTION_ALIASES = ["/wachiman", "/wachi", "@agent-review", "@claude"];
305
+ export const MENTION_ALIASES = ["/wachiman", "/wachi", "@claude"];
269
306
  const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
270
307
 
271
308
  /** The keyword or an alias, as a word of its own: "docs/wachi" or "me@claude" is not a mention. */
@@ -277,7 +314,11 @@ export function parseCommand(body: string, keyword = DEFAULT_MENTION): Command |
277
314
  const match = body.match(new RegExp(`${mentionSource(keyword)}(.*)`));
278
315
  if (!match) return null;
279
316
  const words = match[1].trim().split(/\s+/).filter(Boolean);
280
- if (words[0]?.toLowerCase() === "review") return { kind: "review", paths: words.slice(1) };
317
+ if (words[0]?.toLowerCase() === "review") {
318
+ const rest = words.slice(1);
319
+ // `paths` is every word after `review`, as before the ledger: `comment` drops `--force` from it only when a ledger is set.
320
+ return { kind: "review", paths: rest, force: rest.includes("--force") };
321
+ }
281
322
  return { kind: "answer" };
282
323
  }
283
324
 
@@ -348,7 +389,7 @@ export const isBinaryAtHead = (headDir: string, filename: string) => headContent
348
389
  /**
349
390
  * Splits the kept files into those a model can review and those it cannot. The engine decides it
350
391
  * from the file, never the model: a binary the model skipped as "binary" would leave the review
351
- * partial, and a partial review writes no incremental marker, so every push would be a full review.
392
+ * partial, and a partial review has to carry the file to the next push as an unread one.
352
393
  * A file with a patch is text by definition (GitHub sends none for a binary); one without is read
353
394
  * at the head. One that is not there any more is a binary only when GitHub counted no lines for it
354
395
  * either (`additions` and `deletions` both 0): a removed text file too large for a patch still has
@@ -389,7 +430,7 @@ export function fileKind(path: string): FileKind {
389
430
  /**
390
431
  * Path rules for `riskScore`. These are defaults taken from the first consumer (`ipc`, `preload`,
391
432
  * `main`, `apps/<name>/src`) and are the owner's to tune; per-repository configuration is planned
392
- * (https://github.com/niway-dev/agent-review/issues/5).
433
+ * (https://github.com/niway-dev/wachiman/issues/5).
393
434
  * The highest matching weight wins. A test or a document scores its kind's weight whatever its
394
435
  * path, so `ipc/foo.test.ts` does not outrank the IPC code it tests.
395
436
  */
@@ -660,7 +701,55 @@ export function annotateDiff(files: ReviewFile[]) {
660
701
  return out.join("\n");
661
702
  }
662
703
 
663
- export const marker = (sha: string) => `<!-- agent-review sha=${sha} -->`;
704
+ export const marker = (sha: string) => `<!-- wachiman sha=${sha} -->`;
705
+
706
+ /**
707
+ * What the review at `sha` left for the next run (ADR 0036). A complete review leaves nothing
708
+ * (`rest` is empty). A partial, unscoped one lists the files it did not review (`rest`) and which
709
+ * of those a model was already sent once and did not review (`tried`, a subset of `rest`).
710
+ */
711
+ export interface ReviewState {
712
+ sha: string;
713
+ rest: string[];
714
+ tried: string[];
715
+ }
716
+
717
+ const PARTIAL_SOURCE = "<!-- wachi:partial sha=([A-Za-z0-9]+) state=([A-Za-z0-9_-]+) -->";
718
+
719
+ /**
720
+ * The most characters the partial marker may take. The marker sits in the footer, which the
721
+ * fitting to `MAX_BODY_CHARS` never cuts, so it is capped at a sixth of the body: about 110 files
722
+ * of 65 characters. A longer list writes no partial marker (`partialMarker` returns null).
723
+ */
724
+ export const MAX_PARTIAL_MARKER_CHARS = 10_000;
725
+
726
+ /**
727
+ * The marker a partial review writes: `<!-- wachi:partial sha=… state=… -->`. The state is the
728
+ * JSON `{"r": [files], "t": [indexes into r]}` as base64url, so no file name can end the comment
729
+ * (the alphabet has no `>`, and the comment's text is never read back as text) and any name GitHub
730
+ * allows survives (spaces, unicode, `-->`). Null when the marker would pass `MAX_PARTIAL_MARKER_CHARS`.
731
+ */
732
+ export function partialMarker(state: ReviewState): string | null {
733
+ const index = new Map(state.rest.map((f, i) => [f, i]));
734
+ const tried = state.tried.flatMap((f) => (index.has(f) ? [index.get(f) as number] : []));
735
+ const encoded = Buffer.from(JSON.stringify({ r: state.rest, t: tried }), "utf8").toString("base64url");
736
+ const text = `<!-- wachi:partial sha=${state.sha} state=${encoded} -->`;
737
+ return text.length > MAX_PARTIAL_MARKER_CHARS ? null : text;
738
+ }
739
+
740
+ /** The files and indexes inside a partial marker's state, or null when it is not what `partialMarker` writes. */
741
+ function decodePartialState(sha: string, encoded: string): ReviewState | null {
742
+ try {
743
+ const data = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as { r?: unknown; t?: unknown };
744
+ if (!Array.isArray(data.r) || !Array.isArray(data.t)) return null;
745
+ if (!data.r.every((f) => typeof f === "string")) return null;
746
+ const rest = data.r as string[];
747
+ if (!data.t.every((i) => Number.isInteger(i) && (i as number) >= 0 && (i as number) < rest.length)) return null;
748
+ return { sha, rest, tried: (data.t as number[]).map((i) => rest[i]) };
749
+ } catch {
750
+ return null;
751
+ }
752
+ }
664
753
 
665
754
  /**
666
755
  * Hidden signatures the engine writes outside any model text. With `neutralise` on all model text,
@@ -706,15 +795,16 @@ export const neutralise = (text: string) =>
706
795
  *
707
796
  * <!-- wachi:review -->
708
797
  *
709
- * <!-- agent-review sha=… -->
798
+ * <!-- wachiman sha=… -->
710
799
  *
711
800
  * and the marker is read only as the last line, right after the signature (`postReview` then adds
712
- * its `<!-- wachi:attempt id=… -->` line after it, which is allowed). Anything else
801
+ * its `<!-- wachi:attempt id=… -->` line after it, which is allowed). A partial, unscoped review
802
+ * writes `<!-- wachi:partial sha=… state=… -->` in the marker's place (see `partialMarker`). Anything else
713
803
  * (a marker in the middle of the body, in a file name, in a list) is not the engine's footer, even
714
804
  * if some string slipped past `neutralise`.
715
805
  */
716
806
  const SIGNED_FOOTER = new RegExp(
717
- `\\n\\n${SIGNATURE_REVIEW_SOURCE}\\n\\n${MARKER_SOURCE}(?:\\n\\n${ATTEMPT_SOURCE})?$`,
807
+ `\\n\\n${SIGNATURE_REVIEW_SOURCE}\\n\\n(?:${MARKER_SOURCE}|${PARTIAL_SOURCE})(?:\\n\\n${ATTEMPT_SOURCE})?$`,
718
808
  );
719
809
  /** A review written before signatures existed ended with `</sub>`, a blank line and the marker. */
720
810
  const LEGACY_FOOTER = new RegExp(`</sub>\\n\\n${MARKER_SOURCE}$`);
@@ -726,7 +816,7 @@ const LEGACY_FOOTER = new RegExp(`</sub>\\n\\n${MARKER_SOURCE}$`);
726
816
  * is never read; and the flag is an HTML comment, which `neutralise` defuses in model text.
727
817
  */
728
818
  const AUTO_FOOTER = new RegExp(
729
- `(?:^|\\n\\n)<sub>[^\\n]*\\$(\\d+(?:\\.\\d+)?)</sub>\\n\\n${AUTO_SOURCE}\\n\\n(?:${SIGNATURE_REVIEW_SOURCE}(?:\\n\\n${MARKER_SOURCE})?(?:\\n\\n${ATTEMPT_SOURCE})?|${SIGNATURE_REPLY_SOURCE})$`,
819
+ `(?:^|\\n\\n)<sub>[^\\n]*\\$(\\d+(?:\\.\\d+)?)</sub>\\n\\n${AUTO_SOURCE}\\n\\n(?:${SIGNATURE_REVIEW_SOURCE}(?:\\n\\n(?:${MARKER_SOURCE}|${PARTIAL_SOURCE}))?(?:\\n\\n${ATTEMPT_SOURCE})?|${SIGNATURE_REPLY_SOURCE})$`,
730
820
  );
731
821
 
732
822
  /** The dollars an engine-signed body records as spent by an automatic run, or null when it records none. */
@@ -770,9 +860,21 @@ export function readCeilingNotice(body: string) {
770
860
  return body.trimEnd().match(CEILING_NOTICE)?.[1] ?? null;
771
861
  }
772
862
 
773
- /** The marker in a signed review's footer, or null when the body does not end with that footer. */
863
+ /**
864
+ * What a signed review's footer records: a complete review's marker (nothing left over), or a
865
+ * partial one's list of the files not reviewed. Null when the body does not end with that footer,
866
+ * or its partial state is not one `partialMarker` writes.
867
+ */
868
+ export function readSignedState(body: string): ReviewState | null {
869
+ const found = body.trimEnd().match(SIGNED_FOOTER);
870
+ if (!found) return null;
871
+ if (found[1] !== undefined) return { sha: found[1], rest: [], tried: [] };
872
+ return decodePartialState(found[2], found[3]);
873
+ }
874
+
875
+ /** The commit in a signed review's footer, complete or partial, or null when the body does not end with that footer. */
774
876
  export function readSignedMarker(body: string) {
775
- return body.trimEnd().match(SIGNED_FOOTER)?.[1] ?? null;
877
+ return readSignedState(body)?.sha ?? null;
776
878
  }
777
879
 
778
880
  /** The marker in the footer a review had before signatures existed (see `lastEngineMarker`). */
@@ -990,6 +1092,12 @@ function commitsText(commits: string[] | undefined) {
990
1092
  export const prSoFar = (prior: { spent: number; runs: number }, thisRun: number) =>
991
1093
  `PR so far $${(prior.spent + thisRun).toFixed(2)} over ${countOf(prior.runs + 1, "automatic run")}`;
992
1094
 
1095
+ /** True when this run's dollars are API-price estimates: the engine is on a Claude subscription token (ADR 0037). */
1096
+ const onSubscription = (deps: { provider: ProviderAdapter }) => isEstimate(deps.provider.auth);
1097
+
1098
+ /** After a `<sub>` line of this run's cost and the pull request's total: the same wording as the cost line's. */
1099
+ const estimateTail = (estimate: boolean) => (estimate ? ` · ${ESTIMATE_NOTE}` : "");
1100
+
993
1101
  export function buildReview(input: {
994
1102
  /** A finding's `anchor`, when given (a `ReviewResult`'s), decides inline or body; else its file's patch does. */
995
1103
  output: Omit<ReviewOutput, "findings"> & { findings: (Finding & Partial<Pick<ResultFinding, "anchor" | "origin" | "verification">>)[] };
@@ -1012,6 +1120,8 @@ export function buildReview(input: {
1012
1120
  effort?: string;
1013
1121
  /** An automatic run: its footer gets the flag the pull request's ceiling sums (ADR 0012). */
1014
1122
  automatic?: boolean;
1123
+ /** The ledger's footer lines (receipt, or a note that the run was not counted), written immediately before the cost line. */
1124
+ receiptLine?: string;
1015
1125
  /** The configured mention keyword, for the hint on how to ask for the rest. */
1016
1126
  mention?: string;
1017
1127
  /** Files the engine kept out of `files` because no model can review them (binaries). */
@@ -1027,10 +1137,26 @@ export function buildReview(input: {
1027
1137
  instructionChanges?: { files: string[]; baseSha: string };
1028
1138
  /** The verifier's record (ADR 0027): its outcome goes in the footer's cost line. */
1029
1139
  verification?: ResultVerificationV2;
1140
+ /** The run is on a Claude subscription: its dollar figures are API-price estimates (ADR 0037). */
1141
+ estimate?: boolean;
1030
1142
  /** The risk map (ADR 0031), rendered right after the count line. */
1031
1143
  riskMap?: RiskMap;
1144
+ /** PR Confidence (ADR 0033): the grade as one line after the count line; the description block holds the rest. */
1145
+ fidelity?: Fidelity;
1032
1146
  /** A review of one push to the pull request: the map says it covers that push (ADR 0011). */
1033
1147
  pushOnly?: boolean;
1148
+ /**
1149
+ * The files of `files` reviewed whole because the previous partial review did not reach them
1150
+ * (ADR 0036), named in the headline. Only with `since`.
1151
+ */
1152
+ carried?: string[];
1153
+ /**
1154
+ * The files an earlier run already sent to a model and that came back not reviewed. One that
1155
+ * comes back not reviewed again is named in the notice and left out of the next push's list.
1156
+ */
1157
+ tried?: string[];
1158
+ /** Where the engine's warnings go (a partial marker too long to write). */
1159
+ warn?: (line: string) => void;
1034
1160
  }): Review {
1035
1161
  const { output, files, headSha, since, scoped, costUsd, batches = [], modelLabel, effort } = input;
1036
1162
  const mention = input.mention ?? DEFAULT_MENTION;
@@ -1068,9 +1194,14 @@ export function buildReview(input: {
1068
1194
  const reviewed = new Set(output.files_reviewed);
1069
1195
  const notReviewed = expected.filter((f) => !reviewed.has(f));
1070
1196
  const reasons = new Map(output.files_skipped.map((s) => [s.path, s.reason]));
1071
- const scope = since
1197
+ const carried = new Set((input.carried ?? []).filter((f) => expected.includes(f)));
1198
+ const sinceScope = since
1072
1199
  ? `the changes since \`${short(since)}\`${input.rebased ? " (after a rebase)" : commitsText(input.commits)}`
1073
1200
  : "the whole pull request";
1201
+ const unread = `the ${countOf(carried.size, "file")} the previous review did not reach`;
1202
+ // A resumed review: what changed since, if anything did, and the files the last one left unread.
1203
+ const scope =
1204
+ since && carried.size > 0 ? (carried.size < expected.length ? `${sinceScope} and ${unread}` : unread) : sinceScope;
1074
1205
  const unreviewable = input.unreviewable ?? [];
1075
1206
  const notReviewable =
1076
1207
  unreviewable.length > 0
@@ -1079,9 +1210,20 @@ export function buildReview(input: {
1079
1210
  const parts: string[] = [];
1080
1211
  const list = notReviewed.map((f) => `\`${neutralise(f)}\`${reasons.has(f) ? ` (${neutralise(reasons.get(f) ?? "")})` : ""}`);
1081
1212
  const fullList = list.join(", ");
1213
+ // What the next push carries (ADR 0036). A file that was sent to a model before and came back
1214
+ // not reviewed again, with a reason other than "not reached" (the run never got to it), has had
1215
+ // its two tries: it is named here and no longer carried. A scoped review leaves the list alone.
1216
+ const notReached = (f: string) => (reasons.get(f) ?? "").startsWith("not reached");
1217
+ const priorTried = new Set(input.tried ?? []);
1218
+ const twice = scoped ? [] : notReviewed.filter((f) => priorTried.has(f) && !notReached(f));
1219
+ const rest = scoped ? [] : notReviewed.filter((f) => !twice.includes(f));
1220
+ const twiceNote =
1221
+ twice.length > 0
1222
+ ? ` Not reviewed after two tries, so the next push will not carry ${twice.length === 1 ? "it" : "them"}: ${fitList(twice.map((f) => `\`${neutralise(f)}\``), 2_000)}.`
1223
+ : "";
1082
1224
  if (notReviewed.length > 0) {
1083
1225
  parts.push(
1084
- branded(`⚠️ **Partial review**: the agent reviewed ${expected.length - notReviewed.length} of ${expected.length} files of ${scope}, at \`${short(headSha)}\`. Not reviewed: ${fullList}${notReviewable}. Ask \`${mention} review <paths>\` for the rest.`),
1226
+ branded(`⚠️ **Partial review**: reviewed ${expected.length - notReviewed.length} of ${expected.length} files of ${scope}, at \`${short(headSha)}\`. Not reviewed: ${fullList}${notReviewable}.${twiceNote} Ask \`${mention} review <paths>\` for the rest.`),
1085
1227
  );
1086
1228
  } else {
1087
1229
  parts.push(
@@ -1097,6 +1239,7 @@ export function buildReview(input: {
1097
1239
  parts.push(
1098
1240
  `${countLine(output.findings)}; ${comments.length} on their lines. Reply in a comment's thread to answer it.`,
1099
1241
  );
1242
+ if (input.fidelity) parts.push(fidelitySummary(input.fidelity));
1100
1243
  if (input.verification?.status === "failed") {
1101
1244
  parts.push("⚠️ **Not verified**: the second reader that checks each finding did not finish, so these findings are posted as the review wrote them.");
1102
1245
  } else if (input.verification?.status === "partial") {
@@ -1129,9 +1272,10 @@ export function buildReview(input: {
1129
1272
  `| ${neutralise(b.label)} | ${b.files} | ${b.lines} | ${b.maxRisk} | ${b.status} | ${b.turns} | $${b.costUsd.toFixed(2)} |`,
1130
1273
  );
1131
1274
  parts.push(
1132
- `<details><summary>Coverage by batch</summary>\n\n| Batch | Files | Lines | Highest risk | Status | Turns | Cost |\n| --- | --- | --- | --- | --- | --- | --- |\n${rows.join("\n")}\n\n</details>`,
1275
+ `<details><summary>Coverage by batch</summary>\n\n| Batch | Files | Lines | Highest risk | Status | Turns | Cost${input.estimate ? " (estimate)" : ""} |\n| --- | --- | --- | --- | --- | --- | --- |\n${rows.join("\n")}\n\n</details>`,
1133
1276
  );
1134
1277
  }
1278
+ if (input.receiptLine) parts.push(input.receiptLine);
1135
1279
  parts.push(
1136
1280
  costLine({
1137
1281
  modelLabel,
@@ -1144,14 +1288,26 @@ export function buildReview(input: {
1144
1288
  ...(input.automatic && input.priorSpend ? [prSoFar(input.priorSpend, costUsd)] : []),
1145
1289
  ],
1146
1290
  usage: input.usage,
1291
+ estimate: input.estimate,
1147
1292
  costUsd,
1148
1293
  }),
1149
1294
  );
1150
1295
  if (input.automatic) parts.push(SIGNATURE.auto);
1151
1296
  parts.push(SIGNATURE.review);
1152
- // The next `review` request starts from this commit, so only a review that covered everything
1153
- // may move it; a scoped or partial one would leave the rest never reviewed.
1154
- if (!scoped && notReviewed.length === 0) parts.push(marker(headSha));
1297
+ // The next `review` request starts from this commit. A review that covered everything moves it
1298
+ // (the complete marker). A partial one moves it too, and lists what it did not reach, so the next
1299
+ // push reviews those files (ADR 0036). A scoped review writes neither: it read only the paths
1300
+ // asked for, so the last unscoped review's commit and list stay as they were.
1301
+ if (!scoped) {
1302
+ const tried = rest.filter((f) => priorTried.has(f) || !notReached(f));
1303
+ const state = rest.length > 0 ? partialMarker({ sha: headSha, rest, tried }) : null;
1304
+ if (rest.length === 0) parts.push(marker(headSha));
1305
+ else if (state !== null) parts.push(state);
1306
+ else
1307
+ input.warn?.(
1308
+ `${rest.length} file(s) not reviewed do not fit in a partial marker (more than ${MAX_PARTIAL_MARKER_CHARS} characters): none is written, so the next push reviews the whole pull request again.`,
1309
+ );
1310
+ }
1155
1311
  // A part another text replaces (or `null`, none) while the body is being fitted.
1156
1312
  const replaced = new Map<number, string | null>();
1157
1313
  const render = () =>
@@ -1454,8 +1610,8 @@ empty list. Cite only lines you read: the engine checks that each cited line exi
1454
1610
  answer is true. When an answer shows a defect, report it as a finding as well.`;
1455
1611
 
1456
1612
  export const FOCUS_PATH = ".github/wachiman.md";
1457
- /** The paths used before the rename, newest first; the first one found is still read, with a notice. */
1458
- export const OLD_FOCUS_PATHS = [".github/agent-review.md", ".github/claude-review.md"] as const;
1613
+ /** The path used before the rename; it is still read when the focus file is absent, with a notice. */
1614
+ export const OLD_FOCUS_PATHS = [".github/claude-review.md"] as const;
1459
1615
 
1460
1616
  /** Repository rules the engine reads from the pull request's base commit, in prompt order. */
1461
1617
  export const INSTRUCTION_PATHS = [FOCUS_PATH, "CLAUDE.md", "AGENTS.md"] as const;
@@ -1682,6 +1838,12 @@ export interface Deps extends CoreDeps {
1682
1838
  * current directory.
1683
1839
  */
1684
1840
  repoDir?: string;
1841
+ /** Runs `curl` for the spend ledger; swapped for a fake in tests. Default: the real `curl`. */
1842
+ curl?: CurlFn;
1843
+ /** Where the id-token request variables come from. Default: `process.env`. */
1844
+ ledgerEnv?: LedgerEnv;
1845
+ /** What the ledger did or could not do in this run, one line each: the CLI writes them into the job summary. */
1846
+ ledgerNotes?: string[];
1685
1847
  }
1686
1848
 
1687
1849
  const blockingSleep = (ms: number) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -1702,7 +1864,8 @@ export function listFiles(gh: GhFn, repo: string, pr: number): ReviewFile[] {
1702
1864
  }
1703
1865
 
1704
1866
  /**
1705
- * The commit the last Wachi review covered. A review is Wachi's when `github-actions[bot]` wrote
1867
+ * The commit the last Wachi review covered, complete or partial (a partial review's marker also
1868
+ * lists the files it did not reach; `lastReviewState` returns them). A review is Wachi's when `github-actions[bot]` wrote
1706
1869
  * it AND it carries the review signature: that login is shared by every workflow of the
1707
1870
  * repository, so the login alone proves nothing. The marker counts only at the footer position
1708
1871
  * (see `readSignedMarker`).
@@ -1713,7 +1876,16 @@ export function listFiles(gh: GhFn, repo: string, pr: number): ReviewFile[] {
1713
1876
  * ones are another workflow's and are ignored. Drop the unsigned branch once the cutoff has passed.
1714
1877
  */
1715
1878
  export function lastReviewedSha(gh: GhFn, repo: string, pr: number) {
1716
- return lastEngineMarker(
1879
+ return lastReviewState(gh, repo, pr)?.sha ?? null;
1880
+ }
1881
+
1882
+ /**
1883
+ * What the last Wachi review left for the next run (see `lastReviewedSha` for which reviews count):
1884
+ * its commit and, for a partial review, the files it did not reach. The commit alone is enough for
1885
+ * a run that only answers threads. The push path reads the files too (`review`).
1886
+ */
1887
+ export function lastReviewState(gh: GhFn, repo: string, pr: number) {
1888
+ return lastEngineState(
1717
1889
  botReviews(gh, repo, pr).map((r) => ({ body: r.body, created_at: r.submitted_at })),
1718
1890
  );
1719
1891
  }
@@ -1728,15 +1900,21 @@ function botReviews(gh: GhFn, repo: string, pr: number) {
1728
1900
  return reviews.map((r) => ({ body: r.body ?? "", submitted_at: r.submitted_at ?? undefined }));
1729
1901
  }
1730
1902
 
1731
- /** The marker of the last review the engine wrote, among `github-actions[bot]` reviews in order. */
1732
- export function lastEngineMarker(reviews: { body: string; created_at?: string }[]) {
1903
+ /** The state of the last review the engine wrote, among `github-actions[bot]` reviews in order. */
1904
+ export function lastEngineState(reviews: { body: string; created_at?: string }[]): ReviewState | null {
1733
1905
  const firstSigned = reviews.findIndex((r) => r.body.includes(SIGNATURE.review));
1734
- const found = reviews.map((r, i) => {
1735
- if (r.body.includes(SIGNATURE.review)) return readSignedMarker(r.body);
1906
+ const found = reviews.map((r, i): ReviewState | null => {
1907
+ if (r.body.includes(SIGNATURE.review)) return readSignedState(r.body);
1736
1908
  const legacy = (firstSigned === -1 || i < firstSigned) && beforeLegacyCutoff(r.created_at);
1737
- return legacy ? readLegacyMarker(r.body) : null;
1909
+ const sha = legacy ? readLegacyMarker(r.body) : null;
1910
+ return sha === null ? null : { sha, rest: [], tried: [] };
1738
1911
  });
1739
- return found.filter((m): m is string => m !== null).at(-1) ?? null;
1912
+ return found.filter((m): m is ReviewState => m !== null).at(-1) ?? null;
1913
+ }
1914
+
1915
+ /** The commit of the last review the engine wrote, complete or partial, among `github-actions[bot]` reviews in order. */
1916
+ export function lastEngineMarker(reviews: { body: string; created_at?: string }[]) {
1917
+ return lastEngineState(reviews)?.sha ?? null;
1740
1918
  }
1741
1919
 
1742
1920
  export interface Comparison {
@@ -2214,7 +2392,7 @@ export function ceilingRoom(
2214
2392
  postReview(deps, repo, pr, headSha, {
2215
2393
  body: [
2216
2394
  branded(
2217
- `Automatic reviews paused: $${spent.toFixed(2)} of $${ceiling.toFixed(2)} spent on this pull request. Comment \`${config.mention} review\` to review now.`,
2395
+ `Automatic reviews paused: $${spent.toFixed(2)} of $${ceiling.toFixed(2)} spent on this pull request. Comment \`${config.mention} review\` to review now.${onSubscription(deps) ? " These reviews run on a Claude subscription, so the dollars are API-equivalent estimates, not a bill." : ""}`,
2218
2396
  ),
2219
2397
  SIGNATURE.review,
2220
2398
  ceilingFooter(ceiling),
@@ -2224,6 +2402,361 @@ export function ceilingRoom(
2224
2402
  return null;
2225
2403
  }
2226
2404
 
2405
+ // ---------------------------------------------------------------------------------------------
2406
+ // The spend ledger: ask before the first model call, say what was spent after the last.
2407
+
2408
+ /** A limit refused the run: the account's daily or weekly limit, or this repository's own. `mode` is the caller's `limit_mode`. */
2409
+ export class SpendLimitReached extends Error {
2410
+ constructor(
2411
+ readonly refusal: Refusal,
2412
+ readonly mode: LimitMode,
2413
+ message: string,
2414
+ ) {
2415
+ super(message);
2416
+ }
2417
+ }
2418
+
2419
+ /**
2420
+ * The run was stopped before any model call for a ledger reason that is not a limit: the
2421
+ * repository is not linked, the ledger does not accept the job's identity, the job cannot request
2422
+ * an OIDC token, or the ledger is unreachable and `ledger_unavailable` is `stop`. The message says
2423
+ * what to fix.
2424
+ */
2425
+ export class LedgerStopped extends Error {}
2426
+
2427
+ /** What a run may spend after asking the ledger, and what the run still owes it. */
2428
+ export interface SpendGrant {
2429
+ /** `none`: no ledger. `bypassed`: `limit_bypass`. `reserved`: the ledger granted `roomUsd`. `unreached`: it could not be asked. */
2430
+ kind: "none" | "bypassed" | "reserved" | "unreached";
2431
+ reservationId: string | null;
2432
+ roomUsd: number;
2433
+ /** What the ledger granted: only for a `reserved` grant. */
2434
+ reservedUsd?: number;
2435
+ /** Reserved with `forced`: the footer says so, next to the receipt. */
2436
+ forced?: boolean;
2437
+ /** Where this run's calls start in `deps.costs`: the settle sends the calls from here on. */
2438
+ costsFrom: number;
2439
+ trigger: string;
2440
+ pr: number;
2441
+ }
2442
+
2443
+ /** Written where the receipt would be when a repository skips the ledger. */
2444
+ export const LEDGER_BYPASSED_FOOTER = "<!-- wachi:ledger bypassed -->";
2445
+
2446
+ /** Written next to the receipt of a `/wachiman review --force` run, which may pass a limit. */
2447
+ export const LEDGER_FORCED_FOOTER = "<!-- wachi:forced -->";
2448
+
2449
+ /** The footer line of a run the ledger could not count. */
2450
+ export const LEDGER_NOT_COUNTED_NOTE = "<sub>Not counted against the spend limit: the ledger could not be reached.</sub>";
2451
+
2452
+ /** The footer line of a run that skipped the ledger. */
2453
+ export const LEDGER_BYPASSED_NOTE = "<sub>Spend limit bypassed for this repository (`limit_bypass`).</sub>";
2454
+
2455
+ /**
2456
+ * The notice posted when a limit refuses a run, once per pull request per limit and period. Its
2457
+ * footer names the reason and the day or week it was posted for, so a second run in the same
2458
+ * period posts nothing.
2459
+ */
2460
+ const LIMIT_SOURCE = "<!-- wachi:limit reason=(limit|weekly_limit|repository_limit) on=(\\d{4}-\\d{2}-\\d{2}) -->";
2461
+ export const limitFooter = (reason: string, on: string) => `<!-- wachi:limit reason=${reason} on=${on} -->`;
2462
+ const LIMIT_NOTICE = new RegExp(`\\n\\n${SIGNATURE_REVIEW_SOURCE}\\n\\n${LIMIT_SOURCE}(?:\\n\\n${ATTEMPT_SOURCE})?$`);
2463
+
2464
+ /** `reason:on` of a signed limit notice, or null when the body is not one. */
2465
+ export function readLimitNotice(body: string) {
2466
+ const match = body.trimEnd().match(LIMIT_NOTICE);
2467
+ return match ? `${match[1]}:${match[2]}` : null;
2468
+ }
2469
+
2470
+ const usd = (value: number) => `$${value.toFixed(2)}`;
2471
+ const DAY_MS = 86_400_000;
2472
+
2473
+ /** The Monday (`YYYY-MM-DD`, UTC) of the week `ms` falls in. */
2474
+ const mondayOf = (ms: number) => new Date(Math.floor(ms / DAY_MS) * DAY_MS - ((new Date(ms).getUTCDay() + 6) % 7) * DAY_MS).toISOString().slice(0, 10);
2475
+
2476
+ /** The period a refusal is about: the weekly limit is a week, the account's daily limit a day, the repository's follows `period`. */
2477
+ const periodOf = (refusal: Refusal) => (refusal.reason === "weekly_limit" ? "week" : refusal.reason === "limit" ? "day" : (refusal.period ?? "day"));
2478
+
2479
+ /** `00:00 UTC (in 5 h 12 min)`, or with the date and days for a week: the reset the ledger named, relative to now. */
2480
+ function resetText(deps: Deps, refusal: Refusal) {
2481
+ const now = (deps.now ?? Date.now)();
2482
+ const period = periodOf(refusal);
2483
+ const named = refusal.resetsAt ? Date.parse(refusal.resetsAt) : Number.NaN;
2484
+ const reset = Number.isNaN(named)
2485
+ ? period === "week"
2486
+ ? Date.parse(mondayOf(now)) + 7 * DAY_MS
2487
+ : Math.floor(now / DAY_MS + 1) * DAY_MS
2488
+ : named;
2489
+ const stamp = new Date(reset).toISOString();
2490
+ const minutes = Math.max(0, Math.floor((reset - now) / 60_000));
2491
+ const hours = Math.floor(minutes / 60);
2492
+ const left = hours >= 24 ? `${Math.floor(hours / 24)} d ${hours % 24} h` : `${hours} h ${minutes % 60} min`;
2493
+ return `${period === "week" ? `${stamp.slice(0, 10)} ` : ""}${stamp.slice(11, 16)} UTC (in ${left})`;
2494
+ }
2495
+
2496
+ /** What the notice says was reached, how much was spent against which limit, in the words of its period. */
2497
+ function limitSentence(deps: Deps, refusal: Refusal) {
2498
+ const period = periodOf(refusal);
2499
+ const when = period === "week" ? "this week" : "today";
2500
+ const against =
2501
+ refusal.accountSpentUsd !== undefined && refusal.accountLimitUsd !== undefined
2502
+ ? `the account has spent **${usd(refusal.accountSpentUsd)} of ${usd(refusal.accountLimitUsd)}** ${when} across its repositories`
2503
+ : undefined;
2504
+ const estimate = onSubscription(deps) ? ` ${ESTIMATE_NOTE}.` : "";
2505
+ if (refusal.reason === "repository_limit") {
2506
+ // The figures the ledger names with this reason are the account's, not the repository's: not shown.
2507
+ const own = period === "week" ? "weekly" : "daily";
2508
+ return `This repository reached its own ${own} limit (\`${period === "week" ? "weekly_budget_usd" : "daily_budget_usd"}\` in the workflow, or the cap the account sets for this repository).${estimate}`;
2509
+ }
2510
+ const name = refusal.reason === "weekly_limit" ? "weekly" : "daily";
2511
+ return against
2512
+ ? `The ${name} spend limit is reached: ${against}.${estimate}`
2513
+ : `The ${name} spend limit is reached.${estimate}`;
2514
+ }
2515
+
2516
+ function postLimitNotice(deps: Deps, repo: string, pr: number, headSha: string, refusal: Refusal) {
2517
+ const now = (deps.now ?? Date.now)();
2518
+ const week = periodOf(refusal) === "week";
2519
+ const on = (week ? refusal.week : refusal.day) ?? (week ? mondayOf(now) : new Date(now).toISOString().slice(0, 10));
2520
+ const key = `${refusal.reason}:${on}`;
2521
+ const jq = '.[] | select(.user.login == "github-actions[bot]") | {body} | @json';
2522
+ const told = jsonLines<{ body: string | null }>(deps.gh(["api", "--paginate", `repos/${repo}/pulls/${pr}/reviews`, "--jq", jq])).some(
2523
+ (r) => readLimitNotice(r.body ?? "") === key,
2524
+ );
2525
+ if (told) {
2526
+ deps.log(`A spend limit is reached and this pull request already has its notice (${key}); posting none.`);
2527
+ return;
2528
+ }
2529
+ postReview(deps, repo, pr, headSha, {
2530
+ body: [
2531
+ branded(
2532
+ `**Spend limit reached.** ${limitSentence(deps, refusal)} It resets at **${resetText(deps, refusal)}**. To review this pull request now, comment \`${deps.config.mention} review --force\`. To change a limit, edit the account in the ledger; to let this repository ignore the ledger, set \`limit_bypass: true\` (at your own risk).`,
2533
+ ),
2534
+ SIGNATURE.review,
2535
+ limitFooter(refusal.reason, on),
2536
+ ].join("\n\n"),
2537
+ comments: [],
2538
+ });
2539
+ }
2540
+
2541
+ const ledgerNote = (deps: Deps, note: string) => void deps.ledgerNotes?.push(note);
2542
+ const short200 = (error: unknown) => (error instanceof Error ? error.message : String(error)).slice(0, 200);
2543
+
2544
+ /** The dollars the calls since `grant` cost, for a run that ended before it could say what it spent. */
2545
+ export const spentSince = (deps: Deps, grant: SpendGrant) => (deps.costs ?? []).slice(grant.costsFrom).reduce((n, c) => n + c.costUsd, 0);
2546
+
2547
+ /**
2548
+ * Asks the ledger how much this run may spend, before any model call. With no `ledger_url` there is
2549
+ * nothing to ask and the room is unlimited; `limit_bypass` skips the ledger the same way, and the
2550
+ * footer says so. A refusal for a limit posts the notice (once per period per pull request) and
2551
+ * throws `SpendLimitReached`. A repository the ledger does not know, an identity it does not
2552
+ * accept and a job without an OIDC token are configuration errors: `LedgerStopped`, whatever
2553
+ * `ledger_unavailable` says. A ledger that cannot be reached lets the run go on under its normal
2554
+ * budgets (`unreached`), or stops it with `LedgerStopped` when `ledger_unavailable` is `stop`.
2555
+ */
2556
+ export function spendReserve(deps: Deps, repo: string, pr: number, headSha: string, wantedUsd: number, forced: boolean): SpendGrant {
2557
+ const { config } = deps;
2558
+ const open = { reservationId: null, roomUsd: Number.POSITIVE_INFINITY, costsFrom: deps.costs?.length ?? 0, trigger: config.trigger ?? "cli", pr };
2559
+ if (!config.ledgerUrl) return { kind: "none", ...open };
2560
+ if (config.limitBypass) {
2561
+ deps.log("ledger bypassed");
2562
+ ledgerNote(deps, "The spend limit was bypassed for this run (`limit_bypass`); nothing was reserved or recorded.");
2563
+ return { kind: "bypassed", ...open };
2564
+ }
2565
+ const curl = deps.curl ?? defaultCurl;
2566
+ try {
2567
+ const token = requestIdToken(deps.ledgerEnv ?? process.env, config.ledgerUrl, curl);
2568
+ const granted = ledgerReserve(
2569
+ config.ledgerUrl,
2570
+ token,
2571
+ {
2572
+ wantedUsd,
2573
+ callerLimitUsd: config.dailyBudgetUsd,
2574
+ callerWeeklyLimitUsd: config.weeklyBudgetUsd,
2575
+ trigger: open.trigger,
2576
+ forced,
2577
+ pr,
2578
+ },
2579
+ curl,
2580
+ );
2581
+ return { kind: "reserved", ...open, reservationId: granted.reservationId, roomUsd: granted.grantedUsd, reservedUsd: granted.grantedUsd, ...(forced ? { forced: true } : {}) };
2582
+ } catch (error) {
2583
+ if (error instanceof LedgerRefused) {
2584
+ const { reason } = error.refusal;
2585
+ if (reason === "limit" || reason === "weekly_limit" || reason === "repository_limit") {
2586
+ postLimitNotice(deps, repo, pr, headSha, error.refusal);
2587
+ const message = limitSentence(deps, error.refusal).replace(/\*\*/g, "");
2588
+ ledgerNote(deps, `A spend limit refused this run before any model call: ${message}`);
2589
+ throw new SpendLimitReached(error.refusal, config.limitMode, message);
2590
+ }
2591
+ const message =
2592
+ reason === "not_linked"
2593
+ ? "This repository is not linked to a ledger account, so nothing was reviewed. Ask the ledger's operator to link it, or remove `ledger_url` (or set `limit_bypass: true`)."
2594
+ : "The ledger did not accept this job's identity token, so nothing was reviewed. Check that `ledger_url` is the ledger's address, and that the ledger knows this repository.";
2595
+ ledgerNote(deps, message);
2596
+ throw new LedgerStopped(message);
2597
+ }
2598
+ if (error instanceof LedgerBadAnswer) {
2599
+ // A wrong address or a broken service, not an outage: `ledger_unavailable` does not apply.
2600
+ ledgerNote(deps, error.message);
2601
+ throw new LedgerStopped(error.message);
2602
+ }
2603
+ if (error instanceof LedgerNotPermitted) {
2604
+ const message =
2605
+ "`ledger_url` is set, but this job cannot request an OIDC token, so nothing was reviewed. Call `.github/workflows/review-platform.yml` instead of `review.yml`, and grant `id-token: write` in the caller's job (docs/install.md).";
2606
+ ledgerNote(deps, message);
2607
+ throw new LedgerStopped(message);
2608
+ }
2609
+ if (error instanceof LedgerUnavailable) {
2610
+ if (config.ledgerUnavailable === "stop") {
2611
+ const message = `The spend ledger could not be reached (${short200(error)}) and \`ledger_unavailable\` is \`stop\`, so nothing was reviewed. Re-run later, or set \`ledger_unavailable: run\` to review without it.`;
2612
+ ledgerNote(deps, message);
2613
+ throw new LedgerStopped(message);
2614
+ }
2615
+ deps.warn(`The spend ledger could not be reached; reviewing under the normal budgets: ${short200(error)}`);
2616
+ return { kind: "unreached", ...open };
2617
+ }
2618
+ throw error;
2619
+ }
2620
+ }
2621
+
2622
+ /**
2623
+ * Tells the ledger what the run spent, with the calls it made, and returns the footer lines for the
2624
+ * review (joined by a blank line), or null when there is nothing to say. Nothing here fails the
2625
+ * run. After a reservation: the signed receipt (a failed settle leaves the reservation counted at
2626
+ * the reserved amount, and the job summary says so). After an unreachable ledger: the run is
2627
+ * recorded once, apart from reserved runs; the footer says it was not counted, and the job summary
2628
+ * says whether it was recorded. A forced run's lines also carry the forced footer.
2629
+ */
2630
+ export function spendSettle(deps: Deps, grant: SpendGrant, spentUsd: number): string | null {
2631
+ const { ledgerUrl } = deps.config;
2632
+ if (grant.kind === "bypassed") return `${LEDGER_BYPASSED_NOTE}\n\n${LEDGER_BYPASSED_FOOTER}`;
2633
+ if (grant.kind === "none" || !ledgerUrl) return null;
2634
+ const curl = deps.curl ?? defaultCurl;
2635
+ const calls = (deps.costs ?? []).slice(grant.costsFrom).map(ledgerCall);
2636
+ if (grant.kind === "unreached") {
2637
+ try {
2638
+ ledgerRecord(ledgerUrl, requestIdToken(deps.ledgerEnv ?? process.env, ledgerUrl, curl), { spentUsd, calls, trigger: grant.trigger, pr: grant.pr }, curl);
2639
+ ledgerNote(deps, "This run was not counted against the spend limit because the ledger could not be reached when it started. It was recorded afterwards, apart from reserved runs.");
2640
+ } catch (error) {
2641
+ deps.warn(`Could not record the run with the ledger: ${short200(error)}`);
2642
+ ledgerNote(deps, "This run was not counted against the spend limit because the ledger could not be reached, and it was not recorded: the ledger has no entry for it.");
2643
+ }
2644
+ return LEDGER_NOT_COUNTED_NOTE;
2645
+ }
2646
+ try {
2647
+ // A fresh token: a long run can outlive the one `spendReserve` used.
2648
+ const token = requestIdToken(deps.ledgerEnv ?? process.env, ledgerUrl, curl);
2649
+ const { receipt, signature } = ledgerSettle(ledgerUrl, token, grant.reservationId!, spentUsd, calls, curl);
2650
+ const line = receiptFooter(receipt, signature);
2651
+ return grant.forced ? `${line}\n\n${LEDGER_FORCED_FOOTER}` : line;
2652
+ } catch (error) {
2653
+ deps.warn(`Could not settle with the ledger; the reservation stays counted: ${short200(error)}`);
2654
+ ledgerNote(deps, `The settlement was not delivered: the ledger could not be reached after the run, so its reservation of ${usd(grant.reservedUsd ?? 0)} stays counted instead of the ${usd(spentUsd)} spent.${onSubscription(deps) ? ` ${ESTIMATE_NOTE}.` : ""} The review is posted.`);
2655
+ return grant.forced ? LEDGER_FORCED_FOOTER : null;
2656
+ }
2657
+ }
2658
+
2659
+ /**
2660
+ * Whether the ledger granted less than a call needs (the minimum the review path also uses). When
2661
+ * so, the run makes no model call: it settles with 0, so the reservation is released, and the job
2662
+ * summary says so. Only a reserved grant can be this small: with no ledger the room is unlimited.
2663
+ */
2664
+ function grantTooSmall(deps: Deps, grant: SpendGrant, what: string): boolean {
2665
+ if (grant.kind !== "reserved" || grant.roomUsd >= MIN_BATCH_USD) return false;
2666
+ spendSettle(deps, grant, 0);
2667
+ ledgerNote(
2668
+ deps,
2669
+ `The ledger granted ${usd(grant.roomUsd)}, below the ${usd(MIN_BATCH_USD)} a call needs, so ${what} made no model call and settled with $0.00.${onSubscription(deps) ? ` ${ESTIMATE_NOTE}.` : ""}`,
2670
+ );
2671
+ deps.log(`The ledger granted ${usd(grant.roomUsd)}, below the minimum for ${what}; no model call.`);
2672
+ return true;
2673
+ }
2674
+
2675
+ /** Runs a paid step; if it throws, the ledger still hears what the calls so far cost, then the error goes on. */
2676
+ function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => T): T {
2677
+ try {
2678
+ return run();
2679
+ } catch (error) {
2680
+ spendSettle(deps, grant, spentSince(deps, grant));
2681
+ throw error;
2682
+ }
2683
+ }
2684
+
2685
+ /** The estimate of reviewing `files` with this configuration: the batches `planBatches` makes, priced per batch. */
2686
+ export function estimateFor(files: ReviewFile[], config: EngineConfig): ReviewEstimate {
2687
+ const batches = planBatches(files, { maxLines: config.batchLines, maxChars: config.batchChars }).length;
2688
+ return estimateReview(files, { batches, batchBudgetUsd: config.batchBudgetUsd, model: config.model });
2689
+ }
2690
+
2691
+ /** The hidden marker of the size-gate comment, so the next push updates it instead of adding another. */
2692
+ export const SIZE_GATE_MARKER = "<!-- wachi:size-gate -->";
2693
+
2694
+ const usd2 = (n: number) => `$${n.toFixed(2)}`;
2695
+ const count = (n: number) => n.toLocaleString("en-US");
2696
+
2697
+ /**
2698
+ * The comment that says a pull request was not reviewed because its estimate is above the size
2699
+ * gate (nothing was sent to a model), what the estimate rests on, and the inputs that lift it.
2700
+ */
2701
+ export function sizeGateBody(o: {
2702
+ estimate: ReviewEstimate;
2703
+ gate: number;
2704
+ headSha: string;
2705
+ mention: string;
2706
+ model: string;
2707
+ }): string {
2708
+ const { estimate: e, gate, headSha, mention, model } = o;
2709
+ const budget = suggestedBudget(e.usd);
2710
+ return [
2711
+ branded(
2712
+ `**Not reviewed: this pull request is above the size gate.** Reviewing all of it would cost about **${usd2(e.usd)}**, and the gate is **${usd2(gate)}**, so nothing was sent to a model and nothing was spent.`,
2713
+ ),
2714
+ `The estimate: ${count(e.batches)} batches × ${usd2(e.perBatchUsd)} a batch for \`${model}\` (${count(e.files)} files, ${count(e.lines)} changed lines), from the diff alone, before any model call. It can be off by about 40% either way.`,
2715
+ `To review the whole pull request, set the run budget in the workflow that calls Wachiman, then comment \`${mention} review\`:`,
2716
+ ["```yaml", " with:", ` budget_usd: ${budget}`, "```"].join("\n"),
2717
+ `A \`budget_usd\` at or above the estimate lifts the gate for that run. To have pushes reviewed automatically as well, also set \`auto_budget_usd: ${budget}\`. To review part of it now, comment \`${mention} review <path> [path…]\`.`,
2718
+ `<sub>Estimated at \`${short(headSha)}\`. This comment is updated on each push instead of a new one.</sub>`,
2719
+ SIZE_GATE_MARKER,
2720
+ ].join("\n\n");
2721
+ }
2722
+
2723
+ /**
2724
+ * Posts the size-gate comment, or updates the one already there. Only the bot's own comments are
2725
+ * looked at, so a person cannot plant the marker. The comment has no cost line, so
2726
+ * `automaticSpend` does not count it.
2727
+ */
2728
+ export function postSizeGateNotice(
2729
+ deps: Deps,
2730
+ repo: string,
2731
+ pr: number,
2732
+ headSha: string,
2733
+ estimate: ReviewEstimate,
2734
+ gate: number,
2735
+ ) {
2736
+ const { config } = deps;
2737
+ const body = sizeGateBody({
2738
+ estimate,
2739
+ gate,
2740
+ headSha,
2741
+ mention: config.mention,
2742
+ model: config.model,
2743
+ });
2744
+ if (config.dryRun) {
2745
+ deps.log("--- size gate comment ---\n" + body);
2746
+ return;
2747
+ }
2748
+ const jq = '.[] | select(.user.login == "github-actions[bot]") | {id, body} | @json';
2749
+ const existing = jsonLines<{ id: number; body: string | null }>(
2750
+ deps.gh(["api", "--paginate", `repos/${repo}/issues/${pr}/comments`, "--jq", jq]),
2751
+ ).filter((c) => (c.body ?? "").includes(SIZE_GATE_MARKER));
2752
+ const last = existing[existing.length - 1];
2753
+ if (last) {
2754
+ deps.gh(["api", "-X", "PATCH", `repos/${repo}/issues/comments/${last.id}`, "-f", `body=${body}`]);
2755
+ return;
2756
+ }
2757
+ deps.gh(["pr", "comment", String(pr), "-R", repo, "--body-file", "-"], body);
2758
+ }
2759
+
2227
2760
  /** Waits before the 1st and 2nd retry of a review POST GitHub answered with a transient error. */
2228
2761
  export const REVIEW_RETRY_DELAYS_MS = [1_000, 3_000];
2229
2762
 
@@ -2257,18 +2790,30 @@ function reviewLanded(deps: Deps, repo: string, pr: number, attemptId: string) {
2257
2790
  return reviews.some((r) => (r.body ?? "").trimEnd().endsWith(attemptFooter(attemptId)));
2258
2791
  }
2259
2792
 
2260
- export function postReview(deps: Deps, repo: string, pr: number, headSha: string, review: Review) {
2793
+ /** The address of the review GitHub created, from the answer to the POST; undefined when it said none. */
2794
+ function reviewUrlOf(answer: string): string | undefined {
2795
+ try {
2796
+ const url = (JSON.parse(answer) as { html_url?: unknown }).html_url;
2797
+ return typeof url === "string" && url.startsWith("https://") ? url : undefined;
2798
+ } catch {
2799
+ return undefined;
2800
+ }
2801
+ }
2802
+
2803
+ /** Posts the review. Returns its address when GitHub gave one (the description block links to it). */
2804
+ export function postReview(deps: Deps, repo: string, pr: number, headSha: string, review: Review): string | undefined {
2261
2805
  if (deps.config.dryRun) {
2262
2806
  deps.log(`--- review at ${short(headSha)} ---\n${review.body}`);
2263
2807
  for (const c of review.comments) deps.log(`--- ${c.path}:${c.line} ---\n${c.body}`);
2264
- return;
2808
+ return undefined;
2265
2809
  }
2810
+ let url: string | undefined;
2266
2811
  const sleep = deps.sleep ?? blockingSleep;
2267
2812
  // One id for this call: the retries and the fallback are the same attempt, and an older review
2268
2813
  // of the same head does not carry it.
2269
2814
  const attemptId = crypto.randomUUID();
2270
- const send = (r: Review) =>
2271
- deps.gh(
2815
+ const send = (r: Review) => {
2816
+ const answer = deps.gh(
2272
2817
  ["api", "-X", "POST", `repos/${repo}/pulls/${pr}/reviews`, "--input", "-"],
2273
2818
  JSON.stringify({
2274
2819
  commit_id: headSha,
@@ -2277,6 +2822,8 @@ export function postReview(deps: Deps, repo: string, pr: number, headSha: string
2277
2822
  comments: r.comments,
2278
2823
  }),
2279
2824
  );
2825
+ url = reviewUrlOf(answer);
2826
+ };
2280
2827
  // A transient error may hide a POST that did land, so look before each retry.
2281
2828
  const sendWithRetry = (r: Review) => {
2282
2829
  for (let retry = 0; ; retry++) {
@@ -2306,6 +2853,7 @@ export function postReview(deps: Deps, repo: string, pr: number, headSha: string
2306
2853
  deps.warn(`GitHub refused the inline comments; posting them in the body. ${error}`);
2307
2854
  sendWithRetry(moveCommentsToBody(review));
2308
2855
  }
2856
+ return url;
2309
2857
  }
2310
2858
 
2311
2859
  /**
@@ -2348,6 +2896,13 @@ export interface ReviewOptions {
2348
2896
  * finding above `info`. Its money is reserved out of `totalBudgetUsd` before the batches run.
2349
2897
  */
2350
2898
  verify?: { model: string; budgetUsd: number };
2899
+ /**
2900
+ * PR Confidence (ADR 0033): for a pull request, one small call first lists the claims in its
2901
+ * title and body, every batch says which claim each of its files serves, and the engine computes
2902
+ * the grade into `result.fidelity`. Set by the pull request review for a full review only, never
2903
+ * by `reviewOptionsOf`: a local review and an incremental or scoped one have no grade.
2904
+ */
2905
+ confidence?: { budgetUsd: number };
2351
2906
  }
2352
2907
 
2353
2908
  /** Today's settings as the core's options. */
@@ -2406,6 +2961,9 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2406
2961
  // About 40k tokens at 3.5 characters a token.
2407
2962
  maxChars: options.batchChars,
2408
2963
  });
2964
+ // The files this run reviews whole because the previous review did not reach them.
2965
+ const keptNames = new Set(kept.map((f) => f.filename));
2966
+ const carriedHere = (input.since?.carried ?? []).filter((f) => keptNames.has(f));
2409
2967
  const threads = input.conversation ?? [];
2410
2968
  const threadsByBatch = assignThreads(threads, batches);
2411
2969
  const everyFile = kept.map((f) => `- ${f.filename} +${f.additions} −${f.deletions}`).join("\n");
@@ -2417,6 +2975,7 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2417
2975
  headDir: input.headDir,
2418
2976
  since: input.since?.sha ?? null,
2419
2977
  rebased: input.since?.rebased,
2978
+ ...(carriedHere.length > 0 ? { carried: carriedHere, changedSince: kept.length - carriedHere.length } : {}),
2420
2979
  paths: input.scope,
2421
2980
  dropped: dropped.length,
2422
2981
  everyFile,
@@ -2430,14 +2989,32 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2430
2989
  const notRun: string[] = [];
2431
2990
  let spent = 0;
2432
2991
  let usage = NO_USAGE;
2992
+ // PR Confidence (ADR 0033): only a pull request, only when the caller asked. The claims call
2993
+ // comes first so that every batch can say which claim each of its files serves; what it spends
2994
+ // is spent before the batches, so they cannot overspend the pull request's budget.
2995
+ const confidence = change.kind === "pull-request" ? options.confidence : undefined;
2996
+ const claimsStep = confidence
2997
+ ? listClaims(core, options, context, Math.min(confidence.budgetUsd, batchTotal / 4))
2998
+ : undefined;
2999
+ if (claimsStep) {
3000
+ spent += claimsStep.costUsd;
3001
+ usage = addUsage(usage, claimsStep.usage);
3002
+ if (claimsStep.claims && claimsStep.claims.length > 0) context.claims = claimsStep.claims.map((c) => c.text);
3003
+ }
2433
3004
  let budgetError = false;
2434
3005
  let limitError: "turns" | "timeout" | undefined;
3006
+ // Any call, a retry included, that ended on a turn or time limit or on its budget: a batch that
3007
+ // still gave usable output is not a finished review, so PR Confidence cannot grade it.
3008
+ let anyLimit = false;
2435
3009
  // The first call the provider refused because the reviewer's account cannot make it (no credit,
2436
3010
  // bad key, rate limit that outlasted its retry): every later call would fail the same way.
2437
3011
  let rejection: { kind: Exclude<ProviderErrorClass, "other">; text: string } | undefined;
2438
3012
  // The first unclassified error, kept for the message of the final throw.
2439
3013
  let otherError: string | undefined;
2440
3014
  const rejectedFiles: string[] = [];
3015
+ // Files of a batch that was started and then stopped on its budget, so no model refused them:
3016
+ // like the batches never started, they were not reached (ADR 0036).
3017
+ const budgetCut: string[] = [];
2441
3018
  const noteRejection = (r: BatchResult["rejection"]) => {
2442
3019
  if (!r) return;
2443
3020
  if (r.kind === "other") otherError ??= r.text;
@@ -2488,6 +3065,7 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2488
3065
  if (first.output) parts.push({ label, output: first.output });
2489
3066
  if (first.budget) budgetError = true;
2490
3067
  if (first.stopped) limitError = first.stopped;
3068
+ if (first.budget || first.stopped) anyLimit = true;
2491
3069
  let status = first.output
2492
3070
  ? "reviewed"
2493
3071
  : first.budget
@@ -2524,8 +3102,11 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2524
3102
  turns += retry.turns;
2525
3103
  cost += retry.costUsd;
2526
3104
  noteRejection(retry.rejection);
3105
+ if (retry.budget || retry.stopped) anyLimit = true;
2527
3106
  if (retry.output) parts.push({ label: `${label}, retry`, output: retry.output });
2528
3107
  const left = batchGaps(gaps, retry.output);
3108
+ if (retry.rejection && retry.rejection.kind !== "other") rejectedFiles.push(...left.map((f) => f.filename));
3109
+ else if (retry.budget) budgetCut.push(...left.map((f) => f.filename));
2529
3110
  status =
2530
3111
  left.length === 0 ? "reviewed after a retry" : `${left.length} file(s) left after a retry`;
2531
3112
  } else if (gaps.length > 0) {
@@ -2534,6 +3115,9 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2534
3115
  : first.stopped === "timeout"
2535
3116
  ? `${gaps.length} file(s) left: the call timed out`
2536
3117
  : `${gaps.length} file(s) left: budget spent`;
3118
+ // A refused call or a spent budget is not the files' doing; a timeout may be, so it stays unexplained.
3119
+ if (rejection) rejectedFiles.push(...gaps.map((f) => f.filename));
3120
+ else if (first.stopped !== "timeout") budgetCut.push(...gaps.map((f) => f.filename));
2537
3121
  }
2538
3122
  reports.push({
2539
3123
  label,
@@ -2576,8 +3160,16 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2576
3160
  } else checked = annotateUnverified(merged.findings);
2577
3161
  for (const path of notRun)
2578
3162
  merged.files_skipped.push({ path, reason: "not reached: the pull request's budget was spent" });
2579
- for (const path of rejectedFiles)
2580
- merged.files_skipped.push({ path, reason: "not reached: the provider rejected the call" });
3163
+ // A file the model listed itself, with a reason of its own, is replaced: the run's own cause comes first.
3164
+ for (const [paths, reason] of [
3165
+ [budgetCut, "not reached: the call ran out of its budget"],
3166
+ [rejectedFiles, "not reached: the provider rejected the call"],
3167
+ ] as const) {
3168
+ for (const path of paths) {
3169
+ merged.files_skipped = merged.files_skipped.filter((s) => s.path !== path);
3170
+ merged.files_skipped.push({ path, reason });
3171
+ }
3172
+ }
2581
3173
 
2582
3174
  // The anchor is decided here, so a sink needs no patch to know which findings sit on a diff line.
2583
3175
  const commentable = new Map(kept.map((f) => [f.filename, commentableLines(f.patch ?? "")]));
@@ -2625,6 +3217,41 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2625
3217
  core.log(
2626
3218
  `Risk map: ${riskMap.droppedFacts} risk fact(s) or judgement item(s) dropped: their file is not in the review, or their line does not exist at the head.`,
2627
3219
  );
3220
+ let fidelity: Fidelity | undefined;
3221
+ if (claimsStep) {
3222
+ const proposed = claimsStep.claims;
3223
+ const entries = parts.flatMap((p) => (Array.isArray(p.output.claim_assignments) ? p.output.claim_assignments : []));
3224
+ const assembled = proposed ? assembleClaims(proposed, entries) : { claims: [], assignments: [] };
3225
+ const sha = change.head.sha;
3226
+ const digest = claimsDigest(change.title ?? "", change.description);
3227
+ fidelity = buildFidelity({
3228
+ claims: checkClaims(assembled.claims, (path, line) => {
3229
+ const count = lineCount(path);
3230
+ return count !== null && line >= 1 && line <= count;
3231
+ }),
3232
+ assignments: assembled.assignments,
3233
+ // Every file of the pull request, not only the ones the review read: a binary, an oversize
3234
+ // diff or a path the owner excluded is explained only by a rule, or it is named unexplained.
3235
+ changedFiles: input.files.map((f) => ({ path: f.filename, patch: f.patch })),
3236
+ // Not this change's doing: a pre-existing finding does not grade the pull request.
3237
+ openFindings: findings
3238
+ .filter((f) => f.origin !== "pre-existing")
3239
+ .map((f) => ({ severity: f.severity, path: f.path, line: f.line, title: f.title })),
3240
+ riskMap,
3241
+ run: {
3242
+ // No claims list means no claim was read: that is an unknown, not a pull request that claims nothing.
3243
+ finished: proposed !== undefined && stop === "complete" && !anyLimit,
3244
+ ...(notRun.length > 0 || budgetError || claimsStep.budget ? { stoppedBy: "spend-ceiling" as const } : {}),
3245
+ ...(claimsStep.truncated ? { textTruncated: true } : {}),
3246
+ unreadFiles: expected.filter((f) => !reviewedSet.has(f)).length,
3247
+ reviewedCommit: sha,
3248
+ // The connector checks again at the moment it writes: here the review and the pull request agree.
3249
+ headCommit: sha,
3250
+ digestAtRead: digest,
3251
+ digestAtWrite: digest,
3252
+ },
3253
+ });
3254
+ }
2628
3255
  return {
2629
3256
  format: REVIEW_RESULT_V2,
2630
3257
  change,
@@ -2660,9 +3287,47 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2660
3287
  notices,
2661
3288
  },
2662
3289
  ...(verification ? { verification } : {}),
3290
+ ...(fidelity ? { fidelity } : {}),
2663
3291
  };
2664
3292
  }
2665
3293
 
3294
+ /**
3295
+ * The claims call (ADR 0033 decision 8): one small call that lists what the title and body claim,
3296
+ * from the author's text alone (Wachiman's own block stripped). It fails closed: with no list the
3297
+ * review still runs, and the grade is `cannot say`. A call that cannot be afforded is not made.
3298
+ */
3299
+ function listClaims(
3300
+ deps: CoreDeps,
3301
+ options: ReviewOptions,
3302
+ ctx: ReviewContext,
3303
+ budgetUsd: number,
3304
+ ): { claims?: ProposedClaim[]; costUsd: number; usage: TokenUsage; budget: boolean; truncated: boolean } {
3305
+ const input = claimsInput(ctx.meta.title ?? "", ctx.meta.body);
3306
+ const truncated = claimsTextTruncated(input);
3307
+ const none = { costUsd: 0, usage: NO_USAGE, budget: false, truncated };
3308
+ if (budgetUsd < MIN_BATCH_USD) {
3309
+ deps.warn("PR Confidence: no budget left for the claims call; the pull request gets no grade.");
3310
+ return { ...none, budget: true };
3311
+ }
3312
+ const prompt = buildClaimsPrompt(input);
3313
+ const call = attempt(
3314
+ () => runProvider(deps, options, ctx.headDir, { operation: "review", label: "claims", ...ctx.costTags }, prompt, ctx.headDir, budgetUsd, CLAIMS_SCHEMA),
3315
+ budgetUsd,
3316
+ );
3317
+ if (!call.ok) {
3318
+ deps.warn(`PR Confidence: the claims call failed (${call.error}); the pull request gets no grade.`);
3319
+ return { ...none, costUsd: call.costUsd };
3320
+ }
3321
+ const { value: result } = call;
3322
+ // A call that ended on its turn or time limit is not trusted even when its list parses: the list
3323
+ // may be the part it got to, and nothing is salvaged from an unfinished call.
3324
+ const limited = result.terminalReason === "turns" || result.terminalReason === "timeout";
3325
+ const claims = result.isError || limited ? undefined : parseClaimList(result.structuredOutput);
3326
+ if (limited) deps.warn(`PR Confidence: the claims call ended on its ${result.terminalReason} limit; the pull request gets no grade.`);
3327
+ else if (!claims) deps.warn("PR Confidence: the claims call returned no usable list; the pull request gets no grade.");
3328
+ return { claims, costUsd: result.costUsd, usage: result.usage ?? NO_USAGE, budget: result.terminalReason === "budget", truncated };
3329
+ }
3330
+
2666
3331
  /** Why a verifier call ended without answering everything, from how it ended; undefined for a clean finish. */
2667
3332
  function stopOf(result: { terminalReason: string; isError: boolean; providerError?: ProviderErrorClass; errorText?: string }): VerifierStop | undefined {
2668
3333
  const { terminalReason: reason } = result;
@@ -2802,6 +3467,8 @@ export function githubReviewInput(p: {
2802
3467
  since: string | null;
2803
3468
  rebased: boolean;
2804
3469
  commits?: string[];
3470
+ /** The files of `files` the previous partial review did not reach (they carry their whole diff). */
3471
+ carried?: string[];
2805
3472
  threads: Thread[];
2806
3473
  }): ReviewInput {
2807
3474
  return {
@@ -2813,7 +3480,8 @@ export function githubReviewInput(p: {
2813
3480
  base: { sha: p.baseSha },
2814
3481
  head: { sha: p.headSha },
2815
3482
  title: p.meta.title,
2816
- description: p.meta.body,
3483
+ // Wachiman's own description block is never the author's text (ADR 0033 decision 14).
3484
+ description: p.meta.body === undefined ? undefined : stripBlock(p.meta.body),
2817
3485
  author: p.meta.author?.login ?? undefined,
2818
3486
  identifier: `#${p.pr}`,
2819
3487
  },
@@ -2822,7 +3490,14 @@ export function githubReviewInput(p: {
2822
3490
  headDir: p.headDir,
2823
3491
  scope: p.scope,
2824
3492
  ...(p.since
2825
- ? { since: { sha: p.since, rebased: p.rebased, ...(p.commits?.length ? { commits: p.commits } : {}) } }
3493
+ ? {
3494
+ since: {
3495
+ sha: p.since,
3496
+ rebased: p.rebased,
3497
+ ...(p.commits?.length ? { commits: p.commits } : {}),
3498
+ ...(p.carried?.length ? { carried: p.carried } : {}),
3499
+ },
3500
+ }
2826
3501
  : {}),
2827
3502
  ...(p.threads.length > 0 ? { conversation: p.threads } : {}),
2828
3503
  };
@@ -2836,13 +3511,23 @@ export function githubReview(
2836
3511
  rebased: boolean;
2837
3512
  /** The commits since `since`, for the headline of a re-review. */
2838
3513
  commits?: string[];
3514
+ /** The files the previous partial review did not reach, reviewed whole in this run. */
3515
+ carried?: string[];
3516
+ /** The files an earlier run sent to a model that came back not reviewed (ADR 0036). */
3517
+ tried?: string[];
3518
+ /** Where a warning goes (a partial marker too long to write). */
3519
+ warn?: (line: string) => void;
2839
3520
  /** What the automatic runs before this one spent, for the footer's running total. */
2840
3521
  priorSpend?: { spent: number; runs: number };
2841
3522
  scoped: boolean;
2842
3523
  mention: string;
2843
3524
  automatic: boolean;
3525
+ /** The ledger's footer lines, when the run has any. */
3526
+ receiptLine?: string;
2844
3527
  /** Computed by the connector from every file of the pull request, not only the reviewed ones. */
2845
3528
  instructionChanges: { files: string[]; baseSha: string };
3529
+ /** The run is on a Claude subscription: the footer says its dollars are estimates. */
3530
+ estimate?: boolean;
2846
3531
  },
2847
3532
  ): Review {
2848
3533
  return buildReview({
@@ -2860,6 +3545,9 @@ export function githubReview(
2860
3545
  since: github.since,
2861
3546
  rebased: github.rebased,
2862
3547
  commits: github.commits,
3548
+ carried: github.carried,
3549
+ tried: github.tried,
3550
+ warn: github.warn,
2863
3551
  priorSpend: github.priorSpend,
2864
3552
  unreviewable: result.coverage.unreviewable,
2865
3553
  scoped: github.scoped,
@@ -2870,15 +3558,19 @@ export function githubReview(
2870
3558
  modelLabel: result.provider.label,
2871
3559
  effort: result.provider.effort,
2872
3560
  automatic: github.automatic,
3561
+ receiptLine: github.receiptLine,
2873
3562
  mention: github.mention,
2874
3563
  instructionChanges: github.instructionChanges,
2875
3564
  riskMap: result.riskMap,
3565
+ ...(result.fidelity ? { fidelity: result.fidelity } : {}),
2876
3566
  pushOnly: github.since !== null,
2877
3567
  ...(result.verification ? { verification: result.verification } : {}),
3568
+ ...(github.estimate ? { estimate: true } : {}),
2878
3569
  });
2879
3570
  }
2880
3571
 
2881
- export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3572
+ /** `force` (`--force`) counts only for the operator's own run, never an automatic trigger. */
3573
+ export function review(deps: Deps, repo: string, pr: number, words: string[], force = false) {
2882
3574
  const { gh, config } = deps;
2883
3575
  const meta = JSON.parse(
2884
3576
  gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,title,body,author"]),
@@ -2894,9 +3586,19 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
2894
3586
  );
2895
3587
  if (ignored.length > 0)
2896
3588
  deps.log(`Not paths in this pull request, ignored: ${ignored.join(" ")}`);
2897
- // A dry run may ask for the whole pull request again (AGENT_REVIEW_FULL_REVIEW): no marker read.
2898
- const last = config.fullReview ? null : lastReviewedSha(gh, repo, pr);
2899
- if (last === headSha && paths.length === 0) {
3589
+ // A dry run may ask for the whole pull request again (WACHIMAN_FULL_REVIEW): no marker read.
3590
+ const state = config.fullReview ? null : lastReviewState(gh, repo, pr);
3591
+ const last = state?.sha ?? null;
3592
+ // What the last review did not reach (ADR 0036), by name. Only an unscoped run carries it over: a
3593
+ // request for paths reviews those paths. The files that left the pull request, or are excluded
3594
+ // now, are dropped here without a word; the rest are reviewed whole, with the patch the pull
3595
+ // request has now, even when they also changed since: nothing of them was ever reviewed.
3596
+ const unread = new Set(paths.length === 0 ? (state?.rest ?? []) : []);
3597
+ const carried: ReviewFile[] =
3598
+ unread.size === 0
3599
+ ? []
3600
+ : filterFiles(prFiles.filter((f) => unread.has(f.filename)), [...DEFAULT_EXCLUDE, ...config.exclude], []).kept;
3601
+ if (last === headSha && paths.length === 0 && carried.length === 0) {
2900
3602
  bodyOnly(
2901
3603
  `Already reviewed at \`${short(headSha)}\`. Push changes, or ask \`${config.mention} review <paths>\`.`,
2902
3604
  );
@@ -2907,7 +3609,12 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
2907
3609
  // The commits since `since`, for the headline; only when compare lists every one of them.
2908
3610
  let commits: string[] | undefined;
2909
3611
  let files = prFiles;
2910
- if (last && paths.length === 0) {
3612
+ // The head did not move but files were never reached: only those are reviewed.
3613
+ if (last === headSha && paths.length === 0) {
3614
+ deps.log(`Resuming at ${short(headSha)}: ${carried.length} file(s) the previous review did not reach: ${carried.map((f) => f.filename).join(", ")}.`);
3615
+ since = last;
3616
+ files = [];
3617
+ } else if (last && paths.length === 0) {
2911
3618
  let status = "unavailable";
2912
3619
  let cmp: ReturnType<typeof compareFiles> | null = null;
2913
3620
  try {
@@ -2945,14 +3652,15 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
2945
3652
  comments: [],
2946
3653
  });
2947
3654
  };
2948
- if (delta.kind === "unchanged") {
3655
+ if (delta.kind === "unchanged" && carried.length === 0) {
2949
3656
  upToDate(
2950
3657
  `The ${cmp.files.length} file(s) changed since ${short(last)} are not part of the pull request's own change (a merge of the base branch), or their change is the one already reviewed; nothing to review.`,
2951
3658
  );
2952
3659
  return;
2953
3660
  }
2954
3661
  const keep = delta.kind === "changed" ? new Set(delta.files.map((f) => f.filename)) : null;
2955
- const candidates = keep ? own.filter((f) => keep.has(f.filename)) : own;
3662
+ // "unchanged" reaches here only to resume: nothing changed since, the unread files remain.
3663
+ const candidates = delta.kind === "unchanged" ? [] : keep ? own.filter((f) => keep.has(f.filename)) : own;
2956
3664
  // The file's patch at `last`: "" when the pull request did not change it then, undefined when unknown.
2957
3665
  const before = delta.kind === "changed" ? new Map(delta.before.map((f) => [f.filename, f])) : null;
2958
3666
  const thenOf = (f: ReviewFile) => patchAtReview(before, f, inPr.get(f.filename));
@@ -2974,7 +3682,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
2974
3682
  deps.log(
2975
3683
  `${foreignOnly.length} file(s) changed since ${short(last)} hold only lines that came from the merged branch, not reviewed: ${foreignOnly.join(", ")}.`,
2976
3684
  );
2977
- if (files.length === 0) {
3685
+ if (files.length === 0 && carried.length === 0) {
2978
3686
  upToDate(`Every change since ${short(last)} in the pull request's files came from the merged branch; nothing to review.`);
2979
3687
  return;
2980
3688
  }
@@ -2982,12 +3690,20 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
2982
3690
  deps.log(
2983
3691
  `${cmp.files.length - files.length} of the ${cmp.files.length} file(s) changed since ${short(last)} are not reviewed: not in the pull request's own change, or that change is the one already reviewed.`,
2984
3692
  );
2985
- deps.log(`Reviewed since ${short(last)}: ${files.map((f) => f.filename).join(", ")}.`);
3693
+ if (files.length > 0) deps.log(`Reviewed since ${short(last)}: ${files.map((f) => f.filename).join(", ")}.`);
2986
3694
  } else {
2987
3695
  // The branch was rewritten (a rebase, a squash, a force-push). The content decides, not the SHAs.
2988
3696
  const base = baseSha(gh, repo, pr);
2989
3697
  const delta = rebaseDelta(gh, repo, base, last, prFiles);
2990
- if (delta.kind === "unchanged") {
3698
+ if (delta.kind === "unchanged" && carried.length > 0) {
3699
+ // The same change over a new head, but files were never reached: only those are reviewed.
3700
+ deps.log(
3701
+ `The last reviewed commit ${short(last)} is not behind the head (${status}), but the pull request's changes are the same; rebased with no content change. The ${carried.length} file(s) the previous review did not reach are reviewed.`,
3702
+ );
3703
+ since = last;
3704
+ rebased = true;
3705
+ files = [];
3706
+ } else if (delta.kind === "unchanged") {
2991
3707
  deps.log(
2992
3708
  `The last reviewed commit ${short(last)} is not behind the head (${status}), but the pull request's changes are the same${delta.removed.length > 0 ? ` (no longer in it: ${delta.removed.join(", ")})` : ""}; rebased with no content change, nothing to review.`,
2993
3709
  );
@@ -3001,8 +3717,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3001
3717
  comments: [],
3002
3718
  });
3003
3719
  return;
3004
- }
3005
- if (delta.kind === "changed") {
3720
+ } else if (delta.kind === "changed") {
3006
3721
  deps.log(
3007
3722
  `The last reviewed commit ${short(last)} is not behind the head (${status}); the branch was rewritten. ${delta.files.length} file(s) differ from what was reviewed, ${delta.unchanged} are the same and are not reviewed again.`,
3008
3723
  );
@@ -3017,6 +3732,13 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3017
3732
  }
3018
3733
  }
3019
3734
 
3735
+ // An incremental run adds the unread files to what changed since, each once and with its whole
3736
+ // patch. A run that fell back to the whole pull request (`since` is null) already holds them.
3737
+ const resumed = since !== null ? carried.map((f) => f.filename) : [];
3738
+ if (resumed.length > 0) {
3739
+ const unreadNames = new Set(resumed);
3740
+ files = [...files.filter((f) => !unreadNames.has(f.filename)), ...carried];
3741
+ }
3020
3742
  const { kept, dropped } = filterFiles(files, [...DEFAULT_EXCLUDE, ...config.exclude], paths);
3021
3743
  if (kept.length === 0) {
3022
3744
  bodyOnly(
@@ -3042,6 +3764,15 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3042
3764
  });
3043
3765
  return;
3044
3766
  }
3767
+ // The size gate: what this run would send, priced before any model call. Nothing is posted as a
3768
+ // review and no marker is written, so the next push sees no marker and gates again.
3769
+ const estimate = estimateFor(allBinary.reviewable, config);
3770
+ const gate = sizeGate(config, isAutomatic(config.trigger));
3771
+ if (estimate.usd > gate) {
3772
+ deps.log(`Estimated $${estimate.usd.toFixed(2)} is above the $${gate.toFixed(2)} size gate; nothing sent to a model.`);
3773
+ postSizeGateNotice(deps, repo, pr, headSha, estimate, gate);
3774
+ return;
3775
+ }
3045
3776
  // After the rebase exits above (they cost nothing and move the marker) and before any paid step.
3046
3777
  const ceiling = ceilingRoom(deps, repo, pr, headSha);
3047
3778
  if (ceiling === null) return;
@@ -3050,7 +3781,6 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3050
3781
  const prior = automatic ? { spent: ceiling.spent, runs: ceiling.runs } : undefined;
3051
3782
  const base = baseSha(gh, repo, pr);
3052
3783
  const instructions = readBaseInstructions(gh, repo, base, deps.warn);
3053
- const totalBudget = Math.min(config.budgetUsd, ceiling.room);
3054
3784
  const batchBudget = config.batchBudgetUsd;
3055
3785
  // Only threads that wait for an answer (the owner wrote last, Wachiman has replies left): a
3056
3786
  // thread Wachiman already answered is not read again, so it is not answered twice (ADR 0008).
@@ -3068,11 +3798,24 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3068
3798
  since,
3069
3799
  rebased,
3070
3800
  commits,
3801
+ carried: resumed,
3071
3802
  threads,
3072
3803
  });
3073
- const result = reviewChange(input, reviewOptionsOf(config, totalBudget), deps);
3804
+ // PR Confidence grades a full review only (ADR 0033): an incremental or scoped review reads a
3805
+ // part of the change, and "nothing else changed" cannot be said of a part.
3806
+ const fullReview = since === null && paths.length === 0;
3807
+ // Everything the run reads from GitHub is read by now. The ledger is asked last, just before the
3808
+ // first paid step, so a failing read cannot leave a reservation that nobody settles.
3809
+ const grant = spendReserve(deps, repo, pr, headSha, Math.min(config.budgetUsd, ceiling.room), force && !automatic);
3810
+ const totalBudget = Math.min(config.budgetUsd, ceiling.room, grant.roomUsd);
3811
+ const options: ReviewOptions = {
3812
+ ...reviewOptionsOf(config, totalBudget),
3813
+ ...(config.confidence && fullReview ? { confidence: { budgetUsd: CLAIMS_BUDGET_USD } } : {}),
3814
+ };
3815
+ const result = settledOnError(deps, grant, () => reviewChange(input, options, deps));
3074
3816
  const { usage, costUsdEstimate: spent } = result.execution;
3075
3817
  const operation: Operation = since ? "re-review" : "review";
3818
+ const receiptLine = spendSettle(deps, grant, spent) ?? undefined;
3076
3819
 
3077
3820
  if (result.execution.callsWithOutput === 0) {
3078
3821
  // A failed automatic run still spent money: its notice carries the cost line the ceiling sums.
@@ -3081,12 +3824,14 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3081
3824
  ? postReview(deps, repo, pr, headSha, {
3082
3825
  body: [
3083
3826
  branded(text),
3827
+ ...(receiptLine ? [receiptLine] : []),
3084
3828
  costLine({
3085
3829
  modelLabel: result.provider.label,
3086
3830
  effort: config.effort,
3087
3831
  operation,
3088
3832
  extra: prior ? [prSoFar(prior, spent)] : [],
3089
3833
  usage,
3834
+ estimate: onSubscription(deps),
3090
3835
  costUsd: spent,
3091
3836
  }),
3092
3837
  SIGNATURE.auto,
@@ -3094,15 +3839,27 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3094
3839
  ].join("\n\n"),
3095
3840
  comments: [],
3096
3841
  })
3097
- : bodyOnly(text);
3842
+ : // A manual run keeps its receipt and forced/bypass lines, but not `SIGNATURE.auto`: the ceiling does not count it.
3843
+ receiptLine
3844
+ ? postReview(deps, repo, pr, headSha, { body: [branded(text), receiptLine].join("\n\n"), comments: [] })
3845
+ : bodyOnly(text);
3098
3846
  const { rejection, stop } = result.execution;
3099
3847
  const refused = rejection && rejection.kind !== "other" ? { kind: rejection.kind, text: rejection.text } : undefined;
3100
3848
  if (refused) {
3101
- const headline = {
3102
- billing: "**Not reviewed: the reviewer's Anthropic account has no credit.** Top up, then re-run this job.",
3103
- auth: "**Not reviewed: the reviewer's API key was rejected.** Check the `ANTHROPIC_API_KEY` secret, then re-run.",
3104
- rate_limit: "**Not reviewed: the Anthropic API kept rate-limiting the reviewer.** Re-run later.",
3105
- }[refused.kind];
3849
+ // On a subscription token the key is not the credential: say what fits it, and that nothing falls back to a key.
3850
+ const headline = (
3851
+ deps.provider.auth === "oauth-token"
3852
+ ? {
3853
+ billing: "**Not reviewed: the reviewer's Claude subscription refused the call (usage limit or plan access).** Re-run after the limit resets. Wachiman does not fall back to an API key.",
3854
+ auth: "**Not reviewed: the reviewer's Claude subscription token was rejected.** Check the `CLAUDE_CODE_OAUTH_TOKEN` secret (a token lasts a year; make a new one with `claude setup-token`), then re-run.",
3855
+ rate_limit: "**Not reviewed: Claude kept rate-limiting the reviewer.** Re-run later.",
3856
+ }
3857
+ : {
3858
+ billing: "**Not reviewed: the reviewer's Anthropic account has no credit.** Top up, then re-run this job.",
3859
+ auth: "**Not reviewed: the reviewer's API key was rejected.** Check the `ANTHROPIC_API_KEY` secret, then re-run.",
3860
+ rate_limit: "**Not reviewed: the Anthropic API kept rate-limiting the reviewer.** Re-run later.",
3861
+ }
3862
+ )[refused.kind];
3106
3863
  // `oneLine` neutralises the text and cuts it at 300 characters.
3107
3864
  const detail = oneLine(refused.text, 300);
3108
3865
  spentNotice(detail ? `${headline}\n\n> ${detail}` : headline);
@@ -3136,24 +3893,39 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3136
3893
  since,
3137
3894
  rebased,
3138
3895
  commits,
3896
+ carried: resumed,
3897
+ tried: paths.length === 0 ? state?.tried : undefined,
3898
+ warn: deps.warn,
3139
3899
  priorSpend: prior,
3140
3900
  scoped: paths.length > 0,
3141
3901
  mention: config.mention,
3142
3902
  automatic,
3903
+ receiptLine,
3143
3904
  instructionChanges: {
3144
3905
  files: changedInstructionFiles(prFiles.map((f) => f.filename)),
3145
3906
  baseSha: instructions.baseSha,
3146
3907
  },
3908
+ estimate: onSubscription(deps),
3147
3909
  });
3148
3910
  refuseLeak(deps, [
3149
3911
  built.body,
3150
3912
  ...built.comments.map((c) => c.body),
3151
3913
  ...result.threadReplies.map((r) => r.reply),
3152
3914
  ]);
3153
- postReview(deps, repo, pr, headSha, built);
3915
+ const reviewUrl = postReview(deps, repo, pr, headSha, built);
3916
+ // After the review, best-effort: the review is the record and is already posted.
3917
+ if (config.confidence) {
3918
+ publishConfidence({ gh, dryRun: config.dryRun, log: deps.log, warn: deps.warn, now: deps.now }, repo, pr, {
3919
+ headSha,
3920
+ fidelity: result.fidelity,
3921
+ partialReason: "This review covered only part of the pull request, so it cannot grade the whole change",
3922
+ reviewUrl,
3923
+ permalinkBase: `https://github.com/${repo}`,
3924
+ });
3925
+ }
3154
3926
  // This run's cost and the pull request's total, under each reply. Not flagged automatic: the
3155
3927
  // review body above carries the flagged line, so the ceiling would count the run twice.
3156
- const replyCost = prior ? `\n\n<sub>this run $${spent.toFixed(2)} · ${prSoFar(prior, spent)}</sub>` : "";
3928
+ const replyCost = prior ? `\n\n<sub>this run $${spent.toFixed(2)} · ${prSoFar(prior, spent)}${estimateTail(onSubscription(deps))}</sub>` : "";
3157
3929
  for (const r of result.threadReplies) {
3158
3930
  const label = r.status === "addressed" ? "Looks addressed" : "Still open";
3159
3931
  if (config.dryRun) {
@@ -3295,7 +4067,6 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3295
4067
  }
3296
4068
  const ceiling = ceilingRoom(deps, repo, pr, headSha);
3297
4069
  if (ceiling === null) return;
3298
- const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room);
3299
4070
 
3300
4071
  const meta = JSON.parse(gh(["pr", "view", String(pr), "-R", repo, "--json", "title,body,author"]));
3301
4072
  const repoDir = deps.repoDir ?? process.cwd();
@@ -3308,16 +4079,23 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3308
4079
  join(dir, "threads.json"),
3309
4080
  JSON.stringify(pending.map((t) => ({ ...t, code: codeAround(repoDir, t.path, t.line) })), null, 2),
3310
4081
  );
3311
- const call = runProvider(
3312
- deps,
3313
- config,
3314
- repoDir,
3315
- { operation: "reply", label: "threads", repo, pr },
3316
- buildThreadsPrompt({ pr, repo, headSha }, dir),
3317
- dir,
3318
- budgetUsd,
3319
- THREAD_SCHEMA,
4082
+ // The ledger is asked last, after every read and write above, so a failing one leaves no reservation unsettled.
4083
+ const grant = spendReserve(deps, repo, pr, headSha, Math.min(config.threadsBudgetUsd, ceiling.room), false);
4084
+ const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room, grant.roomUsd);
4085
+ if (grantTooSmall(deps, grant, "thread replies")) return;
4086
+ const call = settledOnError(deps, grant, () =>
4087
+ runProvider(
4088
+ deps,
4089
+ config,
4090
+ repoDir,
4091
+ { operation: "reply", label: "threads", repo, pr },
4092
+ buildThreadsPrompt({ pr, repo, headSha }, dir),
4093
+ dir,
4094
+ budgetUsd,
4095
+ THREAD_SCHEMA,
4096
+ ),
3320
4097
  );
4098
+ const receiptLine = spendSettle(deps, grant, call.costUsd);
3321
4099
  const raw = !call.isError ? (call.structuredOutput as { thread_replies?: ThreadReply[] } | undefined) : undefined;
3322
4100
  if (!raw || !Array.isArray(raw.thread_replies)) {
3323
4101
  throw new Error(`The agent did not answer the threads (${call.terminalReason}); $${call.costUsd.toFixed(2)} spent.`);
@@ -3361,8 +4139,8 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3361
4139
  const prior = { spent: ceiling.spent, runs: ceiling.runs };
3362
4140
  const cost =
3363
4141
  i === 0
3364
- ? `\n\n${costLine({ modelLabel: deps.provider.modelLabel(), effort: config.effort, operation: "reply", extra: [`answers ${toPost.length} thread(s)`, prSoFar(prior, call.costUsd)], usage: call.usage, costUsd: call.costUsd })}\n\n${SIGNATURE.auto}`
3365
- : `\n\n<sub>this run $${call.costUsd.toFixed(2)} · ${prSoFar(prior, call.costUsd)}</sub>`;
4142
+ ? `${receiptLine ? `\n\n${receiptLine}` : ""}\n\n${costLine({ modelLabel: deps.provider.modelLabel(), effort: config.effort, operation: "reply", extra: [`answers ${toPost.length} thread(s)`, prSoFar(prior, call.costUsd)], usage: call.usage, estimate: onSubscription(deps), costUsd: call.costUsd })}\n\n${SIGNATURE.auto}`
4143
+ : `\n\n<sub>this run $${call.costUsd.toFixed(2)} · ${prSoFar(prior, call.costUsd)}${estimateTail(onSubscription(deps))}</sub>`;
3366
4144
  const body = `${branded(`**${label}**`)} at \`${short(headSha)}\`: ${neutralise(reply.reply)}${cost}\n\n${SIGNATURE.reply}`;
3367
4145
  if (config.dryRun) {
3368
4146
  deps.log(`--- reply to ${reply.comment_id}: ${label} ---\n${body}`);
@@ -3381,6 +4159,9 @@ export interface ReviewContext {
3381
4159
  since: string | null;
3382
4160
  /** The branch was rewritten since `since`: the files are those whose changed lines differ. */
3383
4161
  rebased?: boolean;
4162
+ /** The files reviewed whole because the previous review did not reach them, and how many files changed since. */
4163
+ carried?: readonly string[];
4164
+ changedSince?: number;
3384
4165
  paths: string[];
3385
4166
  dropped: number;
3386
4167
  everyFile: string;
@@ -3388,6 +4169,8 @@ export interface ReviewContext {
3388
4169
  meta: { title?: string; body?: string; author?: string };
3389
4170
  /** `renderInstructions` of the base commit's rules. */
3390
4171
  instructions: string;
4172
+ /** PR Confidence on: the claims the batches assign their files to, as the claims call listed them. */
4173
+ claims?: readonly string[];
3391
4174
  /** How the cost log line names the change; absent for a change with no repository or number. */
3392
4175
  costTags?: Pick<CallCost, "repo" | "pr">;
3393
4176
  }
@@ -3431,12 +4214,20 @@ export function buildBatchPrompt(
3431
4214
  evidence = "",
3432
4215
  questions: readonly DataPathQuestion[] = selectQuestions(files),
3433
4216
  ) {
3434
- const list = files.map((f) => `- ${f.filename} +${f.additions} −${f.deletions}`).join("\n");
3435
- const scope = ctx.since
4217
+ const carried = new Set(ctx.carried ?? []);
4218
+ const list = files
4219
+ .map((f) => `- ${f.filename} +${f.additions} −${f.deletions}${carried.has(f.filename) ? " (not reached by the previous review: whole diff)" : ""}`)
4220
+ .join("\n");
4221
+ const sinceScope = ctx.since
3436
4222
  ? ctx.rebased
3437
4223
  ? `only the files whose changed lines differ from what was reviewed at commit ${ctx.since}, the last reviewed one (the branch was rebased since; a file's diff below is still its whole diff against the base)`
3438
4224
  : `only the changes since commit ${ctx.since}, the last reviewed one`
3439
4225
  : "the whole pull request";
4226
+ // A resumed review: the previous one stopped before these files, so they were never reviewed.
4227
+ // They come with their whole diff against the base, changed since or not.
4228
+ const unreached = `${carried.size} file(s) the previous review, at commit ${ctx.since}, did not reach: those files are marked in the lists below and are reviewed whole, because nothing of them was reviewed before, with their whole diff against the base`;
4229
+ const scope =
4230
+ ctx.since && carried.size > 0 ? ((ctx.changedSince ?? 0) > 0 ? `${sinceScope}, and ${unreached}` : `only ${unreached}`) : sinceScope;
3440
4231
  return `You are reviewing ${ctx.describe}, checked out at its head commit ${ctx.headSha}.
3441
4232
  The repository's rules are in the "Repository instructions" section below; the ADRs in docs/adr/ hold its decisions.
3442
4233
 
@@ -3476,7 +4267,7 @@ finding that already has an open thread.
3476
4267
  `
3477
4268
  : ""
3478
4269
  }
3479
- ${RISK_PARAGRAPH}
4270
+ ${RISK_PARAGRAPH}${ctx.claims ? `\n\n${claimsParagraph(ctx.claims)}` : ""}
3480
4271
 
3481
4272
  ${FLOW_QUESTIONS}${renderDataPathQuestions(questions)}
3482
4273
 
@@ -3505,8 +4296,18 @@ export function relativisePaths(output: ReviewOutput, repoDir: string): ReviewOu
3505
4296
  // `wellFormed` drops it later, and it must not throw here.
3506
4297
  const stripItemPath = <T extends { path: string }>(item: T): T =>
3507
4298
  item !== null && typeof item === "object" && typeof item.path === "string" ? { ...item, path: strip(item.path) } : item;
4299
+ // Same rule for a claim assignment: a path that is not a string is left for `assembleClaims` to drop.
4300
+ const stripAssignment = (a: ClaimAssignment): ClaimAssignment =>
4301
+ a !== null && typeof a === "object"
4302
+ ? {
4303
+ ...a,
4304
+ path: typeof a.path === "string" ? strip(a.path) : a.path,
4305
+ evidence: Array.isArray(a.evidence) ? a.evidence.map(stripItemPath) : a.evidence,
4306
+ }
4307
+ : a;
3508
4308
  return {
3509
4309
  ...output,
4310
+ ...(Array.isArray(output.claim_assignments) ? { claim_assignments: output.claim_assignments.map(stripAssignment) } : {}),
3510
4311
  files_reviewed: output.files_reviewed.map(strip),
3511
4312
  files_skipped: output.files_skipped.map((s) => ({ ...s, path: strip(s.path) })),
3512
4313
  findings: output.findings.map((f) => ({ ...f, path: strip(f.path) })),
@@ -3609,7 +4410,7 @@ function reviewBatch(
3609
4410
  part: { index: number; total: number; retry?: boolean },
3610
4411
  budgetUsd: number,
3611
4412
  ) {
3612
- const dir = mkdtempSync(join(tmpdir(), "agent-review-"));
4413
+ const dir = mkdtempSync(join(tmpdir(), "wachiman-review-"));
3613
4414
  // The run dir holds the change's text (title, body, threads, evidence): removed once the call
3614
4415
  // is over, whatever happened. Nothing reads it after the provider returns.
3615
4416
  try {
@@ -3649,7 +4450,7 @@ function reviewBatch(
3649
4450
  prompt,
3650
4451
  dir,
3651
4452
  budgetUsd,
3652
- SCHEMA,
4453
+ ctx.claims ? { ...SCHEMA, properties: { ...SCHEMA.properties, claim_assignments: ASSIGNMENTS_SCHEMA } } : SCHEMA,
3653
4454
  ),
3654
4455
  budgetUsd,
3655
4456
  );
@@ -3741,6 +4542,7 @@ export function runProvider(
3741
4542
  // (`attempt`); record it that way here, still as a table row and a log line, then fail as before.
3742
4543
  const dead: CallCost = {
3743
4544
  ...what,
4545
+ ...(deps.provider.auth ? { auth: deps.provider.auth } : {}),
3744
4546
  model: limits.model,
3745
4547
  turns: 0,
3746
4548
  durationMs: Date.now() - started,
@@ -3778,10 +4580,12 @@ export function runProvider(
3778
4580
  durationMs: result.durationMs,
3779
4581
  providerError: result.providerError,
3780
4582
  errorText: result.errorText,
4583
+ credential: deps.provider.auth,
3781
4584
  }),
3782
4585
  );
3783
4586
  const cost: CallCost = {
3784
4587
  ...what,
4588
+ ...(deps.provider.auth ? { auth: deps.provider.auth } : {}),
3785
4589
  model: result.model ?? limits.model,
3786
4590
  turns: result.turns,
3787
4591
  durationMs: result.durationMs,
@@ -3928,6 +4732,14 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
3928
4732
  thread: line && !walkthrough ? threadBefore(deps.gh, repo, pr, line) : undefined,
3929
4733
  });
3930
4734
  // One question is one call, with the budget a whole review had before batches: $1.
4735
+ const grant = spendReserve(deps, repo, pr, headSha, deps.config.answerBudgetUsd, false);
4736
+ if (grantTooSmall(deps, grant, "an answer")) {
4737
+ const note = `Wachiman did not answer: the spend limit leaves too little room for a call (at least ${usd(MIN_BATCH_USD)} is needed). Nothing was spent.`;
4738
+ const body = `${BRAND}\n\n${note}\n\n${asker === undefined ? SIGNATURE.answer : `${SIGNATURE.ask}\n\n${SIGNATURE.answer}`}`;
4739
+ if (deps.config.dryRun) deps.log(body);
4740
+ else postAnswer(deps, repo, pr, body, line);
4741
+ return;
4742
+ }
3931
4743
  let result: ReturnType<typeof runProvider> | undefined;
3932
4744
  let failure = "";
3933
4745
  try {
@@ -3938,26 +4750,31 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
3938
4750
  { operation: "on-demand", label: "question", repo, pr },
3939
4751
  prompt,
3940
4752
  dir,
3941
- deps.config.answerBudgetUsd,
4753
+ Math.min(deps.config.answerBudgetUsd, grant.roomUsd),
3942
4754
  ASK_SCHEMA,
3943
4755
  );
3944
4756
  } catch (error) {
3945
4757
  // The call died without a result: for someone but the operator it is counted at its cap below.
3946
- if (asker === undefined) throw error;
4758
+ if (asker === undefined) {
4759
+ spendSettle(deps, grant, spentSince(deps, grant));
4760
+ throw error;
4761
+ }
3947
4762
  failure = String(error).slice(0, 200);
3948
4763
  }
3949
4764
  const parsed = result && !result.isError ? result.structuredOutput : undefined;
3950
- const costUsd = result?.costUsd ?? deps.config.answerBudgetUsd;
4765
+ const costUsd = result?.costUsd ?? Math.min(deps.config.answerBudgetUsd, grant.roomUsd);
4766
+ const receiptLine = spendSettle(deps, grant, costUsd);
3951
4767
  const build = (text: string) => {
3952
4768
  const cost = costLine({
3953
4769
  modelLabel: deps.provider.modelLabel(),
3954
4770
  effort: deps.config.effort,
3955
4771
  operation: "on-demand",
3956
4772
  usage: result?.usage,
4773
+ estimate: onSubscription(deps),
3957
4774
  costUsd,
3958
4775
  });
3959
4776
  const signed = asker === undefined ? SIGNATURE.answer : `${SIGNATURE.ask}\n\n${SIGNATURE.answer}`;
3960
- return `${BRAND}\n\n${text}\n\n${cost}\n\n${signed}`;
4777
+ return `${BRAND}\n\n${text}\n\n${receiptLine ? `${receiptLine}\n\n` : ""}${cost}\n\n${signed}`;
3961
4778
  };
3962
4779
  let text: string;
3963
4780
  if (isAskAnswer(parsed)) {
@@ -3995,7 +4812,7 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
3995
4812
  function postAskLimit(deps: Deps, repo: string, pr: number, spent: number) {
3996
4813
  const body = [
3997
4814
  branded(
3998
- `The question budget for this pull request is used up: questions from collaborators have spent $${spent.toFixed(2)} of the $${deps.config.askCeilingUsd.toFixed(2)} ceiling, so this question is not answered. The repository operator can still ask.`,
4815
+ `The question budget for this pull request is used up: questions from collaborators have spent $${spent.toFixed(2)} of the $${deps.config.askCeilingUsd.toFixed(2)} ceiling, so this question is not answered. The repository operator can still ask.${onSubscription(deps) ? " These are API-equivalent estimates: the reviews run on a Claude subscription, not a bill." : ""}`,
3999
4816
  ),
4000
4817
  SIGNATURE.answer,
4001
4818
  SIGNATURE.askLimit,
@@ -4029,7 +4846,11 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4029
4846
  const operatorAsked =
4030
4847
  author === undefined ? askers === "operator" || deps.config.dryRun : author.toLowerCase() === operator.toLowerCase();
4031
4848
  if (operatorAsked) {
4032
- if (command?.kind === "review") review(deps, repo, pr, command.paths);
4849
+ if (command?.kind === "review") {
4850
+ // With no ledger `--force` means nothing: it stays a word that names no file, as it always did.
4851
+ const words = deps.config.ledgerUrl ? command.paths.filter((w) => w !== "--force") : command.paths;
4852
+ review(deps, repo, pr, words, command.force);
4853
+ }
4033
4854
  else if (command) answer(deps, repo, pr, request, { line });
4034
4855
  return;
4035
4856
  }
@@ -4038,7 +4859,7 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4038
4859
  return;
4039
4860
  }
4040
4861
  if (author === undefined) {
4041
- throw new Error("askers is write, but the caller did not say who wrote the comment (AGENT_REVIEW_COMMENT_AUTHOR); not answering.");
4862
+ throw new Error("askers is write, but the caller did not say who wrote the comment (WACHIMAN_COMMENT_AUTHOR); not answering.");
4042
4863
  }
4043
4864
  if (command?.kind !== "answer") {
4044
4865
  deps.warn(`Comment by ${author} is not a question; only the operator starts a review. Nothing to do.`);