@memnexus-ai/mx-agent-cli 0.1.229 → 0.1.231

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 (74) hide show
  1. package/dist/__tests__/agent-attribution.test.js +7 -5
  2. package/dist/__tests__/agent-attribution.test.js.map +1 -1
  3. package/dist/__tests__/doctor.test.d.ts +20 -0
  4. package/dist/__tests__/doctor.test.d.ts.map +1 -0
  5. package/dist/__tests__/doctor.test.js +849 -0
  6. package/dist/__tests__/doctor.test.js.map +1 -0
  7. package/dist/__tests__/fleet-data.test.d.ts +2 -0
  8. package/dist/__tests__/fleet-data.test.d.ts.map +1 -0
  9. package/dist/__tests__/fleet-data.test.js +340 -0
  10. package/dist/__tests__/fleet-data.test.js.map +1 -0
  11. package/dist/__tests__/fleet-tmux.test.d.ts +2 -0
  12. package/dist/__tests__/fleet-tmux.test.d.ts.map +1 -0
  13. package/dist/__tests__/fleet-tmux.test.js +242 -0
  14. package/dist/__tests__/fleet-tmux.test.js.map +1 -0
  15. package/dist/__tests__/project-config.test.js +37 -0
  16. package/dist/__tests__/project-config.test.js.map +1 -1
  17. package/dist/__tests__/session-model.test.d.ts +2 -0
  18. package/dist/__tests__/session-model.test.d.ts.map +1 -0
  19. package/dist/__tests__/session-model.test.js +71 -0
  20. package/dist/__tests__/session-model.test.js.map +1 -0
  21. package/dist/__tests__/worker-cap.test.d.ts +14 -0
  22. package/dist/__tests__/worker-cap.test.d.ts.map +1 -0
  23. package/dist/__tests__/worker-cap.test.js +97 -0
  24. package/dist/__tests__/worker-cap.test.js.map +1 -0
  25. package/dist/agent-config/agents/implementation-engineer.md +8 -0
  26. package/dist/agent-config/agents/qa-tester.md +13 -5
  27. package/dist/agent-config/skills/mx-pre-pr-check/SKILL.md +4 -0
  28. package/dist/commands/doctor.d.ts +203 -0
  29. package/dist/commands/doctor.d.ts.map +1 -0
  30. package/dist/commands/doctor.js +688 -0
  31. package/dist/commands/doctor.js.map +1 -0
  32. package/dist/commands/fleet-tmux.d.ts +68 -0
  33. package/dist/commands/fleet-tmux.d.ts.map +1 -0
  34. package/dist/commands/fleet-tmux.js +288 -0
  35. package/dist/commands/fleet-tmux.js.map +1 -0
  36. package/dist/commands/start.d.ts.map +1 -1
  37. package/dist/commands/start.js +41 -0
  38. package/dist/commands/start.js.map +1 -1
  39. package/dist/index.d.ts +1 -0
  40. package/dist/index.d.ts.map +1 -1
  41. package/dist/index.js +87 -0
  42. package/dist/index.js.map +1 -1
  43. package/dist/lib/agent-session.d.ts +5 -0
  44. package/dist/lib/agent-session.d.ts.map +1 -1
  45. package/dist/lib/agent-session.js +3 -1
  46. package/dist/lib/agent-session.js.map +1 -1
  47. package/dist/lib/claude.d.ts +5 -0
  48. package/dist/lib/claude.d.ts.map +1 -1
  49. package/dist/lib/claude.js +3 -1
  50. package/dist/lib/claude.js.map +1 -1
  51. package/dist/lib/fleet-data.d.ts +181 -0
  52. package/dist/lib/fleet-data.d.ts.map +1 -0
  53. package/dist/lib/fleet-data.js +375 -0
  54. package/dist/lib/fleet-data.js.map +1 -0
  55. package/dist/lib/fleet-render.d.ts +66 -0
  56. package/dist/lib/fleet-render.d.ts.map +1 -0
  57. package/dist/lib/fleet-render.js +184 -0
  58. package/dist/lib/fleet-render.js.map +1 -0
  59. package/dist/lib/jsonl.d.ts.map +1 -1
  60. package/dist/lib/jsonl.js +7 -3
  61. package/dist/lib/jsonl.js.map +1 -1
  62. package/dist/lib/project-config.d.ts +13 -0
  63. package/dist/lib/project-config.d.ts.map +1 -1
  64. package/dist/lib/project-config.js +29 -1
  65. package/dist/lib/project-config.js.map +1 -1
  66. package/dist/lib/tmux.d.ts +69 -0
  67. package/dist/lib/tmux.d.ts.map +1 -0
  68. package/dist/lib/tmux.js +115 -0
  69. package/dist/lib/tmux.js.map +1 -0
  70. package/dist/lib/vm-health.d.ts +562 -0
  71. package/dist/lib/vm-health.d.ts.map +1 -0
  72. package/dist/lib/vm-health.js +960 -0
  73. package/dist/lib/vm-health.js.map +1 -0
  74. package/package.json +1 -1
