opencode-harness-kit 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -12,6 +12,47 @@ is not happening.
 
 ---
 
+## [0.6.4] — 2026-10-23
+
+Fixed, each one found by re-reading what 0.6.3 published, not by running
+anything new:
+
+- **The install command in the README named a package that does not exist.**
+  The Install section said `npx oc-harness init` "from the registry", and
+  `oc-harness` is this kit's binary name, not a package anyone can fetch: the
+  command every new reader was pointed at returns `npm error 404 'oc-harness'
+  is not in this registry`. Every install path in the README now reads
+  `npx -y opencode-harness-kit@latest <cmd>`, bare `oc-harness` is defined
+  once as shorthand for one of the two real forms, and a test pins every
+  `npx` reference in the README to this package. Released because the npm
+  page is a snapshot: the README on npmjs.com renders from the published
+  tarball, so fixing it in git changes nothing for the next visitor.
+- **`profiles/index.json` listed `flint-40b-free` twice**, and the README's
+  shipped-profiles table repeated it with a second, differently-worded
+  note. `oc-harness list` printed twelve rows, `oc-harness init` offered
+  twelve choices, flint twice in both, and the README counted twelve
+  shipped profiles. Eleven profiles ship; one entry remains, carrying the
+  honest note of both. Tests now diff the index, the table and the loader,
+  with no Set to collapse the difference.
+- **`retention.yml` repeated `opencode/flint-40b-free`, and the last key
+  won.** The hand-rolled parser overwrites `models[id]` on every repeat, so
+  the vague 2026-10-22 stub silently replaced the 2026-10-23 record that
+  quotes the provider's terms verbatim - same retention class, wrong date,
+  lost detail. A test now scans the file for repeated keys.
+- **`install` from npx symlinked into the npx cache.** The installer always
+  symlinked the plugin, prompts, skills and GLOBAL.md back to the package
+  root - right from a git checkout ("edit here, live everywhere"), visible
+  breakage from an npx cache that `npm cache clean --force` deletes. From a
+  checkout nothing changes; from npx or any npm install, where `.git` is
+  absent, `install` now copies, so the harness on disk does not dangle the
+  day the cache is cleaned. `verify` and `uninstall` learn that a
+  byte-identical copy of the kit's file is the kit's, and a test installs
+  from a copy of the package with no `.git` into a temp HOME, asserts real
+  files where links used to go, and runs `verify` green.
+
+No runtime change: `dist/`, the plugin and every model-facing artifact are
+byte-for-byte what 0.6.3 shipped.
+
 ## [0.6.3] — 2026-10-23
 
 Nothing here changes the runtime. The plugin, the CLI and `dist/` are
@@ -210,15 +251,19 @@ default fleet was carrying a dead fallback rung in **all ten lanes** while
   release, and it is out of the repository now.
 
   A take is about one machine and one moment, and so is the recording of it.
-  The `.gitignore` already said as much: "a recording stays on the machine
-  that made it until somebody decides, deliberately, to publish it". The
-  decision went the other way, so the file went back where that rule keeps
-  it — `video/build/`, which is ignored — and the README no longer links a
-  video the repository does not carry.
-
-  What is published is still the old `docs/demo/pitch.mp4`: four minutes
-  forty-seven seconds, recorded live from a Mac terminal, with a voice. The
-  npm package never carried a video at all.
+  The `.gitignore` of that release said the same thing: "a recording stays on
+  the machine that made it until somebody decides, deliberately, to publish
+  it". The decision went the other way then, so the file went back where
+  that rule keeps it — `video/build/`, which is ignored — and the README no
+  longer links a video the repository does not carry. (Neither the rule nor
+  the recording survived 0.6.3, which removed the rule along with the
+  demonstration.)
+
+  At the time, what was published on GitHub was still the old
+  `docs/demo/pitch.mp4`: four minutes forty-seven seconds, recorded live
+  from a Mac terminal, with a voice. 0.6.3 removed it, and the history
+  rewrite of that release means no tag carries it today. The npm package
+  never carried a video at all.
 
 ## [0.5.8] — 2026-10-22
 

package/README.md

@@ -20,7 +20,8 @@ git clone https://github.com/pham-canh/opencode-harness-kit.git
 ```
 
 The three steps `init` runs, spelled out for when you want to know what
-happened (prefix with `npx` or `./bin/oc-harness.mjs` to taste):
+happened (prefix each with `npx -y opencode-harness-kit@latest` or
+`./bin/oc-harness.mjs` to taste):
 
 ```bash
 oc-harness use fleet-safe    # compile the profile
