wachiman 1.15.0 → 1.17.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 (87) hide show
  1. package/README.md +13 -0
  2. package/package.json +1 -1
  3. package/skills/wachiman-loop/SKILL.md +43 -0
  4. package/src/accounts/commands.ts +3 -2
  5. package/src/accounts/confirm.ts +1 -1
  6. package/src/accounts/profile-list.ts +24 -0
  7. package/src/cli.ts +91 -26
  8. package/src/config.ts +40 -8
  9. package/src/connectors/local-git.ts +128 -0
  10. package/src/connectors/working-tree.ts +23 -1
  11. package/src/doctor/checks.ts +106 -1
  12. package/src/doctor/run.ts +9 -1
  13. package/src/engine.ts +1126 -222
  14. package/src/formats.ts +44 -3
  15. package/src/help.ts +204 -7
  16. package/src/history/command.ts +5 -5
  17. package/src/history/match.ts +24 -4
  18. package/src/history/store.ts +1 -1
  19. package/src/history/types.ts +7 -2
  20. package/src/init/agents.ts +135 -0
  21. package/src/init/args.ts +7 -2
  22. package/src/init/github-login.ts +13 -0
  23. package/src/init/json.ts +82 -0
  24. package/src/init/options.ts +42 -4
  25. package/src/init/prompt.ts +46 -15
  26. package/src/init/render.ts +3 -1
  27. package/src/init/run.ts +362 -28
  28. package/src/init/settings.ts +137 -0
  29. package/src/init/write.ts +16 -102
  30. package/src/json-schema.ts +8 -0
  31. package/src/ledger.ts +2 -2
  32. package/src/local-ask.ts +5 -4
  33. package/src/local.ts +90 -17
  34. package/src/loop/command.ts +29 -7
  35. package/src/memory/candidates.ts +425 -0
  36. package/src/memory/capture.ts +298 -0
  37. package/src/memory/command.ts +195 -0
  38. package/src/memory/entries.ts +213 -0
  39. package/src/memory/hygiene.ts +291 -0
  40. package/src/memory/inspect.ts +74 -0
  41. package/src/memory/load.ts +283 -0
  42. package/src/memory/mute.ts +259 -0
  43. package/src/memory/personal.ts +253 -0
  44. package/src/memory/proposal.ts +92 -0
  45. package/src/memory/propose.ts +414 -0
  46. package/src/memory/remember.ts +187 -0
  47. package/src/memory/report.ts +250 -0
  48. package/src/memory/settings.ts +20 -0
  49. package/src/pr-template/adopt.ts +434 -0
  50. package/src/pr-template/catalog.ts +429 -0
  51. package/src/pr-template/check-run.ts +328 -0
  52. package/src/pr-template/check.ts +338 -0
  53. package/src/pr-template/describe.ts +368 -0
  54. package/src/pr-template/format.ts +399 -0
  55. package/src/pr-template/gh.ts +159 -0
  56. package/src/pr-template/install.ts +311 -0
  57. package/src/pr-template/legacy-guides.ts +50 -0
  58. package/src/pr-template/pr-risk.ts +426 -0
  59. package/src/pr-template/render.ts +302 -0
  60. package/src/pr-template/resolve.ts +65 -0
  61. package/src/pr-template/run.ts +88 -0
  62. package/src/pr-template/strip.ts +171 -0
  63. package/src/pr-template/write.ts +139 -0
  64. package/src/precision.ts +10 -2
  65. package/src/priority.ts +106 -0
  66. package/src/providers/claude-code.ts +7 -8
  67. package/src/providers/codex.ts +4 -4
  68. package/src/providers/spawn.ts +95 -0
  69. package/src/providers/types.ts +5 -2
  70. package/src/repo-settings.ts +322 -0
  71. package/src/risk.ts +38 -9
  72. package/src/setup/prompt.ts +49 -33
  73. package/src/setup/run.ts +31 -6
  74. package/src/sinks/common.ts +22 -9
  75. package/src/sinks/markdown.ts +6 -2
  76. package/src/sinks/terminal.ts +6 -2
  77. package/src/store/figures.ts +5 -4
  78. package/src/store/html.ts +1 -1
  79. package/src/upgrade/command.ts +286 -0
  80. package/src/upgrade/pin.ts +112 -0
  81. package/src/verify.ts +20 -2
  82. package/src/wizard/mascot.ts +56 -51
  83. package/src/wizard/prompt-fancy.ts +10 -2
  84. package/src/wizard/prompt.ts +17 -4
  85. package/src/wizard/ui.ts +2 -0
  86. package/templates/pr/sections.json +163 -0
  87. package/templates/wachiman-review-caller.yml +7 -7
