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
@@ -10,7 +10,7 @@ import { UsageError } from "../config";
10
10
  import type { TokenUsage } from "../cost";
11
11
  import { locatePrompt } from "./locate";
12
12
  import { classifyProviderError } from "./errors";
13
- import { DEFAULT_CALL_TIMEOUT_S, DEFAULT_EFFORT, type Effort, type NeutralTool, type ProviderAdapter, ProviderRequest, ProviderResult } from "./types";
13
+ import { DEFAULT_CALL_TIMEOUT_S, DEFAULT_EFFORT, type Effort, type NeutralTool, type ProviderAdapter, type ProviderAuth, ProviderRequest, ProviderResult } from "./types";
14
14
 
15
15
  const BINARY = "claude";
16
16
  const SETTINGS_FILE = "claude-code.settings.json";
@@ -36,8 +36,14 @@ export function prettyModel(model: string): string {
36
36
  return `Claude ${family} ${match[2].replaceAll("-", ".")}`;
37
37
  }
38
38
 
39
- export function leaksKey(texts: string[], key: string) {
40
- return texts.some((t) => (key !== "" && t.includes(key)) || KEY_SHAPE.test(t));
39
+ /**
40
+ * True when a text holds a credential: the exact value of any of `exact` (the key, the CI token),
41
+ * or anything shaped like an Anthropic key. The shape is not loosened for the CI token: Anthropic's
42
+ * documentation does not state the token's shape, so the exact value is what the check relies on.
43
+ */
44
+ export function leaksKey(texts: string[], ...exact: string[]) {
45
+ const values = exact.filter((v) => v !== "");
46
+ return texts.some((t) => values.some((v) => t.includes(v)) || KEY_SHAPE.test(t));
41
47
  }
42
48
 
43
49
  /**
@@ -58,6 +64,9 @@ export const CHILD_ENV_ALLOWLIST = [
58
64
  "GITHUB_ACTIONS",
59
65
  ] as const;
60
66
 
67
+ /** The variable `claude setup-token` documents for CI; allowlisted only in the `oauth-token` mode. */
68
+ export const OAUTH_TOKEN_VAR = "CLAUDE_CODE_OAUTH_TOKEN";
69
+
61
70
  /**
62
71
  * What a child process needs on Windows to start and find its own sign-in: the profile and
63
72
  * application-data directories, the system root, the temporary directories and the executable
@@ -80,10 +89,22 @@ export const WINDOWS_CHILD_ENV_ALLOWLIST = [
80
89
  const LOCALE_PREFIX = "LC_";
81
90
 
82
91
  /**
83
- * `api-key`: the CI path, billed to `ANTHROPIC_API_KEY`. `subscription`: the local review, on the
84
- * developer's own signed-in `claude` (ADR 0019 decision 3); the key is refused and never forwarded.
92
+ * `api-key`: the CI path, billed to `ANTHROPIC_API_KEY`. `oauth-token`: the CI path on a
93
+ * subscription, with the token `claude setup-token` made, in `CLAUDE_CODE_OAUTH_TOKEN` (ADR 0037);
94
+ * the key is never forwarded. `subscription`: the local review, on the developer's own signed-in
95
+ * `claude` (ADR 0019 decision 3); the key is refused and never forwarded.
85
96
  */
86
- export type ClaudeAuth = "api-key" | "subscription";
97
+ export type ClaudeAuth = ProviderAuth;
98
+
99
+ /**
100
+ * The CI credential by presence, the token first: with both set, `claude -p` would bill the key
101
+ * (it outranks the token in Claude Code's precedence), so the token wins here and the key never
102
+ * reaches the child. An empty value counts as absent: a workflow that does not pass a secret still
103
+ * sets the variable, to the empty string.
104
+ */
105
+ export function resolveClaudeAuth(env: Record<string, string | undefined>): "api-key" | "oauth-token" {
106
+ return env[OAUTH_TOKEN_VAR] ? "oauth-token" : "api-key";
107
+ }
87
108
 
88
109
  /** D10: set in every local call; what each one switches off is in docs/providers/claude-code.md. */
89
110
  export const SUBSCRIPTION_ENV = {
@@ -96,7 +117,9 @@ export const SUBSCRIPTION_ENV = {
96
117
  } as const;
97
118
 
98
119
  /**
99
- * The child's environment. In subscription mode the allowlist loses `ANTHROPIC_API_KEY` and gains
120
+ * The child's environment. In `oauth-token` mode the allowlist loses `ANTHROPIC_API_KEY` and gains
121
+ * `CLAUDE_CODE_OAUTH_TOKEN`, and nothing else changes: the extras below are the local mode's. In
122
+ * subscription mode the allowlist loses `ANTHROPIC_API_KEY` and gains
100
123
  * `USER` (without it, `claude` on macOS cannot find its own sign-in: spec D17) and the D10
101
124
  * switches; `configDir` (an isolated profile) replaces any `CLAUDE_CONFIG_DIR` of the parent. The
102
125
  * sign-in itself is never read here: the binary finds it through `HOME`, `USER` and
@@ -107,14 +130,17 @@ export function buildChildEnv(
107
130
  opts: { auth?: ClaudeAuth; configDir?: string; platform?: string } = {},
108
131
  ) {
109
132
  const subscription = opts.auth === "subscription";
133
+ const token = opts.auth === "oauth-token";
110
134
  // Windows names are case-insensitive and the search path is usually `Path`, so match them so.
111
135
  const windows = (opts.platform ?? process.platform) === "win32";
112
- const allowed = new Set<string>([...CHILD_ENV_ALLOWLIST, ...(windows ? WINDOWS_CHILD_ENV_ALLOWLIST : [])].map((n) => (windows ? n.toUpperCase() : n)));
136
+ const allowed = new Set<string>(
137
+ [...CHILD_ENV_ALLOWLIST, ...(token ? [OAUTH_TOKEN_VAR] : []), ...(windows ? WINDOWS_CHILD_ENV_ALLOWLIST : [])].map((n) => (windows ? n.toUpperCase() : n)),
138
+ );
113
139
  const child: Record<string, string> = {};
114
140
  for (const [name, value] of Object.entries(env)) {
115
141
  if (value === undefined) continue;
116
142
  const key = windows ? name.toUpperCase() : name;
117
- if (subscription && key === "ANTHROPIC_API_KEY") continue;
143
+ if ((subscription || token) && key === "ANTHROPIC_API_KEY") continue;
118
144
  if (allowed.has(key) || name.startsWith(LOCALE_PREFIX)) {
119
145
  child[name] = value;
120
146
  }
@@ -278,6 +304,11 @@ export class ClaudeCodeProvider implements ProviderAdapter {
278
304
  return this.opts.auth === "subscription";
279
305
  }
280
306
 
307
+ /** What pays for the calls (`api-key` unless the constructor said otherwise). */
308
+ get auth(): ProviderAuth {
309
+ return this.opts.auth ?? "api-key";
310
+ }
311
+
281
312
  private childEnv() {
282
313
  return buildChildEnv(process.env, { auth: this.opts.auth, configDir: this.opts.configDir });
283
314
  }
@@ -301,8 +332,11 @@ export class ClaudeCodeProvider implements ProviderAdapter {
301
332
  );
302
333
  }
303
334
  this.version = probe.stdout.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
304
- if (this.opts.requireApiKey && !process.env.ANTHROPIC_API_KEY) {
305
- throw new Error("ANTHROPIC_API_KEY is not set");
335
+ if (this.opts.requireApiKey) {
336
+ if (this.auth === "oauth-token" && !process.env[OAUTH_TOKEN_VAR]) throw new Error(`${OAUTH_TOKEN_VAR} is not set`);
337
+ if (this.auth === "api-key" && !process.env.ANTHROPIC_API_KEY) {
338
+ throw new Error(`Neither ANTHROPIC_API_KEY nor ${OAUTH_TOKEN_VAR} is set: pass a Console API key, or a token from \`claude setup-token\` to review on a Claude subscription.`);
339
+ }
306
340
  }
307
341
  }
308
342
 
@@ -311,7 +345,8 @@ export class ClaudeCodeProvider implements ProviderAdapter {
311
345
  }
312
346
 
313
347
  leaksSecret(texts: string[]) {
314
- return leaksKey(texts, process.env.ANTHROPIC_API_KEY ?? "");
348
+ // The token is checked too in the CI modes: it is a credential in the engine's environment.
349
+ return leaksKey(texts, process.env.ANTHROPIC_API_KEY ?? "", this.auth === "oauth-token" ? (process.env[OAUTH_TOKEN_VAR] ?? "") : "");
315
350
  }
316
351
 
317
352
  run(request: ProviderRequest): ProviderResult {
@@ -320,7 +355,7 @@ export class ClaudeCodeProvider implements ProviderAdapter {
320
355
  // The session starts in an empty scratch directory, never in the head: Claude Code discovers
321
356
  // `CLAUDE.md` (and `.claude/`) from its working directory and its parents, and a pull request
322
357
  // must not supply instructions. The head is only an `--add-dir`, which does not load them.
323
- const workDir = mkdtempSync(join(tmpdir(), "agent-review-claude-"));
358
+ const workDir = mkdtempSync(join(tmpdir(), "wachiman-review-claude-"));
324
359
  const prompt = locatePrompt(request.prompt, request.cwd, request.addDirs, { shell: false });
325
360
  const args = buildClaudeArgs({
326
361
  addDirs: [request.cwd, ...request.addDirs],
@@ -81,7 +81,7 @@ export const CACHE_WRITE_MULTIPLIER = 2.5
81
81
 
82
82
  /**
83
83
  * List prices of the models this adapter has been set up for. A model not listed here needs
84
- * `AGENT_REVIEW_PRICE_PER_MTOK`: the engine's budgets are in dollars, and Codex reports tokens.
84
+ * `WACHIMAN_PRICE_PER_MTOK`: the engine's budgets are in dollars, and Codex reports tokens.
85
85
  */
86
86
  export const PRICES: Record<string, Price> = {
87
87
  "gpt-6.1-sol": { input: 2, cachedInput: 0.1, output: 10, cacheWrite: 5 },
@@ -93,7 +93,7 @@ export function parsePrice(raw: string): Price {
93
93
  const parts = raw.split(",").map((p) => Number(p.trim()));
94
94
  if (parts.length < 3 || parts.length > 4 || parts.some((n) => !Number.isFinite(n) || n < 0)) {
95
95
  throw new Error(
96
- `AGENT_REVIEW_PRICE_PER_MTOK must be "input,cached_input,output[,cache_write]" in USD per million tokens, got "${raw}".`,
96
+ `WACHIMAN_PRICE_PER_MTOK must be "input,cached_input,output[,cache_write]" in USD per million tokens, got "${raw}".`,
97
97
  );
98
98
  }
99
99
  return { input: parts[0], cachedInput: parts[1], output: parts[2], ...(parts.length === 4 ? { cacheWrite: parts[3] } : {}) };
@@ -171,12 +171,13 @@ export function buildChildEnv(
171
171
 
172
172
  /** The `codex exec` arguments. The prompt always goes through stdin (`-`). */
173
173
  /**
174
- * The top-level properties the engine leaves optional in a batch's schema (ADR 0031). Codex's
174
+ * The top-level properties the engine leaves optional in a batch's schema (ADR 0031; the claim
175
+ * assignments of ADR 0033 are asked for only when PR Confidence is on). Codex's
175
176
  * structured output is strict: every property must be `required`, so these are required in the
176
177
  * schema Codex receives. The model then answers an empty array when a batch has none, and a
177
178
  * missing one parses as empty (`risk.ts`). Other properties of other schemas are not touched.
178
179
  */
179
- const RISK_ARRAYS = ["risk_facts", "judgement"];
180
+ const RISK_ARRAYS = ["risk_facts", "judgement", "claim_assignments"];
180
181
 
181
182
  export function strictSchema(schema: unknown): unknown {
182
183
  if (schema === null || typeof schema !== "object") return schema;
@@ -269,7 +270,7 @@ export class CodexProvider implements ProviderAdapter {
269
270
  private readonly opts: {
270
271
  model: string;
271
272
  requireApiKey: boolean;
272
- /** `AGENT_REVIEW_PRICE_PER_MTOK`, for a model not in `PRICES`. */
273
+ /** `WACHIMAN_PRICE_PER_MTOK`, for a model not in `PRICES`. */
273
274
  priceOverride?: string;
274
275
  reasoningEffort?: string;
275
276
  /**
@@ -291,7 +292,7 @@ export class CodexProvider implements ProviderAdapter {
291
292
  preflight() {
292
293
  if (!this.price) {
293
294
  throw new Error(
294
- `No price is known for model "${this.opts.model}". Set AGENT_REVIEW_PRICE_PER_MTOK="input,cached_input,output[,cache_write]" (USD per million tokens).`,
295
+ `No price is known for model "${this.opts.model}". Set WACHIMAN_PRICE_PER_MTOK="input,cached_input,output[,cache_write]" (USD per million tokens).`,
295
296
  );
296
297
  }
297
298
  const probe = spawnSync(this.binary, ["--version"], { encoding: "utf8", env: { PATH: process.env.PATH ?? "" } });
@@ -313,7 +314,7 @@ export class CodexProvider implements ProviderAdapter {
313
314
  run(request: ProviderRequest): ProviderResult {
314
315
  const unknown = request.allowedTools.filter((t) => !READ_TOOLS.includes(t));
315
316
  if (unknown.length > 0) throw new Error(`The Codex adapter only grants reads; asked for ${unknown.join(", ")}.`);
316
- const scratch = mkdtempSync(join(tmpdir(), "agent-review-codex-"));
317
+ const scratch = mkdtempSync(join(tmpdir(), "wachiman-review-codex-"));
317
318
  try {
318
319
  const workDir = join(scratch, "work");
319
320
  const home = join(scratch, "home");
@@ -1,4 +1,4 @@
1
- import { ClaudeCodeProvider, type ClaudeAuth } from "./claude-code";
1
+ import { ClaudeCodeProvider, resolveClaudeAuth, type ClaudeAuth } from "./claude-code";
2
2
  import { CodexProvider } from "./codex";
3
3
  import type { Effort, ProviderAdapter } from "./types";
4
4
 
@@ -7,9 +7,9 @@ export type { NeutralTool, ProviderAdapter, ProviderRequest, ProviderResult } fr
7
7
  export const PROVIDER_NAMES = ["claude-code", "codex"] as const;
8
8
  export const DEFAULT_PROVIDER = "claude-code";
9
9
 
10
- /** The model each provider uses when `AGENT_REVIEW_MODEL` is not set. */
10
+ /** The model each provider uses when `WACHIMAN_MODEL` is not set. */
11
11
  export const DEFAULT_MODELS: Record<(typeof PROVIDER_NAMES)[number], string> = {
12
- "claude-code": "claude-opus-5-5",
12
+ "claude-code": "claude-sonnet-5-5",
13
13
  codex: "gpt-6.1-sol",
14
14
  };
15
15
 
@@ -31,11 +31,14 @@ export function getProvider(
31
31
  ): ProviderAdapter {
32
32
  if (name === "claude-code") {
33
33
  const subscription = options.auth === "subscription";
34
+ // GitHub mode names no auth: the credential in the environment decides (ADR 0037 decision 1).
35
+ const auth = options.auth ?? resolveClaudeAuth(process.env);
34
36
  return new ClaudeCodeProvider({
35
37
  model: options.model,
36
38
  requireApiKey: !subscription && !options.dryRun,
37
39
  effort: options.effort,
38
40
  ...(subscription ? { auth: options.auth, configDir: options.configDir, binary: options.binary } : {}),
41
+ ...(auth === "oauth-token" ? { auth } : {}),
39
42
  });
40
43
  }
41
44
  if (name === "codex") {
@@ -24,12 +24,12 @@ export type Effort = (typeof EFFORTS)[number];
24
24
  export const DEFAULT_EFFORT: Effort = "high";
25
25
 
26
26
  /**
27
- * Default cap on the agent's turns per call (`AGENT_REVIEW_MAX_TURNS`). Wachiman's batches take
27
+ * Default cap on the agent's turns per call (`WACHIMAN_MAX_TURNS`). Wachiman's batches take
28
28
  * 5–12 turns and an external agent's whole-PR reviews took 19–46, so 40 never cuts a normal batch;
29
29
  * it only stops a run that is looping.
30
30
  */
31
31
  export const DEFAULT_MAX_TURNS = 40;
32
- /** Default wall-clock limit on one provider call, in seconds (`AGENT_REVIEW_CALL_TIMEOUT_S`). */
32
+ /** Default wall-clock limit on one provider call, in seconds (`WACHIMAN_CALL_TIMEOUT_S`). */
33
33
  export const DEFAULT_CALL_TIMEOUT_S = 900;
34
34
 
35
35
  /** Tool names the engine may ask for. Each adapter maps them to its own names. */
@@ -99,9 +99,19 @@ export interface ProviderResult {
99
99
  raw: unknown;
100
100
  }
101
101
 
102
+ /**
103
+ * What pays for a call: `api-key` (a Console key, billed per token), `oauth-token` (a Claude Code
104
+ * token made with `claude setup-token`, the CI route on a subscription: ADR 0037) or `subscription`
105
+ * (the developer's own sign-in, the local mode: ADR 0019). The last two report a dollar figure that
106
+ * is an API-price equivalent, not a charge.
107
+ */
108
+ export type ProviderAuth = "api-key" | "oauth-token" | "subscription";
109
+
102
110
  export interface ProviderAdapter {
103
- /** The value of `AGENT_REVIEW_PROVIDER` that selects it. */
111
+ /** The value of `WACHIMAN_PROVIDER` that selects it. */
104
112
  readonly name: string;
113
+ /** What pays for the calls. Absent means `api-key`. */
114
+ readonly auth?: ProviderAuth;
105
115
  /** Throws when the call would fail anyway: missing binary, settings file or credential. */
106
116
  preflight(): void;
107
117
  /** For the review footer, e.g. "Claude Sonnet 5.5 via Claude Code 2.1.304". */
@@ -128,9 +128,9 @@ export function costSentence(e: { costUsdEstimate: number; calls: number; turns:
128
128
 
129
129
  const STOP_REASONS: Record<Exclude<ReviewResult["execution"]["stop"], "complete">, string> = {
130
130
  quota: "the account's usage limit ended the run",
131
- budget: "the run's estimate guard (AGENT_REVIEW_BUDGET_USD) was spent",
132
- turns: "the calls hit the turn limit (AGENT_REVIEW_MAX_TURNS)",
133
- timeout: "the calls hit the time limit (AGENT_REVIEW_CALL_TIMEOUT_S)",
131
+ budget: "the run's estimate guard (WACHIMAN_BUDGET_USD) was spent",
132
+ turns: "the calls hit the turn limit (WACHIMAN_MAX_TURNS)",
133
+ timeout: "the calls hit the time limit (WACHIMAN_CALL_TIMEOUT_S)",
134
134
  error: "no call returned a review",
135
135
  };
136
136
 
package/src/sinks/json.ts CHANGED
@@ -5,5 +5,16 @@
5
5
  import type { ReviewResult } from "../engine";
6
6
  import { toResultV1 } from "../formats";
7
7
 
8
- export const renderJson = (result: ReviewResult, version: 1 | 2 = 1) =>
9
- `${JSON.stringify(version === 1 ? toResultV1(result) : result, null, 2)}\n`;
8
+ /**
9
+ * `ids[i]` is the history id of `result.findings[i]` (ADR 0034). Only `/2` carries it, as an
10
+ * optional `id` on a finding; `/1` is never changed.
11
+ */
12
+ export const renderJson = (result: ReviewResult, version: 1 | 2 = 1, ids?: (string | undefined)[]) => {
13
+ const out =
14
+ version === 1
15
+ ? toResultV1(result)
16
+ : ids
17
+ ? { ...result, findings: result.findings.map((f, i) => (ids[i] === undefined ? f : { ...f, id: ids[i] })) }
18
+ : result;
19
+ return `${JSON.stringify(out, null, 2)}\n`;
20
+ };
@@ -1,5 +1,5 @@
1
1
  /**
2
- * `wachiman skills install|uninstall`: copies the two agent skills into the directories where
2
+ * `wachiman skills install|uninstall`: copies the agent skills into the directories where
3
3
  * coding agents look for them, marks each copy so it can be told from anyone else's, and removes
4
4
  * only what it installed (command contract section 5.9).
5
5
  */
@@ -10,7 +10,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
10
10
  import { wachimanHome } from "../accounts/config";
11
11
  import { UsageError } from "../config";
12
12
 
13
- export const SKILL_NAMES = ["wachiman-review", "wachiman-audit"] as const;
13
+ export const SKILL_NAMES = ["wachiman-review", "wachiman-loop", "wachiman-audit"] as const;
14
14
  export const MARKER_FILE = ".wachiman-skill.json";
15
15
 
16
16
  export interface SkillsOptions { action: "install" | "uninstall"; dirs: string[]; json: boolean }
@@ -28,7 +28,7 @@ interface SkillInstallMarker {
28
28
 
29
29
  export interface SkillsDeps {
30
30
  userHome?: string;
31
- /** The directory that holds `wachiman-review/` and `wachiman-audit/`. */
31
+ /** The directory that holds `wachiman-review/`, `wachiman-loop/` and `wachiman-audit/`. */
32
32
  sourceDir?: string;
33
33
  version?: string;
34
34
  now?: () => Date;
@@ -309,7 +309,7 @@ function uninstallOne(dest: string): Entry | undefined {
309
309
  }
310
310
 
311
311
  /**
312
- * Installs or removes both skills in every target directory. A target under the Wachiman home
312
+ * Installs or removes every skill in every target directory. A target under the Wachiman home
313
313
  * throws a UsageError before anything is written. A copy that is not ours (no marker, a symlink, a
314
314
  * file, a modified file) is reported `preserved` and warned about, never overwritten or followed.
315
315
  */
@@ -196,7 +196,7 @@ export function runStatus(args: StatusArgs, repoDir: string, env: Record<string,
196
196
  lines.push(`${runs.length} run${runs.length === 1 ? "" : "s"}, ${usd(total)} estimated (API-equivalent, not a bill), ${runs[0].at.slice(0, 10)} → ${runs.at(-1)!.at.slice(0, 10)}`, "");
197
197
  lines.push(` ${pad(args.by, w)} runs cost`);
198
198
  for (const g of groups) lines.push(` ${pad(g.key, w)} ${pad(String(g.runs), 4)} ${usd(g.costUsdEstimate)}`);
199
- lines.push("", retentionDays === 0 ? "New `--history` runs keep all runs (AGENT_REVIEW_HISTORY_DAYS=0). `--json` lists every run with its attributes." : `A new \`--history\` run deletes runs older than ${retentionDays} days (AGENT_REVIEW_HISTORY_DAYS changes that). \`--json\` lists every run with its attributes.`);
199
+ lines.push("", retentionDays === 0 ? "New `--history` runs keep all runs (WACHIMAN_HISTORY_DAYS=0). `--json` lists every run with its attributes." : `A new \`--history\` run deletes runs older than ${retentionDays} days (WACHIMAN_HISTORY_DAYS changes that). \`--json\` lists every run with its attributes.`);
200
200
  io.stdout(`${lines.join("\n")}\n`);
201
201
  return 0;
202
202
  }
@@ -0,0 +1,109 @@
1
+ /**
2
+ * `wachiman dashboard`: brings the local index up to date from the history files, then prints the
3
+ * figures as `wachiman.dashboard/1` JSON or writes them as one static HTML file (ADR 0035). It writes
4
+ * only the index and, without `--json`, the page; like `wachiman history`, it moves a damaged run
5
+ * file aside. No `claude`, no GitHub, no network, no server, and it never opens a browser.
6
+ */
7
+ import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from "node:fs";
8
+ import { dirname, join, resolve } from "node:path";
9
+ import { wachimanHome } from "../accounts/config";
10
+ import { UsageError } from "../config";
11
+ import { readFigures, type Figures } from "./figures";
12
+ import { renderHtml, type DashboardDocument } from "./html";
13
+ import { refreshIndex } from "./index";
14
+
15
+ export const DASHBOARD_FORMAT = "wachiman.dashboard/1";
16
+ export const DASHBOARD_FILE = "dashboard.html";
17
+
18
+ export const dashboardUsage = `wachiman dashboard [--json] [--out <file>] [--repo-dir <dir>]`;
19
+
20
+ export const LOCAL_ONLY = "Local runs only: those kept by `wachiman local --history` and `wachiman loop`. Runs by the GitHub Actions workflow are not counted.";
21
+
22
+ export interface DashboardArgs {
23
+ json: boolean;
24
+ out?: string;
25
+ }
26
+
27
+ /** The arguments after `dashboard` (`--repo-dir` is already taken out). Both `--x v` and `--x=v`. */
28
+ export function parseDashboardArgs(argv: string[]): DashboardArgs | { help: true } {
29
+ const args: DashboardArgs = { json: false };
30
+ for (let i = 0; i < argv.length; i++) {
31
+ const arg = argv[i];
32
+ if (arg === "--help" || arg === "-h") return { help: true };
33
+ if (!arg.startsWith("--")) throw new UsageError(`dashboard takes no argument "${arg}".`);
34
+ const eq = arg.indexOf("=");
35
+ const name = eq === -1 ? arg : arg.slice(0, eq);
36
+ if (name === "--json") {
37
+ if (eq !== -1) throw new UsageError("--json takes no value.");
38
+ args.json = true;
39
+ } else if (name === "--out") {
40
+ const v = eq === -1 ? argv[++i] : arg.slice(eq + 1);
41
+ if (v === undefined || v === "" || (eq === -1 && v.startsWith("--"))) throw new UsageError("--out needs a file name.");
42
+ args.out = v;
43
+ } else throw new UsageError(`Unknown option ${name} for dashboard.`);
44
+ }
45
+ if (args.json && args.out !== undefined) throw new UsageError("--out writes the HTML page; --json prints to stdout and takes no --out.");
46
+ return args;
47
+ }
48
+
49
+ /** Writes `text` to `path` at 0600 through a temporary name beside it: all or nothing. */
50
+ function writeFileAtomic(path: string, text: string) {
51
+ mkdirSync(dirname(path), { recursive: true });
52
+ const tmp = `${path}.tmp-${process.pid}`;
53
+ const fd = openSync(tmp, "w", 0o600);
54
+ try {
55
+ try {
56
+ writeSync(fd, text);
57
+ fsyncSync(fd);
58
+ } finally {
59
+ closeSync(fd);
60
+ }
61
+ chmodSync(tmp, 0o600);
62
+ renameSync(tmp, path);
63
+ } catch (error) {
64
+ try {
65
+ unlinkSync(tmp);
66
+ } catch {
67
+ // Already gone.
68
+ }
69
+ throw error;
70
+ }
71
+ }
72
+
73
+ /**
74
+ * The figures from an up-to-date index. If reading them fails (a damaged or half-built index that
75
+ * looked current), the index is rebuilt once and read again; a second failure is the caller's.
76
+ */
77
+ export function loadFigures(home: string, warn: (line: string) => void, read: (path: string) => Figures = readFigures): Figures {
78
+ const { path } = refreshIndex(home, warn);
79
+ try {
80
+ return read(path);
81
+ } catch {
82
+ refreshIndex(home, warn, { force: true });
83
+ return read(path);
84
+ }
85
+ }
86
+
87
+ export interface DashboardIo {
88
+ stdout: (text: string) => void;
89
+ stderr: (line: string) => void;
90
+ now?: () => Date;
91
+ }
92
+
93
+ export function runDashboard(args: DashboardArgs, env: Record<string, string | undefined>, io: DashboardIo): number {
94
+ const home = wachimanHome(env);
95
+ const doc: DashboardDocument = {
96
+ format: DASHBOARD_FORMAT,
97
+ generatedAt: (io.now?.() ?? new Date()).toISOString(),
98
+ scope: LOCAL_ONLY,
99
+ ...loadFigures(home, io.stderr),
100
+ };
101
+ if (args.json) {
102
+ io.stdout(`${JSON.stringify(doc, null, 2)}\n`);
103
+ return 0;
104
+ }
105
+ const out = args.out === undefined ? join(home, DASHBOARD_FILE) : resolve(args.out);
106
+ writeFileAtomic(out, renderHtml(doc));
107
+ io.stdout(`${out}\n`);
108
+ return 0;
109
+ }
@@ -0,0 +1,153 @@
1
+ /**
2
+ * What the dashboard shows, read from the index with plain queries. Everything here is a figure the
3
+ * run files record; a figure they do not record is marked `not recorded` rather than guessed.
4
+ */
5
+ import { Database } from "bun:sqlite";
6
+ import { GRADES, type Grade } from "../fidelity/types";
7
+ import { VERDICT_WORDS } from "../history/types";
8
+
9
+ export const SEVERITY_ORDER = ["blocker", "fix", "consider", "info"] as const;
10
+ export const LOOP_STATUSES = ["new", "open", "probably-fixed", "not-repeated", "unknown"] as const;
11
+ const NOT_RECORDED = "not recorded";
12
+
13
+ export interface SpendDay {
14
+ day: string;
15
+ runs: number;
16
+ costUsdEstimate: number;
17
+ }
18
+ export interface SpendRepository {
19
+ key: string;
20
+ name: string;
21
+ runs: number;
22
+ costUsdEstimate: number;
23
+ }
24
+ export interface LoopBranch {
25
+ repositoryKey: string;
26
+ repository: string;
27
+ branch: string;
28
+ base: string;
29
+ outcome: "open" | "converged";
30
+ /** The loop state keeps only open or converged; why a loop stopped is printed by `loop` and never saved. */
31
+ exitReason: typeof NOT_RECORDED;
32
+ rounds: number;
33
+ firstRoundAt?: string;
34
+ lastRoundAt?: string;
35
+ ledger: { total: number; byStatus: Record<(typeof LOOP_STATUSES)[number], number> };
36
+ }
37
+
38
+ export type PrConfidence =
39
+ | { status: typeof NOT_RECORDED; note: string }
40
+ | { status: "recorded"; gradedRuns: number; byGrade: Record<Grade, number> };
41
+
42
+ export interface Figures {
43
+ totals: { repositories: number; runs: number; costUsdEstimate: number };
44
+ spend: { byDay: SpendDay[]; byRepository: SpendRepository[] };
45
+ findings: {
46
+ total: number;
47
+ bySeverity: Record<(typeof SEVERITY_ORDER)[number], number>;
48
+ byVerdict: Record<"correct" | "partial" | "wrong" | "unjudged", number>;
49
+ };
50
+ loops: {
51
+ branches: LoopBranch[];
52
+ totals: { branches: number; rounds: number; converged: number; open: number };
53
+ };
54
+ prConfidence: PrConfidence;
55
+ }
56
+
57
+ /** Dollars are summed as floating point; six decimals hide the noise and lose no cent. */
58
+ const money = (n: number) => Math.round(n * 1e6) / 1e6;
59
+
60
+ export function readFigures(indexPath: string): Figures {
61
+ const db = new Database(indexPath, { readonly: true });
62
+ try {
63
+ const all = <T>(sql: string, ...params: string[]) => db.query(sql).all(...params) as T[];
64
+
65
+ const totals = db.query("SELECT COUNT(*) AS runs, COALESCE(SUM(cost_usd), 0) AS cost FROM runs").get() as { runs: number; cost: number };
66
+ const repositories = (db.query("SELECT COUNT(*) AS n FROM repositories").get() as { n: number }).n;
67
+
68
+ const byDay = all<{ day: string; runs: number; cost: number }>("SELECT day, COUNT(*) AS runs, SUM(cost_usd) AS cost FROM runs GROUP BY day ORDER BY day").map(
69
+ (r): SpendDay => ({ day: r.day, runs: r.runs, costUsdEstimate: money(r.cost) }),
70
+ );
71
+ const byRepository = all<{ key: string; name: string; runs: number; cost: number }>(
72
+ `SELECT r.key AS key, r.name AS name, COUNT(u.repo_key) AS runs, COALESCE(SUM(u.cost_usd), 0) AS cost
73
+ FROM repositories r LEFT JOIN runs u ON u.repo_key = r.key GROUP BY r.key ORDER BY cost DESC, r.key`,
74
+ ).map((r): SpendRepository => ({ key: r.key, name: r.name, runs: r.runs, costUsdEstimate: money(r.cost) }));
75
+
76
+ const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0])) as Figures["findings"]["bySeverity"];
77
+ for (const r of all<{ severity: string; n: number }>("SELECT severity, COUNT(*) AS n FROM findings GROUP BY severity")) {
78
+ if (r.severity in bySeverity) bySeverity[r.severity as keyof typeof bySeverity] = r.n;
79
+ }
80
+ const byVerdict = { correct: 0, partial: 0, wrong: 0, unjudged: 0 };
81
+ for (const r of all<{ verdict: string | null; n: number }>("SELECT verdict, COUNT(*) AS n FROM findings GROUP BY verdict")) {
82
+ const word = r.verdict ?? "unjudged";
83
+ if (word === "unjudged" || (VERDICT_WORDS as readonly string[]).includes(word)) byVerdict[word as keyof typeof byVerdict] = r.n;
84
+ }
85
+ const findingsTotal = (db.query("SELECT COUNT(*) AS n FROM findings").get() as { n: number }).n;
86
+
87
+ const ledgerRows = all<{ repo_key: string; branch: string; status: string; count: number }>("SELECT repo_key, branch, status, count FROM loop_ledger");
88
+ const branches = all<{
89
+ repo_key: string;
90
+ name: string;
91
+ branch: string;
92
+ base: string;
93
+ outcome: "open" | "converged";
94
+ rounds: number;
95
+ first_round_at: string | null;
96
+ last_round_at: string | null;
97
+ }>(
98
+ `SELECT l.repo_key, COALESCE(r.name, l.repo_key) AS name, l.branch, l.base, l.outcome, l.rounds, l.first_round_at, l.last_round_at
99
+ FROM loops l LEFT JOIN repositories r ON r.key = l.repo_key ORDER BY l.repo_key, l.branch`,
100
+ ).map((l): LoopBranch => {
101
+ const byStatus = Object.fromEntries(LOOP_STATUSES.map((s) => [s, 0])) as LoopBranch["ledger"]["byStatus"];
102
+ let total = 0;
103
+ for (const e of ledgerRows) {
104
+ if (e.repo_key !== l.repo_key || e.branch !== l.branch) continue;
105
+ total += e.count;
106
+ if (e.status in byStatus) byStatus[e.status as keyof typeof byStatus] += e.count;
107
+ }
108
+ return {
109
+ repositoryKey: l.repo_key,
110
+ repository: l.name,
111
+ branch: l.branch,
112
+ base: l.base,
113
+ outcome: l.outcome,
114
+ exitReason: NOT_RECORDED,
115
+ rounds: l.rounds,
116
+ ...(l.first_round_at ? { firstRoundAt: l.first_round_at } : {}),
117
+ ...(l.last_round_at ? { lastRoundAt: l.last_round_at } : {}),
118
+ ledger: { total, byStatus },
119
+ };
120
+ });
121
+
122
+ const grades = all<{ grade: string; n: number }>("SELECT grade, COUNT(*) AS n FROM runs WHERE grade IS NOT NULL GROUP BY grade");
123
+ let prConfidence: PrConfidence;
124
+ if (grades.length === 0) {
125
+ prConfidence = {
126
+ status: NOT_RECORDED,
127
+ note: "not recorded: only GitHub pull request reviews compute a grade, and they do not write the local review history, so no run file here carries one.",
128
+ };
129
+ } else {
130
+ const byGrade = Object.fromEntries(GRADES.map((g) => [g, 0])) as Record<Grade, number>;
131
+ for (const g of grades) byGrade[g.grade as Grade] = g.n;
132
+ prConfidence = { status: "recorded", gradedRuns: grades.reduce((n, g) => n + g.n, 0), byGrade };
133
+ }
134
+
135
+ return {
136
+ totals: { repositories, runs: totals.runs, costUsdEstimate: money(totals.cost) },
137
+ spend: { byDay, byRepository },
138
+ findings: { total: findingsTotal, bySeverity, byVerdict },
139
+ loops: {
140
+ branches,
141
+ totals: {
142
+ branches: branches.length,
143
+ rounds: branches.reduce((n, b) => n + b.rounds, 0),
144
+ converged: branches.filter((b) => b.outcome === "converged").length,
145
+ open: branches.filter((b) => b.outcome === "open").length,
146
+ },
147
+ },
148
+ prConfidence,
149
+ };
150
+ } finally {
151
+ db.close();
152
+ }
153
+ }