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,344 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:concurrency — cross-session working-tree guard (harness-shipped).
5
+ *
6
+ * The anti-collision gate for the single-tree model. The harness shards its own
7
+ * artifacts (qa-plans, handoffs, features) so concurrent sessions never fight
8
+ * over one file — but the git working tree is still shared. A pre-push hook that
9
+ * runs a project gate (`test:quick` → `tsc` + `check-translations`) validates the
10
+ * LIVE tree, so one session's half-done work (e.g. a page referencing translation
11
+ * keys not yet in messages/*.json) makes another session's push fail for no fault
12
+ * of its own.
13
+ *
14
+ * This gate makes that collision *visible and mechanical* instead of surfacing as
15
+ * a random test failure:
16
+ * - clean tree -> pass.
17
+ * - dirty tree + 2+ "In progress" rows -> FAIL: provably another session owns
18
+ * uncommitted work that will leak into pre-push gates.
19
+ * - dirty tree + 1 "In progress" row -> warn (could be your own WIP), pass.
20
+ * - dirty tree + 0 "In progress" rows -> warn (unowned WIP), pass.
21
+ *
22
+ * When a project declares owned files (`.agents/memory/owned-files.md`), the
23
+ * "2+ In progress" case is sharpened: each dirty file is attributed to the
24
+ * in-progress row(s) whose globs match it, so the gate fails *exactly* when
25
+ * files are contended (owned by 2+ rows, or a mix of different sessions) and
26
+ * passes when every dirty file is cleanly owned by a single session.
27
+ *
28
+ * It also reports the live primary sessions sharing this checkout, read from the
29
+ * `.serve/sessions/` leases the context-guard plugin writes (`lease-lib.js` owns
30
+ * the liveness rules: alive pid + matching process birth token + fresh
31
+ * heartbeat, so recycled pids and closed TUIs no longer block a push). That
32
+ * report is ADVISORY: two live sessions on one checkout is a workflow smell, but
33
+ * a clean tree has no WIP to collide over, so the lease count never fails a push
34
+ * by itself — only a dirty tree with provably contended files does. (A hard
35
+ * "2+ live leases" failure here stranded legitimate clean-tree finalizations
36
+ * behind unrelated sessions; the push gate's job is provable contention, not
37
+ * census.)
38
+ *
39
+ * The fix the message points at is either isolation (`backlog worktree <id>`, or
40
+ * `--open` to root the session there), ownership declaration (`backlog owns <id>
41
+ * --files ...`), committing/stashing the foreign work, or — for leases only —
42
+ * `node scripts/qa/check-concurrency.js --prune`. Exit 0 unless the collision is
43
+ * provable.
44
+ */
45
+ const fs = require("fs");
46
+ const path = require("path");
47
+ const { execFileSync } = require("child_process");
48
+ const { splitCells } = require("./board-lib.js");
49
+ const leases = require("./lease-lib.js");
50
+
51
+ const root = path.resolve(__dirname, "..", "..");
52
+
53
+ function git(args) {
54
+ try {
55
+ return execFileSync("git", args, {
56
+ cwd: root,
57
+ encoding: "utf8",
58
+ stdio: ["ignore", "pipe", "pipe"],
59
+ });
60
+ } catch (_) {
61
+ return null;
62
+ }
63
+ }
64
+
65
+ function insideGitRepo() {
66
+ const r = git(["rev-parse", "--is-inside-work-tree"]);
67
+ return !!r && r.trim() === "true";
68
+ }
69
+
70
+ /* Dirty files = tracked changes (M/A/D/R/C) + untracked (`??`). Ignored files
71
+ * (node_modules, build output) never show up here because `status` respects
72
+ * .gitignore. */
73
+ function dirtyFiles() {
74
+ const out = git(["status", "--porcelain"]) || "";
75
+ return out
76
+ .split(/\r?\n/)
77
+ .filter(Boolean)
78
+ .map((l) => ({ code: l.slice(0, 2).trim(), file: l.slice(3) }));
79
+ }
80
+
81
+ /* Live-session leases. The context-guard plugin writes
82
+ * `.serve/sessions/<sessionID>.json` when a PRIMARY session is created, removes
83
+ * it on delete, and heartbeats it on activity. Two or more live leases in THIS
84
+ * tree mean two primary sessions share one checkout — a collision that exists
85
+ * even on a clean tree (and that the dirty-tree heuristics above cannot see).
86
+ * The liveness rules (pid + process birth token + heartbeat) live in
87
+ * `lease-lib.js` so the writer and this reader can never disagree. A lease for a
88
+ * dead or recycled pid, or a stale heartbeat, is not live. */
89
+ function allLeases() {
90
+ return leases.readLeases(root);
91
+ }
92
+
93
+ /* Split a markdown table row on unescaped `|` — shared with backlog.js and the
94
+ * other board gates via board-lib.js (one home for the row parser). */
95
+
96
+ /* ADR 0001: when the board service is the backend, the in-progress rows and the
97
+ * owned-files registry come from the service, not BACKLOG.md / owned-files.md. */
98
+ const boardClient = (() => {
99
+ try {
100
+ return require("./board-client.js");
101
+ } catch {
102
+ return null;
103
+ }
104
+ })();
105
+ const useService = boardClient && boardClient.enabled(root) && !process.argv.includes("--file");
106
+
107
+ /* The active-session IDs: first cell of every table row under `## In progress`. */
108
+ function inProgressIds() {
109
+ if (useService) {
110
+ try {
111
+ return (boardClient.getBoard(root).inprogress || []).map((r) => r.id).filter(Boolean);
112
+ } catch (e) {
113
+ console.log(` \u26a0 board service unreachable (${e.message}) \u2014 treating as no in-progress rows`);
114
+ return [];
115
+ }
116
+ }
117
+ const p = path.join(root, "BACKLOG.md");
118
+ if (!fs.existsSync(p)) return [];
119
+ const lines = fs.readFileSync(p, "utf8").split(/\r?\n/);
120
+ let inSection = false;
121
+ const ids = [];
122
+ for (const raw of lines) {
123
+ const h = raw.match(/^#{2,3}\s+(.*)$/);
124
+ if (h) {
125
+ inSection = /^in progress$/i.test(h[1].trim());
126
+ continue;
127
+ }
128
+ if (!inSection) continue;
129
+ const row = raw.trim();
130
+ if (!/^\|.*\|$/.test(row)) continue;
131
+ const cells = splitCells(row.slice(1, -1));
132
+ if (cells.every((c) => /^[-:|\s]*$/.test(c))) continue; // separator
133
+ if (cells.some((c) => /^(ID|[Ii]d|Task|Handoff)$/.test(c.trim()))) continue; // header
134
+ const id = (cells[0] || "").trim();
135
+ if (id) ids.push(id);
136
+ }
137
+ return ids;
138
+ }
139
+
140
+ /* `.agents/memory/owned-files.md` -> Map<ID, glob[]> (upper-cased IDs). */
141
+ function ownedFilesMap() {
142
+ const map = new Map();
143
+ if (useService) {
144
+ try {
145
+ for (const r of boardClient.getBoard(root).inprogress || []) {
146
+ if (r.owned && r.owned.length) map.set(String(r.id).toUpperCase(), r.owned.slice());
147
+ }
148
+ return map;
149
+ } catch (e) {
150
+ console.log(` \u26a0 board service unreachable (${e.message}) \u2014 no ownership data`);
151
+ return map;
152
+ }
153
+ }
154
+ const p = path.join(root, ".agents", "memory", "owned-files.md");
155
+ if (!fs.existsSync(p)) return map;
156
+ const src = fs.readFileSync(p, "utf8");
157
+ for (const raw of src.split(/\r?\n/)) {
158
+ const m = raw.match(/^\s*[-*]\s+([A-Za-z]+-\d+)\s*:\s*(.+)$/);
159
+ if (m) map.set(m[1].toUpperCase(), m[2].split(/\s*,\s*/).map((s) => s.trim()).filter(Boolean));
160
+ }
161
+ return map;
162
+ }
163
+
164
+ /* Minimal glob -> regex: `**` (any depth), `*` (within a segment), `?` (one char). */
165
+ function globToRegExp(g) {
166
+ let s = "";
167
+ for (let i = 0; i < g.length; i++) {
168
+ const c = g[i];
169
+ if (c === "*") {
170
+ if (g[i + 1] === "*") {
171
+ s += ".*";
172
+ i++;
173
+ } else {
174
+ s += "[^/]*";
175
+ }
176
+ } else if (c === "?") {
177
+ s += "[^/]";
178
+ } else {
179
+ s += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
180
+ }
181
+ }
182
+ return new RegExp("^" + s + "$");
183
+ }
184
+
185
+ function matchesGlob(glob, file) {
186
+ const g = glob.replace(/\\/g, "/").replace(/^\.\//, "");
187
+ const f = file.replace(/\\/g, "/").replace(/^\.\//, "");
188
+ return globToRegExp(g).test(f);
189
+ }
190
+
191
+ const failures = [];
192
+ const warnings = [];
193
+
194
+ console.log("concurrency gate \u2014 a concurrent session's uncommitted work must not leak into your push");
195
+
196
+ if (!insideGitRepo()) {
197
+ console.log(" \u26a0 not a git repo \u2014 concurrency gate skipped");
198
+ console.log("\nRESULT: skipped (0 failures)");
199
+ process.exit(0);
200
+ }
201
+
202
+ /* `--prune` clears dead / recycled / stale leases so a crashed session can never
203
+ * block the gate (the plugin also sweeps on startup). */
204
+ if (process.argv.slice(2).includes("--prune")) {
205
+ const removed = leases.pruneLeases(root);
206
+ for (const r of removed) console.log(` - removed ${r.sessionID} (pid ${r.pid}, ${r.reason})`);
207
+ if (!removed.length) console.log(" no dead/recycled/stale leases to prune");
208
+ console.log(`\nRESULT: pruned ${removed.length} stale lease(s)`);
209
+ process.exit(0);
210
+ }
211
+
212
+ /* Live primary sessions sharing one tree are ADVISORY, never a clean-tree push
213
+ * blocker. Only leases whose pid is alive AND matches the recorded process birth
214
+ * token AND has a fresh heartbeat count — a recycled pid (the 0.1.67 bug) or a
215
+ * lease leaked by a closed TUI is not live. The hard failure lives on provable
216
+ * contention below (dirty tree + overlapping ownership), not on a session count:
217
+ * a clean tree has no WIP for another session's work to leak into, so it always
218
+ * pushes. */
219
+ const all = allLeases();
220
+ const live = all.filter((r) => leases.leaseStatus(r).live);
221
+ const ghosts = all.filter((r) => !leases.leaseStatus(r).live);
222
+ if (ghosts.length) {
223
+ console.log(
224
+ ` \u2139 ${ghosts.length} stale lease(s) present but ignored \u2014 clear them with ` +
225
+ `\`node scripts/qa/check-concurrency.js --prune\`.`
226
+ );
227
+ }
228
+ if (live.length > 1) {
229
+ console.log(` \u26a0 ${live.length} live sessions share this working tree (advisory report):`);
230
+ for (const r of live) console.log(` ${leases.describeLease(r)}`);
231
+ console.log(
232
+ " Two primary sessions on one checkout should isolate: start each in its own\n" +
233
+ " feature worktree (`backlog worktree <id> --open`). A clean tree still pushes."
234
+ );
235
+ }
236
+
237
+ const dirty = dirtyFiles();
238
+ if (dirty.length === 0) {
239
+ console.log(" \u2713 working tree clean \u2014 nothing for another session's WIP to leak in");
240
+ console.log("\nRESULT: green");
241
+ process.exit(0);
242
+ }
243
+
244
+ for (const d of dirty) console.log(` ${d.code} ${d.file}`);
245
+
246
+ const ids = inProgressIds();
247
+ const active = ids.length;
248
+
249
+ // The one file the ownership model cannot cleanly assign is BACKLOG.md itself:
250
+ // the board is genuinely shared across every In-progress session (each session's
251
+ // board tools write rows into the same file on main). When 2+ sessions are In
252
+ // progress AND the shared board is dirty, we cannot tell whose uncommitted row
253
+ // edits the tree holds — that is exactly the collision `test:concurrency` exists
254
+ // to catch, so it FAILS instead of being tolerated as a warning. (A single
255
+ // In-progress session's board delta is that session's own WIP and is handled by
256
+ // the existing warn branches below.)
257
+ const boardDirty = dirty.some((d) => (d.file || "").replace(/\\/g, "/") === "BACKLOG.md");
258
+ if (boardDirty && active >= 2) {
259
+ failures.push(
260
+ `the shared BACKLOG.md is dirty while ${active} sessions are In progress (${ids.join(", ")}) ` +
261
+ `\u2014 the board is one file every session writes on main, so this tree mixes two sessions' board deltas. ` +
262
+ `Commit/stash this board delta before push (it belongs to ONE session), then re-run the gate.`
263
+ );
264
+ console.log(" \u2717 " + failures[failures.length - 1]);
265
+ console.log(
266
+ "\nRESULT: " +
267
+ `${failures.length} FAILURE(S) \u2014 isolate, stash, or commit before push`
268
+ );
269
+ process.exit(1);
270
+ }
271
+
272
+ if (active > 1) {
273
+ // Ownership-aware attribution: if the project declared owned files
274
+ // (`.agents/memory/owned-files.md`), attribute each dirty file to the
275
+ // in-progress row(s) whose globs match it. This makes the collision check
276
+ // precise instead of coarse: fail exactly when dirty files are contended
277
+ // (owned by 2+ rows, or a mix of different rows), pass when they are cleanly
278
+ // attributable to a single session.
279
+ const owns = ownedFilesMap();
280
+ const overlaps = [];
281
+ const ownerOf = new Map();
282
+ const distinctOwners = new Set();
283
+ for (const d of dirty) {
284
+ const owners = [];
285
+ for (const id of ids) {
286
+ const globs = owns.get(id);
287
+ if (globs && globs.some((g) => matchesGlob(g, d.file))) owners.push(id);
288
+ }
289
+ if (owners.length >= 2) overlaps.push({ file: d.file, rows: owners });
290
+ else if (owners.length === 1) {
291
+ ownerOf.set(d.file, owners[0]);
292
+ distinctOwners.add(owners[0]);
293
+ }
294
+ }
295
+
296
+ if (overlaps.length) {
297
+ for (const o of overlaps) {
298
+ failures.push(
299
+ `"${o.file}" is owned by ${o.rows.length} In-progress rows (${o.rows.join(", ")}) ` +
300
+ `\u2014 two sessions contend on the same file. Reassign ownership (backlog owns <id> --files ...) ` +
301
+ `or isolate (backlog worktree <id>) before push.`
302
+ );
303
+ console.log(" \u2717 " + failures[failures.length - 1]);
304
+ }
305
+ } else if (ownerOf.size === dirty.length && distinctOwners.size >= 2) {
306
+ failures.push(
307
+ `uncommitted files are owned by ${distinctOwners.size} DIFFERENT In-progress sessions (${[...distinctOwners].join(", ")}) ` +
308
+ `\u2014 this tree mixes two sessions' WIP. Isolate per feature (backlog worktree <id>) before push.`
309
+ );
310
+ console.log(" \u2717 " + failures[failures.length - 1]);
311
+ } else if (ownerOf.size === dirty.length) {
312
+ warnings.push(
313
+ `dirty tree with ${active} In-progress rows, but every uncommitted file is owned by a single session ` +
314
+ `(${[...distinctOwners].join(", ")}) \u2014 no cross-session overlap detected. Commit before push.`
315
+ );
316
+ console.log(" \u26a0 " + warnings[warnings.length - 1]);
317
+ } else {
318
+ failures.push(
319
+ `${active} sessions are In progress (${ids.join(", ")}) while the working tree has ${dirty.length} uncommitted change(s) ` +
320
+ `\u2014 a session other than the one pushing owns uncommitted work that will leak into pre-push gates. ` +
321
+ `Isolate per feature (backlog worktree <id>), declare ownership (backlog owns <id> --files ...), or stash/commit before push.`
322
+ );
323
+ console.log(" \u2717 " + failures[failures.length - 1]);
324
+ }
325
+ } else if (active === 1) {
326
+ warnings.push(
327
+ `working tree is dirty with 1 session In progress (${ids[0]}) \u2014 if these uncommitted files belong to a ` +
328
+ `DIFFERENT session, isolate them (backlog worktree) or stash before push; if they are yours, commit them first.`
329
+ );
330
+ console.log(" \u26a0 " + warnings[warnings.length - 1]);
331
+ } else {
332
+ warnings.push(
333
+ "working tree is dirty with no In progress rows \u2014 uncommitted work with no owner on the board; commit or stash it."
334
+ );
335
+ console.log(" \u26a0 " + warnings[warnings.length - 1]);
336
+ }
337
+
338
+ console.log(
339
+ "\nRESULT: " +
340
+ (failures.length
341
+ ? `${failures.length} FAILURE(S) \u2014 isolate, stash, or commit before push`
342
+ : "green (dirty tree tolerated \u2014 see warnings)")
343
+ );
344
+ process.exit(failures.length ? 1 : 0);
@@ -0,0 +1,296 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:dispatch — opencode dispatch-config preflight (repo guard gate).
5
+ *
6
+ * Verifies every persona dispatch target is mechanically sound BEFORE work
7
+ * starts, so a broken subagent config can never ship silently:
8
+ * 1. Every `.opencode/agents/<name>.md` pins a `model:` that is a REAL
9
+ * provider model (frozen allowlist seeded from `opencode models`).
10
+ * 2. Personas are 1:1: every `.agents/skills/<name>/SKILL.md` has a matching
11
+ * `.opencode/agents/<name>.md` and vice-versa (no path/skill drift).
12
+ * 3. Every agent body carries the output-contract marker (Result / Evidence /
13
+ * Deferred & risks) so subagents return a consistent report shape.
14
+ * 4. `opencode.json` main `model` + `agents.title.model` (the small-model pin)
15
+ * and every `agents.<name>.model` override (e.g. the opportunistic
16
+ * `explore` pin) are real provider IDs.
17
+ * 5. `.agents/memory/model-routing.md` does not name a concrete model that is
18
+ * no longer pinned by any agent or opencode.json (doc↔config drift) —
19
+ * except IDs declared on a machine-readable `opportunistic_models:` /
20
+ * `escalation_models:` / `fallback_models:` line (legal targets,
21
+ * deliberately unpinned).
22
+ * 6. Every bash-enabled editor carries the working-tree gate (verify
23
+ * `git rev-parse --show-toplevel` + branch before editing) so a subagent
24
+ * can never silently edit the wrong checkout/worktree.
25
+ *
26
+ * Allowlist refresh (only when the provider adds/removes models):
27
+ * npx opencode models > scripts/qa/models.allowlist.txt
28
+ * then DELETE every `opencode/*` (Zen pay-as-you-go) line — the routing policy
29
+ * is OpenCode Go (`opencode-go/*`) + DeepSeek direct (`deepseek/*`) only, and
30
+ * this gate fails if a Zen line is present. Never edit agent `model:` without
31
+ * re-running this check.
32
+ */
33
+ const fs = require("fs");
34
+ const path = require("path");
35
+ const root = path.resolve(__dirname, "..", "..");
36
+ const agentsDir = path.join(root, ".opencode", "agents");
37
+ const skillsDir = path.join(root, ".agents", "skills");
38
+ const allowlistFile = path.join(__dirname, "models.allowlist.txt");
39
+ const opencodeJson = path.join(root, "opencode.json");
40
+
41
+ const failures = [];
42
+ const warnings = [];
43
+ const pass = (m) => console.log(" \u2713 " + m);
44
+ const fail = (m) => {
45
+ failures.push(m);
46
+ console.log(" \u2717 " + m);
47
+ };
48
+ const warn = (m) => {
49
+ warnings.push(m);
50
+ console.log(" \u26a0 " + m);
51
+ };
52
+
53
+ if (!fs.existsSync(allowlistFile)) {
54
+ console.error(
55
+ "FATAL: missing allowlist. Generate it: `npx opencode models > scripts/qa/models.allowlist.txt`"
56
+ );
57
+ process.exit(2);
58
+ }
59
+ const allowlist = new Set(
60
+ fs
61
+ .readFileSync(allowlistFile, "utf8")
62
+ .split(/\r?\n/)
63
+ .map((l) => l.trim())
64
+ .filter(Boolean)
65
+ );
66
+
67
+ console.log("dispatch preflight \u2014 persona model pins vs provider allowlist");
68
+
69
+ // 0. no Zen pay-as-you-go targets: the policy is OpenCode Go + DeepSeek direct
70
+ // only, so `opencode/*` must never be an allowed pin (a regenerated allowlist
71
+ // re-adds it — delete those lines, don't relax the policy).
72
+ const zenLines = [...allowlist].filter((m) => /^opencode\//.test(m));
73
+ if (zenLines.length) {
74
+ fail(
75
+ `allowlist has ${zenLines.length} Zen pay-as-you-go model(s) (${zenLines.slice(0, 3).join(", ")}${zenLines.length > 3 ? ", ..." : ""}) — ` +
76
+ "policy is opencode-go/* + deepseek/* only; remove them"
77
+ );
78
+ }
79
+
80
+ function frontmatterModelRaw(file) {
81
+ const src = fs.readFileSync(file, "utf8");
82
+ const m = src.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---\r?\n/m);
83
+ if (!m) return null;
84
+ const modelLine = m[1].split(/\r?\n/).find((l) => /^model:/i.test(l.trim()));
85
+ return modelLine ? modelLine.replace(/^model:\s*/i, "").trim() : null;
86
+ }
87
+
88
+ function frontmatterModel(file) {
89
+ const raw = frontmatterModelRaw(file);
90
+ // Native V2 pins join the variant to the model (`provider/model#variant`); the
91
+ // provider allowlist holds base IDs, so strip any `#variant` before matching.
92
+ return raw ? raw.replace(/#.*$/, "") : null;
93
+ }
94
+
95
+ /* The agent's `mode:` frontmatter (primary | subagent | all). A new custom agent
96
+ * defaults to `primary`; every harness persona is `subagent`. */
97
+ function frontmatterMode(file) {
98
+ const src = fs.readFileSync(file, "utf8");
99
+ const m = src.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---\r?\n/m);
100
+ if (!m) return null;
101
+ const line = m[1].split(/\r?\n/).find((l) => /^mode:/i.test(l.trim()));
102
+ return line ? line.replace(/^mode:\s*/i, "").trim().toLowerCase() : null;
103
+ }
104
+
105
+ /* Does a `provider/model#variant` pin actually take effect? Only on a
106
+ * `mode: subagent` agent's `model:` (frontmatter). A `#variant` on the PRIMARY
107
+ * session — the root `model` or `agents.<primary>.model` (`build`/`plan`) — is
108
+ * inert (opencode 2.0.31, verified 2026-10-17 by live probe: root `…#high` and
109
+ * `agents.build.model=…#high` both recorded `variant:"default"`, while an
110
+ * explicit session model — `-m provider/model#variant`/the TUI picker — and a
111
+ * subagent's `…#low` were preserved). So a `#variant` on a non-subagent is
112
+ * inert config that reads like enforcement. */
113
+ function variantApplies(mode) {
114
+ return mode === "subagent";
115
+ }
116
+
117
+ /* Parse the agent's native V2 `permissions:` list from the frontmatter into
118
+ * `{ action, resource, effect }` entries (order preserved). */
119
+ function frontmatterPermissions(file) {
120
+ const src = fs.readFileSync(file, "utf8");
121
+ const m = src.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---\r?\n/m);
122
+ if (!m) return [];
123
+ const lines = m[1].split(/\r?\n/);
124
+ const perms = [];
125
+ let inPerm = false;
126
+ let cur = null;
127
+ for (const raw of lines) {
128
+ const indent = raw.length - raw.trimStart().length;
129
+ const t = raw.trim();
130
+ if (/^permissions:\s*$/.test(t)) {
131
+ inPerm = true;
132
+ continue;
133
+ }
134
+ if (!inPerm) continue;
135
+ if (indent === 0 && t) break;
136
+ if (/^-\s+action:/.test(t)) {
137
+ cur = { action: t.replace(/^-\s+action:\s*/, "").trim(), resource: "", effect: "" };
138
+ perms.push(cur);
139
+ continue;
140
+ }
141
+ if (!cur) continue;
142
+ let mm;
143
+ if ((mm = t.match(/^resource:\s*(.+)$/))) cur.resource = mm[1].trim();
144
+ else if ((mm = t.match(/^effect:\s*(.+)$/))) cur.effect = mm[1].trim();
145
+ }
146
+ return perms;
147
+ }
148
+
149
+ function escapeRe(s) {
150
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
151
+ }
152
+
153
+ // 1. every agent file exists, pins a real model, references a real skill
154
+ const agentModels = new Set();
155
+ const agentNames = fs
156
+ .readdirSync(agentsDir)
157
+ .filter((f) => f.endsWith(".md"))
158
+ .sort();
159
+ if (agentNames.length === 0) fail(`no agents found in ${agentsDir}`);
160
+ for (const f of agentNames) {
161
+ const name = f.replace(/\.md$/, "");
162
+ const file = path.join(agentsDir, f);
163
+ const model = frontmatterModel(file);
164
+ if (model) agentModels.add(model);
165
+ const body = fs.readFileSync(file, "utf8");
166
+ const skillMd = path.join(skillsDir, name, "SKILL.md");
167
+ if (!model) fail(`agent ${f}: missing frontmatter model: (all agents must pin a model)`);
168
+ else if (!allowlist.has(model)) fail(`agent ${f}: model \`${model}\` NOT in provider allowlist`);
169
+ else pass(`agent ${name}: model \`${model}\` is a real provider model`);
170
+ if (!fs.existsSync(skillMd)) fail(`agent ${name}: referenced skill missing \`${path.relative(root, skillMd)}\``);
171
+ if (!/return your final message in this exact order[\s\S]*Deferred & risks/i.test(body))
172
+ fail(`agent ${name}: missing output-contract marker (Result -> Evidence -> Deferred & risks)`);
173
+ const canBash = frontmatterPermissions(file).some((p) => p.action === "shell" && p.effect === "allow");
174
+ if (canBash && !/git rev-parse --show-toplevel/.test(body))
175
+ fail(`agent ${name}: shell-enabled editor missing the working-tree gate (verify \`git rev-parse --show-toplevel\` + branch before editing)`);
176
+ // A `#variant` on a NON-subagent (primary) agent is inert in V2: the session
177
+ // stores its own model and drops the agent variant (verified 2026-10-17).
178
+ const rawModel = frontmatterModelRaw(file);
179
+ const mode = frontmatterMode(file);
180
+ if (rawModel && rawModel.includes("#") && !variantApplies(mode))
181
+ fail(
182
+ `agent ${name}: model variant \`${rawModel}\` does NOT apply — mode is \`${mode || "primary"}\`, ` +
183
+ "and opencode V2 ignores a variant on a primary agent's model (the session model is separate). " +
184
+ "Pin variants on `mode: subagent` agents only, or drop the variant."
185
+ );
186
+ }
187
+
188
+ // 2. bidirectional parity: every skill dir has a matching agent file
189
+ const skillNames = fs
190
+ .readdirSync(skillsDir)
191
+ .filter((f) => fs.statSync(path.join(skillsDir, f)).isDirectory())
192
+ .sort();
193
+ const agentSet = new Set(agentNames.map((f) => f.replace(/\.md$/, "")));
194
+ const skillSet = new Set(skillNames);
195
+ for (const s of skillNames) if (!agentSet.has(s)) fail(`skill ${s}: no matching .opencode/agents/${s}.md`);
196
+ for (const a of agentSet) if (!skillSet.has(a)) fail(`agent ${a}: no matching .agents/skills/${a}/SKILL.md`);
197
+ if (skillNames.join("|") === [...agentNames].map((f) => f.replace(/\.md$/, "")).sort().join("|"))
198
+ pass(`persona parity: ${agentNames.length} agents == ${skillNames.length} skills`);
199
+
200
+ // 3. opencode.json main model + every `agents.<name>.model` override (the V2
201
+ // small-model pin lives on the built-in `title` agent; `explore` is the
202
+ // opportunistic pin) are real provider IDs.
203
+ const configModels = new Set();
204
+ if (fs.existsSync(opencodeJson)) {
205
+ const cfg = JSON.parse(fs.readFileSync(opencodeJson, "utf8"));
206
+ const checkModel = (label, raw) => {
207
+ // Strip any `#variant` so the base ID is checked against the allowlist.
208
+ const v = raw ? String(raw).replace(/#.*$/, "") : raw;
209
+ if (!v) {
210
+ warn(`opencode.json: no \`${label}\` set`);
211
+ return;
212
+ }
213
+ configModels.add(v);
214
+ if (allowlist.has(v)) pass(`opencode.json ${label} \`${v}\` is a real provider model`);
215
+ else fail(`opencode.json ${label} \`${v}\` NOT in provider allowlist`);
216
+ };
217
+ checkModel("model", cfg.model);
218
+ // A `#variant` on the root `model` is inert too: opencode drops it for the
219
+ // primary session (verified 2026-10-17 — `model: …#high` recorded `default`).
220
+ // Effort for the main session can only be set per-session (`-m`/the TUI pick).
221
+ if (String(cfg.model || "").includes("#"))
222
+ fail(
223
+ `opencode.json model \`${cfg.model}\` carries a \`#variant\` that does NOT apply — ` +
224
+ "opencode V2 drops a variant on the root `model` for the primary session. Pin variants on " +
225
+ "`mode: subagent` agents only, or drop it (the orchestrator effort is a per-session choice)."
226
+ );
227
+ const cfgAgents = cfg.agents && typeof cfg.agents === "object" ? cfg.agents : {};
228
+ if (!cfgAgents.title || !cfgAgents.title.model)
229
+ warn("opencode.json: no `agents.title.model` (V2 small-model) set");
230
+ for (const [name, agentCfg] of Object.entries(cfgAgents)) {
231
+ const v = agentCfg && typeof agentCfg === "object" ? agentCfg.model : null;
232
+ if (!v) continue;
233
+ checkModel(`agents.${name}.model`, v);
234
+ // An opencode.json `agents.<name>.model` with `#variant` is inert for a
235
+ // PRIMARY session: V2 keeps the session model separate and the root `model`
236
+ // drops the variant (built-ins `build`/`plan` are primary; `title`/`explore`
237
+ // are hidden/subagent). Express the effort as a subagent frontmatter pin.
238
+ if (String(v).includes("#")) {
239
+ const mode = agentCfg && typeof agentCfg === "object" ? agentCfg.mode : null;
240
+ if (!variantApplies(mode))
241
+ fail(
242
+ `opencode.json agents.${name}.model \`${v}\` carries a \`#variant\` that does NOT apply — ` +
243
+ "opencode V2 ignores a variant on an opencode.json agent model; the primary session model is " +
244
+ "the root `model` (which drops `#variant`). Move the effort to a `mode: subagent` agent's " +
245
+ "frontmatter `model:`, or drop the variant."
246
+ );
247
+ }
248
+ }
249
+ } else warn("opencode.json not found (skip)");
250
+
251
+ // 4. model-routing.md ↔ model: pin consistency (doc↔config drift).
252
+ // Concrete IDs on a machine-readable `opportunistic_models:` / `escalation_models:`
253
+ // / `fallback_models:` line are DECLARED TARGETS (legal tiers, deliberately not
254
+ // pinned) — they pass the drift check without a matching pin; every other concrete
255
+ // ID must be pinned.
256
+ const declaredTargets = new Set();
257
+ const targetTiers = new Map();
258
+ const usedModels = new Set([...agentModels, ...configModels]);
259
+ const modelRoutingFile = path.join(root, ".agents", "memory", "model-routing.md");
260
+ if (fs.existsSync(modelRoutingFile)) {
261
+ const doc = fs.readFileSync(modelRoutingFile, "utf8");
262
+ for (const m of doc.matchAll(/^(opportunistic|escalation|fallback)_models:\s*(.+)$/gim)) {
263
+ const tier = m[1].toLowerCase();
264
+ for (const id of m[2].split(/[,\s]+/).map((s) => s.trim()).filter(Boolean)) {
265
+ if (/^`?(opportunistic|escalation|fallback)_models:`?$/i.test(id)) continue;
266
+ declaredTargets.add(id);
267
+ targetTiers.set(id, tier);
268
+ }
269
+ }
270
+ // Longest-first alternation so a declared `...-contributor-free` ID is never
271
+ // clipped to a shorter allowlist entry that shares its prefix.
272
+ const modelPattern = [...allowlist].sort((a, b) => b.length - a.length).map(escapeRe).join("|");
273
+ const mentioned = new Set();
274
+ const re = new RegExp(modelPattern, "g");
275
+ let m;
276
+ while ((m = re.exec(doc)) !== null) mentioned.add(m[0]);
277
+ if (mentioned.size === 0) {
278
+ pass("model-routing.md names no concrete model IDs (tier policy only) — nothing to cross-check");
279
+ } else {
280
+ for (const mid of mentioned) {
281
+ if (usedModels.has(mid)) pass(`model-routing.md \`${mid}\` matches an actual pin`);
282
+ else if (declaredTargets.has(mid))
283
+ pass(`model-routing.md \`${mid}\` is a declared ${targetTiers.get(mid)} target (not a pin)`);
284
+ else fail(`model-routing.md references \`${mid}\` but no agent/config pins it (doc↔config drift)`);
285
+ }
286
+ }
287
+ } else {
288
+ warn("model-routing.md not found (skip doc↔config drift check)");
289
+ }
290
+
291
+ console.log(
292
+ `\nRESULT: ${agentNames.length} agents checked \u2014 ` +
293
+ (failures.length ? `${failures.length} FAILURE(S)` : "0 failures") +
294
+ (warnings.length ? `, ${warnings.length} warning(s)` : "")
295
+ );
296
+ process.exit(failures.length ? 1 : 0);