package/src/init/write.ts CHANGED
@@ -1,61 +1,16 @@
1
1
  /**
2
- * Writing the workflow file safely (contract section 5.5): no symbolic link may stand in for
3
- * `.github`, `workflows` or the target, an existing file is copied to a backup that never
4
- * overwrites another backup, and the new content goes in through an exclusive temporary file and a
5
- * rename after the target is found unchanged since it was inspected.
2
+ * Writing the workflow file safely (contract section 5.5). The mechanism is shared with
3
+ * `wachiman pr-template` and lives in `../pr-template/write.ts`; this file keeps the names and the
4
+ * behaviour `init` relies on: a backup of an existing file on every write, and messages that say
5
+ * `init`.
6
6
  */
7
- import { randomBytes } from "node:crypto";
8
- import { constants, copyFileSync, linkSync, lstatSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, type Stats } from "node:fs";
9
- import { basename, dirname, join, sep } from "node:path";
10
- import { UsageError } from "../config";
7
+ import { backupStamp, inspectManagedTarget, writeManagedFile, type TargetState, type WriteHooks } from "../pr-template/write";
11
8
 
12
- export interface TargetState {
13
- /** The real path the file is written to: the real repository root plus the relative path. */
14
- target: string;
15
- exists: boolean;
16
- identity?: string;
17
- }
18
-
19
- const identityOf = (s: Stats) => `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}`;
20
-
21
- const lstatOrNull = (path: string) => {
22
- try {
23
- return lstatSync(path);
24
- } catch (error) {
25
- if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
26
- throw error;
27
- }
28
- };
9
+ export { backupStamp };
10
+ export type { TargetState, WriteHooks };
29
11
 
30
12
  /** Looks at the target and its ancestors without following a link; refuses anything that is not a plain directory chain and a plain file. */
31
- export function inspectTarget(repoDir: string, relativePath: string): TargetState {
32
- const root = realpathSync(repoDir);
33
- let current = root;
34
- const parts = relativePath.split("/");
35
- for (const part of parts.slice(0, -1)) {
36
- current = join(current, part);
37
- const stat = lstatOrNull(current);
38
- if (stat === null) break;
39
- if (stat.isSymbolicLink()) throw new UsageError(`${current} is a symbolic link; init does not write through links. Replace it with a real directory.`);
40
- if (!stat.isDirectory()) throw new UsageError(`${current} is not a directory; init cannot write ${relativePath}.`);
41
- const real = realpathSync(current);
42
- if (real !== root && !real.startsWith(root + sep)) throw new UsageError(`${current} resolves outside the repository (${real}); init refuses it.`);
43
- }
44
- const target = join(root, relativePath);
45
- const stat = lstatOrNull(target);
46
- if (stat === null) return { target, exists: false };
47
- if (stat.isSymbolicLink()) throw new UsageError(`${target} is a symbolic link; init does not write through links.`);
48
- if (!stat.isFile()) throw new UsageError(`${target} exists and is not a regular file.`);
49
- return { target, exists: true, identity: identityOf(stat) };
50
- }
51
-
52
- /** `YYYYMMDD-HHMMSS` in UTC, from an ISO timestamp. */
53
- export const backupStamp = (iso: string) => iso.replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
54
-
55
- export interface WriteHooks {
56
- /** Runs after the temporary file is complete and before it replaces the target; a test changes the target here. */
57
- beforeCommit?: () => void;
58
- }
13
+ export const inspectTarget = (repoDir: string, relativePath: string): TargetState => inspectManagedTarget(repoDir, relativePath, "init");
59
14
 
60
15
  /**
61
16
  * Writes `content` to the inspected target. An existing file is copied to `<target>.bak-<stamp>`
@@ -63,52 +18,11 @@ export interface WriteHooks {
63
18
  * inspected. A new file is linked into place, which fails if one appeared meanwhile. Returns the
64
19
  * backup path when one was made.
65
20
  */
