opencode-agent-harness 0.0.0-stage → 0.3.14

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 (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +288 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +187 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,916 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * capacity-lib — the machine-capacity envelope shared by `serve.js`,
5
+ * `check-capacity.js`, the `context-guard` plugin, and `agent-harness doctor`.
6
+ *
7
+ * Why: WSL2 is ONE Linux VM. Every agent, worktree, emulator, `next dev`, and
8
+ * gate shares its RAM/CPU/swap, and there is no per-agent cgroup limit. When the
9
+ * working set (emulator ~3 GB + agents + dev server) exceeds the VM cap, the
10
+ * kernel thrashes reclaim/swap AND starves the host<->VM vsock relay — so every
11
+ * terminal freezes at once (the 2026-09-29 freeze: 10 GB cap, 4 GB swap full,
12
+ * load 60). The root fix is policy (serialize heavy tiers, reap idle daemons),
13
+ * and the harness makes it MECHANICAL: an envelope read from the project-owned
14
+ * `.agents/memory/orchestration.md`, sampled against live `/proc` + `.serve/`
15
+ * state, with one owner of the numbers so every surface agrees.
16
+ *
17
+ * Pure-ish (fs reads only, never throws). Every path is env-overridable so the
18
+ * gate and its tests can inject synthetic host state:
19
+ * AGENT_CAPACITY_MEMINFO (default /proc/meminfo)
20
+ * AGENT_CAPACITY_LOADAVG (default /proc/loadavg)
21
+ * AGENT_CAPACITY_MOUNTS (default /proc/mounts)
22
+ * AGENT_CAPACITY_PSI_DIR (default /proc/pressure)
23
+ * AGENT_CAPACITY_FORCE_WSL (1 -> treat as WSL2 even off-Linux, 0 -> never)
24
+ * AGENT_CAPACITY_DISABLE (1 -> skip capacity gates entirely)
25
+ * AGENT_HEAVY_LOCK (default ~/.agent-harness/heavy.lock)
26
+ * AGENT_WSL_CONFIG (explicit .wslconfig path for doctor)
27
+ * AGENT_HOST_RAM_MB / AGENT_HOST_CPUS (inject Windows host totals for tests)
28
+ * AGENT_TUNING_SYSCTL_DIR / AGENT_TUNING_SLICE_FILE (tuning status for tests)
29
+ */
30
+ const fs = require("fs");
31
+ const os = require("os");
32
+ const path = require("path");
33
+ const classifier = require("./command-classifier");
34
+
35
+ /* Documented defaults. The project overrides them in `orchestration.md` (the
36
+ * same machine-read file the context guard uses) — a missing row falls back
37
+ * here, so the guard survives a hand-trimmed file. Values target the 10 GB WSL2
38
+ * box the harness is built on; a project on a bigger host can raise them. */
39
+ const DEFAULT_ENVELOPE = {
40
+ minAvailableMemMb: 1024,
41
+ maxSwapUsedPct: 80,
42
+ maxLiveServes: 2,
43
+ maxHeavyTiers: 1,
44
+ idleReapMinutes: 90,
45
+ emulatorRamMb: 2048,
46
+ heavyLockTtlMinutes: 240,
47
+ // A heavy tier (emulator, Metro/Next dev, live E2E) is capped in its own
48
+ // cgroup by default (serve.js). The cap is deliberately generous — above the
49
+ // observed peak (an AVD from a 2048 MB guest peaks ~3.9 GB RSS) — so normal
50
+ // E2E is never throttled, but a runaway is OOM-killed inside its slice
51
+ // instead of freezing every terminal. Overridable per launch with --mem-max.
52
+ heavyMemMaxMb: 5120,
53
+ // Combined budget for ONE tier group (serve.js --group, e.g. the `mobile`
54
+ // emulator + dev server). Each member's per-process cap (`heavy_mem_max_mb`)
55
+ // is generous, so two members could legally fill the whole VM (2 × 5 GB on a
56
+ // 10 GB box — the 2026-09-30 freeze, where the emulator + `next dev` + an
57
+ // inline Gradle build together exhausted RAM). `serve.js` tightens a new
58
+ // member's cap to the group's remaining budget so the pair stays inside one
59
+ // tier; `evaluate` warns when a live group overshoots.
60
+ groupMemMaxMb: 6144,
61
+ // Soft `MemoryHigh` backstop for the cgroup that actually holds the agents
62
+ // (WSL puts the `wsl.exe` session in init.scope, NOT user.slice). Soft: it
63
+ // throttles/reclaims near the freeze line and never OOM-kills. 8.5 GB sits
64
+ // above the observed non-reclaimable working set (~6.9 GB) so the cap only
65
+ // reclaims page cache in normal E2E, and below the ~9.5 GB freeze peak.
66
+ backstopMemHighMb: 8704,
67
+ // PSI (`/proc/pressure/*`) is the earliest true freeze signal — load average
68
+ // lies, but memory "some avg10" climbing means processes are already stalled
69
+ // on reclaim. Warning thresholds, not hard failures.
70
+ maxMemPressureAvg10: 10,
71
+ maxCpuPressureAvg10: 80,
72
+ };
73
+
74
+ const ENVELOPE_KEYS = {
75
+ min_available_mem_mb: "minAvailableMemMb",
76
+ max_swap_used_pct: "maxSwapUsedPct",
77
+ max_live_serves: "maxLiveServes",
78
+ max_heavy_tiers: "maxHeavyTiers",
79
+ idle_reap_minutes: "idleReapMinutes",
80
+ emulator_ram_mb: "emulatorRamMb",
81
+ heavy_lock_ttl_minutes: "heavyLockTtlMinutes",
82
+ heavy_mem_max_mb: "heavyMemMaxMb",
83
+ group_mem_max_mb: "groupMemMaxMb",
84
+ backstop_mem_high_mb: "backstopMemHighMb",
85
+ max_mem_pressure_avg10: "maxMemPressureAvg10",
86
+ max_cpu_pressure_avg10: "maxCpuPressureAvg10",
87
+ };
88
+
89
+ /* Heavy-process classification lives in `command-classifier.js`: it tokenizes
90
+ * the shell and matches the PROGRAM / subcommand / script basename, so a
91
+ * read-only reference to a device serial (`emulator-5554`) or an artifact path
92
+ * (`~/.maestro/…`) is never heavy. The envelope's consumers (serve.js, the
93
+ * context-guard plugin, doctor) read these thin wrappers so there is one owner
94
+ * of the command taxonomy. */
95
+ function procPath(envKey, fallback) {
96
+ return process.env[envKey] || fallback;
97
+ }
98
+
99
+ function isAlive(pid) {
100
+ const n = Number(pid);
101
+ if (!Number.isFinite(n) || n <= 0) return false;
102
+ try {
103
+ process.kill(n, 0);
104
+ return true;
105
+ } catch (err) {
106
+ return err && err.code === "EPERM";
107
+ }
108
+ }
109
+
110
+ function classifyHeavy(cmd) {
111
+ return classifier.classifyHeavy(cmd);
112
+ }
113
+
114
+ function isHeavyCommand(cmd) {
115
+ return classifier.isHeavyCommand(cmd);
116
+ }
117
+
118
+ /* True when a command is a long-lived heavy tier (holds RAM for its lifetime),
119
+ * as opposed to a one-shot heavy command (build/test/maestro). Callers use this
120
+ * to decide whether adding the command would introduce a concurrent tier. */
121
+ function isLongLivedHeavy(cmd) {
122
+ return classifier.isLongLivedHeavy(cmd);
123
+ }
124
+
125
+ /* The full analysis (`{ label, longLived, evidence }` or null) for callers that
126
+ * want the WHY in a message/log. */
127
+ function analyzeHeavy(cmd) {
128
+ return classifier.analyzeCommand(cmd);
129
+ }
130
+
131
+ /* Parse a MemoryMax-style value (`5120M`, `4G`, `1024`) to whole MB; null when
132
+ * absent/unparseable. Used to sum a tier group's live budget. */
133
+ function parseMemMb(value) {
134
+ if (value == null) return null;
135
+ const m = String(value).match(/^\s*([0-9.]+)\s*([KMGT]?)B?\s*$/i);
136
+ if (!m) return null;
137
+ const n = parseFloat(m[1]);
138
+ if (!Number.isFinite(n)) return null;
139
+ const unit = (m[2] || "M").toUpperCase();
140
+ const mult = unit === "K" ? 1 / 1024 : unit === "M" ? 1 : unit === "G" ? 1024 : 1024 * 1024;
141
+ return Math.round(n * mult);
142
+ }
143
+
144
+ /* `| \`key\` | 2048 | ... |` rows. Non-envelope keyed rows (turn/stuck) are
145
+ * ignored because their key is not in ENVELOPE_KEYS. */
146
+ function parseEnvelope(text) {
147
+ const env = Object.assign({}, DEFAULT_ENVELOPE);
148
+ for (const line of String(text || "").split(/\r?\n/)) {
149
+ const m = line.match(/^\|\s*`?([a-z_]+)`?\s*\|\s*(\d+)\s*\|/);
150
+ if (!m) continue;
151
+ const key = ENVELOPE_KEYS[m[1]];
152
+ if (key) env[key] = Number(m[2]);
153
+ }
154
+ return env;
155
+ }
156
+
157
+ function envelopePath(root) {
158
+ return path.join(root, ".agents", "memory", "orchestration.md");
159
+ }
160
+
161
+ function readEnvelopeText(root) {
162
+ try {
163
+ return fs.readFileSync(envelopePath(root), "utf8");
164
+ } catch (_) {
165
+ return "";
166
+ }
167
+ }
168
+
169
+ function readEnvelope(root) {
170
+ return parseEnvelope(readEnvelopeText(root));
171
+ }
172
+
173
+ function isWsl() {
174
+ if (process.env.AGENT_CAPACITY_FORCE_WSL === "1") return true;
175
+ if (process.env.AGENT_CAPACITY_FORCE_WSL === "0") return false;
176
+ if (process.platform !== "linux") return false;
177
+ try {
178
+ return /microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"));
179
+ } catch (_) {
180
+ return false;
181
+ }
182
+ }
183
+
184
+ function readMem() {
185
+ try {
186
+ const text = fs.readFileSync(procPath("AGENT_CAPACITY_MEMINFO", "/proc/meminfo"), "utf8");
187
+ const get = (key) => {
188
+ const m = text.match(new RegExp("^" + key + ":\\s+(\\d+)", "m"));
189
+ return m ? Number(m[1]) : null;
190
+ };
191
+ const toMb = (kb) => (kb == null ? null : Math.round(kb / 1024));
192
+ const total = toMb(get("MemTotal"));
193
+ const available = toMb(get("MemAvailable"));
194
+ const swapTotal = toMb(get("SwapTotal")) || 0;
195
+ const swapFree = toMb(get("SwapFree")) || 0;
196
+ return {
197
+ total,
198
+ available,
199
+ swapTotal,
200
+ swapFree,
201
+ swapUsedPct: swapTotal > 0 ? Math.round(((swapTotal - swapFree) / swapTotal) * 100) : 0,
202
+ };
203
+ } catch (_) {
204
+ return null;
205
+ }
206
+ }
207
+
208
+ function readLoad() {
209
+ try {
210
+ const text = fs.readFileSync(procPath("AGENT_CAPACITY_LOADAVG", "/proc/loadavg"), "utf8").trim();
211
+ const load1 = parseFloat(text.split(/\s+/)[0]);
212
+ return { load1: Number.isFinite(load1) ? load1 : null, cpus: os.cpus().length || 1 };
213
+ } catch (_) {
214
+ return null;
215
+ }
216
+ }
217
+
218
+ /* PSI (`/proc/pressure/{memory,cpu}`): the kernel's own stall accounting. `some
219
+ * avg10` is the share of the last 10 s during which at least one task was
220
+ * stalled; a memory `some` value climbing past ~10 is the freeze arriving,
221
+ * before free-RAM or load make it obvious. Returns null where PSI is absent. */
222
+ function readPsi() {
223
+ const dir = process.env.AGENT_CAPACITY_PSI_DIR || "/proc/pressure";
224
+ const readOne = (name) => {
225
+ try {
226
+ const text = fs.readFileSync(path.join(dir, name), "utf8");
227
+ const get = (re) => {
228
+ const m = text.match(re);
229
+ return m ? parseFloat(m[1]) : null;
230
+ };
231
+ return {
232
+ some10: get(/some\s+avg10=([0-9.]+)/),
233
+ full10: get(/full\s+avg10=([0-9.]+)/),
234
+ };
235
+ } catch (_) {
236
+ return null;
237
+ }
238
+ };
239
+ const mem = readOne("memory");
240
+ const cpu = readOne("cpu");
241
+ if (!mem && !cpu) return null;
242
+ return { mem, cpu };
243
+ }
244
+
245
+ /* Windows-host totals, for host-aware advice. On WSL the VM is a slice of the
246
+ * real machine, so "raise memory" is only sensible when the host has room and
247
+ * "processors=N" only when it leaves Windows threads to run the terminal/relay.
248
+ * Best-effort (powershell may be slow/unavailable); overridable for tests. */
249
+ function readHost() {
250
+ if (process.env.AGENT_HOST_RAM_MB || process.env.AGENT_HOST_CPUS) {
251
+ const ramMb = Number(process.env.AGENT_HOST_RAM_MB);
252
+ const cpus = Number(process.env.AGENT_HOST_CPUS);
253
+ return {
254
+ ramMb: Number.isFinite(ramMb) && ramMb > 0 ? ramMb : null,
255
+ cpus: Number.isFinite(cpus) && cpus > 0 ? cpus : null,
256
+ };
257
+ }
258
+ if (!isWsl()) return null;
259
+ const ps = (expr) => {
260
+ try {
261
+ const r = require("child_process").execFileSync(
262
+ "powershell.exe",
263
+ ["-NoProfile", "-Command", expr],
264
+ { encoding: "utf8", timeout: 8000, stdio: ["ignore", "pipe", "ignore"] }
265
+ );
266
+ const n = Number(String(r).trim());
267
+ return Number.isFinite(n) && n > 0 ? n : null;
268
+ } catch (_) {
269
+ return null;
270
+ }
271
+ };
272
+ const ramBytes = ps("(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory");
273
+ const cpus = ps("(Get-CimInstance Win32_ComputerSystem).NumberOfLogicalProcessors");
274
+ if (!ramBytes && !cpus) return null;
275
+ return { ramMb: ramBytes ? Math.round(ramBytes / 1048576) : null, cpus };
276
+ }
277
+
278
+ /* Windows-side stray dev listeners (F-13). A dev server / emulator started from a
279
+ * Windows terminal — or a leftover `npm run dev` on the host — is invisible to the
280
+ * WSL-side `.serve/` registry yet holds the port the WSL side needs (the "metro is
281
+ * running from Windows" incident: the WSL session could not bind or silently
282
+ * talked to the wrong Metro). Best-effort PowerShell; returns the held port numbers
283
+ * (empty when not WSL, unqueryable, or nothing matches). `AGENT_WINDOWS_STRAYS`
284
+ * overrides for tests (a space-separated port list). */
285
+ function readWindowsStrays(opts = {}) {
286
+ const parse = (text) =>
287
+ [
288
+ ...new Set(
289
+ String(text || "")
290
+ .split(/[\s,]+/)
291
+ .map((s) => Number(s))
292
+ .filter((n) => Number.isFinite(n) && n > 0)
293
+ ),
294
+ ];
295
+ if (opts.strays != null) return parse(opts.strays);
296
+ if (process.env.AGENT_WINDOWS_STRAYS != null) return parse(process.env.AGENT_WINDOWS_STRAYS);
297
+ if (!isWsl()) return [];
298
+ const ports = opts.ports || [8081, 3000, 3001, 5037, 5554, 5555];
299
+ const expr =
300
+ "$ErrorActionPreference='SilentlyContinue';" +
301
+ "Get-NetTCPConnection -State Listen |" +
302
+ ` Where-Object { @(${ports.join(",")}) -contains $_.LocalPort } |` +
303
+ " Select-Object -ExpandProperty LocalPort -Unique";
304
+ try {
305
+ const r = require("child_process").execFileSync(
306
+ "powershell.exe",
307
+ ["-NoProfile", "-Command", expr],
308
+ { encoding: "utf8", timeout: 8000, stdio: ["ignore", "pipe", "ignore"] }
309
+ );
310
+ return [...new Set(parse(r))];
311
+ } catch (_) {
312
+ return [];
313
+ }
314
+ }
315
+
316
+ /* Whether the one-time in-WSL tuning (`scripts/wsl-tune.sh apply`) is present:
317
+ * a low swappiness, the user.slice resource ceiling, and the soft init.scope
318
+ * backstop. Doctor reads this to tell the operator the single command that
319
+ * finishes the setup.
320
+ *
321
+ * The cgroup facts are the important part. WSL's `wsl.exe` session — and so
322
+ * every agent, emulator, and dev server — lands in `init.scope`, NOT
323
+ * `user.slice`; a ceiling only on `user.slice` never binds the real workload.
324
+ * `workloadCapped` is true only when the cgroup that holds the workload carries
325
+ * a finite limit (`init.scope` MemoryHigh/MemoryMax). `sliceApplied` alone is
326
+ * not enough, which is exactly the gap this detects. */
327
+ function readTuning() {
328
+ const sysctlDir = process.env.AGENT_TUNING_SYSCTL_DIR || "/proc/sys";
329
+ let swappiness = null;
330
+ try {
331
+ const v = fs.readFileSync(path.join(sysctlDir, "vm", "swappiness"), "utf8").trim();
332
+ swappiness = Number(v);
333
+ if (!Number.isFinite(swappiness)) swappiness = null;
334
+ } catch (_) {
335
+ swappiness = null;
336
+ }
337
+ const sliceFile =
338
+ process.env.AGENT_TUNING_SLICE_FILE || "/etc/systemd/system/user.slice.d/90-agent-cap.conf";
339
+ const backstopUnit =
340
+ process.env.AGENT_TUNING_BACKSTOP_UNIT || "/etc/systemd/system/agent-wsl-backstop.service";
341
+ const cgroupRoot = process.env.AGENT_TUNING_CGROUP_ROOT || "/sys/fs/cgroup";
342
+ const readCg = (rel) => {
343
+ try {
344
+ return fs.readFileSync(path.join(cgroupRoot, rel), "utf8").trim();
345
+ } catch (_) {
346
+ return null;
347
+ }
348
+ };
349
+ const finite = (v) => v != null && v !== "" && v !== "max";
350
+ const initHigh = readCg("init.scope/memory.high");
351
+ const initMax = readCg("init.scope/memory.max");
352
+ const userSliceMax = readCg("user.slice/memory.max");
353
+ return {
354
+ swappiness,
355
+ sliceFile,
356
+ sliceApplied: fs.existsSync(sliceFile),
357
+ backstopUnit,
358
+ backstopApplied: fs.existsSync(backstopUnit),
359
+ initHigh,
360
+ initMax,
361
+ userSliceMax,
362
+ workloadCapped: finite(initHigh) || finite(initMax),
363
+ };
364
+ }
365
+
366
+ /* Live long-lived processes recorded by `serve.js` under `.serve/*.pid`. A pid
367
+ * file whose pid is dead is still reported (so a stale file is visible) but
368
+ * never counts as live. `ageMs` comes from the recorded start timestamp. */
369
+ function readServes(root) {
370
+ const dir = path.join(root, ".serve");
371
+ let files = [];
372
+ try {
373
+ files = fs.readdirSync(dir).filter((f) => f.endsWith(".pid"));
374
+ } catch (_) {
375
+ return [];
376
+ }
377
+ const out = [];
378
+ for (const f of files) {
379
+ const name = f.slice(0, -4);
380
+ let info = {};
381
+ try {
382
+ info = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
383
+ } catch (_) {
384
+ info = { name };
385
+ }
386
+ const pid = Number(info.pid);
387
+ const startedAt = info.startedAt ? Date.parse(info.startedAt) : null;
388
+ const ageMs = Number.isFinite(startedAt) ? Date.now() - startedAt : null;
389
+ const cmd = info.cmd || "";
390
+ const memMax = info.memMax || null;
391
+ out.push({
392
+ name,
393
+ pid: Number.isFinite(pid) ? pid : null,
394
+ cmd,
395
+ url: info.url || null,
396
+ port: info.port || null,
397
+ group: info.group || null,
398
+ startedAt: info.startedAt || null,
399
+ ageMs,
400
+ alive: isAlive(pid),
401
+ heavy: info.heavy != null ? !!info.heavy : isHeavyCommand(cmd),
402
+ memMax,
403
+ memMaxMb: parseMemMb(memMax),
404
+ });
405
+ }
406
+ return out;
407
+ }
408
+
409
+ /* Mounted tmpfs roots (the RAM-backed cache from `setup-tmpfs.sh`). Only
410
+ * informative: tmpfs pages are RAM, so a large cache eats the very headroom the
411
+ * emulator/agents need — the freeze's hidden third contributor. */
412
+ function readTmpfs() {
413
+ try {
414
+ const text = fs.readFileSync(procPath("AGENT_CAPACITY_MOUNTS", "/proc/mounts"), "utf8");
415
+ const mounts = text
416
+ .split(/\r?\n/)
417
+ .filter((l) => /\btmpfs\b/.test(l))
418
+ .map((l) => l.split(" ")[1])
419
+ .filter((p) => p && !/^\/(dev\/shm|run|sys|proc)(\/|$)/.test(p));
420
+ const out = [];
421
+ for (const raw of mounts) {
422
+ const mount = raw.replace(/\\040/g, " ");
423
+ try {
424
+ const st = fs.statfsSync(mount);
425
+ const bsize = st.bsize || 4096;
426
+ out.push({
427
+ mount,
428
+ totalMb: Math.round((st.blocks * bsize) / 1048576),
429
+ usedMb: Math.round(((st.blocks - st.bfree) * bsize) / 1048576),
430
+ });
431
+ } catch (_) {
432
+ /* unmounted or unreadable — skip */
433
+ }
434
+ }
435
+ return out;
436
+ } catch (_) {
437
+ return [];
438
+ }
439
+ }
440
+
441
+ function sample(root, envelopeText) {
442
+ const envelope = parseEnvelope(envelopeText != null ? envelopeText : readEnvelopeText(root));
443
+ return {
444
+ root,
445
+ envelope,
446
+ mem: readMem(),
447
+ load: readLoad(),
448
+ psi: readPsi(),
449
+ serves: readServes(root),
450
+ tmpfs: readTmpfs(),
451
+ wsl: isWsl(),
452
+ };
453
+ }
454
+
455
+ /* Evaluate a sample. `opts.pendingHeavy` / `opts.pendingLive` let a caller ask
456
+ * "would adding this process exceed the envelope?" — the preflight must count
457
+ * the process it is ABOUT to start, not only what is already running.
458
+ *
459
+ * `opts.pendingGroup` is a shared tier group (e.g. `mobile`): the device tier
460
+ * legitimately needs two heavy processes (emulator + dev server), so members of
461
+ * ONE group count as a single heavy tier rather than tripping `maxHeavyTiers`.
462
+ * A second, unrelated heavy tier is still refused. */
463
+ function evaluate(s, opts) {
464
+ const e = (s && s.envelope) || DEFAULT_ENVELOPE;
465
+ const pendingHeavy = (opts && opts.pendingHeavy) || 0;
466
+ const pendingLive = (opts && opts.pendingLive) || 0;
467
+ const pendingGroup = (opts && opts.pendingGroup) || null;
468
+ const reasons = [];
469
+ const warnings = [];
470
+ const live = ((s && s.serves) || []).filter((x) => x.alive);
471
+ const heavy = live.filter((x) => x.heavy);
472
+
473
+ if (s && s.mem && s.mem.available != null && s.mem.available < e.minAvailableMemMb) {
474
+ reasons.push(
475
+ `only ${s.mem.available} MB RAM available (envelope min ${e.minAvailableMemMb} MB)`
476
+ );
477
+ }
478
+ // A single live heavy GROUP is ONE tier, whether or not the incoming command
479
+ // declares that group. The device tier legitimately runs two heavy members
480
+ // (emulator + its dev server, both `--group mobile`), so counting them as two
481
+ // would refuse every other heavy command — including a one-shot build/test
482
+ // that the live-tier test pattern explicitly allows (F-311: the context-guard
483
+ // plugin does not pass `pendingGroup`, so a one-shot `maestro`/`run-maestro.js`
484
+ // was refused while the device tier was up). Only a *different* group, an
485
+ // ungrouped live tier, or a second pending long-lived tier adds a tier.
486
+ const heavyGroups = new Set(heavy.map((x) => x.group).filter(Boolean));
487
+ const allGrouped = heavy.length > 0 && heavy.every((x) => !!x.group);
488
+ const oneLiveGroup = allGrouped && heavyGroups.size === 1;
489
+ const joinsRunningGroup = !!pendingGroup && oneLiveGroup && heavyGroups.has(pendingGroup);
490
+ const liveTiers = oneLiveGroup ? 1 : heavy.length;
491
+ // A member joining the already-live group shares its ONE budgeted tier, so it
492
+ // adds 0 (emulator + dev server + a one-shot = one tier). Any other pending
493
+ // heavy adds 1.
494
+ const heavyTiers = liveTiers + (joinsRunningGroup ? 0 : pendingHeavy);
495
+ if (heavyTiers > e.maxHeavyTiers) {
496
+ const group = [...heavyGroups][0];
497
+ const liveDesc = oneLiveGroup
498
+ ? `group ${group} (${heavy.map((h) => h.name).join(", ")})`
499
+ : heavy.map((h) => h.name).join(", ");
500
+ reasons.push(
501
+ `${heavyTiers} heavy tier(s) would run at once ` +
502
+ `(${[liveDesc, !joinsRunningGroup && pendingHeavy ? "this launch" : null].filter(Boolean).join(", ")}); ` +
503
+ `envelope allows ${e.maxHeavyTiers}`
504
+ );
505
+ }
506
+ if (live.length + pendingLive > e.maxLiveServes) {
507
+ warnings.push(
508
+ `${live.length + pendingLive} live serve process(es); envelope suggests max ${e.maxLiveServes}`
509
+ );
510
+ }
511
+ // Combined per-group budget: each heavy member is capped generously
512
+ // (`heavy_mem_max_mb`), so without this a two-member mobile tier could fill
513
+ // the VM. `serve.js` enforces it by tightening a new member's cap; this warns
514
+ // when an already-live group is over budget.
515
+ if (e.groupMemMaxMb > 0) {
516
+ const groupMem = new Map();
517
+ for (const x of heavy) {
518
+ if (!x.group || x.memMaxMb == null) continue;
519
+ groupMem.set(x.group, (groupMem.get(x.group) || 0) + x.memMaxMb);
520
+ }
521
+ for (const [g, sum] of groupMem) {
522
+ if (sum > e.groupMemMaxMb) {
523
+ warnings.push(
524
+ `tier group "${g}" is budgeted ${sum} MB (group_mem_max_mb ${e.groupMemMaxMb} MB) — ` +
525
+ `lower a member with --mem-max or stop one`
526
+ );
527
+ }
528
+ }
529
+ }
530
+ if (s && s.mem && s.mem.swapTotal > 0 && s.mem.swapUsedPct >= e.maxSwapUsedPct) {
531
+ warnings.push(`swap ${s.mem.swapUsedPct}% used (envelope max ${e.maxSwapUsedPct}%)`);
532
+ }
533
+ if (s && s.psi && s.psi.mem && s.psi.mem.some10 != null && s.psi.mem.some10 >= e.maxMemPressureAvg10) {
534
+ warnings.push(
535
+ `memory pressure ${s.psi.mem.some10.toFixed(1)} (PSI some avg10 ≥ ${e.maxMemPressureAvg10}) — ` +
536
+ `processes are already stalling on reclaim`
537
+ );
538
+ }
539
+ if (s && s.psi && s.psi.cpu && s.psi.cpu.some10 != null && s.psi.cpu.some10 >= e.maxCpuPressureAvg10) {
540
+ warnings.push(`CPU pressure ${s.psi.cpu.some10.toFixed(1)} (PSI some avg10 ≥ ${e.maxCpuPressureAvg10})`);
541
+ }
542
+ for (const x of live) {
543
+ if (x.ageMs != null && x.ageMs > e.idleReapMinutes * 60000) {
544
+ warnings.push(
545
+ `"${x.name}" has been up ${Math.round(x.ageMs / 60000)}m — stop it when its tier is done (idle hint ${e.idleReapMinutes}m)`
546
+ );
547
+ }
548
+ }
549
+ return { ok: reasons.length === 0, reasons, warnings, live, heavy };
550
+ }
551
+
552
+ /* Live memory budget of one tier group: sum of the live members' applied caps,
553
+ * and what remains of `group_mem_max_mb`. `serve.js` uses `remainingMb` to
554
+ * tighten a new member's cap so the group stays inside one budget. */
555
+ function groupBudget(serves, group, envelope) {
556
+ const e = envelope || DEFAULT_ENVELOPE;
557
+ const total = e.groupMemMaxMb > 0 ? e.groupMemMaxMb : Infinity;
558
+ let used = 0;
559
+ for (const x of serves || []) {
560
+ if (!x.alive || x.group !== group || x.memMaxMb == null) continue;
561
+ used += x.memMaxMb;
562
+ }
563
+ return { usedMb: used, totalMb: e.groupMemMaxMb, remainingMb: total === Infinity ? null : total - used };
564
+ }
565
+
566
+ function formatSummary(s) {
567
+ const parts = [];
568
+ if (s && s.mem && s.mem.total != null) {
569
+ parts.push(`RAM ${s.mem.available}/${s.mem.total} MB free`);
570
+ if (s.mem.swapTotal > 0) parts.push(`swap ${s.mem.swapUsedPct}% of ${s.mem.swapTotal} MB`);
571
+ }
572
+ if (s && s.load && s.load.load1 != null) parts.push(`load ${s.load.load1}/${s.load.cpus} cpu`);
573
+ if (s && s.psi && s.psi.mem && s.psi.mem.some10 != null) {
574
+ parts.push(`mem pressure ${s.psi.mem.some10.toFixed(1)}`);
575
+ }
576
+ const live = ((s && s.serves) || []).filter((x) => x.alive);
577
+ parts.push(`${live.length} live serve(s)`);
578
+ if (s && s.tmpfs && s.tmpfs.length) {
579
+ const used = s.tmpfs.reduce((a, t) => a + t.usedMb, 0);
580
+ if (used > 0) parts.push(`tmpfs ${used} MB`);
581
+ }
582
+ return `capacity: ${parts.join(" \u00b7 ")}`;
583
+ }
584
+
585
+ /* The refusal body for a blocked heavy launch. Lists what is already running
586
+ * with ages so the operator can stop the right one. */
587
+ function heavyBlockText(label, ev, s) {
588
+ const lines = [`refused: "${label}" would exceed the machine capacity envelope`];
589
+ for (const r of ev.reasons) lines.push(` - ${r}`);
590
+ const running = ((s && s.serves) || [])
591
+ .filter((x) => x.alive)
592
+ .map((x) => `${x.name}${x.ageMs != null ? ` (${Math.round(x.ageMs / 60000)}m)` : ""}`);
593
+ lines.push(` running: ${running.length ? running.join(", ") : "none"}`);
594
+ lines.push(
595
+ ` stop one first (node scripts/serve.js stop --name <name> | stop-all), ` +
596
+ `or re-run with --force to override (AGENT_CAPACITY_DISABLE=1 must be set ` +
597
+ `when opencode starts — it cannot be prefixed per command)`
598
+ );
599
+ return lines.join("\n");
600
+ }
601
+
602
+ /* A short tail nudge the context-guard plugin can inject (same envelope, live
603
+ * sample). Returns null when there is nothing to say. */
604
+ function notice(ev) {
605
+ if (!ev || (ev.ok && !(ev.warnings && ev.warnings.length))) return null;
606
+ const head = ev.ok ? "capacity warning" : "CAPACITY OVER ENVELOPE";
607
+ const lines = [head, ...(ev.reasons || []).map((r) => ` - ${r}`), ...(ev.warnings || []).map((w) => ` - ${w}`)];
608
+ lines.push(" Serialize heavy tiers; stop idle dev servers/emulators (node scripts/serve.js stop-all).");
609
+ return lines.join("\n");
610
+ }
611
+
612
+ /* --------------------------------------------------------------- heavy lock
613
+ * A machine-wide, single-holder lock so two sessions can never both start a
614
+ * device/live tier. Cross-process and cross-session by design (unlike the
615
+ * per-tree session leases): `serve.js start` acquires it for a heavy command
616
+ * and `serve.js stop` releases it. TTL + dead-pid detection mean a crashed
617
+ * holder can never wedge the machine. */
618
+ function lockPath() {
619
+ return process.env.AGENT_HEAVY_LOCK || path.join(os.homedir(), ".agent-harness", "heavy.lock");
620
+ }
621
+
622
+ function readLock() {
623
+ try {
624
+ return JSON.parse(fs.readFileSync(lockPath(), "utf8"));
625
+ } catch (_) {
626
+ return null;
627
+ }
628
+ }
629
+
630
+ /* Members of a lock. A current lock carries `members: [{name, pid, unit}]` — the
631
+ * REAL server pids, because the `serve.js start` CLI process that writes the
632
+ * lock exits immediately and would make a pid-based lock look stale at once.
633
+ * A legacy `{pid, name}` record is normalised to a single member. */
634
+ function lockMembers(lock) {
635
+ if (!lock) return [];
636
+ if (Array.isArray(lock.members) && lock.members.length > 0) return lock.members;
637
+ if (lock.pid) return [{ name: lock.name || "heavy", pid: lock.pid, unit: lock.unit || null }];
638
+ return [];
639
+ }
640
+
641
+ function writeLock(record) {
642
+ const p = lockPath();
643
+ fs.mkdirSync(path.dirname(p), { recursive: true });
644
+ fs.writeFileSync(p, JSON.stringify(record, null, 2));
645
+ }
646
+
647
+ /* Stale when no recorded member process is alive, or the lock has outlived its
648
+ * TTL (a crashed tier can never wedge the machine). */
649
+ function lockIsStale(lock, ttlMinutes) {
650
+ if (!lock) return true;
651
+ const members = lockMembers(lock);
652
+ if (members.length === 0) return true;
653
+ if (!members.some((m) => isAlive(m.pid))) return true;
654
+ const since = lock.since ? Date.parse(lock.since) : null;
655
+ const ttl = Number(ttlMinutes) > 0 ? Number(ttlMinutes) : DEFAULT_ENVELOPE.heavyLockTtlMinutes;
656
+ if (since != null && Number.isFinite(since) && Date.now() - since > ttl * 60000) return true;
657
+ return false;
658
+ }
659
+
660
+ /* Returns { ok, held, lock?, joined?, error? }. `ok` false + `held` true means
661
+ * another live tier holds the lock; `held` false means it could not be written.
662
+ * `group` records a shared tier (e.g. `mobile`): a live holder of the SAME group
663
+ * is compatible, and this member is appended rather than refused. The member pid
664
+ * is the short-lived CLI pid until serve.js calls `updateHeavyMember` with the
665
+ * real server pid. */
666
+ function acquireHeavyLock(name, envelope, group) {
667
+ const ttl = (envelope && envelope.heavyLockTtlMinutes) || DEFAULT_ENVELOPE.heavyLockTtlMinutes;
668
+ const p = lockPath();
669
+ for (let attempt = 0; attempt < 2; attempt++) {
670
+ try {
671
+ fs.mkdirSync(path.dirname(p), { recursive: true });
672
+ const fd = fs.openSync(p, "wx");
673
+ fs.writeSync(
674
+ fd,
675
+ JSON.stringify(
676
+ {
677
+ name: name || "heavy",
678
+ group: group || null,
679
+ host: os.hostname(),
680
+ since: new Date().toISOString(),
681
+ members: [{ name: name || "heavy", pid: process.pid, unit: null }],
682
+ },
683
+ null,
684
+ 2
685
+ )
686
+ );
687
+ fs.closeSync(fd);
688
+ return { ok: true, held: true };
689
+ } catch (err) {
690
+ if (err.code !== "EEXIST") return { ok: false, held: false, error: err.message || String(err) };
691
+ const existing = readLock();
692
+ if (lockIsStale(existing, ttl)) {
693
+ try {
694
+ fs.unlinkSync(p);
695
+ } catch (_) {}
696
+ continue;
697
+ }
698
+ if (group != null && existing.group === group) {
699
+ return { ok: true, held: true, joined: true, lock: existing };
700
+ }
701
+ return { ok: false, held: true, lock: existing };
702
+ }
703
+ }
704
+ return { ok: false, held: true, lock: readLock() };
705
+ }
706
+
707
+ /* Register/replace a lock member with the REAL running server pid + unit. Called
708
+ * by serve.js after the spawn, so the lock tracks a process that outlives the
709
+ * `start` CLI. Adds the member to a same-group lock (never clobbers a sibling). */
710
+ function updateHeavyMember(member) {
711
+ const lock = readLock();
712
+ if (!lock) {
713
+ writeLock({
714
+ name: member.name,
715
+ group: member.group || null,
716
+ host: os.hostname(),
717
+ since: new Date().toISOString(),
718
+ members: [{ name: member.name, pid: member.pid, unit: member.unit || null }],
719
+ });
720
+ return true;
721
+ }
722
+ const members = lockMembers(lock).filter((m) => m.name !== member.name);
723
+ members.push({ name: member.name, pid: member.pid, unit: member.unit || null });
724
+ lock.members = members;
725
+ if (member.group != null) lock.group = member.group;
726
+ writeLock(lock);
727
+ return true;
728
+ }
729
+
730
+ /* Release this member. `name` (the server being stopped) removes its member
731
+ * entry; the lock is deleted only when the last member is gone, so a shared
732
+ * group (emulator + dev server) releases exactly once. `group` is a fallback for
733
+ * a legacy record without a members list. */
734
+ function releaseHeavyLock(name, group) {
735
+ const lock = readLock();
736
+ if (!lock) return false;
737
+ const members = lockMembers(lock);
738
+ if (Array.isArray(lock.members) && lock.members.length > 0 && name != null) {
739
+ const remaining = members.filter((m) => m.name !== name);
740
+ if (remaining.length > 0) {
741
+ lock.members = remaining;
742
+ writeLock(lock);
743
+ return true;
744
+ }
745
+ } else {
746
+ const mine = Number(lock.pid) === process.pid;
747
+ const named = name != null && lock.name === name;
748
+ const grouped = group != null && lock.group === group;
749
+ if (!mine && !named && !grouped) return false;
750
+ }
751
+ try {
752
+ fs.unlinkSync(lockPath());
753
+ return true;
754
+ } catch (_) {
755
+ return false;
756
+ }
757
+ }
758
+
759
+ /* Remove the machine-wide heavy lock unconditionally. Teardown only:
760
+ * `serve.js stop-all` has already stopped every member — including an orphaned
761
+ * lock member whose `.serve/` record was lost in another worktree (the F-302
762
+ * leak: a dev server started in MAIN survived a worktree-scoped stop-all and
763
+ * pinned RAM, refusing the F-304/F-305 device tiers). */
764
+ function clearHeavyLock() {
765
+ try {
766
+ fs.unlinkSync(lockPath());
767
+ return true;
768
+ } catch (_) {
769
+ return false;
770
+ }
771
+ }
772
+
773
+ /* --------------------------------------------------------------- .wslconfig
774
+ * Doctor-only: read the Windows-side `.wslconfig` (best-effort) and turn its
775
+ * vmIdleTimeout/memory/swap/autoMemoryReclaim into concrete advice. */
776
+ function parseWslConfig(text) {
777
+ const out = {};
778
+ let section = "";
779
+ for (const raw of String(text || "").split(/\r?\n/)) {
780
+ const line = raw.trim();
781
+ if (!line || line.startsWith("#") || line.startsWith(";")) continue;
782
+ const sec = line.match(/^\[(.+)\]$/);
783
+ if (sec) {
784
+ section = sec[1].trim().toLowerCase();
785
+ continue;
786
+ }
787
+ const kv = line.match(/^([A-Za-z0-9_]+)\s*=\s*(.+)$/);
788
+ if (kv) out[(section ? section + "." : "") + kv[1].toLowerCase()] = kv[2].trim();
789
+ }
790
+ return out;
791
+ }
792
+
793
+ function readWslConfig() {
794
+ const candidates = [];
795
+ if (process.env.AGENT_WSL_CONFIG) candidates.push(process.env.AGENT_WSL_CONFIG);
796
+ try {
797
+ for (const user of fs.readdirSync("/mnt/c/Users")) {
798
+ candidates.push(path.join("/mnt/c/Users", user, ".wslconfig"));
799
+ }
800
+ } catch (_) {
801
+ /* not on a Windows-mount host */
802
+ }
803
+ for (const c of candidates) {
804
+ try {
805
+ const text = fs.readFileSync(c, "utf8");
806
+ return { path: c, text, config: parseWslConfig(text) };
807
+ } catch (_) {
808
+ /* keep looking */
809
+ }
810
+ }
811
+ return null;
812
+ }
813
+
814
+ function memToGb(value) {
815
+ const m = String(value || "").match(/^([0-9.]+)\s*(GB|MB|TB)?$/i);
816
+ if (!m) return null;
817
+ const n = parseFloat(m[1]);
818
+ const unit = (m[2] || "GB").toUpperCase();
819
+ if (!Number.isFinite(n)) return null;
820
+ if (unit === "MB") return n / 1024;
821
+ if (unit === "TB") return n * 1024;
822
+ return n;
823
+ }
824
+
825
+ function wslConfigAdvice(wsl, host) {
826
+ const advice = [];
827
+ if (!wsl || !wsl.config) return advice;
828
+ const cfg = wsl.config;
829
+ const hostGb = host && host.ramMb ? host.ramMb / 1024 : null;
830
+ const mem = cfg["wsl2.memory"];
831
+ const gb = mem ? memToGb(mem) : null;
832
+ if (gb != null) {
833
+ if (hostGb != null) {
834
+ // Host-aware: only push back when the VM leaves Windows too little.
835
+ const leftForWindows = hostGb - gb;
836
+ if (leftForWindows < 5) {
837
+ advice.push(
838
+ `.wslconfig memory=${mem} leaves Windows ~${leftForWindows.toFixed(1)} GB on a ${hostGb.toFixed(1)} GB host — ` +
839
+ `too tight (Windows needs room for the terminal + vsock relay); keep WSL at ~${Math.max(6, Math.floor(hostGb - 6))} GB or serialize heavy tiers`
840
+ );
841
+ }
842
+ } else if (gb < 12) {
843
+ advice.push(
844
+ `.wslconfig memory=${mem} — raise it only if the Windows host has headroom (a 10 GB VM + emulator + 2 agents + next dev does not fit)`
845
+ );
846
+ }
847
+ }
848
+ const proc = Number(cfg["wsl2.processors"]);
849
+ const hostCpus = host && host.cpus;
850
+ if (Number.isFinite(proc) && hostCpus && proc > hostCpus - 4) {
851
+ advice.push(
852
+ `.wslconfig processors=${proc} of ${hostCpus} host logical CPUs leaves only ${hostCpus - proc} thread(s) for ` +
853
+ `Windows (terminal, vsock relay) — set processors=${Math.max(2, hostCpus - 4)}`
854
+ );
855
+ }
856
+ const idle = cfg["wsl2.vmidletimeout"];
857
+ const idleMs = idle ? Number(idle) : NaN;
858
+ if (idle && Number.isFinite(idleMs) && idleMs > 2 * 3600 * 1000) {
859
+ advice.push(`.wslconfig vmIdleTimeout=${idle} (>2h) — lower it so idle WSL RAM is returned to Windows`);
860
+ }
861
+ const reclaim = cfg["experimental.automemoryreclaim"] || cfg["wsl2.automemoryreclaim"];
862
+ if (!reclaim) {
863
+ advice.push(".wslconfig has no autoMemoryReclaim=gradual — idle WSL memory is never reclaimed");
864
+ }
865
+ const swap = cfg["wsl2.swap"];
866
+ if (swap === "0") {
867
+ advice.push(".wslconfig swap=0 disables swap — keep a modest swap file so a spike degrades instead of OOM-freezing");
868
+ } else if (swap && memToGb(swap) != null && memToGb(swap) >= 8) {
869
+ advice.push(
870
+ `.wslconfig swap=${swap} allows long swap-thrash before an OOM — a smaller swap (2–4 GB) fails faster and lets the ` +
871
+ `capacity guard intervene (scripts/wsl-tune.sh sets this)`
872
+ );
873
+ }
874
+ return advice;
875
+ }
876
+
877
+ module.exports = {
878
+ DEFAULT_ENVELOPE,
879
+ ENVELOPE_KEYS,
880
+ classifyHeavy,
881
+ isHeavyCommand,
882
+ isLongLivedHeavy,
883
+ analyzeHeavy,
884
+ parseMemMb,
885
+ groupBudget,
886
+ parseEnvelope,
887
+ envelopePath,
888
+ readEnvelopeText,
889
+ readEnvelope,
890
+ isWsl,
891
+ readMem,
892
+ readLoad,
893
+ readPsi,
894
+ readHost,
895
+ readTuning,
896
+ readWindowsStrays,
897
+ readServes,
898
+ readTmpfs,
899
+ sample,
900
+ evaluate,
901
+ formatSummary,
902
+ heavyBlockText,
903
+ notice,
904
+ lockPath,
905
+ readLock,
906
+ lockMembers,
907
+ lockIsStale,
908
+ acquireHeavyLock,
909
+ updateHeavyMember,
910
+ releaseHeavyLock,
911
+ clearHeavyLock,
912
+ isAlive,
913
+ parseWslConfig,
914
+ readWslConfig,
915
+ wslConfigAdvice,
916
+ };