wachiman 1.13.0 → 1.15.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 (45) hide show
  1. package/README.md +2 -2
  2. package/bin/wachiman.js +1 -1
  3. package/package.json +5 -4
  4. package/skills/wachiman-review/SKILL.md +2 -2
  5. package/src/accounts/confirm.ts +62 -3
  6. package/src/cli.ts +136 -132
  7. package/src/config.ts +83 -35
  8. package/src/connectors/local-git.ts +1 -1
  9. package/src/cost.ts +28 -1
  10. package/src/engine.ts +396 -38
  11. package/src/help.ts +555 -0
  12. package/src/history/store.ts +5 -5
  13. package/src/init/options.ts +1 -1
  14. package/src/init/run.ts +43 -17
  15. package/src/ledger-read/command.ts +106 -0
  16. package/src/ledger-read/credentials.ts +103 -0
  17. package/src/ledger-read/files.ts +141 -0
  18. package/src/ledger-read/pull.ts +69 -0
  19. package/src/ledger-read/rows.ts +60 -0
  20. package/src/ledger-read/types.ts +127 -0
  21. package/src/ledger.ts +322 -0
  22. package/src/local.ts +4 -4
  23. package/src/providers/claude-code.ts +1 -1
  24. package/src/providers/codex.ts +5 -5
  25. package/src/providers/index.ts +1 -1
  26. package/src/providers/types.ts +3 -3
  27. package/src/setup/run.ts +27 -10
  28. package/src/sinks/common.ts +3 -3
  29. package/src/spend/report.ts +349 -0
  30. package/src/status/command.ts +151 -37
  31. package/src/store/command.ts +20 -3
  32. package/src/store/html.ts +205 -8
  33. package/src/store/index.ts +64 -5
  34. package/src/store/rows.ts +103 -0
  35. package/src/wizard/interactive.ts +11 -0
  36. package/src/wizard/launcher.ts +340 -0
  37. package/src/wizard/load.ts +30 -0
  38. package/src/wizard/mascot.ts +223 -0
  39. package/src/wizard/prompt-fancy.ts +127 -0
  40. package/src/wizard/prompt.ts +95 -61
  41. package/src/wizard/style.ts +93 -13
  42. package/src/wizard/tone.ts +11 -0
  43. package/src/wizard/ui.ts +78 -0
  44. package/templates/caller-workflow.yml +44 -47
  45. package/templates/wachiman-review-caller.yml +5 -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,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,300 @@ 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
