opencode-harness-kit 0.2.0 → 0.2.1

package/README.md

@@ -3,13 +3,26 @@
 [![CI](https://github.com/pham-canh/space-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/pham-canh/space-harness/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/opencode-harness-kit.svg)](https://www.npmjs.com/package/opencode-harness-kit)
 
+<p align="center">
+  <video src="docs/demo/pitch.mp4" width="720" controls></video>
+</p>
+
+*Four minutes forty-seven seconds, recorded live from a real terminal and
+narrated. The take script and the voiceover are in [`video/`](video/), and
+rebuilding it is documented there — including the two mistakes that cost the
+most time, so the next person does not repeat them.*
+
 A harness kit for [OpenCode](https://opencode.ai) that is **model-agnostic by
 construction**. Switching models is a data edit, not a code change.
 
 ```bash
-npx oc-harness init                  # pick a free model, then install + verify
+npx -y opencode-harness-kit init    # pick a free model, then install + verify
 ```
 
+<p align="center">
+  <img src="docs/demo-loop.gif" width="760" alt="oc-harness list showing the model-agnostic profiles, then oc-harness verify reporting a consistent install">
+</p>
+
 then restart opencode. That is the whole quickstart. No npm account needed on
 your side — `npx` only downloads the published kit. Prefer git? The same three
 steps from a checkout (see [Install](#install)):
@@ -19,11 +32,6 @@ git clone https://github.com/pham-canh/space-harness.git
 ./bin/oc-harness.mjs init
 ```
 
-![demo: init and verify in one go](docs/demo/demo.gif)
-
-Regenerate it any time with `python3 docs/demo/render.py` (needs ffmpeg); the
-frames are drawn from real CLI output, not typed by hand.
-
 The three steps `init` runs, spelled out for when you want to know what
 happened (prefix with `npx` or `./bin/oc-harness.mjs` to taste):
 
@@ -52,7 +60,7 @@ profiles/space-bunny-free.json     ← the model
 src/                               ← no model name anywhere in here
 ```
 
-Same plugin source, four shipped profiles, four different behaviours. The test
+Same plugin source, five shipped profiles, five different behaviours. The test
 suite asserts that rather than taking it on faith.
 
 ## What the compiler derives
@@ -159,20 +167,41 @@ three of its five roles run on Muse Spark, a Meta contributor-tier endpoint whos
 provider may train on your prompts. Install it for public or throwaway
 repositories.
 
+## Requirements
+
+| | |
+|---|---|
+| Node | **22 or newer** — `engines` in package.json, and the CLI uses `node:` prefixed builtins. Node 20 fails at import time, not with a friendly message. |
+| npm | 10 or newer, for `npm ci` when installing from a checkout |
+| OS | macOS, Linux and Windows. No platform checks in the code; the tests run on `ubuntu-latest`. |
+| Shell | none. The CLI never shells out, so no `bash`, `zsh` or `fish` setup is needed. |
+| Network | `list` and `doctor` read models.dev, which is the point of both. Everything else, including `install`, `use` and `verify`, works offline. |
+| Disk | it writes into `~/.config/opencode/` and nothing else. |
+
+`~/.config/opencode/` is your live agent config. `use` and `install` write there,
+`verify` only reads, and `use --dryrun` writes nothing at all. Every write keeps
+a `.bak` next to the file, including under `--yes`.
+
 ## Commands
 
 ```
 oc-harness list       profiles with retention and caveats
-oc-harness use <id>   compile a profile into ~/.config/opencode/opencode.jsonc
 oc-harness show <id>  resolved effort, derived numbers, fallback queue
+oc-harness init       pick a free profile, then install + verify
+oc-harness use <id>   compile a profile into ~/.config/opencode/opencode.jsonc
 oc-harness use <id> --dryrun   print what would be written, write nothing
+oc-harness refresh <id> re-derive a profile against the live model list
 oc-harness install    symlink the plugin, agents, skills and GLOBAL.md
+oc-harness link       just the plugin and instruction file, no agents or skills
 oc-harness verify     check the install against the profile; non-zero on drift
 oc-harness agents     report agents the effort tiering does not reach
 oc-harness doctor     re-check profiles against models.dev and the live config
 oc-harness baseline   measure the current install
 ```
 
+`oc-harness <anything-else>` now exits non-zero with the list of real commands,
+instead of printing help and reporting success.
+
 ### `verify` is the command that matters
 
 A generated config is only half an install. The other half is the instruction
@@ -333,8 +362,7 @@ pkg install nodejs git
 npx -y opencode-harness-kit init
 ```
 
-Not published to npm yet, or no registry access? The checkout path works
-identically:
+Without registry access, the checkout path works identically:
 
 ```bash
 pkg install nodejs git
@@ -460,6 +488,15 @@ Measured results, and the limits they do not cross, are in
 `docs/RESEARCH.md` records where the numbers came from and what was tried and
 rejected.
 
+## Contributing
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) — the bar is that every change is
+verifiable. Offline tests stay offline, anything that writes to disk needs a
+`--dryrun` and a backup, and a number that moves updates the README in the same
+commit. Bug reports go to [SECURITY.md](SECURITY.md) if they involve a key or
+someone else's config; otherwise open an issue with the command you ran and what
+it printed.
+
 ## License
 
 MIT

package/agents/build.md

@@ -2,7 +2,7 @@
 description: Writes code and verifies it. Use when the plan is settled and files need to change.
 mode: primary
 model: opencode/space-bunny-free
-variant: high
+variant: max
 steps: 40
 permission:
   edit: allow

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"
@@ -32,6 +32,7 @@ import {
   resolveDefaultVariant,
   resolveRoles,
   ProfileError,
+  parseJsonc,
 } from "../src/profile.js"
 import { generateConfig, globalInstructionsPath } from "../src/config.js"
 import { planEffort } from "../src/effort.js"
@@ -134,7 +135,7 @@ 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}`)
@@ -373,25 +374,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 +432,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 {
@@ -631,10 +641,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 +659,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))
@@ -687,16 +696,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. */
@@ -838,7 +855,7 @@ async function cmdDoctor() {
       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 +875,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
@@ -908,7 +925,7 @@ function cmdAgents() {
     fail("no profile is installed. Run: oc-harness use <profile>")
   }
 
-  const config = existsSync(CONFIG_FILE) ? stripComments(readFileSync(CONFIG_FILE, "utf8")) : {}
+  const config = readConfigJson()
   const configured = config.model ?? "(none)"
   const wantModel = `${current.provider}/${current.model}`
 
@@ -960,6 +977,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":
@@ -995,6 +1038,9 @@ try {
     case "baseline":
       await import("./baseline.mjs")
       break
+    case "run":
+      await cmdRun()
+      break
     case "help":
     default:
       console.log(`
@@ -1011,13 +1057,25 @@ try {
     agents        report agents the effort tiering does not reach
     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)

package/dist/index.js

@@ -564,16 +564,87 @@ function configFilePath() {
   const dir = process.env.OPENCODE_CONFIG_DIR ?? join(process.env.HOME ?? "", ".config", "opencode");
   return join(dir, "opencode.jsonc");
 }
+function parseJsonc(text) {
+  let out = "";
+  let i = 0;
+  let inString = false;
+  let escaped = false;
+  let pendingComma = false;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      if (pendingComma) {
+        out += ",";
+        pendingComma = false;
+      }
+      out += ch;
+      inString = true;
+      i++;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < n && text[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < n && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === ",") {
+      if (pendingComma) return null;
+      pendingComma = true;
+      i++;
+      continue;
+    }
+    if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
+      out += ch;
+      i++;
+      continue;
+    }
+    if (ch === "}" || ch === "]") {
+      pendingComma = false;
+      out += ch;
+      i++;
+      continue;
+    }
+    if (pendingComma) {
+      out += ",";
+      pendingComma = false;
+    }
+    out += ch;
+    i++;
+  }
+  try {
+    const parsed = JSON.parse(out);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    if (!out.trim()) return {};
+    return null;
+  }
+}
 function profileIdFromConfig() {
   const fromEnv = process.env.OPENCODE_HARNESS_PROFILE;
   if (fromEnv) return fromEnv.trim() || null;
   const file = configFilePath();
   if (!existsSync(file)) return null;
   try {
-    const text = readFileSync(file, "utf8");
-    const json = text.slice(text.indexOf("{"));
-    const parsed = JSON.parse(json);
-    const id = parsed?.harness?.profile;
+    const parsed = parseJsonc(readFileSync(file, "utf8"));
+    const harness = parsed?.harness;
+    const id = harness && typeof harness === "object" ? (
+      /** @type {{profile?: unknown}} */
+      harness.profile
+    ) : null;
     return typeof id === "string" && id ? id : null;
   } catch {
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-harness-kit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Model-agnostic harness kit for OpenCode: capability profiles, role-based reasoning effort, context pruning, and measured baselines.",
   "license": "MIT",
   "homepage": "https://github.com/pham-canh/space-harness#readme",
@@ -37,7 +37,7 @@
     "GLOBAL.md",
     "agents/",
     "skills/",
-    "docs/",
+    "docs/*.md",
     "README.md",
     "LICENSE"
   ],
@@ -75,9 +75,7 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.18.31",
     "@types/node": "^22.0.0",
+    "esbuild": "^0.28.2",
     "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "esbuild": "^0.28.2"
   }
 }

