@memnexus-ai/mx-agent-cli 0.1.230 → 0.1.232

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 (52) hide show
  1. package/dist/__tests__/doctor.test.d.ts +20 -0
  2. package/dist/__tests__/doctor.test.d.ts.map +1 -0
  3. package/dist/__tests__/doctor.test.js +849 -0
  4. package/dist/__tests__/doctor.test.js.map +1 -0
  5. package/dist/__tests__/fleet-data.test.d.ts +2 -0
  6. package/dist/__tests__/fleet-data.test.d.ts.map +1 -0
  7. package/dist/__tests__/fleet-data.test.js +340 -0
  8. package/dist/__tests__/fleet-data.test.js.map +1 -0
  9. package/dist/__tests__/fleet-tmux.test.d.ts +2 -0
  10. package/dist/__tests__/fleet-tmux.test.d.ts.map +1 -0
  11. package/dist/__tests__/fleet-tmux.test.js +242 -0
  12. package/dist/__tests__/fleet-tmux.test.js.map +1 -0
  13. package/dist/__tests__/worker-cap.test.d.ts +14 -0
  14. package/dist/__tests__/worker-cap.test.d.ts.map +1 -0
  15. package/dist/__tests__/worker-cap.test.js +97 -0
  16. package/dist/__tests__/worker-cap.test.js.map +1 -0
  17. package/dist/agent-config/agents/implementation-engineer.md +8 -0
  18. package/dist/agent-config/agents/qa-tester.md +13 -5
  19. package/dist/agent-config/shared/eval-tiered-rigor.md +4 -2
  20. package/dist/agent-config/skills/mx-pre-pr-check/SKILL.md +4 -0
  21. package/dist/commands/doctor.d.ts +203 -0
  22. package/dist/commands/doctor.d.ts.map +1 -0
  23. package/dist/commands/doctor.js +688 -0
  24. package/dist/commands/doctor.js.map +1 -0
  25. package/dist/commands/fleet-tmux.d.ts +68 -0
  26. package/dist/commands/fleet-tmux.d.ts.map +1 -0
  27. package/dist/commands/fleet-tmux.js +288 -0
  28. package/dist/commands/fleet-tmux.js.map +1 -0
  29. package/dist/commands/start.d.ts.map +1 -1
  30. package/dist/commands/start.js +36 -0
  31. package/dist/commands/start.js.map +1 -1
  32. package/dist/index.d.ts +1 -0
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +87 -0
  35. package/dist/index.js.map +1 -1
  36. package/dist/lib/fleet-data.d.ts +181 -0
  37. package/dist/lib/fleet-data.d.ts.map +1 -0
  38. package/dist/lib/fleet-data.js +375 -0
  39. package/dist/lib/fleet-data.js.map +1 -0
  40. package/dist/lib/fleet-render.d.ts +66 -0
  41. package/dist/lib/fleet-render.d.ts.map +1 -0
  42. package/dist/lib/fleet-render.js +184 -0
  43. package/dist/lib/fleet-render.js.map +1 -0
  44. package/dist/lib/tmux.d.ts +69 -0
  45. package/dist/lib/tmux.d.ts.map +1 -0
  46. package/dist/lib/tmux.js +115 -0
  47. package/dist/lib/tmux.js.map +1 -0
  48. package/dist/lib/vm-health.d.ts +562 -0
  49. package/dist/lib/vm-health.d.ts.map +1 -0
  50. package/dist/lib/vm-health.js +960 -0
  51. package/dist/lib/vm-health.js.map +1 -0
  52. package/package.json +1 -1
