feat(iso-harness): emit opencode-model-fallback.json from iso/config.json

Add optional top-level `opencodeModelFallback` on `iso/config.json`. When
present, the OpenCode emitter writes `.opencode/opencode-model-fallback.json`
verbatim so `@razroo/opencode-model-fallback` picks up global
`fallback_models`, custom `retryable_error_patterns`, cooldowns, etc.
without merging unknown keys into `opencode.json`.

Validates the field is a plain object. Documented in README + CHANGELOG.
Tests cover happy path and schema rejection.

Bumps @razroo/iso-harness to 0.6.1.

Made-with: Cursor

Author: CharGrnmn

package-lock.json

@@ -1,5 +1,19 @@
 # @razroo/iso-harness
 
+## 0.6.1
+
+### Patch Changes
+
+- Emit `.opencode/opencode-model-fallback.json` when `iso/config.json`
+  defines a top-level `opencodeModelFallback` object.
+
+  This is the on-disk config shape consumed by
+  `@razroo/opencode-model-fallback` (retryable error patterns, global
+  `fallback_models`, cooldowns, etc.). Keeping it in `iso/` means
+  `iso-harness build` fans it out with the rest of the OpenCode target
+  instead of hand-maintaining a generated path outside the harness
+  source tree.
+
 ## 0.6.0
 
 ### Minor Changes

packages/iso-harness/CHANGELOG.md

@@ -13,8 +13,9 @@ iso/                              →  CLAUDE.md                    (Claude Code
 ├── agents/                          .mcp.json
 │   └── researcher.md             →  AGENTS.md                    (Codex + OpenCode)
 └── commands/                        .codex/config.toml
-    └── review.md                    .opencode/agents/*.md
+    └── review.md                                                         .opencode/agents/*.md
                                      .opencode/skills/*.md
+                                     .opencode/opencode-model-fallback.json  (optional; from `opencodeModelFallback` in iso/config.json)
                                      opencode.json
                                   →  .cursor/rules/*.mdc          (Cursor)
                                      .cursor/mcp.json
@@ -50,6 +51,7 @@ iso-harness build --watch                 # rebuild on every change under iso/
 ```
 iso/
 ├── instructions.md       # root prompt → CLAUDE.md / AGENTS.md / .cursor/rules/main.mdc
+├── config.json           # optional — targets.* merges + opencodeModelFallback file emit
 ├── mcp.json              # shared MCP server definitions
 ├── agents/               # subagents
 │   └── <slug>.md         # YAML frontmatter + body
@@ -138,6 +140,11 @@ explicit hatches keep harness-specific features possible:
    harness config (not per-item). Keys under `targets.opencode` are
    merged into the generated `opencode.json` — use this for OpenCode's
    top-level `instructions: [...]` array, for example.
+4. **`iso/config.json` top-level `opencodeModelFallback`** — JSON object
+   written verbatim to `.opencode/opencode-model-fallback.json` for the
+   [`@razroo/opencode-model-fallback`](https://www.npmjs.com/package/@razroo/opencode-model-fallback)
+   plugin (`retryable_error_patterns`, global `fallback_models`, etc.).
+   OpenCode-only; other harnesses ignore it.
 
 ```json
 // iso/config.json
@@ -146,13 +153,18 @@ explicit hatches keep harness-specific features possible:
     "opencode": {
       "instructions": ["templates/states.yml"]
     }
+  },
+  "opencodeModelFallback": {
+    "cooldown_seconds": 60,
+    "retryable_error_patterns": ["(?i)venice.*insufficient"],
+    "fallback_models": ["openrouter/openai/gpt-oss-120b:free"]
   }
 }
 ```
 
-For features with no cross-harness analogue (Claude Code hooks, OpenCode
-`fallback_models`), edit the generated file or add a separate post-build
-step — don't force them into the neutral source.
+Per-agent OpenCode `fallback_models` still belong in agent frontmatter
+under `targets.opencode`. Use `opencodeModelFallback` only for the
+**global** plugin file OpenCode loads from `.opencode/`.
 
 ## Composition with `@razroo/iso-route`
 

packages/iso-harness/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@razroo/iso-harness",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "One config for every coding agent — Cursor, Claude Code, Codex, OpenCode.",
   "type": "module",
   "bin": {

packages/iso-harness/package.json

@@ -125,5 +125,14 @@ export async function emitOpenCode(src, outDir, opts = {}) {
     await push(opencodeJsonPath, output, writeJson);
   }
 
+  // Optional @razroo/opencode-model-fallback plugin config — emitted as its
+  // own file so OpenCode picks it up without polluting opencode.json. Source
+  // of truth lives next to other harness config in iso/config.json.
+  const modelFallback = src.config?.opencodeModelFallback;
+  if (modelFallback != null) {
+    const p = path.join(outDir, '.opencode', 'opencode-model-fallback.json');
+    await push(p, JSON.stringify(modelFallback, null, 2) + '\n');
+  }
+
   return written;
 }

packages/iso-harness/src/targets/opencode.mjs

@@ -157,6 +157,16 @@ export function validateConfig(config, file = 'iso/config.json') {
       }
     }
   }
+  if (config.opencodeModelFallback !== undefined) {
+    if (!isPlainObject(config.opencodeModelFallback)) {
+      diags.push({
+        severity: 'error',
+        file,
+        field: 'opencodeModelFallback',
+        message: `"opencodeModelFallback" must be a JSON object (plugin config for .opencode/opencode-model-fallback.json)`,
+      });
+    }
+  }
   return diags;
 }
 

packages/iso-harness/src/validate.mjs

@@ -117,6 +117,40 @@ test('loadSource: throws a clear error when mcp.json has no servers object', asy
   await assert.rejects(() => loadSource(iso), /top-level "servers" object/);
 });
 
+test('build: opencode target writes opencode-model-fallback.json from opencodeModelFallback', async () => {
+  const { iso, out } = mkIso();
+  writeFileSync(
+    join(iso, 'config.json'),
+    JSON.stringify(
+      {
+        opencodeModelFallback: {
+          cooldown_seconds: 1,
+          retryable_error_patterns: ['(?i)venice'],
+          fallback_models: ['openrouter/openai/gpt-oss-20b:free'],
+        },
+      },
+      null,
+      2,
+    ),
+  );
+  await build({ source: iso, out, targets: ['opencode'] });
+  const p = join(out, '.opencode', 'opencode-model-fallback.json');
+  assert.ok(existsSync(p));
+  const got = JSON.parse(readFileSync(p, 'utf8'));
+  assert.equal(got.cooldown_seconds, 1);
+  assert.deepEqual(got.retryable_error_patterns, ['(?i)venice']);
+  assert.deepEqual(got.fallback_models, ['openrouter/openai/gpt-oss-20b:free']);
+});
+
+test('build: rejects opencodeModelFallback when not a plain object', async () => {
+  const { iso, out } = mkIso();
+  writeFileSync(join(iso, 'config.json'), JSON.stringify({ opencodeModelFallback: [] }));
+  await assert.rejects(
+    () => build({ source: iso, out, targets: ['opencode'] }),
+    /opencodeModelFallback/,
+  );
+});
+
 test('build: rendered CLAUDE.md preserves the instructions file verbatim (plus trailing newline)', async () => {
   const { iso, out } = mkIso({ instructions: '# My project\n\nRule 1.\nRule 2.' });
   await build({ source: iso, out, targets: ['claude'] });