opencode-harness-kit 0.0.0-stage → 0.1.0

package/docs/KNOWN-LIMITS.md

@@ -0,0 +1,188 @@
+# Known limits
+
+Written down so nobody spends a day rediscovering them.
+
+## A global `permission.edit: "ask"` silently un-locks every read-only agent
+
+Worth knowing before you hand-edit the generated config, because the failure is
+invisible from the config itself.
+
+Two documented OpenCode behaviours combine badly:
+
+1. Permission rules are matched with **the last matching rule winning**.
+2. The **global** rule is appended *after* the agent's own rule.
+
+So an agent configured `edit: "deny"` under a global `permission.edit: "ask"`
+resolves to **ask**, not deny. The read-only roles can edit files, just not
+without a prompt. Confirmed on 1.18.35 with `opencode agent list`, which prints
+each agent's fully resolved rule list — for `plan` it showed `edit * deny`
+followed by `edit * ask`.
+
+The fix is counter-intuitive: set the global to `allow`. `allow` is the
+permissive *implicit default* and emits no rule at all, so each agent's `deny` is
+what decides. Verified after the change:
+
+```
+build      edit -> allow
+plan       edit -> deny
+locate     edit -> deny
+reviewer   edit -> deny
+verify     edit -> deny
+```
+
+Writes outside the project still ask, via `external_directory`.
+
+## Two schema keys this kit used to emit, and what they do instead
+
+The 1.18.35 `Config` schema sets `additionalProperties: false`, so an
+unrecognised top-level key is stripped from the resolved config rather than
+rejected. Two keys were being written that OpenCode throws away:
+
+- **`variant`** is not a top-level config key at all. It only exists on
+  `agent.<name>.variant`. Per-role tiering is delivered by those, and
+  `effort.js` sets the session default in the `config` hook where the runtime
+  still sees it. A test once asserted this key existed, which meant it was
+  asserting that dead config was present.
+- **`harness`** survives in the file but is not visible to the `config` hook, so
+  the plugin reads the profile id from the file on disk instead. That behaviour
+  is correct and `profile.js` documents it; `variant` had no such workaround and
+  was simply doing nothing.
+
+`oc-harness verify` fails on a top-level `variant` specifically, because it looks
+exactly like working tiering in a config you are reading.
+
+## A generated config is only half an install
+
+`use` writes `opencode.jsonc`. That file *points at* three other things: the
+instruction file in `instructions`, the agent files it declares per role, and the
+plugin that enforces the guard. All three can be absent while the config still
+validates and still looks correct — and, on a real install of this kit, all three
+were.
+
+The specific failure was invisible because `opencode agent list` simply does not
+print an agent that does not exist. A config declaring `reviewer`, `locate` and
+`verify` produced no error and no warning; the roles were invoked and quietly
+resolved to nothing.
+
+That is what `oc-harness install` and `oc-harness verify` exist for. Anything the
+compiler emits a reference to should have an installer and a checker; otherwise
+the generated file is a pointer to nothing.
+
+## Model failover happens at the next session, never mid-flight
+
+No OpenCode plugin hook can change the model of a running session. Verified by
+reading `Hooks` in `@opencode-ai/plugin@1.18.35`. The surface is 21 hooks; of
+the six that mention `model`, five read it as input and the sixth
+(`experimental.provider.small_model`) writes only the utility model, never the
+session's:
+
+| hook | can it change the model? |
+|---|---|
+| `chat.params` | No. Output is `temperature`, `topP`, `topK`, `maxOutputTokens`, `options`. |
+| `chat.message` | No. `model` and `variant` on the input are read-only. |
+| `experimental.provider.small_model` | Only the small model. |
+| `config` | Yes, but it runs once at startup. |
+| `provider` | Can add or override models in the catalog, not the active session. |
+
+So `router.ts` does two things instead of the obvious third: at startup it
+moves to the next healthy profile, and when a request fails it tells the agent
+plainly that a new session is the fix. It does not pretend to retry.
+
+The gap is real and tracked upstream. Provider issue #42977 asks Zen for a
+`scope` field and a remaining-quota figure on 429 responses, precisely because
+a client cannot currently tell a short quota window from a permanent block.
+
+## Retry on 429 is deliberately not attempted
+
+Zen free routes return `429 FreeUsageLimitError`, and #42977 documents models
+staying blocked for **10+ days** without recovery. The `Retry-After` header
+measured by the reporter points at 00:00 UTC, so the window is daily. The
+maintainers' own guidance is to mark the route unhealthy rather than retry.
+
+Retrying inside a session would burn turns against a wall. Marking it
+unhealthy and failing over at the next start is the honest behaviour.
+
+## Free models get withdrawn quickly
+
+From one install's 20-day history, free model slots turned over in days:
+
+| model | observed lifetime |
+|---|---|
+| `mimo-v2.5-free` | 1 day |
+| `big-pickle` | 1 day |
+| `nemotron-3-ultra-free` | 3 days |
+| `muse-spark-1.3-contributor-free` | still running at 20 days |
+
+Zen states free models are available "for a limited time" with no date. Treat
+profiles as perishable: run `oc-harness doctor`, which re-checks each profile
+against live metadata and reports drift.
+
+## A model-driven compressor is not assumed to work
+
+`@tarquinen/opencode-dcp` (4.3k stars) exposes a `compress` tool so the model
+chooses when to compact. That is a better design in principle, and it is
+AGPL-3.0, and it depends on a model remembering to call a tool.
+
+This kit targets models with weak instruction following, so `prune.ts` is
+deterministic and unconditional. If you want both, install DCP for its
+deduplication and purge-errors passes and let this handle the floor. Check
+whether its `compress` tool actually fires on your model before assuming it
+does; if it does not, `prune.ts` is doing the work anyway.
+
+## Pruning is an approximation
+
+`prune.ts` keeps pointers rather than bodies. Full tool output is not deleted
+from the session record, and OpenCode already writes over-cap output to its own
+truncation directory, so re-reading is possible. But "re-run the command to see
+it again" is more expensive than "scroll up". The stub is one line precisely so
+an agent can decide whether it is worth it, and the stub says so.
+
+A `savedBytes` of 0 in `prune.jsonl` is not a second, redundant pass. It means
+`bytesAfter` did not come out below `bytesBefore` for that turn, which happens
+when a stub is no shorter than the output it replaced (the stub's own label
+costs more than a short body), or when a `reasoning` part was under the 200
+byte floor and so was not shortened at all. These lines are still logged
+because a part was stubbed, which is the event worth recording. Savings
+aggregate correctly either way, since each line is measured independently.
+
+`baseline.mjs` measures permission pressure with its own glob approximation of
+OpenCode's matcher, not OpenCode's matcher. It handles the cases that matter
+(bare commands, embedded newlines) but a discrepancy in the last few percent is
+possible. Treat the ratio as a guide, not an exact count. It does import the
+real allowlist rather than keeping a copy, so the list cannot drift from what is
+actually shipped.
+
+## What this kit does not do
+
+It does not implement memory persistence, worktree orchestration, a context
+compressor, or a session UI. Those exist and are good:
+
+| need | use |
+|---|---|
+| model-driven compression | `@tarquinen/opencode-dcp` |
+| cross-harness context proxy | `sleev.ai` |
+| persistent memory | `opencode-supermemory` |
+| git worktrees | `kdcokenny/opencode-worktree` |
+| memory in git markdown | `code-yeongyu/oh-my-opencode` (now `omo`) |
+| agent DAGs | `spoons-and-mirrors/subtask2` |
+
+The gap this kit fills is the one between a provider catalog and a config file:
+capability and privacy metadata in, a working harness out, with a command to
+re-check that the metadata has not rotted.
+
+## Verification methodology
+
+Read
+[Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents](https://arxiv.org/abs/2609.00006)
+(arXiv:2609.00006) before extending this. It dissects eleven production
+harnesses along seven subsystems and catalogues 29 recurring patterns. Two of
+its findings shaped the design here:
+
+- No harness in the corpus uses embedding-based retrieval over code. Everything
+  runs on ripgrep, tree-sitter, glob, and auto-discovered markdown. An earlier
+  draft of this project proposed GraphRAG; that was wrong.
+- `syntax-aware command permissioning` is a named pattern, which is why
+  `guard.ts` splits on shell separators instead of matching a raw string.
+
+The paper's own advice applies: build these components knowing that some will
+stop being necessary as models improve.

package/docs/RESEARCH.md

@@ -0,0 +1,210 @@
+# Research notes
+
+Where the numbers came from, and what was tried and thrown away. The short
+version: most of the first draft of this project was wrong, and the corrections
+are more useful than the conclusions.
+
+## The measurement everything rests on
+
+One real install, 14 days, read out of `~/.local/share/opencode/opencode.db`.
+Reproduce with `npm run baseline`.
+
+```
+153 sessions · 11,750 assistant messages
+input 66.07M · output 3.00M · reasoning 1.45M · cache read 1358.49M
+cache read = 20.6x input
+recorded cost $0.40 · the same work on a paid route would be $53.36
+
+context per request   p50 99,648   p90 246,536   p99 482,779   max 547,986
+fresh input per request  p50 534
+compaction events     0
+
+stored message bytes
+  tool        114.78 MB   77.9%   (11,817 parts)
+  reasoning    22.94 MB   15.6%
+  text          3.04 MB    2.1%
+
+per model
+  muse-spark-1.3-contributor-free  xhigh   7,955 msgs  reasoning 31.9%  7.8s median
+  space-bunny-free                 max     2,684 msgs  reasoning 38.1%  18.7s median
+```
+
+Three conclusions:
+
+**Context is the cost.** Fresh input per request is 534 tokens; context per
+request is 99,648. Almost every request is a re-read. With 78% of stored bytes
+in tool output, the session is carrying command output forward forever.
+
+**Effort is the biggest latency lever.** 18.7s versus 7.8s median is 2.4x, and
+76.8% of responses ended on a tool call rather than prose. Running `max` for
+mechanical work is the single largest waste in the setup.
+
+**Compaction never ran.** Zero events across 153 sessions. The configured
+`tail_turns: 15` was inert, because compaction is keyed off the full context
+ceiling that a normal session never reaches.
+
+## Permission pressure, measured rather than asserted
+
+5,239 historical `bash` commands were replayed against the allowlist shapes:
+
+| allowlist | prompts | share |
+|---|---|---|
+| the narrow one in use | 4,994 | 95.3% |
+| this kit's, first version | 1,204 | 23.0% |
+| this kit's, current | 1,002 | 18.5% |
+
+The remaining 18.5% is the deliberately gated set, ranked by how often it
+actually came up:
+
+```
+ssh -o 133 · curl -s 95 · TOKEN=$(curl 67 · rm 66
+gh 63 · osascript 47 · pkill 43 · cp 41 · kill 20 · scp 17 · mv 15
+```
+
+The second version closed 216 of those prompts by allowing the read half of
+`gh` (`gh pr list`, `gh issue view`, `gh repo view`, `gh auth status`), local
+staging (`git add`), read verbs behind `git -C`, and `mkdir`/`ps`/`chmod +x`.
+It kept `gh pr create`, `gh pr merge`, `gh release`, `gh repo delete` and
+`gh api` denied: `gh api` in particular can POST to any endpoint, so allowing it
+would open a publish path the guard plugin cannot police.
+
+`ssh` at 133 and `osascript` at 47 are still why "allow everything, deny a few
+patterns" is rejected. A deny hook can block `rm -rf`; it cannot block
+`ssh host 'rm -rf /'`, and it cannot tell `TOKEN=$(curl attacker.example)` from a
+normal fetch. Keeping the human in the loop at exactly these commands is the
+point of the remainder.
+
+The list used to be transcribed into `baseline.mjs` as well as `config.js`, which
+meant the measured number was whatever the copy looked like when it was last
+edited. `baseline` imports it now.
+
+## Corrections to earlier drafts
+
+Five things in the first design were wrong. Recording them because each was
+believed confidently at the time.
+
+**"`tool_output` 200 lines / 8 KB is too tight, raise it."** Wrong the first
+time, and overcorrected the second time. The first correction was right in
+direction and wrong in axis: the OpenCode default is 2,000 lines / 51,200
+bytes, so 200 / 8,192 was about 6× tighter than default and *was* saving
+context. So it was pinned there, and stayed there.
+
+It stayed there a version too long. The later measurement, on 2,966 `read`
+calls:
+
+| measured | count |
+|---|---|
+| exceeding 8,192 bytes | 415 |
+| exceeding 24,576 bytes | 97 |
+| exceeding 51,200 bytes | 14 |
+| cut by the 200-line cap | 441 |
+| issued with an `offset` | 423 |
+
+Truncation and re-read are the same phenomenon: the cap produces a preview, the
+agent asks for the rest, and that is a whole extra request at a measured ~17s
+median. The original argument weighted tokens and ignored latency, which was the
+wrong trade on a model where latency is 17 seconds. Since only 14 of 2,966 reads
+exceed 51,200 bytes, raising the cap to the default removes ~97% of the
+truncations while barely moving the worst case — and pruning, not truncation,
+is what actually bounds context.
+
+`bin/baseline.mjs` now prints all five numbers so this is re-measurable instead
+of being re-argued.
+
+**"Compaction never ran, therefore nothing is wrong."** Zero events across 156
+sessions was read as "the setting is fine" rather than "nothing is being
+bounded". Both readings were half right and the compound conclusion was wrong:
+the configured `tail_turns` was inert *and* there was no bound on growth.
+Dropped the dead key rather than tuning it.
+
+**"Consider GraphRAG or a vector store for code retrieval."** Wrong, and
+checkable in one step. arXiv:2609.00006 dissects eleven production harnesses at
+source level; **none** uses embedding-based retrieval over code. All of them
+run ripgrep, tree-sitter, glob, and auto-discovered markdown. An earlier draft
+cited a community plugin's GraphRAG claim without checking the primary source.
+
+**"Build a pruner."** Four existing projects already had one, the best being
+`@tarquinen/opencode-dcp` at 4.3k stars. Rewriting it would have been the
+third-worst use of a week. What was worth building is the part nobody had: a
+profile compiler, and the retention field.
+
+**"The 46.6% that effort tiering saves is a measurement."** It was not. The
+`eval` cost model pairs `max` medians from `space-bunny-free` with lower-tier
+medians from `muse-spark-1.3-contributor-free` — cross-model, because the
+tiering had never actually run on the zero-retention model: `build` had been
+hand-pinned to the muse-spark route, so every recorded message on
+`space-bunny-free` is at `max`. Per the install's own database:
+
+| model | variant | messages | median |
+|---|---|---|---|
+| muse-spark-1.3-contributor-free | xhigh | 7,955 | 7.8s |
+| space-bunny-free | **max** | 3,030 | 16.9s |
+| space-bunny-free | high / xhigh / low | **0** | — |
+
+Zero data below `max` is not a rounding detail, it is the whole claim being
+unfalsified. `eval` now prints the figure as `PROJECTION` with `measured: no`,
+and `baseline` reports per-model-per-variant medians so the claim becomes real
+once the tiering has actually been running.
+
+## Why Space Bunny Free is the default
+
+Scanning free models on OpenCode Zen for context, effort, and privacy together:
+
+| model | context | effort levels | retention |
+|---|---|---|---|
+| `space-bunny-free` | 1,048,576 | low … **max** | zero-retention |
+| `x-preview-f-free` | 1,000,000 | low, high, max | zero-retention |
+| `longcat-2.5-preview-free` | 1,000,000 | *(none)* | zero-retention |
+| `deepseek-v4-flash-free` | 200,000 | low, high, max | zero-retention |
+| `muse-spark-1.3-contributor-free` | 1,048,576 | minimal … xhigh | **may train** |
+
+It is the only free model that is both top-tier on effort and zero-retention.
+The Muse Spark contributor tier is free, fast, and widely used, and it is the
+one whose provider is permitted to train on prompts. The install this replaces
+had that model as its default, which is the specific reason `retention.yml`
+exists in this project.
+
+The trade-off this project cannot resolve: Space Bunny is served over
+`/v1/chat/completions`, a weaker cache dialect than the `/v1/responses` route
+Muse Spark uses, and it is an anonymous preview model with thin benchmark
+coverage and no public identity. Zero-retention and a `max` effort tier were
+judged worth those risks; that judgement is a default, not a fact, and
+`oc-harness use` makes reversing it one flag.
+
+## How the privacy list was assembled
+
+From the Privacy section of the OpenCode Zen docs, which states a general
+zero-retention policy and then names exceptions. Ten models are named as
+retaining data. Two more, `x-preview-f-free` and `deepseek-v4-flash-free`, are
+not named in the exception list and so fall under the general policy. Those two
+are marked in `retention.yml` as inferred rather than quoted, because the
+distinction matters if you are handling someone else's code.
+
+## What the ecosystem already covers
+
+Checked before writing any of the above, so the kit composes instead of
+duplicating:
+
+| need | existing project |
+|---|---|
+| model-driven context compression | `Tarquinen/opencode-dynamic-context-pruning` (4.3k★, AGPL-3.0, development moved to `sleev.ai`) |
+| secret redaction before the LLM | `inkdust2021/opencode-vibeguard` |
+| git worktrees | `kdcokenny/opencode-worktree` |
+| persistent memory | `supermemoryai/opencode-supermemory` |
+| memory in git markdown, model routing | `code-yeongyu/oh-my-opencode` (now `omo`) |
+| bundled multi-agent harness | `kdcokenny/opencode-workspace` (16 components) |
+| distributing skills and agents from git | `jgordijn/opencode-remote-config` |
+| orchestration from slash commands | `spoons-and-mirrors/subtask2` |
+
+The gap is the seam between a provider catalog and a config file. That is what
+this kit is for.
+
+## Sources
+
+- arXiv:2609.00006 — Harness Engineering, eleven-harness source study
+- `https://opencode.ai/docs/zen/` — pricing, retention, free-tier terms
+- `https://opencode.ai/config.json` — the resolved config schema for 1.18.35
+- `@opencode-ai/plugin@1.18.35` `dist/index.d.ts` — the hook surface (the
+  version actually installed; re-check against it after any plugin bump)
+- `https://models.dev/api.json` — provider and model metadata
+- `anomalyco/opencode` issue #42977 — free-route 429 behaviour

package/examples/muse-spark-1.3-contributor-free.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "Contrarian example. Kept out of profiles/index.json on purpose: free, 1M context, and widely used, but its provider is permitted to train on your prompts and it has no `max` effort. `oc-harness list` shows it struck through with the reason. Install it with `oc-harness use muse-spark-1.3-contributor-free` and the warning is repeated on install.",
+  "id": "muse-spark-1.3-contributor-free",
+  "title": "Muse Spark 1.3 Contributor Free (OpenCode Zen)",
+  "provider": "opencode",
+  "model": "muse-spark-1.3-contributor-free",
+  "family": "muse-free",
+  "verified": "2026-10-07",
+  "retention": "may-train",
+  "notes": "Capability/privacy tradeoff, not a recommendation. Served over /v1/responses, a better cache dialect than chat/completions, and it supports temperature. But: 'Heavily discounted token pricing in exchange for permission to use your prompts and completions to train future Meta models', and its top effort is xhigh rather than max. Do not make this the default for private code.",
+  "limits": {
+    "context": 1048576,
+    "output": 131072
+  },
+  "supports": {
+    "reasoning": true,
+    "temperature": true,
+    "toolCall": true,
+    "structuredOutput": true,
+    "attachment": true
+  },
+  "effort": {
+    "levels": ["minimal", "low", "medium", "high", "xhigh"],
+    "default": "xhigh",
+    "reserveShare": 0.12
+  },
+  "roles": {
+    "plan": "max",
+    "build": "high",
+    "reviewer": "xhigh",
+    "locate": "low",
+    "verify": "low"
+  },
+  "prune": {
+    "enabled": true,
+    "keepRecentToolCalls": 6,
+    "keepRecentTurns": 3,
+    "keepUserMessages": true
+  },
+  "fallback": ["x-preview-f-free", "longcat-2.5-preview-free"]
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "opencode-harness-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Model-agnostic harness kit for OpenCode: capability profiles, role-based reasoning effort, context pruning, and measured baselines.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crytobot459/space-harness.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./profile": "./src/profile.js",
+    "./config": "./src/config.js",
+    "./rules": "./src/rules.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "oc-harness": "bin/oc-harness.mjs"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "src/",
+    "profiles/",
+    "examples/",
+    "retention.yml",
+    "GLOBAL.md",
+    "agents/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.js\"",
+    "test:all": "npm run build && npm run typecheck && npm test",
+    "test:install": "npm run measure:check && npm run attribute",
+    "check": "npm run test:all && npm run test:install && node bin/oc-harness.mjs verify",
+    "check:online": "npm run check && node bin/oc-harness.mjs doctor",
+    "baseline": "node bin/baseline.mjs",
+    "eval": "node eval/run.mjs",
+    "measure": "node eval/measure-install.mjs",
+    "measure:check": "node eval/measure-install.mjs --min-narrow 45 --min-ctx-drop 20",
+    "attribute": "node eval/attribute.mjs",
+    "attribute:json": "node eval/attribute.mjs --json",
+    "thresholds": "node eval/thresholds.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "agent",
+    "harness",
+    "context-management",
+    "reasoning-effort"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.31",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  }
+}

