opencode-harness-kit 0.2.0 → 0.3.3

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 } from "node:fs"
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, relative } from "node:path"
 import { execFileSync } from "node:child_process"
@@ -25,16 +25,27 @@ import {
   listProfileIds,
   profileIdFromConfig,
   profilePath,
+  inputCap,
   pruneThreshold,
   reservedTokens,
   effectiveRetention,
+  modelsInPlay,
+  retentionFor,
   roleSplitModels,
   resolveDefaultVariant,
   resolveRoles,
+  resolveRoleModel,
+  resolveLaneChain,
+  resolveLaneModel,
+  modelRetention,
+  loadLanes,
+  laneNames,
   ProfileError,
+  parseJsonc,
 } from "../src/profile.js"
 import { generateConfig, globalInstructionsPath } from "../src/config.js"
 import { planEffort } from "../src/effort.js"
+import { findTelemetryFile, readLaneUsage, averageMs } from "../src/lane-usage.js"
 
 const CONFIG_DIR =
   process.env.OPENCODE_CONFIG_DIR ?? join(homedir(), ".config/opencode")
@@ -84,33 +95,58 @@ async function cmdList() {
   console.log(`\n${bold("opencode-harness-kit")} ${stamp("profiles")}\n`)
   const head = [
     "  " + "profile".padEnd(30),
-    "ctx".padStart(9),
+    "input".padStart(9),
     "top".padStart(7),
+    "lanes".padStart(6),
     "retention".padEnd(15),
   ].join("  ")
   console.log(head)
-  console.log("  " + "-".repeat(72))
+  console.log("  " + "-".repeat(79))
 
   for (const entry of idx.profiles ?? []) {
     if (only && entry.retention !== only) continue
     if (freeOnly && entry.free === false) continue
-    const r = retention[`opencode/${entry.id}`]
+    // The retention lookup is keyed on the model, not the profile id: a fleet
+    // profile's id is not a model, and looking it up by id silently found
+    // nothing, which is why the disagreement below never fired for one.
+    let model = entry.id
+    let lanes = 0
+    let effective = entry.retention
+    // The number that matters is the input cap the config can actually use:
+    // the narrowest lane model's on a fleet, the model's own on a
+    // single-model profile. The base model's context is a different number
+    // and it is printed by `show` and by the generated header.
+    let cap = entry.context ?? 0
+    try {
+      const loaded = loadProfile(entry.id)
+      model = loaded.model
+      lanes = Object.keys(loaded.roles ?? {}).length
+      // A fleet's retention is the worst of the models it resolves to, not the
+      // base model's. Comparing the base would report every fleet as
+      // disagreeing with retention.yml, which records the base model's terms.
+      effective = effectiveRetention(loaded).retention
+      cap = inputCap(loaded)
+    } catch {
+      model = entry.id
+    }
+    const r = retention[`opencode/${model}`]
     const isDefault = entry.default
     const name = (isDefault ? green("▸ ") : "  ") + entry.id
     const top = entry.topEffort ?? stamp("—")
     const ret =
-      entry.retention === "zero-retention"
-        ? green(entry.retention)
-        : yellow(entry.retention)
+      effective === "zero-retention"
+        ? green(effective)
+        : yellow(effective)
     const mismatch =
-      r && r.retention && r.retention !== entry.retention
+      r && r.retention && r.retention !== effective && lanes === 0
         ? ` ${red(`(retention.yml says ${r.retention})`)}`
         : ""
     console.log(
       [
         "  " + name.padEnd(32),
-        (entry.context ?? 0).toLocaleString("en-US").padStart(9),
+        cap.toLocaleString("en-US").padStart(9),
         String(top).padStart(7),
+        String(lanes).padStart(6),
         ret.padEnd(15),
       ].join("  ") + mismatch,
     )
@@ -125,6 +161,17 @@ async function cmdList() {
       console.log(`      ${yellow(entry.reason)}`)
     }
   }
+  // The routes that died. A profile is perishable, and a tier that turns over
+  // in days is the reason the fleet has chains instead of pins - so the ones
+  // that went are named, with what replaced them.
+  const gone = idx.withdrawn ?? []
+  if (gone.length) {
+    console.log("\n  " + stamp("no longer on the tier"))
+    for (const entry of gone) {
+      console.log(`  ${red("✗")} ${entry.id}`)
+      console.log(`      ${stamp(entry.reason)}`)
+    }
+  }
   console.log(
     `\n  ${stamp("install one:")} oc-harness use <profile>\n  ${stamp("inspect:")}   oc-harness show <profile>\n`,
   )
@@ -134,13 +181,17 @@ function cmdShow(id) {
   if (!id) fail("usage: oc-harness show <profile>")
   const p = loadProfile(id)
   const plan = planEffort(id)
-  const retention = loadRetention()[`opencode/${p.provider}/${p.model}`]
+  const retention = loadRetention()[`${p.provider}/${p.model}`]
 
   console.log(`\n${bold(p.id)}  ${stamp(p.title ?? "")}\n`)
   const row = (k, v) => console.log(`  ${k.padEnd(20)} ${v}`)
   row("provider/model", `${p.provider}/${p.model}`)
   row("context", p.limits.context.toLocaleString("en-US"))
-  row("input cap", (p.limits.input ?? p.limits.context).toLocaleString("en-US"))
+  // The cap that actually governs: the narrowest lane model's on a fleet, the
+  // model's own on a single-model profile. Printing the base model's number
+  // next to a prune threshold derived from another one made the two
+  // irreconcilable on the screen.
+  row("input cap", inputCap(p).toLocaleString("en-US"))
   row("output cap", p.limits.output.toLocaleString("en-US"))
   row("effort levels", p.effort?.levels?.length ? p.effort.levels.join(" < ") : "(not tunable)")
   row("default variant", resolveDefaultVariant(p) ?? "(none)")
@@ -156,14 +207,31 @@ function cmdShow(id) {
     console.log(`  ${"".padEnd(20)} ${stamp(`base ${p.model} is ${p.retention}, but ${eff.worst} makes the whole profile ${eff.retention}`)}`)
   }
   if (roleSplitModels(p).length) {
-    console.log(`\n  ${bold("role models")}`)
+    console.log(`\n  ${bold("lanes")}`)
     for (const s of roleSplitModels(p)) {
       const cap = s.limits ? `  out ${s.limits.output.toLocaleString("en-US")}` : ""
+      const chain = resolveLaneChain(p, s.role)
+      const via = chain.length > 1 ? `  via ${chain.join(" → ")}` : ""
       console.log(`  ${s.role.padEnd(20)} ${s.model}${cap}`)
+      if (via) console.log(`  ${"".padEnd(20)} ${stamp(via.trim())}`)
+    }
+  } else {
+    console.log(`\n  ${bold("lanes")}`)
+    for (const role of Object.keys(p.roles ?? {})) {
+      console.log(`  ${role.padEnd(20)} ${p.model}`)
     }
   }
 
-  console.log(`\n  ${bold("role effort")}`)
+  if (p.maxRetention && p.maxRetention !== p.retention) {
+    console.log(
+      `\n  ${bold("retention ceiling")} ${p.maxRetention}`,
+    )
+    console.log(
+      `  ${stamp("a lane may only resolve to a model at or below this")}`,
+    )
+  }
+
+  console.log(`\n  ${bold("lane effort")}`)
   for (const [role, level] of Object.entries(plan.roles)) {
     const want = p.roles?.[role]
     const arrow = want && want !== level ? ` ${stamp(`(requested ${want})`)}` : ""
@@ -216,12 +284,69 @@ function cmdLink() {
 /** Where the behavioural layer has to land for the config to mean anything. */
 function installTargets() {
   return [
-    { src: join(ROOT, "agents"), dest: join(CONFIG_DIR, "agents"), kind: "dir" },
+    { 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" },
   ]
 }
 
+/**
+ * The directories opencode loads agent markdown files from.
+ *
+ * Measured on OpenCode 1.19, not read off the docs:
+ *
+ *   - `$CONFIG_DIR/agents/` and `$CONFIG_DIR/agent/` are both read, and when
+ *     the same name is in both the plural directory wins.
+ *   - `<project>/.opencode/agents/` and `<project>/.opencode/agent/` are both
+ *     read. A `./agent/` in the project root is not.
+ *
+ * A file in any of them replaces the config entry of the same name
+ * wholesale, so a shadow in the singular directory is exactly as dangerous as
+ * one in the plural one, and a checker that only looks at `agents/` misses
+ * half of them.
+ */
+function agentDirs() {
+  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" },
+  ]
+}
+
+/**
+ * Remove the agent files an earlier version of this kit installed.
+ *
+ * They used to carry the model in their frontmatter, and an agent file of the
+ * same name replaces the config entry wholesale. A leftover `plan.md` from
+ * the old layout would therefore pin `plan` to whatever model it named -
+ * a model that may since have been withdrawn - and the config would look
+ * correct while the lane ran somewhere else. The prompts moved to prompts/,
+ * where a file cannot shadow a config entry.
+ */
+function removeLegacyAgentFiles() {
+  const removed = []
+  for (const { dir } of agentDirs()) {
+    if (!existsSync(dir)) continue
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".md")) continue
+      const full = join(dir, name)
+      let ours = false
+      try {
+        ours = readlinkSync(full).includes(join("space-harness", "agents"))
+      } catch {
+        ours = false
+      }
+      if (!ours) continue
+      try {
+        rmSync(full, { force: true })
+        removed.push(name)
+      } catch {}
+    }
+  }
+  return removed
+}
+
 /**
  * Replace `link` with `link` plus the agents, skills and GLOBAL.md.
  *
@@ -238,6 +363,13 @@ async function cmdInstall() {
   // The plugin link first: without it the guard is not enforcing anything.
   cmdLink()
 
+  const legacy = removeLegacyAgentFiles()
+  if (legacy.length) {
+    console.log(
+      `  ${green("✓")} ${stamp(`removed ${legacy.length} legacy agent file(s) that would have shadowed the config`)}`,
+    )
+  }
+
   for (const { src, dest, kind } of installTargets()) {
     if (!existsSync(src)) {
       console.log(`  ${yellow("!")} ${stamp(`${kind} missing in repo: ${src}`)}`)
@@ -373,25 +505,36 @@ async function askChoice(question) {
 function linkOne(src, dest) {
   const parent = realpathSync(dirname(dest))
   const target = relative(parent, realpathSync(src))
-  let stale = false
+
+  let isLink = false
+  let ours = false
   try {
-    stale = readlinkSync(dest) !== target
+    isLink = lstatSync(dest).isSymbolicLink()
+    ours = isLink && readlinkSync(dest) === target
   } catch {
-    stale = true
+    // Nothing at `dest` yet.
   }
-  if (stale) {
-    try {
-      rmSync(dest, { force: true, recursive: false })
-    } catch {
-      // Nothing to remove, or it is a real directory we must not delete.
+  if (ours) return
+
+  if (existsSync(dest)) {
+    // Replace only what this installer put there. The old code treated "not
+    // already our link" as "safe to delete" and called `rmSync` with
+    // `recursive: false`, which succeeds on a plain file: a hand-written
+    // agent was deleted and replaced by a symlink without a word. A real
+    // directory is left alone too -- unlinking it is not this installer's
+    // call to make.
+    if (!isLink) {
+      const kind = lstatSync(dest).isDirectory() ? "directory" : "file"
+      console.log(`  ${yellow("!")} ${stamp(`left alone: ${dest} is a real ${kind} and was not ours to replace`)}`)
+      return
     }
+    rmSync(dest, { force: true })
   }
-  if (!existsSync(dest)) {
-    try {
-      symlinkSync(target, dest)
-    } catch (err) {
-      console.log(`  ${yellow("!")} ${stamp(`could not link ${dest}: ${err.message}`)}`)
-    }
+
+  try {
+    symlinkSync(target, dest)
+  } catch (err) {
+    console.log(`  ${yellow("!")} ${stamp(`could not link ${dest}: ${err.message}`)}`)
   }
 }
 
@@ -420,9 +563,7 @@ function cmdVerify() {
   //    hand-edit anywhere in the model/variant/permission surface shows up
   //    here, which is the check that would have caught `build` being moved onto
   //    a may-train model.
-  const actual = existsSync(CONFIG_FILE)
-    ? stripComments(readFileSync(CONFIG_FILE, "utf8"))
-    : null
+  const actual = existsSync(CONFIG_FILE) ? readConfigJson() : null
   if (!actual) {
     problems.push(`${CONFIG_FILE} does not exist. Run: oc-harness use ${p.id}`)
   } else {
@@ -452,53 +593,88 @@ function cmdVerify() {
     }
   }
 
-  // 3. Every role the profile tiers must have an installed agent file, or the
-  //    config entry configures a model and a permission but no behaviour.
-  const agentsDir = join(CONFIG_DIR, "agents")
+  // 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
+  //    permission but no prompt is a lane that runs on opencode's default
+  //    instructions and nobody can tell.
+  const promptsDir = join(CONFIG_DIR, "prompts")
   const roles = resolveRoles(p)
   for (const [role, level] of Object.entries(roles)) {
     if (level === undefined) continue
-    const file = join(agentsDir, `${role}.md`)
+    const file = join(promptsDir, `${role}.md`)
     if (!existsSync(file)) {
-      // build and plan are built-in agents: opencode reads their config entry
-      // even with no markdown file, but they then carry no custom prompt.
-      const builtin = role === "build" || role === "plan"
-      const msg = builtin
-        ? `no agents/${role}.md - ${role} is a built-in agent, so it runs with opencode's default prompt, not this kit's`
-        : `no agents/${role}.md - ${role} is declared in the config but does not exist as an agent. Run: oc-harness install`
-      problems.push(msg)
+      problems.push(
+        `no prompts/${role}.md - the ${role} lane is declared in the config but has no instructions. Run: oc-harness install`,
+      )
       continue
     }
-    const front = stripFrontmatter(readFileSync(file, "utf8"))
-    const wantModel = `${p.provider}/${p.model}`
-    const gotModel = front.model
-    if (gotModel && gotModel !== wantModel) {
-      problems.push(`agents/${role}.md names model ${gotModel}, profile says ${wantModel}`)
-    } else if (!gotModel) {
-      notes.push(`agents/${role}.md has no model: inherits the session model, so effort tiering may not apply`)
-    }
-    if (!gotModel && front.variant) {
-      problems.push(`agents/${role}.md sets variant "${front.variant}" without a model; variant only applies to the agent's own model`)
+    ok.push(`prompt ${role}.md installed`)
+    const ref = actual?.agent?.[role]?.prompt
+    if (ref) {
+      const target = ref.replace(/^\{file:/, "").replace(/\}$/, "")
+      const resolved = target.startsWith("~")
+        ? join(homedir(), target.slice(1))
+        : target
+      if (!existsSync(resolved)) {
+        problems.push(
+          `agent.${role}.prompt points at ${target}, which does not exist. Run: oc-harness install`,
+        )
+      }
     }
   }
 
-  // 4. No installed agent may name a model that is not the active one. A
-  //    stale name in a prompt is the documentation rot `space-finish` warns
-  //    about, and it also means the agent silently runs on another model.
-  if (existsSync(agentsDir)) {
-    for (const name of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-      const text = readFileSync(join(agentsDir, name), "utf8")
+  // 4. No installed agent file may shadow a lane. An agent file of the same
+  //    name replaces the config entry wholesale, and a file without a `model:`
+  //    line makes the agent inherit the caller's model. Either way the lane
+  //    stops running on the model the profile resolved for it, and the config
+  //    keeps looking correct. Verified against OpenCode 1.19.
+  //
+  //    The file's `model:` wins when the plugin is not there to re-pin it, and
+  //    its `prompt` and `description` win even when it is. So a shadow is
+  //    worth reporting wherever opencode would read one from.
+  for (const { dir, scope } of agentDirs()) {
+    if (!existsSync(dir)) continue
+    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 ?? {})) {
+        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")
       const named = text.match(/opencode\/([a-z0-9.\-]+)/i)
-      if (named && named[1] !== p.model) {
-        problems.push(`agents/${name} mentions opencode/${named[1]}, active profile is ${p.model}`)
+      if (named && !modelsInPlay(p).includes(named[1])) {
+        problems.push(
+          `agent file ${where}/${name} mentions opencode/${named[1]}, which is not in the active profile`,
+        )
       }
     }
   }
 
   // 5. The plugin link has to exist or none of the guard is running.
   const pluginLink = join(CONFIG_DIR, "plugins", "opencode-harness-kit.js")
-  if (existsSync(pluginLink)) ok.push("plugin linked")
-  else notes.push("no plugin link: the guard is not enforcing anything. Run: oc-harness link")
+  if (existsSync(pluginLink)) {
+    ok.push("plugin linked")
+    // The bundle finds its profiles by walking up from itself, so a bundle
+    // that was copied out of the kit's tree loads and does nothing: no guard,
+    // no pruning, no lane failover, no telemetry, and no error anywhere. The
+    // symlink is what keeps this honest, and this check is what notices when
+    // somebody replaced it with a copy.
+    let resolved = pluginLink
+    try {
+      resolved = realpathSync(pluginLink)
+    } catch {}
+    const dataRoot = join(dirname(resolved), "..")
+    if (!existsSync(join(dataRoot, "profiles"))) {
+      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`,
+      )
+    }
+  } else {
+    notes.push("no plugin link: the guard is not enforcing anything. Run: oc-harness link")
+  }
 
   // 6. Schema check. `variant` at the top level is silently stripped by
   //    OpenCode, so emitting it looks like tiering and does nothing.
@@ -512,15 +688,30 @@ function cmdVerify() {
   //    is missing or whose frontmatter is broken is skipped silently by
   //    OpenCode, so half the plan -> build -> review -> finish loop can go
   //    missing without any error surfacing.
+  //
+  //    The check covers the kit's OWN skills, and only the kit's own skills.
+  //    OpenCode identifies a skill by its DIRECTORY name, not by the `name:`
+  //    in its frontmatter, so a skill whose two differ loads perfectly well
+  //    under its directory name. A checker that insists they match fails a
+  //    perfectly good install over somebody else's naming choice - which is
+  //    what happened on an install that carried 220-odd community skills.
+  //
+  //    For the kit's own skills the two DO have to agree: the loop refers to
+  //    them by name, and a skill whose frontmatter drifted away from its
+  //    directory is one the loop will not find.
   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")
   } else {
+    const installed = new Set(readdirSync(skillsDir))
     let valid = 0
-    for (const name of readdirSync(skillsDir)) {
+    for (const name of ourSkills) {
       const skillFile = join(skillsDir, name, "SKILL.md")
       if (!existsSync(skillFile)) {
-        problems.push(`skills/${name} has no SKILL.md - it will never load. Run: oc-harness install`)
+        problems.push(
+          `skills/${name} has no SKILL.md - the ${name} step of the loop will never load. Run: oc-harness install`,
+        )
         continue
       }
       const front = stripFrontmatter(readFileSync(skillFile, "utf8"))
@@ -532,7 +723,19 @@ function cmdVerify() {
         valid += 1
       }
     }
-    if (valid) ok.push(`${valid} skill(s) valid`)
+    // A directory of the same name as one of the kit's would shadow it, and
+    // the installer refuses to replace a real directory - so the kit's skill
+    // would be missing and the loop would break at that step.
+    for (const name of installed) {
+      if (ourSkills.has(name)) continue
+      const foreign = join(skillsDir, name, "SKILL.md")
+      if (!existsSync(foreign)) {
+        problems.push(`skills/${name} has no SKILL.md - it will never load`)
+      }
+    }
+    const others = [...installed].filter((n) => !ourSkills.has(n)).length
+    if (valid) ok.push(`${valid} kit skill(s) valid`)
+    if (others) ok.push(`${others} other skill(s) present`)
   }
 
   console.log(`\n${bold("verify")}  ${stamp(`profile ${p.id} -> ${CONFIG_FILE}`)}\n`)
@@ -547,6 +750,21 @@ function cmdVerify() {
   console.log(`\n  ${green("install is consistent with the profile")}\n`)
 }
 
+/**
+ * The names of the skills this kit installs, read from the repo.
+ *
+ * These are the ones the loop refers to by name, so their frontmatter has to
+ * agree with their directory. Everything else in the skills directory belongs
+ * to whoever put it there.
+ *
+ * @returns {Set<string>}
+ */
+function kitSkillNames() {
+  const dir = join(ROOT, "skills")
+  if (!existsSync(dir)) return new Set()
+  return new Set(readdirSync(dir).filter((n) => existsSync(join(dir, n, "SKILL.md"))))
+}
+
 /** Minimal `key: value` reader for agent frontmatter. */
 function stripFrontmatter(text) {
   const block = /^---\n([\s\S]*?)\n---/.exec(text)
@@ -570,6 +788,7 @@ 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}`)
 
   for (const [role, level] of Object.entries(roles)) {
     if (level === undefined) continue
@@ -578,17 +797,22 @@ function configDrift(p, actual) {
       out.push(`agent.${role} missing`)
       continue
     }
-    // A role's expected model is the one roleModels declares for it, falling
-    // back to the base. Comparing every agent against `want` would report
-    // drift on every split role forever, which trains the user to ignore the
-    // one command that exists to catch a moved `build`.
-    const wantRole = `${p.provider}/${p.roleModels?.[role]?.model ?? p.model}`
+    // A lane's expected model is the one its chain resolved to, not the
+    // profile's base. A fleet puts ten different models behind ten agents, so
+    // comparing every lane against the base would report drift forever and
+    // train the user to ignore the one command that exists to catch a moved
+    // lane.
+    const resolved = resolveRoleModel(p, role)
+    const wantRole = `${p.provider}/${resolved ? resolved.model : p.model}`
     if (agent.model !== wantRole) {
       out.push(`agent.${role}.model ${agent.model} -> ${wantRole}`)
     }
     if (agent.variant !== (level ?? undefined)) {
       out.push(`agent.${role}.variant ${agent.variant ?? "(none)"} -> ${level ?? "(none)"}`)
     }
+    if (!agent.prompt) {
+      out.push(`agent.${role}.prompt missing - the lane would run without instructions`)
+    }
   }
 
   const wantReserved = reservedTokens(p)
@@ -610,20 +834,33 @@ function configDrift(p, actual) {
 async function cmdUse(id) {
   if (!id) fail("usage: oc-harness use <profile> [--print] [--yes]")
   const p = loadProfile(id)
-  const retention = loadRetention()[`${p.provider}/${p.model}`]
+
+  // A split profile puts the user behind every model in play, not just the base
+  // one. `p.retention` describes the base only, so gating on it let a profile
+  // whose plan/build/reviewer run on a may-train endpoint install silently.
+  // Every check below is over the whole set.
+  const eff = effectiveRetention(p)
+  const unrecorded = modelsInPlay(p).filter((m) => {
+    const entry = retentionFor(m)
+    return !entry || entry.retention === "unknown"
+  })
 
   // A profile may not become the default until a human has stated its
   // retention terms. Capability metadata cannot answer this question.
-  if (retention?.retention === "unknown" || (!retention && p.retention === "unknown")) {
+  if (unrecorded.length) {
     fail(
-      `retention for ${p.provider}/${p.model} is not recorded in retention.yml.\n` +
+      `retention for ${unrecorded.join(", ")} is not recorded in retention.yml.\n` +
         `Add an entry with retention: zero-retention | may-train before installing it.`,
     )
   }
-  if (p.retention === "may-train" && !has("--yes")) {
+  if (eff.retention === "may-train" && !has("--yes")) {
+    const trainOn = roleSplitModels(p)
+      .filter((s) => retentionFor(s.model)?.retention === "may-train")
+      .map((s) => `${s.role} runs on ${s.model}`)
     const msg =
-      `${yellow("!")} ${p.provider}/${p.model} may train on your prompts and completions.\n` +
-      `  ${retention?.note ?? ""}\n` +
+      `${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")
@@ -631,10 +868,7 @@ async function cmdUse(id) {
     console.error(msg)
   }
 
-  let base = {}
-  if (existsSync(CONFIG_FILE)) {
-    base = stripComments(readFileSync(CONFIG_FILE, "utf8"))
-  }
+  const base = readConfigJson()
 
   const out = generateConfig(p, { base, comments: true })
   if (has("--print")) {
@@ -652,10 +886,12 @@ async function cmdUse(id) {
   }
 
   mkdirSync(dirname(CONFIG_FILE), { recursive: true })
-  if (existsSync(CONFIG_FILE) && !has("--yes")) {
-    // The config is the user's file once written. A backup is made either
-    // way, but overwriting it without asking is how a hand-tuned setup dies.
-    if (interactive() && !(await confirm(`overwrite ${CONFIG_FILE}? (a .bak backup is kept)`))) {
+  if (existsSync(CONFIG_FILE)) {
+// The config is the user's file once written. The backup is unconditional:
+    // `--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)`))) {
       fail("left the existing config alone")
     }
     writeFileSync(`${CONFIG_FILE}.bak`, readFileSync(CONFIG_FILE))
@@ -673,11 +909,12 @@ function summary(p) {
   const splits = roleSplitModels(p)
   console.log(`  ${stamp(`model      ${p.provider}/${p.model}`)}`)
   console.log(`  ${stamp(`effort     ${resolveDefaultVariant(p) ?? "(not tunable)"}`)}`)
-  console.log(`  ${stamp(`roles      ${Object.entries(resolveRoles(p)).map(([k, v]) => `${k}=${v ?? "-"}`).join(" ")}`)}`)
+  console.log(`  ${stamp(`lanes      ${Object.entries(resolveRoles(p)).map(([k, v]) => `${k}=${v ?? "-"}`).join(" ")}`)}`)
   if (splits.length) {
-    // Without this the split is invisible until someone opens the file, which
-    // is too late to be told which roles send prompts to a provider that trains.
-    console.log(`  ${stamp(`split      ${splits.map((s) => `${s.role}=${s.model}`).join(" ")}`)}`)
+    // Without this the fleet is invisible until someone opens the file, which
+    // is too late to be told which lane sends prompts to a provider that
+    // trains on them.
+    console.log(`  ${stamp(`lane model ${splits.map((s) => `${s.role}=${s.model}`).join(" ")}`)}`)
     console.log(`  ${stamp(`           ${splits.map((s) => s.limits ? `${s.role} out ${s.limits.output.toLocaleString("en-US")}` : null).filter(Boolean).join("  ")}`)}`)
   }
   console.log(`  ${stamp(`retention  ${eff.retention}${eff.retention === "may-train" ? "  <-- prompts may train a model" : ""}`)}`)
@@ -687,16 +924,24 @@ function summary(p) {
   console.log(`  ${stamp(`reserved   ${reservedTokens(p).toLocaleString("en-US")} tokens`)}`)
 }
 
-/** opencode.jsonc is JSONC, so strip comments before parsing. */
-function stripComments(text) {
-  const without = text
-    .replace(/^\s*\/\/.*$/gm, "")
-    .replace(/\/\*[\s\S]*?\*\//g, "")
-  try {
-    return JSON.parse(without)
-  } catch {
-    return {}
+/**
+ * Read the installed config as JSONC.
+ *
+ * Strict on purpose. Returning `{}` for a config we could not parse made
+ * `oc-harness use` merge onto an empty base and write the user's own settings
+ * back out deleted, with no message. Refusing is the only safe answer here.
+ */
+function readConfigJson() {
+  if (!existsSync(CONFIG_FILE)) return {}
+  const parsed = parseJsonc(readFileSync(CONFIG_FILE, "utf8"))
+  if (!parsed) {
+    fail(
+      `${CONFIG_FILE} is not valid JSONC and was left untouched.\n` +
+        `  Refusing to regenerate: the existing settings cannot be read, so merging\n` +
+        `  onto them would silently drop them. Fix the file by hand, then re-run.`,
+    )
   }
+  return parsed
 }
 
 /** Re-fetch models.dev and report which profiles have drifted from it. */
@@ -801,6 +1046,20 @@ async function cmdRefresh(id) {
   )
 }
 
+/**
+ * The model chain of every lane a profile enables, keyed by lane.
+ * @param {ReturnType<typeof loadProfile>} p
+ * @returns {Record<string, string[]>}
+ */
+function chainOf(p) {
+  /** @type {Record<string, string[]>} */
+  const out = {}
+  for (const lane of Object.keys(p.roles ?? {})) {
+    out[lane] = resolveLaneChain(p, lane)
+  }
+  return out
+}
+
 /** Re-check every profile against the live provider catalog. */
 async function cmdDoctor() {
   const catalog = await fetchCatalog()
@@ -832,13 +1091,29 @@ async function cmdDoctor() {
       issues.push(red("retention.yml now says may-train"))
     }
 
+    // A fleet's lanes point at other models, and those are the routes that
+    // get withdrawn. A lane whose whole chain has left the catalog is a lane
+    // with no model at all, which no amount of `refresh` on the base profile
+    // would reveal.
+    for (const [lane, chain] of Object.entries(chainOf(p))) {
+      const alive = chain.filter((rung) => catalog?.[p.provider]?.models?.[rung])
+      if (!alive.length) {
+        issues.push(red(`lane ${lane}: every model in its chain has left the catalog`))
+      } else if (alive.length < chain.length) {
+        const gone = chain.filter((rung) => !alive.includes(rung))
+        issues.push(
+          yellow(`lane ${lane}: ${gone.join(", ")} withdrawn, falls back to ${alive[0]}`),
+        )
+      }
+    }
+
     if (issues.length === 0) {
       console.log(`  ${green("✓")} ${id.padEnd(32)} ${stamp("matches catalog")}`)
     } else {
       problems++
       console.log(`  ${yellow("!")} ${id.padEnd(32)} ${yellow("drift")}`)
       for (const i of issues) console.log(`      ${i}`)
-      console.log(`      ${stamp(`fix: oc-harness use ${id} --refresh`)}`)
+      console.log(`      ${stamp(`fix: oc-harness refresh ${id}`)}`)
     }
   }
   console.log(
@@ -858,7 +1133,7 @@ async function cmdDoctor() {
     console.log(`  ${yellow("!")} ${stamp("no profile recorded in the config. Run: oc-harness use <profile>")}\n`)
     return
   }
-  const installed = existsSync(CONFIG_FILE) ? stripComments(readFileSync(CONFIG_FILE, "utf8")) : null
+  const installed = existsSync(CONFIG_FILE) ? readConfigJson() : null
   if (!installed) {
     console.log(`  ${yellow("!")} ${stamp(`${CONFIG_FILE} missing. Run: oc-harness use ${activeId}`)}\n`)
     return
@@ -874,6 +1149,93 @@ async function cmdDoctor() {
   }
 }
 
+/**
+ * Which lanes the fleet actually used.
+ *
+ * A fleet is a hypothesis, not a fact: ten lanes is a guess about which jobs
+ * need a different model. The only way to know which of them earn their place
+ * is to count the calls. A lane that was never called is a description the
+ * model reads on every turn and a free model doing nothing, so it is the first
+ * thing to cut.
+ */
+function cmdLanes() {
+  const activeId = profileIdFromConfig() ?? index().default
+  let profile = null
+  try {
+    profile = loadProfile(activeId)
+  } catch (err) {
+    fail(`active profile "${activeId}" cannot be loaded: ${err.message}`)
+  }
+
+  // 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`)
+  const lanes = Object.keys(profile.roles ?? {})
+  if (!lanes.length) {
+    console.log(`  ${stamp("this profile enables no lanes")}\n`)
+    return
+  }
+  const head = [
+    "  " + "lane".padEnd(12),
+    "reqs".padStart(7),
+    "avg ms".padStart(9),
+    "model".padEnd(32),
+  ].join("  ")
+  console.log(head)
+  console.log("  " + "-".repeat(64))
+
+  let unused = 0
+  for (const lane of lanes) {
+    const s = stats[lane]
+    const model = resolveLaneModel(profile, lane).model
+    if (!s) {
+      unused++
+      console.log(
+        [
+          "  " + lane.padEnd(12),
+          String(0).padStart(7),
+          "-".padStart(9),
+          (model ?? "-").padEnd(32),
+        ].join("  ") + yellow("  never used"),
+      )
+      continue
+    }
+    const avg = averageMs(s.ms)
+    console.log(
+      [
+        "  " + lane.padEnd(12),
+        String(s.requests).padStart(7),
+        String(avg ?? "-").padStart(9),
+        ([...s.models].join(", ") || model || "-").padEnd(32),
+      ].join("  "),
+    )
+  }
+
+  console.log("")
+  if (unused) {
+    console.log(
+      `  ${yellow(`${unused} lane(s) were never used`)} ${stamp("cut candidates, not defects")}`,
+    )
+  } else {
+    console.log(`  ${green("every lane was used at least once")}`)
+  }
+  console.log(
+    `  ${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`,
+  )
+  if (ignored) {
+    console.log(
+      `  ${yellow(`${ignored} record(s) had no message id and were not counted`)} ${stamp("written by a kit version before the counter was fixed")}\n`,
+    )
+  }
+}
+
 /**
  * Report agents in a project that the kit's effort tiering does not cover.
  *
@@ -886,13 +1248,16 @@ function cmdAgents() {
   // The global dir is where `oc-harness install` puts the kit's own agents, so
   // scanning only the project reported "no project agents found" forever and hid
   // the fact that none of them were installed at all.
-  const dirs = [
-    join(CONFIG_DIR, "agents"),
-    join(process.cwd(), ".opencode", "agents"),
-    join(process.cwd(), ".opencode", "agent"),
-  ]
-  const files = dirs.flatMap((d) =>
-    existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".md")).map((f) => join(d, f)) : [],
+  //
+  // opencode reads `agent/` and `agents/` alike, in the config dir and in
+  // `.opencode/`, so all four are scanned. A file in the singular directory
+  // shadows a lane exactly as one in the plural one does.
+  const files = agentDirs().flatMap(({ dir }) =>
+    existsSync(dir)
+      ? readdirSync(dir)
+          .filter((f) => f.endsWith(".md"))
+          .map((f) => join(dir, f))
+      : [],
   )
 
   // Never hardcode a profile here: the whole point is to check the one that is
@@ -908,49 +1273,75 @@ function cmdAgents() {
     fail("no profile is installed. Run: oc-harness use <profile>")
   }
 
-  const config = existsSync(CONFIG_FILE) ? stripComments(readFileSync(CONFIG_FILE, "utf8")) : {}
-  const configured = config.model ?? "(none)"
+  const config = readConfigJson()
   const wantModel = `${current.provider}/${current.model}`
 
   console.log(`\n${bold("agents")}  ${stamp(`tiering against ${current.id}`)}\n`)
-  if (!files.length) {
-    console.log(`  ${red("✗")} ${yellow("no agent markdown found")}`)
-    console.log(`      ${stamp(`looked in ${dirs.join("\n      ")}`)}`)
-    console.log(`      ${stamp("run: oc-harness install")}\n`)
-    return
-  }
 
+  // The kit's own lanes live in the config, not in markdown: an agent file of
+  // the same name replaces the config entry, and a file without a `model:`
+  // line makes the agent inherit the caller's model.
   const roles = resolveRoles(current)
+  const lanes = Object.keys(config.agent ?? {})
+  if (!lanes.length) {
+    console.log(`  ${red("✗")} ${yellow("the config declares no agents")}`)
+    console.log(`      ${stamp("run: oc-harness use <profile>")}\n`)
+    return
+  }
   let untiered = 0
-  let stale = 0
-  for (const file of files) {
-    const text = readFileSync(file, "utf8")
-    const name = file.split("/").pop().replace(/\.md$/, "")
-    const front = stripFrontmatter(text)
-    const hasModel = Boolean(front.model)
-    const hasVariant = Boolean(front.variant)
-    const isKitRole = name in roles
-
+  for (const lane of lanes) {
+    const a = config.agent[lane] ?? {}
     const notes = []
-    if (!hasModel) notes.push("no model of its own, inherits the session model")
-    if (front.model && front.model !== wantModel) {
-      notes.push(`model ${front.model} is not the active ${wantModel}`)
+    if (!a.model) notes.push("no model of its own, inherits the session model")
+    else if (a.model !== wantModel && !modelsInPlay(current).some((m) => `${current.provider}/${m}` === a.model)) {
+      notes.push(`model ${a.model} is not in the active profile`)
+    }
+    if (a.model && !a.variant) {
+      notes.push("no variant, runs at the model default")
     }
-    if (hasModel && !hasVariant) notes.push("no variant, runs at the model default")
+    if (!a.prompt) notes.push("no prompt, runs on opencode's default instructions")
+    else {
+      const target = String(a.prompt).replace(/^\{file:/, "").replace(/\}$/, "")
+      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")
 
     if (!notes.length) {
-      console.log(`  ${green("✓")} ${name.padEnd(14)} ${stamp(`tiered${isKitRole ? ` ${roles[name]}` : ""}`)}`)
+      console.log(
+        `  ${green("✓")} ${lane.padEnd(14)} ${stamp(`${a.model ?? "-"}${a.variant ? ` ${a.variant}` : ""}`)}`,
+      )
       continue
     }
-    untiered += !hasVariant || !hasModel ? 1 : 0
-    stale += front.model && front.model !== wantModel ? 1 : 0
-    console.log(`  ${yellow("!")} ${name.padEnd(14)} ${yellow("not tiered")}`)
+    untiered++
+    console.log(`  ${yellow("!")} ${lane.padEnd(14)} ${yellow("not tiered")}`)
     for (const nn of notes) console.log(`      ${nn}`)
   }
 
+  // A project agent declared in .opencode/agents/ with no model of its own
+  // inherits the global model and runs at the global effort, which is usually
+  // 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")
+    const name = file.split("/").pop().replace(/\.md$/, "")
+    const front = stripFrontmatter(text)
+    if (name in config.agent) {
+      console.log(
+        `  ${yellow("!")} ${name.padEnd(14)} ${yellow("shadows a lane in the config")}`,
+      )
+      console.log(`      ${stamp("an agent file replaces the config entry, so the lane loses its model")}`)
+      continue
+    }
+    if (!front.model) {
+      untiered++
+      console.log(`  ${yellow("!")} ${name.padEnd(14)} ${yellow("not tiered")}`)
+      console.log(`      ${stamp("no model of its own, inherits the session model")}`)
+    }
+  }
+
   console.log(
-    `\n  ${untiered ? yellow(`${untiered} agent(s) run at the session effort`) : green("all agents tiered")}` +
-      `${stale ? `, ${stale} pinned to a model that is not active` : ""}`,
+    `\n  ${untiered ? yellow(`${untiered} agent(s) run at the session effort`) : green("all agents tiered")}`,
   )
   console.log(`  ${stamp("add `model:` and `variant:` to the agent frontmatter, or map them in the profile")}\n`)
 }
@@ -960,6 +1351,32 @@ function fail(msg) {
   process.exit(1)
 }
 
+/**
+ * Drive the task file to done without a human at the keyboard.
+ *
+ * Every stop condition is printed, and the exit code says which kind of stop it
+ * was: 0 finished, 1 nothing to plan, 2 needs a person, 3 the agent died,
+ * 4 verify failed. A caller can therefore tell "done" from "gave up" without
+ * reading the transcript.
+ */
+async function cmdRun() {
+  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),
+  })
+
+  const s = result.summary
+  console.log(`\n  ${bold(result.code === 0 ? "done" : "stopped")} ${result.reason}`)
+  if (s) {
+    console.log(`  ${stamp(`${s.done} done, ${s.blocked} blocked, ${s.pending} pending`)}`)
+  }
+  if (result.code !== 0) process.exitCode = result.code
+}
+
 try {
   switch (cmd) {
     case "list":
@@ -989,12 +1406,18 @@ try {
     case "agents":
       cmdAgents()
       break
+    case "lanes":
+      cmdLanes()
+      break
     case "doctor":
       await cmdDoctor()
       break
     case "baseline":
       await import("./baseline.mjs")
       break
+    case "run":
+      await cmdRun()
+      break
     case "help":
     default:
       console.log(`
@@ -1003,21 +1426,34 @@ try {
     list      show profiles with retention and caveats
     init      pick a free profile, then install + use + verify in one go
     use <id>  compile a profile into ${CONFIG_FILE}
-    show <id> print the resolved effort plan and derived numbers
+    show <id> print the resolved lane plan and derived numbers
     refresh <id>  update capability fields from models.dev
-    install   symlink the plugin, agents, skills and GLOBAL.md into the config dir
+    install   symlink the plugin, prompts, skills and GLOBAL.md into the config dir
     verify    check the install still matches the profile and its rules are loaded
     link          symlink the built plugin into ~/.config/opencode/plugins
     agents        report agents the effort tiering does not reach
+    lanes         report which lanes the fleet actually used
     doctor    re-check profiles against models.dev and the installed config
     baseline  measure the current opencode install
+    run       drive .space/tasks.md to done with the build agent
 
   options
     --print        write the config to stdout instead of disk
     --yes          accept a retention warning, back up the old config
     --retention    filter list by retention class
     --free         list free profiles only
+
+  run options
+    --role <agent>  which agent does the work (default: build)
+    --max-rounds N  stop after N tasks (default: 20)
+    --budget MIN    stop after MIN minutes (default: 120)
 `)
+    // An unknown command is a typo, not a request for help. Without this
+    // `oc-harness tsl` prints help and exits 0, so a script calling it never
+    // finds out that nothing ran.
+    if (cmd !== "help" && cmd !== "--help" && cmd !== "-h") {
+      fail(`unknown command: ${cmd}\n  run 'oc-harness help' for the list`)
+    }
   }
 } catch (err) {
   if (err instanceof ProfileError) fail(err.message)