package/profiles/space-bunny-free.json

@@ -27,7 +27,7 @@
   },
   "roles": {
     "plan": "max",
-    "build": "high",
+    "build": "max",
     "reviewer": "max",
     "locate": "low",
     "verify": "low"

package/skills/space-finish/SKILL.md

@@ -27,16 +27,6 @@ over an unreviewed or blocked change is the failure this skill exists to stop.
    config or profile, run its verify command. A hand-edit survives a regeneration
    silently, and that is how a zero-retention claim ends up running on a
    may-train model.
-2. **Read the diff once more as a whole.** Reviewers read task by task; you
-   read the change as someone who has never seen it will.
-3. **Check the documentation.** Did this change make a document describe
-   something that no longer exists? Fix the document, do not note it for later.
-4. **Write the summary** a person needs in order to trust the change without
-   reading the whole diff.
-5. **Check the install is still whole.** If this project is driven by a generated
-   config or profile, run its verify command. A hand-edit survives a regeneration
-   silently, and that is how a zero-retention claim ends up running on a
-   may-train model.
 
 ## Summary shape
 

package/src/driver/run.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+// `oc-harness run` -- drive the space-plan -> build -> review -> finish loop
+// without a human at the keyboard.
+//
+// The four skills already know how to do their own job. What was missing was
+// the thing that decides *which* one runs next and *when to stop*. That is
+// here, and it is deliberately small: it reads `.space/tasks.md`, hands one
+// task at a time to `opencode run --agent <role>`, records the real verify
+// output, and stops.
+//
+// What it will not do, ever:
+//   - push, open a PR, or cut a release. Publishing is a human decision, and an
+//     unattended loop that can do it is an unattended loop that will.
+//   - retry a task it already blocked, or start a task with no verify command.
+//     A task it cannot check is a task it cannot claim is done.
+//   - loop forever. Every stop condition is explicit and every one of them is
+//     reported, so a run that ends is never a mystery.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import {
+  parseTasks,
+  nextPending,
+  markTask,
+  taskPrompt,
+  summarize,
+  isBlocked,
+} from "../tasks.js"
+
+const TASKS_PATH = join(".space", "tasks.md")
+
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+const stamp = (s) => `\x1b[2m${s}\x1b[0m`
+const green = (s) => `\x1b[32m${s}\x1b[0m`
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+const red = (s) => `\x1b[31m${s}\x1b[0m`
+
+/**
+ * Run one command to completion and report what happened.
+ *
+ * Never throws: the caller has to be able to write the failure into the task
+ * file, which is the only record anyone gets of why a task did not land.
+ */
+export function sh(command, { cwd, timeoutMs = 900_000 } = {}) {
+  const started = Date.now()
+  const res = spawnSync(command, {
+    shell: true,
+    cwd,
+    timeout: timeoutMs,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    env: { ...process.env, NO_COLOR: process.env.NO_COLOR ?? "" },
+  })
+  const stdout = `${res.stdout ?? ""}${res.stderr ?? ""}`.trimEnd()
+  return {
+    ok: res.status === 0,
+    status: res.status,
+    // A spawn that never started has no stderr; say so instead of implying the
+    // command ran and said nothing.
+    output: stdout || (res.error ? String(res.error.message) : ""),
+    seconds: Math.round((Date.now() - started) / 1000),
+  }
+}
+
+/** The tail of a verify run -- the last few lines are the verdict. */
+export function tail(text, n = 12) {
+  const lines = String(text).split("\n").filter((l) => l.trim())
+  return lines.slice(-n).join("\n")
+}
+
+/**
+ * Ask `opencode` to do the task. Returns the transcript so a human can read what
+ * the agent actually did rather than being told about it.
+ */
+export function invokeAgent(role, prompt, { cwd, timeoutMs }) {
+  const res = spawnSync(
+    "opencode",
+    ["run", "--agent", role, "--format", "json", prompt],
+    {
+      cwd,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      maxBuffer: 64 * 1024 * 1024,
+    },
+  )
+  return {
+    ok: res.status === 0,
+    status: res.status,
+    output: `${res.stdout ?? ""}${res.stderr ?? ""}`.trimEnd(),
+    error: res.error ? String(res.error.message) : "",
+  }
+}
+
+/** The agent's own instructions for one task, plus what the loop expects back. */
+export function buildPrompt(task) {
+  return [
+    `You are the space-build agent. Do exactly this one task and stop.`,
+    ``,
+    taskPrompt(task),
+    ``,
+    task.verify
+      ? `When the change is done, run this command yourself: ${task.verify}`
+      : `There is no verify command for this task. Do the work, say what you changed, and stop.`,
+    ``,
+    `Rules for this run:`,
+    `  - Change only the files named above. If the task is wrong or blocked, say so and stop.`,
+    `  - Never run git push, never create a PR, never publish. A human does that.`,
+    `  - Report the real output of the verify command. Never invent a passing result.`,
+  ].join("\n")
+}
+
+/**
+ * Run the loop.
+ *
+ * Stops at the first of: nothing pending, nothing verifiable, a blocked task, a
+ * failing verify, the round cap, or the time budget. Whichever it was gets
+ * printed, so a run that stops early always says why.
+ */
+export function runLoop({
+  cwd = process.cwd(),
+  role = "build",
+  maxRounds = 20,
+  budgetMinutes = 120,
+  runAgent = invokeAgent,
+  runVerify = sh,
+} = {}) {
+  const started = Date.now()
+  const budgetMs = budgetMinutes * 60_000
+  const log = []
+
+  if (!existsSync(join(cwd, TASKS_PATH))) {
+    return stop(log, {
+      reason: `no task file at ${TASKS_PATH}. Run space-plan first -- this loop needs a plan to walk.`,
+      code: 1,
+    })
+  }
+
+  let text = readFileSync(join(cwd, TASKS_PATH), "utf8")
+  let rounds = 0
+
+  for (;;) {
+    const parsed = parseTasks(text)
+    const task = nextPending(parsed)
+
+    if (!task) {
+      const s = summarize(parsed)
+      return stop(log, {
+        reason:
+          s.blocked > 0
+            ? `nothing left to run: ${s.done} done, ${s.blocked} blocked.`
+            : `every task is done (${s.done}/${s.total}).`,
+        code: s.blocked > 0 ? 2 : 0,
+        summary: s,
+      })
+    }
+
+    if (isBlocked(task)) {
+      return stop(log, { reason: `task is blocked and needs a person: ${task.title}`, code: 2 })
+    }
+
+    if (!task.verify) {
+      text = markTask(text, task, {
+        status: "blocked",
+        verifyOutput: "blocked by the loop: this task has no verify command, so nothing could prove it finished.",
+      })
+      writeFileSync(join(cwd, TASKS_PATH), text)
+      return stop(log, {
+        reason: `"${task.title}" has no verify command. It cannot be checked, so it cannot be run unattended. Add one, or do it yourself.`,
+        code: 2,
+      })
+    }
+
+    rounds++
+    if (rounds > maxRounds) {
+      return stop(log, { reason: `stopped at the round cap (${maxRounds}). Raise it with --max-rounds, or run fewer tasks.`, code: 2 })
+    }
+
+    const elapsed = Date.now() - started
+    if (elapsed >= budgetMs) {
+      return stop(log, { reason: `stopped at the time budget (${budgetMinutes} min, ${Math.round(elapsed / 60000)} min used).`, code: 2 })
+    }
+
+    console.log(`\n  ${bold(`[${rounds}]`)} ${task.title}`)
+    if (task.files) console.log(`      ${stamp(task.files)}`)
+
+    const agent = runAgent(role, buildPrompt(task), {
+      cwd,
+      timeoutMs: Math.max(60_000, budgetMs - (Date.now() - started)),
+    })
+    if (!agent.ok) {
+      const why = agent.error || agent.output || `exit ${agent.status}`
+      text = markTask(text, task, {
+        status: "blocked",
+        verifyOutput: `blocked by the loop: the ${role} agent failed.\n${tail(why)}`,
+      })
+      writeFileSync(join(cwd, TASKS_PATH), text)
+      return stop(log, {
+        reason: `the ${role} agent failed on "${task.title}": ${tail(why, 3).split("\n")[0]}`,
+        code: 3,
+      })
+    }
+
+    // The agent's claim is not the evidence. Re-run the verify here, because a
+    // loop that trusts the agent's own word about whether it passed is a loop
+    // that reports success it never checked.
+    console.log(`      ${stamp(`verify: ${task.verify}`)}`)
+    const check = runVerify(task.verify, { cwd, timeoutMs: 1800_000 })
+    log.push({ round: rounds, task: task.title, ok: check.ok, seconds: check.seconds })
+
+    if (!check.ok) {
+      text = markTask(text, task, {
+        status: "blocked",
+        verifyOutput: `verify failed (exit ${check.status}, ${check.seconds}s)\n${tail(check.output)}`,
+      })
+      writeFileSync(join(cwd, TASKS_PATH), text)
+      return stop(log, {
+        reason: `verify failed on "${task.title}". Marked blocked -- the real output is in ${TASKS_PATH}.`,
+        code: 4,
+      })
+    }
+
+    text = markTask(text, task, {
+      status: "done",
+      verifyOutput: `exit ${check.status} in ${check.seconds}s\n${tail(check.output)}`,
+    })
+    writeFileSync(join(cwd, TASKS_PATH), text)
+    console.log(`      ${green("done")} ${stamp(`${check.seconds}s`)}`)
+  }
+}
+
+function stop(log, { reason, code, summary }) {
+  return { reason, code: code ?? 0, rounds: log.length, log, summary }
+}
+
+export { TASKS_PATH }