package/profiles/deepseek-v4-flash-free.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "Fallback tier 3. The smallest context in the queue at 200k, which is why prune.keepRecentToolCalls drops: the same settings tuned for a 1M model overflow this one.",
+  "id": "deepseek-v4-flash-free",
+  "title": "DeepSeek V4 Flash Free (OpenCode Zen)",
+  "provider": "opencode",
+  "model": "deepseek-v4-flash-free",
+  "family": "deepseek-flash",
+  "verified": "2026-10-07",
+  "retention": "zero-retention",
+  "notes": "Text only, no attachment, 200k context. Included to show the compiler scaling pruning to the model: reserveShare and retention fall together, so a 1M-tuned profile cannot silently overflow a 200k model.",
+  "limits": {
+    "context": 200000,
+    "output": 128000
+  },
+  "supports": {
+    "reasoning": true,
+    "temperature": true,
+    "toolCall": true,
+    "structuredOutput": true,
+    "attachment": false
+  },
+  "effort": {
+    "levels": ["low", "high", "max"],
+    "default": "max",
+    "reserveShare": 0.12
+  },
+  "roles": {
+    "plan": "max",
+    "build": "high",
+    "reviewer": "max",
+    "locate": "low",
+    "verify": "low"
+  },
+  "prune": {
+    "enabled": true,
+    "keepRecentToolCalls": 4,
+    "keepRecentTurns": 2,
+    "keepUserMessages": true
+  },
+  "fallback": []
+}

