opencode-harness-kit 0.4.3 → 0.4.4

package/bin/oc-harness.mjs

@@ -12,9 +12,9 @@
 // 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 } from "node:fs"
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync } from "node:fs"
 import { homedir } from "node:os"
-import { dirname, join, relative } from "node:path"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { execFileSync } from "node:child_process"
 import { fileURLToPath } from "node:url"
 import { createInterface } from "node:readline/promises"
@@ -43,9 +43,10 @@ import {
   ProfileError,
   parseJsonc,
 } from "../src/profile.js"
-import { generateConfig, globalInstructionsPath } from "../src/config.js"
+import { generateConfig, globalInstructionsPath, utilityModel, withMemoryPlugin, canAddMemoryPlugin, kitVersion, MEMORY_PLUGIN } from "../src/config.js"
+import { ruleNames, BASH_RULES, WRITE_RULES } from "../src/rules.js"
 import { planEffort } from "../src/effort.js"
-import { findTelemetryFile, readLaneUsage, averageMs } from "../src/lane-usage.js"
+import { findTelemetryFiles, readLaneUsage, averageMs } from "../src/lane-usage.js"
 import { main as trustMain } from "../src/trust.js"
 
 const CONFIG_DIR =
@@ -56,9 +57,48 @@ const ROOT = import.meta.dirname ? join(import.meta.dirname, "..") : process.cwd
 const args = process.argv.slice(2)
 const cmd = args[0] ?? "list"
 const has = (f) => args.includes(f)
+/**
+ * The value of a flag, in either spelling.
+ *
+ * `--profile fleet-safe` and `--profile=fleet-safe` are the same flag, and
+ * the second one is the conventional one. Reading only the first form made
+ * `--profile=fleet-safe` look like a flag with a missing value, which is a
+ * confusing way to be told you got the syntax wrong.
+ */
 const opt = (f) => {
   const i = args.indexOf(f)
-  return i >= 0 ? args[i + 1] : undefined
+  if (i >= 0) return args[i + 1]
+  const inline = args.find((a) => a.startsWith(`${f}=`))
+  return inline === undefined ? undefined : inline.slice(f.length + 1)
+}
+/** A flag given as `--flag` or `--flag=value`. */
+const flag = (f) => has(f) || args.some((a) => a.startsWith(`${f}=`))
+
+/**
+ * A number from a flag, or the default.
+ *
+ * `Number("abc")` is NaN, and every comparison against NaN is false - so a
+ * typo in `--max-rounds` silently disabled the round cap AND the time
+ * budget, which are the two limits that keep an unattended loop from
+ * running forever.
+ *
+ * A mistyped cap is refused, not replaced with a default. The cap is the
+ * limit the operator chose, and a substitute is a different limit wearing
+ * the same name - the one thing a cap cannot be. So the run stops here,
+ * before a loop is started, instead of starting one under a limit nobody
+ * asked for.
+ *
+ * @param {string | undefined} raw
+ * @param {number} fallback
+ * @returns {number}
+ */
+const positiveNumber = (raw, fallback) => {
+  if (raw === undefined) return fallback
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n <= 0) {
+    fail(`${raw} is not a positive number. --max-rounds and --budget have to be positive numbers.`)
+  }
+  return n
 }
 
 const stamp = (s) => `\x1b[2m${s}\x1b[0m`
