werkmeister-core 0.89.0 → 0.89.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # sandbox-core
2
2
 
3
+ ## 0.89.2
4
+
5
+ ### Patch Changes
6
+
7
+ - fedb19b: The ICM bug-fix exercise stage (after the review's fixes) and the feature and refactor implement stages (after a fix to the post-exercise review) rerun `werkmeister pr gate --tests` instead of one service's test command. These edits come after the gate's run, and the gate retests every service the diff touches, so a docs fix no longer skips docs-site's tests and fails the first `pr open`.
8
+ - 5e724a6: The ICM research and reproduce stages say that when a change adds or widens an input to a pre-approved command (an allow rule, or a wrapper one covers), the decision defaults to an allowlist of accepted values and lists what each can reach (files, env vars, network addresses, processes); a blocklist needs a stated reason.
9
+ - b811b93: `werkmeister-context.md` § Test commands prints each running service's `docker exec` test line with the repo's `lint:` appended (`… sh -c '<test> && <lint>'`), as the host test line already does. An implement stage that runs its tests in the container now catches a `docs:check` or format failure there, not first at `werkmeister pr gate`. The lint-tailed line is not pre-approved, since a service container can hold the Docker socket and the real `~/.werkmeister`: Claude Code asks before each run.
10
+ - 69877d8: Every ICM stage that exercises a change says that a filter, workaround or special case the exercise needs before the change passes is a finding: a `FAIL` row in `exercise.md` until the code is fixed, or until the row says why it reflects real use rather than a defect.
11
+ - 62dca50: The ICM research and reproduce stages name, before a recommended answer or proposed fix is written, how each acceptance criterion's stated verification runs on that design (which command, which platform or container), and turn a criterion whose verification cannot reach the design into an open question.
12
+
13
+ ## 0.89.1
14
+
3
15
  ## 0.89.0
4
16
 
5
17
  ### Minor Changes
@@ -24,6 +24,11 @@ export declare class DaemonTimeout extends SandboxError {
24
24
  export declare const tookTheCall: (code: string) => boolean;
25
25
  /** Request: the build the CLI would start. Response: the build the daemon loaded (SW-306). */
26
26
  export declare const BUILD_HEADER = "x-werkmeister-build";
27
+ /**
28
+ * `/api/tool`, request `1`: answer with headers at once and the status in the body (SW-700).
29
+ * Response `1`: the daemon did; a daemon that leaves it out answers with status codes.
30
+ */
31
+ export declare const STREAM_HEADER = "x-werkmeister-stream";
27
32
  /** `claudeLauncher()` evaluated in the session's env, not the daemon's launchd env. */
28
33
  export declare const LAUNCHER_HEADER = "x-werkmeister-launcher";
29
34
  /** Comma-separated `io.modelcontextprotocol/ui` mime types the session's MCP client advertised. */
@@ -65,6 +65,11 @@ const restartGapMs = () => Number(envVar("DAEMON_RETRY_MS")) || 15_000;
65
65
  let gaveUp = false;
66
66
  /** The error *code* comes after the request reached the daemon; a connect timeout never got there. */
67
67
  export const tookTheCall = (code) => code === "TimeoutError" || (code.startsWith("UND_ERR_") && code !== "UND_ERR_CONNECT_TIMEOUT");
68
+ // fetch wraps ECONNREFUSED and timeouts as a TypeError/AbortError with a cause.
69
+ const codeOf = (e) => {
70
+ const err = e;
71
+ return err.cause?.code ?? err.name;
72
+ };
68
73
  /**
69
74
  * *retry*: wait out the daemon's own restart (SW-306) on a refused or reset connect,
70
75
  * which the daemon never saw, so resending is safe.
@@ -79,9 +84,7 @@ async function send(url, init, retry = true) {
79
84
  return res;
80
85
  }
81
86
  catch (e) {
82
- // fetch wraps ECONNREFUSED and timeouts as a TypeError/AbortError with a cause.
83
- const err = e;
84
- const code = err.cause?.code ?? err.name;
87
+ const code = codeOf(e);
85
88
  if (tookTheCall(code))
86
89
  throw new DaemonTimeout(code);
87
90
  if (!(code in NOT_LISTENING))
@@ -97,6 +100,11 @@ async function send(url, init, retry = true) {
97
100
  }
98
101
  /** Request: the build the CLI would start. Response: the build the daemon loaded (SW-306). */
99
102
  export const BUILD_HEADER = "x-werkmeister-build";
103
+ /**
104
+ * `/api/tool`, request `1`: answer with headers at once and the status in the body (SW-700).
105
+ * Response `1`: the daemon did; a daemon that leaves it out answers with status codes.
106
+ */
107
+ export const STREAM_HEADER = "x-werkmeister-stream";
100
108
  // Set by the session's stdio proxy (SW-344): facts only the session's own process can see.
101
109
  /** `claudeLauncher()` evaluated in the session's env, not the daemon's launchd env. */
102
110
  export const LAUNCHER_HEADER = "x-werkmeister-launcher";
@@ -166,6 +174,7 @@ export async function callTool(name, args = {}, opts = {}) {
166
174
  "Content-Type": "application/json",
167
175
  ...headers(opts.token),
168
176
  ...(build ? { [BUILD_HEADER]: build } : {}),
177
+ [STREAM_HEADER]: "1",
169
178
  },
170
179
  body: JSON.stringify({ name, arguments: args }),
171
180
  signal: opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout,
@@ -177,14 +186,21 @@ export async function callTool(name, args = {}, opts = {}) {
177
186
  res.status !== 403) {
178
187
  throw new DaemonUnavailable(`HTTP ${res.status}: the port is held by something that is not the werkmeister daemon`);
179
188
  }
180
- const body = (await res.json().catch(() => ({})));
181
- if (!res.ok) {
189
+ const streamed = res.headers.get(STREAM_HEADER) === "1";
190
+ const body = (await res.json().catch((e) => {
191
+ // Streamed headers mean the daemon is running the call: never let a caller run it again.
192
+ if (streamed)
193
+ throw new DaemonTimeout(codeOf(e));
194
+ return {};
195
+ }));
196
+ const status = streamed ? (body.status ?? 500) : res.status;
197
+ if (status < 200 || status > 299) {
182
198
  // SW-254: the daemon has no tool this CLI knows, so it runs older code; the MCP SDK's own words.
183
199
  if (body.error?.replace(/^MCP error -?\d+: /, "") === `Tool ${name} not found`) {
184
200
  throw new SandboxError(`The werkmeister daemon is older than this CLI: it has no \`${name}\` tool. ` +
185
201
  "Run `werkmeister daemon restart`.", "DAEMON_STALE");
186
202
  }
187
- throw new SandboxError(body.error ?? `daemon answered HTTP ${res.status} to ${name}`, body.code ?? `HTTP_${res.status}`);
203
+ throw new SandboxError(body.error ?? `daemon answered HTTP ${status} to ${name}`, body.code ?? `HTTP_${status}`);
188
204
  }
189
205
  return { data: body.structuredContent, text: body.text ?? "" };
190
206
  }
@@ -253,13 +253,13 @@ Hit a bug, or need to log a feature or task, in the \`werkmeister\` tool or a re
253
253
  // ---------------------------------------------------------------------------
254
254
  // werkmeister-context.md generation
255
255
  // ---------------------------------------------------------------------------
256
- function testCommandLine(feature, svc, servicesConfig, archetypes) {
256
+ function testCommandLine(feature, svc, servicesConfig, archetypes, lint) {
257
257
  const cmd = serviceTestCommand(svc, servicesConfig[svc], archetypes);
258
258
  const noTests = serviceNoTests(servicesConfig[svc]);
259
259
  if (noTests)
260
260
  return `- \`${svc}\`: no tests (registry: ${noTests})`;
261
261
  return cmd
262
- ? `- \`${svc}\`: \`${containerTestCommand(feature, svc, cmd)}\``
262
+ ? `- \`${svc}\`: \`${containerTestCommand(feature, svc, lint ? `${cmd} && ${lint}` : cmd)}\``
263
263
  : `- \`${svc}\`: no test command registered (add \`test:\` to its registry entry)`;
264
264
  }
265
265
  /**
@@ -415,6 +415,8 @@ export function buildSandboxContextMd(feature, slot, portStart, portEnd, localSe
415
415
  let containerCommandsBlock;
416
416
  if (localServices.length > 0) {
417
417
  const svcs = [...localServices].sort();
418
+ // SW-688: the in-container line carries the repo's lint too, as the host line does (SW-219).
419
+ const svcLint = svcs.map((s) => lintOf(String(servicesConfig[s]?.["repo"] ?? "")));
418
420
  const containerList = svcs.map((s) => `\`${feature}-${s}\``).join(", ");
419
421
  const sampleSvc = svcs[0];
420
422
  containerCommandsBlock = `### Container Commands
@@ -434,9 +436,11 @@ docker compose restart ${sampleSvc}
434
436
 
435
437
  ### Test commands
436
438
 
437
- The registry's \`test:\` for each service (or its archetype's), run in its container — the worktree is mounted at \`/app\` with its \`node_modules\`; the host checkout has none. The pre-PR gate runs these (\`werkmeister pr gate\`).
439
+ The registry's \`test:\` for each service (or its archetype's), run in its container — the worktree is mounted at \`/app\` with its \`node_modules\`; the host checkout has none. The pre-PR gate runs these (\`werkmeister pr gate\`).${svcLint.some(Boolean)
440
+ ? " A line ending in `&& <lint>` also runs the repo's lint, the PR gate's lint row, so a `docs:check` or format failure shows here and not first at the gate."
441
+ : ""}
438
442
 
439
- ${svcs.map((s) => testCommandLine(feature, s, servicesConfig, archetypes ?? loadArchetypes())).join("\n")}
443
+ ${svcs.map((s, i) => testCommandLine(feature, s, servicesConfig, archetypes ?? loadArchetypes(), svcLint[i])).join("\n")}
440
444
 
441
445
  `;
442
446
  }
@@ -501,7 +505,7 @@ or visit https://${proxy.host}/__werkmeister and select \`${feature}\` — the s
501
505
  How to exercise a change to each service in this workspace.${onDemand.length
502
506
  ? ` A plain \`werkmeister feature up\` skips the on-demand ones, ${onDemand.map((s) => `\`${s}\``).join(", ")}: start one with \`werkmeister feature up --service <name>\`.`
503
507
  : ""}${tempHome
504
- ? ` Each test command runs through \`.werkmeister/bin/with-temp-home\`, which gives it a fresh temporary HOME and deletes it on exit: never hand-roll \`HOME=…\`. Start every exercise command with the script itself, never with env assignments or a \`cd\`, so one permission rule matches it: \`${tempHome} <test command>\`. A command that needs an env var takes it after the script (\`${tempHome} env WERKMEISTER_ROOT=… <cmd>\`); no rule pre-approves that form, so it asks. Put \`--no-wait\` first (\`${tempHome} --no-wait <cmd>\`) to skip its host-load wait; the allow rules below cover that form too. That wait lasts up to 90 s; if load is still over then, the script exits 75 without running the command (retry later). It prints only on stderr, so a foreground call shows nothing until it ends and its only child is \`werkmeister internal wait-load\`: that is the wait, not a hang. The allow rule that covers them is \`Bash(${tempHome} <test command>:*)\` for each test command below: run those for a test without a prompt. A test command of more than one command (an \`&&\` chain, a \`{ …; }\` group, \`||\`, \`;\` or a pipe) is shown as \`${tempHome} sh -c '…'\`, so every part runs under the temp HOME, and its rule allows that exact line: run it as shown, with no extra arguments. Neither \`node --test\` through the script nor the script alone is allowed, since both run any file (SW-510). The temp HOME only keeps a run from writing to the real one by accident; it is not an isolation boundary. A pre-approved test command or built CLI still runs whatever the worktree holds, a test written in this run included, and that code can reach absolute paths, the caller's env, the network, docker and gh (SW-522).`
508
+ ? ` Each test command runs through \`.werkmeister/bin/with-temp-home\`, which gives it a fresh temporary HOME and deletes it on exit: never hand-roll \`HOME=…\`. Start every exercise command with the script itself, never with env assignments or a \`cd\`, so one permission rule matches it: \`${tempHome} <test command>\`. A command that needs an env var takes it after the script (\`${tempHome} env WERKMEISTER_ROOT=… <cmd>\`); no rule pre-approves that form, so it asks. Put \`--no-wait\` first (\`${tempHome} --no-wait <cmd>\`) to skip its host-load and free-memory wait; the allow rules below cover that form too. That wait lasts up to 90 s; if load or memory is still over its limit then, the script exits 75 without running the command (retry later). It prints only on stderr, so a foreground call shows nothing until it ends and its only child is \`werkmeister internal wait-load\`: that is the wait, not a hang. The allow rule that covers them is \`Bash(${tempHome} <test command>:*)\` for each test command below: run those for a test without a prompt. A test command of more than one command (an \`&&\` chain, a \`{ …; }\` group, \`||\`, \`;\` or a pipe) is shown as \`${tempHome} sh -c '…'\`, so every part runs under the temp HOME, and its rule allows that exact line: run it as shown, with no extra arguments. Neither \`node --test\` through the script nor the script alone is allowed, since both run any file (SW-510). The temp HOME only keeps a run from writing to the real one by accident; it is not an isolation boundary. A pre-approved test command or built CLI still runs whatever the worktree holds, a test written in this run included, and that code can reach absolute paths, the caller's env, the network, docker and gh (SW-522).`
505
509
  : ""}${linted
506
510
  ? " A test command ending in `&& <lint>` also runs the repo's lint, the same command the PR gate's lint row runs, so a format error fails here and not first at `werkmeister pr open`."
507
511
  : ""}
@@ -76,6 +76,11 @@ export interface Deps {
76
76
  load: number[];
77
77
  cores: number;
78
78
  };
79
+ /** Bytes available and total, read once before the gate starts anything (SW-620). */
80
+ hostMemory: () => {
81
+ free: number;
82
+ total: number;
83
+ };
79
84
  sleep: (ms: number) => Promise<void>;
80
85
  /** One idle-reaper pass over every workspace (SW-39). */
81
86
  reapIdle: () => Promise<{
@@ -28,7 +28,7 @@ import { loadNote } from "./resources.js";
28
28
  import { commitAndPush, listRepoWorktrees, listWorkspaces, removeWorkspace, resolveSessionSource, resolveWorkspaceDir, sendToClaudeSession, sessionStartDir, WorkspaceError, worktreeSources,
29
29
  // biome-ignore lint/suspicious/noImportCycles: pr_lifecycle↔sandbox.ts↔usage_snapshot; SW-411
30
30
  } from "./sandbox.js";
31
- import { portHolders, readHostLoad, waitForHostLoadNow } from "./scheduler_state.js";
31
+ import { lowMemory, portHolders, readHostLoad, readHostMemory, waitForHostLoadNow, } from "./scheduler_state.js";
32
32
  import { getServicePort } from "./slots.js";
33
33
  import { repoDirs } from "./standards.js";
34
34
  import { TEMP_HOME_SCRIPT } from "./temp_home.js";
@@ -91,6 +91,7 @@ export function defaultDeps() {
91
91
  stop: stopWorkspace,
92
92
  prWatch: () => prWatchScheduleState(),
93
93
  hostLoad: readHostLoad,
94
+ hostMemory: readHostMemory,
94
95
  sleep: (ms) => delay(ms),
95
96
  reapIdle: async () => {
96
97
  const minutes = idleStopMinutes();
@@ -571,7 +572,8 @@ testsOnly = false) {
571
572
  ...(!ok && capacityShort && NO_CONTAINER.test(detail) && { retry: true }),
572
573
  });
573
574
  const startFailed = (name, e, prefix = "") => {
574
- const capacity = e.code === "NO_CAPACITY";
575
+ // HOST_LOAD: a setup start that waited out load or low memory is the host, not the change (SW-620).
576
+ const capacity = ["NO_CAPACITY", "HOST_LOAD"].includes(e.code ?? "");
575
577
  if (capacity)
576
578
  capacityShort = true;
577
579
  checks.push({
@@ -884,6 +886,18 @@ testsOnly = false) {
884
886
  }
885
887
  return true;
886
888
  };
889
+ // Admission prices reservations, not the host's live memory: Claude Code stops an idle background
890
+ // gate when the Mac runs low, before any row runs, so exit 75 before starting anything (SW-620).
891
+ const memory = lowMemory(deps.hostMemory);
892
+ if (memory) {
893
+ checks.push({
894
+ name: "memory",
895
+ ok: false,
896
+ detail: `low memory: ${memory}; no container started and no row run. Retry later.`,
897
+ retry: true,
898
+ });
899
+ return done();
900
+ }
887
901
  // Running containers come from compose.yml, rendered from the machine registry; a
888
902
  // touched service whose branch settings render differently runs from compose.gate.yml (SW-118).
889
903
  let changed = [];
@@ -1112,7 +1126,7 @@ export function failedRowExcerpt(output, tail) {
1112
1126
  }
1113
1127
  export function formatGate(dir, g) {
1114
1128
  return [
1115
- `${dir}: gate ${g.ok ? "passed" : g.retry ? "retry later (no capacity)" : "FAILED"}`,
1129
+ `${dir}: gate ${g.ok ? "passed" : g.retry ? `retry later (${g.checks.some((c) => c.name === "memory" && !c.ok) ? "low memory" : "no capacity"})` : "FAILED"}`,
1116
1130
  ...g.checks.map((c) => ` ${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail.replace(/\n/g, "\n ")}`),
1117
1131
  ];
1118
1132
  }
@@ -39,11 +39,30 @@ export declare function loadBudget(info?: () => Promise<{
39
39
  }>): Promise<Budget>;
40
40
  /** 1-min host load above which with-temp-home and a setup start wait (SW-209, SW-542, SW-630): `budget.host_load`, else 2 × cores; 0 is off. */
41
41
  export declare function hostLoadLimit(cores: number): number;
42
+ /** % of memory available under which the gate and with-temp-home hold off (SW-620): `budget.free_memory`, else 15; 0 is off. */
43
+ export declare function freeMemoryLimit(): number;
44
+ /**
45
+ * Bytes available and total. On macOS os.freemem() counts only untouched pages (0.08 of 16 GiB on a
46
+ * healthy host), so it reads kern.memorystatus_level, the % the kernel calls available (SW-620).
47
+ */
48
+ export declare function readHostMemory(platform?: NodeJS.Platform): {
49
+ free: number;
50
+ total: number;
51
+ };
52
+ /** "N% free, under budget.free_memory M%" when memory is low, else ""; unreadable memory is not low. */
53
+ export declare function lowMemory(hostMemory?: () => {
54
+ free: number;
55
+ total: number;
56
+ }): string;
42
57
  export interface HostLoadDeps {
43
58
  hostLoad: () => {
44
59
  load: number[];
45
60
  cores: number;
46
61
  };
62
+ hostMemory: () => {
63
+ free: number;
64
+ total: number;
65
+ };
47
66
  sleep: (ms: number) => Promise<unknown>;
48
67
  }
49
68
  export declare const readHostLoad: () => {
@@ -52,16 +71,18 @@ export declare const readHostLoad: () => {
52
71
  };
53
72
  /**
54
73
  * The wait of `werkmeister internal wait-load`, which the generated with-temp-home runs first (SW-224):
55
- * up to 90 s for the 1-minute load to fall under the limit, saying so up front and printing progress
56
- * each minute (SW-262); the note for the wrapper's stderr, or "". The gate stopped waiting in SW-542.
57
- * Not on macOS: its loadavg counts idle daemons in R state (450-550 on a quiet host) and never the
58
- * Linux VM that runs the tests, so it is no signal to wait on and the wait was pure delay (SW-556).
74
+ * up to 90 s for the 1-minute load to fall under the limit and free memory to rise over its own (SW-620),
75
+ * saying so up front and printing progress each minute (SW-262); the note for the wrapper's stderr, or "".
76
+ * A spent wait's note starts "ran with". The gate stopped waiting in SW-542.
77
+ * Load not on macOS: its loadavg counts idle daemons in R state (450-550 on a quiet host) and never the
78
+ * Linux VM that runs the tests, so it is no signal to wait on (SW-556). Its memory is: Claude Code
79
+ * stops an idle background shell when the Mac runs low (SW-620).
59
80
  */
60
81
  export declare function waitForHostLoadNow(deps?: HostLoadDeps, platform?: NodeJS.Platform, before?: string): Promise<string>;
61
82
  /**
62
83
  * Before compose starts a setup one-shot among *services* (undefined: what a whole `up` starts),
63
- * wait on host load as with-temp-home does, and fail with the load once the wait is spent (SW-630):
64
- * a setup install started at load ~413 ran 78 min, past compose's 20 min `--wait`, and ended 137.
84
+ * wait on host load and free memory as with-temp-home does, and fail once the wait is spent (SW-630,
85
+ * SW-620): a setup install started at load ~413 ran 78 min, past compose's 20 min `--wait`, and ended 137.
65
86
  *
66
87
  * Throws `HOST_LOAD`.
67
88
  */
@@ -11,6 +11,7 @@
11
11
  * What is running, and what it costs, is never stored: `lifecycle.ts` reads it
12
12
  * from Docker on every decision, because `up` exits once containers start.
13
13
  */
14
+ import { execFileSync } from "node:child_process";
14
15
  import { createHash } from "node:crypto";
15
16
  import * as fs from "node:fs";
16
17
  import * as net from "node:net";
@@ -115,43 +116,106 @@ export function hostLoadLimit(cores) {
115
116
  const v = isDict(cfg) ? Number(cfg["host_load"] ?? Number.NaN) : Number.NaN;
116
117
  return Number.isFinite(v) && v >= 0 ? v : 2 * cores;
117
118
  }
119
+ /** % of memory available under which the gate and with-temp-home hold off (SW-620): `budget.free_memory`, else 15; 0 is off. */
120
+ export function freeMemoryLimit() {
121
+ const cfg = loadGlobalConfig()["budget"];
122
+ const v = isDict(cfg) ? Number(cfg["free_memory"] ?? Number.NaN) : Number.NaN;
123
+ return Number.isFinite(v) && v >= 0 ? v : 15;
124
+ }
125
+ /**
126
+ * Bytes available and total. On macOS os.freemem() counts only untouched pages (0.08 of 16 GiB on a
127
+ * healthy host), so it reads kern.memorystatus_level, the % the kernel calls available (SW-620).
128
+ */
129
+ export function readHostMemory(platform = process.platform) {
130
+ const total = os.totalmem();
131
+ if (platform !== "darwin")
132
+ return { free: os.freemem(), total };
133
+ const level = Number(execFileSync("sysctl", ["-n", "kern.memorystatus_level"], { encoding: "utf8" }));
134
+ return { free: (total * level) / 100, total };
135
+ }
136
+ /** "N% free, under budget.free_memory M%" when memory is low, else ""; unreadable memory is not low. */
137
+ export function lowMemory(hostMemory = readHostMemory) {
138
+ const limit = freeMemoryLimit();
139
+ if (limit === 0)
140
+ return "";
141
+ let pct;
142
+ try {
143
+ const { free, total } = hostMemory();
144
+ pct = (100 * free) / total;
145
+ }
146
+ catch {
147
+ return "";
148
+ }
149
+ return Number.isFinite(pct) && pct < limit
150
+ ? `${pct.toFixed(0)}% free, under budget.free_memory ${limit}%`
151
+ : "";
152
+ }
118
153
  const LOAD_POLL_MS = 15_000;
119
154
  // with-temp-home's own wait: under an agent's default 2 min Bash timeout, so the call can't time out before its command starts (SW-469).
120
155
  const WRAPPER_LOAD_WAIT_MS = 90_000;
121
156
  const LOAD_PROGRESS_MS = 60_000;
122
157
  export const readHostLoad = () => ({ load: os.loadavg(), cores: os.availableParallelism() });
123
- const realHostLoad = { hostLoad: readHostLoad, sleep: (ms) => delay(ms) };
158
+ const realHostLoad = {
159
+ hostLoad: readHostLoad,
160
+ hostMemory: readHostMemory,
161
+ sleep: (ms) => delay(ms),
162
+ };
124
163
  const minutes = (ms) => Number((ms / 60_000).toFixed(1));
125
164
  /**
126
165
  * The wait of `werkmeister internal wait-load`, which the generated with-temp-home runs first (SW-224):
127
- * up to 90 s for the 1-minute load to fall under the limit, saying so up front and printing progress
128
- * each minute (SW-262); the note for the wrapper's stderr, or "". The gate stopped waiting in SW-542.
129
- * Not on macOS: its loadavg counts idle daemons in R state (450-550 on a quiet host) and never the
130
- * Linux VM that runs the tests, so it is no signal to wait on and the wait was pure delay (SW-556).
166
+ * up to 90 s for the 1-minute load to fall under the limit and free memory to rise over its own (SW-620),
167
+ * saying so up front and printing progress each minute (SW-262); the note for the wrapper's stderr, or "".
168
+ * A spent wait's note starts "ran with". The gate stopped waiting in SW-542.
169
+ * Load not on macOS: its loadavg counts idle daemons in R state (450-550 on a quiet host) and never the
170
+ * Linux VM that runs the tests, so it is no signal to wait on (SW-556). Its memory is: Claude Code
171
+ * stops an idle background shell when the Mac runs low (SW-620).
131
172
  */
132
173
  export async function waitForHostLoadNow(deps = realHostLoad, platform = process.platform, before = "with-temp-home; --no-wait skips") {
133
174
  // WERKMEISTER_NO_WAIT skips it inside the command too, not only in with-temp-home's shell (SW-425).
134
- if (platform === "darwin" || envVar("NO_WAIT"))
175
+ if (envVar("NO_WAIT"))
135
176
  return "";
136
- let { load, cores } = deps.hostLoad();
137
- const limit = hostLoadLimit(cores);
138
- if (limit === 0 || load[0] <= limit)
177
+ const read = () => {
178
+ const { load, cores } = deps.hostLoad();
179
+ const limit = platform === "darwin" ? 0 : hostLoadLimit(cores);
180
+ return {
181
+ load: load[0],
182
+ limit,
183
+ loadOver: limit !== 0 && load[0] > limit,
184
+ memory: lowMemory(deps.hostMemory),
185
+ };
186
+ };
187
+ let now = read();
188
+ if (!now.loadOver && !now.memory)
139
189
  return "";
140
- info(`waiting up to ${minutes(WRAPPER_LOAD_WAIT_MS)} min for host load ${load[0].toFixed(1)} to fall to ${limit} (budget.host_load) before ${before}`);
190
+ const waitedFor = [now.loadOver && "host load", now.memory && "free memory"]
191
+ .filter(Boolean)
192
+ .join(" and ");
193
+ info(`waiting up to ${minutes(WRAPPER_LOAD_WAIT_MS)} min for ${[
194
+ now.loadOver && `host load ${now.load.toFixed(1)} to fall to ${now.limit} (budget.host_load)`,
195
+ now.memory && `free memory to rise (${now.memory})`,
196
+ ]
197
+ .filter(Boolean)
198
+ .join(" and ")} before ${before}`);
199
+ const state = () => [
200
+ now.loadOver && `host load ${now.load.toFixed(1)} over ${now.limit}`,
201
+ now.memory && `low memory (${now.memory})`,
202
+ ]
203
+ .filter(Boolean)
204
+ .join(", ");
141
205
  for (let waited = LOAD_POLL_MS; waited <= WRAPPER_LOAD_WAIT_MS; waited += LOAD_POLL_MS) {
142
206
  await deps.sleep(LOAD_POLL_MS);
143
- ({ load } = deps.hostLoad());
144
- if (load[0] <= limit)
145
- return `waited ${waited / 1000} s for host load`;
207
+ now = read();
208
+ if (!now.loadOver && !now.memory)
209
+ return `waited ${waited / 1000} s for ${waitedFor}`;
146
210
  if (waited % LOAD_PROGRESS_MS === 0 && waited < WRAPPER_LOAD_WAIT_MS)
147
- info(`still waiting for host load: ${load[0].toFixed(1)} over ${limit}, ${waited / 1000} s so far, up to ${minutes(WRAPPER_LOAD_WAIT_MS - waited)} min left`);
211
+ info(`still waiting: ${state()}, ${waited / 1000} s so far, up to ${minutes(WRAPPER_LOAD_WAIT_MS - waited)} min left`);
148
212
  }
149
- return `ran with host load ${load[0].toFixed(1)} over ${limit}; the ${minutes(WRAPPER_LOAD_WAIT_MS)} min host-load wait is spent`;
213
+ return `ran with ${state()}; the ${minutes(WRAPPER_LOAD_WAIT_MS)} min host-load wait is spent`;
150
214
  }
151
215
  /**
152
216
  * Before compose starts a setup one-shot among *services* (undefined: what a whole `up` starts),
153
- * wait on host load as with-temp-home does, and fail with the load once the wait is spent (SW-630):
154
- * a setup install started at load ~413 ran 78 min, past compose's 20 min `--wait`, and ended 137.
217
+ * wait on host load and free memory as with-temp-home does, and fail once the wait is spent (SW-630,
218
+ * SW-620): a setup install started at load ~413 ran 78 min, past compose's 20 min `--wait`, and ended 137.
155
219
  *
156
220
  * Throws `HOST_LOAD`.
157
221
  */
@@ -167,9 +231,19 @@ export async function waitForSetupLoad(workspace, services, deps = realHostLoad,
167
231
  if (!note.startsWith("ran with"))
168
232
  return;
169
233
  const { load, cores } = deps.hostLoad();
170
- throw new SandboxError(`host load ${load[0].toFixed(1)} is over ${hostLoadLimit(cores)} (budget.host_load) after the ` +
171
- `${minutes(WRAPPER_LOAD_WAIT_MS)} min wait; ${what} not started. Retry when load falls, ` +
172
- "or set WERKMEISTER_NO_WAIT=1 to start anyway.", "HOST_LOAD");
234
+ const limit = hostLoadLimit(cores);
235
+ const memory = lowMemory(deps.hostMemory);
236
+ const over = [
237
+ platform !== "darwin" &&
238
+ limit !== 0 &&
239
+ load[0] > limit &&
240
+ `host load ${load[0].toFixed(1)} is over ${limit} (budget.host_load)`,
241
+ memory && `memory is low (${memory})`,
242
+ ]
243
+ .filter(Boolean)
244
+ .join(" and ");
245
+ throw new SandboxError(`${over || note} after the ${minutes(WRAPPER_LOAD_WAIT_MS)} min wait; ${what} not started. ` +
246
+ "Retry when load falls or memory frees, or set WERKMEISTER_NO_WAIT=1 to start anyway.", "HOST_LOAD");
173
247
  }
174
248
  function composeServices(workspace, composePath = path.join(workspace, COMPOSE_FILE)) {
175
249
  try {
@@ -18,6 +18,8 @@ const HOSTNAME_RULE = "If `werkmeister feature up` warns that a routed hostname
18
18
  // SW-143: a library or CLI has nothing to restart. How to exercise one is the service's (or its archetype's)
19
19
  // `validate:` text, so app-specific steps stay out of the generic templates.
20
20
  const NO_SERVICE_RULE = "A library or CLI has no service to restart: build it, then exercise the built artifact exactly as its Validation text in `werkmeister-context.md` § How to validate says.";
21
+ // SW-691: sw-681's replay filtered out the very lines that showed its bug, and recorded nothing.
22
+ const EXERCISE_WORKAROUND = "A filter, workaround or special case the exercise needs before the change passes is a finding: write it into `exercise.md` as a `FAIL` row until the code is fixed, or until the row says why it reflects real use rather than a defect.";
21
23
  const IMPLEMENT_STEPS = [
22
24
  "Confirm ponytail is active (see `_shared/standards.md`; invoke the skill only if it is not), then read the standards rows above. Restate the rule you are applying beside each edit.",
23
25
  ];
@@ -47,7 +49,8 @@ const HOST_TEST_STEP = `${HOST_TESTS}Record its exit code. ${TEST_TAIL}`;
47
49
  // SW-430: the gate runs once, on reviewed code; a Must fix found after it forced a rerun (SW-344).
48
50
  const GATE_STEP = "Once the review's fixes are in, run `werkmeister pr gate --tests` (from the workspace, detached when it may pass 10 minutes) and fix what it fails; record its exit code. A fix here reruns the host test step first.";
49
51
  // SW-534: sw-385's exercise on the real harness fixed ~40 lines after the review; they shipped unreviewed.
50
- const REVIEW_DELTA = "If the exercise below changes code, rerun the review on that delta: a fresh subagent with the same brief, over the commits and changes made since the first review. Fix its **Must fix** findings, rerun the host test step, and append the result as new rows to `output/review.md`; the gate's review row covers them.";
52
+ // SW-678: a docs fix rerun with one service's tests skipped docs-site's, and the first `pr open` failed on it.
53
+ const REVIEW_DELTA = "If the exercise below changes code, rerun the review on that delta: a fresh subagent with the same brief, over the commits and changes made since the first review. Fix its **Must fix** findings, rerun `werkmeister pr gate --tests` (not one service's test command: these edits come after the gate above, and the gate retests every service the diff touches), and append the result as new rows to `output/review.md`; the gate's review row covers them.";
51
54
  // SW-351: one of five parallel Edits reported success but never reached the file; tests did not cover it.
52
55
  const diffCheck = (doc) => `Before running tests, read \`git diff\` in each repo you touched and tick off each edit \`${doc}\` settled against it: an edit reported as applied can be missing.`;
53
56
  // SW-562: sw-499's two MANUAL rows (a real VS Code window) were approved unrun and shipped as MANUAL, never recorded.
@@ -91,12 +94,16 @@ const reviewStep = (rerun, group) => "Review the diff: for each code worktree yo
91
94
  `${REVIEW_FORMAT}, with one row per worktree (\`PASS\` means no Must fix left open). ` +
92
95
  "The PR gate refuses to open a PR while `review.md` is missing or has a row that is not `PASS`; a file of prose alone fails with `has no PASS row`.";
93
96
  const implementReview = (v) => reviewStep("rerun the host test step above", v.group);
97
+ // SW-687: sw-634 decided a blocklist for a pre-approved wrapper's input; one key it let through sent auth to any host.
98
+ const PREAPPROVED_INPUT = "When the change adds or widens an input to a pre-approved command (an allow rule, or a wrapper an allow rule covers), the decision defaults to an allowlist of accepted values and lists what each accepted value can reach: files, env vars, network addresses, processes. A blocklist needs a stated reason.";
94
99
  // SW-106 decision 7 renamed a legacy alias that `git log -S` would have shown was meant to be removed.
95
100
  const NAME_HISTORY_STEP = "For each decision that renames, keeps or removes a name, a fallback or an alias, record its definition site (file and line) and the commit that introduced it (`git log -S <name>`, in the repo that defines it). " +
96
101
  'When that commit marks it as a transition or legacy alias, list "remove" as an option beside rename and keep.';
97
102
  // SW-478: a stage gate must be a status line, so /check-in can flip it with its note and the waiting session acts on the file.
98
103
  const statusGate = (file, read) => `${read} Then change \`status: proposed\` at the top of \`output/${file}\` to \`status: decided\`: that flip is the approval, and the next session starts without asking again. ${CHAT_APPROVAL}`;
99
104
  const FIRST_LINE = ", its first line `status: proposed`";
105
+ // SW-709: sw-614's criterion was checked in the Linux container, where the decided macOS-only row never runs.
106
+ const CRITERION_REACH = "Before writing a recommended answer or proposed fix, name for each acceptance criterion in `BRIEF.md` how its stated verification runs on that design (which command, which platform or container). A criterion whose verification cannot reach the design is an open question, not a decided one.";
100
107
  // SW-517: a check left as a sentence at the end of a long reply is easy to miss; the question tool makes it a prompt.
101
108
  export const askLine = (tool) => tool
102
109
  ? `Ask this check through \`${tool}\`: at most 4 questions per call (more than 4: batches of 4, one call after another), each standing on its own (what was checked, 2–3 concrete options with the exact wording or behaviour, the recommended one first; "Other" takes edits). Write each answer into the output file as its status, noted \`${APPROVAL_NOTE.chat}\` (a PR file: \`${APPROVAL_NOTE.chatPr}\`). A check left as a sentence at the end of a reply is not asked.`
@@ -182,10 +189,11 @@ const feature = [
182
189
  // Moved from docs/harnesses.md: adapter runs kept deciding from a harness's docs, not its binary.
183
190
  "When a decision rests on how an external tool behaves (a CLI command or flag, a plugin API, an event name), check it against the installed tool, not only its docs: record `<bin> --version`, and confirm each fact with `<bin> <cmd> --help` or a real run or plugin load. `decisions.md` names the version and, beside each fact, the command that confirmed it; a fact only the docs support is marked `unverified: docs only`, and no decision rests on it. If the tool cannot be installed, say so and mark every such fact `unverified`. " +
184
191
  // SW-605: sw-583 recommended a GitHub API call as `unverified` only in the file; the person approved it and a read-only call later returned 403.
185
- "A recommended answer that rests on an external API, permission or platform behaviour (a token scope, a hosted API's response, a cloud permission) is checked live, read-only (a list, get, `--help` or dry run, never a write), before it goes into `decisions.md`, with the command and its result beside it. When it cannot be checked read-only, write `unverified` in the option text itself, so the question the person is asked carries the word, not only the file.",
192
+ "A recommended answer that rests on an external API, permission or platform behaviour (a token scope, a hosted API's response, a cloud permission) is checked live, read-only (a list, get, `--help` or dry run, never a write), before it goes into `decisions.md`, with the command and its result beside it. When it cannot be checked read-only, write `unverified` in the option text itself, so the question the person is asked carries the word, not only the file. " +
193
+ PREAPPROVED_INPUT,
186
194
  "Write `output/inventory.md`: steps 1–3.",
187
195
  NAME_HISTORY_STEP,
188
- "Write `output/decisions.md`: every open question in `BRIEF.md`, each as a heading with `status: proposed`, your recommended answer, and the evidence from steps 1–3 and 5. Leave the answer blank when only a person can give it (a ticket key, a preference).",
196
+ `Write \`output/decisions.md\`: every open question in \`BRIEF.md\`, each as a heading with \`status: proposed\`, your recommended answer, and the evidence from steps 1–3 and 5. Leave the answer blank when only a person can give it (a ticket key, a preference). ${CRITERION_REACH}`,
189
197
  ],
190
198
  outputs: ["`output/inventory.md`", "`output/decisions.md`"],
191
199
  humanCheck: `Open \`output/decisions.md\`. Edit each answer as needed and change its \`status: proposed\` to \`status: decided\`. The next stage must not start while any question is still \`proposed\`. When every question reads \`decided\`, that is the approval — the next session starts the next stage without asking for confirmation. ${CHAT_APPROVAL}`,
@@ -247,7 +255,7 @@ const feature = [
247
255
  implementReview(v),
248
256
  GATE_STEP,
249
257
  REVIEW_DELTA,
250
- `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} Then exercise the change as the How-to-validate section of \`werkmeister-context.md\` describes for each service touched, and capture the output. ${NO_SERVICE_RULE}`,
258
+ `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} Then exercise the change as the How-to-validate section of \`werkmeister-context.md\` describes for each service touched, and capture the output. ${NO_SERVICE_RULE} ${EXERCISE_WORKAROUND}`,
251
259
  `Write \`output/exercise.md\`: \`git diff --stat\` for each repo you touched, the host and \`pr gate --tests\` exit codes and summary lines, ${SKIPPED}, any deviation from \`spec.md\` with its reason, and the exercise checks as ${exerciseFormat("evidence")}.`,
252
260
  MANUAL_STEP,
253
261
  ],
@@ -289,11 +297,11 @@ const bugfix = [
289
297
  // SW-566: sw-545's fix changed a return shape its one caller treated as "stop"; only the exercise caught it.
290
298
  "List every other caller of the function at the root cause and what each does with the result (an early return, a printed value, a stored state), so the fix's return shape is checked against every caller before the fix stage — a fix there reaches them too. When the fix belongs in shared code, list its call sites through every helper or entry point that reaches that code, not one argument shape, and record the search commands (greps) you used in `repro.md`.",
291
299
  // SW-442: sessionBusy had two true cases; stage 01 listed callers, so only review caught the second (sw-418).
292
- "When the proposed fix branches on a predicate, list each condition that makes it true and give each one a test.",
300
+ `When the proposed fix branches on a predicate, list each condition that makes it true and give each one a test. ${PREAPPROVED_INPUT}`,
293
301
  NAME_HISTORY_STEP,
294
302
  // SW-564: sw-521's root cause was a permission rule; step 4 listed the callers of one builder and missed two other sources of a matching rule.
295
303
  "When the root cause is a permission rule (allow, deny, ask), step 4 lists every source of a matching rule: each builder, each rule derived from a registered command (its `&&` segments included), rules recorded in existing workspaces and how a refresh or migrate removes them, and the list a headless wake passes (`--allowedTools` / `--disallowedTools`). The failing test probes each source.",
296
- `Write \`output/repro.md\`: steps 1–7, and a proposed fix in one paragraph under a \`status: proposed\` line.${noCommitPlan(v.group)}`,
304
+ `Write \`output/repro.md\`: steps 1–7, and a proposed fix in one paragraph under a \`status: proposed\` line.${noCommitPlan(v.group)} ${CRITERION_REACH}`,
297
305
  ],
298
306
  outputs: ["`output/repro.md`", "One failing test, uncommitted"],
299
307
  humanCheck: `Read \`output/repro.md\`. Correct the root cause or the proposed fix if needed, then change \`status: proposed\` to \`status: decided\`. That is the approval — the next session starts the fix without asking again. ${CHAT_APPROVAL}`,
@@ -351,11 +359,12 @@ const bugfix = [
351
359
  process: [
352
360
  `Reload the running code: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${NO_SERVICE_RULE}`,
353
361
  "Rerun the reproduction steps from `repro.md` exactly. Capture the output.",
354
- "Exercise one neighbouring path through each caller `repro.md` listed. Capture the output.",
362
+ `Exercise one neighbouring path through each caller \`repro.md\` listed. Capture the output. ${EXERCISE_WORKAROUND}`,
355
363
  `Write \`output/exercise.md\`: steps 2–3 as ${exerciseFormat("detail")}.`,
356
364
  // SW-579: the review step rewrites exercise.md, so recorded MANUAL results come first.
357
365
  MANUAL_STEP,
358
- reviewStep("rerun the test command exactly as `../../.werkmeister/werkmeister-context.md` states it (through `.werkmeister/bin/with-temp-home`), rerun steps 2–3 and update `exercise.md`", v.group),
366
+ // SW-678: these edits come after the fix stage's gate; one service's test command missed docs-site's (sw-631, sw-669).
367
+ reviewStep("rerun `werkmeister pr gate --tests` (from the workspace, detached when it may pass 10 minutes), not one service's test command: it retests every service the diff touches, and these edits come after the fix stage's gate. Then rerun steps 2–3 and update `exercise.md`", v.group),
359
368
  ],
360
369
  outputs: [
361
370
  "`output/exercise.md`",
@@ -420,7 +429,7 @@ const refactor = [
420
429
  implementReview(v),
421
430
  GATE_STEP,
422
431
  REVIEW_DELTA,
423
- `After the last step, reload and exercise the service: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${NO_SERVICE_RULE}`,
432
+ `After the last step, reload and exercise the service: ${v.restart}. ${RELOAD_RULE} ${HOSTNAME_RULE} ${NO_SERVICE_RULE} ${EXERCISE_WORKAROUND}`,
424
433
  `Write \`output/exercise.md\`: \`git diff --stat\` per repo, the test result after each step, the \`pr gate --tests\` exit code, ${SKIPPED}, and the final exercise checks as ${exerciseFormat("evidence")}.`,
425
434
  MANUAL_STEP,
426
435
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "werkmeister-core",
3
- "version": "0.89.0",
3
+ "version": "0.89.2",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "description": "werkmeister's shared library. Its public API is werkmeister-core/sdk; every other entry point is internal.",