@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/src/review-round.ts

@@ -0,0 +1,335 @@
+/**
+ * T36 — the turn-shaped review driver: start → park → resume → repair.
+ *
+ * WHY A STATE MACHINE AND NOT A LOOP. The harness offers no parent-side
+ * await-settlement promise: a continuable child's verdict arrives as a durable user
+ * message on a LATER turn. So a review cannot be one function call that waits. It is
+ * a sequence of turns, each of which either advances the round or honestly reports
+ * that it is waiting — and the child id has to survive between those turns, which is
+ * what the state file here is for. A tool call is the agent's only interface, so the
+ * driver is designed to be driven once per turn, exactly like `recursive_audit_team`
+ * advances the teams board one transition per call.
+ *
+ * THE FOUR OUTCOMES THAT MATTER:
+ *   `reviewing`   the child has not settled yet — call again later
+ *   `revised`     the round came back REVISE, so a repair instruction went to the
+ *                 SAME child and the driver is waiting for the re-submission
+ *   `approved`    a settled round read APPROVE and the work is accepted
+ *   `rejected`    a settled round read REJECT — the reviewer says do not proceed
+ * `unavailable` is the fifth, and it is not a failure of the work: it means the
+ * delegation could not run continuably at all, so the repair path does not exist.
+ * Naming that is the whole point of T35's `delegationMode`.
+ *
+ * THE VERDICT IS READ FROM `reply.md`, FAIL-CLOSED. A settlement carries free-form
+ * text, and the loop's structured reader treats "no verdict" as APPROVE; a review
+ * round must not. `readVerdictFromReply` is used instead, so prose, an empty reply
+ * or an off-vocabulary answer becomes REVISE with a repair instruction rather than a
+ * false approval.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { readRepairFromReply, readVerdictFromReply, type ContinuableDelegationLike, type DelegationVerdict } from './delegation.ts'
+
+/** The durable record of an in-flight review, so the next turn can resume it. */
+export interface ReviewState {
+  delegationId: string
+  /** The durable child carrying this review, stable across turns. */
+  childId: string
+  phase: string
+  role: string
+  /** How many rounds the loop has observed so far. */
+  rounds: number
+  startedAt: string
+  lastVerdict?: DelegationVerdict
+  /**
+   * ⚠ FU-17 — whether this round carries a VERDICT (`review`) or a DELIVERABLE (`work`). Optional and defaulted
+   * on read, so a state file written before this field existed still means what it always meant.
+   */
+  kind?: 'review' | 'work'
+}
+
+export interface AdvanceReviewOutcome {
+  status: 'reviewing' | 'revised' | 'approved' | 'rejected' | 'unavailable' | 'submitted'
+  childId?: string
+  verdict?: DelegationVerdict
+  rounds: number
+  /** One sentence for the agent, saying what to do next. */
+  message: string
+}
+
+/** Where one delegation's review state lives (beside its handoff and replies). */
+export function reviewStatePath(runDir: string, delegationId: string): string {
+  return join(runDir, 'subagents', delegationId, 'review-state.json')
+}
+
+/** Read an in-flight review, or null when there is none (or it is unreadable). */
+export function readReviewState(runDir: string, delegationId: string): ReviewState | null {
+  let raw: string
+  try {
+    raw = readFileSync(reviewStatePath(runDir, delegationId), 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<ReviewState> | null
+    if (parsed === null || typeof parsed !== 'object') return null
+    if (typeof parsed.childId !== 'string' || parsed.childId === '') return null
+    if (typeof parsed.delegationId !== 'string') return null
+    const state: ReviewState = {
+      delegationId: parsed.delegationId,
+      childId: parsed.childId,
+      phase: typeof parsed.phase === 'string' ? parsed.phase : '',
+      role: typeof parsed.role === 'string' ? parsed.role : '',
+      rounds: typeof parsed.rounds === 'number' && Number.isFinite(parsed.rounds) ? parsed.rounds : 0,
+      startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : '',
+    }
+    if (parsed.lastVerdict === 'APPROVE' || parsed.lastVerdict === 'REVISE' || parsed.lastVerdict === 'REJECT') {
+      state.lastVerdict = parsed.lastVerdict
+    }
+    return state
+  } catch {
+    // A corrupt state file means "no known review", never a crash: the worst case is
+    // that a fresh review starts, which the caller can see from the returned status.
+    return null
+  }
+}
+
+export function writeReviewState(runDir: string, state: ReviewState): string {
+  const path = reviewStatePath(runDir, state.delegationId)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf8')
+  return path
+}
+
+/** Forget a finished review. A finished review must not be resumable by accident. */
+export function clearReviewState(runDir: string, delegationId: string): void {
+  const path = reviewStatePath(runDir, delegationId)
+  if (existsSync(path)) rmSync(path, { force: true })
+}
+
+/**
+ * Advance one review by exactly one turn.
+ *
+ * `delegate` is injected rather than called directly so this driver can be tested
+ * against a scripted loop, and so the caller owns how the review is dispatched
+ * (which provider, which bundle, which parent). It receives `resumeChild` when a
+ * child is already carrying the review — a resumed round must NEVER re-establish
+ * the child, which would orphan the one already doing the work.
+ */
+export async function advanceReview(input: {
+  runDir: string
+  delegationId: string
+  phase: string
+  role: string
+  /** Dispatch one turn of the continuable loop, resuming `resumeChild` when given. */
+  delegate: (args: { resumeChild?: string }) => Promise<ContinuableDelegationLike>
+  /** The child's reply text for the settled round, or '' when it has not written one. */
+  readReply: (childId: string) => string
+  /**
+   * Deliver a repair instruction to the child.
+   *
+   * NEEDED BECAUSE THE LOOP CAN STOP EARLY ON A MISREAD. The loop's own verdict
+   * reader falls back to APPROVE when a result carries no structured verdict, so a
+   * child that answered in prose can make the loop believe it was approved and
+   * END — leaving no repair sent and the child idle. This driver re-reads the reply
+   * fail-closed and disagrees, so it must be able to send the repair itself;
+   * otherwise the round would sit in `revised` forever with nothing ever asking the
+   * child to fix anything.
+   */
+  sendRepair?: (childId: string, instruction: string) => Promise<void>
+  now?: () => string
+  /**
+   * ⚠ FU-17 — WHICH KIND OF ROUND THIS IS, and it defaults to `'review'`.
+   *
+   * The kind is a PARAMETER rather than a forked code path, so every existing caller and spec keeps the exact
+   * behaviour it had — that is what makes "review is unchanged" a proof instead of a hope. A `'work'` round is
+   * the same round: same child, same state file, same park-and-resume mechanics, same repair delivery. The one
+   * difference is what a settlement MEANS: a work round's settlement is a DELIVERABLE, so the driver must not
+   * read an APPROVE out of prose that was never a verdict.
+   */
+  kind?: 'review' | 'work'
+  /**
+   * The main agent's feedback for a `'work'` round — delivered to the SAME child, which then repairs with its
+   * working set intact. Ignored for reviews, whose repair text is read from the reviewer's own reply.
+   */
+  instruction?: string
+}): Promise<AdvanceReviewOutcome> {
+  const { runDir, delegationId } = input
+  const kind = input.kind ?? 'review'
+  const state = readReviewState(runDir, delegationId)
+  const resumeChild = state?.childId
+
+  let result: ContinuableDelegationLike
+  try {
+    result = await input.delegate(resumeChild === undefined ? {} : { resumeChild })
+  } catch (err) {
+    return {
+      status: 'unavailable',
+      childId: resumeChild,
+      rounds: state?.rounds ?? 0,
+      message: 'the review could not be dispatched: ' + (err instanceof Error ? err.message : String(err)),
+    }
+  }
+
+  // The delegation ran, but not continuably: the review happened without the repair
+  // path. Named, never hidden behind a success — this is T35's whole reason.
+  if (result.fellBackToOneShot === true) {
+    // ⚠ FU-9 — AND SAY WHICH CONDITION, when the delegation kept it. The sentence below used to name two
+    // possibilities for a branch that covers three, so a live run's cause was undecidable from its own report.
+    return {
+      status: 'unavailable',
+      rounds: result.rounds.length,
+      message: 'the review ran WITHOUT the continuable repair path'
+        + (result.reason !== undefined
+          ? ' — ' + result.reason + ' — so a failed review cannot be sent back to the child that did the work'
+          : ' (no continuable seam or no live parent), so a failed review cannot be sent back to the child that did the work'),
+    }
+  }
+
+  const childId = result.childId ?? resumeChild
+  const rounds = result.rounds.length
+  const repaired = result.rounds.some((round) => (round as { revise?: boolean }).revise === true)
+
+  if (result.parked === true) {
+    // Still working, or a repair was just sent and we are waiting for the re-submission.
+    if (childId !== undefined) {
+      writeReviewState(runDir, {
+        delegationId,
+        childId,
+        phase: input.phase,
+        role: input.role,
+        rounds,
+        startedAt: state?.startedAt ?? (input.now ?? defaultNow)(),
+        ...(repaired ? { lastVerdict: 'REVISE' as const } : {}),
+      })
+    }
+    return repaired
+      ? {
+        status: 'revised',
+        childId,
+        verdict: 'REVISE',
+        rounds,
+        message: 'the review came back REVISE; a repair instruction was delivered to the SAME child '
+          + '(childId ' + String(childId) + '). Call recursive_review again after it settles.',
+      }
+      : {
+        status: 'reviewing',
+        childId,
+        rounds,
+        message: 'the review is still running (childId ' + String(childId) + '). No settlement has landed yet; '
+          + 'call recursive_review again after it settles.',
+      }
+  }
+
+  // ⚠ FU-17 — A WORK ROUND ENDS AT ITS DELIVERABLE, and nothing is read out of it. A review must fail closed
+  // (prose is not an approval); a WORK round has no verdict to fail closed ON, so parsing one would manufacture
+  // a judgement the child never made. The main agent judges — that is the whole point of delegating work to a
+  // child and keeping the decision in the parent.
+  if (kind === 'work') {
+    const childId = result.childId ?? resumeChild
+    const rounds = result.rounds.length
+    // The main agent's feedback, when it has any: delivered to the SAME child so the repair keeps its context.
+    const feedback = input.instruction?.trim() ?? ''
+    if (feedback !== '' && childId !== undefined && input.sendRepair !== undefined) {
+      try {
+        await input.sendRepair(childId, feedback)
+      } catch {
+        // The instruction could not be delivered; the child is still kept, so a later call can retry.
+        return {
+          status: 'unavailable',
+          childId,
+          rounds,
+          message: 'the work round settled, but the feedback could not be delivered to the child ('
+            + String(childId) + '); it is kept, so call again to retry',
+        }
+      }
+      return {
+        status: 'revised',
+        childId,
+        rounds,
+        message: 'feedback was delivered to the SAME child (' + String(childId)
+          + '); call again after its re-submission settles',
+      }
+    }
+    return {
+      status: 'submitted',
+      childId,
+      rounds,
+      message: 'the delegated work is in: read the child\'s reply and judge it. Send feedback with the delegate '
+        + 'tool if it is not good enough — the same child will repair it.',
+    }
+  }
+
+  // A settled round: read the verdict from the child's own reply, FAIL-CLOSED.
+  const replyText = childId === undefined ? '' : input.readReply(childId)
+  const verdict = readVerdictFromReply(replyText)
+
+  if (result.accepted && verdict === 'APPROVE') {
+    clearReviewState(runDir, delegationId)
+    return { status: 'approved', childId, verdict, rounds, message: 'the review passed: verdict APPROVE.' }
+  }
+  if (verdict === 'REJECT') {
+    clearReviewState(runDir, delegationId)
+    return {
+      status: 'rejected',
+      childId,
+      verdict,
+      rounds,
+      message: 'the reviewer rejected the work: verdict REJECT. Do not proceed; resolve it before locking.',
+    }
+  }
+
+  // Anything else — an unreadable reply, a stopped child, a REVISE the loop ended on —
+  // is a REPAIR, not a pass: keep the state so the child can be told to fix it, and
+  // TELL IT, since the loop may have stopped believing it was approved.
+  if (childId !== undefined) {
+    writeReviewState(runDir, {
+      delegationId,
+      childId,
+      phase: input.phase,
+      role: input.role,
+      rounds,
+      startedAt: state?.startedAt ?? (input.now ?? defaultNow)(),
+      lastVerdict: 'REVISE',
+    })
+  }
+  let repairSent = false
+  if (childId !== undefined && input.sendRepair !== undefined) {
+    try {
+      await input.sendRepair(childId, readRepairFromReply(replyText))
+      repairSent = true
+    } catch {
+      // The repair could not be delivered; the child is still kept, so a later turn
+      // can retry. Reported below rather than swallowed.
+    }
+  }
+  // BOTH facts are always stated: WHY the round is a repair, and what happened to
+  // the child — because a caller that does not know the child was kept cannot know
+  // whether a later turn can still repair it.
+  const why = result.accepted
+    ? 'the reviewer approved, but the reply could not be read as an APPROVE; treated as REVISE so it is not '
+      + 'accepted on a technicality.'
+    : 'the round ended without an approval.'
+  const what = repairSent
+    ? ' A repair instruction was sent to the SAME child.'
+    : ' The child is kept so the repair can be sent to it.'
+  // ⚠ FU-9 — AND SAY WHY THE DELEGATION SAYS SO, when it says anything. `rounds: 0` plus a canned sentence hid
+  // one of THREE named failure branches (a caught error, "no continuable interrupt seam", "REVISE verdict
+  // without a repair instruction") for two rounds of live runs. The reason was already in the result and this
+  // message simply did not print it — the ninth surface in this sequence that could not say what the code knew.
+  // ADDITIVE: a result carrying no reason produces exactly the message it always did, so no caller changes.
+  const detail = result.reason !== undefined && result.reason !== ''
+    ? ' The delegation reported: ' + result.reason + '.'
+    : ''
+  return {
+    status: 'revised',
+    childId,
+    verdict: 'REVISE',
+    rounds,
+    message: why + what + detail,
+  }
+}
+
+function defaultNow(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')
+}

package/src/review.ts

@@ -33,6 +33,15 @@ export interface ReviewBundleInput {
   addenda?: string[]
   priorEvidence?: string[]
   memoryRefs?: string[]
+  /**
+   * T14 — the RETRIEVED prior-run memory, rendered, written into the bundle body.
+   *
+   * ⚠ `memoryRefs` above is the slot the bundle already had, and nothing ever filled it — so the
+   * memory section a reviewer was supposed to see did not exist. The two are complementary, not
+   * duplicates: `memoryRefs` is WHERE the memory lives (traceability), and this is the CONTENT,
+   * because a reviewer cannot cite a path whose contents it was never given.
+   */
+  memory?: string
   changedFiles?: string[]
 }
 
@@ -79,8 +88,7 @@ function pathList(title: string, values: string[]): string[] {
  * when a path would escape the workspace root (fail loud, never a silent
  * bundle).
  */
-export function buildReviewBundle(input: ReviewBundleInput): ReviewBundleResult {
-  const { root, runId, phase, role } = input
+export function buildReviewBundle(input: ReviewBundleInput): ReviewBundleResult {  const { root, runId, phase, role } = input
   const runDir = resolveUnderRoot(root, '.recursive/run/' + runId)
   if (!existsSync(runDir)) {
     throw new Error('Run directory does not exist: ' + runId)
@@ -162,7 +170,13 @@ export function buildReviewBundle(input: ReviewBundleInput): ReviewBundleResult
   ]
 
   const markdown = lines.join('\n')
-  writeFileSync(bundlePath, markdown, 'utf8')
+  // T14: the retrieved prior-run memory goes INTO the bundle, because the prompt references the
+  // bundle by PATH — a section appended to the prompt instead would sit outside the document the
+  // reviewer is told to read, and a reviewer that cites memory must be citing what it was given.
+  const withMemory = input.memory === undefined || input.memory.trim() === ''
+    ? markdown
+    : markdown + '\n\n## Prior-run memory\n\n' + input.memory.trim() + '\n'
+  writeFileSync(bundlePath, withMemory, 'utf8')
 
   return {
     bundlePath,

package/src/role-route.ts

@@ -0,0 +1,230 @@
+/**
+ * T9 → FU-19 — per-role model routing, and now a full provider/model ladder.
+ *
+ * WHY. A delegation would otherwise run on whatever model the child inherits: the reviewer that must be rigorous
+ * and the repairer that will iterate many times become the same choice by accident. The item asks for them to
+ * differ — and FU-19 extends that to a general default, per-phase overrides, and a per-call choice.
+ *
+ * ⚠ THE PARAGRAPH THAT USED TO BE HERE WAS TRUE WHEN WRITTEN AND IS NOW FALSE, so it is replaced rather than
+ * left to mislead. It said the plugin "cannot by itself force a child onto a model", because
+ * `SubagentStartRequestLike` had no model field and model selection was the host's concern. Both halves changed:
+ * the harness accepts `agentOptions` on a start, and `delegateReview` now sets `request.agentOptions = { model }`
+ * — but ONLY for a provider that declares the `agentOptions` capability, because the harness REJECTS such a start
+ * otherwise.
+ *
+ * SO WHAT THIS MODULE PROMISES TODAY, precisely:
+ *   - it resolves WHICH provider and model a child should get, from the ladder in `resolveSubagentTarget`, and it
+ *     reports which level chose each value;
+ *   - the caller (not this module) applies them, because applying is a decision with consequences — a model on a
+ *     provider that cannot take overrides is NOT applied and is REPORTED rather than silently dropped;
+ *   - and the model is checked against what DSH actually has (`model-inventory.ts`), with an `unverified` verdict
+ *     when there is no inventory to ask, so a choice is never silently approved OR silently replaced.
+ *
+ * A module that claimed more than that would be lying about where the choice is made. The comment above is the
+ * second half of that lesson: a stale rationale is how a working feature gets deleted by accident.
+ */
+import type { RouterPolicy } from './router.ts'
+
+/** What kind of work a role does — the distinction the item is about. */
+export type RoleKind = 'review' | 'repair' | 'unknown'
+
+/**
+ * The roles this plugin scaffolds, classified by the JOB rather than by seniority.
+ *
+ * Review work wants rigour and reads carefully once; repair work wants many cheap iterations.
+ * An unrecognised role is `unknown` rather than silently assumed to be a reviewer: assuming
+ * would put an unreviewed role on the expensive path (or a reviewer on the cheap one) with no
+ * signal anywhere, which is the sort of quiet mismatch this item exists to remove.
+ */
+const REVIEW_ROLES: readonly string[] = ['code-reviewer', 'memory-auditor', 'auditor', 'reviewer']
+const REPAIR_ROLES: readonly string[] = ['implementer', 'repairer', 'fixer']
+
+export function roleKindOf(role: string): RoleKind {
+  const normalised = role.trim().toLowerCase()
+  if (REVIEW_ROLES.includes(normalised)) return 'review'
+  if (REPAIR_ROLES.includes(normalised)) return 'repair'
+  return 'unknown'
+}
+
+/** One role's resolved route: what kind of work it is, and which model the policy names. */
+export interface RoleRoute {
+  role: string
+  kind: RoleKind
+  /** The policy's model for this role, or null when it names none. */
+  model: string | null
+  /** Where the model came from — `unset` is a fact worth carrying, not an absence. */
+  source: 'policy' | 'unset'
+  /** One self-sufficient sentence, including the unknown-role case. */
+  reason: string
+}
+
+/**
+ * Resolve a role's route from the policy.
+ *
+ * Never throws and never invents a model: an unknown role, an unconfigured role and a role whose
+ * policy entry names no model each produce a route with a reason that says which it is. A caller
+ * that wants to refuse an unknown role can; a caller that wants to proceed knows exactly what it
+ * is proceeding with.
+ */
+export function routeForRole(role: string, policy: RouterPolicy): RoleRoute {
+  const kind = roleKindOf(role)
+  const configured = policy.role_routes?.[role]
+  const model = typeof configured?.model === 'string' && configured.model.trim() !== '' ? configured.model : null
+  const source: RoleRoute['source'] = model === null ? 'unset' : 'policy'
+
+  if (kind === 'unknown') {
+    return {
+      role,
+      kind,
+      model,
+      source,
+      reason: 'role ' + role + ' is not a role this plugin classifies, so no review/repair expectation is asserted for it'
+        + (model === null ? ' and the policy names no model.' : ' (the policy does name model ' + model + ').'),
+    }
+  }
+  if (model === null) {
+    return {
+      role,
+      kind,
+      model,
+      source,
+      reason: kind + ' role ' + role + ' has no model in the policy, so it inherits the child default'
+        + ' — the review/repair split is NOT in effect for it.',
+    }
+  }
+  return {
+    role,
+    kind,
+    model,
+    source,
+    reason: kind + ' role ' + role + ' resolves to model ' + model + ' from the policy.',
+  }
+}
+
+/**
+ * The model the caller should use for a role, or null to inherit.
+ *
+ * A one-line convenience for a caller that only needs the value; {@link routeForRole} is what a
+ * caller should use when it wants to SAY why.
+ */
+export function modelForRole(role: string, policy: RouterPolicy): string | null {
+  return routeForRole(role, policy).model
+}
+
+/**
+ * ⚠ FU-19 — WHICH PROVIDER AND MODEL A DELEGATED CHILD WOULD ACTUALLY GET, AND WHO CHOSE EACH.
+ *
+ * ## The words, because they were doing too much work
+ *
+ * "Provider" is the thing that CREATES a child. In this harness it is resolved by a tier ladder, and the tiers
+ * have names that are not self-explanatory:
+ *
+ *   - **native** — a provider the harness runs ITSELF, in-process. It is what `ctx.subagents` serves; in the
+ *     session I measured it advertised exactly two: `spawn` and `fork`. "Native" means "the harness's own",
+ *     as opposed to something it shells out to.
+ *   - **external-cli** — a registered provider that drives a SEPARATE installed program (Codex, Claude Code and
+ *     friends). A child still exists, but the work happens in another process the user installed.
+ *   - **self-audit** — no child is created at all: the main agent reviews its own work. This is the honest
+ *     fallback, and it is NAMED rather than hidden.
+ *   - **local-controller** — the host's own controller. I have not measured this tier's behaviour in a live
+ *     session, so I will not describe it further here.
+ *
+ * ## Why "a provider but no model" — the part my earlier wording got wrong
+ *
+ * A MODEL CAN BE LEFT UNSET ON PURPOSE, AND THAT IS NOT THE SAME AS "NO MODEL". Absent means **inherited**: the
+ * plugin sends no `agentOptions.model` at all, and the child runs on whatever the session/provider default is.
+ * That is the measured behaviour — `delegation.ts` forwards `agentOptions` only when the caller supplies them,
+ * and `modelForRole` returns null precisely to mean "inherit".
+ *
+ * So the floor of the ladder is not a gap. A child cannot exist without a provider, so a provider is always
+ * resolved (by the ladder, or by the user); a model is only sent when someone actually chose one, because
+ * inventing one would silently override the session's own setting — and overriding a user's session default
+ * without being asked is worse than inheriting it.
+ *
+ * ## The precedence, and the labels it reports
+ *
+ *   per-call override  →  phase route  →  role route  →  general default  →  inherit
+ *
+ * Every value carries the label of the level that produced it, so "why did this child run on that model?" is
+ * answerable from the decision alone rather than by reading this function.
+ */
+export interface SubagentTarget {
+  role: string
+  /** The provider that would create the child, or null when nothing resolved one. */
+  provider: string | null
+  /** The model to ask for, or null meaning INHERIT — do not send `agentOptions.model` at all. */
+  model: string | null
+  /** Plain-language provenance for each value: which level chose it. */
+  chosen: { provider: string; model: string }
+  /** One sentence a reader can act on. */
+  reason: string
+}
+
+/** Which level produced a value. `inherit` is a decision, not an absence. */
+export type ChoiceSource = 'per-call' | 'phase' | 'role' | 'general' | 'ladder' | 'inherit'
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null
+}
+
+export function resolveSubagentTarget(input: {
+  role: string
+  /** The phase the delegation is for, when it is known — the narrowest configured level. */
+  phase?: string
+  policy: RouterPolicy
+  /** A per-call override from the tool: wins over every configured level. */
+  override?: { provider?: string | null; model?: string | null }
+  /** What the tier ladder resolved. Used when no level named a provider, and labelled as the ladder's. */
+  ladderProvider?: string | null
+}): SubagentTarget {
+  const { role, policy } = input
+  const phase = input.phase?.trim() ?? ''
+  const phaseRoute = phase === '' ? undefined : policy.phase_routes?.[phase]
+  const roleRoute = policy.role_routes?.[role]
+  const general = policy.defaults.subagent
+
+  const pick = (value: string | null | undefined, source: ChoiceSource): { value: string | null; source: ChoiceSource } =>
+    ({ value: nonEmpty(value), source })
+
+  const providerChoice = [
+    pick(input.override?.provider, 'per-call'),
+    pick(phaseRoute?.provider, 'phase'),
+    pick(roleRoute?.provider, 'role'),
+    pick(general?.provider, 'general'),
+    pick(input.ladderProvider, 'ladder'),
+  ].find((candidate) => candidate.value !== null) ?? { value: null, source: 'inherit' as ChoiceSource }
+
+  const modelChoice = [
+    pick(input.override?.model, 'per-call'),
+    pick(phaseRoute?.model, 'phase'),
+    pick(roleRoute?.model, 'role'),
+    pick(general?.model, 'general'),
+  ].find((candidate) => candidate.value !== null) ?? { value: null, source: 'inherit' as ChoiceSource }
+
+  const where = (source: ChoiceSource): string => {
+    switch (source) {
+      case 'per-call': return 'this call'
+      case 'phase': return 'the phase ' + phase + ' override'
+      case 'role': return 'the ' + role + ' role route'
+      case 'general': return 'the general subagent default'
+      case 'ladder': return 'the provider ladder'
+      default: return 'nothing — it is inherited'
+    }
+  }
+
+  const providerText = providerChoice.value === null
+    ? 'no provider was resolved'
+    : providerChoice.value + ' (from ' + where(providerChoice.source) + ')'
+  const modelText = modelChoice.value === null
+    ? 'no model is sent, so the child inherits the session default'
+    : modelChoice.value + ' (from ' + where(modelChoice.source) + ')'
+
+  return {
+    role,
+    provider: providerChoice.value,
+    model: modelChoice.value,
+    chosen: { provider: providerChoice.source, model: modelChoice.source },
+    reason: 'child for role ' + role + (phase === '' ? '' : ' in phase ' + phase) + ': provider ' + providerText
+      + '; model ' + modelText + '.',
+  }
+}