leos-agent 6.1.0

package/skills/using-leo/references/opencode-mapping.md

@@ -0,0 +1,28 @@
+<!-- Generated by scripts/render_adapters.py; do not edit. -->
+# OpenCode mapping
+
+Provider: `openrouter`
+
+| Tier | Model | Effort |
+|---|---|---|
+| Fable | `moonshotai/kimi-k3` | native default |
+| Opus | `moonshotai/kimi-k3` | native default |
+| Sonnet | `z-ai/glm-5.2` | native default |
+| Haiku | `z-ai/glm-5.2` | native default |
+
+Roles register as native OpenCode agents (from `adapters/opencode/agents.json`, generated from `config/models.json` and `roles/*.md`) and are spawned via the task tool as subagents. There is no per-spawn model override on this harness: each agent always runs its registered model, so `reviewer` always runs the full Opus-tier model — the trivial-diff Sonnet-tier downscale does not apply here; every diff gets the full review.
+
+Read-only is harness-enforced here, unlike Codex and Cursor: read-only roles carry a generated `permission.edit: deny`, so an off-policy write attempt is refused by OpenCode itself, not merely discouraged by the prompt. Write-capable agents additionally carry coarse `rm -rf` bash denies as a stopgap for opencode#5894 (unconfirmed whether `tool.execute.before` also intercepts subagent bash); the precise tripwire stays `hooks/bash-guard.py` on the primary agent.
+
+No `EnterWorktree` tool exists here — use leo:worktrees' raw `git worktree` fallback for isolated branch work. State reads and writes go through `python3 <plugin-root>/scripts/state.py` (`get` / `merge` / `path`), same contract as every other harness. There is no Workflow tool and no `cost-tiered-fix.js` here — a batch of independent tasks is fanned out as manual parallel task-tool subagent spawns instead.
+
+Tier collapse here: Fable≡Opus (`moonshotai/kimi-k3`), Sonnet≡Haiku (`z-ai/glm-5.2`) — routing between collapsed rungs buys role, not power. Fable is not a real rung: `expert` cannot break a deadlock a collapsed Opus already lost, so cap escalation at Opus and report.
+
+## Leo skills not available here
+
+- `leo:attach-pr` — its entire purpose is Claude Code Desktop's PR-card detector, which no other harness has, and it reaches its resolver through a Claude-only skill-directory placeholder.
+- `leo:resolve-ticket` — needs plugin-path placeholders, a pinned Claude model, and Claude-only subagent, worktree, and question tools.
+- `leo:review-pr` — its whole mechanism is a script reached through a Claude-only skill-directory placeholder, plus a pinned Claude model.
+- `leo:watch-review` — pinned Claude model, and it drives review-pr through Claude Code's own skill-invocation tool.
+
+Every other skill in the policy's Skill index is registered here and behaves the same. Reviewing a pull request on this harness means running the canonical reviewer role prompt against the diff by hand.