package/profiles/index.json

@@ -0,0 +1,60 @@
+{
+  "$comment": "Profiles verified against live provider metadata. `retention` must come from retention.yml; a model missing there cannot enter this list.",
+  "default": "space-bunny-free",
+  "profiles": [
+    {
+      "id": "space-bunny-free",
+      "file": "profiles/space-bunny-free.json",
+      "title": "Space Bunny Free",
+      "retention": "zero-retention",
+      "free": true,
+      "topEffort": "max",
+      "context": 1048576,
+      "default": true,
+      "note": "Only free Zen model with a max effort and zero-retention terms."
+    },
+    {
+      "id": "x-preview-f-free",
+      "file": "profiles/x-preview-f-free.json",
+      "title": "x-preview-f Free",
+      "retention": "zero-retention",
+      "free": true,
+      "topEffort": "max",
+      "context": 1000000,
+      "default": false,
+      "note": "Three effort levels only; no medium or xhigh."
+    },
+    {
+      "id": "longcat-2.5-preview-free",
+      "file": "profiles/longcat-2.5-preview-free.json",
+      "title": "LongCat 2.5 Preview Free",
+      "retention": "zero-retention",
+      "free": true,
+      "topEffort": null,
+      "context": 1000000,
+      "default": false,
+      "note": "No tunable reasoning effort."
+    },
+    {
+      "id": "deepseek-v4-flash-free",
+      "file": "profiles/deepseek-v4-flash-free.json",
+      "title": "DeepSeek V4 Flash Free",
+      "retention": "zero-retention",
+      "free": true,
+      "topEffort": "max",
+      "context": 200000,
+      "default": false,
+      "note": "200k context, text only."
+    }
+  ],
+  "excluded": [
+    {
+      "id": "muse-spark-1.3-contributor-free",
+      "file": "examples/muse-spark-1.3-contributor-free.json",
+      "title": "Muse Spark 1.3 Contributor Free",
+      "retention": "may-train",
+      "reason": "Provider may train on your prompts and completions (Meta contributor tier). Top effort is xhigh, not max.",
+      "installable": true
+    }
+  ]
+}

