opencode-turnstile 0.2.0 → 0.2.5

package/bin/cli.mjs

@@ -7,9 +7,14 @@
 //
 //   opencode-turnstile init       Install/sync artifacts into ~/.config/opencode
 //   opencode-turnstile check      Verify artifacts against the manifest
-//   opencode-turnstile uninstall  Remove installed artifacts (agents + block)
+//   opencode-turnstile uninstall  Remove installed artifacts (manifest artifacts)
+//   opencode-turnstile status     Report gate/plan state from the JSONL journal
 //   opencode-turnstile version    Print the installed package version
 //
+// `init -- --print-model-config` writes nothing: the router runs install.mjs,
+// which prints the snippet and short-circuits before any install work, so the
+// router returns install.mjs's exit code verbatim.
+//
 // Unknown subcommand or no args prints usage and exits 2.
 
 import { spawn } from "node:child_process"
@@ -20,14 +25,19 @@ import { fileURLToPath } from "node:url"
 const here = dirname(fileURLToPath(import.meta.url))
 const repoRoot = resolve(here, "..")
 const installScript = join(repoRoot, "scripts/install.mjs")
-const agentsScript = join(repoRoot, "scripts/install-agents.mjs")
+const statusScript = join(repoRoot, "scripts/status.mjs")
 
 const USAGE = `Usage: opencode-turnstile <command>
 
 Commands:
   init      Install or sync artifacts into ~/.config/opencode
+            (with --print-model-config, prints a {"agents": {...}} snippet and writes nothing)
   check     Verify installed artifacts against the manifest
-  uninstall Remove installed artifacts (agents + block)
+            (check --repair prints which targets would be auto-repaired,
+             writing nothing — a dry run of the --repair apply mode)
+  uninstall Remove installed artifacts (manifest artifacts)
+  status    Report per-session gate/plan state from the journal
+            (status --json prints machine-readable JSON; read-only, nothing is written)
   version   Print the installed package version
 
 init also accepts convenience flags (passthrough to scripts/install.mjs); separate them from the subcommand with a leading "--":
@@ -63,40 +73,42 @@ async function main() {
 
   switch (command) {
     case "init": {
-      // Full install: manifest artifacts (plugin + agents), then the
-      // managed contract block in ~/.config/opencode/AGENTS.md, mirroring
-      // uninstall's two-step shape in reverse. Passthrough flags go to the
-      // manifest installer; the agents installer needs none of them.
+      // Full install: manifest artifacts (plugin + agents) via a single
+      // install.mjs spawn. This installer never writes to AGENTS.md — the
+      // legacy contract-block installer was deleted (R1); any pre-existing
+      // block is removed by hand by the user, not by npm/init.
       //
-      // --print-model-config is passthrough too: install.mjs prints the
-      // snippet and short-circuits before any manifest work, but the router
-      // still runs BOTH steps, so the contract block is idempotently
-      // installed as usual. Print mode writes nothing; the two-step install
-      // is the router's idempotent contract-block behavior, which is out of
-      // scope for the write-free printer flag.
+      // Printer-mode short-circuit: --print-model-config makes init write
+      // completely free. install.mjs prints the snippet and short-circuits
+      // before any manifest work, so the router returns install.mjs's exit
+      // code verbatim. This is what makes "print mode writes nothing"
+      // literally true.
       //
       // A leading "--" separates the subcommand from its flags
       // (`init -- --print-model-config`); install.mjs rejects a literal "--"
       // as an unknown argument, so drop it before forwarding.
       const initPassthrough = passthrough[0] === "--" ? passthrough.slice(1) : passthrough
-      const byInstall = await spawnInstaller(installScript, initPassthrough)
-      const byAgents = await spawnInstaller(agentsScript, [])
-      return process.exit(byInstall || byAgents ? 1 : 0)
+      return process.exit(await spawnInstaller(installScript, initPassthrough))
     }
     case "check":
       return spawnInstaller(installScript, ["--check", ...passthrough])
     case "uninstall": {
-      // Reverse the copy/symlink install, then unmerge the managed block.
-      // Inherited stdio surfaces both scripts' reports verbatim; exit non-zero
-      // only if either step failed. No restart note is printed here; each
-      // child prints its own, gated on whether it changed anything.
+      // Reverse the copy/symlink install via a single install.mjs spawn.
+      // Inherited stdio surfaces the report verbatim; exit non-zero only if
+      // it failed. No restart note is printed here; the child prints its own,
+      // gated on whether it changed anything.
       const byInstall = await spawnInstaller(installScript, ["--uninstall"])
-      const byAgents = await spawnInstaller(agentsScript, ["--remove"])
-      return process.exit(byInstall || byAgents ? 1 : 0)
+      return process.exit(byInstall ? 1 : 0)
     }
     case "version":
       console.log(JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version)
       return
+    case "status": {
+      // Read-only status surface over the JSONL journal: spawn scripts/status.mjs
+      // with passthrough args (mirrors the init case's leading-"--" stripping).
+      const statusPassthrough = passthrough[0] === "--" ? passthrough.slice(1) : passthrough
+      return process.exit(await spawnInstaller(statusScript, statusPassthrough))
+    }
     default:
       console.log(USAGE)
       process.exit(2)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-turnstile",
-  "version": "0.2.0",
-  "description": "OpenCode plugin that mechanically enforces agent pipeline gates (planner → executor → test-runner → reviewer)",
+  "version": "0.2.5",
+  "description": "OpenCode plugin that mechanically enforces an agent pipeline (planner → plan-reviewer → executor → test-runner → reviewer) for OpenCode",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -13,7 +13,6 @@
     "scripts",
     "bin",
     "install.json",
-    "templates",
     "skills",
     "agents",
     "README.md",
@@ -26,16 +25,16 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "check:markers": "node scripts/check-markers.mjs",
-    "test": "node --test --experimental-strip-types tests/*.test.ts",
+    "test": "node --test --experimental-strip-types --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-include='**/src/**' --test-coverage-include='**/turnstile.ts' tests/*.test.ts",
     "init": "node scripts/install.mjs",
     "init:copy": "node scripts/install.mjs --copy",
     "init:check": "node scripts/install.mjs --check",
     "install:copy": "node scripts/install.mjs --copy",
     "install:check": "node scripts/install.mjs --check",
-    "install:agents": "node scripts/install-agents.mjs",
     "pack:dry": "npm pack --dry-run",
     "ci:host": "npm run lint && npm run format:check && npm run typecheck && npm run check:markers && npm test",
-    "ci": "npm run ci:host && npm run install:check"
+    "ci": "npm run ci:host",
+    "ci:installed": "npm run install:check"
   },
   "repository": {
     "type": "git",

package/scripts/branch-coverage.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Branch-level coverage reporter for the turnstile test suite.
+ *
+ * Node's built-in coverage report prints percentages and uncovered *lines*
+ * only; the raw V8 JSON (via `NODE_V8_COVERAGE`) carries per-function *block*
+ * ranges whose zero counts pinpoint exactly which decision never executed —
+ * coverage.py-style arc diagnosis, derived from V8 block data.
+ *
+ * Usage: `node scripts/branch-coverage.mjs [test-file ...]`
+ * Runs each test file in its own child process (the same per-file isolation
+ * `node --test` uses) with `NODE_V8_COVERAGE` pointed at a shared temp dir,
+ * merges the V8 JSON across children, and prints every never-executed block
+ * inside a function that DID run, as `file:line:col-line` plus a snippet.
+ * Exit 0 always — this is a diagnostic, not a gate.
+ *
+ * Merge semantics (the non-obvious part — learned the hard way):
+ * - A function instance is identified by `(functionName, root range)`; the
+ *   same closure re-recorded in several children merges into one entry.
+ * - V8 may record DIFFERENT block granularity for the same function across
+ *   children (optimization feedback differs per run), so ranges merge by
+ *   exact `(startOffset, endOffset)` span with max count. Never spread a
+ *   coarse count across a finer record's blocks: a parent range's count is
+ *   the *function/block entry* count, not evidence that nested blocks ran.
+ * - A merged zero block is only reported when no child has a POSITIVE range
+ *   contained within it (code inside it demonstrably ran somewhere). Coarse
+ *   zero spans that contain proven-covered sub-blocks are pruned — they are
+ *   lumping artifacts, not branch evidence. This fails toward less noise.
+ * - Functions whose root never ran in any child are skipped (they show as
+ *   uncovered lines in the standard report anyway).
+ */
+
+import { spawnSync } from "node:child_process"
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+/** Builds per-file line-offset tables for snippet and position rendering. */
+function loadSources(files) {
+  const sources = {}
+  for (const file of files) {
+    try {
+      const text = readFileSync(file, "utf8")
+      const offsets = []
+      let off = 0
+      for (const line of text.split("\n")) {
+        offsets.push(off)
+        off += line.length + 1
+      }
+      sources[file] = { text, offsets }
+    } catch {
+      /* covered file may be outside this checkout; leave unknown */
+    }
+  }
+  return sources
+}
+
+/** Converts a character offset to a `line:col` string via the offsets table. */
+function toPos(source, offset) {
+  let lo = 0
+  let hi = source.offsets.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (source.offsets[mid] <= offset) lo = mid
+    else hi = mid - 1
+  }
+  return `${lo + 1}:${offset - source.offsets[lo] + 1}`
+}
+
+/** Converts a character offset to a 1-based line number. */
+function toLine(source, offset) {
+  return Number(toPos(source, offset).split(":")[0])
+}
+
+const args = process.argv.slice(2)
+const testFiles = args.filter((a) => !a.startsWith("--"))
+const files = testFiles.length
+  ? testFiles
+  : readdirSync("tests")
+      .filter((f) => f.endsWith(".test.ts"))
+      .map((f) => `tests/${f}`)
+const covDir = mkdtempSync(join(tmpdir(), "branch-cov-"))
+
+// One child per test file — exactly how `node --test` runs them — so module
+// state isolation matches the real suite and the union over children is the
+// same union the standard report computes. All children share one
+// NODE_V8_COVERAGE dir; records are merged below.
+let failures = 0
+for (const file of files) {
+  const result = spawnSync(
+    process.execPath,
+    ["--test", "--experimental-strip-types", "--experimental-test-coverage", file],
+    {
+      env: { ...process.env, NODE_V8_COVERAGE: covDir },
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    },
+  )
+  if (result.status !== 0) {
+    failures++
+    console.error(`${file}: child exited ${result.status}`)
+  }
+}
+
+const records = readdirSync(covDir).map((f) => JSON.parse(readFileSync(join(covDir, f), "utf8")))
+rmSync(covDir, { recursive: true, force: true })
+
+/** Normalizes a V8 URL to a filesystem path. */
+const toFile = (url) => url.replace(/^file:\/\//, "")
+
+/**
+ * Merges one child's ranges into the accumulated span→maxCount map by exact
+ * span. Identical spans across children take the max count (a block executed
+ * in any child is covered); spans unique to one child are that child's own
+ * block structure and are kept for the containment pruning pass.
+ * @param acc The accumulated `Map<"start:end", { startOffset, endOffset, count }>` for a function.
+ * @param incoming One child's range list for that function.
+ */
+function mergeRanges(acc, incoming) {
+  for (const r of incoming) {
+    const key = `${r.startOffset}:${r.endOffset}`
+    const prior = acc.get(key)
+    if (prior) prior.count = Math.max(prior.count, r.count)
+    else acc.set(key, { ...r })
+  }
+}
+
+/** Merges all records: url → (function key → span map). */
+const scripts = new Map()
+for (const record of records) {
+  for (const entry of record.result) {
+    if (!entry.functions) continue
+    let script = scripts.get(entry.url)
+    if (!script) {
+      script = new Map()
+      scripts.set(entry.url, script)
+    }
+    for (const fn of entry.functions) {
+      if (!fn.ranges) continue
+      const key = `${fn.functionName}@${fn.ranges[0].startOffset}`
+      const prior = script.get(key)
+      if (!prior) {
+        const spans = new Map()
+        const positives = []
+        for (const r of fn.ranges) {
+          const k = `${r.startOffset}:${r.endOffset}`
+          spans.set(k, { ...r })
+          if (r.count > 0 && r !== fn.ranges[0]) positives.push({ ...r })
+        }
+        script.set(key, { spans, positives })
+      } else {
+        mergeRanges(prior.spans, fn.ranges)
+        for (const r of fn.ranges) {
+          if (r.count > 0 && r !== fn.ranges[0]) prior.positives.push({ ...r })
+        }
+      }
+    }
+  }
+}
+
+const sources = loadSources([...scripts.keys()].map(toFile))
+const findings = []
+for (const [url, fns] of scripts) {
+  const file = toFile(url)
+  if (!/\/src\//.test(file) && !file.endsWith("turnstile.ts")) continue
+  const source = sources[file]
+  if (!source) continue
+  for (const [key, { spans, positives }] of fns) {
+    const root = [...spans.values()].find(
+      (s) => s.startOffset === Math.min(...[...spans.values()].map((v) => v.startOffset)),
+    )
+    if (!root || root.count === 0) continue // whole function never ran in any child
+    for (const span of spans.values()) {
+      if (span.count !== 0) continue
+      // Prune lumping artifacts: a zero span that CONTAINS a proven-covered
+      // sub-range from another child is not branch evidence.
+      const containedPositive = positives.some(
+        (p) =>
+          p.startOffset >= span.startOffset &&
+          p.endOffset <= span.endOffset &&
+          !(p.startOffset === span.startOffset && p.endOffset === span.endOffset),
+      )
+      if (containedPositive) continue
+      const start = toPos(source, span.startOffset)
+      const endLine = toLine(source, span.endOffset)
+      const snippet = source.text.slice(span.startOffset, span.startOffset + 80).split("\n")[0]
+      findings.push({ file, key: key.split("@")[0], start, endLine, snippet })
+    }
+  }
+}
+findings.sort(
+  (a, b) =>
+    a.file.localeCompare(b.file) || a.start.localeCompare(b.start, undefined, { numeric: true }),
+)
+
+console.log(`tests: ${files.length} files, child failures=${failures}`)
+if (findings.length === 0) {
+  console.log("branch coverage: every executed function's blocks are covered")
+} else {
+  console.log(`uncovered blocks: ${findings.length}`)
+  for (const f of findings) {
+    console.log(
+      `  ${f.file.replace(/^.*turnstile\//, "")}:${f.start}-${f.endLine}  [${f.key}]  ${f.snippet}`,
+    )
+  }
+}