package/src/profile.js

@@ -455,14 +455,118 @@ export function configFilePath() {
   return join(dir, "opencode.jsonc")
 }
 
+/**
+ * Parse JSONC the way OpenCode does: comments and trailing commas are legal.
+ *
+ * A regex that strips `//` cannot be used here. The generated config carries
+ * `"$schema": "https://opencode.ai/config.json"`, so a naive strip corrupts the
+ * URL; and a trailing comma -- ordinary in a hand-edited `.jsonc` -- makes
+ * `JSON.parse` throw, which used to surface as an empty object and silently
+ * dropped every hand-tuned key in `oc-harness use`. This walks the text once,
+ * tracking string state, so both are handled correctly.
+ *
+ * @param {string} text
+ * @returns {Record<string, unknown> | null} null when the text is not valid JSONC
+ */
+export function parseJsonc(text) {
+  let out = ""
+  let i = 0
+  let inString = false
+  let escaped = false
+  /** True once a `,` has been emitted that a `}` or `]` may turn out to cancel. */
+  let pendingComma = false
+
+  const n = text.length
+  while (i < n) {
+    const ch = text[i]
+
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === "\\") escaped = true
+      else if (ch === '"') inString = false
+      i++
+      continue
+    }
+
+    if (ch === '"') {
+      if (pendingComma) {
+        out += ","
+        pendingComma = false
+      }
+      out += ch
+      inString = true
+      i++
+      continue
+    }
+
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < n && text[i] !== "\n") i++
+      continue
+    }
+
+    if (ch === "/" && text[i + 1] === "*") {
+      i += 2
+      while (i < n && !(text[i] === "*" && text[i + 1] === "/")) i++
+      i += 2
+      continue
+    }
+
+    if (ch === ",") {
+      // A second comma before any value is malformed. Repairing `,,,` into one
+      // separator would mean guessing at a file we are about to rewrite, which
+      // is the exact failure this parser exists to prevent.
+      if (pendingComma) return null
+      // Hold the comma back: if the next significant character closes an
+      // object or array, this comma was illegal trailing punctuation.
+      pendingComma = true
+      i++
+      continue
+    }
+
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      out += ch
+      i++
+      continue
+    }
+
+    if (ch === "}" || ch === "]") {
+      // A closer cancels any comma held back before it.
+      pendingComma = false
+      out += ch
+      i++
+      continue
+    }
+
+    // Every other significant character settles a comma held back across
+    // whitespace or a comment. Miss this on the string branch below and a
+    // comment after `1, // note` swallows the separator entirely.
+    if (pendingComma) {
+      out += ","
+      pendingComma = false
+    }
+    out += ch
+    i++
+  }
+
+  try {
+    const parsed = JSON.parse(out)
+    return parsed && typeof parsed === "object" ? parsed : null
+  } catch {
+    // An empty or comments-only file is not malformed JSONC, it is an empty
+    // config, and `oc-harness use` has to be able to fill one in. Only report
+    // a parse failure when there was actually something to parse.
+    if (!out.trim()) return {}
+    return null
+  }
+}
+
 /**
  * Read the active profile id from the config file on disk.
  *
- * This exists because the `config` hook cannot be the source. OpenCode's
- * Config schema sets `additionalProperties: false`, so a custom `harness` key
- * written into the file is stripped from the object handed to the hook. The
- * file survives; the in-memory config does not. Verified against the 1.18.35
- * schema.
+ * Returns null when the file is absent, unreadable, or not valid JSONC. Callers
+ * fall back to the profile named in the `config` hook, so a null here degrades
+ * to the default profile rather than failing.
  *
  * @returns {string | null}
  */