package/profiles/longcat-2.5-preview-free.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "Fallback tier 2. No tunable reasoning effort at all, so the loader omits `variant` entirely for this profile rather than guessing a level.",
+  "id": "longcat-2.5-preview-free",
+  "title": "LongCat 2.5 Preview Free (OpenCode Zen)",
+  "provider": "opencode",
+  "model": "longcat-2.5-preview-free",
+  "family": "longcat",
+  "verified": "2026-10-07",
+  "retention": "zero-retention",
+  "notes": "Zero-retention with a 1M context, but reasoning_options is null upstream: the model has one fixed effort. Any role requesting a level resolves to null and the generated config leaves variant unset.",
+  "limits": {
+    "context": 1000000,
+    "output": 131072
+  },
+  "supports": {
+    "reasoning": true,
+    "temperature": true,
+    "toolCall": true,
+    "structuredOutput": false,
+    "attachment": true
+  },
+  "effort": {
+    "levels": [],
+    "default": null,
+    "reserveShare": 0.12
+  },
+  "roles": {
+    "plan": null,
+    "build": null,
+    "reviewer": null,
+    "locate": null,
+    "verify": null
+  },
+  "prune": {
+    "enabled": true,
+    "keepRecentToolCalls": 6,
+    "keepRecentTurns": 3,
+    "keepUserMessages": true
+  },
+  "fallback": ["deepseek-v4-flash-free"]
+}