dsh-llm-verifier 0.3.1 → 0.4.0

package/src/router.ts

@@ -44,8 +44,20 @@ export interface RouterPolicy {
   mode: AutoVerifyMode
   minConfidence: number
   maxCandidates: number
-  maxPerTask: number
-  maxPerSession: number
+  /**
+   * Automatic route attempts (semantic classification, plan pre-review, team-task gate and
+   * compare/select/track) allowed within one task and one session.
+   *
+   * Routing and the final acceptance are metered by SEPARATE counters on purpose. They used
+   * to share one, which let routing spend the final gate's share: the gate is mandatory once
+   * armed (finalRequiredFromSeq), so a busy task could exhaust the shared counter on routes
+   * and then close the turn with the gate never having run.
+   */
+  maxRoutePerTask: number
+  maxRoutePerSession: number
+  /** Attempts reserved for the final acceptance; routing can never spend these. */
+  maxFinalPerTask: number
+  maxFinalPerSession: number
   maxModelCallsPerTask: number
   maxModelCallsPerSession: number
   maxInputChars: number
@@ -55,14 +67,22 @@ export interface RouterPolicy {
 interface Reservation { id: string; phase: RoutePhase; fingerprint: string; taskStartSeq: number }
 interface RouterState {
   taskStartSeq: number
-  taskAttempts: number
-  sessionAttempts: number
+  routeAttempts: number
+  finalAttempts: number
+  sessionRouteAttempts: number
+  sessionFinalAttempts: number
   taskModelCalls: number
   sessionModelCalls: number
   completed: Set<string>
   failed: Set<string>
   inFlight?: Reservation
   finalRequiredFromSeq?: number
+  /**
+   * Armed when a track route already cleared the completion threshold. The next stop
+   * boundary then skips automatic routing and runs the mandatory final gate instead of
+   * paying for another progress route whose steered text would be identical.
+   */
+  finalPreferred: boolean
   strictBlocked: boolean
 }
 
@@ -163,11 +183,12 @@ export function buildEvidenceIndex(events: readonly SessionEvent[]): EvidenceInd
   // Track the rolling view of team tasks across the session
   const currentTeamTasks = new Map<string, TeamTaskItem>()
   let narration: { seq: number; text: string } | undefined
-  // Tool names each wrapper call (a `run_code` program) dispatched, keyed by the
-  // wrapper's callId. Session V3 carries rootCallId on the dispatch event, which is the
-  // only reliable parent link: the wrapper's own result text is a concatenation of its
-  // sub-results, so the tool name of the wrapper says nothing about what it did.
-  const dispatchedTools = new Map<string, Set<string>>()
+  // What each wrapper call (a `run_code` program) dispatched, keyed by the wrapper's
+  // callId: how many sub-calls it made and whether any of them produced evidence.
+  // Session V3 carries rootCallId on the dispatch event, which is the only reliable
+  // parent link: the wrapper's own result text is a concatenation of its sub-results,
+  // so the tool name of the wrapper says nothing about what it did.
+  const dispatchedWork = new Map<string, { count: number; evidence: boolean }>()
 
   for (const rawEvent of relevant) {
     const event = rawEvent as unknown as { type: string; seq: number; data: any }
@@ -192,9 +213,10 @@ export function buildEvidenceIndex(events: readonly SessionEvent[]): EvidenceInd
       const data = event.data as { rootCallId?: string; subCallId?: string; name: string; isError?: boolean; content?: readonly ContentBlock[] }
       const rootCallId = typeof data.rootCallId === 'string' && data.rootCallId ? data.rootCallId : undefined
       if (rootCallId) {
-        const names = dispatchedTools.get(rootCallId) ?? new Set<string>()
-        names.add(data.name)
-        dispatchedTools.set(rootCallId, names)
+        const entry = dispatchedWork.get(rootCallId) ?? { count: 0, evidence: false }
+        entry.count += 1
+        if (isEvidenceOutput(data.name, Array.isArray(data.content) ? blockText(data.content) : '')) entry.evidence = true
+        dispatchedWork.set(rootCallId, entry)
       }
       const isOk = data.isError !== true && (!Array.isArray(data.content) || data.content.every(b => (b as { isError?: boolean }).isError !== true))
       if (isOk) {
@@ -208,11 +230,12 @@ export function buildEvidenceIndex(events: readonly SessionEvent[]): EvidenceInd
   for (const [callId, call] of calls) {
     const result = results.get(callId)
     if (!result) continue
-    // A wrapper that dispatched nothing but bookkeeping carries only their payloads
-    // (typically the todo list echoed straight back), so it is bookkeeping too. Its
-    // nested dispatches stay in the index under their own names, so real work done by
-    // the same program is still available as evidence.
-    if (onlyBookkeepingDispatches(dispatchedTools.get(callId))) continue
+    // A wrapper whose every dispatch was bookkeeping/coordination carries only their
+    // payloads (the todo list, or a "started subagent" acknowledgement, echoed straight
+    // back), so it is coordination too. Its nested dispatches stay in the index under
+    // their own names, so real work done by the same program is still available.
+    const dispatched = dispatchedWork.get(callId)
+    if (dispatched !== undefined && dispatched.count > 0 && !dispatched.evidence) continue
     paired.set(callId, { name: call.data.name, callSeq: call.seq, resultSeq: result.seq, text: blockText(result.data.message.content) })
   }
   return { problemSeq: taskStartSeq, calls: paired, todos, teamTasks, narration }
@@ -282,13 +305,174 @@ function canonicalTodoSnapshots(index: EvidenceIndex): Array<{ seq: number; todo
  */
 const BOOKKEEPING_TOOLS = new Set([
   'todo_write', 'create_goal', 'get_goal', 'update_goal', 'interrupt_agent', 'list_agents', 'exit_plan_mode', 'skill', 'present',
+  'job_list', 'job_kill', 'list_subagent_models', 'send_message',
 ])
 
-/** Whether a wrapper's dispatches were all bookkeeping; undefined/empty means it dispatched nothing. */
-function onlyBookkeepingDispatches(names: ReadonlySet<string> | undefined): boolean {
-  if (names === undefined || names.size === 0) return false
-  for (const name of names) if (!BOOKKEEPING_TOOLS.has(name)) return false
-  return true
+/**
+ * The plugin's own verdict tools.
+ *
+ * They must stay in the evidence index — {@link successfulExplicitKinds} reads it so an
+ * explicit route is not re-run automatically — but they are never rendered as observed
+ * work output: a judge grading progress from an earlier verdict would be grading itself,
+ * and a stale "passed" would grade as if the work behind it still stood.
+ */
+const VERIFIER_EVIDENCE_TOOLS = new Set(['verifier_compare', 'verifier_select', 'verifier_track', 'verifier_best_of_n', 'verifier_current_session'])
+
+/** Tools that return either a child's report (evidence) or a bare start acknowledgement (not evidence). */
+const SUBAGENT_TOOLS = new Set(['subagent', 'subagent_fork'])
+
+/**
+ * Start acknowledgement of a background child.
+ *
+ * `subagent`/`subagent_fork` cannot be excluded by name: a foreground call returns the
+ * child's report, a background one returns exactly `started subagent <childId>` (or
+ * `started background subagent job <id>`), which hides the output the child was asked to
+ * produce while looking like the newest "observed" result of the task.
+ */
+const CHILD_START_ACKNOWLEDGEMENT = /^started (?:background )?subagent\b/u
+
+/**
+ * Whether one settled tool result is evidence of work rather than coordination output.
+ *
+ * Single definition for every site that renders or offers evidence, so the checkpoint
+ * picker and the semantic router cannot disagree about what counts — the same
+ * disagreement produced the K-cap loop described on {@link BOOKKEEPING_TOOLS}.
+ * @param name - tool name that produced the result.
+ * @param text - rendered result text.
+ * @returns True when the result may be shown to a judge as observed output.
+ */
+function isEvidenceOutput(name: string, text: string): boolean {
+  if (BOOKKEEPING_TOOLS.has(name) || VERIFIER_EVIDENCE_TOOLS.has(name)) return false
+  const body = text.trim()
+  if (!body) return false
+  return !(SUBAGENT_TOOLS.has(name) && CHILD_START_ACKNOWLEDGEMENT.test(body))
+}
+
+/** Signatures of an output that reports verification results. */
+const VERIFICATION_SIGNATURES: readonly RegExp[] = [
+  /\bTest Files\s+\d+/u,
+  /\bTests?\s*:?\s*\d+\s+(?:passed|failed|skipped|todo)/iu,
+  /\bTest Suites?:\s*\d+/u,
+  /\b\d+\s+passed\b/u,
+  /\b(?:all\s+)?tests?\s+passed\b/iu,
+  /^\s*(?:ok|FAIL|PASS)\s+\S+/mu,
+  /\b(?:TEST|TYPECHECK|BUILD|LINT|CHECK|GATE)_EXIT\s*[:=]\s*0\b/u,
+]
+
+/**
+ * Whether an output looks like a test/typecheck/build run reporting its result.
+ *
+ * Only decides whether one extra evidence block is worth rendering. A miss degrades to
+ * the single-output rendering the checkpoints always had, and a false positive shows the
+ * judge one more observed result — neither can invent evidence.
+ * @param text - rendered tool result.
+ * @returns True when the text carries a runner-shaped summary.
+ */
+function looksLikeVerificationRun(text: string): boolean {
+  return VERIFICATION_SIGNATURES.some(pattern => pattern.test(text))
+}
+
+/**
+ * How much settled tool work followed one call, as a short histogram.
+ *
+ * Lets the judge decide whether a verification run still covers the current state
+ * ("nothing but issue replies since" versus "12 writes since") instead of guessing.
+ * Counts come from the evidence index, so a wrapper and its dispatches are each counted
+ * as the results they produced.
+ * @param index - evidence index of the current task.
+ * @param call - the call to measure from.
+ * @param maxChars - hard cap for the summary.
+ * @returns The summary text, or '' when nothing followed.
+ */
+function trailingSummary(index: EvidenceIndex, call: EvidenceCall, maxChars: number): string {
+  const counts = new Map<string, number>()
+  let total = 0
+  for (const other of index.calls.values()) {
+    if (other.resultSeq <= call.resultSeq) continue
+    total += 1
+    counts.set(other.name, (counts.get(other.name) ?? 0) + 1)
+  }
+  if (total === 0) return ''
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+  const summary = total + ' tool result(s) since, ' + ranked.slice(0, 4).map(([name, count]) => name + ' ×' + count).join(', ') + (ranked.length > 4 ? ', …' : '')
+  return summary.length <= maxChars ? summary : summary.slice(0, Math.max(1, maxChars - 1)) + '…'
+}
+
+/**
+ * One extra block for the newest verification run in the task.
+ *
+ * The judge's own rule caps a state whose evidence carries no verification (see
+ * {@link BOOKKEEPING_TOOLS}), but only ONE output fits per checkpoint — and the last
+ * call of a task is rarely the test run. A live session ran the full suite and then
+ * spent 88 tool calls closing issues and printing a status summary: the newest
+ * checkpoint showed only that summary, the judge answered exactly K = 52.6% against a
+ * 0.8 threshold, and the route steered "continue the unfinished work" for work that was
+ * finished and verified. Putting the newest verification run back in front of the judge
+ * restores evidence the session really produced; it does not loosen the threshold.
+ * @param index - evidence index of the current task.
+ * @param newest - the call already rendered as the newest output, if any.
+ * @param budget - maximum characters this block may occupy.
+ * @returns The labelled block and the run it came from, or an empty block.
+ */
+function verificationEvidence(index: EvidenceIndex, newest: EvidenceCall | undefined, budget: number): { text: string; call: EvidenceCall | undefined } {
+  if (budget < 128) return { text: '', call: undefined }
+  // A freshly observed run already sits in the newest block; showing an older one as
+  // well would only add noise (and could read as two independent verifications).
+  if (newest !== undefined && looksLikeVerificationRun(newest.text)) return { text: '', call: undefined }
+  let run: EvidenceCall | undefined
+  for (const pair of index.calls.values()) {
+    if (!isEvidenceOutput(pair.name, pair.text) || !looksLikeVerificationRun(pair.text)) continue
+    if (run === undefined || pair.resultSeq > run.resultSeq) run = pair
+  }
+  if (run === undefined) return { text: '', call: undefined }
+  const trailing = trailingSummary(index, run, 200)
+  const prefix = '\n\nLatest observed verification run (' + run.name + (trailing === '' ? '' : ' — ' + trailing) + '):\n'
+  if (prefix.length >= budget) return { text: '', call: undefined }
+  return { text: prefix + sanitizeVerifierText(run.text, budget - prefix.length), call: run }
+}
+
+/** Upper bound on the one-line-per-call digest attached to the newest checkpoint. */
+const MAX_DIGEST_LINES = 8
+
+/**
+ * One line per recent tool result, newest last.
+ *
+ * The detailed blocks above show the newest output and the newest verification run; a
+ * judge deciding whether that verification still covers the current state also needs to
+ * know what the calls in between actually did. The trailing histogram on the
+ * verification block names the tools, this names the work ("gh api … state=closed",
+ * "Updated todo list: 0 pending"), and it deliberately keeps coordination results — they
+ * are exactly what a tail of the task looks like.
+ *
+ * Rendered only for the checkpoint being judged, bounded by its own slice of the same
+ * per-item budget, and always keeping the newest lines when the budget is tight.
+ * @param index - evidence index of the current task.
+ * @param budget - maximum characters this block may occupy.
+ * @param shown - calls already rendered in full above, marked instead of dropped.
+ * @returns The labelled block, or '' when there is nothing recent to add.
+ */
+function recentEvidenceDigest(index: EvidenceIndex, budget: number, shown: readonly (EvidenceCall | undefined)[]): string {
+  if (budget < 128) return ''
+  // The plugin's own verdicts stay out even here: a one-line "winner A, score 1" in the
+  // judge's context is the self-grading this module refuses everywhere else.
+  const recent = [...index.calls.values()]
+    .filter(call => !VERIFIER_EVIDENCE_TOOLS.has(call.name))
+    .sort((a, b) => a.resultSeq - b.resultSeq)
+    .slice(-MAX_DIGEST_LINES)
+  if (recent.length === 0) return ''
+  const rendered = recent.map(call => {
+    const first = call.text.split('\n').map(line => line.trim()).find(line => line.length > 0) ?? ''
+    const mark = shown.includes(call) ? ' [shown above]' : ''
+    return '  [' + call.resultSeq + '] ' + (call.name + ': ' + first).slice(0, 110) + mark
+  })
+  const prefix = '\n\nRecent tool results (newest last):\n'
+  if (prefix.length >= budget) return ''
+  const room = budget - prefix.length
+  let kept = rendered
+  while (kept.length > 1 && kept.join('\n').length > room) kept = kept.slice(1)
+  const omitted = kept.length < rendered.length ? '  …older omitted\n' : ''
+  const body = omitted + kept.join('\n')
+  return prefix + (body.length > room ? body.slice(body.length - room) : body)
 }
 
 /**
@@ -303,29 +487,31 @@ function onlyBookkeepingDispatches(names: ReadonlySet<string> | undefined): bool
  * snapshot they wrote, so their own result repeats it while displacing the real
  * output produced just before them (a live session attached `create_goal`,
  * `update_goal` and `interrupt_agent` output to checkpoints that had already run
- * the task's test suite).
+ * the task's test suite). Coordination results are skipped by the same rule — see
+ * {@link isEvidenceOutput} — because they are also written after the work.
  * @param index - evidence index of the current task.
  * @param seq - checkpoint sequence number, or `Infinity` for the current state.
  * @param budget - maximum characters the evidence may occupy.
  * @param current - render the newest output in the task instead of the newest one before `seq`.
- * @returns Evidence block, or '' when the task produced none yet.
+ * @returns The rendered block and the call it came from, or an empty block.
  */
-function checkpointEvidence(index: EvidenceIndex, seq: number, budget: number, current = false): string {
-  if (budget < 64) return ''
+function checkpointEvidence(index: EvidenceIndex, seq: number, budget: number, current = false): { text: string; call: EvidenceCall | undefined } {
+  const empty = { text: '', call: undefined }
+  if (budget < 64) return empty
   let latest: EvidenceCall | undefined
   for (const pair of index.calls.values()) {
-    if (BOOKKEEPING_TOOLS.has(pair.name) || !pair.text.trim()) continue
+    if (!isEvidenceOutput(pair.name, pair.text)) continue
     if (pair.resultSeq <= seq && (latest === undefined || pair.resultSeq > latest.resultSeq)) latest = pair
   }
-  if (latest === undefined) return ''
+  if (latest === undefined) return empty
   // The prefix length depends on the tool name, so measure it instead of assuming a
   // fixed overhead: with a long tool name the old "- 60" let the rendered step exceed
   // maxItemChars, and boundDecision() then dropped the whole track decision silently.
   const prefix = current
     ? '\n\nLatest observed tool output at routing time (' + latest.name + '):\n'
     : '\n\nLatest observed tool output before this checkpoint (' + latest.name + '):\n'
-  if (prefix.length >= budget) return ''
-  return prefix + sanitizeVerifierText(latest.text, budget - prefix.length)
+  if (prefix.length >= budget) return empty
+  return { text: prefix + sanitizeVerifierText(latest.text, budget - prefix.length), call: latest }
 }
 
 /**
@@ -368,7 +554,11 @@ interface CheckpointSource { seq: number; label: string; body: string }
  * the CURRENT state: its evidence is the newest observed output in the task rather
  * than the newest one before the last todo snapshot (which is often several tool calls
  * stale), and it carries the agent's latest prose as an explicitly labelled claim (see
- * {@link currentNarration}), because prose deliverables never reach a tool.
+ * {@link currentNarration}), because prose deliverables never reach a tool. It gets one
+ * extra slots as well — the newest verification run in the task
+ * ({@link verificationEvidence}) and a one-line digest of the recent calls
+ * ({@link recentEvidenceDigest}) — because a single output slot cannot show both the
+ * tail of the task and the test run that tail is hiding.
  * @param index - evidence index of the current task.
  * @param sources - checkpoints in chronological order.
  * @param maxItemChars - hard per-item cap enforced by boundDecision().
@@ -390,8 +580,20 @@ function renderCheckpointSteps(index: EvidenceIndex, sources: readonly Checkpoin
     // never reaches a tool.
     const isCurrent = position === kept.length - 1
     const observed = checkpointEvidence(index, isCurrent ? Number.POSITIVE_INFINITY : source.seq, isCurrent ? Math.floor(evidenceBudget / 2) : evidenceBudget, isCurrent)
-    const narration = isCurrent ? currentNarration(index, evidenceBudget - observed.length) : ''
-    return sanitizeVerifierText(note + source.label + source.body, Math.max(1, stepCap - observed.length - narration.length)) + observed + narration
+    // Only the newest checkpoint can be short of verification: the older ones describe
+    // past states, and their single output is what was current for them then.
+    const verification = isCurrent
+      ? verificationEvidence(index, observed.call, Math.floor(evidenceBudget / 2) - observed.text.length)
+      : { text: '', call: undefined }
+    // The digest comes out of the item cap rather than the evidence budget: it is a
+    // bounded summary, and the narration keeps the room the evidence budget reserved for
+    // it. MAX_DIGEST_LINES lines of ~110 characters never exceed a tenth of the item.
+    const digest = isCurrent
+      ? recentEvidenceDigest(index, Math.min(1000, Math.floor(stepCap / 10)), [observed.call, verification.call])
+      : ''
+    const narration = isCurrent ? currentNarration(index, evidenceBudget - observed.text.length - verification.text.length) : ''
+    const used = observed.text.length + verification.text.length + digest.length + narration.length
+    return sanitizeVerifierText(note + source.label + source.body, Math.max(1, stepCap - used)) + observed.text + verification.text + digest + narration
   })
   return { steps, evidenceSeqs: kept.map(source => source.seq), omitted }
 }
@@ -499,9 +701,10 @@ export function buildSemanticRoutePrompt(problem: string, events: readonly Sessi
   let used = 0
   let omitted = 0
   for (const [callId, pair] of [...index.calls.entries()].reverse()) {
-    // Bookkeeping results are not alternatives to anything; offering them let the
-    // classifier cite e.g. two goal/agent-control calls as competing candidates.
-    if (BOOKKEEPING_TOOLS.has(pair.name)) continue
+    // Bookkeeping and coordination results are not alternatives to anything; offering
+    // them let the classifier cite e.g. two goal/agent-control calls as competing
+    // candidates, or a previous verdict as an artifact of work.
+    if (!isEvidenceOutput(pair.name, pair.text)) continue
     const text = sanitizeVerifierText(pair.text, maxItemChars)
     if (artifacts.length > 0 && used + text.length > maxInputChars) { omitted += 1; continue }
     used += text.length
@@ -559,10 +762,10 @@ export function semanticDecision(output: SemanticRouteOutput, events: readonly S
   const perItem = itemBudget(output.candidateCallIds.length, maxItemChars, maxInputChars)
   const candidates = output.candidateCallIds.map((callId, i) => {
     const pair = index.calls.get(callId)
-    // Bookkeeping calls are not candidates (they were never offered to the classifier);
+    // Non-evidence calls are not candidates (they were never offered to the classifier);
     // a citation of one is an invalid reference, so the whole decision is rejected
     // instead of comparing metadata as if it were alternative work.
-    if (!pair || BOOKKEEPING_TOOLS.has(pair.name)) return undefined
+    if (!pair || !isEvidenceOutput(pair.name, pair.text)) return undefined
     return { id: callId, groupId: 'semantic', label: pair.name + ' ' + (i + 1), content: sanitizeVerifierText(pair.text, perItem), callId, fromSeq: pair.callSeq, toSeq: pair.resultSeq }
   }).filter((candidate): candidate is CandidateArtifact => candidate !== undefined)
   if (candidates.length !== output.candidateCallIds.length) return undefined
@@ -592,13 +795,18 @@ export function semanticDecision(output: SemanticRouteOutput, events: readonly S
  * cancels that.
  *
  * `select` does not need it: its ring is symmetric by construction and the pivot round
- * is oriented per pair by the engine, so one round is already unbiased. `track` scores
- * a single checkpoint list and has no slots at all.
+ * is oriented per pair by the engine, so one round is already unbiased. `track` has no
+ * slots at all, but it has its own repeat count: without token logprobs one call yields
+ * ONE sampled letter (5.3% of the scale per letter), so repeats are averaged to keep the
+ * progress curve from flipping bands on sampling noise — the same reason the upstream
+ * `n_evaluations` averages repeated verifications.
  * @param decision - the routed decision about to run.
  * @param configured - the configured auto-route repeat count.
+ * @param trackRepeats - repeat count for a `track` route; defaults to `configured`.
  * @returns The repeat count to pass to the engine.
  */
-export function routedRepeats(decision: RouteDecision, configured: number): number {
+export function routedRepeats(decision: RouteDecision, configured: number, trackRepeats = configured): number {
+  if (decision.kind === 'track') return Math.max(1, trackRepeats)
   if (decision.kind !== 'compare') return configured
   return configured % 2 === 0 ? configured : configured + 1
 }
@@ -632,8 +840,9 @@ export class AutoVerifierRouter {
     const taskStartSeq = latestDirectUserSeq(sessionEvents(agent.session))
     if (taskStartSeq === undefined) return undefined
     const id = String(agent.id)
-    const state = this.states.get(id) ?? { taskStartSeq, taskAttempts: 0, sessionAttempts: 0, taskModelCalls: 0, sessionModelCalls: 0, completed: new Set(), failed: new Set(), strictBlocked: false }
-    if (state.taskStartSeq !== taskStartSeq) { state.taskStartSeq = taskStartSeq; state.taskAttempts = 0; state.taskModelCalls = 0; state.completed.clear(); state.failed.clear(); state.inFlight = undefined; state.finalRequiredFromSeq = undefined; state.strictBlocked = false; this.exhaustedNotices.delete(id) }
+    const state = this.states.get(id) ?? { taskStartSeq, routeAttempts: 0, finalAttempts: 0, sessionRouteAttempts: 0, sessionFinalAttempts: 0, taskModelCalls: 0, sessionModelCalls: 0, completed: new Set(), failed: new Set(), finalPreferred: false, strictBlocked: false }
+    // A new task resets its own attempt and model-call counters, but never the session counters.
+    if (state.taskStartSeq !== taskStartSeq) { state.taskStartSeq = taskStartSeq; state.routeAttempts = 0; state.finalAttempts = 0; state.taskModelCalls = 0; state.completed.clear(); state.failed.clear(); state.inFlight = undefined; state.finalRequiredFromSeq = undefined; state.finalPreferred = false; state.strictBlocked = false; this.exhaustedNotices.delete(id) }
     this.states.set(id, state)
     return state
   }
@@ -641,9 +850,27 @@ export class AutoVerifierRouter {
   reserve(agent: RoutedAgent, phase: RoutePhase, fingerprint: string, expectedCalls: number, policy: RouterPolicy): Reservation | undefined {
     if (policy.mode === 'manual') return undefined
     const state = this.state(agent)
-    if (!state || state.inFlight || state.completed.has(fingerprint) || state.taskAttempts >= policy.maxPerTask || state.sessionAttempts >= policy.maxPerSession || state.taskModelCalls + expectedCalls > policy.maxModelCallsPerTask || state.sessionModelCalls + expectedCalls > policy.maxModelCallsPerSession) return undefined
+    if (!state || state.inFlight || state.completed.has(fingerprint)) return undefined
+    // Routing and the final gate draw on separate attempt counters, so no amount of
+    // routing can leave the mandatory acceptance without an attempt of its own.
+    const final = phase === 'final'
+    const attempts = final ? state.finalAttempts : state.routeAttempts
+    const sessionAttempts = final ? state.sessionFinalAttempts : state.sessionRouteAttempts
+    const maxTask = final ? policy.maxFinalPerTask : policy.maxRoutePerTask
+    const maxSession = final ? policy.maxFinalPerSession : policy.maxRoutePerSession
+    if (attempts >= maxTask || sessionAttempts >= maxSession || state.taskModelCalls + expectedCalls > policy.maxModelCallsPerTask || state.sessionModelCalls + expectedCalls > policy.maxModelCallsPerSession) return undefined
     const reservation = { id: String(++this.serial), phase, fingerprint, taskStartSeq: state.taskStartSeq }
-    state.inFlight = reservation; state.taskAttempts++; state.sessionAttempts++; state.taskModelCalls += expectedCalls; state.sessionModelCalls += expectedCalls
+    state.inFlight = reservation
+    if (final) {
+      state.finalAttempts += 1; state.sessionFinalAttempts += 1
+      // The reservation honors the preference; a later failure must not keep routing
+      // disabled for the rest of the task.
+      state.finalPreferred = false
+    } else {
+      state.routeAttempts += 1; state.sessionRouteAttempts += 1
+    }
+    state.taskModelCalls += expectedCalls
+    state.sessionModelCalls += expectedCalls
     return reservation
   }
 
@@ -655,7 +882,7 @@ export class AutoVerifierRouter {
     // a full session verification at the very next stop boundary, before anything was built
     // (and, in strict mode, burn an attempt and set strictBlocked on that empty review).
     if (reservation.phase !== 'semantic' && reservation.phase !== 'final' && reservation.phase !== 'plan_review') state.finalRequiredFromSeq = Math.max(state.finalRequiredFromSeq ?? 0, evidenceSeq ?? reservation.taskStartSeq)
-    if (reservation.phase === 'final') state.finalRequiredFromSeq = undefined
+    if (reservation.phase === 'final') { state.finalRequiredFromSeq = undefined; state.finalPreferred = false }
     return true
   }
 
@@ -663,6 +890,7 @@ export class AutoVerifierRouter {
     const state = this.state(agent)
     if (!state || state.inFlight?.id !== reservation.id) return
     state.inFlight = undefined; state.failed.add(reservation.fingerprint); if (strict) state.strictBlocked = true
+    if (reservation.phase === 'final') state.finalPreferred = false
   }
 
   /**
@@ -690,7 +918,7 @@ export class AutoVerifierRouter {
   budgetExhausted(agent: RoutedAgent, expectedCalls: number, policy: RouterPolicy): boolean {
     const state = this.state(agent)
     if (!state) return true
-    return state.taskAttempts >= policy.maxPerTask || state.sessionAttempts >= policy.maxPerSession
+    return state.routeAttempts >= policy.maxRoutePerTask || state.sessionRouteAttempts >= policy.maxRoutePerSession
       || state.taskModelCalls + expectedCalls > policy.maxModelCallsPerTask || state.sessionModelCalls + expectedCalls > policy.maxModelCallsPerSession
   }
 
@@ -698,6 +926,17 @@ export class AutoVerifierRouter {
   completedFingerprint(agent: RoutedAgent, fingerprint: string): boolean { return this.state(agent)?.completed.has(fingerprint) ?? false }
 
   finalRequired(agent: RoutedAgent): number | undefined { return this.state(agent)?.finalRequiredFromSeq }
+
+  /**
+   * Arm "run the final gate next": a track route already cleared the completion threshold,
+   * so the next stop boundary must not buy another route first.
+   * @param agent - Agent whose track route cleared the threshold.
+   */
+  preferFinal(agent: RoutedAgent): void { const state = this.state(agent); if (state) state.finalPreferred = true }
+
+  /** Whether the next stop boundary must skip routing and run the final gate. */
+  finalPreferred(agent: RoutedAgent): boolean { return this.state(agent)?.finalPreferred ?? false }
+
   strictBlocked(agent: RoutedAgent): boolean { return this.state(agent)?.strictBlocked ?? false }
   release(agent: { id: unknown }): void { this.states.delete(String(agent.id)); this.exhaustedNotices.delete(String(agent.id)) }
 }

package/src/statistics.test.ts

@@ -44,6 +44,12 @@ describe('StatisticsStore', () => {
     expect(all.totals).toMatchObject({ invocations: 2, successes: 1, failures: 1, calls: 3, attempts: 4, retries: 1, tokens: 185, cacheHits: 1, cacheMisses: 2 })
     expect(all.totals.successRate).toBe(0.5)
     expect(all.totals.averageDurationMs).toBe(500)
+    // Provider prefix cache: 20 of 170 input tokens came from cache. DSH reports cached and
+    // uncached input as DISJOINT counts, so the denominator is their sum (that is also how
+    // tokens() totals them). This is a different quantity from the score-cache hit rate
+    // (1 of 3 lookups) and the two must never be conflated.
+    expect(all.totals.prefixCacheHitRate).toBeCloseTo(20 / 170, 10)
+    expect(all.totals.cacheHitRate).toBeCloseTo(1 / 3, 10)
     expect(all.daily).toHaveLength(1)
     expect(all.daily[0]).toMatchObject({ date: '2026-08-20', invocations: 2, calls: 3, tokens: 185 })
     expect(all.tools.map(row => [row.toolName, row.invocations])).toEqual([['verifier_compare', 1], ['verifier_track', 1]])
@@ -55,6 +61,14 @@ describe('StatisticsStore', () => {
     expect(JSON.parse(await readFile(file, 'utf8')).version).toBe(1)
   })
 
+  it('reports a zero prefix cache rate for an empty range instead of NaN', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-verifier-statistics-'))
+    const store = new StatisticsStore(join(root, 'statistics.json'), 100)
+    const empty = await store.overview({ fromMs: 0, toMs: 1 })
+    expect(empty.totals.prefixCacheHitRate).toBe(0)
+    expect(empty.totals.cacheHitRate).toBe(0)
+  })
+
   it('serializes concurrent writes and keeps only the configured tail', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-verifier-statistics-'))
     const store = new StatisticsStore(join(root, 'statistics.json'), 2)
@@ -196,6 +210,9 @@ describe('StatisticsStore', () => {
     expect(summarizeVerdict('verifier_route_classify', { kind: 'none' }, 'semantic', thresholds)).toEqual({ phase: 'semantic', outcome: 'classified' })
     // Select reports the ranked winner's score.
     expect(summarizeVerdict('verifier_select', { index: 1, scores: [0.2, 0.9], ranking: [1, 0] }, 'select', thresholds)).toEqual({ phase: 'select', outcome: 'ranked', score: 0.9 })
+    // A candidate list whose entries were all byte-identical was never judged: say so instead
+    // of reporting index 0's 0.5 as if the tournament had ranked it.
+    expect(summarizeVerdict('verifier_select', { index: 0, scores: [0.5, 0.5], identical: true }, 'select', thresholds)).toEqual({ phase: 'select', outcome: 'identical-candidates' })
     // Track reports the newest checkpoint (not the historical minimum) plus the curve.
     expect(summarizeVerdict('verifier_track', { scores: [0, 0.10526315789473684, 0.7894736842105262] }, 'track', thresholds)).toEqual({
       phase: 'track',
@@ -205,6 +222,26 @@ describe('StatisticsStore', () => {
       threshold: 0.8,
     })
     expect(summarizeVerdict('verifier_track', { scores: [0.9] }, 'track', thresholds)).toEqual({ phase: 'track', outcome: 'passed', score: 0.9, threshold: 0.8 })
+    // Best-of-N is a GATE-shaped acceptance, not a select ranking: its scores array holds
+    // relative tournament shares and must never be read as the absolute score, while
+    // score/baselineScore/criteria come from the same empty-work comparison the gate runs.
+    expect(summarizeVerdict('verifier_best_of_n', {
+      scores: [0.9, 0.7, 0.4],
+      index: 0,
+      score: 0.66,
+      baselineScore: 0,
+      winner: 'A',
+      criteria: [{ id: 'specification', scoreA: 0.7 }, { id: 'output_match', scoreA: 0.62 }],
+    }, 'explicit', thresholds)).toEqual({
+      phase: 'explicit',
+      outcome: 'below-threshold',
+      score: 0.66,
+      baselineScore: 0,
+      criteria: [{ id: 'specification', score: 0.7 }, { id: 'output_match', score: 0.62 }],
+      winner: 'A',
+      threshold: 0.65,
+    })
+    expect(summarizeVerdict('verifier_best_of_n', { score: 0.9, baselineScore: 0, winner: 'A', criteria: [{ id: 'a', scoreA: 1 }] }, 'explicit', thresholds)).toMatchObject({ outcome: 'passed', score: 0.9, threshold: 0.65 })
   })
 
   it('reports the winning side of a comparison instead of the loser under a threshold', () => {
@@ -214,6 +251,8 @@ describe('StatisticsStore', () => {
     expect(summarizeVerdict('verifier_compare', { scoreA: 0.2, scoreB: 0.9, winner: 'B' }, 'compare', thresholds)).toEqual({ phase: 'compare', outcome: 'compared', score: 0.9, scoreB: 0.9, winner: 'B' })
     expect(summarizeVerdict('verifier_compare', { scoreA: 0.9, scoreB: 0.2, winner: 'A' }, 'compare', thresholds)).toEqual({ phase: 'compare', outcome: 'compared', score: 0.9, scoreB: 0.2, winner: 'A' })
     expect(summarizeVerdict('verifier_compare', { scoreA: 0.5, scoreB: 0.5, winner: 'tie' }, 'compare', thresholds)).toEqual({ phase: 'compare', outcome: 'tie', score: 0.5, scoreB: 0.5, winner: 'tie' })
+    // Byte-identical sides: distinguishable from a judged tie, because no call was made.
+    expect(summarizeVerdict('verifier_compare', { scoreA: 0.5, scoreB: 0.5, winner: 'tie', identical: true }, 'compare', thresholds)).toEqual({ phase: 'compare', outcome: 'identical', score: 0.5, scoreB: 0.5, winner: 'tie' })
     // Session acceptance keeps A = the session and B = the empty-work baseline.
     expect(summarizeVerdict('verifier_current_session', { score: 0.4, baselineScore: 0, winner: 'A' }, 'final', thresholds)).toEqual({
       phase: 'final', outcome: 'below-threshold', score: 0.4, baselineScore: 0, winner: 'A', threshold: 0.65,
@@ -224,7 +263,10 @@ describe('StatisticsStore', () => {
     // Losing to the baseline can never pass, however high the raw score is.
     expect(summarizeVerdict('verifier_current_session', { score: 0.9, baselineScore: 0.95, winner: 'B' }, 'final', thresholds)).toMatchObject({ outcome: 'below-threshold' })
     // One criterion below the threshold fails the record even though the mean passes.
-    expect(summarizeVerdict('verifier_current_session', { score: 0.6667, baselineScore: 0, winner: 'A', criteria: [{ id: 'specification', scoreA: 1 }, { id: 'error_signals', scoreA: 0 }] }, 'final', thresholds)).toEqual({
+    // This case uses the EXACT shape `verifySession` returns (AcceptanceCriterion: {id, name,
+    // score}) — a previous version of this test fed {id, scoreA}, which is the compare shape, so
+    // it passed while every real session acceptance stored an empty criteria array.
+    expect(summarizeVerdict('verifier_current_session', { score: 0.6667, baselineScore: 0, winner: 'A', criteria: [{ id: 'specification', name: 'Specification Adherence', score: 1 }, { id: 'error_signals', name: 'Error Signal Detection', score: 0 }] }, 'final', thresholds)).toEqual({
       phase: 'final',
       outcome: 'below-threshold',
       score: 0.6667,
@@ -233,6 +275,12 @@ describe('StatisticsStore', () => {
       winner: 'A',
       threshold: 0.65,
     })
+    // The compare-shaped scoreA is still accepted, and a malformed entry is dropped rather than
+    // stored as NaN.
+    expect(summarizeVerdict('verifier_current_session', { score: 0.9, baselineScore: 0, winner: 'A', criteria: [{ id: 'legacy', scoreA: 0.4 }, { id: 'broken', score: 'high' }] }, 'final', thresholds)).toMatchObject({
+      outcome: 'below-threshold',
+      criteria: [{ id: 'legacy', score: 0.4 }],
+    })
   })
 
   it('keeps the track checkpoint progression and drops invalid entries', async () => {