@@ -0,0 +1,203 @@
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 { type DoctorCheck, type DoctorReading, type Regression } from '../lib/vm-health.js';
76
+ /**
77
+ * Which path is running the checks.
78
+ *
79
+ * 'interactive' — a human typed `mx-agent doctor`. Everything runs.
80
+ * 'startup' — the automatic session-start check. Checks that touch a REAL
81
+ * filesystem are skipped. See checkDisk for why.
82
+ */
83
+ export type DoctorRunMode = 'interactive' | 'startup';
84
+ export interface DoctorOptions {
85
+ /**
86
+ * REQUIRED, deliberately — there is no default.
87
+ *
88
+ * A default of 'interactive' would mean a future caller wired into a
89
+ * startup-like path who forgets to pass 'startup' silently inherits the
90
+ * unbounded `statfsSync`. That is a default that fails toward the hazard, and
91
+ * it fails silently. Making this required moves the decision to compile time:
92
+ * every call site has to state which risk budget it is spending.
93
+ */
94
+ mode: DoctorRunMode;
95
+ /** Print every check with its current number, run the expensive scans. */
96
+ verbose?: boolean;
97
+ /** Machine-readable output. Implies verbose data collection. */
98
+ json?: boolean;
99
+ /** Override the last-reading cache path (test seam). */
100
+ readingPath?: string;
101
+ }
102
+ export interface AgentFootprint {
103
+ sessions: number;
104
+ totalRssKb: number;
105
+ peakRssKb: number;
106
+ projectedKb: number;
107
+ reclaimableKb: number;
108
+ }
109
+ /**
110
+ * Compute the RAM headroom assessment from measured inputs. Pure so the formula
111
+ * is unit-tested rather than only exercised against live state.
112
+ *
113
+ * projected = peak observed session RSS x session count. If every running
114
+ * session grew to the size of the largest one now running — which is
115
+ * what the 2026-07-24 post-mortem describes, with node processes
116
+ * reaching ~1.3 GB anon-rss each — this is the footprint.
117
+ * reclaimable = MemAvailable + the RSS the sessions already hold. That is the
118
+ * memory the box could give those sessions without swapping.
119
+ * WARN when projected > reclaimable.
120
+ *
121
+ * KNOWN LIMITATION, stated so a quiet check is not mistaken for a healthy box:
122
+ * because the projection is peak x count, it stays quiet when every session is
123
+ * ALREADY at the peak — there is no projected growth left to warn about. This
124
+ * check detects a fleet about to grow into trouble, not a box already in it.
125
+ * Checks 1-3 (swap sizing, swap occupancy, OOM kills) cover the already-in-it
126
+ * case.
127
+ */
128
+ export declare function assessAgentFootprint(sessionRssKb: number[], memAvailableKb: number): AgentFootprint;
129
+ export interface DoctorResult {
130
+ timestamp: string;
131
+ checks: DoctorCheck[];
132
+ regressions: Regression[];
133
+ reading: DoctorReading;
134
+ previous: DoctorReading | null;
135
+ /** True when the host-side remedy applies to what we measured. */
136
+ remedyApplies: boolean;
137
+ }
138
+ /**
139
+ * Run every check and assemble the result. Exported so tests and future callers
140
+ * can consume the structured result without going through the renderer.
141
+ */
142
+ export declare function collectDoctorResult(options: DoctorOptions): DoctorResult;
143
+ /**
144
+ * How often the session-start check may actually measure. One hour.
145
+ *
146
+ * The monitor check next to it in start.ts uses 6 hours, but that one calls a
147
+ * remote API; this one is local and costs single-digit milliseconds, and the
148
+ * thing it watches — memory pressure during a busy fleet window — moves on a
149
+ * much shorter timescale than fleet-wide autonomy trends. One hour keeps the
150
+ * delta baseline recent enough to attribute a regression to something that
151
+ * happened this session, while still meaning that nine teams starting sessions
152
+ * in the same window measure roughly once between them, not nine times.
153
+ */
154
+ export declare const STARTUP_DOCTOR_INTERVAL_MS: number;
155
+ /**
156
+ * Whether the session-start check should measure this time.
157
+ *
158
+ * The rate limit reads the last reading's own timestamp rather than keeping a
159
+ * separate stamp file, so a manual `mx-agent doctor` also satisfies it — if
160
+ * someone measured five minutes ago, session start has nothing to add. The
161
+ * limit is GLOBAL, not per-worktree, because the thing being measured is the
162
+ * VM: nine worktrees share one kernel, one swap file, and one OOM counter.
163
+ *
164
+ * KNOWN LIMITATION — THE AUTOMATIC PATH IS BLIND TO PRE-EXISTING BAD STATE.
165
+ * It reports only what CHANGED since the last reading, so a box that is ALREADY
166
+ * bad before the first-ever measurement produces silence. The first session
167
+ * after this ships, and any session following a quiet period, can start with OOM
168
+ * kills non-zero and VS Code already evicted and see nothing — which is exactly
169
+ * the 2026-07-24 situation, when nobody thought to check. Do not read "no VM
170
+ * health output" as "the machine is healthy."
171
+ *
172
+ * The manual path does not have this hole: `mx-agent doctor` prints the swap and
173
+ * OOM checks on their current values, not on a delta, so a human running it
174
+ * during the 2026-07-24 freeze would have had the diagnosis in about 10 ms
175
+ * instead of two days. The automatic path narrows to regressions on purpose —
176
+ * printing current state at every session start is the alarm fatigue this design
177
+ * removes — and this is the cost of that choice, recorded rather than hidden.
178
+ */
179
+ export declare function shouldRunStartupDoctorCheck(now?: number, path?: string): boolean;
180
+ /**
181
+ * Render a regression for the SESSION-START transcript.
182
+ *
183
+ * DEFENCE IN DEPTH — deliberately does not use `Regression.message`. That string
184
+ * is composed with values from the delta store, and this text is printed into an
185
+ * LLM's context in every agent session on every team. loadLastReading's
186
+ * validation already makes a hostile store unable to produce arbitrary text, and
187
+ * that alone is judged sufficient; this is the second layer, so that NO
188
+ * store-derived string reaches the transcript at all. Everything below comes
189
+ * from either a fixed label table or a number: `metric` is set by
190
+ * detectRegressions from a closed union, and both values are validated finite
191
+ * non-negative numbers rendered by JavaScript's own number formatting.
192
+ *
193
+ * The interactive `mx-agent doctor` output still uses the richer `message` — a
194
+ * human at a terminal chose to run it, and that is a different trust context
195
+ * from text injected into every session.
196
+ */
197
+ export declare function formatRegressionForTranscript(r: Regression): string;
198
+ export declare function runStartupDoctorCheck(options?: {
199
+ now?: number;
200
+ readingPath?: string;
201
+ }): Regression[];
202
+ export declare function runDoctor(options: DoctorOptions): void;
203
+ //# sourceMappingURL=doctor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAGH,OAAO,EA4BL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2MD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EAAE,EACtB,cAAc,EAAE,MAAM,GACrB,cAAc,CAWhB;AA+MD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CA0CxE;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,SAAa,EAAE,IAAI,SAAsB,GAAG,OAAO,CAWjG;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAEnE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,EAAE,CAQxG;AAoBD,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAkDtD"}