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,106 @@
1
+ # Nightly E2E cycle
2
+
3
+ How the harness tests the day's landed code off-hours, and closes the loop on a
4
+ fix. The day loop lands features on **cheap gates**; the expensive device/Maestro
5
+ tier is deliberately not run during the day. `scripts/nightly.js` runs the full
6
+ battery overnight against a dedicated `nightly` worktree fast-forwarded to
7
+ `origin/main`, writes a report, and reconciles the backlog.
8
+
9
+ ```
10
+ DAY worktree → cheap gates → land on main → CI → UAT deploy
11
+ (no emulator / Maestro unless the user explicitly asks)
12
+ NIGHT local timer (device matrix) + cloud workflow (unit/API/routes/browser)
13
+ → report → board reconciliation
14
+ MORNING `orient` shows the verdict; reopened + new rows are waiting
15
+ ```
16
+
17
+ ## Two halves
18
+
19
+ - **Local (heavy, host-bound)** — `scripts/nightly.js` on a systemd `--user`
20
+ timer. Runs the Android device/Maestro matrix (it needs the local emulator +
21
+ GPU), plus the project's tiers, in a `nightly` worktree. Install with
22
+ `agent-harness install-nightly --target .` (or `bash scripts/setup-nightly.sh install`).
23
+ - **Cloud (host-independent)** — `.github/workflows/nightly.yml`: unit, DB/API,
24
+ route, and browser tiers on a schedule. Fails loudly (the red run is the alert).
25
+
26
+ ## Config — `.agents/nightly.json` (project-owned)
27
+
28
+ Seeded create-if-missing by `init`/`update`; never overwritten on deploy.
29
+
30
+ | Key | Meaning |
31
+ | --- | --- |
32
+ | `worktree` | nightly worktree path (default `<repo>/../.worktrees/<repo>/nightly`) |
33
+ | `seedCmd` | optional dev-DB seed run before the phases (development only) |
34
+ | `waitForQuietMin` | wait this long for live human sessions to end before starting |
35
+ | `stalePendingNights` | nights a `nightly:pending` row may stay unvalidated before it is flagged |
36
+ | `keepDays` | report retention under `.agents/qa-runs/nightly/` |
37
+ | `fileBacklog` | reconcile the board (`add`/`reopen`/`validate`); default `true` |
38
+ | `notify` | optional command run with the report path on completion |
39
+ | `phases[]` | ordered battery: `{name, kind, script|cmd, heavy, timeoutMin}` |
40
+
41
+ Phase `kind`s: `gate` (a package.json script; a missing one is **skipped**, never
42
+ failed), `cmd` (a shell command), `device-e2e` (the built-in
43
+ device-up → Maestro matrix → device-down sequence, included only when the tier is
44
+ present). `heavy` phases run capped through `serve.js run`.
45
+
46
+ ## The bug lifecycle
47
+
48
+ A nightly failure and its fix move through the board as **one row**:
49
+
50
+ ```
51
+ NIGHT N journey J fails, no row exists
52
+ → backlog add "[nightly:flow=J] J e2e failed"
53
+ DAY N+1 you fix J on the cheap gates (NO Maestro), finalize as usual
54
+ NIGHT N+1 reconcile (journey-level):
55
+ J passes → archive <id> --closed "nightly-validated <date> <report>"
56
+ J still fails → backlog reopen <id> --reason "nightly <date>: still failing"
57
+ a different journey→ backlog add (a new row)
58
+ ```
59
+
60
+ - The marker `[nightly:flow=<journey>]` lives in the **Task cell**, which every
61
+ board section preserves, so the row stays on the radar through
62
+ Open → In progress → Archive without any schema change.
63
+ - Matching is **journey-level**: one row per broken journey, reopened until
64
+ green. A signature change on the same journey is recorded in the reopen reason
65
+ but still reopens the same row (the fix was incomplete/regressed); a different
66
+ journey's failure is a new row.
67
+ - **No Maestro during the day.** A device-only path is addressed in the QA plan
68
+ as `audited: device tier deferred to nightly [nightly:flow=<journey>]` (a valid
69
+ `audited:`/`waived:` reason). `finalize`/`ship` never demand the device tier.
70
+ - Repeated reopens escalate P2 → P1 (`[nightly:reopen=N]`); stale pending rows
71
+ surface in `orient` and `agent-harness doctor`.
72
+
73
+ ## Running and reading
74
+
75
+ ```bash
76
+ npm run nightly -- run # run the cycle now (foreground)
77
+ npm run nightly -- run --dry-run # phase plan, no side effects
78
+ node scripts/nightly.js report # last verdict + failures + board actions
79
+ node scripts/nightly.js status # last run + rows awaiting validation
80
+
81
+ agent-harness install-nightly --target . # install the timer (02:00)
82
+ agent-harness install-nightly --target . --time 01:30 --force
83
+ bash scripts/setup-nightly.sh status # timer state + last report
84
+ bash scripts/setup-nightly.sh run-now # run immediately
85
+ bash scripts/setup-nightly.sh uninstall
86
+ ```
87
+
88
+ Artifacts: `.agents/qa-runs/nightly/<stamp>/report.json` + `report.md`, a
89
+ `latest.json` pointer, and `state.json` (reopen counts / first-seen). These are
90
+ local artifacts and are gitignored.
91
+
92
+ ## WSL / host notes
93
+
94
+ - The timer needs the machine running. `Persistent=true` runs a missed cycle on
95
+ the next boot; `install` enables `loginctl enable-linger` so the user timer
96
+ fires without an open login session.
97
+ - A host without a `systemd --user` bus falls back to a crontab line (printed by
98
+ `setup-nightly.sh install`).
99
+ - Nightly is the ideal time for heavy tiers: the capacity envelope
100
+ (`.agents/memory/orchestration.md`) expects a free box, and the runner waits
101
+ `waitForQuietMin` for live sessions before it starts.
102
+
103
+ ## Related
104
+
105
+ - `docs/mobile-testing.md` — the device tier mechanics.
106
+ - `docs/ci-cd-pipeline.md` — the day-loop landing + deploy path.
@@ -0,0 +1,290 @@
1
+ # WSL2 / agentic-development optimizations
2
+
3
+ Four harness-managed, re-runnable mechanisms that keep recursive work cheap and
4
+ the VM healthy on a 10 GB / 10 CPU WSL2 box while staying safe outside it:
5
+
6
+ 1. **Ignore-aware search** — a canonical `.ignore` plus `scripts/agent-search.sh`
7
+ so recursive discovery never walks `node_modules`, `.git`, or build output.
8
+ 2. **RAM-backed build/cache storage** — `scripts/setup-tmpfs.sh` mounts a tmpfs
9
+ and points cache/build env vars at it.
10
+ 3. **Machine capacity envelope** — one set of numbers (`.agents/memory/orchestration.md`)
11
+ enforced by `serve.js`, `test:capacity`, the `context-guard` plugin, and
12
+ `agent-harness doctor`, so parallel agents can never stack parallel *heavy
13
+ tiers* into a freeze.
14
+ 4. **WSL2 GPU acceleration** — `scripts/wsl-gpu.sh` loads `vgem` and selects
15
+ Mesa's `d3d12` driver so the device E2E emulator renders on the Windows GPU
16
+ instead of the CPU software rasterizer.
17
+
18
+ All are scripts/config/docs only; none touches application source.
19
+
20
+ ## 1. Ignore-aware search
21
+
22
+ ### The canonical ignore file (`.ignore`)
23
+
24
+ `.ignore` is read by ripgrep and fd (git does **not** read it — `.gitignore`
25
+ stays the project's own file and the harness never writes it). `agent-harness
26
+ update` merges a harness-managed begin/end block listing the high-cost trees:
27
+
28
+ ```
29
+ node_modules/ .git/ .venv/ venv/ __pycache__/ .mypy_cache/ .pytest_cache/
30
+ target/ dist/ build/ .next/ .nuxt/ coverage/ .gradle/ .cargo/ vendor/
31
+ .terraform/ tmp/ .cache/
32
+ ```
33
+
34
+ Project entries outside the markers are preserved; the managed block is replaced
35
+ in place, so re-running `update` never duplicates or truncates anything.
36
+
37
+ ### `scripts/agent-search.sh`
38
+
39
+ A thin ripgrep wrapper that:
40
+
41
+ - relies on the default ignore files and **never** passes `--no-ignore` or
42
+ `--unrestricted` (it refuses those flags, and `--hidden`, outright);
43
+ - excludes lockfiles, minified bundles, source maps, and oversized files via
44
+ `--max-columns` / `--max-filesize`;
45
+ - supports `--files` for cheap discovery with no content reads;
46
+ - caps output (default 200 lines; `--limit N` / `AGENT_SEARCH_LIMIT`).
47
+
48
+ ```bash
49
+ scripts/agent-search.sh --files # candidate files, no content read
50
+ scripts/agent-search.sh -g '*.ts' 'interface Foo'
51
+ scripts/agent-search.sh --limit 50 'TODO'
52
+ ```
53
+
54
+ ### When to use `git grep` instead
55
+
56
+ For a **symbol search over tracked files** (where you want the repo's definition
57
+ of the file set and nothing generated or untracked), `git grep` reads the git
58
+ index and searches tracked files only — no ignore-file dependence, so it is the
59
+ deterministic choice for "where is this symbol defined":
60
+
61
+ ```bash
62
+ git grep -n 'functionName' -- '*.ts' '*.tsx' # tracked files only, reads the index
63
+ git grep -l 'SymbolName' # list matching tracked files
64
+ ```
65
+
66
+ Rule of thumb:
67
+
68
+ - `git grep` — tracked-source symbol search; the index already knows the files
69
+ and ignores are irrelevant. Prefer it for "where is this defined".
70
+ - `scripts/agent-search.sh` (rg) — content search that must also see untracked
71
+ files while still honouring the canonical ignores; best for "what changed
72
+ locally / what's generated". On small warm trees raw `rg` is often the fastest
73
+ of all; `git grep` wins on large trees where tracked-only traversal pays off.
74
+ - Never `rg --no-ignore` / `rg -u` in an agent workspace — it walks `node_modules`
75
+ and build trees and floods both time and context.
76
+
77
+ No harness agent/tool config forces `--no-ignore`; if a local wrapper does,
78
+ remove it and rely on `.ignore` + explicit `-g` globs.
79
+
80
+ ## 2. RAM-backed build/cache storage
81
+
82
+ `scripts/setup-tmpfs.sh` mounts a single tmpfs root (default `/mnt/ramdisk`)
83
+ sized 25–40 % of WSL RAM (default 30 %), then exports cache/build env vars for
84
+ **only the toolchains present**:
85
+
86
+ | Toolchain | Env |
87
+ | --- | --- |
88
+ | Python | `PIP_CACHE_DIR` |
89
+ | npm | `npm_config_cache` |
90
+ | pnpm | `PNPM_STORE_DIR` |
91
+ | Yarn | `YARN_CACHE_FOLDER` |
92
+ | Cargo | `CARGO_TARGET_DIR` |
93
+ | Go | `GOCACHE` |
94
+ | Gradle | `GRADLE_USER_HOME` |
95
+ | ccache / sccache | `CCACHE_DIR` / `SCCACHE_DIR`, `RUSTC_WRAPPER=sccache` |
96
+
97
+ ```bash
98
+ scripts/setup-tmpfs.sh up # mount + write env (idempotent)
99
+ eval "$(scripts/setup-tmpfs.sh env)"
100
+ scripts/setup-tmpfs.sh status
101
+ scripts/setup-tmpfs.sh install # persist: ~/.bashrc hook + systemd --user unit
102
+ scripts/setup-tmpfs.sh down # unmount + drop the env file
103
+ scripts/setup-tmpfs.sh uninstall # down + remove unit + hook
104
+ ```
105
+
106
+ - **Idempotent**: `up` is a no-op mount when the tmpfs is already mounted.
107
+ - **No-op outside WSL**: every action detects WSL (override with
108
+ `AGENT_TMPFS_FORCE=1`).
109
+ - **Persisted per boot / per shell**: `install` writes an idempotent managed
110
+ block into `~/.bashrc` (which runs `ensure` and sources the env file) and, when
111
+ available, a `systemd --user` unit. `ensure` is the quiet variant the hook uses.
112
+ - **Overrides**: `AGENT_RAMDISK`, `AGENT_TMPFS_PERCENT` (clamped 25–40),
113
+ `AGENT_TMPFS_CONFIG`, `AGENT_TMPFS_DRY_RUN=1`.
114
+
115
+ ### Volatility warning
116
+
117
+ tmpfs lives in RAM. A reboot, an OOM kill, a WSL restart, or `down` **erases**
118
+ it. Only **caches and build artifacts** belong there — **never** source code,
119
+ databases, secrets, or git state. `down`/`uninstall` remove the env file so
120
+ new shells fall back to the default on-disk caches.
121
+
122
+ ### tmpfs is not free RAM
123
+
124
+ Because the cache lives in RAM, at the default 30 % of a 10 GB VM it competes
125
+ directly with the emulator and the agents — the hidden third contributor to the
126
+ 2026-09-29 freeze. Keep it small while running device tiers:
127
+
128
+ ```bash
129
+ AGENT_TMPFS_PERCENT=25 scripts/setup-tmpfs.sh up
130
+ ```
131
+
132
+ `serve.js list` and `agent-harness doctor` both report tmpfs usage.
133
+
134
+ ## 3. Machine capacity envelope
135
+
136
+ WSL2 is **one** Linux VM: every agent, worktree, emulator, dev server, and gate
137
+ shares its RAM/CPU/swap, and there is no per-agent cgroup limit. When the working
138
+ set exceeds the VM cap the kernel thrashes reclaim/swap and starves the
139
+ host↔VM **vsock relay** — so every terminal freezes at once. That is a capacity
140
+ failure, not a stuck agent. **Parallel agents are fine; parallel heavy tiers are
141
+ not.**
142
+
143
+ The envelope is project-owned and machine-readable in
144
+ `.agents/memory/orchestration.md` (`min_available_mem_mb`, `max_swap_used_pct`,
145
+ `max_live_serves`, `max_heavy_tiers`, `idle_reap_minutes`, `emulator_ram_mb`,
146
+ `heavy_mem_max_mb`, `group_mem_max_mb`, `backstop_mem_high_mb`,
147
+ `heavy_lock_ttl_minutes`). One owner of the numbers, read by every surface:
148
+
149
+ | Surface | Role |
150
+ | --- | --- |
151
+ | `scripts/qa/capacity-lib.js` | samples `/proc` + PSI + `.serve/`, parses the envelope, owns the machine-wide heavy lock, and delegates command classification to `command-classifier.js` (long-lived vs one-shot), detects whether the real workload cgroup is capped |
152
+ | `scripts/qa/command-classifier.js` | tokenizes the shell and classifies by **program / subcommand / script basename** (peeling `VAR=x` + `env`/`sudo`/`timeout`/`systemd-run` wrappers, resolving interpreters + `npm run`/`npx`, recursing into `--cmd`/`sh -c` payloads). A path or device serial in an argument is never a program, and heredoc bodies are ignored |
153
+ | `scripts/serve.js start` | **refuses** a heavy launch that would exceed the envelope or a held heavy lock (naming what is up); `--force` overrides; caps a heavy tier **by default** (transient `user.slice` unit, `heavy_mem_max_mb`); tightens a `--group` member to the group's remaining `group_mem_max_mb`; `--mem-max`/`--cpu-max` override; `--no-cap` opts out; `list` shows capacity + ages + caps |
154
+ | `scripts/serve.js run` | runs a heavy **one-shot** (build/test tier) in a transient systemd scope with `MemoryMax` (default `heavy_mem_max_mb`, `--mem-max` overrides), streaming output and returning its exit code; leaves no `.serve/` record; the APK build wrapper uses it |
155
+ | `scripts/serve.js prune` | removes `.serve/*.pid` records whose process is gone (all agent worktrees with `--worktrees`) so a stopped heavy tier is never misreported as live |
156
+ | `scripts/serve.js reap` | auto-closes an orphaned/idle serve **after use**: stops one whose owning session's lease is gone/stale (or an untagged one past `idle_reap_minutes` with no recent log activity) and reconciles an untracked `agent-serve-*` unit left by a killed session. Runs at every `start` and on the context-guard `session.deleted` event; never touches a live owner's serve. `stop` verifies the teardown and keeps the record if the process survives |
157
+ | `scripts/qa/check-capacity.js` (`npm run test:capacity`) | reports free RAM/swap/load/PSI/live serves; **fails** when the envelope is already exceeded; skips on non-Linux / `AGENT_CAPACITY_DISABLE=1` |
158
+ | `context-guard` plugin | **blocks** any over-envelope heavy command (long-lived counts as a tier; a one-shot build/test is gated by the free-RAM floor), logs `kind:"capacity"` to `.agents/guard-events.jsonl` |
159
+ | `agent-harness doctor` | capacity + **PSI** + host-aware `.wslconfig` advice + in-WSL tuning status (including whether the cgroup agents actually run in is capped) |
160
+
161
+ A heavy launch (`serve.js start` on an emulator / Metro / Next dev / live tier)
162
+ is capped **by default** — not only when `--mem-max` is passed. It runs as a
163
+ transient `systemd-run --user` unit under `user.slice` with `MemoryMax` from the
164
+ envelope (`heavy_mem_max_mb`, default 5 GB, deliberately above the observed
165
+ emulator peak so normal E2E is never throttled). A runaway is then
166
+ throttled/OOM-killed **inside its cgroup** instead of dragging the VM into
167
+ swap-thrash; it passes the caller's cwd + environment through and is a graceful
168
+ no-op where systemd is absent. `--mem-max`/`--cpu-max` override the default,
169
+ `--no-cap` opts out. Running heavy tiers under `user.slice` is also what makes
170
+ the `user.slice` ceiling below actually bind them (see the backstop note).
171
+
172
+ A heavy **one-shot** — a build or a heavy test tier — is heavy but not a
173
+ long-lived tier, so `serve.js start`'s lock does not cover it. Run it through
174
+ `serve.js run` (a transient `--scope` with `MemoryMax`, streaming output, exit
175
+ code propagated) so it, too, is contained. The 2026-09-30 freeze was exactly a
176
+ miss: an inline `bash .../build-dev-apk.sh` (Gradle daemon + Kotlin daemon + R8)
177
+ ran uncapped while the emulator and `next dev` were up, and the three filled the
178
+ 10 GB VM. The APK wrapper (`scripts/qa/mobile-e2e/build-apk.sh`) now runs the
179
+ build through `serve.js run` and right-sizes Gradle (no daemon, one worker, one
180
+ ABI, 1 GB heap).
181
+
182
+ Classification is on the **program**, never on free text: a read-only command
183
+ that merely mentions a device serial (`adb -s emulator-5554 shell uiautomator
184
+ dump`), a Maestro artifact path (`~/.maestro/tests/…`), or "npm run dev" inside a
185
+ quoted argument/commit message is **not** heavy and is never gated (F-311 — the
186
+ old substring classifier blocked exactly those probes). A live heavy tier that is
187
+ **one `--group`** (the device tier's emulator + dev server) counts as ONE tier,
188
+ whether or not the caller declares the group, so a heavy one-shot legitimately
189
+ runs alongside it (gated only by the free-RAM floor); only a second, unrelated
190
+ long-lived tier is refused. `--force` overrides per command; `AGENT_CAPACITY_DISABLE=1`
191
+ must be set when opencode starts.
192
+
193
+ The machine-wide heavy lock (`~/.agent-harness/heavy.lock`, TTL + dead-pid
194
+ detection) is what lets many agents coexist while guaranteeing **one
195
+ emulator/live tier at a time across sessions**. It is acquired on a heavy
196
+ `serve.js start` and released on `stop`/`stop-all`.
197
+
198
+ ### One-time VM tuning: `scripts/wsl-tune.sh`
199
+
200
+ `doctor` reports whether it is applied; `sudo bash scripts/wsl-tune.sh apply`
201
+ does it all (auto-sudo where passwordless), idempotently:
202
+
203
+ - **sysctls** (`/etc/sysctl.d/99-agent-wsl.conf`): `vm.swappiness=10`,
204
+ bounded dirty ratios, a `min_free_kbytes` floor — less swap/writeback thrash.
205
+ - **user.slice ceiling** (`/etc/systemd/system/user.slice.d/90-agent-cap.conf`):
206
+ `MemoryHigh=8G`, `MemoryMax=9G`, `CPUQuota=800%` — a backstop so user work can
207
+ never consume the whole VM and starve the kernel/relay.
208
+ - **init.scope soft backstop** (`agent-wsl-backstop.service`, enabled): a
209
+ `MemoryHigh` (`backstop_mem_high_mb`, default 8.5 GB) on the cgroup the workload
210
+ actually lives in. This is the important correction: WSL's `wsl.exe` session —
211
+ and so every agent, emulator, and dev server — runs in **`init.scope`**, a
212
+ sibling of `user.slice`, **not** a child, so the ceiling above never binds it.
213
+ `MemoryHigh` is deliberately *soft*: as the line is approached the kernel
214
+ reclaims and throttles instead of thrash-freezing, and it never OOM-kills.
215
+ Verified live: agents/emulators show `ControlGroup=/init.scope` while the
216
+ `user.slice` drop-in applies to a cgroup holding ~4 MB.
217
+ - **`.wslconfig`** keys merged safely by `scripts/qa/wslconfig-merge.js`
218
+ (processors = host CPUs − 4, swap 4 GB, 2 h idle timeout, reclaim on); the
219
+ only manual step is `wsl --shutdown` from Windows PowerShell, because the VM
220
+ must restart. `wsl-tune.sh status` / `down` inspect / remove.
221
+
222
+ Env overrides (also used to test the guards): `AGENT_CAPACITY_MEMINFO`,
223
+ `AGENT_CAPACITY_LOADAVG`, `AGENT_CAPACITY_MOUNTS`, `AGENT_CAPACITY_PSI_DIR`,
224
+ `AGENT_CAPACITY_FORCE_WSL`, `AGENT_CAPACITY_DISABLE`, `AGENT_HEAVY_LOCK`,
225
+ `AGENT_WSL_CONFIG`, `AGENT_HOST_RAM_MB`, `AGENT_HOST_CPUS`,
226
+ `AGENT_TUNING_SYSCTL_DIR`, `AGENT_TUNING_SLICE_FILE`, `AGENT_WSL_TUNE_*`.
227
+
228
+ ## 4. GPU acceleration for the device emulator: `scripts/wsl-gpu.sh`
229
+
230
+ The Android E2E emulator is the slowest, most CPU-bound part of a mobile run:
231
+ on a software renderer each Maestro command costs ~2.5 s and QEMU pins ~3 cores
232
+ just compositing (F-291/F-296). WSL2 can render on the Windows GPU, but Mesa
233
+ does not use it unless two things are true — and on a typical WSL install
234
+ neither is:
235
+
236
+ - **`vgem` must be loaded.** WSL kernels ≥ 2.5 ship `vgem` as a *loadable*
237
+ module and never auto-load it, so `/dev/dri` is absent and the GL stack falls
238
+ back to `llvmpipe` (WSL issues #12702 / #11837). The Windows GPU is still
239
+ exposed at `/dev/dxg`; only the DRM render node is missing.
240
+ - **Mesa must select `d3d12`.** Even with `/dev/dri` present, the default
241
+ renderer stays `llvmpipe`; `GALLIUM_DRIVER=d3d12`
242
+ (`MESA_LOADER_DRIVER_OVERRIDE=d3d12`, with `/usr/lib/wsl/lib` on the loader
243
+ path) is required.
244
+
245
+ ```bash
246
+ bash scripts/wsl-gpu.sh status # /dev/dxg? vgem? which d3d12 renderer?
247
+ bash scripts/wsl-gpu.sh apply # load + persist vgem, verify (auto-sudo)
248
+ bash scripts/wsl-gpu.sh env # print the GL exports for a process
249
+ ```
250
+
251
+ `apply` runs `modprobe vgem` and persists it via
252
+ `/etc/modules-load.d/vgem.conf`, then verifies with a forced-d3d12 `glxinfo`.
253
+ `doctor` warns when `/dev/dxg` exists but `/dev/dri` is missing (the
254
+ not-loaded state). `boot-emulator.sh` probes the same path: it forces the
255
+ `d3d12` driver when `/dev/dxg` is present, and when that reports an accelerated
256
+ renderer it launches the emulator with `-gpu host` **and** the matching
257
+ `GALLIUM_DRIVER`/`MESA_LOADER_DRIVER_OVERRIDE` env (serve.js forwards the
258
+ caller's env into the transient unit). Otherwise it stays on
259
+ `swiftshader_indirect` and prints the `wsl-gpu.sh apply` hint.
260
+
261
+ No-op outside WSL (no `/dev/dxg`). Env: `AGENT_WSL_GPU_DRIVER` (default
262
+ `d3d12`), `AGENT_WSL_GPU_MODULE` (`vgem`), `AGENT_WSL_GPU_MODULES_FILE`,
263
+ `AGENT_WSL_GPU_GLXINFO`, `AGENT_WSL_GPU_FORCE`. If `apply` loads `vgem` but the
264
+ renderer is still software, the Windows GPU driver lacks WSL support — update
265
+ it to the vendor's WSL driver and `wsl --shutdown`.
266
+
267
+ ## 5. Always-loaded prefix: size budget, orient digest, opt-in LSP
268
+
269
+ The always-loaded leading context (root `AGENTS.md` + `.agents/AGENTS.md` +
270
+ `.agents/rules/00-operating.md` + the session-start memory files) is the prompt
271
+ prefix every turn is billed against. Three mechanisms keep it honest:
272
+
273
+ - **Size budget** — `test:prefix` (`scripts/qa/check-prefix-stability.js`) fails
274
+ when a harness-owned prefix file, or their combined size, exceeds the budget
275
+ shipped in the gate. The gate prints each file against its budget; raising it
276
+ must be a deliberate edit. `AGENT_PREFIX_STRICT=0` disables the size check;
277
+ `AGENT_PREFIX_MAX_BYTES` overrides the combined ceiling.
278
+ - **orient digest** — instead of re-reading five memory files at session start,
279
+ `scripts/orient.js` returns a bounded digest per file (its `##` section index
280
+ plus its first markdown table). The `context-guard` plugin injects
281
+ `orient --brief` into the cache-safe conversation tail at session start
282
+ (cleared on the first material action), so a resume/claim prologue re-derives
283
+ nothing by hand.
284
+ - **Opt-in LSP** — opencode LSP is **disabled by default** (opencode's own
285
+ guidance: language servers can be memory-heavy and drift out of sync, and the
286
+ project already runs `tsc`/eslint directly). A project that wants edit-time
287
+ diagnostics may set `"lsp": true` in its own `opencode.json`; the harness merge
288
+ preserves the project key. On a memory-tight WSL2 box, weigh it against the
289
+ capacity envelope (§3) — an LSP server per session adds RSS across parallel
290
+ sessions.
@@ -0,0 +1,188 @@
1
+ {
2
+ "$schema": "https://opencode.ai/config.json",
3
+ "model": "opencode-go/deepseek-v4.1-flash",
4
+ "agents": {
5
+ "title": {
6
+ "model": "opencode-go/glm-5.3-flash"
7
+ },
8
+ "build": {
9
+ "steps": 120
10
+ },
11
+ "explore": {
12
+ "model": "opencode-go/glm-5.3-flash",
13
+ "steps": 40
14
+ }
15
+ },
16
+ "permissions": [
17
+ {
18
+ "action": "external_directory",
19
+ "resource": "{{WORKSPACE_ROOT}}/**",
20
+ "effect": "allow"
21
+ },
22
+ {
23
+ "action": "external_directory",
24
+ "resource": "/tmp/**",
25
+ "effect": "allow"
26
+ },
27
+ {
28
+ "action": "external_directory",
29
+ "resource": "~/AppData/Local/Temp/**",
30
+ "effect": "allow"
31
+ },
32
+ {
33
+ "action": "external_directory",
34
+ "resource": "~/.maestro/**",
35
+ "effect": "allow"
36
+ },
37
+ {
38
+ "action": "external_directory",
39
+ "resource": "~/.android/**",
40
+ "effect": "allow"
41
+ },
42
+ {
43
+ "action": "external_directory",
44
+ "resource": "~/.local/share/opencode/**",
45
+ "effect": "allow"
46
+ },
47
+ {
48
+ "action": "external_directory",
49
+ "resource": "~/.config/opencode/**",
50
+ "effect": "allow"
51
+ },
52
+ {
53
+ "action": "external_directory",
54
+ "resource": "~/.config/agent-harness/**",
55
+ "effect": "allow"
56
+ },
57
+ {
58
+ "action": "external_directory",
59
+ "resource": "/etc/**",
60
+ "effect": "allow"
61
+ },
62
+ {
63
+ "action": "external_directory",
64
+ "resource": "/proc/**",
65
+ "effect": "allow"
66
+ },
67
+ {
68
+ "action": "external_directory",
69
+ "resource": "~/.ssh/**",
70
+ "effect": "deny"
71
+ },
72
+ {
73
+ "action": "external_directory",
74
+ "resource": "~/.aws/**",
75
+ "effect": "deny"
76
+ },
77
+ {
78
+ "action": "external_directory",
79
+ "resource": "~/.gnupg/**",
80
+ "effect": "deny"
81
+ },
82
+ {
83
+ "action": "external_directory",
84
+ "resource": "~/.config/gh/**",
85
+ "effect": "deny"
86
+ },
87
+ {
88
+ "action": "external_directory",
89
+ "resource": "~/.docker/**",
90
+ "effect": "deny"
91
+ },
92
+ {
93
+ "action": "external_directory",
94
+ "resource": "~/.kube/**",
95
+ "effect": "deny"
96
+ },
97
+ {
98
+ "action": "external_directory",
99
+ "resource": "~/.netrc",
100
+ "effect": "deny"
101
+ },
102
+ {
103
+ "action": "external_directory",
104
+ "resource": "~/.git-credentials",
105
+ "effect": "deny"
106
+ },
107
+ {
108
+ "action": "external_directory",
109
+ "resource": "~/.config/opencode/auth.json",
110
+ "effect": "deny"
111
+ },
112
+ {
113
+ "action": "external_directory",
114
+ "resource": "~/.local/share/opencode/auth.json",
115
+ "effect": "deny"
116
+ },
117
+ {
118
+ "action": "edit",
119
+ "resource": "~/.config/opencode/**",
120
+ "effect": "deny"
121
+ },
122
+ {
123
+ "action": "edit",
124
+ "resource": "~/.local/share/opencode/**",
125
+ "effect": "deny"
126
+ },
127
+ {
128
+ "action": "edit",
129
+ "resource": "~/.config/agent-harness/**",
130
+ "effect": "deny"
131
+ },
132
+ {
133
+ "action": "edit",
134
+ "resource": "~/.ssh/**",
135
+ "effect": "deny"
136
+ },
137
+ {
138
+ "action": "edit",
139
+ "resource": "~/.aws/**",
140
+ "effect": "deny"
141
+ },
142
+ {
143
+ "action": "edit",
144
+ "resource": "~/.gnupg/**",
145
+ "effect": "deny"
146
+ },
147
+ {
148
+ "action": "edit",
149
+ "resource": "~/.config/gh/**",
150
+ "effect": "deny"
151
+ },
152
+ {
153
+ "action": "edit",
154
+ "resource": "/etc/**",
155
+ "effect": "deny"
156
+ },
157
+ {
158
+ "action": "edit",
159
+ "resource": "/proc/**",
160
+ "effect": "deny"
161
+ },
162
+ {
163
+ "action": "shell",
164
+ "resource": "sudo *",
165
+ "effect": "deny"
166
+ },
167
+ {
168
+ "action": "shell",
169
+ "resource": "rm -rf /*",
170
+ "effect": "deny"
171
+ },
172
+ {
173
+ "action": "shell",
174
+ "resource": "rm -rf ~",
175
+ "effect": "deny"
176
+ },
177
+ {
178
+ "action": "shell",
179
+ "resource": "rm -rf ~/*",
180
+ "effect": "deny"
181
+ },
182
+ {
183
+ "action": "shell",
184
+ "resource": "rm -rf /tmp/*",
185
+ "effect": "allow"
186
+ }
187
+ ]
188
+ }