+ /** Runs that already said the ledger is skipped, so the line appears once. */
2548
+ const skippedLedger = new WeakSet<Deps>();
2549
+
2550
+ /**
2551
+ * Asks the ledger how much this run may spend, before any model call. With no `ledger_url` there is
2552
+ * nothing to ask and the room is unlimited; `limit_bypass` skips the ledger the same way, and the
2553
+ * footer says so. A refusal for a limit posts the notice (once per period per pull request) and
2554
+ * throws `SpendLimitReached`. A repository the ledger does not know, an identity it does not
2555
+ * accept and a job without an OIDC token are configuration errors: `LedgerStopped`, whatever
2556
+ * `ledger_unavailable` says. A ledger that cannot be reached lets the run go on under its normal
2557
+ * budgets (`unreached`), or stops it with `LedgerStopped` when `ledger_unavailable` is `stop`.
2558
+ * Outside GitHub Actions (`GITHUB_ACTIONS` is not `true`) nothing is asked: the run goes on and a
2559
+ * line says so.
2560
+ */
2561
+ export function spendReserve(deps: Deps, repo: string, pr: number, headSha: string, wantedUsd: number, forced: boolean): SpendGrant {
2562
+ const { config } = deps;
2563
+ const open = { reservationId: null, roomUsd: Number.POSITIVE_INFINITY, costsFrom: deps.costs?.length ?? 0, trigger: config.trigger ?? "cli", pr };
2564
+ if (!config.ledgerUrl) return { kind: "none", ...open };
2565
+ // Laptop runs are not counted against the limit: `WACHIMAN_LEDGER_URL` there is the read side's
2566
+ // setting (`wachiman ledger`), not a request to reserve. Only a GitHub Actions job reserves.
2567
+ if ((deps.ledgerEnv ?? process.env).GITHUB_ACTIONS !== "true") {
2568
+ if (!skippedLedger.has(deps)) {
2569
+ skippedLedger.add(deps);
2570
+ deps.warn("The spend ledger is skipped: this is not a GitHub Actions run, and laptop runs are not counted against the limit.");
2571
+ }
2572
+ return { kind: "none", ...open };
2573
+ }
2574
+ if (config.limitBypass) {
2575
+ deps.log("ledger bypassed");
2576
+ ledgerNote(deps, "The spend limit was bypassed for this run (`limit_bypass`); nothing was reserved or recorded.");
2577
+ return { kind: "bypassed", ...open };
2578
+ }
2579
+ const curl = deps.curl ?? defaultCurl;
2580
+ try {
2581
+ const token = requestIdToken(deps.ledgerEnv ?? process.env, config.ledgerUrl, curl);
2582
+ const granted = ledgerReserve(
2583
+ config.ledgerUrl,
2584
+ token,
2585
+ {
2586
+ wantedUsd,
2587
+ callerLimitUsd: config.dailyBudgetUsd,
2588
+ callerWeeklyLimitUsd: config.weeklyBudgetUsd,
2589
+ trigger: open.trigger,
2590
+ forced,
2591
+ pr,
2592
+ },
2593
+ curl,
2594
+ );
2595
+ return { kind: "reserved", ...open, reservationId: granted.reservationId, roomUsd: granted.grantedUsd, reservedUsd: granted.grantedUsd, ...(forced ? { forced: true } : {}) };
2596
+ } catch (error) {
2597
+ if (error instanceof LedgerRefused) {
2598
+ const { reason } = error.refusal;
2599
+ if (reason === "limit" || reason === "weekly_limit" || reason === "repository_limit") {
2600
+ postLimitNotice(deps, repo, pr, headSha, error.refusal);
2601
+ const message = limitSentence(deps, error.refusal).replace(/\*\*/g, "");
2602
+ ledgerNote(deps, `A spend limit refused this run before any model call: ${message}`);
2603
+ throw new SpendLimitReached(error.refusal, config.limitMode, message);
2604
+ }
2605
+ const message =
2606
+ reason === "not_linked"
2607
+ ? "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`)."
2608
+ : "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.";
2609
+ ledgerNote(deps, message);
2610
+ throw new LedgerStopped(message);
2611
+ }
2612
+ if (error instanceof LedgerBadAnswer) {
2613
+ // A wrong address or a broken service, not an outage: `ledger_unavailable` does not apply.
2614
+ ledgerNote(deps, error.message);
2615
+ throw new LedgerStopped(error.message);
2616
+ }
2617
+ if (error instanceof LedgerNotPermitted) {
2618
+ const message =
2619
+ "`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).";
2620
+ ledgerNote(deps, message);
2621
+ throw new LedgerStopped(message);
2622
+ }
2623
+ if (error instanceof LedgerUnavailable) {
2624
+ if (config.ledgerUnavailable === "stop") {
2625
+ 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.`;
2626
+ ledgerNote(deps, message);
2627
+ throw new LedgerStopped(message);
2628
+ }
2629
+ deps.warn(`The spend ledger could not be reached; reviewing under the normal budgets: ${short200(error)}`);
2630
+ return { kind: "unreached", ...open };
2631
+ }
2632
+ throw error;
2633
+ }
2634
+ }
2635
+
2636
+ /**
2637
+ * Tells the ledger what the run spent, with the calls it made, and returns the footer lines for the
2638
+ * review (joined by a blank line), or null when there is nothing to say. Nothing here fails the
2639
+ * run. After a reservation: the signed receipt (a failed settle leaves the reservation counted at
2640
+ * the reserved amount, and the job summary says so). After an unreachable ledger: the run is
2641
+ * recorded once, apart from reserved runs; the footer says it was not counted, and the job summary
2642
+ * says whether it was recorded. A forced run's lines also carry the forced footer.
2643
+ */
2644
+ export function spendSettle(deps: Deps, grant: SpendGrant, spentUsd: number): string | null {
2645
+ const { ledgerUrl } = deps.config;
2646
+ if (grant.kind === "bypassed") return `${LEDGER_BYPASSED_NOTE}\n\n${LEDGER_BYPASSED_FOOTER}`;
2647
+ if (grant.kind === "none" || !ledgerUrl) return null;
2648
+ const curl = deps.curl ?? defaultCurl;
2649
+ const calls = (deps.costs ?? []).slice(grant.costsFrom).map(ledgerCall);
2650
+ if (grant.kind === "unreached") {
2651
+ try {
2652
+ ledgerRecord(ledgerUrl, requestIdToken(deps.ledgerEnv ?? process.env, ledgerUrl, curl), { spentUsd, calls, trigger: grant.trigger, pr: grant.pr }, curl);
2653
+ 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.");
2654
+ } catch (error) {
2655
+ deps.warn(`Could not record the run with the ledger: ${short200(error)}`);
2656
+ 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.");
2657
+ }
2658
+ return LEDGER_NOT_COUNTED_NOTE;
2659
+ }
2660
+ try {
2661
+ // A fresh token: a long run can outlive the one `spendReserve` used.
2662
+ const token = requestIdToken(deps.ledgerEnv ?? process.env, ledgerUrl, curl);
2663
+ const { receipt, signature } = ledgerSettle(ledgerUrl, token, grant.reservationId!, spentUsd, calls, curl);
2664
+ const line = receiptFooter(receipt, signature);
2665
+ return grant.forced ? `${line}\n\n${LEDGER_FORCED_FOOTER}` : line;
2666
+ } catch (error) {
2667
+ deps.warn(`Could not settle with the ledger; the reservation stays counted: ${short200(error)}`);
2668
+ 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.`);
2669
+ return grant.forced ? LEDGER_FORCED_FOOTER : null;
2670
+ }
2671
+ }
2672
+
2673
+ /**
2674
+ * Whether the ledger granted less than a call needs (the minimum the review path also uses). When
2675
+ * so, the run makes no model call: it settles with 0, so the reservation is released, and the job
2676
+ * summary says so. Only a reserved grant can be this small: with no ledger the room is unlimited.
2677
+ */
2678
+ function grantTooSmall(deps: Deps, grant: SpendGrant, what: string): boolean {
2679
+ if (grant.kind !== "reserved" || grant.roomUsd >= MIN_BATCH_USD) return false;
2680
+ spendSettle(deps, grant, 0);
2681
+ ledgerNote(
2682
+ deps,
2683
+ `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}.` : ""}`,
2684
+ );
2685
+ deps.log(`The ledger granted ${usd(grant.roomUsd)}, below the minimum for ${what}; no model call.`);
2686
+ return true;
2687
+ }
2688
+
2689
+ /** Runs a paid step; if it throws, the ledger still hears what the calls so far cost, then the error goes on. */
2690
+ function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => T): T {
2691
+ try {
2692
+ return run();
2693
+ } catch (error) {
2694
+ spendSettle(deps, grant, spentSince(deps, grant));
2695
+ throw error;
2696
+ }
2697
+ }
2698
+
2376
2699
  /** The estimate of reviewing `files` with this configuration: the batches `planBatches` makes, priced per batch. */
2377
2700
  export function estimateFor(files: ReviewFile[], config: EngineConfig): ReviewEstimate {
2378
2701
  const batches = planBatches(files, { maxLines: config.batchLines, maxChars: config.batchChars }).length;
@@ -3213,6 +3536,8 @@ export function githubReview(
3213
3536
  scoped: boolean;
3214
3537
  mention: string;
3215
3538
  automatic: boolean;
3539
+ /** The ledger's footer lines, when the run has any. */
3540
+ receiptLine?: string;
3216
3541
  /** Computed by the connector from every file of the pull request, not only the reviewed ones. */
3217
3542
  instructionChanges: { files: string[]; baseSha: string };
3218
3543
  /** The run is on a Claude subscription: the footer says its dollars are estimates. */
@@ -3247,6 +3572,7 @@ export function githubReview(
3247
3572
  modelLabel: result.provider.label,
3248
3573
  effort: result.provider.effort,
3249
3574
  automatic: github.automatic,
3575
+ receiptLine: github.receiptLine,
3250
3576
  mention: github.mention,
3251
3577
  instructionChanges: github.instructionChanges,
3252
3578
  riskMap: result.riskMap,
@@ -3257,7 +3583,8 @@ export function githubReview(
3257
3583
  });
3258
3584
  }
3259
3585
 
3260
- export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3586
+ /** `force` (`--force`) counts only for the operator's own run, never an automatic trigger. */
3587
+ export function review(deps: Deps, repo: string, pr: number, words: string[], force = false) {
3261
3588
  const { gh, config } = deps;
3262
3589
  const meta = JSON.parse(
3263
3590
  gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,title,body,author"]),
@@ -3273,7 +3600,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3273
3600
  );
3274
3601
  if (ignored.length > 0)
3275
3602
  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.
3603
+ // A dry run may ask for the whole pull request again (WACHIMAN_FULL_REVIEW): no marker read.
3277
3604
  const state = config.fullReview ? null : lastReviewState(gh, repo, pr);
3278
3605
  const last = state?.sha ?? null;
3279
3606
  // What the last review did not reach (ADR 0036), by name. Only an unscoped run carries it over: a
@@ -3468,7 +3795,6 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3468
3795
  const prior = automatic ? { spent: ceiling.spent, runs: ceiling.runs } : undefined;
3469
3796
  const base = baseSha(gh, repo, pr);
3470
3797
  const instructions = readBaseInstructions(gh, repo, base, deps.warn);
3471
- const totalBudget = Math.min(config.budgetUsd, ceiling.room);
3472
3798
  const batchBudget = config.batchBudgetUsd;
3473
3799
  // Only threads that wait for an answer (the owner wrote last, Wachiman has replies left): a
3474
3800
  // thread Wachiman already answered is not read again, so it is not answered twice (ADR 0008).
@@ -3492,13 +3818,18 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3492
3818
  // PR Confidence grades a full review only (ADR 0033): an incremental or scoped review reads a
3493
3819
  // part of the change, and "nothing else changed" cannot be said of a part.
3494
3820
  const fullReview = since === null && paths.length === 0;
3821
+ // Everything the run reads from GitHub is read by now. The ledger is asked last, just before the
3822
+ // first paid step, so a failing read cannot leave a reservation that nobody settles.
3823
+ const grant = spendReserve(deps, repo, pr, headSha, Math.min(config.budgetUsd, ceiling.room), force && !automatic);
3824
+ const totalBudget = Math.min(config.budgetUsd, ceiling.room, grant.roomUsd);
3495
3825
  const options: ReviewOptions = {
3496
3826
  ...reviewOptionsOf(config, totalBudget),
3497
3827
  ...(config.confidence && fullReview ? { confidence: { budgetUsd: CLAIMS_BUDGET_USD } } : {}),
3498
3828
  };
3499
- const result = reviewChange(input, options, deps);
3829
+ const result = settledOnError(deps, grant, () => reviewChange(input, options, deps));
3500
3830
  const { usage, costUsdEstimate: spent } = result.execution;
3501
3831
  const operation: Operation = since ? "re-review" : "review";
3832
+ const receiptLine = spendSettle(deps, grant, spent) ?? undefined;
3502
3833
 
3503
3834
  if (result.execution.callsWithOutput === 0) {
3504
3835
  // A failed automatic run still spent money: its notice carries the cost line the ceiling sums.
@@ -3507,6 +3838,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3507
3838
  ? postReview(deps, repo, pr, headSha, {
3508
3839
  body: [
3509
3840
  branded(text),
3841
+ ...(receiptLine ? [receiptLine] : []),
3510
3842
  costLine({
3511
3843
  modelLabel: result.provider.label,
3512
3844
  effort: config.effort,
@@ -3521,7 +3853,10 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3521
3853
  ].join("\n\n"),
3522
3854
  comments: [],
3523
3855
  })
3524
- : bodyOnly(text);
3856
+ : // A manual run keeps its receipt and forced/bypass lines, but not `SIGNATURE.auto`: the ceiling does not count it.
3857
+ receiptLine
3858
+ ? postReview(deps, repo, pr, headSha, { body: [branded(text), receiptLine].join("\n\n"), comments: [] })
3859
+ : bodyOnly(text);
3525
3860
  const { rejection, stop } = result.execution;
3526
3861
  const refused = rejection && rejection.kind !== "other" ? { kind: rejection.kind, text: rejection.text } : undefined;
3527
3862
  if (refused) {
@@ -3579,6 +3914,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[]) {
3579
3914
  scoped: paths.length > 0,
3580
3915
  mention: config.mention,
3581
3916
  automatic,
3917
+ receiptLine,
3582
3918
  instructionChanges: {
3583
3919
  files: changedInstructionFiles(prFiles.map((f) => f.filename)),
3584
3920
  baseSha: instructions.baseSha,
@@ -3745,7 +4081,6 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3745
4081
  }
3746
4082
  const ceiling = ceilingRoom(deps, repo, pr, headSha);
3747
4083
  if (ceiling === null) return;
3748
- const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room);
3749
4084
 
3750
4085
  const meta = JSON.parse(gh(["pr", "view", String(pr), "-R", repo, "--json", "title,body,author"]));
3751
4086
  const repoDir = deps.repoDir ?? process.cwd();
@@ -3758,16 +4093,23 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3758
4093
  join(dir, "threads.json"),
3759
4094
  JSON.stringify(pending.map((t) => ({ ...t, code: codeAround(repoDir, t.path, t.line) })), null, 2),
3760
4095
  );
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,
4096
+ // The ledger is asked last, after every read and write above, so a failing one leaves no reservation unsettled.
4097
+ const grant = spendReserve(deps, repo, pr, headSha, Math.min(config.threadsBudgetUsd, ceiling.room), false);
4098
+ const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room, grant.roomUsd);
4099
+ if (grantTooSmall(deps, grant, "thread replies")) return;
4100
+ const call = settledOnError(deps, grant, () =>
4101
+ runProvider(
4102
+ deps,
4103
+ config,
4104
+ repoDir,
4105
+ { operation: "reply", label: "threads", repo, pr },
4106
+ buildThreadsPrompt({ pr, repo, headSha }, dir),
4107
+ dir,
4108
+ budgetUsd,
4109
+ THREAD_SCHEMA,
4110
+ ),
3770
4111
  );
4112
+ const receiptLine = spendSettle(deps, grant, call.costUsd);
3771
4113
  const raw = !call.isError ? (call.structuredOutput as { thread_replies?: ThreadReply[] } | undefined) : undefined;
3772
4114
  if (!raw || !Array.isArray(raw.thread_replies)) {
3773
4115
  throw new Error(`The agent did not answer the threads (${call.terminalReason}); $${call.costUsd.toFixed(2)} spent.`);
@@ -3811,7 +4153,7 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
3811
4153
  const prior = { spent: ceiling.spent, runs: ceiling.runs };
3812
4154
  const cost =
3813
4155
  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}`
4156
+ ? `${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
4157
  : `\n\n<sub>this run $${call.costUsd.toFixed(2)} · ${prSoFar(prior, call.costUsd)}${estimateTail(onSubscription(deps))}</sub>`;
3816
4158
  const body = `${branded(`**${label}**`)} at \`${short(headSha)}\`: ${neutralise(reply.reply)}${cost}\n\n${SIGNATURE.reply}`;
3817
4159
  if (config.dryRun) {
@@ -4082,7 +4424,7 @@ function reviewBatch(
4082
4424
  part: { index: number; total: number; retry?: boolean },
4083
4425
  budgetUsd: number,
4084
4426
  ) {
4085
- const dir = mkdtempSync(join(tmpdir(), "agent-review-"));
4427
+ const dir = mkdtempSync(join(tmpdir(), "wachiman-review-"));
4086
4428
  // The run dir holds the change's text (title, body, threads, evidence): removed once the call
4087
4429
  // is over, whatever happened. Nothing reads it after the provider returns.
4088
4430
  try {
@@ -4404,6 +4746,14 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4404
4746
  thread: line && !walkthrough ? threadBefore(deps.gh, repo, pr, line) : undefined,
4405
4747
  });
4406
4748
  // One question is one call, with the budget a whole review had before batches: $1.
4749
+ const grant = spendReserve(deps, repo, pr, headSha, deps.config.answerBudgetUsd, false);
4750
+ if (grantTooSmall(deps, grant, "an answer")) {
4751
+ 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.`;
4752
+ const body = `${BRAND}\n\n${note}\n\n${asker === undefined ? SIGNATURE.answer : `${SIGNATURE.ask}\n\n${SIGNATURE.answer}`}`;
4753
+ if (deps.config.dryRun) deps.log(body);
4754
+ else postAnswer(deps, repo, pr, body, line);
4755
+ return;
4756
+ }
4407
4757
  let result: ReturnType<typeof runProvider> | undefined;
4408
4758
  let failure = "";
4409
4759
  try {
@@ -4414,16 +4764,20 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4414
4764
  { operation: "on-demand", label: "question", repo, pr },
4415
4765
  prompt,
4416
4766
  dir,
4417
- deps.config.answerBudgetUsd,
4767
+ Math.min(deps.config.answerBudgetUsd, grant.roomUsd),
4418
4768
  ASK_SCHEMA,
4419
4769
  );
4420
4770
  } catch (error) {
4421
4771
  // The call died without a result: for someone but the operator it is counted at its cap below.
4422
- if (asker === undefined) throw error;
4772
+ if (asker === undefined) {
4773
+ spendSettle(deps, grant, spentSince(deps, grant));
4774
+ throw error;
4775
+ }
4423
4776
  failure = String(error).slice(0, 200);
4424
4777
  }
4425
4778
  const parsed = result && !result.isError ? result.structuredOutput : undefined;
4426
- const costUsd = result?.costUsd ?? deps.config.answerBudgetUsd;
4779
+ const costUsd = result?.costUsd ?? Math.min(deps.config.answerBudgetUsd, grant.roomUsd);
4780
+ const receiptLine = spendSettle(deps, grant, costUsd);
4427
4781
  const build = (text: string) => {
4428
4782
  const cost = costLine({
4429
4783
  modelLabel: deps.provider.modelLabel(),
@@ -4434,7 +4788,7 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4434
4788
  costUsd,
4435
4789
  });
4436
4790
  const signed = asker === undefined ? SIGNATURE.answer : `${SIGNATURE.ask}\n\n${SIGNATURE.answer}`;
4437
- return `${BRAND}\n\n${text}\n\n${cost}\n\n${signed}`;
4791
+ return `${BRAND}\n\n${text}\n\n${receiptLine ? `${receiptLine}\n\n` : ""}${cost}\n\n${signed}`;
4438
4792
  };
4439
4793
  let text: string;
4440
4794
  if (isAskAnswer(parsed)) {
@@ -4506,7 +4860,11 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4506
4860
  const operatorAsked =
4507
4861
  author === undefined ? askers === "operator" || deps.config.dryRun : author.toLowerCase() === operator.toLowerCase();
4508
4862
  if (operatorAsked) {
4509
- if (command?.kind === "review") review(deps, repo, pr, command.paths);
4863
+ if (command?.kind === "review") {
4864
+ // With no ledger `--force` means nothing: it stays a word that names no file, as it always did.
4865
+ const words = deps.config.ledgerUrl ? command.paths.filter((w) => w !== "--force") : command.paths;
4866
+ review(deps, repo, pr, words, command.force);
4867
+ }
4510
4868
  else if (command) answer(deps, repo, pr, request, { line });
4511
4869
  return;
4512
4870
  }
@@ -4515,7 +4873,7 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4515
4873
  return;
4516
4874
  }
4517
4875
  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.");
4876
+ throw new Error("askers is write, but the caller did not say who wrote the comment (WACHIMAN_COMMENT_AUTHOR); not answering.");
4519
4877
  }
4520
4878
  if (command?.kind !== "answer") {
4521
4879
  deps.warn(`Comment by ${author} is not a question; only the operator starts a review. Nothing to do.`);