opencode-agent-harness 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +590 -2
- package/bin/agent-harness.js +3059 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +48 -4
- package/templates/.agents/AGENTS.md +204 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1864 -0
- package/templates/scripts/board-service.sh +207 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +277 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +260 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +469 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +427 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +284 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +183 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +212 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +261 -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
|
+
};
|