opencode-harness-kit 0.0.0-stage → 0.2.0

package/skills/space-finish/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: space-finish
+description: Close out a task: confirm checks, summarise the change, and hand the publish decision to a human. Use when work is implemented and reviewed.
+---
+
+# Finish
+
+Reached only when `space-review` pass 1 was clean. If there is an open
+blocker, you are at the wrong step: send it to `space-build` instead. Finishing
+over an unreviewed or blocked change is the failure this skill exists to stop.
+
+## Steps
+
+1. **Read `.space/tasks.md` first.** Any task still `pending` or `blocked`
+   means the work is unfinished: stop and say which one. The file is the
+   requirement, same as it was for `space-review`.
+2. **Run the checks one final time, on the final state of the tree.** A green
+   suite from before the last edit is not a green suite. Use `verify`.
+3. **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.
+4. **Check the documentation.** Did this change make a document describe
+   something that no longer exists? Fix the document, do not note it for later.
+5. **Write the summary** a person needs in order to trust the change without
+   reading the whole diff. Anything the Decisions section of `.space/tasks.md`
+   marked as deliberately not done belongs in the summary, with its reason.
+6. **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.
+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
+
+- What changed, in one sentence.
+- Which checks ran and their results, verbatim.
+- What was deliberately not done, and why.
+- Anything risky or irreversible.
+
+## The publish boundary
+
+Publishing needs human approval. Ask before `git push`, opening a pull request,
+publishing a package, or changing repository visibility, even if the task
+seems to imply it. Permissions default to ask so opencode prompts first, but
+the boundary is yours to hold, not only the hook's.
+
+Leave the tree in a state a human can review: on a branch, with the change
+visible in `git diff`.
+
+## Do not
+
+- Do not declare success over a failing check.
+- Do not squash, rebase, or force-push to tidy history.
+- Do not delete a failing test to make the suite green. A reported failure is
+  information; a deleted test is lost information.