@@ -48,7 +49,7 @@ lanes.json                   ← the jobs
 src/                         ← no model name anywhere in here
 ```
 
-Same plugin source, twelve shipped profiles, twelve different behaviours. The
+Same plugin source, eleven shipped profiles, eleven different behaviours. The
 test suite asserts that rather than taking it on faith.
 
 ### How a request travels
@@ -237,7 +238,6 @@ it. One file covers ten jobs either way.
 | `nemotron-3.5-lightning-free` | 5 | 262,144 | — | **may train** |
 | `mimo-v2.6-flash-free` | 5 | 200,000 | — | **may train** |
 | `big-pickle` | 5 | 160,000 | — | **may train** |
-| `flint-40b-free` | 5 | 262,144 | `max` | **may train** |
 
 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.
@@ -306,7 +306,7 @@ 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
+It is not a hypothetical. The day this was written, four of the shipped
 shipped profiles had already drifted from the live catalogue — the
 `temperature` flag had flipped on every one of them.
 
@@ -561,7 +561,8 @@ 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
-oc-harness install    symlink the plugin, prompts, skills and GLOBAL.md
+oc-harness install    symlink the plugin, prompts, skills and GLOBAL.md into the config dir
+                      (from `npx`, they link into a package copy it makes first - see Install)
 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
@@ -857,12 +858,15 @@ One command if you are new here (`init` asks which free profile to run on,
 then runs the two commands below plus `verify`):
 
 ```bash
-npx oc-harness init
+npx -y opencode-harness-kit@latest init
 ```
 
-Two commands, in this order, if you already know which profile you want
-(`npx oc-harness …` from the registry, or `./bin/oc-harness.mjs …` from a
-checkout — they are the same program):
+Two commands, in this order, if you already know which profile you want.
+Two forms of the same program: `npx -y opencode-harness-kit@latest …` from
+the registry, or `./bin/oc-harness.mjs …` from a checkout. Bare `oc-harness`
+elsewhere in this README is shorthand for whichever form installed it —
+`npx` leaves no global binary, so every command already naming just
+`oc-harness` is one of the two above in disguise:
 
 ```bash
 oc-harness use fleet-safe   # writes opencode.jsonc
@@ -873,6 +877,15 @@ 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.
 
+That is the checkout behaviour, and it relies on the repository staying put.
+Run through `npx` — or any package install — there is no repository to hold
+the truth, only a npm cache that `npm cache clean --force` can delete under
+it: the installer then COPIES the package once to
+`~/.config/opencode/kit/` and links into that instead, so `npm cache clean`
+cannot dangle the harness out from under its own config. Same commands, same
+config; `uninstall` takes the copy out with the links, and `verify` judges
+both modes by the same ownership rules.
+
 ### The one command that asks nothing
 
 `init` is the front door for a person: it asks which free profile to run on.

package/bin/oc-harness.mjs

@@ -12,7 +12,7 @@
 // The point of the kit: switching models is a data edit, not a code change.
 // Everything model-specific lives in profiles/<id>.json.
 
-import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync, renameSync, unlinkSync } from "node:fs"
+import { chmodSync, copyFileSync, cpSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync, renameSync, unlinkSync } from "node:fs"
 import { homedir } from "node:os"
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { execFileSync } from "node:child_process"
@@ -56,6 +56,74 @@ const CONFIG_DIR =
 const CONFIG_FILE = join(CONFIG_DIR, "opencode.jsonc")
 const ROOT = import.meta.dirname ? join(import.meta.dirname, "..") : process.cwd()
 