@@ -0,0 +1,688 @@
1
+ /**
2
+ * mx-agent doctor [--verbose] [--json]
3
+ *
4
+ * Measures the VM's performance state and names the host-side remedy when the
5
+ * condition that froze the product owner's editor on 2026-07-24 is present
6
+ * (#4498). Read-only: it reads /proc, /sys and statfs, and writes exactly one
7
+ * file — the last-reading cache under ~/.mx-agent/doctor-last-reading/.
8
+ *
9
+ * ADVISORY ONLY — THE EXIT CODE IS ALWAYS 0.
10
+ * Do not put this command in an `&&` chain, a CI gate, or a startup blocker. The
11
+ * failure it detects is host-side and cannot be fixed from inside the container,
12
+ * so a non-zero exit would be permanently red on every machine that has not
13
+ * applied the host fix. Everyone would learn to ignore it — which is the exact
14
+ * failure mode this command exists to prevent (nobody checked anything on
15
+ * 2026-07-24 until the editor had been frozen for two days).
16
+ *
17
+ * DELTA-BASED BY DEFAULT.
18
+ * Steady state is quiet. The command is loud only when a measured number has
19
+ * WORSENED since the previous run (OOM kills, swap in use, swap size, agent
20
+ * session count). `--verbose` prints every check and its current number
21
+ * regardless of delta, for when someone is actively debugging.
22
+ *
23
+ * CHEAP BY DEFAULT.
24
+ * The default path is single reads of /proc/meminfo, /proc/vmstat, /proc/uptime,
25
+ * one cgroup read, two statfs calls, and two bounded `pgrep` execs. It does NOT
26
+ * walk /proc/<pid>/* across hundreds of PIDs — that allocates under exactly the
27
+ * memory pressure being measured. The full per-process scan (capped to the top N
28
+ * by RSS) and the inotify fd walk run only under --verbose.
29
+ *
30
+ * MEASURED COST, and the basis matters — two honest numbers differ by 3x.
31
+ * In-process (one collectDoctorResult call, median of 10, excluding Node
32
+ * startup): startup mode 15.7 ms, interactive 15.6 ms, verbose 54.2 ms.
33
+ * Full CLI invocation (`node dist/index.js doctor`, wall clock, INCLUDING the
34
+ * ~130 ms of Node process startup a session pays anyway): default 148 ms,
35
+ * verbose 187 ms. Quote the in-process figure when reasoning about what the
36
+ * session-start path adds, since that path runs inside an existing process.
37
+ *
38
+ * TWO PATHS, TWO RISK BUDGETS.
39
+ * `mode: 'interactive'` (a human ran the command) runs everything.
40
+ * `mode: 'startup'` (the automatic session-start check) additionally skips the
41
+ * disk check, because `statfsSync` touches a REAL filesystem and, unlike
42
+ * `execFileSync`, cannot be given a timeout or cancelled from the calling
43
+ * thread. A diagnostic must never be able to hang a session; see checkDisk.
44
+ *
45
+ * RESIDUAL EXPOSURE — READ THIS BEFORE TRUSTING THE PARAGRAPH ABOVE.
46
+ * Skipping the disk check does NOT make the startup path free of real-filesystem
47
+ * I/O. The delta store lives at `~/.mx-agent/doctor-last-reading/`, and
48
+ * `~/.mx-agent` is a NAMED ext4 DOCKER VOLUME (`memnexus-mx-agent-config`,
49
+ * declared in .devcontainer/devcontainer.json) — not part of the container's
50
+ * overlay, and on a different device from the workspace. Verified with `df -T`,
51
+ * `findmnt` and `docker ps --filter volume=` on 2026-07-25:
52
+ * `~/.mx-agent` is /dev/sdd ext4, `$HOME` itself is overlay, `/workspace` is
53
+ * /dev/sdc ext4. `loadLastReading` and `saveReading` touch that volume on every
54
+ * startup run, and neither can be given a timeout, exactly like `statfsSync`.
55
+ * The store cannot simply be dropped from the startup path: it IS the delta
56
+ * mechanism.
57
+ *
58
+ * What has been closed is the FIFO/TOCTOU case (loadLastReading now validates an
59
+ * open descriptor, with O_NONBLOCK). What remains open is a genuinely STALLED
60
+ * MOUNT: if the volume backing `~/.mx-agent` hangs, the startup check hangs with
61
+ * it, and no fail-open layer helps because a process blocked in a kernel syscall
62
+ * never throws. That is a smaller exposure than the disk check was — one small
63
+ * file on a Docker volume, versus statfs on the workspace mount — but it is not
64
+ * zero.
65
+ *
66
+ * On the trust boundary in vm-health.ts's header: the store is not on the
67
+ * container's own overlay, it is on a named volume that OUTLIVES the container
68
+ * and that any container declaring the same mount would share. As checked on
69
+ * 2026-07-25, exactly one container currently mounts it — so treat "another
70
+ * container has written here" as possible, not as observed.
71
+ *
72
+ * Two earlier versions of this comment stated a checkable fact about this path
73
+ * without checking it. Re-run those three commands before editing these lines.
74
+ */
75
+ import chalk from 'chalk';
76
+ import { MAX_BOUNDED_PIDS, RECOMMENDED_SWAP_KB, REMEDY_DOC_PATH, SWAPPINESS_REMEDY, SWAP_DRAIN_CAVEAT, SWAP_DRAIN_COMMAND, WSLCONFIG_REMEDY, boundPids, collectCgroupMemoryLimit, collectDisk, collectDmesg, collectInotifyCaps, collectInotifyUsage, collectMeminfo, collectProcesses, collectProcessesByPid, collectUptimeSeconds, collectVmstat, describeOomEventTime, detectRegressions, doctorReadingPath, formatBytes, formatKb, loadLastReading, parseOomEvents, pgrepPids, saveReading, } from '../lib/vm-health.js';
77
+ /** WARN when either inotify counter exceeds this share of its cap. */
78
+ const INOTIFY_WARN_FRACTION = 0.5;
79
+ /** WARN when a filesystem has less than this share free. */
80
+ const DISK_WARN_FRACTION = 0.1;
81
+ /** Cap on the verbose per-process scan. */
82
+ const VERBOSE_PROCESS_LIMIT = 15;
83
+ // ── Individual checks ───────────────────────────────────────────────────────
84
+ /**
85
+ * Check 1 — swap sizing. The 2026-07-24 condition, per that incident's
86
+ * post-mortem: 8 GiB of swap present, driven to SwapFree=0 by thrashing agent
87
+ * sessions, with VS Code evicted into it.
88
+ *
89
+ * Verdicts follow the shipped recommendation (dev-tools/wsl), not "swap is bad":
90
+ * SwapTotal = 0 → WARN. No pressure-relief buffer at all; the kernel
91
+ * goes straight to OOM kills, which lose unsaved
92
+ * agent work.
93
+ * SwapTotal > 4 GiB → FAIL. Oversized: large enough to host a long
94
+ * thrash, which is what happened on 2026-07-24.
95
+ * 0 < SwapTotal <= 4 GiB → OK.
96
+ */
97
+ function checkSwapSizing(mem, memError) {
98
+ if (!mem) {
99
+ return unavailable('swap-sizing', 'Swap sizing', `/proc/meminfo unreadable: ${memError ?? 'unknown error'}`);
100
+ }
101
+ const total = mem.SwapTotal ?? 0;
102
+ const free = mem.SwapFree ?? 0;
103
+ const used = total - free;
104
+ const memAvailable = mem.MemAvailable ?? 0;
105
+ let verdict;
106
+ let note;
107
+ if (total === 0) {
108
+ verdict = 'WARN';
109
+ note = 'no swap configured — the kernel has no pressure-relief buffer and will OOM-kill sooner';
110
+ }
111
+ else if (total > RECOMMENDED_SWAP_KB) {
112
+ verdict = 'FAIL';
113
+ note = `larger than the recommended ${formatKb(RECOMMENDED_SWAP_KB)} — big enough to sustain a thrash (the 2026-07-24 condition)`;
114
+ }
115
+ else {
116
+ verdict = 'OK';
117
+ note = `within the recommended ${formatKb(RECOMMENDED_SWAP_KB)}`;
118
+ }
119
+ return {
120
+ id: 'swap-sizing',
121
+ title: 'Swap sizing',
122
+ verdict,
123
+ detail: `SwapTotal ${formatKb(total)}, ${formatKb(used)} in use, MemAvailable ${formatKb(memAvailable)} — ${note}`,
124
+ metrics: { swapTotalKb: total, swapFreeKb: free, swapUsedKb: used, memAvailableKb: memAvailable, recommendedSwapKb: RECOMMENDED_SWAP_KB },
125
+ };
126
+ }
127
+ /**
128
+ * Check 2 — what is actually sitting in swap right now, with the VS Code server
129
+ * family called out by name. That family is the one whose eviction the product
130
+ * owner feels directly as keystroke lag, and Linux will not page it back in
131
+ * proactively once it is out.
132
+ *
133
+ * The per-process part is bounded: PIDs come from a single `pgrep -f
134
+ * vscode-server` exec (typically 4 processes), not a walk of /proc.
135
+ */
136
+ function checkSwapOccupancy(mem, vmstat, verbose) {
137
+ if (!mem)
138
+ return unavailable('swap-occupancy', 'Processes in swap', '/proc/meminfo unreadable');
139
+ const swapUsedKb = (mem.SwapTotal ?? 0) - (mem.SwapFree ?? 0);
140
+ const pswpout = vmstat?.pswpout ?? null;
141
+ const pswpin = vmstat?.pswpin ?? null;
142
+ const pids = pgrepPids(['-f', 'vscode-server']);
143
+ const extra = [];
144
+ let vscodeSwapKb = 0;
145
+ let vscodeInSwap = 0;
146
+ let vscodeMeasured = null;
147
+ if (pids.value) {
148
+ // ENFORCED bound, not an assumed one: this check is not verbose-gated, so it
149
+ // runs at every session start on every team. See MAX_BOUNDED_PIDS.
150
+ const bounded = boundPids(pids.value);
151
+ if (bounded.dropped > 0) {
152
+ extra.push(`${pids.value.length} processes matched 'vscode-server'; only the first ${bounded.pids.length} were read (bound: ${MAX_BOUNDED_PIDS}). An unusually high count is itself worth investigating.`);
153
+ }
154
+ const samples = collectProcessesByPid(bounded.pids);
155
+ vscodeMeasured = samples.length;
156
+ for (const s of samples.sort((a, b) => (b.vmSwapKb ?? 0) - (a.vmSwapKb ?? 0))) {
157
+ const swap = s.vmSwapKb ?? 0;
158
+ if (swap > 0) {
159
+ vscodeInSwap++;
160
+ vscodeSwapKb += swap;
161
+ extra.push(`${s.vscode ?? s.name} (pid ${s.pid}): ${formatKb(swap)} swapped, ${formatKb(s.vmRssKb ?? 0)} resident`);
162
+ }
163
+ else {
164
+ extra.push(`${s.vscode ?? s.name} (pid ${s.pid}): 0 kB swapped, ${formatKb(s.vmRssKb ?? 0)} resident`);
165
+ }
166
+ }
167
+ }
168
+ else {
169
+ extra.push(`VS Code process lookup unavailable: ${pids.error ?? 'pgrep failed'}`);
170
+ }
171
+ // Full per-process scan — verbose only, capped to the top N by RSS. On the
172
+ // default path this is skipped entirely: walking /proc/<pid>/status across
173
+ // hundreds of PIDs allocates under the memory pressure being measured.
174
+ if (verbose) {
175
+ const all = collectProcesses(VERBOSE_PROCESS_LIMIT);
176
+ if (!all.value) {
177
+ extra.push(`top-process scan unavailable: ${all.error ?? 'unknown error'}`);
178
+ }
179
+ else {
180
+ extra.push(`Top ${all.value.length} processes by RSS:`);
181
+ for (const s of all.value) {
182
+ extra.push(` ${s.name} (pid ${s.pid}): ${formatKb(s.vmRssKb ?? 0)} resident, ${formatKb(s.vmSwapKb ?? 0)} swapped`);
183
+ }
184
+ }
185
+ }
186
+ const verdict = vscodeInSwap > 0 ? 'WARN' : swapUsedKb > 0 ? 'WARN' : 'OK';
187
+ const swapActivity = pswpout === null
188
+ ? 'swap page counters unavailable (/proc/vmstat unreadable)'
189
+ : `${pswpin} pages swapped in / ${pswpout} out since boot`;
190
+ const headline = vscodeInSwap > 0
191
+ ? `${vscodeInSwap} VS Code server process(es) hold ${formatKb(vscodeSwapKb)} in swap — this is what keystroke lag feels like`
192
+ : `no VS Code server process is in swap (${vscodeMeasured ?? 0} measured)`;
193
+ return {
194
+ id: 'swap-occupancy',
195
+ title: 'Processes in swap',
196
+ verdict,
197
+ detail: `${formatKb(swapUsedKb)} of swap in use; ${headline}; ${swapActivity}`,
198
+ extra,
199
+ metrics: {
200
+ swapUsedKb,
201
+ vscodeProcessesMeasured: vscodeMeasured,
202
+ vscodeProcessesInSwap: vscodeInSwap,
203
+ vscodeSwapKb,
204
+ pswpin,
205
+ pswpout,
206
+ },
207
+ };
208
+ }
209
+ /**
210
+ * Check 3 — OOM kills since boot. The number comes from /proc/vmstat `oom_kill`,
211
+ * which is exact, costs one read, and needs no permissions. dmesg is consulted
212
+ * only under --verbose, purely to attach timestamps and victim names; it can
213
+ * fail with EPERM when dmesg_restrict is set, and it is a ring buffer that can
214
+ * have wrapped, so it is never the source of the count.
215
+ */
216
+ function checkOomKills(vmstat, uptimeSeconds, verbose) {
217
+ if (!vmstat || typeof vmstat.oom_kill !== 'number') {
218
+ return unavailable('oom-kills', 'OOM kills since boot', '/proc/vmstat has no oom_kill counter on this kernel');
219
+ }
220
+ const count = vmstat.oom_kill;
221
+ const extra = [];
222
+ if (verbose) {
223
+ const dmesg = collectDmesg();
224
+ if (!dmesg.value) {
225
+ extra.push(`dmesg unavailable (timestamps and victim names cannot be shown): ${dmesg.error ?? 'unknown error'}`);
226
+ }
227
+ else {
228
+ const events = parseOomEvents(dmesg.value).filter((e) => e.kind === 'kill');
229
+ if (events.length === 0) {
230
+ extra.push(count > 0
231
+ ? `the counter reports ${count} kill(s) but the dmesg ring buffer holds no OOM lines — it has wrapped, so timestamps and victims are lost`
232
+ : 'dmesg ring buffer holds no OOM lines, consistent with the counter');
233
+ }
234
+ else if (events.length !== count) {
235
+ extra.push(`dmesg shows ${events.length} kill line(s) against a counter of ${count} — the ring buffer has partially wrapped.`);
236
+ }
237
+ for (const e of events.slice(-10)) {
238
+ const when = describeOomEventTime(e, uptimeSeconds, Date.now());
239
+ const size = e.anonRssKb === null ? 'size not reported' : `${formatKb(e.anonRssKb)} anon-rss`;
240
+ extra.push(`${when} — killed ${e.process ?? 'unknown'} (pid ${e.pid ?? '?'}), ${size}`);
241
+ }
242
+ }
243
+ }
244
+ return {
245
+ id: 'oom-kills',
246
+ title: 'OOM kills since boot',
247
+ verdict: count > 0 ? 'FAIL' : 'OK',
248
+ detail: count > 0
249
+ ? `${count} OOM kill(s) since boot (/proc/vmstat oom_kill)`
250
+ : '0 OOM kills since boot (/proc/vmstat oom_kill)',
251
+ extra,
252
+ metrics: { oomKills: count },
253
+ };
254
+ }
255
+ /**
256
+ * Compute the RAM headroom assessment from measured inputs. Pure so the formula
257
+ * is unit-tested rather than only exercised against live state.
258
+ *
259
+ * projected = peak observed session RSS x session count. If every running
260
+ * session grew to the size of the largest one now running — which is
261
+ * what the 2026-07-24 post-mortem describes, with node processes
262
+ * reaching ~1.3 GB anon-rss each — this is the footprint.
263
+ * reclaimable = MemAvailable + the RSS the sessions already hold. That is the
264
+ * memory the box could give those sessions without swapping.
265
+ * WARN when projected > reclaimable.
266
+ *
267
+ * KNOWN LIMITATION, stated so a quiet check is not mistaken for a healthy box:
268
+ * because the projection is peak x count, it stays quiet when every session is
269
+ * ALREADY at the peak — there is no projected growth left to warn about. This
270
+ * check detects a fleet about to grow into trouble, not a box already in it.
271
+ * Checks 1-3 (swap sizing, swap occupancy, OOM kills) cover the already-in-it
272
+ * case.
273
+ */
274
+ export function assessAgentFootprint(sessionRssKb, memAvailableKb) {
275
+ const sessions = sessionRssKb.length;
276
+ const totalRssKb = sessionRssKb.reduce((a, b) => a + b, 0);
277
+ const peakRssKb = sessions === 0 ? 0 : Math.max(...sessionRssKb);
278
+ return {
279
+ sessions,
280
+ totalRssKb,
281
+ peakRssKb,
282
+ projectedKb: peakRssKb * sessions,
283
+ reclaimableKb: memAvailableKb + totalRssKb,
284
+ };
285
+ }
286
+ /** Check 4 — RAM headroom versus the agent sessions actually running. */
287
+ function checkRamHeadroom(mem) {
288
+ if (!mem)
289
+ return { check: unavailable('ram-headroom', 'RAM headroom vs agent sessions', '/proc/meminfo unreadable'), sessions: null };
290
+ const pids = pgrepPids(['-x', 'claude']);
291
+ if (!pids.value) {
292
+ return {
293
+ check: unavailable('ram-headroom', 'RAM headroom vs agent sessions', `agent session lookup failed: ${pids.error ?? 'pgrep failed'}`),
294
+ sessions: null,
295
+ };
296
+ }
297
+ // Same enforced bound as checkSwapOccupancy — `pgrep -x claude` is equally
298
+ // spoofable by any local process choosing that name.
299
+ const bounded = boundPids(pids.value);
300
+ const samples = collectProcessesByPid(bounded.pids);
301
+ const rss = samples.map((s) => s.vmRssKb ?? 0);
302
+ const f = assessAgentFootprint(rss, mem.MemAvailable ?? 0);
303
+ const warn = f.sessions > 0 && f.projectedKb > f.reclaimableKb;
304
+ return {
305
+ sessions: f.sessions,
306
+ check: {
307
+ id: 'ram-headroom',
308
+ title: 'RAM headroom vs agent sessions',
309
+ verdict: warn ? 'WARN' : 'OK',
310
+ detail: f.sessions === 0
311
+ ? `0 agent sessions running; MemAvailable ${formatKb(mem.MemAvailable ?? 0)}`
312
+ : `${f.sessions} agent session(s) holding ${formatKb(f.totalRssKb)} (largest ${formatKb(f.peakRssKb)}); if all reached the largest they would need ${formatKb(f.projectedKb)} against ${formatKb(f.reclaimableKb)} reclaimable`,
313
+ extra: [
314
+ ...(bounded.dropped > 0
315
+ ? [`${pids.value.length} processes matched 'claude'; only the first ${bounded.pids.length} were read (bound: ${MAX_BOUNDED_PIDS}).`]
316
+ : []),
317
+ ...samples.map((s) => `pid ${s.pid}: ${formatKb(s.vmRssKb ?? 0)} resident, ${formatKb(s.vmSwapKb ?? 0)} swapped`),
318
+ ],
319
+ metrics: {
320
+ sessions: f.sessions,
321
+ totalRssKb: f.totalRssKb,
322
+ peakRssKb: f.peakRssKb,
323
+ projectedKb: f.projectedKb,
324
+ reclaimableKb: f.reclaimableKb,
325
+ memAvailableKb: mem.MemAvailable ?? 0,
326
+ },
327
+ },
328
+ };
329
+ }
330
+ /**
331
+ * Check 5 — inotify usage against the caps. Regression guard for PR #4475 (the
332
+ * `.worktrees` watcher storm). The live count requires a readdir of every
333
+ * /proc/<pid>/fd — there is no aggregate counter in /proc — so the default path
334
+ * reports the caps only and the walk runs under --verbose.
335
+ */
336
+ function checkInotify(verbose) {
337
+ const caps = collectInotifyCaps();
338
+ const capText = `caps: ${caps.maxWatches ?? 'unavailable'} watches, ${caps.maxInstances ?? 'unavailable'} instances`;
339
+ if (!verbose) {
340
+ return {
341
+ id: 'inotify',
342
+ title: 'inotify watches and instances',
343
+ verdict: 'OK',
344
+ detail: `${capText} — live usage not measured on the default path (a readdir of every /proc/<pid>/fd); run --verbose`,
345
+ metrics: { maxWatches: caps.maxWatches, maxInstances: caps.maxInstances, measured: false },
346
+ };
347
+ }
348
+ const usage = collectInotifyUsage();
349
+ if (!usage.value) {
350
+ return unavailable('inotify', 'inotify watches and instances', `/proc walk failed: ${usage.error ?? 'unknown error'}`);
351
+ }
352
+ const u = usage.value;
353
+ const watchFrac = caps.maxWatches ? u.watches / caps.maxWatches : 0;
354
+ const instFrac = caps.maxInstances ? u.instances / caps.maxInstances : 0;
355
+ const warn = watchFrac > INOTIFY_WARN_FRACTION || instFrac > INOTIFY_WARN_FRACTION;
356
+ const extra = [];
357
+ if (u.unreadableProcesses > 0) {
358
+ extra.push(`${u.unreadableProcesses} process(es) had an unreadable /proc/<pid>/fd — these counts are a lower bound.`);
359
+ }
360
+ return {
361
+ id: 'inotify',
362
+ title: 'inotify watches and instances',
363
+ verdict: warn ? 'WARN' : 'OK',
364
+ detail: `${u.watches} watches (${pct(watchFrac)} of ${caps.maxWatches ?? '?'}), ${u.instances} instances (${pct(instFrac)} of ${caps.maxInstances ?? '?'})`,
365
+ extra,
366
+ metrics: {
367
+ watches: u.watches,
368
+ instances: u.instances,
369
+ maxWatches: caps.maxWatches,
370
+ maxInstances: caps.maxInstances,
371
+ unreadableProcesses: u.unreadableProcesses,
372
+ measured: true,
373
+ },
374
+ };
375
+ }
376
+ /**
377
+ * Check 6 — free space on the workspace filesystem and root.
378
+ *
379
+ * NOT RUN ON THE SESSION-START PATH. This is the only check that touches a real
380
+ * filesystem, and `fs.statfsSync` accepts no timeout and cannot be cancelled
381
+ * from the calling thread — unlike `execFileSync`, which we do bound. On a
382
+ * workspace backed by an overlay, virtiofs or 9p mount, a stalled statfs under
383
+ * exactly the memory and I/O pressure this tool exists to diagnose would hang
384
+ * session start indefinitely, for every team. That would turn a diagnostic into
385
+ * an outage and break the invariant the whole automatic path is built on.
386
+ *
387
+ * Bounding it would mean a worker thread or an async race — real machinery added
388
+ * to a startup path to preserve a check that does not serve that path's purpose.
389
+ * The automatic path exists to catch memory pressure; disk free space is not
390
+ * that, and it is absent from the delta store, so skipping it costs the startup
391
+ * path nothing. It runs in full whenever a human invokes the command.
392
+ *
393
+ * (No hung filesystem was reproduced — this is a code-reading judgement about an
394
+ * invariant, not a fix for an observed hang.)
395
+ */
396
+ function checkDisk(mode) {
397
+ if (mode === 'startup') {
398
+ return {
399
+ id: 'disk',
400
+ title: 'Disk free',
401
+ verdict: 'UNAVAILABLE',
402
+ detail: 'not measured on the session-start path — statfs cannot be given a timeout, and a stalled filesystem must never be able to hang a session. Run `mx-agent doctor` to measure it.',
403
+ unavailableReason: 'deliberately skipped on the session-start path (unbounded synchronous statfs)',
404
+ metrics: { skipped: true },
405
+ };
406
+ }
407
+ const workspace = process.env.CLAUDE_WORKTREE_PATH || process.cwd();
408
+ const paths = Array.from(new Set([workspace, '/']));
409
+ const parts = [];
410
+ const extra = [];
411
+ const metrics = {};
412
+ let verdict = 'OK';
413
+ for (const p of paths) {
414
+ const d = collectDisk(p);
415
+ if (!d.value) {
416
+ extra.push(`${p}: unavailable (${d.error ?? 'unknown error'})`);
417
+ if (verdict === 'OK')
418
+ verdict = 'UNAVAILABLE';
419
+ continue;
420
+ }
421
+ const { freePercent, availableBytes, totalBytes } = d.value;
422
+ parts.push(`${p} ${freePercent.toFixed(1)}% free (${formatBytes(availableBytes)} of ${formatBytes(totalBytes)})`);
423
+ metrics[`${p}:freePercent`] = Number(freePercent.toFixed(2));
424
+ metrics[`${p}:availableBytes`] = availableBytes;
425
+ if (freePercent < DISK_WARN_FRACTION * 100)
426
+ verdict = 'WARN';
427
+ }
428
+ return {
429
+ id: 'disk',
430
+ title: 'Disk free',
431
+ verdict,
432
+ detail: parts.length > 0 ? parts.join('; ') : 'no filesystem could be measured',
433
+ extra,
434
+ metrics,
435
+ };
436
+ }
437
+ /** Check 7 — the container's memory cgroup cap. Reported, never a failure. */
438
+ function checkCgroupCap() {
439
+ const limit = collectCgroupMemoryLimit();
440
+ if (limit.error) {
441
+ return unavailable('cgroup-cap', 'Container memory cgroup cap', limit.error);
442
+ }
443
+ const unlimited = limit.value === null;
444
+ return {
445
+ id: 'cgroup-cap',
446
+ title: 'Container memory cgroup cap',
447
+ verdict: 'OK',
448
+ detail: unlimited
449
+ ? 'unlimited — the container can consume the whole VM, so VM-level limits are the only backstop'
450
+ : `${formatBytes(limit.value)} — the container is capped below the VM`,
451
+ metrics: { unlimited, limitBytes: limit.value },
452
+ };
453
+ }
454
+ // ── Helpers ─────────────────────────────────────────────────────────────────
455
+ function unavailable(id, title, reason) {
456
+ return { id, title, verdict: 'UNAVAILABLE', detail: `unavailable — ${reason}`, unavailableReason: reason };
457
+ }
458
+ function pct(fraction) {
459
+ return `${(fraction * 100).toFixed(1)}%`;
460
+ }
461
+ function verdictLabel(v) {
462
+ switch (v) {
463
+ case 'OK':
464
+ return chalk.green('OK ');
465
+ case 'WARN':
466
+ return chalk.yellow('WARN');
467
+ case 'FAIL':
468
+ return chalk.red('FAIL');
469
+ default:
470
+ return chalk.dim('N/A ');
471
+ }
472
+ }
473
+ /**
474
+ * Run every check and assemble the result. Exported so tests and future callers
475
+ * can consume the structured result without going through the renderer.
476
+ */
477
+ export function collectDoctorResult(options) {
478
+ const verbose = Boolean(options.verbose || options.json);
479
+ const mode = options.mode;
480
+ const readingPath = options.readingPath ?? doctorReadingPath();
481
+ const memC = collectMeminfo();
482
+ const vmstatC = collectVmstat();
483
+ const uptimeC = collectUptimeSeconds();
484
+ const mem = memC.value;
485
+ const vmstat = vmstatC.value;
486
+ const swapCheck = checkSwapSizing(mem, memC.error);
487
+ const occupancyCheck = checkSwapOccupancy(mem, vmstat, verbose);
488
+ const oomCheck = checkOomKills(vmstat, uptimeC.value, verbose);
489
+ const { check: ramCheck, sessions } = checkRamHeadroom(mem);
490
+ const inotifyCheck = checkInotify(verbose);
491
+ const diskCheck = checkDisk(mode);
492
+ const cgroupCheck = checkCgroupCap();
493
+ const checks = [swapCheck, occupancyCheck, oomCheck, ramCheck, inotifyCheck, diskCheck, cgroupCheck];
494
+ const reading = {
495
+ timestamp: new Date().toISOString(),
496
+ oomKills: typeof vmstat?.oom_kill === 'number' ? vmstat.oom_kill : 0,
497
+ swapUsedKb: mem ? (mem.SwapTotal ?? 0) - (mem.SwapFree ?? 0) : 0,
498
+ swapTotalKb: mem?.SwapTotal ?? 0,
499
+ agentSessions: sessions ?? 0,
500
+ uptimeSeconds: uptimeC.value ?? 0,
501
+ };
502
+ const previous = loadLastReading(readingPath);
503
+ const regressions = detectRegressions(previous, reading);
504
+ saveReading(reading, readingPath);
505
+ return {
506
+ timestamp: reading.timestamp,
507
+ checks,
508
+ regressions,
509
+ reading,
510
+ previous,
511
+ remedyApplies: swapCheck.verdict === 'FAIL' || oomCheck.verdict === 'FAIL',
512
+ };
513
+ }
514
+ // ── Session-start check (rate-limited, fail-open, regressions only) ─────────
515
+ /**
516
+ * How often the session-start check may actually measure. One hour.
517
+ *
518
+ * The monitor check next to it in start.ts uses 6 hours, but that one calls a
519
+ * remote API; this one is local and costs single-digit milliseconds, and the
520
+ * thing it watches — memory pressure during a busy fleet window — moves on a
521
+ * much shorter timescale than fleet-wide autonomy trends. One hour keeps the
522
+ * delta baseline recent enough to attribute a regression to something that
523
+ * happened this session, while still meaning that nine teams starting sessions
524
+ * in the same window measure roughly once between them, not nine times.
525
+ */
526
+ export const STARTUP_DOCTOR_INTERVAL_MS = 60 * 60 * 1000;
527
+ /**
528
+ * Whether the session-start check should measure this time.
529
+ *
530
+ * The rate limit reads the last reading's own timestamp rather than keeping a
531
+ * separate stamp file, so a manual `mx-agent doctor` also satisfies it — if
532
+ * someone measured five minutes ago, session start has nothing to add. The
533
+ * limit is GLOBAL, not per-worktree, because the thing being measured is the
534
+ * VM: nine worktrees share one kernel, one swap file, and one OOM counter.
535
+ *
536
+ * KNOWN LIMITATION — THE AUTOMATIC PATH IS BLIND TO PRE-EXISTING BAD STATE.
537
+ * It reports only what CHANGED since the last reading, so a box that is ALREADY
538
+ * bad before the first-ever measurement produces silence. The first session
539
+ * after this ships, and any session following a quiet period, can start with OOM
540
+ * kills non-zero and VS Code already evicted and see nothing — which is exactly
541
+ * the 2026-07-24 situation, when nobody thought to check. Do not read "no VM
542
+ * health output" as "the machine is healthy."
543
+ *
544
+ * The manual path does not have this hole: `mx-agent doctor` prints the swap and
545
+ * OOM checks on their current values, not on a delta, so a human running it
546
+ * during the 2026-07-24 freeze would have had the diagnosis in about 10 ms
547
+ * instead of two days. The automatic path narrows to regressions on purpose —
548
+ * printing current state at every session start is the alarm fatigue this design
549
+ * removes — and this is the cost of that choice, recorded rather than hidden.
550
+ */
551
+ export function shouldRunStartupDoctorCheck(now = Date.now(), path = doctorReadingPath()) {
552
+ const last = loadLastReading(path);
553
+ if (!last)
554
+ return true; // never measured, or the stored reading failed validation
555
+ const t = Date.parse(last.timestamp);
556
+ if (Number.isNaN(t))
557
+ return true; // unreadable stamp — measure
558
+ // A timestamp in the future would otherwise suppress the check until that time
559
+ // arrives. `9999-01-01T00:00:00.000Z` is a well-formed instant that passes
560
+ // loadLastReading's validation, so one write would silence this fleet-wide for
561
+ // eight thousand years. A future reading is not a reading; measure now.
562
+ if (t > now)
563
+ return true;
564
+ return now - t >= STARTUP_DOCTOR_INTERVAL_MS;
565
+ }
566
+ /**
567
+ * The session-start entry point. Returns ONLY regressions — metrics that got
568
+ * worse since the last reading — and returns [] for everything else: a clean
569
+ * box, a rate-limited run, or any failure at all.
570
+ *
571
+ * Three properties matter here, because this runs before every session on every
572
+ * team:
573
+ * SILENT WHEN CLEAN. It returns no "all OK" summary. A status block on every
574
+ * session start would cost every team tokens for a line they would learn to
575
+ * skip, rebuilding the alarm fatigue the delta design exists to remove.
576
+ * FAIL OPEN, ALWAYS. Every path is inside the catch. A diagnostic must never
577
+ * be able to stop a team from starting work.
578
+ * CHEAP. It calls collectDoctorResult with `{ readingPath, mode: 'startup' }`
579
+ * and neither `verbose` nor `json`, so `verbose` resolves to false and the
580
+ * three expensive scans it gates (the full /proc/<pid>/status walk, the
581
+ * /proc/<pid>/fd inotify walk, and dmesg) do not run. `mode: 'startup'` also
582
+ * skips the disk check — see checkDisk for why that is about hang risk, not
583
+ * cost.
584
+ */
585
+ /** Human labels for the four delta metrics. Code-derived, never store-derived. */
586
+ const REGRESSION_LABELS = {
587
+ oomKills: 'OOM kills',
588
+ swapUsedKb: 'swap in use (kB)',
589
+ swapTotalKb: 'swap size (kB)',
590
+ agentSessions: 'agent sessions',
591
+ };
592
+ /**
593
+ * Render a regression for the SESSION-START transcript.
594
+ *
595
+ * DEFENCE IN DEPTH — deliberately does not use `Regression.message`. That string
596
+ * is composed with values from the delta store, and this text is printed into an
597
+ * LLM's context in every agent session on every team. loadLastReading's
598
+ * validation already makes a hostile store unable to produce arbitrary text, and
599
+ * that alone is judged sufficient; this is the second layer, so that NO
600
+ * store-derived string reaches the transcript at all. Everything below comes
601
+ * from either a fixed label table or a number: `metric` is set by
602
+ * detectRegressions from a closed union, and both values are validated finite
603
+ * non-negative numbers rendered by JavaScript's own number formatting.
604
+ *
605
+ * The interactive `mx-agent doctor` output still uses the richer `message` — a
606
+ * human at a terminal chose to run it, and that is a different trust context
607
+ * from text injected into every session.
608
+ */
609
+ export function formatRegressionForTranscript(r) {
610
+ return `${REGRESSION_LABELS[r.metric]}: ${r.previous} -> ${r.current}`;
611
+ }
612
+ export function runStartupDoctorCheck(options = {}) {
613
+ try {
614
+ const path = options.readingPath ?? doctorReadingPath();
615
+ if (!shouldRunStartupDoctorCheck(options.now ?? Date.now(), path))
616
+ return [];
617
+ return collectDoctorResult({ readingPath: path, mode: 'startup' }).regressions;
618
+ }
619
+ catch {
620
+ return []; // fail open — never block a session
621
+ }
622
+ }
623
+ /**
624
+ * Print the host-side remedy verbatim. `changed` distinguishes "this just got
625
+ * worse" from "this is the same unfixed condition as last time" — the second
626
+ * case is printed dim so an unchanged condition does not read as an alarm.
627
+ */
628
+ function printRemedy(changed) {
629
+ console.log();
630
+ const heading = `Host remedy — %UserProfile%\\.wslconfig on the WINDOWS HOST. This container cannot reach it (/mnt/c is not mounted), so a human must apply it there.`;
631
+ console.log(changed ? chalk.yellow(heading) : chalk.dim(heading));
632
+ for (const line of WSLCONFIG_REMEDY.split('\n'))
633
+ console.log(` ${line}`);
634
+ console.log(chalk.dim(` Apply: wsl --shutdown, then restart. Also set ${SWAPPINESS_REMEDY} (see ${REMEDY_DOC_PATH}).`));
635
+ console.log(chalk.dim(` Immediate, no restart: ${SWAP_DRAIN_COMMAND}`));
636
+ // The caveat has to be HERE, not only in the README: this is the copy someone
637
+ // will paste, and the command is most dangerous exactly when it is most
638
+ // tempting.
639
+ console.log(chalk.yellow(` Warning: ${SWAP_DRAIN_CAVEAT}`));
640
+ }
641
+ export function runDoctor(options) {
642
+ const result = collectDoctorResult(options);
643
+ if (options.json) {
644
+ console.log(JSON.stringify(result, null, 2));
645
+ return;
646
+ }
647
+ const counts = { OK: 0, WARN: 0, FAIL: 0, UNAVAILABLE: 0 };
648
+ for (const c of result.checks)
649
+ counts[c.verdict]++;
650
+ console.log();
651
+ console.log(chalk.cyan.bold(`VM Doctor — measured ${result.timestamp}`));
652
+ console.log(chalk.dim('─'.repeat(58)));
653
+ // Changes since the last reading — the loud part.
654
+ if (result.regressions.length > 0) {
655
+ console.log(chalk.yellow.bold(' Worse than last check:'));
656
+ for (const r of result.regressions)
657
+ console.log(chalk.yellow(` ⚠ ${r.message}`));
658
+ }
659
+ else if (result.previous) {
660
+ console.log(chalk.dim(` No metric worsened since the last check (${result.previous.timestamp}).`));
661
+ }
662
+ else {
663
+ console.log(chalk.dim(' First run on this machine — no previous reading to compare against.'));
664
+ }
665
+ console.log();
666
+ // Checks: everything under --verbose, otherwise only what is not OK.
667
+ const shown = options.verbose ? result.checks : result.checks.filter((c) => c.verdict !== 'OK');
668
+ if (shown.length === 0) {
669
+ console.log(chalk.green(` All ${result.checks.length} checks OK.`));
670
+ }
671
+ else {
672
+ for (const c of shown) {
673
+ console.log(` ${verdictLabel(c.verdict)} ${chalk.bold(c.title)}: ${c.detail}`);
674
+ if (options.verbose)
675
+ for (const line of c.extra ?? [])
676
+ console.log(chalk.dim(` ${line}`));
677
+ }
678
+ }
679
+ if (result.remedyApplies)
680
+ printRemedy(result.regressions.length > 0);
681
+ console.log();
682
+ console.log(chalk.dim(` ${result.checks.length} checks: ${counts.OK} OK, ${counts.WARN} WARN, ${counts.FAIL} FAIL, ${counts.UNAVAILABLE} unavailable.` +
683
+ (options.verbose ? '' : ' Run --verbose for every number.')));
684
+ console.log(chalk.dim(' Advisory only: this command always exits 0. Do not use it as a gate.'));
685
+ console.log();
686
+ // Deliberately no process.exitCode assignment. See the file header.
687
+ }
688
+ //# sourceMappingURL=doctor.js.map