wachiman 1.13.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.
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,20 +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 { ESTIMATE_NOTE, NO_USAGE, addUsage, costLine, costLogLine, isEstimate, 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
35
  import { estimateReview, sizeGate, suggestedBudget, type ReviewEstimate } from "./estimate";
36
- import { isAutomatic, operatorProblem, type EngineConfig, type Trigger } from "./config";
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";
37
52
  import {
38
53
  EVIDENCE_CAPS,
39
54
  addedLinesOf,
@@ -234,7 +249,8 @@ export interface Review {
234
249
  comments: InlineComment[];
235
250
  }
236
251
 
237
- 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" };
238
254
 
239
255
  export const DEFAULT_EXCLUDE = [
240
256
  "**/bun.lock",
@@ -252,8 +268,8 @@ export const DEFAULT_EXCLUDE = [
252
268
  "**/worker-configuration.d.ts",
253
269
  ];
254
270
 
255
- // The old marker is still read so repositories reviewed before the rename keep their incremental state.
256
- 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]+) -->";
257
273
  const short = (sha: string) => sha.slice(0, 7);
258
274
  /**
259
275
  * `Important · 🟠📝 **Fix · docs: stale cell (confidence high)**`: the tier word, both emojis, then
@@ -286,7 +302,7 @@ export const DEFAULT_MENTION = "/wachiman";
286
302
  * earlier handles. Only the default is documented. `/wachi` does not match `/wachiman`, since a
287
303
  * keyword must end a word, so both are listed.
288
304
  */
289
- export const MENTION_ALIASES = ["/wachiman", "/wachi", "@agent-review", "@claude"];
305
+ export const MENTION_ALIASES = ["/wachiman", "/wachi", "@claude"];
290
306
  const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
291
307
 
292
308
  /** The keyword or an alias, as a word of its own: "docs/wachi" or "me@claude" is not a mention. */
@@ -298,7 +314,11 @@ export function parseCommand(body: string, keyword = DEFAULT_MENTION): Command |
298
314
  const match = body.match(new RegExp(`${mentionSource(keyword)}(.*)`));
299
315
  if (!match) return null;
300
316
  const words = match[1].trim().split(/\s+/).filter(Boolean);
301
- 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
+ }
302
322
  return { kind: "answer" };
303
323
  }
304
324
 