+// A git CHECKOUT is the kit's own source of truth and is expected to stay
+// where it is: everything the kit installs symlinks back at the repository,
+// so an edit there takes effect on the next opencode start.
+//
+// Anything else - `npx`, a plain `npm install` - reached this file through a
+// package cache npm is free to clean at any command, and a symlink INTO that
+// cache is a dangling path the day `npm cache clean --force` runs. For those
+// installs the package is COPIED once to a private, durable place under the
+// config directory, and every install target links into the copy instead.
+const CHECKOUT = existsSync(join(ROOT, ".git"))
+const COPY_ROOT = join(CONFIG_DIR, "kit")
+
+/**
+ * Mirror the package's runtime assets into `COPY_ROOT`.
+ *
+ * Runs at most once per version: a `.source` marker records which package
+ * version the copy was made from, and an install of the same version keeps
+ * the existing copy rather than re-wiping files freshly linked into.
+ *
+ * The copy is whole on purpose. The plugin bundle looks for its profiles and
+ * data by walking up from itself, the prompts and skills are linked per file
+ * out of it, and every asset the behavioral layer needs lives inside it -
+ * which is also what makes `uninstall` clean: one tree, created by one
+ * command, owned by nobody else.
+ */
+function ensurePackageCopy() {
+  if (CHECKOUT) return
+  const want = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version
+  let have = null
+  try {
+    have = readFileSync(join(COPY_ROOT, ".source"), "utf8").trim()
+  } catch {}
+  if (have === want) return
+  rmSync(COPY_ROOT, { recursive: true, force: true })
+  mkdirSync(COPY_ROOT, { recursive: true })
+  for (const name of ["dist", "profiles", "prompts", "skills"]) {
+    cpSync(join(ROOT, name), join(COPY_ROOT, name), { recursive: true })
+  }
+  for (const name of ["lanes.json", "retention.yml", "GLOBAL.md"]) {
+    cpSync(join(ROOT, name), join(COPY_ROOT, name))
+  }
+  writeFileSync(join(COPY_ROOT, ".source"), `${want}\n`)
+}
+
+/**
+ * The root the kit installs FROM: the repository in a checkout, `COPY_ROOT`
+ * otherwise. Calling it at all triggers `ensurePackageCopy()`, so a caller
+ * holding the returned paths can rely on the files existing.
+ *
+ * @returns {string}
+ */
+function kitSourceRoot() {
+  if (CHECKOUT) return ROOT
+  ensurePackageCopy()
+  return COPY_ROOT
+}
+
+/**
+ * The root installed files may POINT at: the repository in a checkout, the
+ * durable package copy otherwise. `isOurs(below)` judges ownership against
+ * it.
+ *
+ * @returns {string}
+ */
+function kitTargetRoot() {
+  return CHECKOUT ? ROOT : COPY_ROOT
+}
+
 const args = process.argv.slice(2)
 const cmd = args[0] ?? "list"
 const has = (f) => args.includes(f)