66
- export function writeWorkflow(p: { repoDir: string; relativePath: string; content: string; inspected: TargetState; now: string; hooks?: WriteHooks }): { target: string; backup?: string } {
67
- const { inspected } = p;
68
- const dir = dirname(inspected.target);
69
- mkdirSync(dir, { recursive: true });
70
- // The directories exist now: look again, so a link planted between the first look and the mkdir is still refused.
71
- const again = inspectTarget(p.repoDir, p.relativePath);
72
- if (again.exists !== inspected.exists || again.identity !== inspected.identity) {
73
- throw new UsageError(`${inspected.target} changed while init was running; nothing was written. Run it again.`);
74
- }
75
- let backup: string | undefined;
76
- if (inspected.exists) {
77
- const stamp = backupStamp(p.now);
78
- for (let n = 1; backup === undefined; n++) {
79
- const candidate = `${inspected.target}.bak-${stamp}${n === 1 ? "" : `-${n}`}`;
80
- try {
81
- copyFileSync(inspected.target, candidate, constants.COPYFILE_EXCL);
82
- backup = candidate;
83
- } catch (error) {
84
- if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
85
- }
86
- }
87
- }
88
- const tmp = join(dir, `.${basename(inspected.target)}.${process.pid}-${randomBytes(4).toString("hex")}.tmp`);
89
- writeFileSync(tmp, p.content, { flag: "wx", mode: 0o644 });
90
- try {
91
- p.hooks?.beforeCommit?.();
92
- if (inspected.exists) {
93
- const now = lstatOrNull(inspected.target);
94
- if (now === null || now.isSymbolicLink() || identityOf(now) !== inspected.identity) {
95
- throw new UsageError(`${inspected.target} changed while init was running; it was not replaced.${backup ? ` A copy of the earlier file is at ${backup}.` : ""}`);
96
- }
97
- renameSync(tmp, inspected.target);
98
- } else {
99
- try {
100
- linkSync(tmp, inspected.target);
101
- } catch (error) {
102
- if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new UsageError(`${inspected.target} appeared while init was running; nothing was written.`);
103
- throw error;
104
- }
105
- }
106
- } finally {
107
- try {
108
- unlinkSync(tmp);
109
- } catch {
110
- // Renamed into place, or already gone.
111
- }
112
- }
113
- return { target: inspected.target, ...(backup ? { backup } : {}) };
114
- }
21
+ export const writeWorkflow = (p: { repoDir: string; relativePath: string; content: string; inspected: TargetState; now: string; hooks?: WriteHooks }): { target: string; backup?: string } =>
22
+ writeManagedFile({ ...p, label: "init", backup: true });
23
+
24
+ /** The generated first line carries a version and a date; a re-run on another day still writes the same workflow. */
25
+ const withoutHeader = (text: string) => text.replace(/^# Generated by wachiman init [^\n]*\n/, "");
26
+
27
+ /** True when `existing` is what `rendered` would write, apart from the generated header line. */
28
+ export const sameWorkflow = (existing: string, rendered: string) => withoutHeader(existing) === withoutHeader(rendered);
@@ -9,6 +9,8 @@ const CHECKED = new Set([
9
9
  "const",
10
10
  "enum",
11
11
  "minimum",
12
+ "maximum",
13
+ "minLength",
12
14
  "properties",
13
15
  "required",
14
16
  "additionalProperties",
@@ -70,6 +72,12 @@ export function validate(schema: Schema, value: unknown, rootSchema: Schema = sc
70
72
  if (typeof schema.minimum === "number" && typeof value === "number" && value < schema.minimum) {
71
73
  problems.push(`${path}: ${value} is below ${schema.minimum}`);
72
74
  }
75
+ if (typeof schema.maximum === "number" && typeof value === "number" && value > schema.maximum) {
76
+ problems.push(`${path}: ${value} is above ${schema.maximum}`);
77
+ }
78
+ if (typeof schema.minLength === "number" && typeof value === "string" && value.length < schema.minLength) {
79
+ problems.push(`${path}: is shorter than ${schema.minLength}`);
80
+ }
73
81
  if (Array.isArray(schema.oneOf)) {
74
82
  const matching = (schema.oneOf as Schema[]).filter((s) => validate(s, value, rootSchema, path).length === 0).length;
75
83
  if (matching !== 1) problems.push(`${path}: matches ${matching} of oneOf, expected exactly 1`);
package/src/ledger.ts CHANGED
@@ -171,7 +171,7 @@ const post = (ledgerUrl: string, route: string, token: string, payload: unknown,
171
171
 
172
172
  /**
173
173
  * A GitHub OIDC token for `audience`. Needs `id-token: write` in the job, which only
174
- * `review-platform.yml` grants; without the request variables there is nothing to retry.
174
+ * `wachiman-platform.yml` grants; without the request variables there is nothing to retry.
175
175
  */
176
176
  export function requestIdToken(env: LedgerEnv, audience: string, curl: CurlFn): string {
177
177
  const url = env.ACTIONS_ID_TOKEN_REQUEST_URL;
@@ -182,7 +182,7 @@ export function requestIdToken(env: LedgerEnv, audience: string, curl: CurlFn):
182
182
  if (status !== 200 || typeof value !== "string" || value === "") {
183
183
  if (isOutage(status)) throw new LedgerUnavailable(`GitHub did not issue an id token (HTTP ${status}).`);
184
184
  throw new LedgerBadAnswer(
185
- `GitHub did not issue an OIDC token for the ledger (HTTP ${status}). Check that the job has \`id-token: write\` and calls review-platform.yml.`,
185
+ `GitHub did not issue an OIDC token for the ledger (HTTP ${status}). Check that the job has \`id-token: write\` and calls wachiman-platform.yml.`,
186
186
  );
187
187
  }
188
188
  return value;
package/src/local-ask.ts CHANGED
@@ -77,7 +77,7 @@ export function storedReviewOf(
77
77
  return undefined;
78
78
  }
79
79
 
80
- export function runAsk(
80
+ export async function runAsk(
81
81
  args: AskArgs,
82
82
  repoDir: string,
83
83
  env: Record<string, string | undefined>,
@@ -87,7 +87,7 @@ export function runAsk(
87
87
  engineVersion: string;
88
88
  },
89
89
  deps: LocalDeps = {},
90
- ): number {
90
+ ): Promise<number> {
91
91
  // The account, the provider and the settings are checked before the change is read, as `local` does.
92
92
  const { config, provider, state } = openLocalSession({
93
93
  profile: args.profile,
@@ -96,6 +96,7 @@ export function runAsk(
96
96
  env,
97
97
  stderr: io.stderr,
98
98
  deps,
99
+ scope: { workingTree: args.workingTree, base: args.base, commit: args.commit, from: args.from, maxDepth: args.maxDepth },
99
100
  });
100
101
  const onSigint = () => {
101
102
  state.interrupted = true;
@@ -159,10 +160,10 @@ export function runAsk(
159
160
  });
160
161
 
161
162
  // One call, read-only, in the snapshot of the head: the same place the review reads from.
162
- let result: ReturnType<typeof runProvider> | undefined;
163
+ let result: Awaited<ReturnType<typeof runProvider>> | undefined;
163
164
  let failure = "";
164
165
  try {
165
- result = runProvider(
166
+ result = await runProvider(
166
167
  { provider, log: io.stderr, warn: io.stderr },
167
168
  config,
168
169
  input.headDir,
package/src/local.ts CHANGED
@@ -13,26 +13,33 @@
13
13
  */
14
14
  import { existsSync, readFileSync, writeFileSync } from "node:fs";
15
15
  import { resolve } from "node:path";
16
- import { loadConfig, UsageError } from "./config";
16
+ import { loadConfig, UsageError, type EngineConfig } from "./config";
17
17
  import {
18
18
  buildLocalInput,
19
19
  DEFAULT_MAX_DEPTH,
20
20
  EMPTY_TREE_LABEL,
21
+ localMemory,
22
+ localRepoSettings,
23
+ localSettingsCommit,
21
24
  type LocalRefs,
22
25
  removeSnapshot,
26
+ type SettingsScope,
23
27
  snapshotHead,
24
28
  warnSnapshotDifferences,
25
29
  } from "./connectors/local-git";
26
- import { DEFAULT_EXCLUDE, estimateFor, filterFiles, planBatches, reviewChange, reviewOptionsOf, type ReviewInput, type ReviewResult } from "./engine";
30
+ import { DEFAULT_EXCLUDE, estimateFor, filterFiles, planBatches, reviewChange, reviewOptionsOf, splitUnreviewable, type ReviewInput, type ReviewResult } from "./engine";
27
31
  import { sizeGate, type ReviewEstimate } from "./estimate";
28
32
  import { spawnGit } from "./evidence";
33
+ import { personalSourceFor } from "./memory/personal";
29
34
  import { assertReviewInputFormat, REVIEW_INPUT_V2 } from "./formats";
35
+ import { applyRepoSettings, fileSettingsNote, ignoredSettingsNote, parsePathRules, wantsRepoSettings, type RepoSettings } from "./repo-settings";
30
36
  import { workingTreeInput, snapshotWorkingTree } from "./connectors/working-tree";
31
37
  import { historyRoot, historySettings, saveRun } from "./history";
32
38
  import { readConfig, wachimanHome } from "./accounts/config";
33
39
  import { confirmProfile, type SpawnFn } from "./accounts/confirm";
34
40
  import { failureText, profileLine, resolveProfile, type ResolvedProfile } from "./accounts/resolve";
35
41
  import { repositoryKey } from "./history/store";
42
+ import { entriesUsed, recordMemoryUse } from "./memory/hygiene";
36
43
  import { inspectIsolatedProfile, parseProfile, populatedProfileError, profileDir } from "./profiles";
37
44
  import { getProvider as defaultGetProvider, type ProviderAdapter } from "./providers";
38
45
  import { InterruptedError, SUBSCRIPTION_KEY_REFUSAL } from "./providers/claude-code";
@@ -59,6 +66,8 @@ export interface LocalArgs {
59
66
  history: boolean;
60
67
  /** `--verify` forces the verifier on, `--no-verify` off; unset follows `WACHIMAN_VERIFY` (off by default, ADR 0027). */
61
68
  verify: boolean | undefined;
69
+ /** `--no-memory`: review as a repository without a `.wachiman/memory/` folder (the control arm of the memory replay). */
70
+ noMemory?: boolean;
62
71
  /** `--result-version`: with `--format json`, which result version to write (default 1 for a committed change). */
63
72
  resultVersion?: 1 | 2;
64
73
  input?: string;
@@ -66,7 +75,7 @@ export interface LocalArgs {
66
75
 
67
76
  export const localUsage = `wachiman local [paths…] [--base <ref> | --from <commit> | --commit <commit>] [--max-depth <n>] [--repo-dir <dir>]
68
77
  [--input <file>] [--format terminal|markdown|json] [--output <file>]
69
- [--profile <name>] [--agent-prompt] [--history] [--verify | --no-verify]
78
+ [--profile <name>] [--agent-prompt] [--history] [--verify | --no-verify] [--no-memory]
70
79
  [--result-version 1|2] [--working-tree staged|all]`;
71
80
 
72
81
  /** Every flag `local` takes. `ask` takes the subset it names in `ask-command`. */
@@ -75,6 +84,7 @@ export const LOCAL_FLAGS = [
75
84
  "--history",
76
85
  "--verify",
77
86
  "--no-verify",
87
+ "--no-memory",
78
88
  "--result-version",
79
89
  "--working-tree",
80
90
  "--base",
@@ -127,6 +137,7 @@ export function parseFlags(argv: string[], command: string, accepted: readonly s
127
137
  };
128
138
  if (name === "--agent-prompt" && eq === -1) args.agentPrompt = true;
129
139
  else if (name === "--history" && eq === -1) args.history = true;
140
+ else if (name === "--no-memory" && eq === -1) args.noMemory = true;
130
141
  else if (name === "--verify" && eq === -1) {
131
142
  args.verify = true;
132
143
  sawVerify = true;
@@ -226,6 +237,9 @@ export function readInputFile(path: string): Omit<ReviewInput, "headDir"> {
226
237
  if (!instr || !isString(instr.baseSha) || !Array.isArray(instr.files)) problems.push("instructions");
227
238
  if (!Array.isArray(input.scope) || input.scope.some((s: unknown) => !isString(s))) problems.push("scope");
228
239
  if (problems.length > 0) throw new UsageError(`--input ${path} is missing or mistypes: ${problems.join(", ")}.`);
240
+ // Optional, and checked as `.wachiman.yml` is: an entry that names no severity is not guessed at.
241
+ if (input.pathRules !== undefined) input.pathRules = parsePathRules(input.pathRules, `--input ${path}`);
242
+ if (input.pathPolicyChanged !== undefined && input.pathPolicyChanged !== true) throw new UsageError(`--input ${path}: pathPolicyChanged must be true when present.`);
229
243
  // In memory only (docs/formats): the head the agent reads is always the engine's own snapshot.
230
244
  if ("headDir" in input) throw new UsageError(`--input ${path} carries headDir, which a review input file never holds.`);
231
245
  return input as Omit<ReviewInput, "headDir">;
@@ -248,10 +262,10 @@ export function interruptible(provider: ProviderAdapter, state: { interrupted: b
248
262
  preflight: () => provider.preflight(),
249
263
  modelLabel: () => provider.modelLabel(),
250
264
  leaksSecret: (texts) => provider.leaksSecret(texts),
251
- run: (request) => {
265
+ run: async (request) => {
252
266
  if (state.interrupted) throw new InterruptedError("the review was interrupted");
253
267
  try {
254
- return provider.run(request);
268
+ return await provider.run(request);
255
269
  } catch (error) {
256
270
  if (error instanceof InterruptedError) state.interrupted = true;
257
271
  throw error;
@@ -281,6 +295,34 @@ export interface LocalSession {
281
295
  state: { interrupted: boolean };
282
296
  }
283
297
 
298
+ /**
299
+ * `config` with the model and the effort the repository's `.wachiman.yml` sets where nothing explicit
300
+ * did. The file is read at the commit the instruction files are read at (`localSettingsCommit`),
301
+ * never from the working tree or the head, for the same reason as in Actions: the change under
302
+ * review cannot choose what it is reviewed under. One stderr line says when the file decided. A
303
+ * broken file at that commit is ignored with a warning and the run continues on the environment and
304
+ * the defaults, so the change that fixes it can be reviewed.
305
+ */
306
+ export function withLocalSettings(config: EngineConfig, repoDir: string, scope: SettingsScope, stderr: (line: string) => void): EngineConfig {
307
+ if (!wantsRepoSettings(config)) return config;
308
+ const sha = localSettingsCommit(repoDir, scope);
309
+ if (sha === undefined) return config;
310
+ const where = `${scope.inputBase !== undefined ? "the input's base" : scope.workingTree ? "HEAD" : "the merge-base"} ${short(sha)}`;
311
+ let settings: RepoSettings | undefined;
312
+ try {
313
+ settings = localRepoSettings(repoDir, sha);
314
+ } catch (error) {
315
+ if (!(error instanceof UsageError)) throw error;
316
+ stderr(ignoredSettingsNote(error.message, where));
317
+ return config;
318
+ }
319
+ if (!settings) return config;
320
+ const next = applyRepoSettings(config, settings, { where, warn: stderr });
321
+ const note = fileSettingsNote(next, where);
322
+ if (note) stderr(`settings: ${note}`);
323
+ return next;
324
+ }
325
+
284
326
  /**
285
327
  * The settings, the account (ADR 0029), the subscription-mode provider and, with `--verify`, the
286
328
  * verifier, all checked before any call. Nothing in the reviewed repository takes part: a corrupt
@@ -293,12 +335,15 @@ export function openLocalSession(p: {
293
335
  env: Record<string, string | undefined>;
294
336
  stderr: (line: string) => void;
295
337
  deps: LocalDeps;
338
+ /** The scope flags: they decide the commit whose `.wachiman.yml` is read (the one the instruction files are read at). */
339
+ scope?: SettingsScope;
296
340
  }): LocalSession {
297
341
  const { env, repoDir, deps } = p;
298
- const loaded = loadConfig(env, p.stderr);
299
- if (loaded.provider !== "claude-code") {
300
- throw new UsageError(`WACHIMAN_PROVIDER=${loaded.provider}: the local review runs only on Claude Code, your signed-in \`claude\`.`);
342
+ const loadedEnv = loadConfig(env, p.stderr);
343
+ if (loadedEnv.provider !== "claude-code") {
344
+ throw new UsageError(`WACHIMAN_PROVIDER=${loadedEnv.provider}: the local review runs only on Claude Code, your signed-in \`claude\`.`);
301
345
  }
346
+ const loaded = withLocalSettings(loadedEnv, repoDir, p.scope ?? {}, p.stderr);
302
347
  // A person ran it: no automatic ceiling (decision 14).
303
348
  const config = {
304
349
  ...loaded,
@@ -444,7 +489,7 @@ export function sizeWarning(estimate: ReviewEstimate, gate: number, budgetUsd: n
444
489
  return `warning: reviewing all of this would cost about $${estimate.usd.toFixed(2)} at API prices (${estimate.batches} batches × $${estimate.perBatchUsd.toFixed(2)} for ${model}), above the $${gate.toFixed(2)} size gate. Local runs are never refused; this one continues and stops at its budget, $${budgetUsd.toFixed(2)} (WACHIMAN_BUDGET_USD).`;
445
490
  }
446
491
 
447
- export function runLocal(
492
+ export async function runLocal(
448
493
  args: LocalArgs,
449
494
  repoDir: string,
450
495
  env: Record<string, string | undefined>,
@@ -454,7 +499,7 @@ export function runLocal(
454
499
  engineVersion: string;
455
500
  },
456
501
  deps: LocalDeps = {},
457
- ): number {
502
+ ): Promise<number> {
458
503
  const fileInput = args.input === undefined ? undefined : readInputFile(args.input);
459
504
  if ((args.workingTree || fileInput?.change.kind === "working-tree") && args.resultVersion === 1) {
460
505
  throw new UsageError("Working-tree reviews require --result-version 2; a tree is not a commit.");
@@ -470,6 +515,14 @@ export function runLocal(
470
515
  env,
471
516
  stderr: io.stderr,
472
517
  deps,
518
+ scope: {
519
+ workingTree: args.workingTree,
520
+ base: args.base,
521
+ commit: args.commit,
522
+ from: args.from,
523
+ maxDepth: args.maxDepth,
524
+ inputBase: fileInput?.change.base.sha,
525
+ },
473
526
  });
474
527
 
475
528
  let release: (() => void) | undefined;
@@ -515,13 +568,17 @@ export function runLocal(
515
568
  io.stderr(`head: ${short(head)}`);
516
569
  }
517
570
  const { kept, dropped } = filterFiles(input.files, [...DEFAULT_EXCLUDE, ...config.exclude], input.scope);
518
- const batches = planBatches(kept, {
519
- maxLines: config.batchLines,
520
- maxChars: config.batchChars,
521
- });
571
+ const batches = planBatches(
572
+ kept,
573
+ {
574
+ maxLines: config.batchLines,
575
+ maxChars: config.batchChars,
576
+ },
577
+ input.pathRules,
578
+ );
522
579
  io.stderr(`files: ${kept.length} (${dropped.length} excluded)`);
523
580
  io.stderr(`batches: ${batches.length}`);
524
- const warning = sizeWarning(estimateFor(kept, config), sizeGate(config, false), config.budgetUsd, config.model);
581
+ const warning = sizeWarning(estimateFor(kept, config, input.pathRules), sizeGate(config, false), config.budgetUsd, config.model);
525
582
  if (warning) io.stderr(warning);
526
583
  io.stderr(
527
584
  config.verify
@@ -529,7 +586,13 @@ export function runLocal(
529
586
  : "verify: off",
530
587
  );
531
588
 
532
- const result = reviewChange(input, reviewOptionsOf(config, config.budgetUsd, profile.kind === "managed" ? "isolated" : "default"), {
589
+ // The memory of the commit the diff starts at (the merge-base), selected by the files this run reviews, binaries
590
+ // excluded as the Actions path does (ADR 0056).
591
+ const reviewable = splitUnreviewable(kept, input.headDir).reviewable;
592
+ if (args.noMemory) io.stderr("memory: off (--no-memory)");
593
+ // The developer's personal memory for this repository (keyed by `origin`) is loaded after it, on the laptop only.
594
+ const memory = args.noMemory ? undefined : localMemory(repoDir, input.change.base.sha, reviewable.map((f) => f.filename), io.stderr, spawnGit, personalSourceFor(home, repoDir, spawnGit, io.stderr));
595
+ const result = await reviewChange(input, { ...reviewOptionsOf(config, config.budgetUsd, profile.kind === "managed" ? "isolated" : "default"), ...(memory ? { memory } : {}) }, {
533
596
  provider,
534
597
  ...(verifier ? { verifier } : {}),
535
598
  // The verifier reads the code before the change too; made once, only when there is something to check.
@@ -554,6 +617,14 @@ export function runLocal(
554
617
  io.stderr("Interrupted: the review stopped and its snapshot was removed.");
555
618
  return 130;
556
619
  }
620
+ // The laptop's record of which memory entries a review used (`memory check` suggests archiving the unused). It lives in the history store, so it is written only when history is on (ADR 0020); it never leaves the laptop and never fails a review.
621
+ if (memory && history.enabled) {
622
+ try {
623
+ recordMemoryUse(home, repositoryKey(repoDir).key, entriesUsed(memory, reviewable.map((f) => f.filename), result.muted ?? []), new Date().toISOString().slice(0, 10));
624
+ } catch (error) {
625
+ io.stderr(`memory: this run's use of memory was not recorded (${error instanceof Error ? error.message : error})`);
626
+ }
627
+ }
557
628
  // After the review and before the snapshot goes: the cited lines are read from it.
558
629
  let annotation: HistoryAnnotation | undefined;
559
630
  if (history.enabled) {
@@ -575,6 +646,7 @@ export function runLocal(
575
646
  io.stderr(thisRunText(result, annotation));
576
647
  io.stderr(sinceLastRunText(annotation));
577
648
  }
649
+ const settingsFrom = { model: config.modelSource === "file", effort: config.effortSource === "file" };
578
650
  const text =
579
651
  args.format === "json"
580
652
  ? renderJson(
@@ -584,9 +656,10 @@ export function runLocal(
584
656
  annotation ? result.findings.map((_, i) => annotation!.byIndex.get(i)?.id) : undefined,
585
657
  )
586
658
  : args.format === "markdown"
587
- ? renderMarkdown(result, { profileNote, history: annotation })
659
+ ? renderMarkdown(result, { profileNote, history: annotation, settingsFrom })
588
660
  : renderTerminal(result, {
589
661
  profileNote,
662
+ settingsFrom,
590
663
  agentPrompt: args.agentPrompt,
591
664
  history: annotation,
592
665
  });
@@ -20,6 +20,8 @@ import { MIN_LINE_CHARS, stripWhitespace, titleKey } from "../history/fingerprin
20
20
  import { replay, type ReplayedFinding } from "../history/match";
21
21
  import { historyRoot, readRuns, readVerdicts, repositoryKey } from "../history/store";
22
22
  import { LOCAL_FLAGS, parseFlags, runLocal, type LocalArgs, type LocalDeps } from "../local";
23
+ import { candidatesForRound } from "../memory/candidates";
24
+ import { loadMemorySettings } from "../memory/settings";
23
25
  import { location, sha7 } from "../sinks/common";
24
26
  import { LOOP_STATE_FORMAT, readLoop, writeLoop, type LedgerEntry, type LoopState } from "./state";
25
27
  import { evaluate, isRefutedBy, roundCapReached, type Decision, type LoopFinding, type LoopStatus, type OpenFinding, type Released } from "./stop-rule";
@@ -92,6 +94,8 @@ export interface RoundReport {
92
94
  notes: LoopFinding[];
93
95
  outcome: { status: "converged" | "open" | "stopped"; reason?: Why; message: string };
94
96
  exitCode: 0 | 10 | 11;
97
+ /** Proposable memory candidates that cite a finding of this loop or whose scope matches its files. Absent when there are none. */
98
+ memoryCandidates?: { id: string; title: string }[];
95
99
  }
96
100
 
97
101
  const GIT_TIMEOUT_MS = 30_000;
@@ -155,11 +159,11 @@ type IdentifiedResult = ReviewResult & { findings: { id: string }[] };
155
159
  type Attempt = { ok: true; result: IdentifiedResult } | { ok: false; why: string } | { interrupted: true };
156
160
 
157
161
  /** One review call: succeeds only with a complete `/2` result in which every finding has a history id. */
158
- function attempt(args: LocalArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps): Attempt {
162
+ async function attempt(args: LocalArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps): Promise<Attempt> {
159
163
  let out = "";
160
164
  let code: number;
161
165
  try {
162
- code = (deps.review ?? runLocal)(args, repoDir, env, { stdout: (t) => (out += t), stderr: io.stderr, engineVersion: io.engineVersion }, deps);
166
+ code = await (deps.review ?? runLocal)(args, repoDir, env, { stdout: (t) => (out += t), stderr: io.stderr, engineVersion: io.engineVersion }, deps);
163
167
  } catch (error) {
164
168
  if (error instanceof UsageError) throw error;
165
169
  return { ok: false, why: error instanceof Error ? error.message : String(error) };
@@ -188,8 +192,9 @@ interface LoopIo {
188
192
  const withVerdicts = (ledger: LedgerEntry[], verdicts: ReturnType<typeof readVerdicts>): LoopFinding[] =>
189
193
  ledger.map((e) => ({ ...e, ...(verdicts.get(e.id) ? { verdict: { verdict: verdicts.get(e.id)!.verdict, reason: verdicts.get(e.id)!.reason } } : {}) }));
190
194
 
191
- export function runLoop(args: LoopArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps = {}): number {
192
- const root = historyRoot(wachimanHome(env));
195
+ export async function runLoop(args: LoopArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps = {}): Promise<number> {
196
+ const home = wachimanHome(env);
197
+ const root = historyRoot(home);
193
198
  const key = repositoryKey(repoDir).key;
194
199
  const branch = currentBranch(repoDir);
195
200
  const head = headOf(repoDir);
@@ -214,7 +219,9 @@ export function runLoop(args: LoopArgs, repoDir: string, env: Record<string, str
214
219
  const verdicts = () => readVerdicts(root, key);
215
220
  const roundsRun = state.rounds.length;
216
221
  const render = (report: RoundReport) => {
217
- io.stdout(args.format === "json" ? renderJson(report) : renderTerminal(report));
222
+ const candidates = memoryCandidatesOf(state, home, key, repoDir);
223
+ const full: RoundReport = candidates.length > 0 ? { ...report, memoryCandidates: candidates } : report;
224
+ io.stdout(args.format === "json" ? renderJson(full) : renderTerminal(full));
218
225
  return report.exitCode;
219
226
  };
220
227
 
@@ -258,10 +265,10 @@ export function runLoop(args: LoopArgs, repoDir: string, env: Record<string, str
258
265
  ...(args.profile !== undefined ? { profile: args.profile } : {}),
259
266
  ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
260
267
  };
261
- let made = attempt(localArgs, repoDir, env, io, deps);
268
+ let made = await attempt(localArgs, repoDir, env, io, deps);
262
269
  if ("ok" in made && !made.ok) {
263
270
  io.stderr(`loop: the review failed (${made.why}); trying once more.`);
264
- made = attempt(localArgs, repoDir, env, io, deps);
271
+ made = await attempt(localArgs, repoDir, env, io, deps);
265
272
  }
266
273
  if ("interrupted" in made) return 130;
267
274
  if (!made.ok) {
@@ -290,6 +297,16 @@ export function runLoop(args: LoopArgs, repoDir: string, env: Record<string, str
290
297
  return render(report(state, round, args, result.change.head.sha, range, decision.decision, decision.decision.converged ? 0 : 10, finish(decision.decision, round, args)));
291
298
  }
292
299
 
300
+ /** The memory candidates worth asking the owner about after this round; none when memory is not in use. */
301
+ function memoryCandidatesOf(state: LoopState, home: string, key: string, repoDir: string) {
302
+ try {
303
+ const min = loadMemorySettings(repoDir).minEvidence;
304
+ return candidatesForRound(home, key, min, state.ledger);
305
+ } catch {
306
+ return [];
307
+ }
308
+ }
309
+
293
310
  /**
294
311
  * The new ledger and the decision after a round. The loop decides from the round's own result and the
295
312
  * code, never from the history's settled map (a review outside the loop writes to the same history).
@@ -413,6 +430,7 @@ export function renderJson(r: RoundReport): string {
413
430
  open: r.open.map((f) => ({ ...cleanFinding(f), ...(f.unreasonedWrong ? { unreasonedWrong: true } : {}) })),
414
431
  released: r.released.map((x) => ({ ...cleanFinding(x.finding), why: x.why, ...(x.reason ? { reason: x.reason } : {}) })),
415
432
  notes: r.notes.map(cleanFinding),
433
+ ...(r.memoryCandidates ? { memoryCandidates: r.memoryCandidates } : {}),
416
434
  };
417
435
  return `${JSON.stringify(doc, null, 2)}\n`;
418
436
  }
@@ -436,6 +454,10 @@ export function renderTerminal(r: RoundReport): string {
436
454
  lines.push("", `Notes, never counted (${r.notes.length}):`);
437
455
  for (const f of r.notes) lines.push(` ${row(f)}`);
438
456
  if (r.notes.length === 0) lines.push(" none");
457
+ if (r.memoryCandidates) {
458
+ lines.push("", `Memory candidates the owner could approve (${r.memoryCandidates.length}); show one with \`wachiman memory show <id>\`:`);
459
+ for (const c of r.memoryCandidates) lines.push(` ${c.id} ${neutralise(c.title).replace(/\s+/g, " ")}`);
460
+ }
439
461
  lines.push("", `Outcome (exit ${r.exitCode}): ${r.outcome.message}`);
440
462
  return `${lines.join("\n")}\n`;
441
463
  }