opencode-agent-harness 0.2.0 → 0.3.15

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 CHANGED
@@ -1,5 +1,206 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.15 — 2026-11-21
4
+
5
+ - The Release workflow pins npm 11 instead of `npm@latest`: npm 12 changed
6
+ `npm pack --json` output (an empty array) and broke `test:pack` before the
7
+ publish step, so auto-releases failed before npm trusted publishing could
8
+ run. npm 11 keeps OIDC publishing while the pack gate passes. (F-011)
9
+
10
+ ## 0.3.14 — 2026-11-21
11
+
12
+ - Version bumps now reach npm automatically: after a green `main` CI run,
13
+ `.github/workflows/auto-tag.yml` creates the missing `v<package.json version>`
14
+ tag and dispatches `release.yml` (which gains `workflow_dispatch`). The release
15
+ publishes with npm trusted publishing (OIDC), so no long-lived `NPM_TOKEN` is
16
+ stored. A tag pushed with the workflow token cannot trigger another workflow,
17
+ hence the explicit dispatch. (F-010)
18
+
19
+ ## 0.3.13 — 2026-11-21
20
+
21
+ - Every green `CI` run on `main` now redeploys the harness into LibraryOS
22
+ (`.github/workflows/deploy-libraryos.yml`): it checks out the CI-tested
23
+ commit plus `dombaras/LibraryOS`, runs `agent-harness update` against it, and
24
+ lets the updater commit/push the `chore(harness)` release. A write-scoped
25
+ deploy key is stored as `LIBRARYOS_DEPLOY_KEY`; `update` is idempotent, so a
26
+ landing that changes no harness file commits nothing. This closes the gap
27
+ that left LibraryOS at v0.3.8 while the harness was v0.3.12. (F-009)
28
+
29
+ ## 0.3.12 — 2026-11-21
30
+
31
+ - `backlog sync` no longer refuses a behind-only checkout just because an
32
+ unrelated tracked file is dirty. It attempts the fast-forward and lets git
33
+ protect the dirty file: unrelated edits are carried across, and only a file
34
+ the landing would overwrite fails closed (with git's own error line). This
35
+ previously stranded `main` one commit behind on an uncommitted config toggle
36
+ the landing never touched. (F-008)
37
+ - Removed the accidentally tracked `node_modules` symlink from the release
38
+ tree. (`7049179`)
39
+
40
+ ## 0.3.11 — 2026-11-21
41
+
42
+ - Archiving a row from a linked feature worktree no longer writes that
43
+ worktree's inherited board snapshot. The archive exception now applies only to
44
+ a row the branch itself claimed (In progress), so a subsumed Open row is
45
+ archived on the canonical board. Previously such an archive stranded in the
46
+ feature checkout after its branch had already landed and had to be redone by
47
+ hand from main. (F-007)
48
+
49
+ ## 0.3.10 — 2026-11-21
50
+
51
+ - Board publishing no longer aborts on the gitignored (but tracked)
52
+ `.agents/memory/owned-files.md`: `publishBoard` force-stages its explicit
53
+ tracked extras, and every add/commit/push failure carries git's first error
54
+ line. `backlog.js` prints that detail and whether the change is committed or
55
+ only in the working tree, instead of a fixed "remote unreachable" note that
56
+ masked local git failures for weeks. (F-004)
57
+ - `test:docs` skips link-shaped inline code spans (an API example such as
58
+ ``plugin["tool.execute.before"](...)`` is not a markdown link), and
59
+ `test:backlog` no longer counts `templates/BACKLOG.md` as a stray board, so
60
+ both gates run green and can be enforced instead of rotting. (F-004)
61
+
62
+ ## 0.3.9 — 2026-11-21
63
+
64
+ - `update` adopts harness-owned files whose working bytes already match the
65
+ release but are still uncommitted against HEAD. A deploy that wrote a file
66
+ but skipped it in its `chore(harness)` commit no longer leaves invisible
67
+ drift: `.harness.json` records the worktree hash, so every later update saw
68
+ "unchanged" and nothing was ever committed (the LibraryOS 0.3.8 case —
69
+ `scripts/board-service.sh`, `finalize.js`, `qa/run-gates.js`, `wsl-tune.sh`
70
+ needed a manual commit). The adopted files join the harness commit; a path
71
+ whose staged bytes belong to another session is left in the index untouched.
72
+
73
+ ## 0.3.8 — 2026-11-21
74
+
75
+ - `check-flows.js` no longer rejects a valid journey matrix: a `*TestID` prop
76
+ that is forwarded resolves to the element's `testID` at runtime, so only a
77
+ literal-free or unknown target is a violation; `runFlow: file:` includes are
78
+ validated recursively — a missing file, an escape outside `flows/`, or an
79
+ include cycle is reported against the journey instead of failing later as a
80
+ Maestro timeout. Ported byte-for-byte from LibraryOS's project-proven copy so
81
+ it has an upstream release identity. (03f3013)
82
+
83
+ ## 0.3.7 — 2026-11-21
84
+
85
+ - `update` refuses to deploy from an uncommitted `templates/` tree and refuses
86
+ `--no-commit` for a real deploy, so a release can never land downstream as
87
+ untracked project WIP (the 2026-11-20 LibraryOS 0.3.6 incident). `--dry-run`
88
+ previews; `--allow-dirty-templates` is the deliberate harness-development
89
+ override. (0b97dc3)
90
+ - `wsl-tune` resolves the node binary instead of assuming PATH, because sudo
91
+ resets it to the secure_path: a user-local node (nvm/volta/fnm/~/.local/bin)
92
+ no longer makes the `.wslconfig` merge die with a bare
93
+ `node: command not found` after the root tunables landed; under sudo the
94
+ merge runs as the invoking user, and a failed merge is reported as one.
95
+ (aa22740)
96
+ - The board-service systemd unit pins the generating node's directory in
97
+ `PATH`: systemd --user's default PATH omits user-level Node installs, so
98
+ `next`'s `#!/usr/bin/env node` shebang made the service restart-loop with
99
+ exit 127. (5c4516b)
100
+
101
+ ## 0.3.6 — 2026-11-20
102
+
103
+ - Finalization now closes the loop instead of reporting drift. `finalize` stages
104
+ its tail with `git add -u` + explicit untracked adds, refusing generated paths,
105
+ symlinks, other features' handoffs, and a stray worktree `BACKLOG.md` when the
106
+ board service owns the board (the `git add -A` sweep had committed a
107
+ `prisma/generated` symlink and could commit another session's work); after
108
+ landing it fast-forwards a clean main checkout and prints the remaining
109
+ close-out actions. NEW `scripts/qa/worktree-hygiene.js` reports main-checkout
110
+ drift + merged/clean leftover worktrees, and `test:worktrees`
111
+ (`scripts/qa/check-worktrees.js`, wired into the `process` gate phase and
112
+ skipped on CI) fails when a landing left either behind.
113
+ - `update` no longer fails closed on the root `AGENTS.md` because `next dev`
114
+ appended its `<!-- BEGIN:nextjs-agent-rules -->` block: the drift check and the
115
+ deploy write now compare the harness-owned content with that tool-owned block
116
+ stripped, so a marker-only difference is neither a hand-edit nor a rewrite
117
+ (which previously made `next dev` re-append the block on the next run). A real
118
+ edit to the harness-owned part is still refused. (F-349)
119
+ - The worktree-hygiene guard scripts (`scripts/qa/worktree-hygiene.js`,
120
+ `scripts/qa/check-worktrees.js`) are committed at the repo root even though
121
+ `/scripts` is gitignored, so a fresh clone gets `test:worktrees` instead of
122
+ silently running nothing. (b68e1bc)
123
+
124
+ ## 0.3.5 — 2026-11-20
125
+
126
+ - Shipped the `.agents/reviews/` scaffolding for review deliverables (ebe9dd8).
127
+ - Trimmed the canonical rulebook (`templates/.agents/AGENTS.md`) from ~47 KB to
128
+ ~27 KB by removing the operating mechanics that duplicate the always-on root
129
+ `AGENTS.md` and `.agents/rules/00-operating.md` (dispatch economics, retry/gate
130
+ discipline, context budget, capacity guards, finalize/reporting). The rulebook
131
+ now carries the durable standards and points at the summary for mechanics;
132
+ test-pinned rules and every section number are preserved.
133
+ - Lowered the `test:prefix` size budget for the rulebook (48 -> 28 KiB) and the
134
+ combined harness-owned ceiling (87 -> 69 KiB), so the dedupe is locked in and
135
+ the prefix cannot silently regrow.
136
+
137
+ ## 0.3.4 — 2026-11-20
138
+
139
+ - Added a durable per-project backend pin: `.harness.json`
140
+ `"board": { ..., "backend": "file" }` keeps a project on the legacy file board
141
+ without relying on a shell export (useful when the service is not provisioned
142
+ on that machine). `backend: "service"` pins the service; `BACKLOG_BACKEND`
143
+ remains the per-environment override, and `--root` still forces file mode for
144
+ migration/tests. The pin survives `update` because `.harness.json` merges
145
+ project fields.
146
+
147
+ ## 0.3.3 — 2026-11-20
148
+
149
+ - Refined worktree archive routing: a row already in the worktree's board
150
+ snapshot still archives there and rides the feature branch (finalize
151
+ semantics), while a row captured after the branch was cut exists only on main
152
+ and now archives on main instead of failing with "no row in BACKLOG.md".
153
+
154
+ ## 0.3.2 — 2026-11-20
155
+
156
+ - Board capture/claim/read commands are project-scoped, never checkout-scoped.
157
+ A `backlog` run inside a linked feature worktree now resolves to the shared
158
+ board service — or, in legacy file mode, to the MAIN checkout's board — so a
159
+ row captured mid-feature (the LibraryOS Next.js security finding filed in an
160
+ f-002 worktree) reaches the main board immediately instead of a private
161
+ worktree copy. In legacy file mode, `archive` of a row already in the
162
+ worktree's snapshot rides the feature branch, so a failed `ship` cannot mark
163
+ unlanded work done on main; a row captured after the branch was cut has no
164
+ local copy, so its archive resolves to main (finalize no longer fails with
165
+ "no row").
166
+ - A project that declares `board.url` in `.harness.json` now treats the service
167
+ as mandatory: a missing token fails loudly with an actionable message instead
168
+ of silently falling back to a checkout-local `BACKLOG.md`. The legacy file
169
+ board remains available only through explicit `BACKLOG_BACKEND=file` or
170
+ `--root`.
171
+ - The board client also reads the installed
172
+ `~/.config/agent-harness/board.env`, so an opencode server launched outside the
173
+ shell hook (systemd/desktop/resumed session) still reaches the service.
174
+ - Tests: a linked worktree mutation/read targets main and leaves the worktree
175
+ copy untouched; a declared-service/no-token project writes no local row; the
176
+ `board.env` token fallback is covered.
177
+
178
+ ## 0.3.1 — 2026-11-17
179
+
180
+ - Added an `sdlc` bundle profile: the process/quality harness only (personas,
181
+ rules, skills, memory, backlog, context/token discipline, and the process
182
+ gates) without deploy, CI, host-tuning, mobile-E2E, or the board service.
183
+ Like `core`, its bundle is a single-commit snapshot.
184
+ - The `sdlc` archive carries a `profile.json`; `init`/`update` read it and wire
185
+ only the npm scripts whose files actually ship, so a process-only checkout has
186
+ no dead `ship`/`nightly`/`serve` entries. No `profile.json` still means the
187
+ full harness.
188
+ - Kept the shared libraries that the retained features import
189
+ (`capacity-lib.js` for the context guard/`orient`, `merge-backlog.js` for the
190
+ board merge driver) in the `sdlc` archive.
191
+
192
+ ## 0.3.0 — 2026-11-17
193
+
194
+ - Added `npm run bundle` (`tools/make-release-bundle.mjs`) for closed /
195
+ air-gapped handovers: a source zip, a git bundle, `MANIFEST.json`
196
+ (commit + per-file SHA-256), `REVIEW-NOTES.md`, and `SHA256SUMS`.
197
+ - Added a `core` bundle profile that drops the host-tuning installers
198
+ (WSL sysctls, tmpfs, GPU, nightly timer), the mobile-E2E tier, and the global
199
+ freshness plugin; its bundle is a single-commit snapshot so excluded files are
200
+ not carried in history.
201
+ - `tools/` is repo tooling only — not shipped in the npm package and not
202
+ deployed by `init`.
203
+
3
204
  ## 0.2.0 — 2026-11-16
4
205
 
5
206
  First public release under the `opencode-agent-harness` name.
package/README.md CHANGED
@@ -99,6 +99,36 @@ across `init`/`update` (the `permissions` array is unioned and `agents` is
99
99
  add-only per agent). This is the **native V2 shape**: there is no V1
100
100
  `small_model`, singular `agent`, keyed `permission`, or `instructions` key.
101
101
 
102
+ ## Closed / air-gapped environments
103
+
104
+ `npx` needs the public registry. For a locked-down machine, build the artifacts
105
+ once on a connected machine and carry them in:
106
+
107
+ ```bash
108
+ npm run bundle # full harness -> dist/
109
+ npm run bundle -- --profile core # scan-reduced (no host-tuning / mobile-E2E / global plugin)
110
+ npm run bundle -- --profile sdlc # process/quality only (no deploy, CI, host tuning, mobile-E2E)
111
+ ```
112
+
113
+ Each bundle directory contains a source zip, a git bundle, `MANIFEST.json`
114
+ (commit + per-file SHA-256), `REVIEW-NOTES.md` (one page for the reviewer), and
115
+ `SHA256SUMS`. Install without a registry:
116
+
117
+ ```bash
118
+ sha256sum -c SHA256SUMS
119
+ git clone agent-harness-*.bundle agent-harness
120
+ node agent-harness/bin/agent-harness.js init --target . --dry-run
121
+ node agent-harness/bin/agent-harness.js init --target . --yes
122
+ ```
123
+
124
+ The `core` profile's bundle is a single-commit snapshot, so excluded files are
125
+ not in its history either. The `sdlc` profile (personas, rules, skills, backlog,
126
+ and the process gates, without the deploy/CI/host machinery) is a snapshot too,
127
+ and it carries a `profile.json` so `init` wires only the scripts it actually
128
+ ships — no dead `ship`/`nightly` entries in the target. Nothing is installed
129
+ globally and no lifecycle script runs; `tools/` is repo tooling and is not part
130
+ of the published package.
131
+
102
132
  ## Placeholders
103
133
 
104
134
  Templates use `{{PROJECT_NAME}}` and `{{PROJECT_DOMAIN}}`; `init` substitutes
@@ -327,6 +357,20 @@ so agents see complete descriptions.
327
357
  follow the session into the worktree, and `archive` clears the pointer. `backlog archive
328
358
  <id>` removes the shipped feature's worktree + merged branch, so a session cleans up
329
359
  after itself on close.
360
+ - **One project board, never a worktree copy**: board reads and writes are project-scoped.
361
+ A `backlog_*`/`backlog` command run inside a linked feature worktree resolves to the
362
+ shared board service, or — in legacy file mode — to the MAIN checkout's board, so a row
363
+ captured mid-feature (e.g. a security finding) is on the main board immediately. In
364
+ file mode, `archive` of a row already in the worktree's snapshot rides the feature branch
365
+ (so a failed `ship` cannot mark unlanded work done on main); a row captured after the
366
+ branch was cut has no local copy, so its archive resolves to main. A
367
+ project whose `.harness.json` declares `board.url` treats the service as mandatory: a
368
+ missing token fails loudly instead of silently falling back to a checkout-local
369
+ `BACKLOG.md` (the split-board defect); `board.backend: "file"` in `.harness.json` (durable),
370
+ `BACKLOG_BACKEND=file` (per shell), or an explicit `--root` is the deliberate legacy
371
+ opt-out. The client also reads the installed
372
+ `~/.config/agent-harness/board.env`, so an opencode server started outside the shell
373
+ hook still reaches the service.
330
374
  - **Single-authority board (main-checkout freshness)**: because a feature's commits reach
331
375
  `origin/main` from its own worktree, the MAIN checkout's board can lag origin until it is
332
376
  pulled. Every mutating command in the MAIN checkout is therefore a transaction
@@ -481,6 +525,8 @@ npx opencode-agent-harness update --target /path/to/project
481
525
  modified harness files. Your unrelated uncommitted work is never staged. The push
482
526
  uses `--no-verify` — a `chore(harness)` maintenance commit must not be stranded by a
483
527
  project pre-push gate that legitimately refuses a direct main push.
528
+ - Tracked harness-owned files that already match the release but remain uncommitted are
529
+ adopted into that commit, preventing invisible drift without manual commits; another session's staged bytes are never swept.
484
530
  - `--no-commit` to skip commit+push, `--no-push` to commit but not push,
485
531
  `--accept-harness` to overwrite a locally-modified harness-owned file.
486
532
  - `init` does **not** commit or push by default: pass `--commit` to commit the
@@ -46,6 +46,17 @@ const GLOBAL_PLUGINS_SRC = path.resolve(__dirname, "..", "contrib", "global-plug
46
46
  const CONFIG_FILE = ".harness.json";
47
47
  const BACKUP_DIR = ".harness-backup";
48
48
 
49
+ /* A real `update` must ship a COMMITTED template tree. `update` reads
50
+ * `templates/` from THIS checkout, not from a published package: an uncommitted
51
+ * template is deployed downstream but never appears in a `chore(harness)` commit,
52
+ * so the target sees it as project WIP and the next update can silently revert
53
+ * it (the 2026-11-20 LibraryOS 0.3.6 incident). Returns the dirty status lines. */
54
+ function dirtyTemplateEntries(root) {
55
+ const r = runGit(root || path.resolve(__dirname, ".."), ["status", "--porcelain", "--", "templates"]);
56
+ if (!r.ok || !r.out) return [];
57
+ return r.out.split(/\r?\n/).filter(Boolean);
58
+ }
59
+
49
60
  // ---------------------------------------------------------------- helpers
50
61
 
51
62
  /* Numeric semver compare (major.minor.patch; prerelease tags ignored).
@@ -200,6 +211,26 @@ function sha256(str) {
200
211
  return crypto.createHash("sha256").update(normalizeEol(str), "utf8").digest("hex");
201
212
  }
202
213
 
214
+ /* `next dev` appends this marker block to the project's root AGENTS.md on every
215
+ * run (and re-adds it when removed). It is tool-owned content, never a
216
+ * hand-edit of the harness file: comparing raw bytes made `update` fail closed
217
+ * on AGENTS.md, and rewriting the file just made `next dev` re-add the block
218
+ * (F-349). Strip the block and its trailing separator before comparing. */
219
+ function stripNextDevMarker(text) {
220
+ const lf = normalizeEol(text);
221
+ if (!lf.includes("<!-- BEGIN:nextjs-agent-rules -->")) return lf;
222
+ return lf.replace(
223
+ /\n*<!-- BEGIN:nextjs-agent-rules -->[\s\S]*?<!-- END:nextjs-agent-rules -->[ \t]*\n?/g,
224
+ ""
225
+ );
226
+ }
227
+
228
+ /* Comparable form of the root AGENTS.md: the harness-owned content, ignoring
229
+ * the `next dev` marker block and the trailing newline it may leave behind. */
230
+ function harnessAgentsComparable(text) {
231
+ return stripNextDevMarker(text).replace(/\s+$/, "");
232
+ }
233
+
203
234
  function safeJson(text, fallback) {
204
235
  if (text == null) return fallback;
205
236
  try {
@@ -488,6 +519,27 @@ const HARNESS_SCRIPTS = {
488
519
  gpu: "bash scripts/wsl-gpu.sh",
489
520
  };
490
521
 
522
+ /* Release profiles. A handover archive may carry `profile.json` next to
523
+ * package.json; when it does, `init` wires only the scripts it names so a
524
+ * process-only build has no dead `ship`/`nightly` entries pointing at files it
525
+ * does not ship. Absent file = the full harness (unchanged behaviour). */
526
+ function activeHarnessProfile() {
527
+ try {
528
+ const p = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "profile.json"), "utf8"));
529
+ return p && typeof p === "object" ? p : null;
530
+ } catch {
531
+ return null;
532
+ }
533
+ }
534
+ function harnessScripts() {
535
+ return filterHarnessScripts(activeHarnessProfile());
536
+ }
537
+ function filterHarnessScripts(profile) {
538
+ if (!profile || !Array.isArray(profile.scripts)) return HARNESS_SCRIPTS;
539
+ const allowed = new Set(profile.scripts);
540
+ return Object.fromEntries(Object.entries(HARNESS_SCRIPTS).filter(([k]) => allowed.has(k)));
541
+ }
542
+
491
543
  /* Detect a project's own indentation so a merge never reformats package.json
492
544
  * (a deploy that only normalizes whitespace still counts as a change and would
493
545
  * be swept into the `chore(harness)` auto-commit). */
@@ -506,7 +558,7 @@ function mergePackageJson(target) {
506
558
  const p = path.join(target, "package.json");
507
559
  const hadPkg = fs.existsSync(p);
508
560
  if (!hadPkg) {
509
- return { text: JSON.stringify({ scripts: { ...HARNESS_SCRIPTS } }, null, 2) + "\n", hadPkg, changed: true };
561
+ return { text: JSON.stringify({ scripts: { ...harnessScripts() } }, null, 2) + "\n", hadPkg, changed: true };
510
562
  }
511
563
  const current = fs.readFileSync(p, "utf8");
512
564
  const existing = safeJson(current, null);
@@ -516,7 +568,7 @@ function mergePackageJson(target) {
516
568
  }
517
569
  const scripts = Object.assign({}, existing.scripts || {});
518
570
  let added = false;
519
- for (const [name, cmd] of Object.entries(HARNESS_SCRIPTS)) {
571
+ for (const [name, cmd] of Object.entries(harnessScripts())) {
520
572
  if (!(name in scripts)) {
521
573
  scripts[name] = cmd;
522
574
  added = true;
@@ -1047,6 +1099,9 @@ function collectLocalHarnessDivergences(target, previousFiles, variables) {
1047
1099
  if (deployedHash === sha256(prev)) continue; // unmodified since last deploy
1048
1100
  const content = substitute(fs.readFileSync(abs, "utf8"), variables);
1049
1101
  if (prev === content) continue; // matches the incoming template: no clobber
1102
+ // The root AGENTS.md carries a `next dev` block that the tool re-appends:
1103
+ // a block-only difference is not a project hand-edit (F-349).
1104
+ if (key === "AGENTS.md" && harnessAgentsComparable(prev) === harnessAgentsComparable(content)) continue;
1050
1105
  divergent.push({ rel: key, targetAbs, prev });
1051
1106
  }
1052
1107
  return divergent;
@@ -1098,6 +1153,25 @@ async function deploy(target, opts) {
1098
1153
  WORKSPACE_ROOT: workspaceRootFor(target),
1099
1154
  };
1100
1155
 
1156
+ // Fail closed before writing when this checkout's own templates/ is dirty: the
1157
+ // deploy would ship unreleased work and the target could never attribute it to
1158
+ // a harness release. `--dry-run` previews, `--allow-dirty-templates` overrides
1159
+ // deliberately for harness development.
1160
+ if (isUpdate && opts.requireCleanTemplates && !dryRun) {
1161
+ const dirty =
1162
+ opts.dirtyTemplates !== undefined ? opts.dirtyTemplates : dirtyTemplateEntries();
1163
+ if (dirty.length && !opts.allowDirtyTemplates) {
1164
+ throw new Error(
1165
+ `refusing to deploy from an uncommitted templates/ tree (${dirty.length} path(s)):\n` +
1166
+ dirty.map((l) => ` ${l}`).join("\n") +
1167
+ `\n Commit + release the harness first, then re-run update. An uncommitted template is` +
1168
+ ` deployed but never recorded in the target's \`chore(harness)\` commit, so it lands as` +
1169
+ ` project WIP and the next update can silently revert it.\n` +
1170
+ ` Override deliberately with --allow-dirty-templates.`
1171
+ );
1172
+ }
1173
+ }
1174
+
1101
1175
  // All writes/commits run under a per-target deploy lock (a no-op outside a git
1102
1176
  // repo and on dry-run) so two updates can never interleave their read-modify-
1103
1177
  // write of .harness.json / the harness tree.
@@ -1316,7 +1390,12 @@ async function deploy(target, opts) {
1316
1390
  // Compare canonically so a line-ending-only difference (a CRLF `*.ps1`
1317
1391
  // that git checked out per `.gitattributes`) is not mistaken for a change
1318
1392
  // and rewritten to LF — which would leave the working tree dirty.
1319
- if (normalizeEol(current) !== normalizeEol(content)) {
1393
+ // The root AGENTS.md also ignores its `next dev` marker block: rewriting
1394
+ // the file only makes `next dev` re-append it (F-349).
1395
+ const nextDevOnly =
1396
+ key === "AGENTS.md" &&
1397
+ harnessAgentsComparable(current) === harnessAgentsComparable(content);
1398
+ if (normalizeEol(current) !== normalizeEol(content) && !nextDevOnly) {
1320
1399
  const deployedHash = previousFiles[key];
1321
1400
  const locallyModified = !!deployedHash && deployedHash !== sha256(current);
1322
1401
  // An untracked pre-existing harness-owned file (a first `init` into a
@@ -1378,6 +1457,30 @@ async function deploy(target, opts) {
1378
1457
  actions.push({ rel, kind: "add-untracked" });
1379
1458
  }
1380
1459
  }
1460
+
1461
+ // Tracked harness files whose working bytes already equal the release but are
1462
+ // still uncommitted against HEAD. A prior deploy can write them and skip them
1463
+ // in its commit (or a restore re-applies them), after which `.harness.json`
1464
+ // records the worktree hash and the drift is invisible to every later update —
1465
+ // the LibraryOS 0.3.8 case (board-service.sh, finalize.js, run-gates.js,
1466
+ // wsl-tune.sh needed a manual commit). They are "unchanged" here, so they never
1467
+ // enter changedRels on their own; absorb the ones ONLY the working tree
1468
+ // modified. A path with staged bytes of its own ("MM" — another session's
1469
+ // work) is left in the index, exactly like the untracked sweep above.
1470
+ const hasHead = runGit(target, ["rev-parse", "--verify", "--quiet", "HEAD"]).ok;
1471
+ const unstaged = runGit(target, ["diff", "--name-only", "--", ...harnessOwnedPresent]);
1472
+ if (unstaged.ok) {
1473
+ const stagedSet = new Set(
1474
+ (hasHead ? runGit(target, ["diff", "--cached", "--name-only", "--", ...harnessOwnedPresent]).out : "")
1475
+ .split(/\r?\n/)
1476
+ .filter(Boolean)
1477
+ .map(relKey)
1478
+ );
1479
+ for (const rel of (unstaged.out || "").split(/\r?\n/).filter(Boolean).map(relKey)) {
1480
+ if (stagedSet.has(rel)) continue; // staged bytes belong to someone else's index state
1481
+ actions.push({ rel, kind: "adopt" });
1482
+ }
1483
+ }
1381
1484
  }
1382
1485
 
1383
1486
  // Nothing-to-update detection: an update that made no effective change to any
@@ -1385,7 +1488,7 @@ async function deploy(target, opts) {
1385
1488
  // report it clearly instead of printing a zero-delta "Updated", and leave the
1386
1489
  // target byte-for-byte untouched (no .harness.json timestamp churn, no commit).
1387
1490
  const changedRelsAll = actions
1388
- .filter((a) => ["create", "overwrite", "overwrite (backup)", "merge", "add-untracked", "remove-obsolete"].includes(a.kind))
1491
+ .filter((a) => ["create", "overwrite", "overwrite (backup)", "merge", "add-untracked", "adopt", "remove-obsolete"].includes(a.kind))
1389
1492
  .map((a) => a.rel);
1390
1493
  const nothingToUpdate =
1391
1494
  !!isUpdate && changedRelsAll.length === 0 && compareVersions(existing.version || "0", PKG.version) === 0;
@@ -1486,7 +1589,8 @@ function printSummary(result, isUpdate) {
1486
1589
  console.log(
1487
1590
  `\n ${counts.create || 0} created, ${counts.overwrite || 0} overwritten, ` +
1488
1591
  `${counts["overwrite (backup)"] || 0} backed up (locally modified), ` +
1489
- `${counts.merge || 0} merged, ${counts["remove-obsolete"] || 0} removed (obsolete), ` +
1592
+ `${counts.merge || 0} merged, ${counts.adopt || 0} adopted (uncommitted drift), ` +
1593
+ `${counts["remove-obsolete"] || 0} removed (obsolete), ` +
1490
1594
  `${counts.preserve || 0} preserved, ${counts.unchanged || 0} unchanged.`
1491
1595
  );
1492
1596
  }
@@ -1552,13 +1656,16 @@ function printUsage() {
1552
1656
  `agent-harness v${PKG.version}\n\n` +
1553
1657
  `Usage:\n` +
1554
1658
  ` agent-harness init [--target <dir>] [--name <project>] [--domain <desc>] [--yes] [--dry-run] [--commit] [--push]\n` +
1555
- ` agent-harness update [--target <dir>] [--dry-run] [--no-commit] [--no-push] [--accept-harness]\n` +
1659
+ ` agent-harness update [--target <dir>] [--dry-run] [--allow-dirty-templates] [--no-push] [--accept-harness]\n` +
1556
1660
  ` agent-harness migrate-backlog [--target <dir>]\n` +
1557
1661
  `\n` +
1558
1662
  ` init writes files but does NOT commit or push by default: pass --commit to\n` +
1559
1663
  ` commit the harness files it creates/changes, and --push to also push. update\n` +
1560
- ` auto-commits (chore(harness): ...) and pushes by default; use --no-commit or\n` +
1561
- ` --no-push to opt out. Your unrelated uncommitted work is never staged. The\n` +
1664
+ ` auto-commits (chore(harness): ...) and pushes by default. A real deploy\n` +
1665
+ ` refuses --no-commit (preview with --dry-run) and an uncommitted templates/\n` +
1666
+ ` tree (--allow-dirty-templates for harness development only), so a release\n` +
1667
+ ` can never land downstream as untracked project WIP. Your unrelated\n` +
1668
+ ` uncommitted work is never staged. The\n` +
1562
1669
  ` target must be on its canonical\n` +
1563
1670
  ` branch (origin/HEAD, else main/master) or the commit is refused, so a\n` +
1564
1671
  ` harness update can never be stranded off main — pass --allow-branch to\n` +
@@ -2525,6 +2632,18 @@ async function update(target, flags) {
2525
2632
  console.error("templates/ directory not found next to this CLI.");
2526
2633
  process.exit(1);
2527
2634
  }
2635
+ // A real deploy must be atomic: the deployed files and their `chore(harness)`
2636
+ // commit are one unit. `--no-commit` split them once (2026-11-20: 0.3.6 landed
2637
+ // in LibraryOS as untracked WIP and the updater later reverted two fixes), so
2638
+ // it is now preview-only; use --dry-run to inspect without writing.
2639
+ if (flags["--no-commit"] && !flags["--dry-run"]) {
2640
+ console.error(
2641
+ "update: refusing --no-commit for a real deploy — the harness files would sit uncommitted in the target.\n" +
2642
+ " They would look like project WIP and the next update could revert them (a release must be atomic).\n" +
2643
+ " Use --dry-run to preview the writes, or drop --no-commit to land one chore(harness) commit."
2644
+ );
2645
+ process.exit(1);
2646
+ }
2528
2647
  const result = await deploy(target, {
2529
2648
  yes: true,
2530
2649
  dryRun: !!flags["--dry-run"],
@@ -2533,6 +2652,8 @@ async function update(target, flags) {
2533
2652
  push: !flags["--no-commit"] && !flags["--no-push"],
2534
2653
  allowBranch: !!flags["--allow-branch"],
2535
2654
  acceptHarness: !!flags["--accept-harness"],
2655
+ requireCleanTemplates: true,
2656
+ allowDirtyTemplates: !!flags["--allow-dirty-templates"],
2536
2657
  });
2537
2658
  printSummary(result, true);
2538
2659
  printUnpublishedWarning();
@@ -2685,7 +2806,7 @@ function parseArgs(argv) {
2685
2806
  if (valueFlags.has(a)) flags[a] = argv[++i];
2686
2807
  else if (a === "--dry-run" || a === "--yes" || a === "-y" || a === "--force") flags[a] = true;
2687
2808
  else if (a === "--remove") flags[a] = true;
2688
- else if (a === "--no-commit" || a === "--no-push" || a === "--allow-branch" || a === "--accept-harness" || a === "--commit" || a === "--push")
2809
+ else if (a === "--no-commit" || a === "--no-push" || a === "--allow-branch" || a === "--accept-harness" || a === "--commit" || a === "--push" || a === "--allow-dirty-templates")
2689
2810
  flags[a] = true;
2690
2811
  }
2691
2812
  return flags;
@@ -3017,6 +3138,7 @@ module.exports = {
3017
3138
  isIgnoreFile,
3018
3139
  withDeployLock,
3019
3140
  sha256,
3141
+ dirtyTemplateEntries,
3020
3142
  readConfig,
3021
3143
  resolveVars,
3022
3144
  workspaceRootFor,
@@ -3051,6 +3173,7 @@ module.exports = {
3051
3173
  opencodeGlobalPluginsDir,
3052
3174
  GLOBAL_PLUGINS_SRC,
3053
3175
  HARNESS_SCRIPTS,
3176
+ filterHarnessScripts,
3054
3177
  runCommand,
3055
3178
  TEMPLATES_DIR,
3056
3179
  CONFIG_FILE,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-agent-harness",
3
- "version": "0.2.0",
3
+ "version": "0.3.15",
4
4
  "description": "Reusable multi-agent harness for OpenCode: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx opencode-agent-harness init`.",
5
5
  "bin": {
6
6
  "agent-harness": "bin/agent-harness.js"
@@ -28,9 +28,47 @@
28
28
  "scripts": {
29
29
  "prepublishOnly": "npm run lint && npm test && npm run test:pack",
30
30
  "test:pack": "node --test tests/pack.e2e.js",
31
- "test": "node --test tests/agent-harness.test.js tests/plugin-loader.e2e.js tests/ci-usage.test.js tests/ci-triage.test.js tests/init-safety.test.js",
31
+ "test": "node --test tests/agent-harness.test.js tests/plugin-loader.e2e.js tests/ci-usage.test.js tests/ci-triage.test.js tests/init-safety.test.js tests/release-bundle.e2e.js tests/worktree-hygiene.test.js",
32
+ "bundle": "node tools/make-release-bundle.mjs",
32
33
  "test:plugin-loader": "node --test tests/plugin-loader.e2e.js",
33
- "lint": "node --check bin/agent-harness.js && node --check templates/scripts/backlog.js && node --check templates/scripts/nightly.js && node --check templates/scripts/ship.js && node --check templates/scripts/finalize.js && node --check templates/scripts/checkpoint.js && node --check templates/scripts/orient.js && node --check templates/scripts/wait-for.js && node --check templates/scripts/agent-report.js && node --check templates/scripts/serve.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/board-lib.js && node --check templates/scripts/qa/board-sync.js && node --check templates/scripts/qa/board-client.js && node --check templates/scripts/qa/tool-lib.js && node --check templates/scripts/qa/lease-lib.js && node --check templates/scripts/qa/ci-wait-lib.js && node --check templates/scripts/qa/ci-triage.js && node --check templates/scripts/qa/check-ci-policy.js && node --check templates/scripts/qa/check-quality.js && node --check templates/scripts/qa/check-product.js && node --check templates/scripts/qa/check-docs.js && node --check templates/scripts/qa/check-concurrency.js && node --check templates/scripts/qa/check-integrate.js && node --check templates/scripts/qa/merge-backlog.js && node --check templates/scripts/qa/run-clean.js && node --check templates/scripts/qa/check-test-wiring.js && node --check templates/scripts/qa/check-linger.js && node --check templates/scripts/qa/check-prefix-stability.js && node --check templates/scripts/qa/command-classifier.js && node --check templates/scripts/qa/capacity-lib.js && node --check templates/scripts/qa/check-capacity.js && node --check templates/scripts/qa/wslconfig-merge.js && node --check templates/scripts/qa/hash-file.js && node --check templates/scripts/qa/context-guard-core.js && node --check templates/scripts/qa/run-loop.js && node --check templates/scripts/qa/provider-stats.js && node --check templates/scripts/qa/store-lib.js && node --check templates/scripts/qa/diff.js && node --check templates/scripts/qa/session-recon.js && node --check templates/scripts/qa/run-gates.js && node --check templates/scripts/qa/where.js && node --check templates/scripts/qa/feature-scaffold.js && node --check templates/scripts/qa/mobile-e2e/run-maestro.js && node --check templates/scripts/qa/mobile-e2e/job-events.js && node --check templates/scripts/qa/mobile-e2e/check-flows.js && node --check templates/scripts/qa/mobile-e2e/apk-cache.js && node --check templates/scripts/qa/mobile-e2e/backend-build-cache.js && node --check templates/scripts/qa/mobile-e2e/ui-dump.js && node --check templates/scripts/qa/mobile-e2e/analyze-timings.js && node --check templates/scripts/qa/ci-usage-lib.js && node --check tests/ci-usage.test.js"
34
+ "lint": "node --check bin/agent-harness.js && node --check templates/scripts/backlog.js && node --check templates/scripts/nightly.js && node --check templates/scripts/ship.js && node --check templates/scripts/finalize.js && node --check templates/scripts/checkpoint.js && node --check templates/scripts/orient.js && node --check templates/scripts/wait-for.js && node --check templates/scripts/agent-report.js && node --check templates/scripts/serve.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/board-lib.js && node --check templates/scripts/qa/board-sync.js && node --check templates/scripts/qa/board-client.js && node --check templates/scripts/qa/tool-lib.js && node --check templates/scripts/qa/lease-lib.js && node --check templates/scripts/qa/ci-wait-lib.js && node --check templates/scripts/qa/ci-triage.js && node --check templates/scripts/qa/check-ci-policy.js && node --check templates/scripts/qa/check-quality.js && node --check templates/scripts/qa/check-product.js && node --check templates/scripts/qa/check-docs.js && node --check templates/scripts/qa/check-concurrency.js && node --check templates/scripts/qa/check-integrate.js && node --check templates/scripts/qa/merge-backlog.js && node --check templates/scripts/qa/run-clean.js && node --check templates/scripts/qa/check-test-wiring.js && node --check templates/scripts/qa/check-linger.js && node --check templates/scripts/qa/check-prefix-stability.js && node --check templates/scripts/qa/command-classifier.js && node --check templates/scripts/qa/capacity-lib.js && node --check templates/scripts/qa/check-capacity.js && node --check templates/scripts/qa/wslconfig-merge.js && node --check templates/scripts/qa/hash-file.js && node --check templates/scripts/qa/context-guard-core.js && node --check templates/scripts/qa/run-loop.js && node --check templates/scripts/qa/provider-stats.js && node --check templates/scripts/qa/store-lib.js && node --check templates/scripts/qa/diff.js && node --check templates/scripts/qa/session-recon.js && node --check templates/scripts/qa/run-gates.js && node --check templates/scripts/qa/where.js && node --check templates/scripts/qa/feature-scaffold.js && node --check templates/scripts/qa/mobile-e2e/run-maestro.js && node --check templates/scripts/qa/mobile-e2e/job-events.js && node --check templates/scripts/qa/mobile-e2e/check-flows.js && node --check templates/scripts/qa/mobile-e2e/apk-cache.js && node --check templates/scripts/qa/mobile-e2e/backend-build-cache.js && node --check templates/scripts/qa/mobile-e2e/ui-dump.js && node --check templates/scripts/qa/mobile-e2e/analyze-timings.js && node --check templates/scripts/qa/ci-usage-lib.js && node --check tests/ci-usage.test.js && node --check tools/make-release-bundle.mjs",
35
+ "backlog": "node scripts/backlog.js",
36
+ "ship": "node scripts/ship.js",
37
+ "finalize": "node scripts/finalize.js",
38
+ "test:dispatch": "node scripts/qa/check-dispatch-config.js",
39
+ "test:governance": "node scripts/qa/governance.js",
40
+ "test:qa-plan": "node scripts/qa/check-qa-plan.js",
41
+ "test:backlog": "node scripts/qa/check-backlog.js",
42
+ "test:product": "node scripts/qa/check-product.js",
43
+ "test:docs": "node scripts/qa/check-docs.js",
44
+ "test:concurrency": "node scripts/qa/check-concurrency.js",
45
+ "test:integrate": "node scripts/qa/check-integrate.js",
46
+ "test:quality": "node scripts/qa/check-quality.js",
47
+ "test:wiring": "node scripts/qa/check-test-wiring.js",
48
+ "test:linger": "node scripts/qa/check-linger.js",
49
+ "test:capacity": "node scripts/qa/check-capacity.js",
50
+ "test:worktrees": "node scripts/qa/check-worktrees.js",
51
+ "test:ci-policy": "node scripts/qa/check-ci-policy.js",
52
+ "test:prefix": "node scripts/qa/check-prefix-stability.js",
53
+ "ci-triage": "node scripts/qa/ci-triage.js",
54
+ "gates": "node scripts/qa/run-gates.js",
55
+ "where": "node scripts/qa/where.js",
56
+ "diff": "node scripts/qa/diff.js",
57
+ "feature:scaffold": "node scripts/qa/feature-scaffold.js",
58
+ "report": "node scripts/agent-report.js",
59
+ "report:cost": "node scripts/agent-report.js --cost --since=14d",
60
+ "report:recon": "node scripts/qa/session-recon.js --since=14d",
61
+ "nightly": "node scripts/nightly.js",
62
+ "report:nightly": "node scripts/nightly.js report",
63
+ "checkpoint": "node scripts/checkpoint.js",
64
+ "orient": "node scripts/orient.js",
65
+ "wait": "node scripts/wait-for.js",
66
+ "serve": "node scripts/serve.js",
67
+ "search": "bash scripts/agent-search.sh",
68
+ "ramdisk": "bash scripts/setup-tmpfs.sh up",
69
+ "ramdisk:down": "bash scripts/setup-tmpfs.sh down",
70
+ "wsl-tune": "bash scripts/wsl-tune.sh",
71
+ "gpu": "bash scripts/wsl-gpu.sh"
34
72
  },
35
73
  "keywords": [
36
74
  "opencode",