package/scripts/check-markers.mjs

@@ -64,6 +64,28 @@ if (agentTemplates === 0) {
   failed++
 }
 
+// Plugin policy: the backticked GATE:/VERDICT: examples in src/policy.ts are
+// the orchestrator-side half of the marker contract — the runtime policy
+// injected into the parent session. Same extraction rule as the agent
+// templates: they spell <n> and must parse once the placeholder stands in
+// for digits. (The template source that once lived here for this contract is
+// gone; src/policy.ts is its successor, so its examples are validated too.)
+const policyFile = join(root, "src", "policy.ts")
+let policyTemplates = 0
+for (const m of readFileSync(policyFile, "utf8").matchAll(/`((?:GATE|VERDICT): [^\n`]*)`/g)) {
+  const line = m[1].replaceAll("<n>", "1")
+  const re = line.startsWith("GATE") ? gateRe : verdictRe
+  policyTemplates++
+  if (!re.test(line)) {
+    console.error(`check-markers: policy marker template not accepted by parser: ${line}`)
+    failed++
+  }
+}
+if (policyTemplates === 0) {
+  console.error("check-markers: no marker templates found in src/policy.ts")
+  failed++
+}
+
 // Inverse check: the regexes must also reject malformed markers.
 for (const [re, bad] of [
   [gateRe, "GATE: PASS tests=12"],
@@ -82,5 +104,5 @@ if (failed) {
   process.exit(1)
 }
 console.log(
-  `check-markers: OK (${lines.length} README examples, ${agentTemplates} agent templates verified against parser)`,
+  `check-markers: OK (${lines.length} README examples, ${agentTemplates} agent + ${policyTemplates} policy templates verified against parser)`,
 )

package/scripts/install.mjs

@@ -7,14 +7,23 @@
 //
 // Usage:
 //   node scripts/install.mjs [--manifest <path>] [--check] [--force]
-//                            [--uninstall] [--link | --copy]
+//                            [--uninstall] [--link | --copy] [--repair]
 //
-//   --manifest     Manifest to install (default: install.json at the repo root)
-//   --check        Verify all targets without writing; exit 1 on drift
+//   --manifest     Manifest to install (default: install.json at the repo root).
+//                  Missing value, or a `--`-prefixed next token, exits 2 here
+//                  ("requires a path") rather than crashing downstream.
+//   --check        Verify all targets without writing; exit 1 on drift. With
+//                  --repair, reportable drift is printed as `would repair`
+//                  (write-free dry run) instead of failing.
 //   --force        Convert conflicting targets after backing them up
 //   --uninstall    Reverse the manifest: remove repo-owned links / ledger-owned
 //                  copies for every entry (then retire leftovers); exit 1 only
 //                  when something could not be removed (conflict/unowned).
+//   --repair       Apply-mode: relink/copy each repairable entry (`missing`/`stale`
+//                  link-mode; `missing`/ledger-`stale` copy-mode) via the same
+//                  path as install, print `install: repair <dest> (<code>)`,
+//                  exit 1 only if something unrepairable remains. `conflict`
+//                  stays gated behind --force (no unprompted backup).
 //   --link/--copy  Override the mode. Resolution: CLI flag > manifest "mode"
 //                  field > auto-detect (.git present => link, else copy)
 //
@@ -78,7 +87,7 @@ try {
 /**
  * Parses command-line arguments.
  * @param {string[]} argv Raw argv (process.argv).
- * @returns {{manifest: string, check: boolean, force: boolean, uninstall: boolean, mode: "link"|"copy"|null, model: string[], printModelConfig: boolean, validate: boolean, modelSpecs: Record<string,string>}} Parsed arguments. A `--model`/`--validate` without `--print-model-config` is an error and exits 2 (checked before any parsing or I/O). Model specs are validated here only when the printer flag is set; a malformed or unknown-name spec prints an actionable message and exits 2 (matching the unknown-arg contract), and the parsed map is stashed as `modelSpecs` for `main`.
+ * @returns {{manifest: string, check: boolean, force: boolean, uninstall: boolean, mode: "link"|"copy"|null, model: string[], printModelConfig: boolean, validate: boolean, modelSpecs: Record<string,string>, repair: boolean}} Parsed arguments. A `--model`/`--validate` without `--print-model-config` is an error and exits 2 (checked before any parsing or I/O). Model specs are validated here only when the printer flag is set; a malformed or unknown-name spec prints an actionable message and exits 2 (matching the unknown-arg contract), and the parsed map is stashed as `modelSpecs` for `main`. A missing or flag-shaped value for `--manifest` or `--model` also exits 2 at the assignment site, naming the offending flag (so neither path reaches a late fs parse-crash).
  */
 function parseArgs(argv) {
   const args = {
@@ -91,15 +100,29 @@ function parseArgs(argv) {
     printModelConfig: false,
     validate: false,
     modelSpecs: {},
+    repair: false,
   }
   for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--manifest") args.manifest = argv[++i]
-    else if (argv[i] === "--check") args.check = true
+    if (argv[i] === "--manifest") {
+      const val = argv[++i]
+      if (val === undefined || val.startsWith("--")) {
+        console.error("install: --manifest requires a path")
+        process.exit(2)
+      }
+      args.manifest = val
+    } else if (argv[i] === "--check") args.check = true
     else if (argv[i] === "--force") args.force = true
     else if (argv[i] === "--uninstall") args.uninstall = true
     else if (argv[i] === "--link") args.mode = "link"
     else if (argv[i] === "--copy") args.mode = "copy"
-    else if (argv[i] === "--model") args.model.push(argv[++i])
+    else if (argv[i] === "--model") {
+      const val = argv[++i]
+      if (val === undefined || val.startsWith("--")) {
+        console.error("install: --model requires a spec")
+        process.exit(2)
+      }
+      args.model.push(val)
+    } else if (argv[i] === "--repair") args.repair = true
     else if (argv[i] === "--print-model-config") args.printModelConfig = true
     else if (argv[i] === "--validate") args.validate = true
     else {
@@ -475,6 +498,20 @@ async function inspectEntry(entry, mode, ledger) {
   return mode === "copy" ? inspectCopy(entry, ledger) : inspectLink(entry)
 }
 
+/**
+ * Decides whether a drift code is repairable by `--repair` without prompting.
+ * Link mode reports `missing`/`stale`; `inspectCopy` only returns `stale` for
+ * a ledger-recorded match, so the same predicate covers both modes. A
+ * `conflict` is deliberately excluded: repairing it would back up user files,
+ * which `--repair` must never do unprompted (that path stays gated behind
+ * `--force`).
+ * @param {string} code Drift code from `inspectEntry`.
+ * @returns {boolean} True when `--repair` would fix it.
+ */
+function isRepairable(code) {
+  return code === "missing" || code === "stale"
+}
+
 /**
  * Backs up a real file by renaming it aside with a timestamp suffix.
  * @param {string} dest Destination path to back up.
@@ -664,15 +701,72 @@ async function apply(manifest, args) {
   return { ok, changed }
 }
 
+/**
+ * Repairs repairable drift across every manifest entry, relinking `missing`
+ * /`stale` link-mode entries and re-copying `missing`/ledger-`stale` copy-mode
+ * entries via the same `installLink`/`installCopy` path `apply()` uses.
+ * `conflict` stays gated behind `--force`: `--repair` must never back up user
+ * files unprompted, so a conflict left without `--force` is reported as
+ * unrepairable and fails. Runs in apply mode; the `--check --repair` dry run
+ * is handled by `check()`.
+ * @param {{mode: "link"|"copy", ledgerPath: string, links: Array<{src: string, dest: string}>, retired: string[]}} manifest Validated manifest.
+ * @param {{force: boolean, repair: boolean}} args Parsed arguments.
+ * @returns {Promise<{ok: boolean, changed: boolean}>} Success flag and whether anything changed.
+ */
+async function repair(manifest, args) {
+  const ledger = loadLedger(manifest.ledgerPath)
+  let ok = true
+  let changed = false
+
+  for (const entry of manifest.links) {
+    const report = await inspectEntry(entry, manifest.mode, ledger)
+    if (report.code === "ok") {
+      console.log(`install: up to date ${entry.dest}`)
+      continue
+    }
+    // Conflict without --force, or an invalid (missing-source) entry, can not
+    // be repaired here: neither would back up user files or invent a source.
+    if (!isRepairable(report.code) && !args.force) {
+      ok = false
+      console.error(
+        `install: ${entry.dest} — ${report.code}${
+          report.detail ? `: ${report.detail}` : ""
+        } (unrepairable; rerun with --force for conflicts)`,
+      )
+      continue
+    }
+    try {
+      const result =
+        manifest.mode === "copy"
+          ? await installCopy(entry, args, ledger, pkgVersion, manifest.mode)
+          : await installLink(entry, args, ledger)
+      if (result.acted) {
+        changed = true
+        console.log(`install: repair ${entry.dest} (${report.code})`)
+      } else console.log(`install: up to date ${entry.dest}`)
+    } catch (error) {
+      ok = false
+      console.error(String(error.message ?? error))
+    }
+  }
+  saveLedger(manifest.ledgerPath, ledger)
+  return { ok, changed }
+}
+
 /**
  * Runs the installer in check mode: reports drift, writes nothing.
  * A ledger record whose version is older than the current package version
- * is reported as a warning and does not fail the check.
+ * is reported as a warning and does not fail the check. When `repairMode`
+ * is set (`--check --repair`), repairable drift (`missing`/`stale`) is
+ * reported as `would repair` instead of an error and does not fail the
+ * check (the entry is going to be fixed); unrepairable drift still fails
+ * as before. `check` alone (`repairMode` false) is byte-for-byte unchanged.
  * @param {{mode: "link"|"copy", ledgerPath: string, links: Array<{src: string, dest: string}>, retired: string[]}} manifest Validated manifest.
  * @param {string} version Current package version.
- * @returns {Promise<boolean>} True when no drift was found.
+ * @param {boolean} [repairMode] When true, report repairable drift as `would repair` rather than failing.
+ * @returns {Promise<boolean>} True when no unrepairable drift was found.
  */
-async function check(manifest, version) {
+async function check(manifest, version, repairMode = false) {
   const ledger = loadLedger(manifest.ledgerPath)
   let ok = true
   for (const entry of manifest.links) {
@@ -686,6 +780,8 @@ async function check(manifest, version) {
     if (record && record.version && record.version !== version)
       console.log(`check: outdated ${entry.dest} (installed ${record.version}, package ${version})`)
     if (report.code === "ok") console.log(`check: OK ${entry.dest}`)
+    else if (repairMode && isRepairable(report.code))
+      console.log(`install: would repair ${entry.dest} (${report.code})`)
     else {
       ok = false
       console.error(
@@ -710,8 +806,7 @@ async function main(argv = process.argv) {
   // optionally validates them against `opencode models`, prints a ready-to
   // paste snippet, and returns. This short-circuits before the manifest is
   // even read (like --check), so no link/copy target or ledger entry is
-  // touched. The router still idempotently installs the contract block
-  // separately; that is out of scope for this write-free flag.
+  // touched.
   if (args.printModelConfig) {
     if (args.validate) {
       let available
@@ -735,7 +830,12 @@ async function main(argv = process.argv) {
   console.log(
     `install: mode=${manifest.mode} (${manifest.mode === "link" ? "checkout" : "package"})`,
   )
-  if (args.check) return await check(manifest, pkgVersion)
+  if (args.check) return await check(manifest, pkgVersion, args.repair)
+  if (args.repair) {
+    const { ok, changed } = await repair(manifest, args)
+    if (changed) console.log("restart OpenCode sessions to pick up changes.")
+    return ok
+  }
   const { ok, changed } = await apply(manifest, args)
   if (changed) console.log("restart OpenCode sessions to pick up changes.")
   return ok