@@ -410,7 +430,7 @@ export function fileKind(path: string): FileKind {
410
430
  /**
411
431
  * Path rules for `riskScore`. These are defaults taken from the first consumer (`ipc`, `preload`,
412
432
  * `main`, `apps/<name>/src`) and are the owner's to tune; per-repository configuration is planned
413
- * (https://github.com/niway-dev/agent-review/issues/5).
433
+ * (https://github.com/niway-dev/wachiman/issues/5).
414
434
  * The highest matching weight wins. A test or a document scores its kind's weight whatever its
415
435
  * path, so `ipc/foo.test.ts` does not outrank the IPC code it tests.
416
436
  */
@@ -681,7 +701,7 @@ export function annotateDiff(files: ReviewFile[]) {
681
701
  return out.join("\n");
682
702
  }
683
703
 
684
- export const marker = (sha: string) => `<!-- agent-review sha=${sha} -->`;
704
+ export const marker = (sha: string) => `<!-- wachiman sha=${sha} -->`;
685
705
 
686
706
  /**
687
707
  * What the review at `sha` left for the next run (ADR 0036). A complete review leaves nothing
@@ -775,7 +795,7 @@ export const neutralise = (text: string) =>
775
795
  *
776
796
  * <!-- wachi:review -->
777
797
  *
778
- * <!-- agent-review sha=… -->
798
+ * <!-- wachiman sha=… -->
779
799
  *
780
800
  * and the marker is read only as the last line, right after the signature (`postReview` then adds
781
801
  * its `<!-- wachi:attempt id=… -->` line after it, which is allowed). A partial, unscoped review
@@ -1100,6 +1120,8 @@ export function buildReview(input: {
1100
1120
  effort?: string;
1101
1121
  /** An automatic run: its footer gets the flag the pull request's ceiling sums (ADR 0012). */
1102
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;
1103
1125
  /** The configured mention keyword, for the hint on how to ask for the rest. */
1104
1126
  mention?: string;
1105
1127
  /** Files the engine kept out of `files` because no model can review them (binaries). */
@@ -1201,7 +1223,7 @@ export function buildReview(input: {
1201
1223
  : "";
1202
1224
  if (notReviewed.length > 0) {
1203
1225
  parts.push(
1204
- branded(`⚠️ **Partial review**: the agent 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.`),
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.`),
1205
1227
  );
1206
1228
  } else {
1207
1229
  parts.push(
@@ -1253,6 +1275,7 @@ export function buildReview(input: {
1253
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>`,
1254
1276
  );
1255
1277
  }
1278
+ if (input.receiptLine) parts.push(input.receiptLine);
1256
1279
  parts.push(
1257
1280
  costLine({
1258
1281
  modelLabel,
@@ -1587,8 +1610,8 @@ empty list. Cite only lines you read: the engine checks that each cited line exi
1587
1610
  answer is true. When an answer shows a defect, report it as a finding as well.`;
1588
1611
 
1589
1612
  export const FOCUS_PATH = ".github/wachiman.md";
1590
- /** The paths used before the rename, newest first; the first one found is still read, with a notice. */
1591
- 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;
1592
1615
 
1593
1616
  /** Repository rules the engine reads from the pull request's base commit, in prompt order. */
1594
1617
  export const INSTRUCTION_PATHS = [FOCUS_PATH, "CLAUDE.md", "AGENTS.md"] as const;
@@ -1815,6 +1838,12 @@ export interface Deps extends CoreDeps {
1815
1838
  * current directory.
1816
1839
  */
1817
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[];
1818
1847
  }
1819
1848
 
1820
1849
  const blockingSleep = (ms: number) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -2373,6 +2402,286 @@ export function ceilingRoom(
2373
2402
  return null;
2374
2403
  }
2375
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
+
2376
2685
  /** The estimate of reviewing `files` with this configuration: the batches `planBatches` makes, priced per batch. */
2377
2686
  export function estimateFor(files: ReviewFile[], config: EngineConfig): ReviewEstimate {
2378
2687
  const batches = planBatches(files, { maxLines: config.batchLines, maxChars: config.batchChars }).length;
@@ -3213,6 +3522,8 @@ export function githubReview(
3213
3522
  scoped: boolean;
3214
3523
  mention: string;
3215
3524
  automatic: boolean;
3525
+ /** The ledger's footer lines, when the run has any. */
3526
+ receiptLine?: string;
3216
3527
  /** Computed by the connector from every file of the pull request, not only the reviewed ones. */
3217
3528
  instructionChanges: { files: string[]; baseSha: string };
3218
3529
  /** The run is on a Claude subscription: the footer says its dollars are estimates. */
@@ -3247,6 +3558,7 @@ export function githubReview(
3247
3558
  modelLabel: result.provider.label,
3248
3559
  effort: result.provider.effort,
3249
3560
  automatic: github.automatic,
3561
+ receiptLine: github.receiptLine,
3250
3562
  mention: github.mention,
3251
3563
  instructionChanges: github.instructionChanges,
3252
3564
  riskMap: result.riskMap,
@@ -3257,7 +3569,8 @@ export function githubReview(
3257
3569
  });
3258
3570
  }
3259
3571
 
3260
- 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) {
3261
3574
  const { gh, config } = deps;
3262
3575
  const meta = JSON.parse(
3263
3576
  gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,title,body,author"]),
@@ -3273,7 +3586,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3273
3586
  );
3274
3587
  if (ignored.length > 0)
3275
3588
  deps.log(`Not paths in this pull request, ignored: ${ignored.join(" ")}`);
3276
- // A dry run may ask for the whole pull request again (AGENT_REVIEW_FULL_REVIEW): no marker read.
3589
+ // A dry run may ask for the whole pull request again (WACHIMAN_FULL_REVIEW): no marker read.
3277
3590
  const state = config.fullReview ? null : lastReviewState(gh, repo, pr);
3278
3591
  const last = state?.sha ?? null;
3279
3592
  // What the last review did not reach (ADR 0036), by name. Only an unscoped run carries it over: a
@@ -3468,7 +3781,6 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3468
3781
  const prior = automatic ? { spent: ceiling.spent, runs: ceiling.runs } : undefined;
3469
3782
  const base = baseSha(gh, repo, pr);
3470
3783
  const instructions = readBaseInstructions(gh, repo, base, deps.warn);
3471
- const totalBudget = Math.min(config.budgetUsd, ceiling.room);
3472
3784
  const batchBudget = config.batchBudgetUsd;
3473
3785
  // Only threads that wait for an answer (the owner wrote last, Wachiman has replies left): a
3474
3786
  // thread Wachiman already answered is not read again, so it is not answered twice (ADR 0008).
@@ -3492,13 +3804,18 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3492
3804
  // PR Confidence grades a full review only (ADR 0033): an incremental or scoped review reads a
3493
3805
  // part of the change, and "nothing else changed" cannot be said of a part.
3494
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);
3495
3811
  const options: ReviewOptions = {
3496
3812
  ...reviewOptionsOf(config, totalBudget),
3497
3813
  ...(config.confidence && fullReview ? { confidence: { budgetUsd: CLAIMS_BUDGET_USD } } : {}),
3498
3814
  };
3499
- const result = reviewChange(input, options, deps);
3815
+ const result = settledOnError(deps, grant, () => reviewChange(input, options, deps));
3500
3816
  const { usage, costUsdEstimate: spent } = result.execution;
3501
3817
  const operation: Operation = since ? "re-review" : "review";
3818
+ const receiptLine = spendSettle(deps, grant, spent) ?? undefined;
3502
3819
 
3503
3820
  if (result.execution.callsWithOutput === 0) {
3504
3821
  // A failed automatic run still spent money: its notice carries the cost line the ceiling sums.
@@ -3507,6 +3824,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3507
3824
  ? postReview(deps, repo, pr, headSha, {
3508
3825
  body: [
3509
3826
  branded(text),
3827
+ ...(receiptLine ? [receiptLine] : []),
3510
3828
  costLine({
3511
3829
  modelLabel: result.provider.label,
3512
3830
  effort: config.effort,
@@ -3521,7 +3839,10 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3521
3839
  ].join("\n\n"),
3522
3840
  comments: [],
3523
3841
  })
3524
- : 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);
3525
3846
  const { rejection, stop } = result.execution;
3526
3847
  const refused = rejection && rejection.kind !== "other" ? { kind: rejection.kind, text: rejection.text } : undefined;
3527
3848
  if (refused) {
@@ -3579,6 +3900,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3579
3900
  scoped: paths.length > 0,
3580
3901
  mention: config.mention,
3581
3902
  automatic,
3903
+ receiptLine,
3582
3904
  instructionChanges: {
3583
3905
  files: changedInstructionFiles(prFiles.map((f) => f.filename)),
3584
3906
  baseSha: instructions.baseSha,
@@ -3745,7 +4067,6 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3745
4067
  }
3746
4068
  const ceiling = ceilingRoom(deps, repo, pr, headSha);
3747
4069
  if (ceiling === null) return;
3748
- const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room);
3749
4070
 
3750
4071
  const meta = JSON.parse(gh(["pr", "view", String(pr), "-R", repo, "--json", "title,body,author"]));
3751
4072
  const repoDir = deps.repoDir ?? process.cwd();
@@ -3758,16 +4079,23 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3758
4079
  join(dir, "threads.json"),
3759
4080
  JSON.stringify(pending.map((t) => ({ ...t, code: codeAround(repoDir, t.path, t.line) })), null, 2),
3760
4081
  );
3761
- const call = runProvider(
3762
- deps,
3763
- config,
3764
- repoDir,
3765
- { operation: "reply", label: "threads", repo, pr },
3766
- buildThreadsPrompt({ pr, repo, headSha }, dir),
3767
- dir,
3768
- budgetUsd,
3769
- 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
+ ),
3770
4097
  );
4098
+ const receiptLine = spendSettle(deps, grant, call.costUsd);
3771
4099
  const raw = !call.isError ? (call.structuredOutput as { thread_replies?: ThreadReply[] } | undefined) : undefined;
3772
4100
  if (!raw || !Array.isArray(raw.thread_replies)) {
3773
4101
  throw new Error(`The agent did not answer the threads (${call.terminalReason}); $${call.costUsd.toFixed(2)} spent.`);
@@ -3811,7 +4139,7 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3811
4139
  const prior = { spent: ceiling.spent, runs: ceiling.runs };
3812
4140
  const cost =
3813
4141
  i === 0
3814
- ? `\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}`
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}`
3815
4143
  : `\n\n<sub>this run $${call.costUsd.toFixed(2)} · ${prSoFar(prior, call.costUsd)}${estimateTail(onSubscription(deps))}</sub>`;
3816
4144
  const body = `${branded(`**${label}**`)} at \`${short(headSha)}\`: ${neutralise(reply.reply)}${cost}\n\n${SIGNATURE.reply}`;
3817
4145
  if (config.dryRun) {
@@ -4082,7 +4410,7 @@ function reviewBatch(
4082
4410
  part: { index: number; total: number; retry?: boolean },
4083
4411
  budgetUsd: number,
4084
4412
  ) {
4085
- const dir = mkdtempSync(join(tmpdir(), "agent-review-"));
4413
+ const dir = mkdtempSync(join(tmpdir(), "wachiman-review-"));
4086
4414
  // The run dir holds the change's text (title, body, threads, evidence): removed once the call
4087
4415
  // is over, whatever happened. Nothing reads it after the provider returns.
4088
4416
  try {
@@ -4404,6 +4732,14 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4404
4732
  thread: line && !walkthrough ? threadBefore(deps.gh, repo, pr, line) : undefined,
4405
4733
  });
4406
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
+ }
4407
4743
  let result: ReturnType<typeof runProvider> | undefined;
4408
4744
  let failure = "";
4409
4745
  try {
@@ -4414,16 +4750,20 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4414
4750
  { operation: "on-demand", label: "question", repo, pr },
4415
4751
  prompt,
4416
4752
  dir,
4417
- deps.config.answerBudgetUsd,
4753
+ Math.min(deps.config.answerBudgetUsd, grant.roomUsd),
4418
4754
  ASK_SCHEMA,
4419
4755
  );
4420
4756
  } catch (error) {
4421
4757
  // The call died without a result: for someone but the operator it is counted at its cap below.
4422
- if (asker === undefined) throw error;
4758
+ if (asker === undefined) {
4759
+ spendSettle(deps, grant, spentSince(deps, grant));
4760
+ throw error;
4761
+ }
4423
4762
  failure = String(error).slice(0, 200);
4424
4763
  }
4425
4764
  const parsed = result && !result.isError ? result.structuredOutput : undefined;
4426
- 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);
4427
4767
  const build = (text: string) => {
4428
4768
  const cost = costLine({
4429
4769
  modelLabel: deps.provider.modelLabel(),
@@ -4434,7 +4774,7 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4434
4774
  costUsd,
4435
4775
  });
4436
4776
  const signed = asker === undefined ? SIGNATURE.answer : `${SIGNATURE.ask}\n\n${SIGNATURE.answer}`;
4437
- 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}`;
4438
4778
  };
4439
4779
  let text: string;
4440
4780
  if (isAskAnswer(parsed)) {
@@ -4506,7 +4846,11 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4506
4846
  const operatorAsked =
4507
4847
  author === undefined ? askers === "operator" || deps.config.dryRun : author.toLowerCase() === operator.toLowerCase();
4508
4848
  if (operatorAsked) {
4509
- 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
+ }
4510
4854
  else if (command) answer(deps, repo, pr, request, { line });
4511
4855
  return;
4512
4856
  }
@@ -4515,7 +4859,7 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4515
4859
  return;
4516
4860
  }
4517
4861
  if (author === undefined) {
4518
- 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.");
4519
4863
  }
4520
4864
  if (command?.kind !== "answer") {
4521
4865
  deps.warn(`Comment by ${author} is not a question; only the operator starts a review. Nothing to do.`);