@@ -66,7 +106,10 @@ const bold = (s) => `\x1b[1m${s}\x1b[0m`
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`
 const green = (s) => `\x1b[32m${s}\x1b[0m`
 const red = (s) => `\x1b[31m${s}\x1b[0m`
-const interactive = () => process.stdin.isTTY && !has("--yes")
+// The colour out. The human report wants it; a JSON field does not, and a
+// script that greps the message gets escape bytes it has to know to strip.
+const plain = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "")
+const interactive = () => process.stdin.isTTY && !flag("--yes")
 
 /**
  * A yes question with a yes default. Only asked on a terminal; scripts and
@@ -89,9 +132,9 @@ function index() {
 
 async function cmdList() {
   const idx = index()
-  const retention = loadRetention()
+  const retention = loadRetention().models
   const only = opt("--retention")
-  const freeOnly = has("--free")
+  const freeOnly = flag("--free")
 
   console.log(`\n${bold("opencode-harness-kit")} ${stamp("profiles")}\n`)
   const head = [
@@ -179,10 +222,64 @@ async function cmdList() {
 }
 
 function cmdShow(id) {
-  if (!id) fail("usage: oc-harness show <profile>")
-  const p = loadProfile(id)
+  const wantJson = flag("--json")
+  if (!id) fail("usage: oc-harness show <profile>", wantJson)
+  let p
+  try {
+    p = loadProfile(id)
+  } catch (err) {
+    fail(`profile "${id}" cannot be loaded: ${err instanceof Error ? err.message : String(err)}`, wantJson)
+  }
   const plan = planEffort(id)
-  const retention = loadRetention()[`${p.provider}/${p.model}`]
+  const retention = loadRetention().models[`${p.provider}/${p.model}`]
+
+  // The machine-readable form. "What does this profile resolve to" is a
+  // question a script asks - to check a config, to diff two profiles, to
+  // feed a dashboard.
+  if (wantJson) {
+    console.log(
+      JSON.stringify(
+        {
+          id: p.id,
+          title: p.title ?? null,
+          provider: p.provider,
+          model: p.model,
+          limits: p.limits ?? null,
+          input_cap: inputCap(p),
+          output_cap: p.limits?.output ?? null,
+          effort_levels: p.effort?.levels ?? [],
+          default_variant: resolveDefaultVariant(p) ?? null,
+          temperature: Boolean(p.supports?.temperature),
+          attachment: Boolean(p.supports?.attachment),
+          reserved: reservedTokens(p),
+          prune_at: pruneThreshold(p),
+          retention: effectiveRetention(p).retention,
+          max_retention: p.maxRetention ?? null,
+          lanes: Object.fromEntries(
+            (roleSplitModels(p).length
+              ? roleSplitModels(p).map((s) => [s.role, { model: s.model, chain: resolveLaneChain(p, s.role) }])
+              : Object.keys(p.roles ?? {}).map((role) => [role, { model: p.model, chain: [p.model] }])
+            ),
+          ),
+          effort: plan.roles,
+          fallback: p.fallback ?? [],
+          // The human report calls these two things different things, so the
+          // JSON does too: "adjustments" are what the compiler changed about
+          // the plan, "notes" are what the profile says about itself.
+          adjustments: plan.notes ?? [],
+          notes: p.notes ?? null,
+          retention_note: retention?.note ?? null,
+          guard_rules: ruleNames().map((name) => {
+            const rule = [...BASH_RULES, ...WRITE_RULES].find((r) => r.name === name)
+            return { name, why: rule?.why ?? "" }
+          }),
+        },
+        null,
+        2,
+      ),
+    )
+    return
+  }
 
   console.log(`\n${bold(p.id)}  ${stamp(p.title ?? "")}\n`)
   const row = (k, v) => console.log(`  ${k.padEnd(20)} ${v}`)
@@ -255,6 +352,14 @@ function cmdShow(id) {
     console.log(`\n  ${bold("notes")}`)
     console.log(`    ${p.notes}`)
   }
+  // What the guard blocks, and why. It was the one part of the kit a user
+  // could not inspect at all, and the answer to "why was my command blocked"
+  // was a guess.
+  console.log(`\n  ${bold("guard rules")}`)
+  for (const name of ruleNames()) {
+    const rule = [...BASH_RULES, ...WRITE_RULES].find((r) => r.name === name)
+    console.log(`    ${name.padEnd(34)} ${stamp(rule?.why ?? "")}`)
+  }
   console.log()
 }
 
@@ -291,6 +396,48 @@ function installTargets() {
   ]
 }
 
+/**
+ * The git repository that contains `startDir`, or null.
+ *
+ * Found by walking up, the same way the telemetry file is found: the project
+ * is not necessarily the directory the command was run in.
+ *
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+function gitRoot(startDir) {
+  let dir = resolve(startDir)
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(join(dir, ".git"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * The project root, found by walking up from the working directory.
+ *
+ * opencode reads a project's agent files from `<project>/.opencode/`, and the
+ * project is not necessarily the directory the command was run from. Anchored
+ * on `process.cwd()`, the shadow check below found nothing whenever the
+ * command was run from a subdirectory - which is the one place a shadow is
+ * most likely to hide, because that is where the agent is working.
+ *
+ * @returns {string}
+ */
+function projectRoot() {
+  let dir = process.cwd()
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(join(dir, ".opencode"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return process.cwd()
+}
+
 /**
  * The directories opencode loads agent markdown files from.
  *
@@ -307,11 +454,12 @@ function installTargets() {
  * half of them.
  */
 function agentDirs() {
+  const project = projectRoot()
   return [
     { dir: join(CONFIG_DIR, "agents"), scope: "config" },
     { dir: join(CONFIG_DIR, "agent"), scope: "config" },
-    { dir: join(process.cwd(), ".opencode", "agents"), scope: "project" },
-    { dir: join(process.cwd(), ".opencode", "agent"), scope: "project" },
+    { dir: join(project, ".opencode", "agents"), scope: "project" },
+    { dir: join(project, ".opencode", "agent"), scope: "project" },
   ]
 }
 
@@ -417,13 +565,40 @@ async function cmdInstall() {
     console.log(`  ${stamp(`  ${dest.replace(`${homedir()}/`, "~/")}`)}`)
   }
 
-  // The commit gate lives in the repository, not in the home directory, so it
-  // survives a reinstall and can be reviewed. An existing hook is never
-  // overwritten without asking.
+  // The commit gate lives in the PROJECT's repository, not in the kit's.
+  //
+  // It used to be written to `<kit root>/.git/hooks/pre-commit`, which for a
+  // user running `npx opencode-harness-kit install` is the kit's own
+  // installation directory - a node_modules folder or an npx cache, possibly
+  // read-only, and never the repository the user works in. So the gate was
+  // installed somewhere useless, and running the test suite installed it
+  // into the kit's own repository.
+  //
+  // The repository is the one that contains the directory the command was
+  // run in, found by walking up - the same way the telemetry file is found.
   const hookSrc = fileURLToPath(new URL("./git-hooks/pre-commit", import.meta.url))
-  const hookDest = join(ROOT, ".git/hooks/pre-commit")
-  let hookState = "skipped, not a git repository"
-  if (existsSync(join(ROOT, ".git"))) {
+  const projectGit = gitRoot(process.cwd())
+  const inTheKit = projectGit !== null && resolve(projectGit) === resolve(ROOT)
+  // The hook is installed into the KIT's own repository, or into a project
+  // that asks for it with `--hook`.
+  //
+  // Installing it into every project that installs the kit is a surprise:
+  // the hook is a gate, and a gate nobody asked for is an obstacle. (Where it
+  // IS installed it is useful - the hook runs the PROJECT's own test script,
+  // not the kit's - but it is still the project's call.)
+  const hookDest =
+    projectGit && (inTheKit || flag("--hook"))
+      ? join(projectGit, ".git", "hooks", "pre-commit")
+      : null
+  // The reason a hook was not installed, when it was not. The kit's own
+  // repository is the one place the hook belongs, so "not a git repository"
+  // was never the right answer for it.
+  let hookState = !projectGit
+    ? "skipped, not a git repository"
+    : inTheKit
+      ? "skipped (the kit's own repository installs it)"
+      : "skipped, a hook is the project's call (use --hook to install one)"
+  if (hookDest && !process.env.OC_HARNESS_NO_HOOK) {
     let existing = null
     try {
       existing = readFileSync(hookDest, "utf8")
@@ -434,14 +609,16 @@ async function cmdInstall() {
       hookState = "skipped at the prompt"
     } else {
       try {
-        mkdirSync(join(ROOT, ".git/hooks"), { recursive: true })
+        mkdirSync(join(projectGit, ".git", "hooks"), { recursive: true })
         copyFileSync(hookSrc, hookDest)
         chmodSync(hookDest, 0o755)
         hookState = `installed ${hookDest}`
       } catch (err) {
-        hookState = `could not install: ${err.message}`
+        hookState = `could not install: ${err instanceof Error ? err.message : String(err)}`
       }
     }
+  } else if (process.env.OC_HARNESS_NO_HOOK) {
+    hookState = "skipped (OC_HARNESS_NO_HOOK is set)"
   }
   console.log(`  ${stamp(`pre-commit hook: ${hookState}`)}`)
 
@@ -482,6 +659,18 @@ async function cmdInit() {
   await cmdInstall()
   await cmdUse(id)
   cmdVerify()
+  if (memorySpec()) {
+    console.log(
+      `\n  ${stamp(
+        `memory: ${memorySpec()} is in the plugin list. It keeps its own config in`,
+      )}`,
+    )
+    console.log(
+      `  ${stamp(
+        "~/.config/opencode/opencode-mem.jsonc - give it a provider for auto-capture, or it stores without extracting.",
+      )}`,
+    )
+  }
   console.log(`\n  ${green("✓")} done. ${stamp("restart opencode, then ask it something")}\n`)
 }
 
@@ -535,7 +724,7 @@ function linkOne(src, dest) {
   try {
     symlinkSync(target, dest)
   } catch (err) {
-    console.log(`  ${yellow("!")} ${stamp(`could not link ${dest}: ${err.message}`)}`)
+    console.log(`  ${yellow("!")} ${stamp(`could not link ${dest}: ${err instanceof Error ? err.message : String(err)}`)}`)
   }
 }
 
@@ -557,7 +746,7 @@ function cmdVerify() {
   try {
     p = loadProfile(activeId)
   } catch (err) {
-    fail(`active profile "${activeId}" cannot be loaded: ${err.message}`)
+    fail(`active profile "${activeId}" cannot be loaded: ${err instanceof Error ? err.message : String(err)}`)
   }
 
   // 1. The generated config must still be what the profile compiles to. A
@@ -578,7 +767,13 @@ function cmdVerify() {
 
   // 2. Instruction paths must resolve. An unresolved path is a no-op, not an
   //    error, which is why it can sit there for weeks unnoticed.
-  const instructions = (actual?.instructions ?? [globalInstructionsPath()])
+  //
+  //    The kit's own GLOBAL.md has to be among them. A config whose
+  //    `instructions` array replaced the kit's file was loading none of the
+  //    behavioural layer - the lane table, the rules, the read-pressure
+  //    guidance - and every one of those paths resolved, so the check passed
+  //    over a harness that was doing nothing.
+  const instructions = /** @type {any} */ (actual?.instructions) ?? [globalInstructionsPath()]
   for (const raw of instructions) {
     const target = raw.startsWith("~")
       ? join(homedir(), raw.slice(1))
@@ -593,6 +788,19 @@ function cmdVerify() {
       )
     }
   }
+  const kitInstruction = globalInstructionsPath()
+  const kitTarget = kitInstruction.startsWith("~")
+    ? join(homedir(), kitInstruction.slice(1))
+    : kitInstruction
+  if (!/** @type {any} */ (instructions).includes(kitInstruction)) {
+    problems.push(
+      `the config does not load ${kitInstruction} - the kit's rules, the lane table and the read-pressure guidance are not being loaded. Run: oc-harness use ${p.id}`,
+    )
+  } else if (!existsSync(kitTarget)) {
+    problems.push(
+      `${kitInstruction} does not exist - the rules in it are not being loaded. Run: oc-harness install`,
+    )
+  }
 
   // 3. Every lane the profile enables must have its prompt installed, and the
   //    config's reference to it must resolve. A lane with a model and a
@@ -638,13 +846,21 @@ function cmdVerify() {
     for (const name of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
       const where = `${scope}:${dir.replace(`${homedir()}/`, "~/")}`
       const lane = name.replace(/\.md$/, "")
-      if (lane in (actual?.agent ?? {})) {
+      if (lane in (/** @type {any} */ (actual?.agent) ?? {})) {
         problems.push(
           `agent file ${where}/${name} shadows the ${lane} lane: an agent file replaces the config entry, so the lane would not run on its own model. Run: oc-harness install`,
         )
         continue
       }
-      const text = readFileSync(join(dir, name), "utf8")
+      // A dangling symlink is a routine state after a checkout is moved or a
+      // package directory is deleted. It must not abort the whole report.
+      let text = ""
+      try {
+        text = readFileSync(join(dir, name), "utf8")
+      } catch {
+        problems.push(`agent file ${where}/${name} cannot be read (a broken symlink?)`)
+        continue
+      }
       const named = text.match(/opencode\/([a-z0-9.\-]+)/i)
       if (named && !modelsInPlay(p).includes(named[1])) {
         problems.push(
@@ -668,13 +884,22 @@ function cmdVerify() {
       resolved = realpathSync(pluginLink)
     } catch {}
     const dataRoot = join(dirname(resolved), "..")
-    if (!existsSync(join(dataRoot, "profiles"))) {
+    // The bundle needs three things beside it: the profiles, the lane table
+    // and the retention table. It used to check only the profiles, so a
+    // bundle with a missing retention.yml passed verification and then
+    // resolved every lane to an unknown retention.
+    const missing = ["profiles", "lanes.json", "retention.yml"].filter(
+      (name) => !existsSync(join(dataRoot, name)),
+    )
+    if (missing.length) {
       problems.push(
-        `the plugin at ${resolved} cannot find its profiles (looked in ${dataRoot}). The guard, the pruning and the lane failover would all be silently absent. Run: oc-harness install`,
+        `the plugin at ${resolved} cannot find ${missing.join(", ")} (looked in ${dataRoot}). The guard, the pruning and the lane failover would all be silently absent. Run: oc-harness install`,
       )
     }
   } else {
-    notes.push("no plugin link: the guard is not enforcing anything. Run: oc-harness link")
+    problems.push(
+      "no plugin link: the guard is not enforcing anything, so nothing in this kit is enforced. Run: oc-harness link",
+    )
   }
 
   // 6. Schema check. `variant` at the top level is silently stripped by
@@ -703,7 +928,9 @@ function cmdVerify() {
   const skillsDir = join(CONFIG_DIR, "skills")
   const ourSkills = kitSkillNames()
   if (!existsSync(skillsDir)) {
-    notes.push("no skills directory: the skill loop is not installed. Run: oc-harness install")
+    problems.push(
+      "no skills directory: the skill loop is not installed, so the plan -> build -> review -> finish loop cannot run. Run: oc-harness install",
+    )
   } else {
     const installed = new Set(readdirSync(skillsDir))
     let valid = 0
@@ -789,7 +1016,12 @@ function configDrift(p, actual) {
   const roles = resolveRoles(p)
 
   if (actual.model !== want) out.push(`model ${actual.model} -> ${want}`)
-  if (actual.small_model !== want) out.push(`small_model ${actual.small_model} -> ${want}`)
+  // The utility route, which is the session model unless the profile names
+  // a cheaper one for opencode's short auxiliary calls.
+  const wantUtility = utilityModel(p) ?? want
+  if (actual.small_model !== wantUtility) {
+    out.push(`small_model ${actual.small_model} -> ${wantUtility}`)
+  }
 
   for (const [role, level] of Object.entries(roles)) {
     if (level === undefined) continue
@@ -832,6 +1064,23 @@ function configDrift(p, actual) {
   return out
 }
 
+/**
+ * The memory plugin to turn on, or null when the flag is absent.
+ *
+ * `--memory` turns on the default plugin, and `--memory=<id>` picks another -
+ * a pinned version, or a mirror of it.
+ *
+ * @returns {string | null}
+ */
+function memorySpec() {
+  if (!flag("--memory")) return null
+  const inline = args.find((a) => a.startsWith("--memory="))
+  if (inline) return inline.slice("--memory=".length)
+  const next = opt("--memory")
+  if (next && !next.startsWith("-")) return next
+  return MEMORY_PLUGIN
+}
+
 async function cmdUse(id) {
   if (!id) fail("usage: oc-harness use <profile> [--print] [--yes]")
   const p = loadProfile(id)
@@ -854,32 +1103,48 @@ async function cmdUse(id) {
         `Add an entry with retention: zero-retention | may-train before installing it.`,
     )
   }
-  if (eff.retention === "may-train" && !has("--yes")) {
+  if (eff.retention === "may-train" && !flag("--yes")) {
     const trainOn = roleSplitModels(p)
       .filter((s) => retentionFor(s.model)?.retention === "may-train")
       .map((s) => `${s.role} runs on ${s.model}`)
     const msg =
       `${yellow("!")} ${eff.worst} may train on your prompts and completions.\n` +
       (trainOn.length ? `  ${trainOn.join(", ")}.\n` : "") +
-      `  ${retentionFor(eff.worst)?.note ?? ""}\n` +
-      `  Re-run with --yes to accept.`
-    if (process.stdin.isTTY && !has("--print")) {
-      fail(msg + "\n")
+      `  ${retentionFor(eff.worst)?.note ?? ""}\n`
+    if (process.stdin.isTTY && !flag("--print")) {
+      // On a terminal the run stops here, so the way forward is to accept it.
+      fail(msg + "  Re-run with --yes to accept.\n")
     }
-    console.error(msg)
+    // Without a terminal there is nobody to ask, so the run continues and the
+    // config is written. Telling the user to re-run with --yes at that point
+    // would be asking them to do something that has already happened.
+    console.error(msg + "  Continuing: there is no terminal to ask.\n")
   }
 
   const base = readConfigJson()
+  // `--memory` turns on the memory plugin. The kit does not implement memory
+  // - a local vector store with embeddings, a web UI and auto-capture is a
+  // large thing to build badly, and `opencode-mem` already is one. What the
+  // kit can do is make it one flag away and keep the config honest about it.
+  const memory = memorySpec()
+  const effectiveBase = memory ? withMemoryPlugin(base, memory) : base
+  if (memory && !canAddMemoryPlugin(base)) {
+    console.error(
+      yellow(
+        `  the config's plugin value is not a list, so ${memory} was not added. Fix it by hand.`,
+      ),
+    )
+  }
 
-  const out = generateConfig(p, { base, comments: true })
-  if (has("--print")) {
+  const out = generateConfig(p, { base: effectiveBase, comments: true })
+  if (flag("--print")) {
     process.stdout.write(out)
     return
   }
 
   // A flag that is accepted and then ignored is worse than one that errors:
   // `--dryrun` used to write the real config anyway.
-  if (has("--dryrun")) {
+  if (flag("--dryrun")) {
     console.log(`\n  ${stamp("dry run, nothing written")}`)
     console.log(`  ${stamp(`would write ${CONFIG_FILE}`)}`)
     summary(p)
@@ -892,11 +1157,15 @@ async function cmdUse(id) {
     // `--yes` skips the question, it does not skip the safety net. Gating the
     // backup on `--yes` meant the one path that overwrites without asking was
     // also the one path with nothing to fall back to.
-    if (!has("--yes") && interactive() && !(await confirm(`overwrite ${CONFIG_FILE}? (a .bak backup is kept)`))) {
+    if (!flag("--yes") && interactive() && !(await confirm(`overwrite ${CONFIG_FILE}? (a .bak backup is kept)`))) {
       fail("left the existing config alone")
     }
-    writeFileSync(`${CONFIG_FILE}.bak`, readFileSync(CONFIG_FILE))
-    console.error(stamp(`  existing config backed up to ${CONFIG_FILE}.bak`))
+    const kept = keepBackup(readFileSync(CONFIG_FILE, "utf8"))
+    if (kept) {
+      console.error(
+        stamp(`  existing config backed up to ${join(BACKUP_DIR, kept)}`),
+      )
+    }
   }
   writeFileSync(CONFIG_FILE, out)
   console.log(`\n  ${green("✓")} wrote ${CONFIG_FILE}`)
@@ -945,18 +1214,68 @@ function readConfigJson() {
   return parsed
 }
 
+/**
+ * Where the live model catalogue comes from.
+ *
+ * models.dev is the default and the only source the kit trusts for capability
+ * metadata. The override exists for a mirror, and for a test: a test that
+ * reached the network would fail on a machine that has none, and the kit's
+ * own rule is that the suite runs offline.
+ */
+const CATALOG_URL =
+  process.env.OPENCODE_HARNESS_CATALOG_URL ?? "https://models.dev/api.json"
+
 /** Re-fetch models.dev and report which profiles have drifted from it. */
 async function fetchCatalog() {
-  const url = "https://models.dev/api.json"
+  const url = CATALOG_URL
   try {
-    return JSON.parse(
-      execFileSync("curl", ["-sL", "--max-time", "40", url], {
-        encoding: "utf8",
-        maxBuffer: 64 * 1024 * 1024,
-      }),
-    )
+    // A `file://` URL is read directly. The catalogue override exists for a
+    // mirror and for a test, and a test that needs the `curl` binary is a
+    // test that fails on a minimal CI image.
+    if (url.startsWith("file://")) {
+      const body = readFileSync(url.slice("file://".length), "utf8")
+      const parsed = JSON.parse(body)
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${url} did not return a model catalogue`)
+      }
+      return parsed
+    }
+    // `--fail` matters: without it curl exits 0 on a 4xx or a 5xx and hands
+    // back an error body, which parses as a catalogue with no models in it.
+    // Every profile would then be reported as withdrawn.
+    const body = execFileSync("curl", ["-sL", "--fail", "--max-time", "40", url], {
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    })
+    const parsed = JSON.parse(body)
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${url} did not return a model catalogue`)
+    }
+    return parsed
+  } catch (err) {
+    // THROWN, not exited. The caller decides what a catalogue that cannot be
+    // read means: `doctor --watch` has to carry on, because a catalogue that
+    // cannot be read says nothing about the models in it, and a failed poll
+    // that ends the watch turns a transient network error into a dead
+    // monitor.
+    throw new Error(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+/**
+ * The catalogue, or a clean failure.
+ *
+ * The commands that read it once and go on to do something else want the
+ * error as a message; the ones that watch it want the error as an error, so
+ * they can carry on.
+ *
+ * @returns {Promise<any>}
+ */
+async function fetchCatalogOrFail() {
+  try {
+    return await fetchCatalog()
   } catch (err) {
-    fail(`could not reach ${url}: ${err.message}`)
+    fail(err instanceof Error ? err.message : String(err))
   }
 }
 
@@ -992,10 +1311,498 @@ function diffProfile(p, live) {
  * the fallback queue are human judgements and are never touched by a script:
  * losing a privacy verdict to an automated rewrite would be worse than drift.
  */
+/**
+ * Refresh every shipped profile against the live catalogue.
+ *
+ * A free model is withdrawn in days, so a profile file goes stale in days
+ * too, and there is no way to notice except by looking. This does the
+ * looking for every profile at once and reports what changed.
+ */
+async function cmdRefreshAll() {
+  const catalog = await fetchCatalogOrFail()
+  const ids = listProfileIds()
+  const changed = []
+  const gone = []
+  const same = []
+  for (const id of ids) {
+    const path = profilePath(id)
+    if (!path) continue
+    let p
+    try {
+      p = JSON.parse(readFileSync(path, "utf8"))
+    } catch {
+      continue
+    }
+    const live = catalog?.[p.provider]?.models?.[p.model]
+    if (!live) {
+      gone.push(`${id} (${p.provider}/${p.model})`)
+      continue
+    }
+    const before = diffProfile(p, live)
+    if (!before.length) {
+      same.push(id)
+      continue
+    }
+    applyLiveMetadata(p, live)
+    // `verified` is the field that says when a profile was last checked
+    // against live metadata. Leaving it stale after a refresh makes it a lie.
+    p.verified = new Date().toISOString().slice(0, 10)
+    if (flag("--dryrun")) {
+      changed.push(`${id}: ${before.join(", ")} (dry run, nothing written)`)
+      continue
+    }
+    // A refresh overwrites 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 backup is the only copy.
+    keepProfileBackup(path, readFileSync(path, "utf8"))
+    writeFileSync(path, `${JSON.stringify(p, null, 2)}\n`)
+    changed.push(`${id}: ${before.join(", ")}`)
+  }
+  console.log(`\n${bold("refreshed")}  ${stamp(`${ids.length} profile(s) against the live catalogue`)}\n`)
+  for (const c of changed) console.log(`  ${green("~")} ${c}`)
+  for (const g of gone) console.log(`  ${red("!")} ${g} is no longer in the catalogue`)
+  for (const id of same) console.log(`  ${green("✓")} ${id} already matches`)
+  if (gone.length) {
+    console.log("")
+    console.log(
+      stamp(
+        "A withdrawn model leaves its lane with one fewer rung. Check the chain, and the retention.",
+      ),
+    )
+  }
+  console.log("")
+}
+
+/**
+ * Whether a path is a symlink, whether or not its target exists.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Whether a symlink points into this package.
+ *
+ * The target is resolved RELATIVE TO THE LINK, and without requiring it to
+ * exist, so a dangling link - the thing `npm uninstall` leaves behind -
+ * still counts as the kit's.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function pointsIntoKit(p) {
+  try {
+    if (!lstatSync(p).isSymbolicLink()) return false
+    const target = readlinkSync(p)
+    const resolved = isAbsolute(target) ? target : resolve(dirname(p), target)
+    return resolved.startsWith(ROOT + sep) || resolved.startsWith(ROOT + "/")
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Copy the machine-derived fields of a live catalogue entry into a profile.
+ *
+ * Only the fields a machine can know: the ceilings, the effort levels and the
+ * capability flags. `retention`, `notes`, `roles` and the fallback queue are
+ * human judgements and are never touched.
+ *
+ * @param {any} p the profile, mutated in place
+ * @param {any} live the catalogue entry
+ */
+function applyLiveMetadata(p, live) {
+  p.limits = {
+    ...p.limits,
+    context: live.limit?.context ?? p.limits.context,
+    output: live.limit?.output ?? p.limits.output,
+  }
+  // Many providers publish no separate input ceiling; drop ours so the loader
+  // derives it from the context rather than pinning a stale number.
+  if (live.limit?.input) p.limits.input = live.limit.input
+  else delete p.limits.input
+  const levels = live.reasoning_options?.find((r) => r.type === "effort")?.values ?? []
+  p.effort = {
+    ...p.effort,
+    levels,
+    default: levels.includes(p.effort?.default) ? p.effort.default : levels[levels.length - 1] ?? null,
+  }
+  p.supports = {
+    ...p.supports,
+    reasoning: Boolean(live.reasoning),
+    temperature: Boolean(live.temperature),
+    toolCall: Boolean(live.tool_call),
+    structuredOutput: Boolean(live.structured_output),
+    attachment: Boolean(live.attachment),
+  }
+}
+
+/**
+ * Bring an install up to date.
+ *
+ * Three things go stale on their own, and all three are invisible:
+ *
+ *   - the KIT. A new release can change the config it writes, and the old
+ *     config stays in place until something rewrites it.
+ *   - the PROFILES. A free model is withdrawn in days, and a profile file
+ *     that names a withdrawn model is a lane with one fewer rung.
+ *   - the CONFIG. A profile that changed does not change the config until
+ *     the config is written again.
+ *
+ * So: check the registry for a newer kit, refresh every profile against the
+ * live catalogue, and write the config again.
+ */
+/**
+ * Put back the config the last `use` replaced.
+ *
+ * `use` keeps one `.bak` next to the config, and it OVERWRITES it on the
+ * next run. So there is no history, and the backup does not say which
+ * profile it was - so "go back to what I had" means "remember the old
+ * profile id and run use again", which is not something a person can do at
+ * 2am.
+ *
+ * The backup is now a DIRECTORY of the last few configs, each named with the
+ * profile it came from and the time it was written.
+ */
+const BACKUP_DIR = "backups"
+
+/**
+ * Keep a copy of a profile before it is overwritten.
+ *
+ * @param {string} path the profile file
+ * @param {string} text its current contents
+ */
+function keepProfileBackup(path, text) {
+  try {
+    // NOT inside `profiles/`. That directory is published to npm, and a
+    // backup of a profile is not part of the package - so every refresh
+    // would add a file to the tarball, forever, with nothing pruning them.
+    // The backup belongs next to the config, where the other backups are.
+    const dir = join(CONFIG_DIR, "profile-backups")
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+    writeFileSync(join(dir, `${basename(path, ".json")}-${stamp}.json`), text)
+  } catch {
+    // A backup that cannot be written is not worth failing over.
+  }
+}
+
+/**
+ * Keep a copy of the config before it is overwritten.
+ *
+ * @param {string} text the config as it is now
+ */
+function keepBackup(text) {
+  try {
+    const dir = join(CONFIG_DIR, BACKUP_DIR)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    // The most recent first, and only a few: a backup nobody can read
+    // through is not a backup.
+    const files = readdirSync(dir).filter((f) => f.endsWith(".jsonc")).sort()
+    for (const f of files.slice(0, 9)) rmSync(join(dir, f), { force: true })
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+    const name = `opencode-${stamp}.jsonc`
+    writeFileSync(join(dir, name), text)
+    return name
+  } catch {
+    return null
+  }
+}
+
+/**
+ * List the configs that were replaced.
+ */
+function cmdBackups() {
+  const dir = join(CONFIG_DIR, BACKUP_DIR)
+  if (!existsSync(dir)) {
+    console.log(`\n${bold("backups")}  ${stamp("none yet")}\n`)
+    return
+  }
+  const files = readdirSync(dir).filter((f) => f.endsWith(".jsonc")).sort().reverse()
+  console.log(`\n${bold("backups")}  ${stamp(`${files.length} config(s)`)}\n`)
+  for (const f of files) {
+    const full = join(dir, f)
+    let profile = "?"
+    try {
+      profile = /** @type {any} */ (parseJsonc(readFileSync(full, "utf8")))?.harness?.profile ?? "?"
+    } catch {}
+    console.log(`  ${f.padEnd(40)} ${stamp(`profile ${profile}`)}`)
+  }
+  console.log("")
+  console.log(stamp("restore one with: oc-harness restore <file>"))
+  console.log("")
+}
+
+/**
+ * What the kit is doing on THIS project, in numbers.
+ *
+ * The kit's claim is a trade: it costs a fixed overhead on every request and
+ * buys back the context it prunes. Both numbers are already being written -
+ * the prune log records what each pass removed, and the telemetry records
+ * what each lane cost - and nothing read them together.
+ *
+ * This reads them and puts them next to each other, so the question "is this
+ * kit earning its place here" has an answer that is about THIS project.
+ */
+function cmdCost() {
+  const dir = join(CONFIG_DIR, "..", ".space")
+  const projectSpace = findProjectSpace(process.cwd())
+  const pruneLog = projectSpace ? join(projectSpace, "prune.jsonl") : null
+  const telemetry = projectSpace ? join(projectSpace, "telemetry.jsonl") : null
+
+  console.log(`\n${bold("cost")}  ${stamp(projectSpace ?? "no project found")}\n`)
+
+  // 1. What the pruner removed.
+  let prunes = 0
+  let saved = 0
+  let stubbed = 0
+  if (pruneLog && existsSync(pruneLog)) {
+    try {
+      for (const line of readFileSync(pruneLog, "utf8").split("\n")) {
+        if (!line.trim()) continue
+        const r = JSON.parse(line)
+        prunes++
+        // The published 0.4.3 wrote `savedBytes` into the same file, and the
+        // file is project-local and persistent, so the old records are still
+        // there. Reading only the new name would report every project that
+        // upgraded as having saved nothing.
+        saved += r.savedChars ?? r.savedBytes ?? 0
+        stubbed += r.stubbed ?? 0
+      }
+    } catch {
+      // A log that cannot be read is a log with nothing in it.
+    }
+  }
+  console.log(`  ${bold("pruned")}`)
+  if (!prunes) {
+    console.log(`    ${stamp("nothing yet - the pruner has not run in this project")}`)
+  } else {
+    console.log(`    ${bold(saved.toLocaleString("en-US"))} characters removed over ${prunes} pass(es)`)
+    console.log(`    ${bold(stubbed.toLocaleString("en-US"))} tool outputs stubbed`)
+    console.log(`    ${stamp("the same context, re-sent on every request of the session")}`)
+  }
+
+  // 2. What the lanes cost.
+  const files = findTelemetryFiles(process.cwd())
+  const { lanes: stats, requests } = readLaneUsage(files)
+  console.log("")
+  console.log(`  ${bold("lanes")}  ${stamp(`${requests} request(s)`)}`)
+  const rows = Object.entries(stats)
+    .map(([lane, s]) => ({
+      lane,
+      requests: s.requests,
+      avgCtx: averageMs(s.ctx),
+      avgReasoning: averageMs(s.reasoning),
+    }))
+    .filter((r) => r.requests > 0)
+    .sort((a, b) => (b.avgCtx ?? 0) - (a.avgCtx ?? 0))
+  if (!rows.length) {
+    console.log(`    ${stamp("no lane has been used in this project yet")}`)
+  } else {
+    console.log(
+      `    ${"lane".padEnd(12)}${"reqs".padStart(6)}${"avg ctx".padStart(10)}${"avg reasoning".padStart(15)}`,
+    )
+    for (const r of rows) {
+      console.log(
+        `    ${r.lane.padEnd(12)}${String(r.requests).padStart(6)}${String(r.avgCtx ?? "-").padStart(10)}${String(r.avgReasoning ?? "-").padStart(15)}`,
+      )
+    }
+  }
+
+  // 3. The fixed overhead.
+  console.log("")
+  console.log(`  ${bold("fixed")}`)
+  console.log(`    ${stamp(`kit ${kitVersion()}, ${Object.keys(loadLanes()).length} lanes defined`)}`)
+  const activeId = profileIdFromConfig()
+  if (activeId) {
+    try {
+      const p = loadProfile(activeId)
+      const models = new Set(
+        Object.values(p.roleModels ?? {}).map((r) => r?.model).filter(Boolean),
+      )
+      console.log(`    ${stamp(`profile ${activeId}: ${models.size} model(s) in play`)}`)
+    } catch {
+      // The active profile not loading is `verify`'s job, not this one's.
+    }
+  }
+  console.log("")
+  console.log(stamp("the full measurement, on the whole install: npm run measure:prune"))
+  console.log("")
+}
+
+/**
+ * The `.space` directory of the project, found by walking up.
+ *
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+function findProjectSpace(startDir) {
+  let dir = resolve(startDir)
+  for (let i = 0; i < 12; i++) {
+    const space = join(dir, ".space")
+    if (existsSync(space)) return space
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * 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.
+ */
+function cmdUninstall() {
+  const removed = []
+  const kept = []
+  const targets = [
+    join(CONFIG_DIR, "plugins", "opencode-harness-kit.js"),
+    join(CONFIG_DIR, "GLOBAL.md"),
+  ]
+  for (const dir of ["prompts", "skills"]) {
+    const full = join(CONFIG_DIR, dir)
+    if (!existsSync(full)) continue
+    // A directory of symlinks is ours; a real directory is not.
+    let entries = []
+    try {
+      entries = readdirSync(full)
+    } catch {
+      continue
+    }
+    // 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.
+    //
+    // 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)))
+    if (!ours.length) {
+      kept.push(`${dir}/ holds real files`)
+      continue
+    }
+    for (const f of ours) {
+      try {
+        rmSync(join(full, f), { force: true })
+      } catch {}
+    }
+    removed.push(`${dir}/ (${ours.length} link(s))`)
+  }
+  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
+      // 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)) {
+        kept.push(`${t} points somewhere else`)
+        continue
+      }
+      rmSync(t, { force: true })
+      removed.push(t)
+    } catch {
+      kept.push(t)
+    }
+  }
+  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}`)
+  if (!removed.length) console.log(`  ${stamp("nothing of the kit's was installed here")}`)
+  console.log("")
+  console.log(stamp("the config itself is untouched - remove it by hand if you want it gone"))
+  console.log("")
+}
+
+/**
+ * Put a backup back.
+ */
+function cmdRestore(name) {
+  const dir = join(CONFIG_DIR, BACKUP_DIR)
+  if (!name) {
+    console.log(`\n${bold("restore")}  ${stamp("which one?")}\n`)
+    cmdBackups()
+    return
+  }
+  const file = name.includes("/") ? name : join(dir, name)
+  if (!existsSync(file)) fail(`no such backup: ${file}`)
+  if (existsSync(CONFIG_FILE)) {
+    writeFileSync(`${CONFIG_FILE}.bak`, readFileSync(CONFIG_FILE))
+  }
+  copyFileSync(file, CONFIG_FILE)
+  console.log(`\n  ${green("✓")} restored ${file} into ${CONFIG_FILE}\n`)
+  console.log(stamp("verify with: oc-harness verify"))
+  console.log("")
+}
+
+async function cmdUpgrade() {
+  console.log(`\n${bold("upgrade")}\n`)
+
+  // 1. The kit.
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"))
+  let latest = null
+  try {
+    const out = execFileSync(
+      "npm",
+      ["view", `${pkg.name}@latest`, "version"],
+      { encoding: "utf8", timeout: 30_000 },
+    )
+    latest = out.trim()
+  } catch {
+    console.log(`  ${yellow("!")} could not reach the registry to check for a newer kit`)
+  }
+  if (latest && latest !== pkg.version) {
+    console.log(
+      `  ${yellow("!")} ${pkg.name} ${pkg.version} is installed; ${latest} is published.`,
+    )
+    console.log(stamp(`    update with: npm install -g ${pkg.name}@latest`))
+  } else if (latest) {
+    console.log(`  ${green("✓")} ${pkg.name} ${pkg.version} is the published version`)
+  }
+
+  // 2. The profiles.
+  await cmdRefreshAll()
+
+  // 3. The config.
+  const activeId = profileIdFromConfig() ?? index().default
+  try {
+    loadProfile(activeId)
+  } catch (err) {
+    fail(`the active profile cannot be loaded: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  await cmdUse(activeId)
+  console.log(`  ${green("✓")} the config was written from ${activeId}`)
+  console.log("")
+  console.log(stamp("verify with: oc-harness verify"))
+  console.log("")
+}
+
 async function cmdRefresh(id) {
+  if (!id || id === "--all") {
+    await cmdRefreshAll()
+    return
+  }
   const path = profilePath(id)
   if (!path) fail(`no profile named "${id}"`)
-  const catalog = await fetchCatalog()
+  const catalog = await fetchCatalogOrFail()
   const p = JSON.parse(readFileSync(path, "utf8"))
   const live = catalog?.[p.provider]?.models?.[p.model]
 
@@ -1039,6 +1846,15 @@ async function cmdRefresh(id) {
   }
   p.verified = new Date().toISOString().slice(0, 10)
 
+  if (flag("--dryrun")) {
+    console.log(`\n  ${stamp("dry run, nothing written")}`)
+    for (const line of before) console.log(`      ${line}`)
+    return
+  }
+  // A refresh overwrites 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 backup is the only copy.
+  keepProfileBackup(path, readFileSync(path, "utf8"))
   writeFileSync(path, `${JSON.stringify(p, null, 2)}\n`)
   console.log(`\n  ${green("✓")} refreshed ${path}`)
   for (const line of before) console.log(`      ${line}`)
@@ -1061,12 +1877,209 @@ function chainOf(p) {
   return out
 }
 
-/** Re-check every profile against the live provider catalog. */
+/**
+ * The history of what the catalogue lost.
+ *
+ * A model is withdrawn without a rename and without a notice, so the only
+ * way to know WHEN a lane started failing is to have been looking. The
+ * history is a JSONL file in the config directory, one line per withdrawal.
+ */
+const WITHDRAWN_LOG = "withdrawn.jsonl"
+
+/**
+ * Record that a model left the catalogue.
+ *
+ * @param {string} model
+ * @param {string} profiles the profile ids, comma-separated
+ */
+function recordWithdrawal(model, profiles) {
+  try {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true })
+    appendFileSync(
+      join(CONFIG_DIR, WITHDRAWN_LOG),
+      JSON.stringify({
+        t: new Date().toISOString(),
+        model,
+        profiles: String(profiles ?? "").split(",").filter(Boolean),
+      }) + "\n",
+    )
+  } catch {
+    // A history that cannot be written is not worth failing over.
+  }
+}
+
+/**
+ * Which shipped models are no longer in the live catalogue.
+ *
+ * This is the question a free-tier user actually has to ask, and the answer
+ * is not "has a profile drifted" - it is "is one of my routes gone". A model
+ * that has left the catalogue is a model whose lane now fails over, or whose
+ * chain has one fewer rung, and nobody is told.
+ *
+ * @param {any} catalog
+ * @returns {Map<string, string[]>} the model ids that are gone, and the
+ *   profiles that used each one
+ */
+function withdrawnModels(catalog) {
+  /** @type {Map<string, string[]>} the model, and the profiles that use it */
+  const gone = new Map()
+  for (const id of listProfileIds()) {
+    let p
+    try {
+      p = loadProfile(id)
+    } catch {
+      continue
+    }
+    for (const model of new Set([
+      p.model,
+      // The utility route is a model the kit runs, so it can be withdrawn
+      // like any other.
+      p.utility?.model,
+      ...Object.values(p.roleModels ?? {}).flatMap((r) => r?.chain ?? []),
+    ])) {
+      if (!model) continue
+      if (catalog?.[p.provider]?.models?.[model]) continue
+      const users = gone.get(model) ?? []
+      if (!users.includes(id)) users.push(id)
+      gone.set(model, users)
+    }
+  }
+  return gone
+}
+
+/**
+ * Watch the catalogue and report what disappeared.
+ *
+ * Free models on this tier are withdrawn in days - one of this kit's own
+ * profiles lasted a month, another a day. A weekly `doctor` is the right
+ * rhythm for a human, and this is the shape a cron wants: one run, a non-zero
+ * exit when something is gone, and a line of output that says what.
+ *
+ * `--watch` keeps running and reports only what CHANGED, so it can sit in a
+ * terminal for a week without becoming noise.
+ */
+async function cmdDoctorWatch() {
+  const watch = flag("--watch")
+  // A mistyped interval used to become NaN, and `setTimeout(fn, NaN)` fires
+  // after 0ms - so `--watch --interval abc` hammered models.dev a thousand
+  // times a second.
+  const interval = Math.max(30, positiveNumber(opt("--interval"), 300))
+  const seen = new Set()
+  let first = true
+  for (;;) {
+    /** @type {Map<string, string[]>} */
+    let gone = new Map()
+    try {
+      const catalog = await fetchCatalog()
+      gone = withdrawnModels(catalog)
+    } catch (err) {
+      // A failed fetch is NOT an empty catalogue. Treating it as one
+      // announced every missing model as "is back", emptied the seen-set,
+      // and made the next successful poll announce them all as gone again.
+      console.error(red(`  could not read the catalogue: ${err instanceof Error ? err.message : String(err)}`))
+      if (!watch) process.exit(1)
+      await new Promise((r) => setTimeout(r, interval * 1000))
+      continue
+    }
+    const current = new Set(gone.keys())
+    const fresh = [...gone.keys()].filter((m) => !seen.has(m))
+    for (const m of fresh) {
+      const users = gone.get(m) ?? []
+      console.log(red(`  ${new Date().toISOString()}  ${m} is no longer in the catalogue`))
+      if (users.length) console.log(stamp(`    used by: ${users.join(", ")}`))
+      console.log(stamp(`    fix: oc-harness doctor && oc-harness refresh <profile>`))
+      recordWithdrawal(m, users.join(","))
+    }
+    if (!first) {
+      for (const m of seen) {
+        if (!current.has(m)) {
+          console.log(green(`  ${new Date().toISOString()}  ${m} is back`))
+        }
+      }
+    }
+    seen.clear()
+    for (const m of current) seen.add(m)
+    if (!watch) {
+      if (gone.size) {
+        console.error(
+          red(`  ${gone.size} shipped model(s) are gone: ${[...gone.keys()].join(", ")}`),
+        )
+        console.error(stamp(`  recorded in ${join(CONFIG_DIR, WITHDRAWN_LOG)}`))
+        process.exit(1)
+      }
+      console.log(green("  every shipped model is still in the catalogue"))
+      return
+    }
+    first = false
+    await new Promise((r) => setTimeout(r, interval * 1000))
+  }
+}
+
+/**
+ * Re-check every profile against the live provider catalog.
+ *
+ * Two kinds of finding, and they are not the same kind of finding.
+ *
+ * A profile that has drifted from models.dev is perishable metadata: a
+ * provider changed a context window, or a model left the catalogue. That is
+ * worth reporting, and `oc-harness refresh` is the fix. It is not a broken
+ * install, and a CI job that fails on it fails on a Tuesday because somebody
+ * else changed a provider's limits.
+ *
+ * A config that has drifted from its profile, or an active profile that no
+ * longer loads, is a broken install. That is always a failure.
+ *
+ * `--strict` makes the perishable finding fail too, for a release.
+ */
 async function cmdDoctor() {
-  const catalog = await fetchCatalog()
-  const retention = loadRetention()
+  // In JSON mode the human report is not printed at all. A report that is
+  // half prose and half JSON is a report a script has to strip lines off.
+  const wantJson = flag("--json")
+  // ONE fetch. Two fetches means two round-trips to models.dev, and a
+  // window in which the pre-check and the report can disagree - a model
+  // withdrawn between them.
+  let catalog
+  try {
+    catalog = await fetchCatalog()
+  } catch (err) {
+    // A catalogue that cannot be read is an error, and in JSON mode an
+    // error is a JSON object: a script that pipes the output into a parser
+    // gets something it can read rather than a parse failure.
+    fail(err instanceof Error ? err.message : String(err), wantJson)
+  }
+  // The human report is built while the JSON one is not, and in JSON mode
+  // the human lines go nowhere. They are collected rather than printed, so
+  // the two modes print exactly one thing each.
+  const realLog = console.log
+  if (wantJson) console.log = () => {}
+  try {
+    await runDoctor(catalog)
+  } finally {
+    console.log = realLog
+  }
+  doctorReport.json = wantJson
+  if (wantJson) console.log(JSON.stringify(doctorReport, null, 2))
+  doctorExit()
+}
+
+// The report the doctor fills in. It is rebuilt from scratch every run, so a
+// second doctor in the same process does not inherit the first one's findings.
+const doctorReport = { ok: true, problems: 0, drift: 0, strict: false, findings: [], json: false }
+
+async function runDoctor(catalog) {
+  const retention = loadRetention().models
   const ids = listProfileIds()
   let problems = 0
+  let drift = 0
+  const strict = flag("--strict")
+  // The machine-readable form. "Is the install healthy" is a question a CI
+  // job or a script asks, and the human report answers it in prose that has
+  // to be parsed.
+  doctorReport.findings = []
+  const findings = doctorReport.findings
+  /** @param {string} level @param {string} profile @param {string} message */
+  const note = (level, profile, message) =>
+    findings.push({ level, profile, message: plain(message) })
 
   console.log(`\n${bold("doctor")}  ${stamp(`catalog ${Object.keys(catalog).length} providers`)}\n`)
 
@@ -1075,14 +2088,17 @@ async function cmdDoctor() {
     try {
       p = loadProfile(id)
     } catch (err) {
-      console.log(`  ${red("✗")} ${id.padEnd(32)} ${err.message}`)
+      const message = err instanceof Error ? err.message : String(err)
+      console.log(`  ${red("✗")} ${id.padEnd(32)} ${message}`)
+      note("problem", id, message)
       problems++
       continue
     }
     const live = catalog?.[p.provider]?.models?.[p.model]
     if (!live) {
       console.log(`  ${red("✗")} ${id.padEnd(32)} ${red("not in models.dev - may be withdrawn")}`)
-      problems++
+      note("drift", id, "not in models.dev - may be withdrawn")
+      drift++
       continue
     }
 
@@ -1111,15 +2127,16 @@ async function cmdDoctor() {
     if (issues.length === 0) {
       console.log(`  ${green("✓")} ${id.padEnd(32)} ${stamp("matches catalog")}`)
     } else {
-      problems++
+      drift++
       console.log(`  ${yellow("!")} ${id.padEnd(32)} ${yellow("drift")}`)
       for (const i of issues) console.log(`      ${i}`)
       console.log(`      ${stamp(`fix: oc-harness refresh ${id}`)}`)
+      for (const i of issues) note("drift", id, i)
     }
   }
   console.log(
-    problems
-      ? `\n  ${yellow(`${problems} profile(s) drifted`)}\n`
+    drift
+      ? `\n  ${yellow(`${drift} profile(s) drifted`)}\n`
       : `\n  ${green("all profiles match live metadata")}\n`,
   )
 
@@ -1132,21 +2149,79 @@ async function cmdDoctor() {
   const activeId = profileIdFromConfig()
   if (!activeId) {
     console.log(`  ${yellow("!")} ${stamp("no profile recorded in the config. Run: oc-harness use <profile>")}\n`)
+    note("problem", "-", "no profile recorded in the config")
+    problems++
+    doctorReport.problems = problems
+    doctorReport.drift = drift
+    doctorReport.strict = strict
+    doctorReport.ok = problems === 0 && (drift === 0 || !strict)
     return
   }
   const installed = existsSync(CONFIG_FILE) ? readConfigJson() : null
   if (!installed) {
     console.log(`  ${yellow("!")} ${stamp(`${CONFIG_FILE} missing. Run: oc-harness use ${activeId}`)}\n`)
+    note("problem", activeId, `${CONFIG_FILE} missing`)
+    problems++
+    doctorReport.problems = problems
+    doctorReport.drift = drift
+    doctorReport.strict = strict
+    doctorReport.ok = problems === 0 && (drift === 0 || !strict)
     return
   }
-  const drift = configDrift(loadProfile(activeId), installed)
+  // A config pointing at a profile that no longer loads is a real problem, and
+  // it used to throw here and lose the whole report.
+  let active = null
+  try {
+    active = loadProfile(activeId)
+  } catch (err) {
+    const message = `the active profile "${activeId}" cannot be loaded: ${err instanceof Error ? err.message : String(err)}`
+    console.log(`  ${red("✗")} ${stamp(message)}`)
+    console.log(`  ${stamp("fix: oc-harness use " + (index().default ?? "fleet-safe"))}\n`)
+    note("problem", activeId, message)
+    problems++
+    active = null
+  }
+  const fields = active ? configDrift(active, installed) : []
   console.log(`${bold("installed config")}  ${stamp(activeId)}\n`)
-  if (drift.length === 0) {
+  if (fields.length === 0) {
     console.log(`  ${green("✓")} ${stamp("opencode.jsonc matches the profile")}`)
   } else {
-    for (const d of drift) console.log(`  ${yellow("!")} ${d}`)
-    console.log(`\n  ${yellow(`${drift.length} field(s) drifted from the profile`)}`)
+    for (const d of fields) console.log(`  ${yellow("!")} ${d}`)
+    console.log(`\n  ${yellow(`${fields.length} field(s) drifted from the profile`)}`)
     console.log(`  ${stamp(`fix: oc-harness use ${activeId}`)}\n`)
+    for (const d of fields) note("drift", activeId, d)
+    problems++
+  }
+  doctorReport.problems = problems
+  doctorReport.drift = drift
+  doctorReport.strict = strict
+  doctorReport.ok = problems === 0 && (drift === 0 || !strict)
+}
+
+/**
+ * The exit code of `doctor`.
+ *
+ * A broken install fails. A profile that has drifted from models.dev is
+ * perishable metadata and only fails under `--strict`, so a CI job that runs
+ * this does not go red because a provider changed a context window.
+ *
+ * Reads the report the doctor filled in, and exits with the code the
+ * report implies.
+ */
+function doctorExit() {
+  const { problems, drift, strict, json } = doctorReport
+  // The exit code is the point of the command, and it is the same either
+  // way. In JSON mode the report is the output, so nothing else is printed.
+  if (problems > 0) {
+    if (!json) console.log(`  ${red(`${problems} problem(s) in the install`)}\n`)
+    process.exit(1)
+  }
+  if (drift > 0 && strict) {
+    if (!json) console.log(`  ${red(`${drift} profile(s) drifted from live metadata`)}\n`)
+    process.exit(1)
+  }
+  if (drift > 0 && !json) {
+    console.log(`  ${stamp(`${drift} profile(s) drifted from live metadata; re-run with --strict to fail on it`)}\n`)
   }
 }
 
@@ -1165,17 +2240,50 @@ function cmdLanes() {
   try {
     profile = loadProfile(activeId)
   } catch (err) {
-    fail(`active profile "${activeId}" cannot be loaded: ${err.message}`)
+    fail(`active profile "${activeId}" cannot be loaded: ${err instanceof Error ? err.message : String(err)}`)
   }
 
   // The plugin writes to the project root, so the file is found by walking up
   // from here. Reading `process.cwd()` alone reported "never called" for every
   // lane whenever the command was run from a subdirectory.
-  const file = findTelemetryFile(process.cwd())
-  const { lanes: stats, records, ignored } = readLaneUsage(file)
-
-  console.log(`\n${bold("lanes")}  ${stamp(`${activeId} - ${records} lane request(s)`)}\n`)
+  // ALL the telemetry files, oldest first. The plugin rotates the file at
+  // 4 MB, and reading only the newest one made every lane report "never
+  // used" the moment a rotation happened.
+  const files = findTelemetryFiles(process.cwd())
+  const { lanes: stats, requests, ignored } = readLaneUsage(files)
   const lanes = Object.keys(profile.roles ?? {})
+
+  // The machine-readable form, because "which lanes earn their place" is a
+  // question a script answers, not a person.
+  if (flag("--json")) {
+    const out = {}
+    for (const lane of lanes) {
+      const s = stats[lane]
+      out[lane] = s
+        ? {
+            requests: s.requests,
+            avg_ms: averageMs(s.ms),
+            avg_ctx: averageMs(s.ctx),
+            avg_reasoning: averageMs(s.reasoning),
+            models: [...s.models],
+          }
+        : { requests: 0, avg_ms: null, avg_ctx: null, avg_reasoning: null, models: [] }
+    }
+    // The key is "usage", not "lanes": `show --json` uses "lanes" for the
+    // lane TABLE - which model each lane runs on - and two commands in one
+    // package using one name for two different shapes is how a script ends
+    // up reading the wrong one.
+    console.log(
+      JSON.stringify(
+        { profile: activeId, requests, ignored, usage: out },
+        null,
+        2,
+      ),
+    )
+    return
+  }
+
+  console.log(`\n${bold("lanes")}  ${stamp(`${activeId} - ${requests} lane request(s)`)}\n`)
   if (!lanes.length) {
     console.log(`  ${stamp("this profile enables no lanes")}\n`)
     return
@@ -1184,10 +2292,11 @@ function cmdLanes() {
     "  " + "lane".padEnd(12),
     "reqs".padStart(7),
     "avg ms".padStart(9),
-    "model".padEnd(32),
+    "avg ctx".padStart(10),
+    "model".padEnd(30),
   ].join("  ")
   console.log(head)
-  console.log("  " + "-".repeat(64))
+  console.log("  " + "-".repeat(70))
 
   let unused = 0
   for (const lane of lanes) {
@@ -1200,18 +2309,21 @@ function cmdLanes() {
           "  " + lane.padEnd(12),
           String(0).padStart(7),
           "-".padStart(9),
-          (model ?? "-").padEnd(32),
+          "-".padStart(10),
+          (model ?? "-").padEnd(30),
         ].join("  ") + yellow("  never used"),
       )
       continue
     }
     const avg = averageMs(s.ms)
+    const ctx = averageMs(s.ctx)
     console.log(
       [
         "  " + lane.padEnd(12),
         String(s.requests).padStart(7),
         String(avg ?? "-").padStart(9),
-        ([...s.models].join(", ") || model || "-").padEnd(32),
+        String(ctx ?? "-").padStart(10),
+        ([...s.models].join(", ") || model || "-").padEnd(30),
       ].join("  "),
     )
   }
@@ -1228,7 +2340,11 @@ function cmdLanes() {
     `  ${stamp("one request is one assistant message; avg ms covers the requests that finished")}`,
   )
   console.log(
-    `  ${stamp(`telemetry is read from ${file ?? "no .space/telemetry.jsonl found by walking up from here"}`)}\n`,
+    `  ${stamp(
+      files.length
+        ? `telemetry is read from ${files.join(", ")}`
+        : "no .space/telemetry.jsonl found by walking up from here",
+    )}\n`,
   )
   if (ignored) {
     console.log(
@@ -1306,7 +2422,13 @@ function cmdAgents() {
       const resolved = target.startsWith("~") ? join(homedir(), target.slice(1)) : target
       if (!existsSync(resolved)) notes.push(`prompt ${target} is not installed`)
     }
-    if (lane in roles && roles[lane] === undefined) notes.push("not tiered by the profile")
+    // A lane the profile does not tier at all gets no variant, and a lane
+    // whose model publishes no such level gets none either. `resolveRoles`
+    // returns null for the second case and never undefined, so the check
+    // that used to be `=== undefined` was never true and reported nothing.
+    if (lane in roles && roles[lane] === null) {
+      notes.push("the profile asks for a level this model does not publish, so no variant is set")
+    }
 
     if (!notes.length) {
       console.log(
@@ -1324,10 +2446,16 @@ function cmdAgents() {
   // the most expensive tier. That is exactly the waste this kit exists to
   // remove, and it is invisible otherwise.
   for (const file of files) {
-    const text = readFileSync(file, "utf8")
+    let text = ""
+    try {
+      text = readFileSync(file, "utf8")
+    } catch {
+      console.log(`  ${yellow("!")} ${file.split("/").pop().padEnd(14)} ${yellow("cannot be read")}`)
+      continue
+    }
     const name = file.split("/").pop().replace(/\.md$/, "")
     const front = stripFrontmatter(text)
-    if (name in config.agent) {
+    if (name in /** @type {any} */ (config.agent)) {
       console.log(
         `  ${yellow("!")} ${name.padEnd(14)} ${yellow("shadows a lane in the config")}`,
       )
@@ -1347,7 +2475,22 @@ function cmdAgents() {
   console.log(`  ${stamp("add `model:` and `variant:` to the agent frontmatter, or map them in the profile")}\n`)
 }
 
-function fail(msg) {
+/**
+ * Stop, with a message.
+ *
+ * In JSON mode the message is a JSON object on STDOUT, so a script that pipes
+ * the output into a parser gets an error it can read instead of a parse
+ * failure. The human form still goes to stderr, where an error belongs.
+ *
+ * @param {string} msg
+ * @param {boolean} [wantJson]
+ */
+function fail(msg, wantJson = false) {
+  if (wantJson) {
+    console.log(JSON.stringify({ ok: false, error: plain(msg) }, null, 2))
+    console.error(`\n  ${red("error")} ${msg}\n`)
+    process.exit(1)
+  }
   console.error(`\n  ${red("error")} ${msg}\n`)
   process.exit(1)
 }
@@ -1361,13 +2504,19 @@ function fail(msg) {
  * reading the transcript.
  */
 async function cmdRun() {
+  // Read the caps before anything is started. A mistyped cap has to stop the
+  // run here, while the answer is still "that is not a number" - not after a
+  // loop has been stood up under a limit nobody asked for.
+  const maxRounds = positiveNumber(opt("--max-rounds"), 20)
+  const budgetMinutes = positiveNumber(opt("--budget"), 120)
+
   const { runLoop } = await import("../src/driver/run.mjs")
 
   const result = runLoop({
     cwd: process.cwd(),
     role: opt("--role") ?? "build",
-    maxRounds: Number(opt("--max-rounds") ?? 20),
-    budgetMinutes: Number(opt("--budget") ?? 120),
+    maxRounds,
+    budgetMinutes,
   })
 
   const s = result.summary
@@ -1392,6 +2541,21 @@ try {
     case "refresh":
       await cmdRefresh(args[1])
       break
+    case "upgrade":
+      await cmdUpgrade()
+      break
+    case "backups":
+      cmdBackups()
+      break
+    case "uninstall":
+      cmdUninstall()
+      break
+    case "cost":
+      cmdCost()
+      break
+    case "restore":
+      cmdRestore(args[1])
+      break
     case "link":
       cmdLink()
       break
@@ -1414,7 +2578,8 @@ try {
       process.exitCode = await trustMain(args.slice(1))
       break
     case "doctor":
-      await cmdDoctor()
+      if (flag("--watch") || flag("--check-models")) await cmdDoctorWatch()
+      else await cmdDoctor()
       break
     case "baseline":
       await import("./baseline.mjs")
@@ -1422,6 +2587,13 @@ try {
     case "run":
       await cmdRun()
       break
+    case "--version":
+    case "-v":
+    case "version":
+      console.log(
+        JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version,
+      )
+      break
     case "help":
     default:
       console.log(`
@@ -1439,6 +2611,11 @@ try {
     lanes         report which lanes the fleet actually used
     trust         set up npm trusted publishing for this package
     doctor    re-check profiles against models.dev and the installed config
+    upgrade   check for a newer kit, refresh the profiles, rewrite the config
+    backups   the configs that were replaced, newest first
+    uninstall remove the plugin, prompts, skills and GLOBAL.md again
+    cost      what the kit is doing on this project, in numbers
+    restore <file>  put one back
     baseline  measure the current opencode install
     run       drive .space/tasks.md to done with the build agent
 
@@ -1447,6 +2624,12 @@ try {
     --yes          accept a retention warning, back up the old config
     --retention    filter list by retention class
     --free         list free profiles only
+    --memory       turn on the memory plugin (--memory=<id> to pick one)
+    --strict       doctor: fail on perishable catalogue drift too
+    --watch        doctor: keep watching the catalogue, report what disappeared
+    --check-models doctor: one run, non-zero when a shipped model is gone
+    --json        doctor, show, lanes: print the machine-readable form, and
+                  nothing else
 
   run options
     --role <agent>  which agent does the work (default: build)
@@ -1462,5 +2645,5 @@ try {
   }
 } catch (err) {
   if (err instanceof ProfileError) fail(err.message)
-  fail(err.message)
+  fail(err instanceof Error ? err.message : String(err))
 }