@@ -473,10 +577,10 @@ export function profileIdFromConfig() {
   const file = configFilePath()
   if (!existsSync(file)) return null
   try {
-    const text = readFileSync(file, "utf8")
-    const json = text.slice(text.indexOf("{"))
-    const parsed = JSON.parse(json)
-    const id = parsed?.harness?.profile
+    const parsed = parseJsonc(readFileSync(file, "utf8"))
+    const harness = parsed?.harness
+    const id =
+      harness && typeof harness === "object" ? /** @type {{profile?: unknown}} */ (harness).profile : null
     return typeof id === "string" && id ? id : null
   } catch {
     return null

package/src/tasks.js

@@ -0,0 +1,248 @@
+// Parse and rewrite `.space/tasks.md`, the one artifact the whole loop reads.
+//
+// The driver reads it to decide what to do next, so a mistake here is a mistake
+// in the loop itself rather than in a report about the loop. It is kept pure and
+// line-based on purpose: every byte of the file that the loop does not own --
+// the goal, the constraints, the decisions, any prose a human added -- survives
+// a rewrite untouched.
+
+export const TASK_FIELDS = ["files", "change", "verify", "status"]
+
+const SECTIONS = ["Constraints", "Decisions", "Risks", "Tasks"]
+
+const headingRe = /^##\s+(.+?)\s*$/
+const taskRe = /^\s*-\s*\[([ xX])\]\s*(.*)$/
+const fieldRe = new RegExp(`^\\s+-\\s+(${TASK_FIELDS.join("|")})\\s*:\\s*(.*)$`)
+
+/**
+ * @typedef {object} Task
+ * @property {number} index      position in the file, zero based
+ * @property {boolean} checked   the checkbox was ticked
+ * @property {string} title      the task on one line
+ * @property {string} files      which files it is allowed to touch
+ * @property {string} change     what it is supposed to change
+ * @property {string} verify     the command that proves it
+ * @property {string} status     pending | done | blocked
+ * @property {number} start      first line of the task block
+ * @property {number} end        last line of the task block
+ * @property {string} [key]      indexed by field name when a block is written
+ */
+
+/**
+ * @typedef {object} TaskFile
+ * @property {string} goal
+ * @property {string} constraints
+ * @property {string} decisions
+ * @property {string} risks
+ * @property {Task[]} tasks
+ */
+
+/**
+ * Read a task file into its sections and tasks.
+ *
+ * Only the Tasks section is parsed structurally. Everything else is kept as raw
+ * lines so that rendering a document back never reformats a decision someone
+ * wrote in prose.
+ *
+ * @param {string} text
+ * @returns {TaskFile}
+ */
+export function parseTasks(text) {
+  const lines = String(text ?? "").split("\n")
+
+  const goal = (() => {
+    for (const line of lines) {
+      if (!line.trim()) continue
+      if (line.startsWith("# ")) return line.slice(2).trim()
+      return line.trim() // a file with no heading still has a goal on line 1
+    }
+    return ""
+  })()
+
+  /** @type {Record<string, string[]>} */
+  const sections = {}
+  let current = ""
+  for (const line of lines) {
+    const h = line.match(headingRe)
+    if (h) {
+      current = h[1]
+      if (!sections[current]) sections[current] = []
+      continue
+    }
+    if (current) sections[current].push(line)
+  }
+
+  /** @type {Task[]} */
+  const tasks = []
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(taskRe)
+    if (!m) continue
+    // A checkbox outside the Tasks section is prose, not a task.
+    if (!inSection(lines, i, "Tasks")) continue
+
+    /** @type {Record<string, any> & Task} */
+    const t = {
+      index: tasks.length,
+      checked: m[1].toLowerCase() === "x",
+      title: m[2].trim(),
+      files: "",
+      change: "",
+      verify: "",
+      status: "",
+      start: i,
+      end: i,
+    }
+
+    let last = null
+    let j = i + 1
+    for (; j < lines.length; j++) {
+      if (taskRe.test(lines[j]) || headingRe.test(lines[j])) break
+      const f = lines[j].match(fieldRe)
+      if (f) {
+        t[f[1]] = f[2].trim()
+        last = f[1]
+        continue
+      }
+      // A wrapped value continues the field above it, indented deeper.
+      if (last && lines[j].trim() && /^\s{4,}\S/.test(lines[j])) {
+        t[last] = `${t[last]} ${lines[j].trim()}`.trim()
+        continue
+      }
+      if (!lines[j].trim()) continue
+      break
+    }
+    t.end = j - 1
+    if (!t.status) t.status = t.checked ? "done" : "pending"
+    tasks.push(t)
+  }
+
+  return {
+    goal,
+    constraints: raw(sections, "Constraints"),
+    decisions: raw(sections, "Decisions"),
+    risks: raw(sections, "Risks"),
+    tasks,
+  }
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} idx
+ * @param {string} name
+ * @returns {boolean}
+ */
+function inSection(lines, idx, name) {
+  for (let i = idx; i >= 0; i--) {
+    const h = lines[i].match(headingRe)
+    if (h) return h[1] === name
+  }
+  return false
+}
+
+/**
+ * @param {Record<string, string[]>} sections
+ * @param {string} name
+ * @returns {string}
+ */
+function raw(sections, name) {
+  return (sections[name] ?? []).join("\n").trim()
+}
+
+/**
+ * The next task the loop is allowed to touch. Blocked work is never retried.
+ *
+ * @param {TaskFile} parsed
+ * @returns {Task | null}
+ */
+export function nextPending(parsed) {
+  return parsed.tasks.find((t) => !isDone(t) && !isBlocked(t)) ?? null
+}
+
+/** @param {Task} t */
+export const isDone = (t) => t.checked || t.status === "done"
+
+/** @param {Task} t */
+export const isBlocked = (t) => t.status === "blocked"
+
+/**
+ * Record the outcome of a task: flip the checkbox, set the status, and paste the
+ * verify output that was actually observed.
+ *
+ * The verify text is written under the `verify:` line rather than replacing it,
+ * because the contract asks for the command and the real output together.
+ *
+ * @param {string} text
+ * @param {Task} task
+ * @param {{ status: string, verifyOutput?: string }} outcome
+ * @returns {string}
+ */
+export function markTask(text, task, { status, verifyOutput }) {
+  const lines = String(text).split("\n")
+  const boxLine = lines[task.start] ?? ""
+  lines[task.start] = boxLine.replace(
+    /^\s*-\s*\[[ xX]\]/,
+    status === "done" ? "- [x]" : "- [ ]",
+  )
+
+  let statusLine = -1
+  for (let i = task.start; i <= task.end + 1 && i < lines.length; i++) {
+    const f = lines[i]?.match(fieldRe)
+    if (f && f[1] === "status") {
+      statusLine = i
+      break
+    }
+  }
+  if (statusLine >= 0) lines[statusLine] = lines[statusLine].replace(
+    /(\s-\s+status\s*:).*$/,
+    `$1 ${status}`,
+  )
+
+  if (verifyOutput) {
+    let verifyLine = -1
+    for (let i = task.start; i <= task.end + 1 && i < lines.length; i++) {
+      const f = lines[i]?.match(fieldRe)
+      if (f && f[1] === "verify") {
+        verifyLine = i
+        break
+      }
+    }
+    const verifySource = verifyLine >= 0 ? lines[verifyLine] : undefined
+    if (verifySource) {
+      const indent = (verifySource.match(/^\s*/) ?? [""])[0] + "  "
+      const quoted = String(verifyOutput)
+        .trimEnd()
+        .split("\n")
+        .map((l) => `${indent}${l}`)
+      lines.splice(verifyLine + 1, 0, ...quoted)
+    }
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * One task rendered as the prompt handed to the agent that will do it.
+ *
+ * @param {Task} task
+ * @returns {string}
+ */
+export function taskPrompt(task) {
+  const out = [task.title]
+  if (task.files) out.push("", `Files: ${task.files}`)
+  if (task.change) out.push("", `Change: ${task.change}`)
+  if (task.verify) out.push("", `Verify: ${task.verify}`)
+  return out.join("\n")
+}
+
+/**
+ * The summary the driver prints when it stops, whatever stopped it.
+ *
+ * @param {TaskFile} parsed
+ * @returns {{ done: number, blocked: number, pending: number, total: number }}
+ */
+export function summarize(parsed) {
+  const done = parsed.tasks.filter(isDone).length
+  const blocked = parsed.tasks.filter(isBlocked).length
+  const pending = parsed.tasks.filter((t) => !isDone(t) && !isBlocked(t)).length
+  return { done, blocked, pending, total: parsed.tasks.length }
+}

package/docs/demo/render.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""Render the space-harness demo video from REAL CLI output.
-
-Nothing here is typed by hand: the script runs `init` and `verify` against a
-throwaway config dir, captures what the CLI actually prints, and draws that.
-The only cosmetic edit is replacing the random tmp path with
-~/.config/opencode so the frames stay readable.
-"""
-import os
-import re
-import subprocess
-import sys
-import tempfile
-
-from PIL import Image, ImageDraw, ImageFont
-
-REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))  # docs/demo/render.py -> repo root
-ROOT = REPO
-BIN = ["node", os.path.join(ROOT, "bin", "oc-harness.mjs")]
-W, H = 1280, 720
-FPS = 15
-FONT = ImageFont.truetype("/System/Library/Fonts/Menlo.ttc", 22)
-LINE_H = 34
-TOP = 40
-LEFT = 48
-BG = (13, 17, 23)
-WHITE = (230, 237, 243)
-GREEN = (63, 185, 80)
-DIM = (139, 148, 158)
-YELLOW = (210, 153, 34)
-RED = (248, 81, 73)
-
-ANSI = re.compile(r"\x1b\[(\d+)m")
-
-
-def run_clip(args, cfg):
-    env = dict(os.environ, OPENCODE_CONFIG_DIR=cfg)
-    p = subprocess.run(BIN + args, capture_output=True, text=True, env=env, cwd=ROOT)
-    assert p.returncode == 0, p.stderr[-2000:]
-    out = (p.stdout + p.stderr).replace(cfg, "~/.config/opencode")
-    return [ln.rstrip() for ln in out.splitlines()]
-
-
-def spans(line):
-    """Split an ANSI-coloured line into (text, colour) runs."""
-    runs, cur, buf = [], WHITE, ""
-    pos = 0
-    for m in ANSI.finditer(line):
-        if m.start() > pos:
-            buf += line[pos : m.start()]
-        code = m.group(1)
-        if buf:
-            runs.append((buf, cur))
-            buf = ""
-        cur = {"0": WHITE, "1": WHITE, "2": DIM, "31": RED, "32": GREEN, "33": YELLOW}.get(code, WHITE)
-        pos = m.end()
-    if pos < len(line):
-        buf += line[pos:]
-    if buf:
-        runs.append((buf, cur))
-    return runs or [("", WHITE)]
-
-
-def draw_terminal(draw, lines, prompt="$ "):
-    draw.rectangle([0, 0, W, H], fill=BG)
-    maxl = (H - TOP) // LINE_H
-    if len(lines) > maxl:
-        head = [lines[0]] if lines[0][0] == "cmd" else []
-        lines = head + [ln for ln in lines if ln[0] != "cmd"][-(maxl - len(head)) :]
-    y = TOP
-    for kind, payload in lines:
-        if y > H - LINE_H:
-            break
-        if kind == "cmd":
-            draw.text((LEFT, y), prompt, font=FONT, fill=GREEN)
-            x = LEFT + draw.textlength(prompt, font=FONT)
-            for text, colour in spans(payload):
-                draw.text((x, y), text, font=FONT, fill=colour)
-                x += draw.textlength(text, font=FONT)
-        elif kind == "card":
-            text, colour = payload
-            draw.text((LEFT, y), text, font=FONT, fill=colour)
-        else:
-            x = LEFT
-            for text, colour in spans(payload):
-                draw.text((x, y), text, font=FONT, fill=colour)
-                x += draw.textlength(text, font=FONT)
-        y += LINE_H
-
-
-def frames_for_command(cmd, output):
-    frames = []
-    typed = ""
-    for ch in cmd:
-        typed += ch
-        frames.append([("cmd", typed)])
-    for i in range(0, len(output), 2):
-        frames.append([("cmd", cmd)] + [("out", ln) for ln in output[: i + 2]])
-    full = [("cmd", cmd)] + [("out", ln) for ln in output]
-    frames.extend([full] * (2 * FPS))
-    return frames
-
-
-def card(lines, hold=2):
-    return [[("card", ln) for ln in lines]] * (hold * FPS)
-
-
-def main(out_dir):
-    cfg = tempfile.mkdtemp(prefix="demo-")
-    init_out = run_clip(["init", "--profile", "space-bunny-free", "--yes"], cfg)
-    verify_out = run_clip(["verify"], cfg)
-    seq = []
-    seq += card([(("space-harness", WHITE)), (("one command from zero to working", DIM))], hold=2)
-    seq += frames_for_command("npx -y opencode-harness-kit init", [l for l in init_out if l.strip()])
-    seq += frames_for_command("oc-harness verify", [l for l in verify_out if l.strip()])
-    seq += card(
-        [
-            (("done. restart opencode, then ask it something", GREEN)),
-            (("github.com/crytobot459/space-harness", WHITE)),
-            (("free models. verified setup.", DIM)),
-        ],
-        hold=3,
-    )
-    os.makedirs(out_dir, exist_ok=True)
-    frame_dir = tempfile.mkdtemp(prefix="frames-")
-    for i, lines in enumerate(seq):
-        flat = []
-        for kind, payload in lines:
-            flat.append((kind, payload))
-        img = Image.new("RGB", (W, H), BG)
-        draw_terminal(ImageDraw.Draw(img), flat)
-        img.save(os.path.join(frame_dir, f"f{i:04d}.png"))
-    mp4 = os.path.join(out_dir, "demo.mp4")
-    subprocess.run(
-        ["ffmpeg", "-y", "-v", "error", "-framerate", str(FPS), "-i", os.path.join(frame_dir, "f%04d.png"),
-         "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "23", mp4], check=True)
-    gif = os.path.join(out_dir, "demo.gif")
-    subprocess.run(
-        ["ffmpeg", "-y", "-v", "error", "-framerate", "10", "-i", os.path.join(frame_dir, "f%04d.png"),
-         "-vf", "scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=64[p];[s1][p]paletteuse",
-         gif], check=True)
-    print(f"wrote {mp4} ({os.path.getsize(mp4)//1024}KB) and {gif} ({os.path.getsize(gif)//1024}KB)")
-
-
-if __name__ == "__main__":
-    main(sys.argv[1] if len(sys.argv) > 1 else os.path.join(ROOT, "docs", "demo"))