@@ -382,12 +450,13 @@ function cmdShow(id) {
 }
 
 /**
- * Link the built plugin into ~/.config/opencode/plugins so opencode loads it
- * without an npm install. This is the path to use while developing, and it
- * means the kit is usable before anything is published.
+ * Put the built plugin where opencode loads it from -
+ * ~/.config/opencode/plugins/opencode-harness-kit.js - symlinked at the kit
+ * itself from a checkout, at the durable package copy when the kit was
+ * reached through npm or npx.
  */
 function cmdLink() {
-  const dist = join(ROOT, "dist", "index.js")
+  const dist = join(kitSourceRoot(), "dist", "index.js")
   if (!existsSync(dist)) {
     fail("dist/index.js missing. Run: npm run build")
   }
@@ -426,10 +495,14 @@ function cmdLink() {
 
 /** Where the behavioural layer has to land for the config to mean anything. */
 function installTargets() {
+  // `kitSourceRoot()` is the repository in a checkout, and the durable copy
+  // of the package under the config directory otherwise - an npx cache is
+  // npm's to clean, and links into it would dangle the day it goes.
+  const root = kitSourceRoot()
   return [
-    { src: join(ROOT, "prompts"), dest: join(CONFIG_DIR, "prompts"), kind: "dir" },
-    { src: join(ROOT, "skills"), dest: join(CONFIG_DIR, "skills"), kind: "dir" },
-    { src: join(ROOT, "GLOBAL.md"), dest: join(CONFIG_DIR, "GLOBAL.md"), kind: "file" },
+    { src: join(root, "prompts"), dest: join(CONFIG_DIR, "prompts"), kind: "dir" },
+    { src: join(root, "skills"), dest: join(CONFIG_DIR, "skills"), kind: "dir" },
+    { src: join(root, "GLOBAL.md"), dest: join(CONFIG_DIR, "GLOBAL.md"), kind: "file" },
   ]
 }
 
@@ -607,7 +680,15 @@ function isLegacyAgentLink(full) {
  * prompts, the four skills, the global rules - was a `cp` line in the README
  * that nobody ran. Nothing checked it afterwards, which is how a config ended
  * up pointing at an instruction file that did not exist while still looking
- * correct. Symlinks rather than copies, so the repo stays the source of truth.
+ * correct.
+ *
+ * From a checkout everything symlinks at the repository: edit there, live
+ * everywhere. From npm or npx there is no repository to hold the truth - the
+ * cache that supplied this process can be cleaned at any moment - so the
+ * package is first COPIED to a private, durable place under the config
+ * directory (`~/.config/opencode/kit/`), and every link points in there.
+ * `linkOne` and the ownership checks are unchanged; only what sits at the far
+ * end of the link differs.
  */
 async function cmdInstall() {
   const dist = join(ROOT, "dist", "index.js")
@@ -1180,7 +1261,7 @@ function cmdVerify() {
     problems.push(
       `${kitInstruction} does not exist - the rules in it are not being loaded. Run: oc-harness install`,
     )
-  } else if (!pointsIntoKit(kitTarget)) {
+  } else if (!isOurs(kitTarget)) {
     // The kit's own file, and not a file that happens to have its name. The
     // installer refuses to replace a real file, so a user who already had a
     // GLOBAL.md keeps it - and the check above was satisfied by its mere
@@ -1218,7 +1299,7 @@ function cmdVerify() {
     // The config's own reference is still checked below: the lane's prompt
     // path is a separate thing, and a broken one is worth saying whatever
     // the file at that path happens to be.
-    if (!pointsIntoKit(file)) {
+    if (!isOurs(file)) {
       problems.push(
         `prompts/${role}.md is not the kit's file - the ${role} lane runs on somebody else's instructions. Run: oc-harness install`,
       )
@@ -1372,7 +1453,7 @@ function cmdVerify() {
       // This does not stop the frontmatter check below. A directory that is
       // not the kit's can still be a skill whose name has drifted away from
       // its directory, and that is a second thing worth saying.
-      if (!pointsIntoKit(join(skillsDir, name))) {
+      if (!isOurs(join(skillsDir, name))) {
         problems.push(
           `skills/${name} is not the kit's skill - the ${name} step of the loop runs on somebody else's instructions. Run: oc-harness install`,
         )
@@ -2039,6 +2120,36 @@ function pointsIntoKit(p) {
   }
 }
 
+/**
+ * Whether an installed path holds the kit's file.
+ *
+ * From a checkout that means a link into the repository itself. From npm or
+ * npx the install copied the package to `COPY_ROOT` and linked everything at
+ * THAT, so "ours" is a link into - or a file inside - the copy. Links are
+ * resolved relative to the link and without requiring them to exist, so a
+ * dangling link still counts as the kit's: the state `npm uninstall` leaves
+ * behind, and `uninstall`'s job to fix.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isOurs(p) {
+  if (CHECKOUT) return pointsIntoKit(p)
+  let st
+  try {
+    st = lstatSync(p)
+  } catch {
+    return false
+  }
+  const root = resolve(COPY_ROOT)
+  const under = (q) => q === root || q.startsWith(root + sep) || q.startsWith(root + "/")
+  if (st.isSymbolicLink()) {
+    const target = readlinkSync(p)
+    return under(isAbsolute(target) ? target : resolve(dirname(p), target))
+  }
+  return under(resolve(p))
+}
+
 /**
  * Copy the machine-derived fields of a live catalogue entry into a profile.
  *
@@ -2333,11 +2444,14 @@ function findProjectSpace(startDir) {
  * Remove what the kit installed.
  *
  * The install SYMLINKS the plugin, the prompts, the skills and GLOBAL.md out
- * of the kit's directory and into the config directory. So `npm uninstall`
- * the kit leaves four dangling symlinks behind, and opencode then loads
- * neither the rules nor the guard - and says nothing about it.
- *
- * So the kit can take them back out, and it says what it removed.
+ * of the kit - the repository in a checkout, the durable package copy
+ * otherwise - and into the config directory. So `npm uninstall` the kit
+ * leaves four dangling symlinks behind, and opencode then loads neither the
+ * rules nor the guard - and says nothing about it.
+ *
+ * So the kit can take them back out, and it says what it removed. A copy of
+ * the package under the config directory is the kit's ENTIRELY - it exists
+ * only because `install` made it - so it goes with the links.
  */
 function cmdUninstall() {
   const removed = []
@@ -2358,14 +2472,16 @@ function cmdUninstall() {
     }
     // A symlink is not enough to make it ours. The user may have their own
     // symlink in that directory - to their own prompts, to a shared folder -
-    // and "a symlink in prompts/ is the kit's" would delete it. A link whose
-    // target is inside this package is the kit's; anything else is kept.
+    // and "a symlink in prompts/ is the kit's" would delete it. A link that
+    // is the kit's to manage goes; anything else is kept. Whose a link is is
+    // `isOurs`'s decision: into the repository from a checkout, into the
+    // package copy otherwise.
     //
     // The target is resolved WITHOUT requiring it to exist. A DANGLING link
     // is the case this command exists for - `npm uninstall` leaves four of
     // them behind - and `realpathSync` throws on those, which classified the
     // kit's own broken links as somebody else's and left them in place.
-    const ours = entries.filter((f) => pointsIntoKit(join(full, f)))
+    const ours = entries.filter((f) => isOurs(join(full, f)))
     if (!ours.length) {
       kept.push(`${dir}/ holds real files`)
       continue
@@ -2388,14 +2504,14 @@ function cmdUninstall() {
   for (const t of targets) {
     if (!existsSync(t) && !isSymlink(t)) continue
     try {
-      // Only a link into this package is ours to remove. A real file the
+      // Only a link the kit installed is ours to remove. A real file the
       // user put there is theirs, and so is a link to their own file -
       // `GLOBAL.md` is a standard opencode name.
       if (!isSymlink(t)) {
         kept.push(`${t} is a real file`)
         continue
       }
-      if (!pointsIntoKit(t)) {
+      if (!isOurs(t)) {
         kept.push(`${t} points somewhere else`)
         continue
       }
@@ -2405,6 +2521,18 @@ function cmdUninstall() {
       kept.push(`${t} (could not be removed)`)
     }
   }
+  // The package copy - `~/.config/opencode/kit/` when the kit was reached
+  // through npm or npx - exists only because `install` created it, so it
+  // goes out with the links. Unreachable from a checkout, where no copy
+  // exists.
+  if (!CHECKOUT && existsSync(COPY_ROOT)) {
+    try {
+      rmSync(COPY_ROOT, { recursive: true, force: true })
+      removed.push("kit/ (the package copy this install was built from)")
+    } catch {
+      kept.push(`${COPY_ROOT} (could not be removed)`)
+    }
+  }
   console.log(`\n${bold("uninstall")}\n`)
   for (const r of removed) console.log(`  ${green("✓")} removed ${r}`)
   for (const k of kept) console.log(`  ${yellow("!")} left alone: ${k}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-harness-kit",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Harness kit for OpenCode: capability profiles, a fleet of job lanes with one free model each, role-based reasoning effort, context pruning, and measured baselines.",
   "license": "MIT",
   "homepage": "https://github.com/pham-canh/opencode-harness-kit#readme",

package/profiles/index.json

@@ -110,7 +110,7 @@
       "topEffort": "max",
       "context": 262144,
       "default": false,
-      "note": "Open-weight MoE with about 2.5B active parameters for local coding agents. Knowledge cutoff 2026-06, no image input. May train on prompts during its free period."
+      "note": "Open-weight MoE, 40B total with about 2.5B active parameters, built for coding agents and small enough to serve locally. Full effort ladder, 262k context, 64k output, no image input. Knowledge cutoff 2026-06. May train on prompts during its free period."
     },
     {
       "id": "big-pickle",
@@ -122,17 +122,6 @@
       "context": 160000,
       "default": false,
       "note": "Stealth model, no public identity, no effort levels, no image input. The provider may train on it during its free period."
-    },
-    {
-      "id": "flint-40b-free",
-      "file": "profiles/flint-40b-free.json",
-      "title": "Flint 40B Free",
-      "retention": "may-train",
-      "free": true,
-      "topEffort": "max",
-      "context": 262144,
-      "default": false,
-      "note": "Open-weight MoE, 40B total with about 2.5B active, built for coding agents and small enough to serve locally. Full effort ladder, 262k context, 64k output, no image input."
     }
   ],
   "excluded": [],

package/retention.yml

@@ -110,14 +110,6 @@ models:
     verified: 2026-10-19
     source: https://opencode.ai/docs/zen
 
-  opencode/flint-40b-free:
-    retention: may-train
-    note: >-
-      Free trial endpoint on opencode zen; treated as may-train until terms
-      state otherwise.
-    verified: 2026-10-22
-    source: https://opencode.ai/docs/zen
-
   # --- Paid routes, kept because the catalog still serves them and a profile
   # may be pointed at one. ---