opencode-harness-kit 0.2.0 → 0.3.3

package/src/config.js

@@ -3,8 +3,31 @@
 // 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.
+//
+// A fleet profile turns several models on at once, and there is one hard
+// constraint that shapes the whole file:
+//
+//   The model lives in the CONFIG, never in a markdown agent file.
+//
+// An agent file of the same name replaces the config entry wholesale, and a
+// file without a `model:` line makes the agent inherit the caller's model
+// instead. Both were verified against OpenCode 1.19: a conflicting file won,
+// and a file with no model ran on the parent session's model. So the lanes
+// live in `agent.<lane>` here, and their prompt bodies live in prompts/ and
+// are referenced with a path opencode can resolve.
 
-import { pruneThreshold, reservedTokens, inputCap, effectiveRetention, resolveRoleModel, resolveRoles, resolveDefaultVariant, roleSplitModels } from "./profile.js"
+import {
+  pruneThreshold,
+  reservedTokens,
+  inputCap,
+  effectiveRetention,
+  resolveRoleModel,
+  resolveRoles,
+  resolveDefaultVariant,
+  roleSplitModels,
+  promptRef,
+  loadLanes,
+} from "./profile.js"
 
 import { join } from "node:path"
 import { homedir } from "node:os"
@@ -67,8 +90,8 @@ export const BASH_ALLOWLIST = [
   "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*",
+  "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.
@@ -102,66 +125,62 @@ export const BASH_DENYLIST = [
   "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]
+ * @param {{ base?: Record<string, any>, comments?: boolean, unhealthy?: Set<string> }} [opts]
  * @returns {string}
  */
 export function generateConfig(p, opts = {}) {
   const base = opts.base ?? {}
+  const unhealthy = opts.unhealthy
   const model = `${p.provider}/${p.model}`
-  const roles = resolveRoles(p)
+  const roles = resolveRoles(p, { unhealthy })
   const instructionsPath = globalInstructionsPath()
+  const lanes = loadLanes()
 
   const agent = { ...(base.agent ?? {}) }
+  /** Lanes the primary agents are allowed to delegate to. */
+  const delegable = Object.keys(roles).filter(
+    (r) => lanes[r]?.mode !== "primary",
+  )
+
   for (const [role, level] of Object.entries(roles)) {
     if (level === undefined) continue
+    const lane = lanes[role]
     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.
+    const rm = resolveRoleModel(p, role, { unhealthy })
     existing.model = rm ? `${p.provider}/${rm.model}` : model
+
     if (level === null) delete existing.variant
     else existing.variant = level
-    if (AGENT_PERMISSIONS[role]) {
+
+    if (lane) {
+      if (lane.description) existing.description = lane.description
+      if (lane.mode) existing.mode = lane.mode
+      if (lane.steps) existing.steps = lane.steps
+      existing.prompt = promptRef(role)
+      if (lane.permission) {
+        existing.permission = {
+          ...(existing.permission ?? {}),
+          ...lane.permission,
+        }
+      }
+    }
+
+    // A primary agent may hand work to a lane. The rule is per-agent, and it
+    // is last-match-wins, so the allow list has to come after the deny.
+    if (lane?.mode === "primary" && delegable.length) {
       existing.permission = {
         ...(existing.permission ?? {}),
-        ...AGENT_PERMISSIONS[role],
+        task: { "*": "deny", ...Object.fromEntries(delegable.map((r) => [r, "allow"])) },
       }
     }
-    if (AGENT_STEPS[role]) existing.steps = AGENT_STEPS[role]
+
     agent[role] = existing
   }
 
@@ -179,7 +198,7 @@ export function generateConfig(p, opts = {}) {
   delete compaction.tail_turns
   compaction.auto = true
   compaction.prune = true
-  compaction.reserved = reservedTokens(p)
+  compaction.reserved = reservedTokens(p, { unhealthy })
 
   const base_ = { ...base }
   // Two keys are dropped from the inherited config outright rather than merged.
@@ -202,7 +221,7 @@ export function generateConfig(p, opts = {}) {
     // 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`,
+    // config`. The per-lane tiering is carried by `agent.<lane>.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",
@@ -240,11 +259,11 @@ export function generateConfig(p, opts = {}) {
       // `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.
+      // lane.
       //
       // 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.
+      // `edit: "deny"` and the read-only lanes 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`.
@@ -265,33 +284,37 @@ export function generateConfig(p, opts = {}) {
     harness: {
       profile: p.id,
       ...(p.fallback?.length ? { fallback: p.fallback[0] } : {}),
-      threshold: pruneThreshold(p),
+      threshold: pruneThreshold(p, { unhealthy }),
     },
   }
 
-  return render(out, p, { comments: opts.comments ?? true, instructionsPath })
+  return render(out, p, { comments: opts.comments ?? true, instructionsPath, unhealthy })
 }
 
 /**
  * @param {Record<string, any>} cfg
  * @param {Profile} p
- * @param {{ comments: boolean, instructionsPath?: string }} opts
+ * @param {{ comments: boolean, instructionsPath?: string, unhealthy?: Set<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 unhealthy = opts.unhealthy
+  const lanes = loadLanes()
   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 roles = resolveRoles(p, { unhealthy })
+
+  const effective = effectiveRetention(p, { unhealthy })
+  // The input cap that actually governs context management, which on a fleet
+  // profile is the NARROWEST lane 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, { unhealthy })
   const splits = Object.keys(p.roleModels ?? {})
+  const laneRows = roleSplitModels(p, { unhealthy })
+  const isFleet = splits.length > 0
+
   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}`,
@@ -300,35 +323,37 @@ function render(cfg, p, opts) {
     `${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}lanes        ${splits.length} enabled, each on the first model its chain allows`,
         ]
       : []),
-    `${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}context      ${p.limits.context.toLocaleString("en-US")} tokens${isFleet ? "  (base model)" : ""}`,
+    `${c}input cap    ${effectiveInput.toLocaleString("en-US")} tokens${effectiveInput !== (p.limits.input ?? p.limits.context) ? "  (narrowest lane; governs the shared reserve)" : ""}`,
     `${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}`,
         ]
       : []),
+    ...(p.maxRetention && p.maxRetention !== p.retention
+      ? [
+          `${c}ceiling      ${p.maxRetention} - a lane may only resolve to a model at or below this`,
+        ]
+      : []),
     `${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}  compaction.reserved  ${reservedTokens(p, { unhealthy }).toLocaleString("en-US")}  (${Math.round((p.effort?.reserveShare ?? 0.12) * 100)}% of the narrowest input cap in play, held back for reasoning growth)`,
+    `${c}  prune threshold      ${pruneThreshold(p, { unhealthy }).toLocaleString("en-US")}  (narrowest input cap minus reserve)`,
     `${c}  role effort          ${Object.entries(roles).map(([k, v]) => `${k}=${v ?? "unset"}`).join("  ")}`,
-    ...(roleSplitModels(p).length
+    ...(laneRows.length
       ? [
-          `${c}  role models          ${roleSplitModels(p).map((r) => `${r.role}=${r.model}${r.limits ? ` (out ${r.limits.output.toLocaleString("en-US")})` : ""}`).join("  ")}`,
+          `${c}  lane models          ${laneRows.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("  ")}`,
+    `${c}  agent steps          ${Object.entries(roles)
+      .map(([k]) => `${k}=${lanes[k]?.steps ?? 0}`)
+      .join("  ")}`,
   ]
 
   if (!levels.length) {
@@ -336,7 +361,7 @@ function render(cfg, p, opts) {
   } else {
     head.push(
       `${c}`,
-      `${c}Effort is per-role above. There is no top-level "variant" key: the 1.18.35`,
+      `${c}Effort is per-lane 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.`,
     )
   }

package/src/driver/run.mjs

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

package/src/effort.js

@@ -7,11 +7,11 @@
 // against 7.8s for `xhigh` on a different model, while 77% of responses ended
 // on a tool call rather than prose.
 //
-// A level is never emitted raw. It is resolved against the profile's own
-// available levels, so a role asking for `max` on a model without `max` gets
-// the nearest level that actually exists.
+// A level is never emitted raw. It is resolved against the levels of the model
+// the lane actually runs on, so a lane asking for `max` on a model without
+// `max` gets the nearest level that actually exists.
 
-import { loadProfile, resolveRoles, resolveDefaultVariant } from "./profile.js"
+import { loadProfile, resolveRoles, resolveDefaultVariant, resolveLaneModel, LANE_NAMES } from "./profile.js"
 
 /**
  * @typedef {import("./profile.js").Profile} Profile
@@ -22,39 +22,56 @@ import { loadProfile, resolveRoles, resolveDefaultVariant } from "./profile.js"
  * @property {string} model
  * @property {string|null} defaultVariant
  * @property {Record<string, string|null>} roles
+ * @property {Record<string, string>} laneModels
  * @property {string[]} notes
  */
 
-/** Roles the kit manages. A role a profile does not mention is left alone. */
-export const MANAGED_ROLES = ["plan", "build", "reviewer", "locate", "verify"]
+/**
+ * The lanes a profile manages. A lane a profile does not mention is left alone.
+ *
+ * This used to be a hand-written list of nine lanes, and it drifted: the
+ * fleet has ten, and `longform` was missing. A second list of lane names is a
+ * second source of truth, and the lane table in `lanes.json` is the first one.
+ *
+ * @type {string[]}
+ */
+export const MANAGED_ROLES = LANE_NAMES
 
 /**
  * @param {string} profileId
+ * @param {{ unhealthy?: Set<string> }} [opts]
  * @returns {EffortResult}
  */
-export function planEffort(profileId) {
+export function planEffort(profileId, opts = {}) {
   const p = loadProfile(profileId)
   const levels = p.effort?.levels ?? []
-  const roles = resolveRoles(p)
+  const roles = resolveRoles(p, opts)
   const notes = []
 
   if (levels.length === 0) {
     notes.push(
-      `${p.model} publishes no tunable reasoning effort; variant will be omitted for every role.`,
+      `${p.model} publishes no tunable reasoning effort; variant will be omitted for every lane.`,
     )
   }
   for (const [role, want] of Object.entries(p.roles ?? {})) {
     const got = roles[role]
     if (want && got && want !== got) {
-      notes.push(`role ${role} asked for ${want}; ${p.model} tops out at ${got}.`)
+      notes.push(`lane ${role} asked for ${want}; its model tops out at ${got}.`)
     }
   }
 
+  /** @type {Record<string, string>} */
+  const laneModels = {}
+  for (const role of Object.keys(p.roles ?? {})) {
+    laneModels[role] = resolveLaneModel(p, role, opts).model
+  }
+
   return {
     profileId,
     model: `${p.provider}/${p.model}`,
     defaultVariant: resolveDefaultVariant(p),
     roles,
+    laneModels,
     notes,
   }
 }
@@ -65,34 +82,54 @@ export function planEffort(profileId) {
  *
  * `AgentConfig.variant` only applies to the agent's own configured model, so
  * the model is written alongside the variant instead of relying on the global
- * default. That is also what makes per-role effort work at all.
+ * default. That is also what makes per-lane effort work at all.
+ *
+ * The model is only filled in when the agent does not have one. A fleet puts
+ * ten different models behind ten agents, and overwriting them with the
+ * profile's base model here would collapse the whole fleet onto one route.
  *
  * @param {Config} config
  * @param {EffortResult} result
- * @param {{ fallbackProfileId?: string }} [opts]
+ * @param {{ fallbackProfileId?: string, sessionModel?: string }} [opts]
  * @returns {Config}
  */
 export function applyEffort(config, result, opts = {}) {
   const cfg = /** @type {Record<string, any>} */ (config)
 
-  // Always pin the model. When the model has no tunable effort we still set it
-  // and simply omit `variant` below.
-  cfg.model = result.model
+  // The session model is the profile's base, unless the router moved it. A
+  // fleet whose base route is spent keeps its lanes and moves the session
+  // onto a fallback; pinning the base back here would undo that failover and
+  // send the session back to the dead route.
+  const sessionModel =
+    typeof opts.sessionModel === "string" && opts.sessionModel
+      ? opts.sessionModel
+      : result.model
+  // Always pin the session model. When the model has no tunable effort we
+  // still set it and simply omit `variant` below.
+  cfg.model = sessionModel
 
   cfg.agent = cfg.agent ?? {}
-  for (const role of MANAGED_ROLES) {
-    const level = result.roles[role]
-    if (level === undefined) continue // role not described by this profile
+  for (const [role, level] of Object.entries(result.roles)) {
+    if (level === undefined) continue
     const existing = cfg.agent[role] ?? {}
-    if (!existing.model) existing.model = result.model
+    if (!existing.model) {
+      existing.model = result.laneModels?.[role]
+        ? `${result.model.split("/")[0]}/${result.laneModels[role]}`
+        : result.model
+    }
     if (level === null) delete existing.variant
     else existing.variant = level
     cfg.agent[role] = existing
   }
 
-  cfg.harness = opts.fallbackProfileId
-    ? { profile: result.profileId, fallback: opts.fallbackProfileId }
-    : { profile: result.profileId }
+  // The router publishes `sessionModel` and `threshold` on the same object.
+  // Replacing the whole thing here dropped them, which is how a fleet that
+  // had failed over ended up with a session model nobody chose.
+  cfg.harness = {
+    ...(cfg.harness ?? {}),
+    profile: result.profileId,
+    ...(opts.fallbackProfileId ? { fallback: opts.fallbackProfileId } : {}),
+  }
 
   return config
 }