package/skills/space-plan/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: space-plan
+description: Turn a vague request into an executable plan before any code is written. Use when a task is ambiguous, touches several files, or two people could disagree about done.
+---
+
+# Plan before building
+
+Most wasted agent time is not bad code, it is solving the wrong problem well.
+
+## The loop these four skills form
+
+```
+space-plan ─one task─▶ space-build ─verify passes─▶ space-review ─pass 1 clean─▶ space-finish ─▶ human
+                                ▲                         │
+                                └──── back to build, on a blocker: the file:line, the requirement
+                                                          missed, and the failing output
+```
+
+The only backwards edge is `space-review → space-build`: a blocker is the loop
+working, not the loop failing, and the only way out of a blocker is to fix the
+thing it names. `space-plan` is never a backwards edge. Each forward edge names
+what it hands over:
+
+| From | To | Hands over |
+|---|---|---|
+| `space-plan` | `space-build` | one task: exact paths, the concrete change, the verify command |
+| `space-build` | `space-review` | the command that ran, and its verbatim output |
+| `space-review` | `space-build` | on a blocker: the `file:line`, the requirement missed, the failing output |
+| `space-review` | `space-finish` | pass 1 clean: the diff as a whole |
+| `space-finish` | human | the summary, the checks, and what was deliberately left undone |
+
+**Re-plan only when the request itself was wrong**, not when a task turns out
+harder than estimated. The second case is a build failure and belongs in
+`space-build`.
+
+## Write the plan down
+
+A plan that only lives in the context gets lost the first time the context is
+pruned, which is exactly the moment the loop needs it. So the plan ends as a
+file, and every later step reads the file instead of the conversation.
+
+- Path: `.space/tasks.md` in the project you are planning for.
+- Format: [`reference/task-template.md`](reference/task-template.md) — goal,
+  constraints, decisions, risks, and one task per bullet with its files, its
+  concrete change, and its verify command.
+- `space-plan` creates it and keeps the Tasks section current. `space-build`
+  works from the task in the file. `space-review` diffs against it.
+  `space-finish` treats any task still `pending` or `blocked` as unfinished.
+
+## When this applies
+
+Use it when any of these is true:
+
+- The request has no single obvious file to change.
+- Nobody could tell from the diff whether the task was finished.
+- More than one design would satisfy the wording.
+- The task is a feature rather than a fix.
+
+Skip it for a single obvious edit. Writing a plan for `fix the typo` is waste.
+
+## Steps
+
+1. **Read first, but narrowly.** Grep the file names that must be involved,
+   then read the functions you need with an offset. A plan built on assumed
+   paths is worse than no plan: it reads as confident and sends the build step
+   to the wrong place. Reading whole files to check whether a function exists is
+   not orientation, it is 20x the context.
+2. **State the goal in one sentence, in the caller's words.** If you cannot,
+   you do not understand the request yet. Ask **one** specific question, and only
+   when a wrong guess would cost money, break the build irreversibly, publish
+   something, or be irreversible. Everything else you decide yourself.
+3. **List the constraints.** What must not change. What is out of scope. What
+   already exists that must keep working.
+4. **Break it into tasks that fit in a few minutes each.** For every task:
+   - exact file paths
+   - the concrete change, not "handle errors"
+   - the verify command, and what passing looks like
+5. **Order so the repository stays working.** Every step should leave the tests
+   green. A plan whose middle step is red is a plan that gets abandoned.
+6. **Name the risks** and the cheapest way to find out early.
+7. **Write it to `.space/tasks.md`** using `reference/task-template.md`, then
+   hand that file over with the plan summary.
+
+## What to hand off
+
+The `.space/tasks.md` file, plus a summary a reviewer can read in one screen:
+the goal sentence, the decisions you made rather than asked about, and the risks.
+Then let the agent that runs the plan load the `space-build` skill for one task at
+a time and `space-review` after the set. Use the `locate` agent to close gaps in
+your evidence first: it is read-only, and a gap closed before the plan is written
+costs a fraction of a gap found during the build.
+
+Do not batch the builds. One task at a time is what keeps the verify command
+attributable to a change.
+
+## Failure modes
+
+- Planning from the request alone, without reading code. This is the main one.
+- Tasks sized "and then the rest". They cannot be verified, so they are not tasks.
+- A plan that requires a decision you cannot make. That is a question, and it
+  belongs at the top, not buried in task 6.

package/skills/space-plan/reference/task-template.md

@@ -0,0 +1,47 @@
+# Task contract: `.space/tasks.md`
+
+`space-plan` writes this file into the project it is planning for. It is the
+one artifact the whole loop reads, so it has to survive a session whose context
+has been pruned. Never keep it in your head.
+
+```markdown
+# <goal, one sentence, in the caller's words>
+
+## Constraints
+- <what must not change, what must not be touched>
+
+## Decisions
+- <date> <decision, one line> — <why; links to plan/summary if there is one>
+
+## Risks
+- <the thing most likely to go wrong, and the cheapest way to find out early>
+
+## Tasks
+- [ ] <task, small enough to finish in a few minutes>
+  - files: <exact paths to change>
+  - change: <what the change is, concretely, not "handle errors">
+  - verify: <the exact command, and what passing looks like>
+  - status: pending | done | blocked
+- [x] <finished task>
+  - files: <paths>
+  - change: <what was done, including anything the original task did not name>
+  - verify: <the command that was actually run, and its verbatim final lines>
+  - status: done
+```
+
+How the loop uses it:
+
+| step | does |
+|---|---|
+| `space-plan` | creates and rewrites the Tasks section; records Decisions and Risks |
+| `space-build` | reads the task, writes only what it names, marks it done with the real verify output |
+| `space-review` | reads the Tasks section as the requirement, diffs against it in pass 1 |
+| `space-finish` | treats any `pending` or `blocked` task as "not finished", and asks for the summary decision |
+
+Rules:
+
+- One file per body of work. Start a new one only when the goal changes.
+- A task is `done` only with the verify command's real output pasted into its
+  `verify:` line. A task marked done without it has not been verified.
+- Add a Decisions line the moment something was chosen rather than asked. That
+  is the line that stops the next session re-litigating it.

