opencode-harness-kit 0.6.3 → 0.7.0

package/bin/oc-harness.mjs

@@ -12,10 +12,10 @@
 // The point of the kit: switching models is a data edit, not a code change.
 // Everything model-specific lives in profiles/<id>.json.
 
-import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync, renameSync, unlinkSync } from "node:fs"
+import { chmodSync, copyFileSync, cpSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync, renameSync, unlinkSync } from "node:fs"
 import { homedir } from "node:os"
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
-import { execFileSync } from "node:child_process"
+import { execFileSync, spawnSync } from "node:child_process"
 import { fileURLToPath } from "node:url"
 import { createInterface } from "node:readline/promises"
 
@@ -56,6 +56,84 @@ const CONFIG_DIR =
 const CONFIG_FILE = join(CONFIG_DIR, "opencode.jsonc")
 const ROOT = import.meta.dirname ? join(import.meta.dirname, "..") : process.cwd()
 
+// A git CHECKOUT is the kit's own source of truth and is expected to stay
+// where it is: everything the kit installs symlinks back at the repository,
+// so an edit there takes effect on the next opencode start.
+//
+// Anything else - `npx`, a plain `npm install` - reached this file through a
+// package cache npm is free to clean at any command, and a symlink INTO that
+// cache is a dangling path the day `npm cache clean --force` runs. For those
+// installs the package is COPIED once to a private, durable place under the
+// config directory, and every install target links into the copy instead.
+const CHECKOUT = existsSync(join(ROOT, ".git"))
+const COPY_ROOT = join(CONFIG_DIR, "kit")
+
+/**
+ * Mirror the package's runtime assets into `COPY_ROOT`.
+ *
+ * Runs at most once per version: a `.source` marker records which package
+ * version the copy was made from, and an install of the same version keeps
+ * the existing copy rather than re-wiping files freshly linked into.
+ *
+ * The copy is whole on purpose. The plugin bundle looks for its profiles and
+ * data by walking up from itself, the prompts and skills are linked per file
+ * out of it, and every asset the behavioral layer needs lives inside it -
+ * which is also what makes `uninstall` clean: one tree, created by one
+ * command, owned by nobody else.
+ */
+function ensurePackageCopy() {
+  if (CHECKOUT) return
+  const want = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version
+  let have = null
+  try {
+    have = readFileSync(join(COPY_ROOT, ".source"), "utf8").trim()
+  } catch {}
+  if (have === want) return
+  rmSync(COPY_ROOT, { recursive: true, force: true })
+  mkdirSync(COPY_ROOT, { recursive: true })
+  for (const name of ["dist", "profiles", "prompts", "skills"]) {
+    cpSync(join(ROOT, name), join(COPY_ROOT, name), { recursive: true })
+  }
+  for (const name of ["lanes.json", "retention.yml", "GLOBAL.md", "package.json"]) {
+    // `package.json` travels with the copy because `kitVersion()` in
+    // src/config.js reads it UP from the plugin bundle's own location
+    // (`../package.json` from `dist/`). Without it, every kit field the
+    // telemetry plugin and the CLI print from a copy install read
+    // "unknown" - an install that could not say which version it was.
+    //
+    // `bin/` is deliberately NOT copied: nothing inside the copy points at
+    // the CLI, and `npx` re-fetches the entry point when the cache has been
+    // cleaned. A second copy of a 176KB CLI for a path nobody in the copy
+    // walks is dead weight, not durability.
+    cpSync(join(ROOT, name), join(COPY_ROOT, name))
+  }
+  writeFileSync(join(COPY_ROOT, ".source"), `${want}\n`)
+}
+
+/**
+ * The root the kit installs FROM: the repository in a checkout, `COPY_ROOT`
+ * otherwise. Calling it at all triggers `ensurePackageCopy()`, so a caller
+ * holding the returned paths can rely on the files existing.
+ *
+ * @returns {string}
+ */
+function kitSourceRoot() {
+  if (CHECKOUT) return ROOT
+  ensurePackageCopy()
+  return COPY_ROOT
+}
+
+/**
+ * The root installed files may POINT at: the repository in a checkout, the
+ * durable package copy otherwise. `isOurs(below)` judges ownership against
+ * it.
+ *
+ * @returns {string}
+ */
+function kitTargetRoot() {
+  return CHECKOUT ? ROOT : COPY_ROOT
+}
+
 const args = process.argv.slice(2)
 const cmd = args[0] ?? "list"
 const has = (f) => args.includes(f)