package/skills/verification/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: verification
+description: >
+  Fresh-evidence gate before claiming done, fixed, or passing. Applies to
+  the main loop, implementer, executor, and anyone reporting completion:
+  a completion claim needs a proving command run in the current turn, whose
+  output was actually read — never a prior run, a "should pass now," or a
+  subagent's self-report relayed as fact.
+when_to_use: >
+  Before writing any completion claim — "tests pass," "build is green,"
+  "bug fixed," "agent finished the task." Also applies when relaying a
+  subagent's own "done"/"success" report up the chain. NOT for routine
+  in-progress status updates that make no completion claim, and NOT a
+  substitute for the review phase itself — this gates the evidence behind
+  it, execute-then-review still owns the verdict.
+---
+
+# verification
+
+Core rule: no completion claim without a proving command run fresh, this
+turn, with output actually read. A claim resting on memory, a prior run, or
+someone else's word is not verification — it is a guess wearing the shape
+of one.
+
+## When it fires
+
+Any sentence of the form "X passes," "X is fixed," "X works now," "agent Y
+finished." That sentence is a claim. A claim needs proof, and proof has an
+expiration: the moment code changes again, prior proof is stale.
+
+Does not fire for: status updates that don't assert completion ("still
+running," "found the bug, fixing now"), or work that genuinely has no
+runtime surface (docs/comment-only diffs — see the execute-then-review
+exemptions).
+
+## The discipline
+
+1. **Name the command that would falsify the claim.** Not "does it look
+   right" — the specific test/build/repro that fails if the claim is false.
+   If no such command exists, the claim isn't verifiable yet; say so instead
+   of asserting it.
+2. **Run it fresh, this turn.** A green run from three edits ago proves
+   nothing about the code as it stands now.
+3. **Read the exit status and failure counts.** Not the last line of
+   scrollback, not a summary a subagent wrote — the actual output.
+4. **Only then claim, and state the evidence** — the command and what it
+   returned, not just "verified."
+
+Skipping step 1 is how "should be fine" sneaks in. Skipping step 2 is how a
+stale green run gets relayed as current. Skipping step 3 is how a nonzero
+exit gets read as success because the output scrolled by fast.
+
+## Claim → proof
+
+| Claim | Falsifying command |
+|---|---|
+| Tests pass | the actual test command, run now, exit code + failure count read |
+| Build is green | the build command, run now, read for errors/warnings |
+| Bug is fixed | the reproducer that showed the bug — now green, run fresh |
+| Agent reports done | its diff and output, inspected directly — its "success" is a claim, not evidence |
+
+## Subagent reports are claims, not evidence
+
+A subagent saying "success," "all tests pass," or "implemented as
+requested" is exactly as unverified as your own untested assertion would be
+— it is one more claim to check against artifacts. Inspect the diff it
+produced. Run the check it says it ran. If it reports a test command, that
+command's output belongs in your evidence, not its summary of the output.
+Relaying a subagent's self-report upward without this check just moves the
+gap in provenance one level up the chain.
+
+## Done is the three-line report
+
+Writing code is not done. Done is the execute-then-review report:
+
+- **what changed** — the diff, in one line
+- **checks run** — the fresh commands from this gate, with results
+- **review verdict** — clean per the execute-then-review policy, not
+  self-assessed
+
+Verification is the evidence behind lines two and three. A report with line
+one but not two and three is a status update, not a completion claim — label
+it as such.
+
+## Self-talk to catch
+
+- "It should pass now, I fixed the obvious thing" — run it.
+- "The tests were green before this edit" — before this edit is not now.
+- "The subagent said it's done" — done according to whom, checked how.
+- "I read the code and it looks correct" — reading is not running.
+- "Re-running is wasteful, nothing changed" — if nothing changed, the prior
+  run is fine to cite as fresh evidence; if anything did, it isn't.
+
+## Works with
+
+- The execute-then-review policy (injected leo:using-leo) — that gate is the
+  outer loop this skill feeds into; the reviewer subagent judges the diff,
+  this skill governs the evidence claimed leading up to that judgment.
+- reviewer — its verdict is itself a claim to relay accurately, not to
+  soften or summarize away.
+- End-to-end exercise — when the falsifying command is "does the real flow
+  work," drive the actual app or flow, not just the test suite.