package/skills/space-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: space-review
+description: Review a change in two passes, spec compliance then code quality, without editing. Use before committing or deciding a task is done.
+---
+
+# Review in two passes
+
+The order matters. Quality opinions on a change that does the wrong thing are
+noise, and they bury the finding that mattered.
+
+## Pass 1 - does it do what was asked
+
+Style is out of scope. Only the question of whether the task got done. The
+requirement is the Tasks section of `.space/tasks.md`, in the format
+`space-plan` wrote — not the conversation, and not your guess at the
+intent. If there is no file, there is no requirement to review against: say
+so and stop.
+
+- Every requirement in the task met? Name the ones that are not, with
+  `file:line`.
+- Anything in the diff the task did not ask for?
+- Does the verify command the task named exist, and does it pass?
+- Any file described as changed that is not actually in the diff?
+
+Any failure here is a **blocker**. Report it and hand it back to `space-build`
+with the location and the verify output that shows it. A review that stops
+without naming where to go next is a half result: the task is still open and
+now has an extra person who knows it is.
+
+## Pass 2 - is it any good
+
+Only if pass 1 was clean.
+
+- Duplication that will cost something on the next change
+- Error paths that swallow the reason a thing failed
+- Edge cases the tests do not cover, named specifically rather than gestured at
+- Names that do not match what they hold
+- Dead code, debug leftovers, commented-out blocks
+
+## Rules
+
+- Every finding needs a location and a consequence. "This could be clearer" is
+  not a finding. "If the API returns a list, this takes the first element and
+  silently drops the rest" is.
+- Severity is real: `blocker`, `should-fix`, `nit`. Do not inflate to look
+  thorough.
+- Propose the smallest change that removes the defect. Not a rewrite.
+- **Silence is a valid result.** Say the diff is clean. Inventing findings to
+  fill a review costs the author more than an empty review.
+
+## Report
+
+Two sections. If pass 1 blocked, one section plus the reason.

package/src/config.js