@@ -382,12 +460,13 @@ function cmdShow(id) {
 }
 
 /**
- * Link the built plugin into ~/.config/opencode/plugins so opencode loads it
- * without an npm install. This is the path to use while developing, and it
- * means the kit is usable before anything is published.
+ * Put the built plugin where opencode loads it from -
+ * ~/.config/opencode/plugins/opencode-harness-kit.js - symlinked at the kit
+ * itself from a checkout, at the durable package copy when the kit was
+ * reached through npm or npx.
  */
 function cmdLink() {
-  const dist = join(ROOT, "dist", "index.js")
+  const dist = join(kitSourceRoot(), "dist", "index.js")
   if (!existsSync(dist)) {
     fail("dist/index.js missing. Run: npm run build")
   }
@@ -426,10 +505,14 @@ function cmdLink() {
 
 /** Where the behavioural layer has to land for the config to mean anything. */
 function installTargets() {
+  // `kitSourceRoot()` is the repository in a checkout, and the durable copy
+  // of the package under the config directory otherwise - an npx cache is
+  // npm's to clean, and links into it would dangle the day it goes.
+  const root = kitSourceRoot()
   return [
-    { src: join(ROOT, "prompts"), dest: join(CONFIG_DIR, "prompts"), kind: "dir" },
-    { src: join(ROOT, "skills"), dest: join(CONFIG_DIR, "skills"), kind: "dir" },
-    { src: join(ROOT, "GLOBAL.md"), dest: join(CONFIG_DIR, "GLOBAL.md"), kind: "file" },
+    { src: join(root, "prompts"), dest: join(CONFIG_DIR, "prompts"), kind: "dir" },
+    { src: join(root, "skills"), dest: join(CONFIG_DIR, "skills"), kind: "dir" },
+    { src: join(root, "GLOBAL.md"), dest: join(CONFIG_DIR, "GLOBAL.md"), kind: "file" },
   ]
 }
 
@@ -607,7 +690,15 @@ function isLegacyAgentLink(full) {
  * prompts, the four skills, the global rules - was a `cp` line in the README
  * that nobody ran. Nothing checked it afterwards, which is how a config ended
  * up pointing at an instruction file that did not exist while still looking
- * correct. Symlinks rather than copies, so the repo stays the source of truth.
+ * correct.
+ *
+ * From a checkout everything symlinks at the repository: edit there, live
+ * everywhere. From npm or npx there is no repository to hold the truth - the
+ * cache that supplied this process can be cleaned at any moment - so the
+ * package is first COPIED to a private, durable place under the config
+ * directory (`~/.config/opencode/kit/`), and every link points in there.
+ * `linkOne` and the ownership checks are unchanged; only what sits at the far
+ * end of the link differs.
  */
 async function cmdInstall() {
   const dist = join(ROOT, "dist", "index.js")
@@ -1180,7 +1271,7 @@ function cmdVerify() {
     problems.push(
       `${kitInstruction} does not exist - the rules in it are not being loaded. Run: oc-harness install`,
     )
-  } else if (!pointsIntoKit(kitTarget)) {
+  } else if (!isOurs(kitTarget)) {
     // The kit's own file, and not a file that happens to have its name. The
     // installer refuses to replace a real file, so a user who already had a
     // GLOBAL.md keeps it - and the check above was satisfied by its mere
@@ -1218,7 +1309,7 @@ function cmdVerify() {
     // The config's own reference is still checked below: the lane's prompt
     // path is a separate thing, and a broken one is worth saying whatever
     // the file at that path happens to be.
-    if (!pointsIntoKit(file)) {
+    if (!isOurs(file)) {
       problems.push(
         `prompts/${role}.md is not the kit's file - the ${role} lane runs on somebody else's instructions. Run: oc-harness install`,
       )
@@ -1372,7 +1463,7 @@ function cmdVerify() {
       // This does not stop the frontmatter check below. A directory that is
       // not the kit's can still be a skill whose name has drifted away from
       // its directory, and that is a second thing worth saying.
-      if (!pointsIntoKit(join(skillsDir, name))) {
+      if (!isOurs(join(skillsDir, name))) {
         problems.push(
           `skills/${name} is not the kit's skill - the ${name} step of the loop runs on somebody else's instructions. Run: oc-harness install`,
         )
@@ -1539,7 +1630,7 @@ async function cmdUse(id, catalog = null, sink = {}) {
     }
     fail(msg, wantJson)
   }
-  if (!id) fail("usage: oc-harness use <profile> [--print] [--yes]")
+  if (!id) fail("usage: oc-harness use <profile> [--print] [--yes] [--no-skills]")
   let p = null
   try {
     p = loadProfile(id)
@@ -1678,7 +1769,15 @@ async function cmdUse(id, catalog = null, sink = {}) {
     )
   }
 
-  const out = generateConfig(p, { base: effectiveBase, comments: true })
+  // Relative skills paths resolve against the same directory the file lives
+  // in - the one OpenCode reads them against. The toolkit default assumes
+  // the standard config dir; the CLI knows where it actually wrote this one.
+  const out = generateConfig(p, {
+    base: effectiveBase,
+    comments: true,
+    configDir: CONFIG_DIR,
+    skills: !flag("--no-skills"),
+  })
   if (flag("--print")) {
     process.stdout.write(out)
     return
@@ -2039,6 +2138,36 @@ function pointsIntoKit(p) {
   }
 }
 
+/**
+ * Whether an installed path holds the kit's file.
+ *
+ * From a checkout that means a link into the repository itself. From npm or
+ * npx the install copied the package to `COPY_ROOT` and linked everything at
+ * THAT, so "ours" is a link into - or a file inside - the copy. Links are
+ * resolved relative to the link and without requiring them to exist, so a
+ * dangling link still counts as the kit's: the state `npm uninstall` leaves
+ * behind, and `uninstall`'s job to fix.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isOurs(p) {
+  if (CHECKOUT) return pointsIntoKit(p)
+  let st
+  try {
+    st = lstatSync(p)
+  } catch {
+    return false
+  }
+  const root = resolve(COPY_ROOT)
+  const under = (q) => q === root || q.startsWith(root + sep) || q.startsWith(root + "/")
+  if (st.isSymbolicLink()) {
+    const target = readlinkSync(p)
+    return under(isAbsolute(target) ? target : resolve(dirname(p), target))
+  }
+  return under(resolve(p))
+}
+
 /**
  * Copy the machine-derived fields of a live catalogue entry into a profile.
  *
@@ -2333,11 +2462,14 @@ function findProjectSpace(startDir) {
  * Remove what the kit installed.
  *
  * The install SYMLINKS the plugin, the prompts, the skills and GLOBAL.md out
- * of the kit's directory and into the config directory. So `npm uninstall`
- * the kit leaves four dangling symlinks behind, and opencode then loads
- * neither the rules nor the guard - and says nothing about it.
- *
- * So the kit can take them back out, and it says what it removed.
+ * of the kit - the repository in a checkout, the durable package copy
+ * otherwise - and into the config directory. So `npm uninstall` the kit
+ * leaves four dangling symlinks behind, and opencode then loads neither the
+ * rules nor the guard - and says nothing about it.
+ *
+ * So the kit can take them back out, and it says what it removed. A copy of
+ * the package under the config directory is the kit's ENTIRELY - it exists
+ * only because `install` made it - so it goes with the links.
  */
 function cmdUninstall() {
   const removed = []
@@ -2358,14 +2490,16 @@ function cmdUninstall() {
     }
     // A symlink is not enough to make it ours. The user may have their own
     // symlink in that directory - to their own prompts, to a shared folder -
-    // and "a symlink in prompts/ is the kit's" would delete it. A link whose
-    // target is inside this package is the kit's; anything else is kept.
+    // and "a symlink in prompts/ is the kit's" would delete it. A link that
+    // is the kit's to manage goes; anything else is kept. Whose a link is is
+    // `isOurs`'s decision: into the repository from a checkout, into the
+    // package copy otherwise.
     //
     // The target is resolved WITHOUT requiring it to exist. A DANGLING link
     // is the case this command exists for - `npm uninstall` leaves four of
     // them behind - and `realpathSync` throws on those, which classified the
     // kit's own broken links as somebody else's and left them in place.
-    const ours = entries.filter((f) => pointsIntoKit(join(full, f)))
+    const ours = entries.filter((f) => isOurs(join(full, f)))
     if (!ours.length) {
       kept.push(`${dir}/ holds real files`)
       continue
@@ -2388,14 +2522,14 @@ function cmdUninstall() {
   for (const t of targets) {
     if (!existsSync(t) && !isSymlink(t)) continue
     try {
-      // Only a link into this package is ours to remove. A real file the
+      // Only a link the kit installed is ours to remove. A real file the
       // user put there is theirs, and so is a link to their own file -
       // `GLOBAL.md` is a standard opencode name.
       if (!isSymlink(t)) {
         kept.push(`${t} is a real file`)
         continue
       }
-      if (!pointsIntoKit(t)) {
+      if (!isOurs(t)) {
         kept.push(`${t} points somewhere else`)
         continue
       }
@@ -2405,6 +2539,18 @@ function cmdUninstall() {
       kept.push(`${t} (could not be removed)`)
     }
   }
+  // The package copy - `~/.config/opencode/kit/` when the kit was reached
+  // through npm or npx - exists only because `install` created it, so it
+  // goes out with the links. Unreachable from a checkout, where no copy
+  // exists.
+  if (!CHECKOUT && existsSync(COPY_ROOT)) {
+    try {
+      rmSync(COPY_ROOT, { recursive: true, force: true })
+      removed.push("kit/ (the package copy this install was built from)")
+    } catch {
+      kept.push(`${COPY_ROOT} (could not be removed)`)
+    }
+  }
   console.log(`\n${bold("uninstall")}\n`)
   for (const r of removed) console.log(`  ${green("✓")} removed ${r}`)
   for (const k of kept) console.log(`  ${yellow("!")} left alone: ${k}`)
@@ -2944,8 +3090,8 @@ async function runDoctor(catalog) {
     }
     const live = catalog?.[p.provider]?.models?.[p.model]
     if (!live) {
-      console.log(`  ${red("✗")} ${id.padEnd(32)} ${red("not in models.dev - may be withdrawn")}`)
-      note("drift", id, "not in models.dev - may be withdrawn")
+      console.log(`  ${red("✗")} ${id.padEnd(32)} ${red("not in models.dev - drifted from live metadata")}`)
+      note("drift", id, "not in models.dev - drifted from live metadata")
       drift++
       continue
     }
@@ -3397,11 +3543,62 @@ async function cmdRun() {
     fail(`--role ${role} is not one of ${lanes.join(", ")}`)
   }
 
+  // `spawnSync("opencode", ...)` in the driver reports a missing binary as a
+  // failed agent, which marks the FIRST task blocked and blames the task. The
+  // install is the thing that is broken, so say that here, before any task is
+  // touched.
+  try {
+    execFileSync("opencode", ["--version"], { stdio: "ignore", timeout: 15_000 })
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? err.code : undefined
+    fail(
+      code === "ENOENT"
+        ? "opencode is not on PATH. Install it first: https://opencode.ai/docs"
+        : "opencode --version failed. Fix the install before running the loop.",
+    )
+  }
+
+  // The files: scope check reads `git status`. Outside a work tree it cannot
+  // see anything, so it used to switch itself off in silence -- an unattended
+  // run believing it was fenced while it was not. The one honest place to say
+  // that is here, before the first task, and the explicit override is the same
+  // flag that already means "no scope check".
+  const allowExtraFiles = flag("--allow-extra-files")
+  if (!allowExtraFiles) {
+    const git = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      encoding: "utf8",
+      timeout: 10_000,
+    })
+    if (git.status !== 0 || String(git.stdout ?? "").trim() !== "true") {
+      fail(
+        "oc-harness run needs a git work tree, because the files: scope check reads git status. Run it inside a repository, or pass --allow-extra-files to run without the check.",
+      )
+    }
+  }
+
+  // A lane's step cap is the other way an agent stops mid-task. When it is
+  // reached opencode exits 0 with a text-only answer, so the loop sees a
+  // failed verify and has no idea why. Reading the cap here lets the stop say
+  // "it ran out of steps" instead of leaving that to the log.
+  let stepCap = 0
+  try {
+    const cfg = existsSync(CONFIG_FILE) ? parseJsonc(readFileSync(CONFIG_FILE, "utf8")) : null
+    const configured = cfg?.agent?.[role]?.steps
+    if (Number.isInteger(configured) && configured > 0) stepCap = configured
+  } catch {
+    // An unreadable config is opencode's failure to report, and it will. A
+    // label on a stop is not worth turning into a second reason to fail.
+  }
+
   const result = runLoop({
     cwd: process.cwd(),
     role,
     maxRounds,
     budgetMinutes,
+    allowExtraFiles,
+    forceUnlock: flag("--force-unlock"),
+    review: flag("--review"),
+    stepCap,
   })
 
   const s = result.summary
@@ -3497,6 +3694,7 @@ try {
     auto      refresh + install + use + verify, asking nothing - the
               unattended reconcile, for an agent or a job
     use <id>  compile a profile into ${CONFIG_FILE}
+              --no-skills omits the skill list from the lanes' prompt
     show <id> print the resolved lane plan and derived numbers
     refresh <id>  update capability fields from models.dev
     install   symlink the plugin, prompts, skills and GLOBAL.md into the config dir
@@ -3514,7 +3712,7 @@ try {
     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
+    run       build and verify .space/tasks.md one task at a time
 
   options
     --print        write the config to stdout instead of disk
@@ -3537,6 +3735,14 @@ try {
     --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)
+    --allow-extra-files  let a task change files its files: line does not
+                   name. Without this, an out-of-scope edit stops the loop,
+                   and the run needs a git work tree to see the change.
+    --force-unlock  clear a lock held by a live pid. Only for a lock left by
+                   a pid that was reused; two real runs must not overlap.
+    --review       after verify, ask the reviewer lane for a schema'd verdict.
+                   The run stops on fail or on any malformed verdict. The
+                   verdict is written to .space/review/.
 `)
     // 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

package/dist/budget.d.ts

@@ -0,0 +1,247 @@
+export declare const DEFAULT_WARN_TOKENS = 2000000;
+export declare const DEFAULT_STOP_TOKENS = 5000000;
+export declare const DEFAULT_TURN_STOP_TOKENS = 300000;
+export declare const DEFAULT_WINDOW_MINUTES = 60;
+export declare const DEFAULT_WINDOW_WARN_TOKENS = 4000000;
+export declare const DEFAULT_WINDOW_STOP_TOKENS = 8000000;
+/**
+ * What one request cost, in context tokens.
+ *
+ * A `step-finish` part reports four separate numbers: `input` is the part of
+ * the prompt that was not cached, `cache.read` is the cached prefix the model
+ * still had to read, `cache.write` is the prefix stored for the next request,
+ * and `output`/`reasoning` are what the model wrote. The first three are the
+ * context; only the first was counted before, which is why a step that cost
+ * 37,324 tokens was recorded as 844.
+ *
+ * `cache.write` is charged once, on the request that stored it, so summing it
+ * here is not double counting the reads that follow. Nor does it overlap
+ * `input`: across 605 measured steps the reported `total` was exactly
+ * `input + cache.read + cache.write + output + reasoning` every time, so the
+ * parts are disjoint and the three that are counted are the whole context.
+ *
+ * A value that is not a number contributes zero: a missing field must not turn
+ * the whole count into NaN, because a NaN comparison never fires a threshold.
+ *
+ * @param {any} tokens a `step-finish` part's `tokens`
+ * @returns {number}
+ */
+export declare function requestTokens(tokens: any): number;
+/**
+ * The limits this process should use.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {{ warnAt: number, stopAt: number, turnStopAt: number }}
+ */
+export declare function budgetLimits(env?: Record<string, string | undefined>): {
+    warnAt: number;
+    stopAt: number;
+    turnStopAt: number;
+};
+/**
+ * A running total for one session.
+ *
+ * `add` returns the thresholds this call CROSSED, so the caller can warn once
+ * rather than once per request. A request that lands exactly on a threshold
+ * crosses it, and a request of zero tokens - a retry that never reached the
+ * provider - moves nothing.
+ *
+ * @param {{ warnAt?: number, stopAt?: number }} [limits]
+ */
+export declare function createBudget({ warnAt, stopAt }?: {
+    warnAt?: number;
+    stopAt?: number;
+}): {
+    /**
+     * @param {any} input tokens this request cost
+     * @returns {{ warn: boolean, stop: boolean }}
+     */
+    add(input: any): {
+        warn: boolean;
+        stop: boolean;
+    };
+    readonly total: number;
+    readonly warned: boolean;
+    readonly stopped: boolean;
+};
+/**
+ * A count with separators, for a message a human reads.
+ *
+ * @param {number} n
+ * @returns {string}
+ */
+export declare function tokens(n: number): string;
+/**
+ * Where the shared ledger lives.
+ *
+ * `XDG_STATE_HOME` is the right place for state that survives a reboot and is
+ * not configuration; falling back to `~/.local/state` is what the spec says to
+ * do. `OC_HARNESS_BUDGET_FILE` overrides both, which is what the tests use and
+ * what a user on a shared account would want.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export declare function ledgerPath(env?: Record<string, string | undefined>): string;
+/**
+ * The entries in the ledger, or none.
+ *
+ * Three answers, not two, because "I could not read the count" and "the count
+ * is zero" are different facts and only one of them means there is room left:
+ *
+ *   - no file            -> `[]`: nothing has been spent yet.
+ *   - a file that parses -> its entries.
+ *   - a file that does not parse -> `null`.
+ *
+ * It used to return `[]` for the third case, which made a corrupt or
+ * half-written ledger indistinguishable from an empty window: the shared stop
+ * silently disappeared. `sharedWindowSpent()` in `guard.ts` repairs the file
+ * instead (see `repairSpend`): a ledger that cannot be read must not lock the
+ * window forever, because the only way out is a hand-delete the user may not
+ * know about. Nothing here throws.
+ *
+ * A `stop` entry is a marker, not a spend: `{ t, n: 0, stop: true }` records
+ * that the window was locked at `t`, so the lock can outlive the sliding sum
+ * that tripped it.
+ *
+ * @param {string} path
+ * @returns {{ t: number, n: number, stop?: boolean }[] | null}
+ */
+export declare function readSpend(path: string): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[] | null;
+/**
+ * Keep the entries that are still inside the keep window, oldest first.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @returns {{ t: number, n: number, stop?: boolean }[]}
+ */
+export declare function pruneSpend(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Move an unreadable ledger aside and start a fresh one.
+ *
+ * The old code read a corrupt file as "spent" and failed closed, which is the
+ * right answer for a single tool call and the wrong answer for the machine:
+ * the only exit was deleting a file the user had never heard of, so the next
+ * session was blocked for six hours by a truncated JSON write. The evidence
+ * still matters - a corrupt ledger is a bug worth reading - so the broken file
+ * is renamed to `<path>.corrupt` rather than deleted, and an empty ledger
+ * replaces it. The count cannot be recovered, so the new file starts at zero;
+ * if the old file had a stop marker, `.corrupt` still holds it.
+ *
+ * Returns false when the repair could not be written; the caller then falls
+ * back to the old fail-closed answer rather than pretending the window is
+ * empty.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+export declare function repairSpend(path: string): boolean;
+/**
+ * Write the ledger, atomically.
+ *
+ * Read-modify-write without a lock: two sessions finishing a step in the same
+ * millisecond can lose one entry. That is a few thousand tokens on a budget of
+ * millions, and a lock file in this path is a worse failure mode - a crashed
+ * session would leave the window blocked for everyone.
+ *
+ * @param {string} path
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ */
+export declare function writeSpend(path: string, entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[]): void;
+/**
+ * Add one request's cost to the shared ledger.
+ *
+ * A ledger that cannot be read is repaired first, so the first write after a
+ * corruption appends to a fresh file instead of overwriting the broken one.
+ * The repair does not invent a stop: the count is unknown, and a marker that
+ * holds for six hours is the failure this repair exists to end.
+ *
+ * @param {string} path
+ * @param {number} n
+ * @param {number} [now]
+ * @returns {{ t: number, n: number, stop?: boolean }[]} the pruned ledger
+ */
+export declare function recordSpend(path: string, n: number, now?: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Record that the window was locked, so the lock survives the window it was
+ * measured in.
+ *
+ * The sum is over the last hour, and the provider's window is not: it stayed
+ * shut for hours after the stop fired. A lock that releases itself on a timer
+ * is a lock that was only partly on, so the marker holds until `KEEP_MS`.
+ *
+ * @param {string} path
+ * @param {number} [now]
+ * @returns {{ t: number, n: number, stop?: boolean }[]} the pruned ledger
+ */
+export declare function recordStop(path: string, now?: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Whether a stop marker is still inside the keep window.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @returns {boolean}
+ */
+export declare function stopRecorded(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number): boolean;
+/**
+ * Tokens spent in the last `windowMs`, across every session on this machine.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @param {number} windowMs
+ * @returns {number}
+ */
+export declare function windowSpend(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number, windowMs: number): number;
+/**
+ * The shared-window thresholds.
+ *
+ * `OC_HARNESS_BUDGET_WINDOW_MINUTES` sets the window (default 60). Zero or a
+ * value that is not a positive number falls back to the default: a window of
+ * zero would sum nothing and silently disable the tripwire.
+ *
+ * `OC_HARNESS_BUDGET_WINDOW_STICKY` (default on) makes a stop hold until its
+ * marker ages out, instead of ending when the entries that tripped it roll out
+ * of the window. `0` restores the sum-only behaviour, which unlocks the
+ * window on a timer the provider does not keep.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {{ windowMs: number, warnAt: number, stopAt: number, sticky: boolean }}
+ */
+export declare function windowLimits(env?: Record<string, string | undefined>): {
+    windowMs: number;
+    warnAt: number;
+    stopAt: number;
+    sticky: boolean;
+};