opencode-harness-kit 0.4.3 → 0.4.4

package/README.md

@@ -3,6 +3,18 @@
 [![CI](https://github.com/pham-canh/space-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/pham-canh/space-harness/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/opencode-harness-kit.svg)](https://www.npmjs.com/package/opencode-harness-kit)
 
+<p align="center">
+  <video src="docs/demo/pitch.mp4" width="720" controls></video>
+</p>
+
+*Four minutes forty-seven seconds, recorded live from a real terminal and
+narrated. The take script and the voiceover are in [`video/`](video/), and
+rebuilding it is documented there — including the two mistakes that cost the
+most time, so the next person does not repeat them.*
+
+*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.*
+
 A harness kit for [OpenCode](https://opencode.ai) that is **model-agnostic by
 construction**. Switching models is a data edit, not a code change.
 
@@ -10,6 +22,10 @@ construction**. Switching models is a data edit, not a code change.
 npx -y opencode-harness-kit init    # pick a free model, then install + verify
 ```
 
+<p align="center">
+  <img src="docs/demo-loop.gif" width="760" alt="oc-harness list showing the model-agnostic profiles, then oc-harness verify reporting a consistent install">
+</p>
+
 then restart opencode. That is the whole quickstart. No npm account needed on
 your side — `npx` only downloads the published kit. Prefer git? The same three
 steps from a checkout (see [Install](#install)):
@@ -55,6 +71,13 @@ test suite asserts that rather than taking it on faith.
 
 The default profile is a **fleet**: ten jobs, ten free models, one session.
 
+The table below is the **unrestricted** fleet (`fleet-all`), where every lane
+gets the model built for it. The default is the **safe** fleet
+(`fleet-safe`), where every lane resolves to a provider with a zero-retention
+policy and six of the ten run on a second-choice model to stay there. Both
+cover the same ten jobs; they differ in what they are willing to promise
+about your prompts.
+
 | lane | job | model | measured |
 |---|---|---|---|
 | `build` | write and verify the change | MiniMax M3.1 Flash | 3.1 s |
@@ -86,11 +109,6 @@ Super VL is the only model on the tier that publishes a `none` effort level,
 which makes "reasoning off" a job of its own. Putting each on the job it is
 good at is worth more than any single "best" model.
 
-The default is the **safe** fleet, and it is safe by construction rather than
-by label: every lane resolves to a provider with a zero-retention policy, and
-six of the ten lanes run on a second-choice model to stay there. The
-unrestricted fleet gives every lane the model built for it.
-
 The full table, with the measurements behind every choice and the three
 capabilities the tier turns out not to have, is in
 [`docs/ROUTING.md`](docs/ROUTING.md).
@@ -115,7 +133,7 @@ $ oc-harness use fleet-safe --print
 // Derived numbers, do not hand-edit:
 //   compaction.reserved  24,000  (12% of the narrowest input cap in play)
 //   prune threshold      176,000  (narrowest input cap minus reserve)
-//   role effort          plan=max  build=max  reviewer=max  locate=unset  ...
+//   role effort          plan=max  build=max  reviewer=max  locate=low  ...
 //   lane models          build=minimax-m3.1-flash-free (out 512,000)  plan=...
 ```
 
@@ -147,7 +165,7 @@ $ oc-harness show fleet-safe
   lane effort
     plan       max
     locate     low
-    sweep      (unset)    (requested none)
+    sweep      low
 ```
 
 A model with no tunable effort at all gets **no** `variant` written, rather
@@ -199,16 +217,118 @@ it. One file covers ten jobs either way.
 The five-lane profiles run everything on one model, which is the right shape
 when you want one route and want to know exactly which one.
 
+## Free models are perishable, so check them
+
+Every model in the table above is a **free tier slot**, and free tier slots
+turn over in days. Zen states free models are available "for a limited time"
+with no date attached, so a profile is a snapshot of a moment rather than a
+stable thing.
+
+Observed lifetimes, from one install's 20-day history:
+
+| model | observed lifetime |
+|---|---|
+| `mimo-v2.5-free` | 1 day |
+| `big-pickle` | 1 day |
+| `nemotron-3-ultra-free` | 3 days |
+| `muse-spark-1.3-contributor-free` | still running at 20 days |
+
+The tier turned over again since. Five of this kit's own profiles are already
+withdrawn, and one of them was the **default** at the time:
+
+| withdrawn | why it matters |
+|---|---|
+| `space-bunny-free` | It was the default profile. A config left pointing at it kept working and kept saying it was zero-retention. |
+| `x-preview-f-free` | Withdrawn within a month of shipping. |
+| `deepseek-v4-flash-free` | Withdrawn within a month. Replaced by `deepseek-v4.1-flash-free`. |
+| `muse-spark-1.3-contributor-free` | A Meta contributor route whose provider was permitted to train on prompts. The paid route is still in the catalogue. |
+| `mimo-v2.5-free` | Observed alive for one day. Replaced by `mimo-v2.6-flash-free`. |
+
+The full list, with a reason for each, is in
+[`profiles/index.json`](profiles/index.json).
+
+### The four commands, and when each one runs
+
+| command | what it checks | when |
+|---|---|---|
+| `oc-harness list` | the profiles this kit ships, with retention and caveats | offline, any time |
+| `oc-harness doctor` | every profile against the live model catalogue, and the installed config against the active profile | **before every release**, and whenever a lane starts failing with a 429 or a "model not found" |
+| `oc-harness doctor --check-models` | one run, non-zero when a shipped model is no longer in the catalogue | from cron: the shape a scheduler wants |
+| `oc-harness doctor --watch` | keeps watching, and reports only what **changed** | leave it in a terminal for a week |
+| `oc-harness refresh <id>` | re-derives a profile's machine-derived fields from live metadata | when `doctor` reports drift |
+| `oc-harness verify` | the installed config still matches the profile, and the kit's own files are still installed | after every `use` / `install` |
+
+A cron line that tells you the moment a route disappears, rather than the
+moment a lane starts failing:
+
+```cron
+0 9 * * * cd ~/.config/opencode && oc-harness doctor --check-models
+```
+
+`doctor` separates the two kinds of finding, because they are not the same
+kind of finding:
+
+- **A broken install** — the config no longer matches the profile, or the
+  active profile no longer loads. This always exits non-zero.
+- **Perishable metadata** — a profile has drifted from models.dev because a
+  provider changed a context window or a capability flag. This is reported and
+  exits zero, unless you pass `--strict`, which is for a release.
+
+A CI job that failed on the second kind would go red on a Tuesday because
+somebody else changed a provider's limits, and a job that goes red for a
+reason you cannot act on is a job people stop reading.
+
+It is not a hypothetical. The day this was written, four of the twelve
+shipped profiles had already drifted from the live catalogue — the
+`temperature` flag had flipped on every one of them.
+
+### What `refresh` will and will not touch
+
+`refresh` rewrites only the fields a machine can derive: context, output and
+input ceilings, the effort levels a model publishes, and the capability flags.
+It never touches `retention`, `note`, `roles` or the fallback queue, because
+those are human judgements and a script overwriting a privacy verdict is worse
+than drift.
+
+**If a provider changes its terms, a human has to say so.** `retention.yml` is
+hand-curated and dated (`verified:` on every entry). `doctor` will catch the
+one case it can check mechanically — a profile that says `zero-retention`
+while `retention.yml` now says `may-train` — and nothing else.
+
+### What happens when a model is withdrawn
+
+No plugin hook can change the model of a running session, so the failover is
+not mid-flight:
+
+1. The router marks the route spent when a request fails with a free-tier
+   limit or a withdrawal.
+2. At the **next** session start, the lane that used it moves to the next rung
+   of its own chain, and the session's own model moves to the next profile in
+   the fallback queue.
+3. A fleet keeps its lanes. One spent route costs one lane, not ten — that is
+   the whole reason every lane carries a chain of models instead of a single
+   name.
+
+If a model is withdrawn and the lane's whole chain has gone with it, the lane
+falls back to the profile's base model. If even that is spent, the lane still
+gets a model and the config header says what the effective retention turned
+out to be. A lane is never left without one.
+
+See [docs/KNOWN-LIMITS.md](docs/KNOWN-LIMITS.md) for the rest of what this
+tier cannot do.
+
 ## Requirements
 
 | | |
 |---|---|
 | Node | **22 or newer** — `engines` in package.json, and the CLI uses `node:` prefixed builtins. Node 20 fails at import time, not with a friendly message. |
 | npm | 10 or newer, for `npm ci` when installing from a checkout |
-| OS | macOS, Linux and Windows. No platform checks in the code; the tests run on `ubuntu-latest`. |
-| Shell | none. The CLI never shells out, so no `bash`, `zsh` or `fish` setup is needed. |
-| Network | `list` and `doctor` read models.dev, which is the point of both. Everything else, including `install`, `use` and `verify`, works offline. |
-| Disk | it writes into `~/.config/opencode/` and nothing else. |
+| OS | macOS, Linux and Windows. The tests run on `ubuntu-latest`. |
+| Shell | none needed to *use* the kit — no `bash`, `zsh` or `fish` setup. Two commands shell out to external binaries: `doctor` and `refresh` call `curl` to read models.dev, and `baseline` and the measurement scripts call `sqlite3`. Everything else, including `install`, `use` and `verify`, works offline. |
+| Network | only `doctor` and `refresh` need it, and only to read the live model catalogue. `list` is offline: it reads the shipped profiles. Everything else works offline. |
+| Disk | `use` and `install` write into `~/.config/opencode/` and nothing else. `doctor` writes nothing. `refresh` rewrites a profile in the kit's own
+directory - `node_modules` for an npm install - and keeps a backup of the
+one it replaced. |
 
 `~/.config/opencode/` is your live agent config. `use` and `install` write there,
 `verify` only reads, and `use --dryrun` writes nothing at all. Every write keeps
@@ -218,20 +338,40 @@ a `.bak` next to the file, including under `--yes`.
 
 ```
 oc-harness list       profiles with retention and caveats
-oc-harness show <id>  resolved lanes, derived numbers, fallback chains
+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 use <id>   compile a profile into ~/.config/opencode/opencode.jsonc
-oc-harness use <id> --dryrun   print what would be written, write nothing
+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
 oc-harness install    symlink the plugin, prompts, skills and GLOBAL.md
-oc-harness link       just the plugin and instruction file, no prompts or skills
+oc-harness link       just the plugin, no prompts or skills
 oc-harness verify     check the install against the profile; non-zero on drift
 oc-harness agents     report agents the effort tiering does not reach
 oc-harness lanes      report which lanes the fleet actually used
+oc-harness lanes --json   the same report, for a script
+oc-harness trust      set up npm trusted publishing for this package
 oc-harness doctor     re-check profiles against models.dev and the live config
+oc-harness doctor --watch  poll the catalogue, and report only what changed
+oc-harness refresh --all   re-derive every shipped profile against the live catalogue
+oc-harness upgrade    check for a newer kit, refresh the profiles, rewrite the config
+oc-harness backups   the configs that were replaced, newest first
+oc-harness uninstall remove the plugin, prompts, skills and GLOBAL.md again
+oc-harness cost      what the kit is doing on this project, in numbers
+oc-harness restore <file>  put one back
 oc-harness baseline   measure the current install
+oc-harness run        drive .space/tasks.md to done with the build agent
 ```
 
+Every flag accepts both spellings: `--profile fleet-safe` and
+`--profile=fleet-safe` are the same flag.
+
+Every command that can fail says so in its exit code, so a script can tell
+"the kit says no" from "the kit broke".
+[`docs/EXIT-CODES.md`](docs/EXIT-CODES.md) lists them.
+
+`doctor`, `show` and `lanes` take `--json` and print nothing else, so a
+script gets the answer without parsing prose.
+
 `oc-harness <anything-else>` now exits non-zero with the list of real commands,
 instead of printing help and reporting success.
 
@@ -312,6 +452,12 @@ A lane that is never used is a description the model reads on every turn and
 a free model doing nothing. Cut it from the profile's `roles` and the lane
 leaves the config with it.
 
+The `build` row is not comparable with the others: it includes the turns
+that did the delegating, so it counts the work of the other nine lanes. A
+one-line `build` reply on its own is about a third of that number, and
+rather more on a cold start. [`docs/ROUTING.md`](docs/ROUTING.md) has the
+per-profile tables and what each row measures.
+
 One request is one assistant message, which is one round trip to the provider:
 a lane that makes three tool calls makes three requests. The counters come
 from `.space/telemetry.jsonl`, written by the plugin, never sent anywhere, and
@@ -326,12 +472,12 @@ From one real install:
 
 ```
 CONTEXT PER REQUEST
-  p50   100,942   p90  256,940    p99  481,687    max  547,986
-  fresh input p50  528
+  p50    99,648   p90  246,536    p99  482,779    max  547,986
+  fresh input p50  534
 STORED MESSAGE BYTES
-  tool        116.58 MB   77.9%
-  reasoning    23.10 MB   15.4%
-  text          3.12 MB    2.1%
+  tool        114.78 MB   77.9%
+  reasoning    22.94 MB   15.6%
+  text          3.04 MB    2.1%
 READ PRESSURE
   read calls                 2,966
   grep/glob/list               249
@@ -340,15 +486,15 @@ READ PRESSURE
   cut by the 200-line cap     441
   re-reads with an offset     423
 PERMISSION PRESSURE
-  prompt with kit allowlist  1,002 (18.5%)
+  prompt with kit allowlist  1,002 (19.1%)
 compaction events  0  (never fired)
 ```
 
 Four numbers in that report changed how this kit is configured, and two of them
 reversed an earlier decision:
 
-**Tool output is 78% of stored context**, and sessions re-read ~101k tokens per
-request to add ~528 new ones. That is why pruning here is deterministic and
+**Tool output is 78% of stored context**, and sessions re-read ~100k tokens per
+request to add ~534 new ones. That is why pruning here is deterministic and
 unconditional.
 
 **Read pressure is 11.9 whole-file reads per search.** Every production harness
@@ -364,6 +510,45 @@ reads exceed 51,200 bytes, so that ceiling is not what limits context.
 
 Your numbers stay on your machine; only the script is in the repo.
 
+`npm run measure` is an **observation** about one install: it compares the
+work before the kit landed with the work after, and the work is never the
+same. It says so when the two windows are not comparable, and the gate uses
+the number that is.
+
+`npm run measure:prune` is the attributable one. opencode stores the message
+parts unpruned — the pruner rewrites the outgoing request, not the history —
+so the stored parts of a real session are exactly what the pruner was given,
+and replaying the real pruner over them measures exactly what it removed, on
+the same messages with and without. On one install: **80.5% of the context
+across 60 real sessions**.
+
+## Memory
+
+The kit does not implement memory. A local vector store with embeddings, a
+web UI, auto-capture and a user profile is a large thing to build badly, and
+[`opencode-mem`](https://github.com/tickernelz/opencode-mem) already is one.
+
+What the kit does is make it one flag away and keep the config honest about
+it:
+
+```bash
+oc-harness use fleet-safe --memory        # adds opencode-mem to the plugin list
+oc-harness use fleet-safe --memory=opencode-mem@2.32.0   # a pinned version
+```
+
+Your own plugins are never touched — the entry is **added**, so a config that
+already has it does not grow a second copy, and a config that already has
+other plugins keeps them.
+
+The memory plugin keeps its own configuration in
+`~/.config/opencode/opencode-mem.jsonc`. It stores and searches without one,
+but **auto-capture needs a provider** to summarise a session into a memory, so
+give it one:
+
+```jsonc
+{ "opencodeProvider": "openai", "opencodeModel": "inherit" }
+```
+
 ## The plugins
 
 | module | hook | job |
@@ -371,7 +556,21 @@ Your numbers stay on your machine; only the script is in the repo.
 | `guard.ts` | `tool.execute.before` | Blocks destructive commands in code. Fail-closed. |
 | `prune.ts` | `experimental.chat.messages.transform` | Replaces old tool output with a one-line stub. |
 | `router.ts` | `config`, `event`, `chat.message` | Moves a lane to the next rung of its chain when a route is spent. |
-| `telemetry.ts` | `event`, `chat.message`, `tool.execute.after` | Local JSONL, gitignored, never a network call. |
+| `telemetry.ts` | `event`, `tool.execute.after` | Local JSONL, gitignored, never a network call. |
+
+Both `.space/telemetry.jsonl` and `.space/prune.jsonl` are written in the
+**project**, not wherever opencode was started from. The prune log used to
+land in the process's working directory, which is often your home directory.
+
+**The utility route.** `small_model` is what opencode uses for its short
+auxiliary calls — a title, a one-line summary, a question rewritten. It used
+to be the session model, so every one of those calls paid the session model's
+*reasoning*, and reasoning, not output, is what a short call costs. Measured
+on this tier, a title costs **49 reasoning tokens on DeepSeek and 332 on
+Nemotron 3.5 Super VL**, and DeepSeek answers in 7.2 s against 22.7 s for
+GLM. A fleet now names a cheaper route; a single-model profile keeps its one
+route, because "one route, and it is the one you asked for" is a promise those
+profiles make. The generated file says which route it chose.
 
 `guard.ts` matches against the command a shell would actually run, not the text
 it was handed. It splits on shell separators, honours quotes so that a `;`
@@ -383,11 +582,19 @@ not guard-blocked; it falls through to the `*` ask permission so opencode
 prompts for human approval before publishing.
 
 Writes are scoped to the project directory, with the OS temp directory as the
-one exception GLOBAL.md allows.
+one exception GLOBAL.md allows. That covers every tool that writes: `write`
+and `edit` by their path, `apply_patch` by the paths named in the patch, and
+a bash command by its **working directory** — a command run from `/etc` is
+writing outside the project, whatever the command is.
+
+A write tool whose arguments name no file is blocked rather than allowed
+through: a guard that cannot see what a write touches cannot scope it. And
+if the guard itself cannot decide, it blocks — a guard that quietly passes
+when broken is worse than none.
 
 Pruning keeps user messages, assistant prose, diffs, and the last few turns
-verbatim, and never touches the in-flight turn. Old reasoning is dropped, since
-stale reasoning is worse than none.
+verbatim, and never touches the in-flight turn. Old reasoning is dropped,
+since stale reasoning is worse than none.
 
 `router.ts` fails over **per lane**. A fleet has ten routes, so one spent
 route must not take the other nine down with it: the lane that used the dead
@@ -496,17 +703,37 @@ Writes outside the project still ask, via `external_directory`.
 
 | lane | mode | job | effort |
 |---|---|---|---|
-| `build` | primary | writes and verifies code | middle |
-| `plan` | primary | turns a request into an executable plan | highest |
-| `reviewer` | subagent | two passes, never edits | highest |
-| `locate` | subagent | finds code, reports `file:line`, never designs | lowest |
-| `verify` | subagent | runs checks, never fixes them | lowest |
+| `build` | primary | writes and verifies code | `max` |
+| `plan` | primary | turns a request into an executable plan | `max` |
+| `reviewer` | subagent | two passes, never edits | `max` |
+| `locate` | subagent | finds code, reports `file:line`, never designs | `low` |
+| `verify` | subagent | runs checks, never fixes them | `low` |
 | `vision` | subagent | reads an image or a screenshot | model's |
 | `doc` | subagent | reads a long document or a spec | model's |
-| `schema` | subagent | produces JSON a program can parse | highest |
-| `sweep` | subagent | bulk mechanical sweep, no judgement | lowest |
+| `schema` | subagent | produces JSON a program can parse | `max` |
+| `sweep` | subagent | bulk mechanical sweep, no judgement | `low` / `none` |
 | `longform` | subagent | very long context, or several answers | model's |
 
+The effort column is the request in the profile, resolved against the levels
+of the model the lane actually runs on — so `max` is `max` where the model
+publishes it and the nearest level that does exist where it does not, and
+`none` is no variant at all on a model that cannot turn reasoning off. Run
+`oc-harness show <profile>` for the resolved values and the note explaining
+any difference.
+
+The tier is worth protecting: measured on one install, DeepSeek spends **320
+reasoning tokens a message at `max` and 19 at `low`**, so the lever is a
+factor of 17. A lane that asks for a tier and lands on a model that publishes
+none runs at that model's natural rate instead, and the generated config says
+so in the form `locate=unset(asked low)`.
+
+Three lanes in the unrestricted fleet cannot get their tier, and the
+measurement says they are the three cheapest reasoners on the tier — 116, 59
+and 18 reasoning tokens a message, against 289 for `build` and 198 for
+`plan`, which keep their tier on purpose. The one lane that was genuinely
+expensive was `sweep`, running on a model that reasons 420 tokens a message
+for what is supposed to be a mechanical grep. It does not any more.
+
 `locate` is deliberately *not* called `scout`: OpenCode ships a built-in `scout`
 subagent for dependency and external-docs research, and shipping our own file
 under that name shadowed it with `bash: deny` so it could not do the one thing
@@ -516,6 +743,11 @@ Each lane carries a `steps` cap. It is a loop breaker, not a quality knob: on
 exhaustion OpenCode forces a text-only response, so an agent that has stopped
 making progress reports rather than looping until the context is gone.
 
+Each lane also gets its own `permission.task` rule — `deny` for everything
+except the lanes it may hand work to. That is the mechanism behind "hand the
+job to the lane that has it": a lane that is not allowed to spawn anything
+cannot quietly become a general-purpose agent on the most expensive tier.
+
 ## The skill loop
 
 The lanes above are the *who*. The skills are the *order*, and they load by
@@ -537,6 +769,43 @@ the conversation instead of the requirement.
 Publishing is never a loop step. `space-finish` prepares the change; a human
 decides it ships.
 
+## What it costs, measured
+
+The kit's own A/B - the same task with and without it, ten reps per arm, 120
+agent runs, both arms on the same model, on this repository at a pinned commit
+so anyone can repeat it:
+
+| metric (median) | kit on | kit off |
+|---|---|---|
+| **correct** | **54/60** | **55/60** |
+| tool calls | 12.5 | 8 |
+| input tokens | 56,205 | 10,540 |
+| final context | 39,928 | 12,718 |
+| wall seconds | 43 | 21 |
+| paths written outside the target | 0 | 0 |
+
+**On a task that fits in one read, the kit is a cost.** It spends over five
+times the input tokens and takes twice as long, and the answers are a tie -
+54 against 55, and a second run of the same 120 runs gave 55 against 54.
+The two edit tasks are a tie at 10/10, and the guard stopped no writes in
+either arm.
+
+The earlier version of this table said 52/60 against 59/59 - the kit looked
+clearly worse - and that was the grader's fault: it could not read a
+citation written as `**File:** x` on one line and `**Line:** 105` on the
+next, which is the shape some of the kit's answers took. Re-scoring the
+same 120 runs with the fixed grader gives 34/40 against 30/40 on the lookup
+tasks - the kit ahead, where the old grader had it behind. The full account is in [eval/RESULTS.md](eval/RESULTS.md).
+
+What the kit buys is in the two places that suite cannot see: **long
+sessions**, where the pruner removes 80.5% of the context, and **process** -
+a reviewer that reviews and does not edit, a verify that runs the checks and
+does not fix them, a publish decision that belongs to a human.
+
+Whether it is worth it depends on whether the work is long. A repository of
+one-file lookups should not install this. The full table is in
+[eval/RESULTS.md](eval/RESULTS.md).
+
 ## Known limits
 
 Read [docs/KNOWN-LIMITS.md](docs/KNOWN-LIMITS.md) before relying on failover.
@@ -549,7 +818,7 @@ session starts.
 
 ```bash
 npm install
-npm run check        # everything: build, typecheck, tests, live install, verify
+npm run check        # everything offline: build, typecheck, tests
 ```
 
 Or one layer at a time:
@@ -557,6 +826,7 @@ Or one layer at a time:
 ```bash
 npm test             # model-agnostic assertions, no network, no model calls
 npm run typecheck
+npm run check:install  # the above, plus the live install measurement and verify
 npm run eval         # synthetic: pruning, prompt pressure, effort projection
 npm run measure      # is this install behaving? narrow reads, context
 npm run attribute    # where the context went: fixed overhead vs history
@@ -565,8 +835,8 @@ npm run baseline     # your own install, from scratch
 ```
 
 `eval/ab.mjs` runs the same tasks with and without the kit, to separate the kit
-from the work. It spawns real agents, so it is not part of `npm run check`, and
-it wants a subject it can hand each run a private copy of:
+from the work. It spawns real agents, so it is not part of any check, and it
+wants a subject it can hand each run a private copy of:
 
 ```bash
 node eval/prepare.mjs --repo ~/work/lablab-harness --ref 8a674f5
@@ -576,7 +846,7 @@ node eval/ab.mjs --rescore <saved stream dir>   # re-grade without spawning agen
 
 `npm test` and `npm run typecheck` need nothing but the repo, so CI runs those.
 The rest read `~/.local/share/opencode/opencode.db` and `~/.config/opencode`,
-which only exist on a machine that has run OpenCode with the kit installed -
+which only exist on a machine that has run OpenCode with the kit installed —
 `npm run check:online` additionally hits the model catalog over the network.
 
 Measured results, and the limits they do not cross, are in

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.4.x | yes |
+| 0.3.x | yes |
+| 0.2.x | security fixes only |
+| 0.1.x | security fixes only |
+
+## Reporting a vulnerability
+
+Please report privately through GitHub's
+[private vulnerability reporting](https://github.com/pham-canh/space-harness/security/advisories/new)
+rather than opening a public issue.
+
+Include the affected version, a reproduction, and the expected behaviour.
+You can expect an acknowledgement within 72 hours and a fix or mitigation
+plan within 7 days.
+
+## Scope
+
+`space-harness` runs agent subprocesses and reads harness config. Reports
+that are in scope include path traversal when resolving a capability
+profile, command injection through harness config values, and any way a
+harness writes outside its configured working directory.
+
+Out of scope: anything requiring you to hand over a credential you were
+never given, and issues in the model provider itself.

package/bin/baseline.mjs

@@ -19,18 +19,24 @@ const wantJson = args.includes("--json")
 const dbArg = args.indexOf("--db")
 const DB = dbArg >= 0 ? args[dbArg + 1] : join(homedir(), ".local/share/opencode/opencode.db")
 
+const { canQuerySqlite, sqliteMissingMessage, query: queryDb } = await import("../src/sqlite.js")
+
 if (!existsSync(DB)) {
   console.error(`opencode database not found: ${DB}`)
   console.error("pass --db <path> or run opencode at least once first")
   process.exit(1)
 }
 
+// The sqlite3 CLI, not the library. A missing tool is a thing a person can
+// fix, and the failure used to be a raw `spawnSync sqlite3 ENOENT` stack
+// trace.
+if (!canQuerySqlite()) {
+  console.error(sqliteMissingMessage())
+  process.exit(1)
+}
+
 function query(sql) {
-  const out = execFileSync("sqlite3", ["-json", `file:${DB}?mode=ro`, sql], {
-    encoding: "utf8",
-    maxBuffer: 256 * 1024 * 1024,
-  }).trim()
-  return out ? JSON.parse(out) : []
+  return queryDb(DB, sql)
 }
 
 const ASSISTANT = `json_extract(data,'$.role')='assistant'`
@@ -163,7 +169,9 @@ const topAskers = () => {
 // allowlist, which meant the number it reported was whatever the list looked
 // like when the copy was last edited. Every tuning decision in this project is
 // supposed to rest on this measurement, so it has to measure the real list.
-const { BASH_ALLOWLIST } = await import(new URL("../src/config.js", import.meta.url))
+const { BASH_ALLOWLIST } = await import(
+  new URL("../src/config.js", import.meta.url).href,
+)
 const kitAllowlist = BASH_ALLOWLIST
 const currentAllow = [
   "git status *", "git log *", "git diff *", "grep *",
@@ -184,7 +192,7 @@ const paidEquivalent =
 //
 // This exists because the kit once shipped max_lines 200 / max_bytes 8192 on
 // the reasoning that tight truncation "saves context", and a later install
-// measured 415 of 2,959 reads exceeding 8 KB against 418 reads issued with an
+// measured 415 of 2,966 reads exceeding 8 KB against 423 reads issued with an
 // `offset`. Truncation causes the re-read roughly one for one, and at the
 // measured ~17s median per request that round trip is more expensive than the
 // tokens it saves. Re-run this before changing these numbers again.

package/bin/git-hooks/pre-commit

@@ -1,12 +1,23 @@
 #!/bin/sh
 # Installed by `oc-harness install`. Remove with: rm .git/hooks/pre-commit
 #
-# Runs the offline gate on every commit. The live-install half is deliberately
-# left out: measure and attribute read ~/.local/share/opencode, which is slow,
-# machine-specific, and irrelevant to whether a commit broke the kit.
+# It runs the PROJECT's own checks, and only if the project has any.
 #
-# On a machine that has never run OpenCode, test:install cannot run at all, so
-# this hook uses the subset that needs nothing but the repository.
+# The previous version ran `npm run test:all`, which is a script of THIS KIT,
+# not of the project the hook was installed into. So in every project that
+# installed the kit, every commit failed with:
+#
+#     npm error Missing script: "test:all"
+#
+# until the author reached for --no-verify. A gate that blocks every commit
+# is not a gate.
+#
+# The kit's own repository is the exception, and it is handled by the script
+# list below: `test:all` is there, so the kit gates itself.
+#
+# The live-install half is deliberately left out: measure and attribute read
+# ~/.local/share/opencode, which is slow, machine-specific, and irrelevant to
+# whether a commit broke anything.
 
 set -e
 
@@ -18,13 +29,34 @@ if [ -n "$SKIP_SPACE_HARNESS_HOOK" ]; then
   exit 0
 fi
 
-echo "pre-commit: npm run test:all"
-if ! npm run test:all >/tmp/space-harness-hook.log 2>&1; then
+# No package.json, no JavaScript project, no gate.
+if [ ! -f package.json ]; then
+  exit 0
+fi
+
+# The gate is the project's own test script, if it has one. The kit's own
+# repository has `test:all`, which is the offline half of its gate.
+gate=""
+if node -e "process.exit(require('./package.json').scripts?.['test:all'] ? 0 : 1)" 2>/dev/null; then
+  gate="test:all"
+elif node -e "process.exit(require('./package.json').scripts?.test ? 0 : 1)" 2>/dev/null; then
+  gate="test"
+fi
+
+if [ -z "$gate" ]; then
+  # Nothing to run. A hook that blocks every commit because the project has
+  # no test script is worse than no hook.
+  exit 0
+fi
+
+log="${TMPDIR:-/tmp}/space-harness-hook.log"
+echo "pre-commit: npm run $gate"
+if ! npm run "$gate" >"$log" 2>&1; then
   echo "pre-commit: FAILED. Last lines:"
-  tail -30 /tmp/space-harness-hook.log
+  tail -30 "$log"
   echo ""
   echo "Fix it, or commit with --no-verify if you are certain it is not yours."
   exit 1
 fi
 
-exit 0
+exit 0