@@ -0,0 +1,358 @@
+// Compile a profile into an opencode.jsonc.
+//
+// Config that does not depend on the model - permission allowlist, pruning
+// defaults, experimental flags - is fixed here. Everything model-specific is
+// derived from the profile, so switching models changes only the profile file.
+
+import { pruneThreshold, reservedTokens, inputCap, effectiveRetention, resolveRoleModel, resolveRoles, resolveDefaultVariant, roleSplitModels } from "./profile.js"
+
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+/** @typedef {import("./profile.js").Profile} Profile */
+
+/**
+ * Where the global rule set lives, as opencode should be told to look for it.
+ *
+ * Honours OPENCODE_CONFIG_DIR, because `~/.config/opencode` is only the default
+ * and emitting it unconditionally points at the wrong file for anyone using a
+ * custom config directory - the installer would write one place and the
+ * compiler would name another. Written with a leading `~` when it is the
+ * default, which is both correct and readable in the generated file.
+ */
+export function globalInstructionsPath() {
+  const dir = process.env.OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "opencode")
+  if (dir === join(homedir(), ".config", "opencode")) return "~/.config/opencode/GLOBAL.md"
+  return join(dir, "GLOBAL.md")
+}
+
+/**
+ * The default location, for documentation and tests. Prefer
+ * `globalInstructionsPath()` when generating a config.
+ *
+ * It is written by `oc-harness install`, which symlinks this file rather than
+ * copying it, so the repo stays the source of truth. `oc-harness verify` fails if
+ * the path it names does not resolve - the failure mode where a config points at
+ * an instruction file that was never installed is silent and makes the whole
+ * harness a no-op.
+ */
+export const GLOBAL_INSTRUCTIONS = "~/.config/opencode/GLOBAL.md"
+
+/**
+ * Read-only and verification commands.
+ *
+ * Measured against 5,239 real bash calls from one install: 95.3% would prompt
+ * under a narrow allowlist, 23% under this one. The gated remainder is
+ * deliberate - ssh, curl, rm, pkill, osascript, cp, mv, kill, docker.
+ *
+ * `X*` with no space is used on purpose: opencode's `X *` pattern requires a
+ * trailing space and therefore does not match a bare `X`.
+ *
+ * The `gh` verbs below are the read half of the CLI and nothing else. `gh pr
+ * create`, `gh pr merge` and `gh api` are NOT here: they write, and `gh api` in
+ * particular can POST to any endpoint. Measured cost of gating the whole `gh`
+ * surface was 146 prompts; gating only the mutating verbs keeps those 146
+ * prompt-free without opening a publish path the guard plugin cannot police.
+ */
+export const BASH_ALLOWLIST = [
+  "ls*", "cat*", "head*", "tail*", "wc*", "file*", "stat*", "pwd*", "env*", "printenv*",
+  "date*", "whoami*", "which*", "find*", "tree*", "du*", "df*", "lsof*", "sed*", "awk*",
+  "sort*", "uniq*", "diff*", "grep*", "rg*", "echo*", "printf*", "sleep*",
+  "cd*", "realpath*", "basename*", "dirname*", "readlink*",
+  "for*", "set*", "export*", "unset*", "bash*", "sh*", "true*", "false*", "test*",
+  "read*", "#*", "xargs*", "seq*", "exit*", ":*",
+  "node*", "python3*", "python*", "npm*", "bun*", "uv*", "go*", "cargo*", "rustc*",
+  "opencode*", "sqlite3*", "jq*", "fd*",
+  "git status*", "git log*", "git diff*", "git show*", "git branch*",
+  "git rev-parse*", "git config --get*", "git remote*", "git blame*",
+  "git stash list*", "git ls-files*", "git describe*", "git shortlog*", "git --version*",
+  // `git -C <dir> <read-verb>` only. A bare `git -C *` would allow `git -C x push`.
+  "git -C * status*", "git -C * log*", "git -C * diff*", "git -C * rev-parse*",
+  "git -C * ls-files*", "git -C * show*",
+  // Staging is local and reversible; publishing is not and stays gated.
+  "git add*",
+  // `chmod 777` is denied below. `+x` is ordinary build work.
+  "chmod +x*", "chmod u+x*",
+  "mkdir*", "ps*",
+  "gh pr list*", "gh pr view*", "gh pr diff*", "gh pr checks*", "gh pr status*",
+  "gh issue list*", "gh issue view*", "gh repo view*", "gh auth status*",
+  "PYTEST_DISABLE_PLUGIN_AUTOLOAD=1*", "PYTHONPATH=*", "PYTHONUNBUFFERED=1*",
+  "python3 -m pytest*", "python3 -m venv*", "python3 -m compileall*",
+  "python3 -c*", "python3 agent/*", "python3 src/*", "python3 -",
+  ".venv/bin/python*", "pytest*", "ruff*", "mypy*", "black*",
+  "npm test*", "npm run *", "npm ci*", "npm ls*", "npm view *",
+  "npx*", "uv run *", "uv pip *", "bun run *", "bunx*", "node -e*",
+  "opencode debug*", "opencode --version*", "opencode models*",
+]
+
+/** Hard blocks. The guard plugin enforces the same set in code. */
+export const BASH_DENYLIST = [
+  // `git push` is intentionally absent: it falls through to the `*` ask rule
+  // so opencode prompts for human approval before publishing.
+  "rm -rf *",
+  "rm -fr *",
+  "curl * | sh",
+  "curl * | bash",
+  "chmod 777 *",
+  "chmod 777*",
+  "gh pr create*",
+  "gh pr merge*",
+  "gh pr close*",
+  "gh release*",
+  "gh repo delete*",
+]
+
+/**
+ * Iteration cap per role, written as `agent.<role>.steps`.
+ *
+ * `steps` is a loop breaker rather than a quality knob. On exhaustion OpenCode
+ * forces a text-only response, so an agent that has stopped making progress
+ * reports what it has instead of silently looping until the context is gone.
+ * The caps are sized to the role's real work: build gets room because it runs
+ * the edit-verify-fix cycle, verify gets room because a full suite is many
+ * commands, and the read-only roles are capped tight because they have one job.
+ */
+export const AGENT_STEPS = /** @type {Record<string, number>} */ ({
+  build: 40,
+  plan: 25,
+  reviewer: 15,
+  locate: 12,
+  verify: 20,
+})
+
+/** Roles the kit writes, with the permissions that keep them honest. */
+const AGENT_PERMISSIONS = /** @type {Record<string, Record<string, string>>} */ ({
+  plan: { edit: "deny" },
+  reviewer: { edit: "deny" },
+  locate: { edit: "deny", bash: "deny" },
+  verify: { edit: "deny" },
+})
+
+/**
+ * @param {Profile} p
+ * @param {{ base?: Record<string, any>, comments?: boolean }} [opts]
+ * @returns {string}
+ */
+export function generateConfig(p, opts = {}) {
+  const base = opts.base ?? {}
+  const model = `${p.provider}/${p.model}`
+  const roles = resolveRoles(p)
+  const instructionsPath = globalInstructionsPath()
+
+  const agent = { ...(base.agent ?? {}) }
+  for (const [role, level] of Object.entries(roles)) {
+    if (level === undefined) continue
+    const existing = { ...(agent[role] ?? {}) }
+    const rm = resolveRoleModel(p, role)
+    // The model is pinned, never inherited. Preserving a model already written
+    // on the agent is how `build` ended up on a `may-train` model while the rest
+    // of the file claimed the profile's zero-retention one: the compiler was
+    // asked to re-run over a hand-edited config and kept the hand-edit.
+    //
+    // `roleModels` is the one sanctioned way a role differs, because it is
+    // declared in the profile next to the model it points at and validated
+    // against retention.yml. Still an assignment, never a preserved value.
+    existing.model = rm ? `${p.provider}/${rm.model}` : model
+    if (level === null) delete existing.variant
+    else existing.variant = level
+    if (AGENT_PERMISSIONS[role]) {
+      existing.permission = {
+        ...(existing.permission ?? {}),
+        ...AGENT_PERMISSIONS[role],
+      }
+    }
+    if (AGENT_STEPS[role]) existing.steps = AGENT_STEPS[role]
+    agent[role] = existing
+  }
+
+  const bashRules = {
+    "*": "ask",
+    ...Object.fromEntries(BASH_ALLOWLIST.map((rule) => [rule, "allow"])),
+    ...Object.fromEntries(BASH_DENYLIST.map((rule) => [rule, "deny"])),
+  }
+
+  const compaction = { ...(base.compaction ?? {}) }
+  // `tail_turns` is dropped even if the inherited config had one. It only
+  // applies during compaction, and compaction is keyed off the full context
+  // ceiling, which a normal session never reaches. On the measured install it
+  // had never fired once, so it was inert config.
+  delete compaction.tail_turns
+  compaction.auto = true
+  compaction.prune = true
+  compaction.reserved = reservedTokens(p)
+
+  const base_ = { ...base }
+  // Two keys are dropped from the inherited config outright rather than merged.
+  // Both are cases where an existing value silently defeats the compiler:
+  // `variant` is rejected by the schema and stripped at load, so keeping it
+  // makes the file look tiered while doing nothing; and `tool_output` set tight
+  // by an earlier version would otherwise survive every regeneration.
+  delete base_.variant
+  delete base_.tool_output
+
+  const out = {
+    $schema: "https://opencode.ai/config.json",
+    ...base_,
+
+    model,
+    // Same model, not a cheaper one: swapping models mid-session changes the
+    // voice and the tool habits. Lower the effort instead. An inherited
+    // small_model pointing at a different model is replaced, not preserved.
+    small_model: model,
+    // No top-level `variant`. The 1.18.35 Config schema sets
+    // `additionalProperties: false` and has no `variant` key, so OpenCode
+    // strips it from the resolved config - verified with `opencode debug
+    // config`. The per-role tiering is carried by `agent.<role>.variant`,
+    // which is a real schema key, and `effort.js` sets the session default at
+    // the `config` hook where the runtime does still see it.
+    default_agent: base.default_agent ?? "build",
+
+    // The default is 1, which blocks subagents from spawning subagents and so
+    // removes every nested review loop.
+    subagent_depth: base.subagent_depth ?? 2,
+    // Omitting `lsp` disables it entirely, so this must be set explicitly.
+    lsp: base.lsp ?? true,
+    instructions: base.instructions ?? [instructionsPath],
+
+    compaction,
+    // OpenCode's own default (2000 lines / 51200 bytes), reached back from an
+    // earlier 200 / 8192. The tight setting truncated 415 of 2,959 measured
+    // `read` calls, and 418 calls were issued with an `offset` to fetch the
+    // rest: the truncation causes the re-read, one for one. At the measured
+    // 17.3s median per request that round trip costs far more than the tokens
+    // it saves, and prune.ts already bounds old tool output deterministically.
+    // Only 14 of 2,959 reads exceed 51,200 bytes, so this ceiling is not the
+    // thing that limits context. `oc-harness baseline` re-measures all four
+    // numbers if this ever needs arguing again.
+    tool_output: { max_lines: 2000, max_bytes: 51200 },
+
+    skills: base.skills ?? {},
+
+    experimental: {
+      batch_tool: true,
+      continue_loop_on_deny: true,
+      ...(base.experimental ?? {}),
+    },
+
+    permission: {
+      ...(base.permission ?? {}),
+      read: "allow",
+      // `allow` here is load-bearing in a way that is easy to get backwards, and
+      // it is pinned rather than inherited for the same reason the model is: an
+      // inherited `ask` survives regeneration and re-breaks every read-only
+      // role.
+      //
+      // OpenCode appends the global rule AFTER the agent's own, and last match
+      // wins, so a global `edit: "ask"` silently overrides every agent's
+      // `edit: "deny"` and the read-only roles can edit files after a prompt.
+      // `allow` is the implicit default and emits no rule at all, which leaves
+      // the per-agent `deny` intact. Writes outside the project are still
+      // gated by `external_directory`, which defaults to `ask`.
+      edit: "allow",
+      // OpenCode ships this as `deny` on every built-in agent, so a genuinely
+      // blocked agent has no cheap way to say so and falls back to prose. One
+      // structured question is cheaper to answer and easier to act on.
+      question: "allow",
+      doom_loop: base.permission?.doom_loop ?? "ask",
+      bash: bashRules,
+    },
+
+    agent,
+
+    // The router plugin reads this at startup to know which fallback queue to
+    // walk, and it is also how a profile stays identifiable after the config
+    // has been hand-edited.
+    harness: {
+      profile: p.id,
+      ...(p.fallback?.length ? { fallback: p.fallback[0] } : {}),
+      threshold: pruneThreshold(p),
+    },
+  }
+
+  return render(out, p, { comments: opts.comments ?? true, instructionsPath })
+}
+
+/**
+ * @param {Record<string, any>} cfg
+ * @param {Profile} p
+ * @param {{ comments: boolean, instructionsPath?: string }} opts
+ * @returns {string}
+ */
+function render(cfg, p, opts) {
+  const c = opts.comments ? "// " : ""
+  const instructionsPath = opts.instructionsPath ?? globalInstructionsPath()
+  const input = p.limits.input ?? p.limits.context
+  const levels = p.effort?.levels ?? []
+  const roles = resolveRoles(p)
+
+  const effective = effectiveRetention(p)
+  // The input cap that actually governs context management, which on a split
+  // profile is the widest role model rather than the base. The header must name
+  // it, or `reserved` and `prune` read as arithmetic against a number that is
+  // not the one they used.
+  const effectiveInput = inputCap(p)
+  const splits = Object.keys(p.roleModels ?? {})
+  const head = [
+    `${c}Generated by opencode-harness-kit. Edit profiles/${p.id}.json instead`,
+    `${c}of this file, then re-run: oc-harness use ${p.id}`,
+    `${c}`,
+    `${c}profile      ${p.id}`,
+    `${c}model        ${p.provider}/${p.model}`,
+    ...(splits.length
+      ? [
+          `${c}split        ${splits.map((r) => `${r}=${p.roleModels?.[r]?.model}`).join("  ")}`,
+          `${c}             (roles not listed above run on the base model above)`,
+        ]
+      : []),
+    `${c}context      ${p.limits.context.toLocaleString("en-US")} tokens`,
+    `${c}input cap    ${input.toLocaleString("en-US")} tokens${effectiveInput !== input ? `  (base model; ${effectiveInput.toLocaleString("en-US")} governs split roles)` : ""}`,
+    `${c}output cap   ${p.limits.output.toLocaleString("en-US")} tokens`,
+    `${c}reasoning    ${levels.length ? levels.join(" < ") : "(not tunable)"}`,
+    // The header must name the retention that actually applies, which with a
+    // split is the least private model in the file, not the base one. Printing
+    // `p.retention` here is the same class of bug as the inherited `build`
+    // model: the file claims a privacy property the agents do not have.
+    `${c}retention    ${effective.retention}${effective.retention === "may-train" ? "  <-- prompts may train a model" : ""}`,
+    ...(effective.retention !== p.retention
+      ? [
+          `${c}             base ${p.provider}/${p.model} is ${p.retention}, but ${effective.worst} makes the whole file ${effective.retention}`,
+        ]
+      : []),
+    `${c}`,
+    `${c}Derived numbers, do not hand-edit:`,
+    `${c}  compaction.reserved  ${reservedTokens(p).toLocaleString("en-US")}  (${Math.round((p.effort?.reserveShare ?? 0.12) * 100)}% of the governing input cap${effectiveInput !== input ? `, ${effectiveInput.toLocaleString("en-US")} for the widest split role` : ""}, held back for reasoning growth)`,
+    `${c}  prune threshold      ${pruneThreshold(p).toLocaleString("en-US")}  (governing input cap minus reserve)`,
+    `${c}  role effort          ${Object.entries(roles).map(([k, v]) => `${k}=${v ?? "unset"}`).join("  ")}`,
+    ...(roleSplitModels(p).length
+      ? [
+          `${c}  role models          ${roleSplitModels(p).map((r) => `${r.role}=${r.model}${r.limits ? ` (out ${r.limits.output.toLocaleString("en-US")})` : ""}`).join("  ")}`,
+        ]
+      : []),
+    `${c}  agent steps          ${Object.entries(AGENT_STEPS).filter(([r]) => roles[r]).map(([r, n]) => `${r}=${n}`).join("  ")}`,
+  ]
+
+  if (!levels.length) {
+    head.push(`${c}`, `${c}This model publishes no tunable reasoning effort, so no variant is written.`)
+  } else {
+    head.push(
+      `${c}`,
+      `${c}Effort is per-role above. There is no top-level "variant" key: the 1.18.35`,
+      `${c}Config schema rejects it, and the router sets the session default at runtime.`,
+    )
+  }
+  if (p.supports?.temperature === false) {
+    head.push(`${c}This model does not support temperature, so none is set.`)
+  }
+  if (p.prune?.enabled) {
+    head.push(
+      `${c}  prune keeps         ${p.prune.keepRecentToolCalls ?? 6} tool calls, ${p.prune.keepRecentTurns ?? 3} turns verbatim`,
+    )
+  }
+  head.push(
+    `${c}`,
+    `${c}Run "oc-harness verify" to check this file still matches the profile and`,
+    `${c}that the agents and ${instructionsPath} are actually installed.`,
+  )
+
+  return `${head.join("\n")}\n${JSON.stringify(cfg, null, 2)}\n`
+}