package/skills/worktrees/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: worktrees
+description: >
+  Worktree lifecycle mechanics for isolated branch work — detect, create,
+  and clean up a git worktree so implementation happens off the main
+  checkout. Shared by resolve-ticket, executing-plans, and delegation
+  fan-outs; not itself a workflow, just the plumbing they all call into.
+when_to_use: >
+  Any skill or agent about to create or tear down a worktree for isolated
+  branch work. NOT for choosing whether isolation is needed in the first
+  place (that call belongs to the calling skill's plan/gate step) and NOT
+  for merging or cleaning up a finished branch's remnants after the PR
+  lands — that's leo:finishing-a-branch.
+---
+
+# Worktrees
+
+Core rule: **detect existing isolation before creating anything, and never
+remove a worktree from inside it.**
+
+## When this fires
+
+A calling skill has already decided it wants isolated branch work (a plan
+was approved, a fan-out item needs its own tree) and needs the mechanics:
+enter, verify, exit, clean up. This skill doesn't decide *whether* to
+isolate — that's upstream. It also doesn't cover post-merge branch
+deletion or remote cleanup; once the PR lands, hand off to
+leo:finishing-a-branch.
+
+## Procedure
+
+### 1. Detect existing isolation first
+
+Before creating anything, check whether the session is already inside a
+worktree:
+
+```
+git rev-parse --git-common-dir
+git rev-parse --git-dir
+```
+
+If they differ, the current checkout **is already a worktree** — the
+session's own isolation. Never nest a worktree inside a worktree: do the
+work here, or exit to the main checkout first if a *different* branch
+needs its own tree. Nesting produces a git state no cleanup step can
+untangle cleanly.
+
+### 2. Prefer the native tools
+
+`EnterWorktree` / `ExitWorktree` are harness-managed: they track which
+worktree belongs to which session and auto-clean on exit. Default to them.
+
+### 3. Raw-git fallback, only when the native tools are unavailable
+
+Fixed location convention: `.claude/worktrees/<name>`. Before creating,
+verify the location is actually ignored:
+
+```
+git check-ignore .claude/worktrees/<name>
+```
+
+No output (or a non-zero exit) means it isn't ignored — stop and fix
+`.gitignore` first. A worktree directory that git tracks will fight every
+subsequent commit in the main checkout. Only after `check-ignore` confirms
+it, run:
+
+```
+git worktree add -b <branch> .claude/worktrees/<name> <base-ref>
+```
+
+### 4. Cleanup is provenance-gated
+
+Before removing any worktree, establish who created it:
+
+- Path under `.claude/worktrees/<name>` (the convention dir) **and** this
+  system created it → safe to remove.
+- Created via `EnterWorktree` → belongs to its `ExitWorktree`, not to raw
+  `git worktree remove`. Use the matching exit tool; don't hand-remove a
+  harness-tracked worktree, it loses the session-tracking state.
+- Anything else — a path outside the convention dir, or one this system
+  didn't create — is the user's. Leave it alone; report it, don't touch it.
+
+Provenance is the only gate. A worktree existing and looking abandoned is
+not permission to remove it; confirm it's one this system made via the
+convention path (or the matching Enter/Exit pairing) before it goes.
+
+### 5. Never remove a worktree from inside it
+
+`cd` to the main checkout first — removing a worktree while it's the
+current working directory leaves git in a state that needs manual repair.
+Sequence:
+
+```
+cd <main-checkout>
+git worktree remove .claude/worktrees/<name>
+git worktree prune
+```
+
+`ExitWorktree` handles this ordering itself when used; the manual sequence
+above is only for the raw-git fallback path.
+
+## Live config repo caveat
+
+In Leo's own setup, files under this repo (`~/.leos-agent`) may be wired
+into the running environment via symlinks or hooks — editing them in place
+can break the very session doing the editing. Restructuring work on this
+repo happens in a worktree so the live tree stays intact while the change
+is built and reviewed. This skill's own file was written that way: this
+migration is the example, not a hypothetical.
+
+## Self-talk to catch
+
+- "It's probably fine to reuse the current checkout" — check
+  `--git-common-dir` vs `--git-dir` first; don't guess from vibes.
+- "This worktree looks stale, I'll just remove it" — stale isn't
+  provenance. Confirm the convention path or the Enter/Exit pairing.
+- "I'm already in the worktree, `git worktree remove .` should work" —
+  never remove a worktree from inside it; cd out first.
+- "Skipping check-ignore, the convention dir is obviously gitignored" —
+  verify it every time; a missing `.gitignore` entry silently breaks the
+  main checkout's commits.
+
+## Works with
+
+- resolve-ticket — Step 5 (Worktree) calls this for enter, Step 8 (Ship)
+  calls this for exit.
+- executing-plans — isolates plan execution the same way.
+- leo:finishing-a-branch — post-merge cleanup once the PR lands; out of
+  scope here.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: writing-plans
+description: >
+  Quality bar for plans produced by the planner agent or in plan mode. A
+  plan is done when a Sonnet implementer can execute it without making a
+  single design decision — every step names exact files, shows literal
+  code or commands, and states how to verify it, anchored to a recorded
+  base ref.
+when_to_use: >
+  Writing or reviewing a plan before handoff to leo:executing-plans —
+  planner-agent output, plan-mode output, or any multi-step change spec.
+  NOT for choosing the approach itself (that's leo:brainstorming) and NOT
+  for the implementation or review phases that consume the plan.
+---
+
+# writing-plans
+
+Core rule: a plan is done when a Sonnet implementer can execute it without
+making a single design decision. If executing the plan requires judgment
+calls, the plan isn't finished — it's a to-do list wearing a plan's clothes.
+
+## When this fires
+
+Any time a plan is about to be handed off for execution: planner-agent
+output before leo:executing-plans picks it up, plan-mode output before
+approval, or a plan Leo asks you to review. Not for the design discussion
+that precedes the plan — an unsettled approach means back up to
+leo:brainstorming (rule 5 below), not push forward into more plan detail.
+
+## The five load-bearing rules
+
+1. **Exact files, literal code, stated verification.** Every step names the
+   file(s) it touches, shows the literal code or command to write/run — not
+   a description of what the code should do — and states how to verify the
+   step worked (a command, a test name, an expected output). "Add error
+   handling to the parser" is not a step. "In `src/parser.py`, wrap the
+   `json.loads(raw)` call on line 42 in a `try/except json.JSONDecodeError`
+   that raises `ParseError(f\"bad payload: {raw[:80]}\")`; verify with
+   `pytest tests/test_parser.py::test_malformed_json`" is a step.
+
+2. **Base ref in the header.** The plan header records the base ref —
+   `git rev-parse HEAD`, or literally "uncommitted working tree" if the
+   plan starts from dirty state. Without a shared base ref, implementer and
+   reviewer are diffing against different worlds and neither's output
+   means anything to the other.
+
+3. **No placeholders.** "TBD", "TODO", "handle edge cases", "add
+   validation", "similar to step N" are plan failures, not acceptable
+   shorthand — fix them before handoff, not during execution. A
+   placeholder in a plan just moves the design decision onto whichever
+   Sonnet implementer hits it first, which is exactly the failure mode
+   this skill exists to prevent. "Similar to step N" is the sneakiest
+   form: it looks concrete but hides a judgment call about what actually
+   differs — write the step out.
+
+4. **Steps sized to a reviewable boundary.** Each step should be the
+   smallest unit a reviewer could accept or reject on its own — one file's
+   worth of change, one migration, one function. Bundle unrelated changes
+   into a single step and the reviewer either rubber-stamps the whole
+   thing or blocks all of it over one bad line. If a step needs "and
+   also" to describe, it's two steps.
+
+5. **Unsettled approach → back up.** If writing the plan surfaces a real
+   design fork ("could go with polling or webhooks here") that the plan
+   author is resolving on the fly, stop — that's not plan-writing, that's
+   design happening inside a document meant to record decisions already
+   made. Route to leo:brainstorming to settle the approach, then come back
+   and write the plan. A plan for an unchosen design is waste: the
+   implementer either can't proceed or silently picks for you, and now
+   the review is judging a decision nobody signed off on.
+
+## Self-talk to catch
+
+- "The implementer will know what I mean" — no placeholder survives
+  contact with a different model on a different day; write the literal
+  code.
+- "This step is basically step 3 again" — then step 3's text belongs
+  here too, verbatim or adapted; "similar to step 3" is a placeholder.
+- "I'll figure out the base ref when review starts" — the header needs it
+  now, or implementer and reviewer silently diff against different trees.
+- "It's obviously going to be small, I don't need to size the step" —
+  size it anyway; "obviously small" is exactly the case where a bundled
+  step slips a real decision past review.
+- "I'm not 100% sure webhooks vs. polling, I'll note it as a decision
+  point in the plan" — a decision point in a plan is a design fork that
+  belongs in leo:brainstorming, not a step for the implementer to guess
+  at.
+
+## Works with
+
+- leo:brainstorming — resolve the approach before a plan gets written for it.
+- leo:executing-plans — consumes a plan that passes this bar; if it can't
+  find exact files/commands or hits a placeholder, the plan should have
+  failed this checklist.
+- reviewer — judges the diff the plan produced, using the same base ref
+  the plan recorded.

package/workflows/cost-tiered-fix.js

@@ -0,0 +1,259 @@
+export const meta = {
+  name: 'cost-tiered-fix',
+  description: 'Fix a batch of independent tasks with tiered models: Opus plans and verifies, Haiku/Sonnet execute, low-confidence items escalate to Opus',
+  whenToUse: 'A list of independent, well-scoped fixes (many tickets, many files) — NOT one large stateful change, which belongs in a normal session with subagents',
+  phases: [
+    { title: 'Plan', detail: 'decompose the goal into tiered work items', model: 'opus' },
+    { title: 'Execute', detail: 'cheap executors, one isolated worktree per item' },
+    { title: 'Verify', detail: 'Opus reviews each branch diff', model: 'opus' },
+  ],
+}
+
+// Invoke with either:
+//   args: { goal: "...", runId?: "..." }                     -> Opus plans the decomposition
+//   args: { tasks: ["...", { task, tier }], runId?: "..." }  -> skip planning, run your list
+// runId (e.g. a ticket id or date string) namespaces branch names across runs;
+// Date.now()/Math.random() are unavailable in workflow scripts, so it must come
+// from the caller. Without it, executors resolve collisions by numeric suffix.
+// Each work item ends up as a committed branch plus an Opus verdict.
+// Merging approved branches is left to the main session.
+//
+// args.tiers optionally remaps the three rungs, e.g.
+//   { tiers: { cheap: 'haiku', normal: 'sonnet', judge: 'opus' } }
+// Workflow scripts have no filesystem access, so the canonical matrix in
+// config/models.json cannot be read here — the caller passes it through when
+// this machine's mapping differs from the defaults below.
+
+if (!args || (!args.goal && !Array.isArray(args.tasks))) {
+  throw new Error('cost-tiered-fix needs args: { goal: "..." } or { tasks: [...] }')
+}
+
+const BRANCH_PREFIX = args.runId ? `leos/fix-${args.runId}` : 'leos/fix'
+
+// Bare model aliases only — this is the documented subagent `model:` shape.
+// The 1m-extended-context suffix (square-bracket /model syntax) is a
+// /model-command / SKILL-frontmatter thing, not a valid subagent model
+// value; passing it here reaches the model selector verbatim and kills the
+// spawn (see the outage this repo just had). Do not add that suffix back.
+const TIERS = {
+  cheap: 'haiku',
+  normal: 'sonnet',
+  judge: 'opus',
+  ...(args.tiers || {}),
+}
+
+const PLAN_SCHEMA = {
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          task: { type: 'string', description: 'self-contained instruction: exact file paths, expected behavior, how to check it' },
+          tier: { type: 'string', enum: [TIERS.cheap, TIERS.normal], description: `${TIERS.cheap} for mechanical work, ${TIERS.normal} for normal implementation` },
+        },
+        required: ['task', 'tier'],
+      },
+    },
+  },
+  required: ['items'],
+}
+
+const EXEC_SCHEMA = {
+  type: 'object',
+  properties: {
+    branch: { type: 'string', description: 'the branch actually created and committed to; omit if no branch was created' },
+    summary: { type: 'string' },
+    checks: { type: 'string', description: 'what was run to verify, and the result' },
+    confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+  },
+  required: ['summary', 'confidence'],
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    approved: { type: 'boolean' },
+    issues: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['approved', 'issues'],
+}
+
+function execPrompt(task, branch) {
+  return [
+    'You are one executor in a fan-out. Work ONLY on this task; touch nothing else.',
+    `Task: ${task}`,
+    `You are in an isolated git worktree. Create and switch to branch ${branch} (if that name already exists, use the lowest free numeric suffix, e.g. ${branch}-2), implement the task, run the narrowest relevant check (tests/build for the touched files), and commit.`,
+    'Report the branch name you actually used. If the task is ambiguous or you cannot make the check pass, commit only what is safe and report confidence: low with the blocker in summary. If you created no branch, omit the branch field entirely — never invent one.',
+  ].join('\n')
+}
+
+// Next tier up the escalation ladder. The judge tier is the ceiling: it has
+// nowhere left to escalate to, so it maps to itself.
+function nextTier(tier) {
+  if (tier === TIERS.cheap) return TIERS.normal
+  return TIERS.judge
+}
+
+// Escalation must buy more than a model swap: the normal rung gets a wider
+// reasoning budget than the cheap rung it is replacing, or a cheap->normal
+// escalation would spend more money for the same effort that already failed.
+function effortFor(tier) {
+  return tier === TIERS.judge ? 'high' : tier === TIERS.normal ? 'medium' : 'low'
+}
+
+// Caller-supplied args.tasks bypasses the planning agent (and PLAN_SCHEMA's
+// validation with it), so entries need their own gate here: a bad `tier`
+// would flow straight into `model:` below, and a non-object/non-string entry
+// (e.g. null) would silently produce `task: undefined` fed to execPrompt.
+const ALLOWED_TIERS = new Set([TIERS.cheap, TIERS.normal])
+function validateTask(t, i) {
+  if (typeof t === 'string') return { task: t, tier: TIERS.normal }
+  if (t && typeof t === 'object' && typeof t.task === 'string') {
+    if (t.tier !== undefined && !ALLOWED_TIERS.has(t.tier)) {
+      throw new Error(`cost-tiered-fix: args.tasks[${i}].tier must be one of ${[...ALLOWED_TIERS].join(', ')}, got ${JSON.stringify(t.tier)}`)
+    }
+    return { tier: TIERS.normal, ...t }
+  }
+  throw new Error(`cost-tiered-fix: args.tasks[${i}] must be a string or an object with a string "task", got ${JSON.stringify(t)}`)
+}
+
+phase('Plan')
+let items
+if (Array.isArray(args.tasks)) {
+  items = args.tasks.map(validateTask)
+  log(`Using ${items.length} caller-provided tasks (planning skipped)`)
+} else {
+  const plan = await agent(
+    `Decompose this goal into independent, well-scoped work items that can each be done in an isolated worktree without touching the same files. For each item write a self-contained instruction (exact file paths, expected behavior, how to check it) and pick a tier: ${TIERS.cheap} for mechanical work, ${TIERS.normal} for normal implementation. At most 10 items — if the goal needs more, return the 10 highest-value and say so in the last item.\n\nGoal: ` + args.goal,
+    { label: 'plan', phase: 'Plan', model: TIERS.judge, effort: 'high', schema: PLAN_SCHEMA },
+  )
+  if (!plan || !Array.isArray(plan.items) || plan.items.length === 0) {
+    log('Planning agent failed or returned no items — aborting cleanly')
+    return { approved: [], rejected: [], note: 'planning agent died or produced no work items; nothing was run' }
+  }
+  items = plan.items
+  log(`Planned ${items.length} work items`)
+}
+if (items.length > 10) {
+  log(`Capping fan-out: running the first 10 of ${items.length} items`)
+  items = items.slice(0, 10)
+}
+
+// pipeline(): no barrier between stages — item 0 can be verifying while item 3
+// is still executing. Wall-clock is the slowest single item, not the sum.
+const results = await pipeline(
+  items,
+
+  // Stage 1 — execute cheap (haiku/sonnet, effort low: the cost levers)
+  (item, _orig, i) =>
+    agent(execPrompt(item.task, `${BRANCH_PREFIX}-${i}`), {
+      label: `exec-${i}:${item.tier}`,
+      phase: 'Execute',
+      model: item.tier,
+      effort: 'low',
+      isolation: 'worktree',
+      schema: EXEC_SCHEMA,
+    }),
+
+  // Stage 2 — escalation ladder:
+  //   - confident result (non-null, confidence !== 'low') -> return as-is, no escalation.
+  //   - null result -> ONE retry at the same tier (haiku retries at sonnet, since
+  //     haiku already failed cheap); if that retry is also null/low, ONE escalation to
+  //     the next tier up.
+  //   - low-confidence result -> ONE escalation exactly one rung up.
+  //   Stop at the first confident attempt. Every superseded attempt's branch is
+  //   collected into supersededBranches so the tail can flag it as an orphan.
+  async (run, item, i) => {
+    if (run && run.confidence !== 'low') return run
+
+    const supersededBranches = []
+
+    async function attempt(tier, suffix, priorSummary) {
+      const branch = `${BRANCH_PREFIX}-${i}-${suffix}`
+      return agent(
+        execPrompt(item.task, branch) +
+          `\n\nA cheaper model already attempted this and reported: "${priorSummary}". Start from the task itself on a fresh branch off the same base as mainline — do NOT build on the earlier attempt's branch.`,
+        { label: `escalate-${i}-${suffix}`, phase: 'Execute', model: tier, effort: effortFor(tier), isolation: 'worktree', schema: EXEC_SCHEMA },
+      )
+    }
+
+    let result
+    let finalTier
+    if (!run) {
+      const retryTier = item.tier === TIERS.cheap ? TIERS.normal : item.tier
+      finalTier = retryTier
+      log(`Item ${i} produced no result — retrying at ${retryTier}`)
+      result = await attempt(retryTier, 'r2', 'no result (agent failed)')
+      if (!result || result.confidence === 'low') {
+        if (result && result.branch) supersededBranches.push(result.branch)
+        const escTier = nextTier(retryTier)
+        finalTier = escTier
+        log(`Item ${i} still ${result ? 'low confidence' : 'no result'} at ${retryTier} — escalating to ${escTier}`)
+        result = await attempt(escTier, 'r3', result ? result.summary : 'no result on retry')
+      }
+    } else {
+      if (run.branch) supersededBranches.push(run.branch)
+      const escTier = nextTier(item.tier)
+      finalTier = escTier
+      log(`Item ${i} low confidence — escalating to ${escTier}`)
+      result = await attempt(escTier, 'r2', run.summary)
+    }
+
+    // "escalated" means the work actually moved up a rung. A same-tier retry
+    // (a null result at a tier that is already the ceiling) is not one.
+    const escalated = finalTier !== item.tier
+
+    if (!result) {
+      // Every attempt failed, but earlier attempts may already have created
+      // branches. Returning null here would drop supersededBranches and leave
+      // those branches out of the orphan report — invisible litter in the repo.
+      return { summary: 'every attempt failed; no usable result', confidence: 'low', supersededBranches, escalated }
+    }
+    return { ...result, supersededBranches, escalated }
+  },
+
+  // Stage 3 — Opus verifies the actual diff, not the executor's self-report.
+  // Stage 2 always returns an object (never null — see its final `return`s
+  // above), so `run` here is never null; no null-guard needed.
+  async (run, item, i) => {
+    if (!run.branch) {
+      return { task: item.task, ...run, verdict: { approved: false, issues: ['executor reported no branch — nothing to review'] } }
+    }
+    // agentType pulls in the canonical reviewer rubric (roles/reviewer.md)
+    // instead of the weaker inline restatement this used to carry.
+    const verdict = await agent(
+      [
+        `Review branch ${run.branch} against this task: "${item.task}".`,
+        `Diff scope: git diff $(git merge-base HEAD ${run.branch}) ${run.branch}`,
+        `First check the branch is reviewable: git rev-parse --verify ${run.branch} and git diff --stat $(git merge-base HEAD ${run.branch}) ${run.branch}. If the branch is missing or the diff is empty, return approved: false with issue "no reviewable diff".`,
+        `Executor self-report (do not trust it, verify it): ${run.summary} — checks: ${run.checks || 'none reported'}`,
+      ].join('\n'),
+      { label: `verify-${i}`, phase: 'Verify', agentType: 'leo:reviewer', model: TIERS.judge, effort: 'medium', schema: VERDICT_SCHEMA },
+    )
+    return { task: item.task, ...run, verdict }
+  },
+)
+
+const done = results.filter(Boolean)
+const approved = done.filter(r => r.verdict && r.verdict.approved)
+const rejected = done.filter(r => !r.verdict || !r.verdict.approved)
+log(`${approved.length} approved, ${rejected.length} rejected, ${items.length - done.length} failed to run`)
+
+// Orphan tracking: only superseded retries (an earlier attempt's branch that
+// got superseded by a later, kept attempt on the SAME item) are safe to
+// delete — that work is duplicated by the branch that replaced it. A
+// rejected branch is different: it may be the only copy of that item's
+// work, just judged not good enough yet, so it is reported separately and
+// never described as safe to delete — deleting it on the note's say-so
+// would destroy the only copy.
+const orphans = [...new Set(done.flatMap(r => r.supersededBranches || []).filter(Boolean))]
+const kept = approved.map(r => r.branch).filter(Boolean)
+
+return {
+  approved: approved.map(r => ({ task: r.task, branch: r.branch, escalated: !!r.escalated })),
+  rejected: rejected.map(r => ({ task: r.task, branch: r.branch || null, issues: r.verdict ? r.verdict.issues : ['agent failed, no verdict'] })),
+  orphans,
+  note: `Approved (merge these from the main session): ${kept.join(', ') || 'none'}. Orphaned (superseded retries — safe to delete): ${orphans.join(', ') || 'none'}. Rejected branches hold work that failed review but may still be worth salvaging — do NOT delete them without reviewing first: ${rejected.map(r => r.branch).filter(Boolean).join(', ') || 'none'}. To clean up an orphan: \`git worktree list\` to find its path, then \`git worktree remove <path>\` (prune does not remove live worktrees).`,
+}