opencode-harness-kit 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -12,6 +12,197 @@ is not happening.
 
 ---
 
+## [0.5.8] — 2026-10-22
+
+Published. The tag is what cut it: `git tag v0.5.8 && git push origin
+main v0.5.8`, and the publish job watches for exactly that.
+
+A minor: one new command, and eleven silent failures closed.
+
+### Added
+
+- **`oc-harness auto` — the whole reconcile in one command, asking nothing.**
+  `refresh`, `install`, `use` and `verify` are each a step somebody has to
+  remember, in the right order, with the right flags; an agent that has to
+  keep an install working has to know all of that, and has to know which of
+  them are allowed to destroy something.
+
+  The profile is the one the installed config names, or the default. A file
+  of yours that the installer would overwrite is **left alone and
+  reported**, not overwritten and not asked about — the answer a person
+  would give. `--offline` skips the refresh, for a machine that cannot
+  reach models.dev. `--json` prints a report a script can read, and nothing
+  else on stdout.
+
+  `--yes` still means consent: a profile whose models may train on your
+  prompts is refused without it, exactly as `use` refuses it. The automation
+  is about the mechanics, not about the consent.
+
+  `init` is unchanged. It is the front door for a person, and it still says
+  so when there is no terminal to ask on.
+
+- **A demo whose numbers are current.** `docs/demo/audit.mp4` — thirty
+  seconds, made on a machine with no screen, no camera and no ffmpeg: the
+  scene is drawn by a browser, the terminal in it is the real output of the
+  real commands, and the narration is on the frame. It names the numbers of
+  this release. The older `pitch.mp4` stays where it was — a live recording
+  from a Mac, with a voice — and the README now says which is which.
+
+### Fixed
+
+- **A refresh overwrote a profile whose backup could not be written.** The
+  backup is the only copy of a file the user may have edited by hand — and
+  for an npm install that file is inside node_modules, where the next
+  `npm install` destroys it anyway. The error was swallowed and the
+  profile was overwritten regardless: the user's edits were gone, with no
+  backup and no message. A backup that cannot be written now stops the
+  refresh.
+
+- **`refresh --all` reported profiles it never checked.** A profile that
+  could not be parsed was skipped without a word, and the summary counted
+  every id it had been given — so a broken profile was reported as a
+  refreshed one, and the withdrawn-model check never ran for it. The count
+  is of the profiles actually checked, the skipped ones are named, and the
+  command exits non-zero: a skipped profile is a failure, not a footnote.
+
+- **`generateConfig(profile, { comments: false })` produced a file nothing
+  could read.** The whole header is comments, so turning comments off
+  emitted it without the `// ` prefix, in front of the JSON body. The
+  result was neither JSON nor JSONC, and the kit's own `parseJsonc`
+  returned null for it. It is pure JSON now.
+
+- **A file named `toString.md` was reported as shadowing a lane.** The
+  check was `lane in (actual.agent ?? {})`, and `in` walks the prototype
+  chain — so a file named after a property every object has matched a lane
+  that does not exist, and `verify` reported a clean install as broken.
+
+- **`--role` took the next flag as its value.** `oc-harness run --role
+  --max-rounds 5` set the role to the literal string `--max-rounds`, and
+  the loop then failed every round and marked every task blocked. A flag
+  with no value is refused now, and so is a role that is not a lane —
+  while the answer is still "that is not a lane".
+
+- **The install deleted a file of yours that only looked like the kit's.**
+  The old agent directory was recognised by a substring, and a directory
+  called `space-harness/agents-backup` contains that substring. The file
+  was deleted. The match is on the parent directory now, segment by
+  segment.
+
+- **A wrapper the list did not name was a way around the rules.** The
+  wrapper list held `env`, `sudo` and a handful of others, so the programs
+  that run a command as their argument - `timeout`, `nice`, `ionice`,
+  `stdbuf`, `setsid`, `chroot`, `taskset`, `busybox` - were commands the
+  rules had never seen. `timeout 5 rm -rf /tmp/x` deleted a tree, and
+  `timeout 5 npm publish` published a package, and neither was blocked.
+
+  The list is a table now, and the flags that take a value are the
+  WRAPPER'S OWN: `sudo -n` is a flag and the word after it is the command,
+  while `stdbuf -o 0` takes a mode and the word after it is the mode. One
+  list for all of them made `sudo -n rm -rf /tmp/x` read `rm` as the value
+  of `-n`, so the delete was invisible - which is the same hole in the other
+  direction.
+
+- **`env -S "rm -rf /tmp/x"` was allowed.** `-S` takes a string and splits
+  it into words, so the string is a command line - the same thing `sh -c`
+  carries. It used to arrive as ONE token, and the command word was read
+  out of it as the text after the last slash, so the guard looked at `x`.
+  The payload is read now, and it is read the way `sh -c` is read.
+
+- **`git -C/tmp reset --hard` was allowed.** `-C` and `-c` take a value, and
+  the value can be written against the flag. The resolver only knew the
+  spaced form, so the subcommand it found was the flag itself - and the
+  rule that watches for a history rewrite never saw the subcommand at all.
+
+- **A public key was refused as a private key.** The rule named the key
+  FILES, and `id_rsa.pub` is the public half of `id_rsa` - a file the user
+  is meant to publish. Writing one was refused for a reason nobody could
+  find.
+
+- **A file that was downloaded and then run was ordinary work.** The rule
+  caught `curl x | sh` and nothing else, so the same download in two steps
+  - fetch it to a file, then run the file - was allowed. It runs exactly the
+  same downloaded script.
+
+- **A symlink out of the project was a write out of the project.** The
+  scope check compared paths as TEXT, so a link inside the project that
+  pointed at `/etc` was a path inside the project - and the write landed
+  outside it. The comparison is made on the real path now, and the part of
+  the path that does not exist yet is put back on the end.
+
+- **`oc-harness agents` called a prototype property a lane.** The check was
+  `name in (config.agent)`, and `in` walks the prototype chain - so a project
+  agent file named `toString.md` or `constructor.md` matched a property every
+  object has: the file was reported as shadowing a lane that does not exist,
+  and the missing `model:` that was the point of the report was never
+  reported either. `verify` had the same check and the same fix; this one
+  was left behind.
+
+- **`auto --json` dropped everything the refresh had found.** The refresh
+  prints what it found - a withdrawn model, a profile it could not read - and
+  `auto --json` silences the human output, so those findings went nowhere:
+  the report said `"ok": true` while a profile had never been checked
+  against the live catalogue, and the exit code said something else
+  entirely. The refresh hands its findings back now, and they are in the
+  report, in the step's status, and in the exit code.
+
+- **`baseline --db=/path` measured the wrong database.** Only the spaced
+  form `--db /path` was read, so the `=` spelling - the one every other flag
+  in this kit accepts - was ignored, and the default database was measured
+  instead. The report then described a database nobody asked about. Both
+  spellings work now, and a `--db` with no value is refused instead of
+  crashing.
+
+- **`doctor --check-models` reported a profile it never checked.** A profile
+  that could not be read was skipped without a word, and the run then said
+  every shipped model was still in the catalogue - so a profile that was NEVER
+  CHECKED was reported as one that was checked and found fine. It is the same
+  hole `refresh --all` had, in the one place that runs from a cron. The
+  skipped profiles are named now, and the run fails.
+
+### Changed
+
+- **The `verify` and `doc` lanes ask nothing.** Both ran the project's own
+  commands, and both asked before every one of them that the lane's
+  allowlist did not name. A run that stops to be asked is a run that does
+  not finish. The mechanical safety is unchanged: the guard plugin still
+  refuses the denied commands in code, and the lanes still cannot edit.
+
+### Added
+
+- **A recorder for a machine with no screen.** `vrec` drives the real
+  keyboard and the real screen, so it needs macOS, the Screen Recording
+  permission, and somebody to grant it. A headless box has none of those,
+  and it has no `ffmpeg` either, so the usual encode step has nothing to
+  encode with. The published demo was made with `vrec`; on such a machine
+  it cannot be made at all.
+
+  The recorder is in the tools repository, next to `vrec` and `btake` — one
+  directory up, and there is exactly one of each, because a copy inside
+  this repository is how two copies drift. It draws the scene on a canvas
+  and lets the browser be the encoder: Chromium's `captureStream` into
+  `MediaRecorder` at a fixed clock, which comes out as an `.mp4` with an
+  H.264 track and no ffmpeg on the machine at all. The text on screen is
+  the real output of the real commands — the take spec names the commands,
+  and they are run when the video is built.
+
+  The gate is the part that matters. A file that exists, has the right
+  duration and has the right size can still be thirty seconds of black, so
+  the gate decodes the take, pulls frames out of it, and looks at them: a
+  frame with no spread in its pixels shows nothing, and the take fails.
+  The frames are written out as PNGs, because a check you cannot look at
+  is a check you cannot argue with.
+
+  **The take is local and the video is local.** The take spec lives in
+  `video/takes/` and the recording lands in `video/build/`; both are
+  gitignored. The repository ships the recorder and not the take, and a
+  recording stays on the machine that made it until somebody decides,
+  deliberately, to publish it.
+
+  And the narration is on the screen. A voice is the best way to carry it
+  and it is not always there — `say` is macOS, and a headless Linux box
+  has no espeak, no festival and no cloud TTS — so the words go on the
+  frame, one caption at a time, and the take still says what it is about.
+
 ## [0.5.7] — 2026-10-21
 
 Published. The tag is what cut it: `git tag v0.5.7 && git push origin main

package/README.md

@@ -15,6 +15,16 @@ record it and the two mistakes that cost the most time.*
 *It was recorded against an earlier version of the kit: the numbers it names
 are the ones from then, and the ones below are the ones now.*
 
+<p align="center">
+  <video src="docs/demo/audit.mp4" width="720" controls></video>
+</p>
+
+*Thirty seconds, made on a machine with no screen and no camera: the scene is
+drawn by a browser, the terminal in it is the **real** output of the **real**
+commands — `oc-harness verify` above — and the narration is on the frame. It
+names the numbers of this release (475 tests), so nothing in it is out of date.
+How it is made is in [`video/`](video/).*
+
 A harness kit for [OpenCode](https://opencode.ai) that is **model-agnostic by
 construction**. Switching models is a data edit, not a code change.
 
@@ -375,6 +385,8 @@ keeps a dated copy in `~/.config/opencode/backups/`, including under
 oc-harness list       profiles with retention and caveats
 oc-harness show <id>  resolved lanes, derived numbers, fallback chains, guard rules
 oc-harness init       pick a free profile, then install + use + verify
+oc-harness auto       refresh + install + use + verify, asking nothing
+oc-harness auto --json   the same reconcile, as a report a script can read
 oc-harness use <id>   compile a profile into ~/.config/opencode/opencode.jsonc
 oc-harness use <id> --dryrun   print a summary of what would be written, write nothing
 oc-harness refresh <id> re-derive a profile against the live model list
@@ -677,6 +689,28 @@ oc-harness install                # writes everything that file points at
 `GLOBAL.md` into `~/.config/opencode/`, so this repo stays the single source
 of truth and an edit here takes effect on the next opencode start.
 
+### The one command that asks nothing
+
+`init` is the front door for a person: it asks which free profile to run on.
+`auto` is the one for a job, an agent, or a script — it reconciles the whole
+install and never waits for an answer:
+
+```bash
+oc-harness auto              # refresh + install + use + verify
+oc-harness auto --json       # the same, as a report a script can read
+oc-harness auto --offline    # skip the refresh, for a machine that cannot reach models.dev
+```
+
+The profile is the one the installed config names, or the default. A file of
+yours that the installer would overwrite is **left alone and reported**, not
+overwritten and not asked about — the answer a person would give.
+
+`--yes` still means consent. A profile whose models may train on your prompts
+is refused without it, exactly as `use` refuses it: the automation is about
+the mechanics, not about the consent. `auto` exits non-zero when `verify`
+finds a problem it is not allowed to repair, and `--json` puts the problems in
+the report.
+
 Then restart opencode. Check it took:
 
 ```bash

package/bin/baseline.mjs

@@ -16,8 +16,23 @@ import { join } from "node:path"
 
 const args = process.argv.slice(2)
 const wantJson = args.includes("--json")
+// Both spellings: `--db /path` and `--db=/path`. Only the first was read, so
+// `--db=/path` was ignored and the DEFAULT database was measured instead -
+// and the report said nothing about it. A flag that does not do what it was
+// given is worse than a flag that is missing.
+const dbEq = args.find((a) => a.startsWith("--db="))
 const dbArg = args.indexOf("--db")
-const DB = dbArg >= 0 ? args[dbArg + 1] : join(homedir(), ".local/share/opencode/opencode.db")
+const dbValue =
+  dbEq !== undefined
+    ? dbEq.slice("--db=".length)
+    : dbArg >= 0
+      ? args[dbArg + 1]
+      : undefined
+if (dbValue !== undefined && (!dbValue || dbValue.startsWith("--"))) {
+  console.error("pass --db <path> or --db=<path>")
+  process.exit(1)
+}
+const DB = dbValue ?? join(homedir(), ".local/share/opencode/opencode.db")
 
 const { canQuerySqlite, sqliteMissingMessage, query: queryDb } = await import("../src/sqlite.js")