opencode-harness-kit 0.5.4 → 0.5.5

package/dist/profile.d.ts

@@ -307,8 +307,21 @@ export declare function pruneThreshold(p: Profile, opts?: {
     unhealthy?: Set<string>;
 }): number;
 /**
- * Every model a profile can put behind the user: the base model plus the model
- * each lane actually resolves to.
+ * Every model a profile can put behind the user: the base model, the model
+ * each lane actually resolves to, and the utility route.
+ *
+ * The utility route belongs in this list because it is WRITTEN into the
+ * config as `small_model` and opencode sends real requests down it - a
+ * title, a one-line summary, a rewritten question. It used to be a chain
+ * rung only, so it never appeared here, and a profile could name a
+ * may-train utility route under a zero-retention claim: the file said
+ * "zero-retention" while a training provider served the calls.
+ *
+ * Every caller of this list wants the same thing - the models that can
+ * serve a request - so the list is widened rather than a second one
+ * invented beside it. The one caller that needs the lanes alone is
+ * `validate()`, which cross-checks the profile's DECLARED retention against
+ * the base model and the lanes; that is `laneModelsInPlay`.
  *
  * @param {Profile} p
  * @param {{ unhealthy?: Set<string> }} [opts]
@@ -317,6 +330,23 @@ export declare function pruneThreshold(p: Profile, opts?: {
 export declare function modelsInPlay(p: Profile, opts?: {
     unhealthy?: Set<string>;
 }): string[];
+/**
+ * The models the profile's own base and lanes put behind the user, without
+ * the utility route.
+ *
+ * This is the set the profile's own `retention` field is about: the base
+ * model and the lanes it resolves to. The utility route is an extra route
+ * the profile adds on top of them, and it is reported where it belongs - the
+ * config header names it, and `oc-harness use` warns about it - so it does
+ * not decide what the profile may declare about itself.
+ *
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {string[]}
+ */
+export declare function laneModelsInPlay(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): string[];
 /**
  * The split lanes, each with the limits of the model that lane actually runs
  * on. A lane on a different model has a different output cap, and the header

package/dist/telemetry-store.d.ts

@@ -3,6 +3,28 @@ export declare const MAX_BYTES: number;
 export declare function logPath(dir: string): string;
 /** The telemetry file and its rotated predecessors, oldest first. */
 export declare function logFiles(dir: string): string[];
+/**
+ * Rotate by size so a long-running project cannot fill its disk.
+ *
+ * THREE generations are kept: the current file, `.1` and `.2`. The reader
+ * enumerates all three, so the writer has to produce all three.
+ *
+ * The rotation used to rename the current file straight to `.1`, and a
+ * rename REPLACES the destination on POSIX - so the previous generation was
+ * destroyed on every rotation and `.2` never came into existence. Two
+ * rotations after the fact, the oldest history was gone and the third
+ * generation the reader looks for was missing: the history a project lost
+ * was lost on a schedule nobody was watching.
+ *
+ * So the oldest is shifted out of the way first, and the oldest of the
+ * three is dropped - the disk use stays bounded at three files, and the
+ * generation that is dropped is the one that was already two rotations
+ * old.
+ *
+ * @param file the file to rotate
+ * @param maxBytes the size above which it is rotated
+ */
+export declare function rotate(file: string, maxBytes?: number): void;
 /**
  * Append one record.
  *

package/docs/EXIT-CODES.md

@@ -75,6 +75,13 @@ attributable measurement carries the gate.
 | 0 | The install is in place, or the change was confirmed. Something may have been left alone - a file that was already there, a prompt that was not answered - and the reason is printed. |
 | 1 | The install was refused, or a step failed. |
 
+A target that was left alone is NOT counted as installed: the install says
+so in place of its tick, and `verify` reports the file that is not the kit's
+- because a file of the user's own at `GLOBAL.md` means the kit's rules are
+not being loaded, and a tick next to that is a claim the installer cannot
+make. A link that could not be created is a step that failed, and the
+install exits 1.
+
 `doctor` also exits 1 when there is no config, or no profile recorded in
 it: a kit that is installed but points at nothing is a broken install, and
 a check that passes it is not a check.

package/docs/KNOWN-LIMITS.md

@@ -361,13 +361,24 @@ re-reads stop: **-69% input tokens and -60% wall time** on that task, at the
 cost of a bigger context. It is a setting - `prune.keepDistinctOutputs` - and
 turning it off brings the old behaviour back.
 
-A `savedChars` of 0 in `prune.jsonl` is not a second, redundant pass. It means
-`bytesAfter` did not come out below `bytesBefore` for that turn, which happens
-when a stub is no shorter than the output it replaced (the stub's own label
-costs more than a short body), or when a `reasoning` part was under the 200
-byte floor and so was not shortened at all. These lines are still logged
-because a part was stubbed, which is the event worth recording. Savings
-aggregate correctly either way, since each line is measured independently.
+`savedChars` in `prune.jsonl` is the size of the request before the pass minus
+the size after it, measured on the parts as they are serialised - not on the
+text inside them. It used to measure the text only, and to ignore the state
+the stub put in a part's place, which carries about fifty characters of its
+own metadata per stubbed part. So a pass whose request GREW was reported as
+a saving of the difference between two texts.
+
+A negative `savedChars` therefore means the pass made the request BIGGER: the
+stub was longer than the output it replaced, because the stub carries its own
+label and its own metadata. Such a pass is still logged, because a part was
+stubbed, which is the event worth recording, and the negative number is the
+honest report of it.
+
+There is no minimum size under which a part is left alone. This file used to
+claim a 200 byte floor for `reasoning` parts; there was never such a floor in
+the code, and a reasoning part shorter than the stub - about seventy-eight
+characters - is still replaced, so the request grows. The measurement above
+is what makes that visible instead of silent.
 
 `baseline.mjs` measures permission pressure with its own glob approximation of
 OpenCode's matcher, not OpenCode's matcher. It handles the cases that matter

package/eval/measure-prune.mjs

@@ -186,11 +186,20 @@ const hook = await HarnessPlugin(
 const transform = hook["experimental.chat.messages.transform"]
 
 /**
- * The size the PRUNER measures.
+ * The size this measurement counts.
  *
- * The pruner counts CHARACTERS, not bytes: `part.text.length`. The report
- * labelled that "bytes", which is wrong for anything that is not ASCII - and
- * an agent's output is not ASCII. Both numbers are reported.
+ * CHARACTERS, not bytes: `part.text.length`. The report labelled that
+ * "bytes", which is wrong for anything that is not ASCII - and an agent's
+ * output is not ASCII. Both numbers are reported.
+ *
+ * This counts the TEXT of every part, while the pruner's own log counts the
+ * PART - and only the parts the pruner touched. So the two numbers answer
+ * two different questions and are not the same number twice: this one asks
+ * how much TEXT the pruner removed from a stored session, the log asks how
+ * much the REQUEST that went out shrank. The stub the pruner leaves behind
+ * carries about fifty characters of metadata of its own, so the log's
+ * saving is the smaller of the two, and it can even be negative where this
+ * one is positive. The gap is stated rather than hidden.
  */
 function sizeOf(part) {
   if (typeof part?.text === "string") return part.text.length

package/package.json

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

package/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,50 @@ 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 neither layer today:
+  // the guard's rule needs the flag before the path, and the glob needs
+  // the flag in front. The config asks, so a human decides. Closing that
+  // hole is a change to the guard's rule in src/rules.js, which reads the
+  // tokens - a glob here could only name one spelling of it, and the
+  // spelling would still be the one it missed.
+  "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 +92,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 +103,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 +122,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
 }