opencode-harness-kit 0.5.4 → 0.5.6

package/src/config.js

@@ -158,6 +158,11 @@ export function utilityModel(p) {
  * `instructions` array used to replace it wholesale, which unloaded the
  * whole behavioural layer while everything still looked correct.
  *
+ * A SINGLE string is a list of one. The parameter has always been typed
+ * `string[] | string | undefined`, but a string was dropped on the floor:
+ * the file that came back named only the kit's GLOBAL.md, so the user's own
+ * instructions were unloaded without a word.
+ *
  * The user's own files keep their order and come first; the kit's is
  * appended. Duplicates are dropped, so re-running `use` does not grow the
  * list.
@@ -167,7 +172,12 @@ export function utilityModel(p) {
  * @returns {string[]}
  */
 export function mergeInstructions(base, kitPath) {
-  const list = Array.isArray(base) ? base.filter((x) => typeof x === "string") : []
+  const given = Array.isArray(base)
+    ? base
+    : typeof base === "string"
+      ? [base]
+      : []
+  const list = given.filter((x) => typeof x === "string")
   /** @type {string[]} */
   const out = []
   for (const entry of [...list, kitPath]) {
@@ -235,6 +245,75 @@ export const BASH_ALLOWLIST = [
  */
 export { BASH_DENYLIST } from "./denylist.js"
 
+/**
+ * The user's own bash rules, as a map the kit can merge into its own.
+ *
+ * The value has to be one of the three verbs opencode's schema defines. A
+ * rule the kit cannot express cannot work anyway, and writing it out
+ * unchanged would make the whole config invalid - which is a worse outcome
+ * than a rule the kit drops.
+ *
+ * A rule the kit drops is NOT dropped silently: the pattern and the verb it
+ * carried are returned in `dropped`, and the header of the generated file
+ * names them. The rule was the user's, and a file that comes back looking
+ * exactly as it did before is how a lost rule stays lost.
+ *
+ * `permission.bash` may also be a SINGLE verb, and a single verb is the
+ * blanket rule - every command that no other rule names. It used to be
+ * dropped on the floor with the rest of the non-object values, so a user
+ * who had `bash: "allow"` lost the blanket allow and got the kit's map
+ * instead.
+ *
+ * @param {any} base the config as it is on disk
+ * @returns {{ rules: Record<string, string>, dropped: string[] }}
+ */
+function userBashRules(base) {
+  const own = base?.permission?.bash
+  /** @type {Record<string, string>} */
+  const rules = {}
+  /** @type {string[]} */
+  const dropped = []
+
+  /**
+   * Keep a rule the kit can write, or name the one it cannot.
+   *
+   * @param {string} pattern
+   * @param {any} verb
+   */
+  const keep = (pattern, verb) => {
+    if (verb === "allow" || verb === "ask" || verb === "deny") {
+      rules[pattern] = verb
+      return
+    }
+    const said = typeof verb === "string" ? JSON.stringify(verb) : String(verb)
+    dropped.push(`permission.bash "${pattern}" -> ${said}`)
+  }
+
+  if (own === undefined || own === null) return { rules, dropped }
+
+  if (typeof own === "string") {
+    keep("*", own)
+    return { rules, dropped }
+  }
+
+  // Anything else that is not a map of rules cannot be merged, and it is
+  // named so the loss is not silent either.
+  if (typeof own !== "object" || Array.isArray(own)) {
+    dropped.push(
+      `permission.bash is ${Array.isArray(own) ? "a list" : String(own)}, which is not a rule the kit can write`,
+    )
+    return { rules, dropped }
+  }
+  for (const [pattern, verb] of Object.entries(own)) {
+    if (typeof pattern !== "string" || !pattern) {
+      dropped.push(`permission.bash has a rule with no pattern, which was dropped`)
+      continue
+    }
+    keep(pattern, verb)
+  }
+  return { rules, dropped }
+}
+
 /**
  * @param {Profile} p
  * @param {{ base?: Record<string, any>, comments?: boolean, unhealthy?: Set<string> }} [opts]
@@ -294,9 +373,34 @@ export function generateConfig(p, opts = {}) {
     agent[role] = existing
   }
 
+  // The user's own bash rules are merged in, not replaced.
+  //
+  // The map used to be built from the kit's two lists alone, so every rule
+  // the user had written was deleted on the next `oc-harness use` - and the
+  // file that came back looked exactly as it had before, so nothing said
+  // it. The rules that let somebody run their own tools without a prompt
+  // were the ones that vanished.
+  //
+  // The order is the precedence ladder, and it is the kit's denylist that
+  // closes it:
+  //
+  //   kit allowlist -> the user's rules -> kit denylist
+  //
+  // The denylist is last because a deny a user rule could re-allow would
+  // not be a deny, and the denylist is the mechanical half of the safety
+  // policy. The user's rules sit after the allowlist so a rule of their own
+  // is not shadowed by one of the kit's.
+  //
+  // The kit's own catch-all stays the FIRST key, so a user rule for `*`
+  // replaces its value and not its position: the catch-all remains the
+  // fallback for the commands no other rule mentions, and the allowlist
+  // still decides the ones it names. opencode takes the last matching rule,
+  // so this order is the whole rule.
+  const own = userBashRules(base)
   const bashRules = {
     "*": "ask",
     ...Object.fromEntries(BASH_ALLOWLIST.map((rule) => [rule, "allow"])),
+    ...own.rules,
     ...Object.fromEntries(BASH_DENYLIST.map((rule) => [rule, "deny"])),
   }
 
@@ -423,13 +527,19 @@ export function generateConfig(p, opts = {}) {
     },
   }
 
-  return render(out, p, { comments: opts.comments ?? true, instructionsPath, unhealthy })
+  return render(out, p, {
+    comments: opts.comments ?? true,
+    instructionsPath,
+    unhealthy,
+    dropped: own.dropped,
+  })
 }
 
 /**
  * @param {Record<string, any>} cfg
  * @param {Profile} p
- * @param {{ comments: boolean, instructionsPath?: string, unhealthy?: Set<string> }} opts
+ * @param {{ comments: boolean, instructionsPath?: string, unhealthy?: Set<string>,
+ *          dropped?: string[] }} opts
  * @returns {string}
  */
 function render(cfg, p, opts) {
@@ -481,6 +591,19 @@ function render(cfg, p, opts) {
           `${c}ceiling      ${p.maxRetention} - a lane may only resolve to a model at or below this`,
         ]
       : []),
+    // The rules the kit could not carry over. They are named HERE, in the
+    // file the user reads, because a rule that is dropped without a word is
+    // a rule that is lost for good: the file comes back looking exactly as
+    // it did before, and the prompt it used to allow is back.
+    ...(opts.dropped?.length
+      ? [
+          `${c}`,
+          `${c}Dropped from your own permission.bash rules, and NOT in the file below.`,
+          `${c}The verb has to be one of allow, ask or deny - a rule the kit cannot`,
+          `${c}write would fail the schema for the whole file:`,
+          ...opts.dropped.map((d) => `${c}  ${d}`),
+        ]
+      : []),
     `${c}`,
     `${c}Derived numbers, do not hand-edit:`,
     `${c}  compaction.reserved  ${reservedTokens(p, { unhealthy }).toLocaleString("en-US")}  (${Math.round((p.effort?.reserveShare ?? 0.12) * 100)}% of the narrowest input cap in play, held back for reasoning growth)`,

package/src/denylist.js

@@ -19,10 +19,49 @@ export const BASH_DENYLIST = [
   // so opencode prompts for human approval before publishing.
   "rm -rf *",
   "rm -fr *",
+  // The short forms of the same flags, one at a time.
+  //
+  // The guard's rule is a TOKEN scanner: it blocks an rm whose short flag
+  // cluster contains r or f in any case, and an rm whose long flag is
+  // --recursive or --force. So `rm -f file` and `rm -r dir` are blocked
+  // there - and the permission map has to deny what the guard blocks, or
+  // the two layers contradict each other: the map would ask about a
+  // command the guard refuses.
+  //
+  // `-R` is named too because the guard's rule is case-insensitive and
+  // GNU rm reads `-R` as `--recursive`.
+  //
+  // The two layers are not the same matcher. The guard reads the tokens
+  // and can see a destructive flag in any position; this list is a flat
+  // glob over the command, so it can only name the spellings.
+  //
+  // A cluster a glob cannot express (`-rfv`) is caught by the guard and
+  // asked about by the config - the config asks about everything it does
+  // not name, and asking is the safe direction.
+  //
+  // A PERMUTED delete (`rm /tmp/x -rf`) is caught by the GUARD, which reads
+  // the tokens and does not care which order they come in. The glob cannot
+  // name it - a glob here could only name one spelling of it, and the
+  // spelling would still be the one it missed. So the config asks about it,
+  // and a human decides, and the code-level block is the guard's.
+  "rm -f *",
+  "rm -r *",
+  "rm -R *",
+  // The long GNU names of the same two flags. A delete that is spelled
+  // `--recursive --force` is the delete the short forms name.
+  "rm --recursive *",
+  "rm --force *",
   "curl * | sh",
   "curl * | bash",
+  // The same pipe into a shell that is named by its path. The shell is the
+  // same shell either way, and the config can only match what it can see.
+  "curl * | */sh",
+  "curl * | */bash",
   "chmod 777 *",
   "chmod 777*",
+  // The same mode written with a leading zero.
+  "chmod 0777 *",
+  "chmod 0777*",
   "gh pr create*",
   "gh pr merge*",
   "gh pr close*",
@@ -52,6 +91,10 @@ export const BASH_DENYLIST = [
  *
  * `*` matches any run of characters, including none.
  *
+ * Every other metacharacter is literal. `?` is a regex quantifier, so an
+ * unescaped one made the character before it optional and the pattern
+ * matched a command it never named.
+ *
  * @param {string} command
  * @param {string} pattern
  * @returns {boolean}
@@ -59,7 +102,7 @@ export const BASH_DENYLIST = [
 export function matchesPattern(command, pattern) {
   const re = new RegExp(
     "^" +
-      pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[\\s\\S]*") +
+      pattern.replace(/[.+^${}()|[\]\\?]/g, "\\$&").replace(/\*/g, "[\\s\\S]*") +
       "$",
   )
   return re.test(command)
@@ -78,7 +121,7 @@ export function matchesPattern(command, pattern) {
  * same list and one of them reads it more carefully; that is the price of
  * having the list in two places.
  *
- * The two PIPE patterns are for the config's side only. `segments()` splits
+ * The PIPE patterns are for the config's side only. `segments()` splits
  * on `|`, so a segment never contains " | sh" and the guard catches a piped
  * script through its own rule instead.
  *

package/src/guard.ts

@@ -31,12 +31,50 @@ export const MARKER = "[opencode-harness-kit] blocked"
  */
 const WRITE_TOOLS = new Set(["write", "edit", "apply_patch", "patch"])
 
+/**
+ * Whether a hunk header follows, before another file's headers do.
+ *
+ * A `---`/`+++` pair is the header pair of a file only when a hunk header
+ * (`@@`) comes after it. That is the difference between the headers of a
+ * diff and two body lines that happen to look like one, and it is the same
+ * thing a reader of the diff does.
+ *
+ * @param {string[]} lines
+ * @param {number} from the line to start looking at
+ * @returns {boolean}
+ */
+function hunkFollows(lines: string[], from: number): boolean {
+  for (let i = from; i < lines.length; i++) {
+    if (/^@@/.test(lines[i])) return true
+    // Another pair of headers starts here, so this pair was not followed by
+    // a hunk of its own.
+    if (/^(?:---|\+\+\+)\s/.test(lines[i])) return false
+  }
+  return false
+}
+
 /**
  * The files a patch touches.
  *
  * `apply_patch` sends a patch, not a path, so the paths have to be read out
  * of it. Two formats are in use: opencode's own `*** Update File: path`
- * markers, and a plain unified diff with `+++ b/path` headers.
+ * markers, and a plain unified diff with `--- a/path` and `+++ b/path`
+ * headers.
+ *
+ * A unified diff names the file TWICE: `--- a/path` is where the change
+ * comes FROM, `+++ b/path` is where it goes TO. A deletion is `--- a/path`
+ * and `+++ /dev/null`, so the path that has to be scope-checked is the one
+ * in the `---` header and nowhere else. Reading only the `+++` header meant
+ * a patch that deleted a file outside the project was checked against
+ * nothing at all - and a patch that deletes a file is exactly the shape
+ * that reaches outside the project.
+ *
+ * The headers of a diff come BEFORE its first hunk, and a body line can
+ * look like a header: a removed line whose content is "-- foo" renders as
+ * "--- foo", and an added line "++ bar" renders as "+++ bar". Reading
+ * those as the headers of a file collected two words as paths, and a path
+ * that is not a path is a write the guard refuses for a reason nobody can
+ * find.
  *
  * @param {string} text
  * @returns {string[]}
@@ -44,16 +82,49 @@ const WRITE_TOOLS = new Set(["write", "edit", "apply_patch", "patch"])
 export function pathsInPatch(text: string): string[] {
   const out: string[] = []
   const push = (p: string) => {
-    const v = p.trim()
+    // A unified diff header can end in a timestamp: `--- a/file\t2026-01-01`.
+    const v = p.split("\t")[0].trim()
     if (!v) return
     if (v === "/dev/null") return
     if (!out.includes(v)) out.push(v)
   }
-  for (const m of text.matchAll(/^\*\*\*\s+(?:Add|Update|Delete)\s+File:\s*(.+)$/gm)) {
-    push(m[1])
-  }
-  for (const m of text.matchAll(/^\+\+\+\s+(?:b\/)?(.+)$/gm)) {
-    push(m[1])
+  const lines = text.split("\n")
+  // Whether a hunk header has been seen. After one, a `+++` line is added
+  // content and not the header of another file.
+  let seenHunk = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const marker = /^\*\*\*\s+(?:Add|Update|Delete)\s+File:\s*(.+)$/.exec(line)
+    if (marker) {
+      push(marker[1])
+      continue
+    }
+    if (/^@@/.test(line)) {
+      seenHunk = true
+      continue
+    }
+    // The `---` and `+++` headers of a unified diff are one pair: the
+    // first names where the change comes FROM, the second where it goes
+    // TO. They are read together so a body line that looks like a header
+    // is not mistaken for one.
+    const minus = /^---\s+(?:a\/)?(.+)$/.exec(line)
+    const next = i + 1 < lines.length ? /^\+\+\+\s+(?:b\/)?(.+)$/.exec(lines[i + 1]) : null
+    if (minus && next) {
+      // A pair is a header pair only when a hunk header follows it.
+      if (hunkFollows(lines, i + 2)) {
+        push(minus[1])
+        push(next[1])
+      }
+      // The `+++` line is consumed either way: it is the other half of the
+      // pair, and not a header of its own.
+      i++
+      continue
+    }
+    // A diff that carries only the `+++` header still names its file. It
+    // only names one while no hunk has been seen - after a hunk, a `+++`
+    // line is added content.
+    const plus = /^\+\+\+\s+(?:b\/)?(.+)$/.exec(line)
+    if (plus && !seenHunk) push(plus[1])
   }
   return out
 }

package/src/health.js

@@ -15,12 +15,96 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
+/**
+ * @typedef {object} SpentEntry
+ * @property {string} at when the route was recorded as spent
+ * @property {string} reason the pattern that matched
+ */
+
 /**
  * @typedef {object} Health
- * @property {Record<string, { at: string, reason: string }>} unhealthy
+ * @property {Record<string, SpentEntry>} unhealthy
  * @property {string} [active]
  */
 
+/**
+ * How long a recorded spent route is honoured for, by default.
+ *
+ * The provider's free window resets at 00:00 UTC, so a route recorded as
+ * spent is expected to come back within a day. Without an expiry the file is
+ * a one-way ratchet: a fleet that hit one rate limit never uses that model
+ * again, its lanes drain onto the last rung of their chains, and the only
+ * way back is a human editing a JSON file by hand.
+ *
+ * 24h is the default because the provider's window is a day. The window
+ * belongs to the provider rather than to the kit, so it is configurable:
+ * HARNESS_SPENT_WINDOW_HOURS overrides it.
+ */
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000
+
+/**
+ * The window, in milliseconds, a recorded spent route is honoured for.
+ *
+ * Read at call time rather than at import time, so a caller that changes it
+ * does not have to reload the module to see the effect.
+ *
+ * @returns {number}
+ */
+export function spentWindowMs() {
+  const raw = process.env.HARNESS_SPENT_WINDOW_HOURS
+  if (!raw) return DEFAULT_WINDOW_MS
+  const hours = Number(raw)
+  // A window of zero would expire every route the moment it was written, and
+  // a negative one would expire routes that were never spent. Neither is a
+  // setting anybody meant, so the default stands.
+  if (!Number.isFinite(hours) || hours <= 0) return DEFAULT_WINDOW_MS
+  return hours * 60 * 60 * 1000
+}
+
+/**
+ * Whether a recorded route is still spent.
+ *
+ * An entry with no usable timestamp is KEPT. The router always stamps one,
+ * so an entry without one was written by a hand, and honouring a standing
+ * statement is safer than putting a route that may be dead back into a
+ * fleet. An entry that cannot be shown to be stale is not dropped.
+ *
+ * @param {unknown} entry
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function isSpent(entry, now = Date.now()) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false
+  const at = /** @type {any} */ (entry).at
+  if (typeof at !== "string") return true
+  const when = Date.parse(at)
+  if (Number.isNaN(when)) return true
+  return now - when <= spentWindowMs()
+}
+
+/**
+ * The spent routes that are still spent.
+ *
+ * Every reader of the file goes through here, so the router and the effort
+ * hook cannot disagree about which routes are down. A reader that looked at
+ * the raw file would see a route that came back an hour ago as spent, and
+ * would fail the fleet over onto a model that works.
+ *
+ * @param {Health} health
+ * @param {number} [now]
+ * @returns {Record<string, SpentEntry>}
+ */
+export function liveUnhealthy(health, now = Date.now()) {
+  /** @type {Record<string, SpentEntry>} */
+  const out = {}
+  const source = health?.unhealthy
+  if (!source || typeof source !== "object" || Array.isArray(source)) return out
+  for (const [key, entry] of Object.entries(source)) {
+    if (isSpent(entry, now)) out[key] = entry
+  }
+  return out
+}
+
 /**
  * @param {string} dir the project root
  * @returns {string}
@@ -30,31 +114,69 @@ export function healthPath(dir) {
 }
 
 /**
+ * The health file, or an empty one.
+ *
+ * A file that is not an object - null, an array, a number, a string - is not
+ * a health file, and reading it as one made `unhealthyModels` throw on a
+ * null. That call sits inside a bare catch in src/index.ts, so the throw
+ * silently skipped the effort plan AND the write of `.space/active` that the
+ * pruner depends on: a corrupt file switched the pruner off without a word.
+ *
  * @param {string} dir the project root
  * @returns {Health}
  */
 export function readHealth(dir) {
+  /** @type {any} */
+  let parsed
   try {
-    return JSON.parse(readFileSync(healthPath(dir), "utf8"))
+    parsed = JSON.parse(readFileSync(healthPath(dir), "utf8"))
   } catch {
     return { unhealthy: {} }
   }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { unhealthy: {} }
+  }
+  const unhealthy = parsed.unhealthy
+  if (!unhealthy || typeof unhealthy !== "object" || Array.isArray(unhealthy)) {
+    // The other keys are kept: `active` names the profile the fleet is
+    // running, and dropping it because the routes are malformed would lose
+    // the pruner's target as well.
+    return { ...parsed, unhealthy: {} }
+  }
+  return parsed
 }
 
 /**
+ * Write the health file, without the routes whose window has passed.
+ *
+ * The expiry is applied on the way out as well as on the way in, so a file
+ * that is read and written again - which the router does on every event -
+ * does not carry its dead routes forever.
+ *
  * @param {string} dir the project root
  * @param {Health} health
  */
 export function writeHealth(dir, health) {
   try {
     if (!existsSync(join(dir, ".space"))) mkdirSync(join(dir, ".space"), { recursive: true })
-    writeFileSync(healthPath(dir), JSON.stringify(health, null, 2))
+    const pruned = { ...(health ?? {}), unhealthy: liveUnhealthy(health) }
+    writeFileSync(healthPath(dir), JSON.stringify(pruned, null, 2))
   } catch {
     // Best effort. A health file that cannot be written means no failover,
     // and failing to write it must not break the session.
   }
 }
 
+/**
+ * The routes on disk that are still spent.
+ *
+ * @param {string} dir the project root
+ * @returns {Record<string, SpentEntry>}
+ */
+export function unhealthyRoutes(dir) {
+  return liveUnhealthy(readHealth(dir))
+}
+
 /**
  * The models a previous session found spent.
  *
@@ -67,13 +189,16 @@ export function writeHealth(dir, health) {
  * lane chains list bare model ids, so the prefix is dropped here. Comparing
  * the two directly would never match, and a spent route would look healthy.
  *
+ * A route whose window has passed is not spent any more, and is not returned
+ * here: the provider's quota comes back at 00:00 UTC, and a lane that stays
+ * on its fallback forever is a lane that never comes back either.
+ *
  * @param {string} dir the project root
  * @returns {Set<string>}
  */
 export function unhealthyModels(dir) {
-  const health = readHealth(dir)
   const out = new Set()
-  for (const key of Object.keys(health.unhealthy ?? {})) {
+  for (const key of Object.keys(unhealthyRoutes(dir))) {
     out.add(key.includes("/") ? key.slice(key.indexOf("/") + 1) : key)
   }
   return out

package/src/lane-usage.js

@@ -34,10 +34,11 @@ import { dirname, join, resolve } from "node:path"
  * The telemetry files for the project containing `startDir`.
  *
  * ALL of them, oldest first. The plugin rotates the file when it passes 4 MB
- * and renames the old one to `telemetry.jsonl.1` - and the reader used to
- * look at `telemetry.jsonl` alone, so a rotation silently threw away the
- * history and every lane reported "never used". The number that decides
- * whether the fleet stays at ten lanes was disappearing on a schedule.
+ * and keeps THREE generations - `telemetry.jsonl`, `telemetry.jsonl.1` and
+ * `telemetry.jsonl.2` - and the reader used to look at `telemetry.jsonl`
+ * alone, so a rotation silently threw away the history and every lane
+ * reported "never used". The number that decides whether the fleet stays at
+ * ten lanes was disappearing on a schedule.
  *
  * @param {string} startDir
  * @returns {string[]} the paths, or an empty array when the project has none
@@ -62,13 +63,19 @@ export function findTelemetryFiles(startDir) {
 }
 
 /**
- * The telemetry file for the project containing `startDir`.
+ * The CURRENT telemetry file for the project containing `startDir`.
+ *
+ * The current one, not the oldest one. The files are enumerated oldest
+ * first, so the current file is the LAST of them - and taking the first
+ * handed back the file that had been rotated away twice, which is the
+ * history rather than the present.
  *
  * @param {string} startDir
  * @returns {string | null} the path, or null when the project has no telemetry
  */
 export function findTelemetryFile(startDir) {
-  return findTelemetryFiles(startDir)[0] ?? null
+  const files = findTelemetryFiles(startDir)
+  return files.length ? files[files.length - 1] : null
 }
 
 /**