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

package/src/snapshot.ts

@@ -12,9 +12,9 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { discoverRuns } from './run.ts'
-import { foldRun } from './status.ts'
+import { foldRun, pendingWork } from './status.ts'
 import { getLockStatus, receiptPath, readReceipt } from './lock.ts'
-import type { RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState } from './types.ts'
+import type { PhasePosition, RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState, RecursiveTamper } from './types.ts'
 
 /** One locked-phase fact from a lock receipt (artifacts/<file>.receipt.json). */
 interface LockFacts {
@@ -41,8 +41,11 @@ function lockFactsOf(runDir: string, artifact: string): LockFacts {
 }
 
 /** One phase row from a run's folded status (locked facts enriched). */
-function phaseRowOf(runDir: string, key: string, file: string, status: string): RecursivePhaseRow {
+function phaseRowOf(runDir: string, key: string, file: string, status: string, position?: PhasePosition): RecursivePhaseRow {
   const row: RecursivePhaseRow = { phase: key, status }
+  // T21: carry the server's single derived position onto the wire so the board
+  // reads ONE value instead of recombining status/gates/lock fields itself.
+  if (position !== undefined) row.position = position
   if (status === 'LOCKED') {
     const facts = lockFactsOf(runDir, file)
     if (facts.lockedAt !== undefined) row.lockedAt = facts.lockedAt
@@ -63,7 +66,7 @@ export function foldRunCard(runDir: string, runId: string, worktreeRoot: string)
   // would never match the filename regex and would break columnForRun/cardFacts.
   const phases: Record<string, RecursivePhaseRow> = {}
   for (const phase of status.phases) {
-    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status)
+    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status, phase.position)
   }
   const state = runStateOf(status)
   return {
@@ -71,17 +74,45 @@ export function foldRunCard(runDir: string, runId: string, worktreeRoot: string)
     worktreeRoot,
     phases,
     state,
-    tampers: {},
+    tampers: tampersOf(status),
     subagents: {},
+    // T18: the card carries the same DERIVED pending set the lock gate enforces,
+    // so the board explains a refusal instead of only recording it. Derived on
+    // every fold, so a cold resume shows it and no store is involved (§4.0).
+    pendingWork: pendingWork(runDir),
   }
 }
 
+/**
+ * T15 (F) — tamper facts by DERIVATION, never by persistence.
+ *
+ * `foldRun` already decides, per phase, whether a LOCKED artifact's stored hash
+ * still matches its content: a mismatch lands in `lockProblems` as the literal
+ * 'LockHash mismatch' and clears `lockValid`. That IS the tamper fact, so the
+ * card reads it off the fold instead of replaying the observed-tamper log —
+ * which means it survives a cold resume, honours plan §4.0 ("derived beats
+ * stored"), and stays correct even if the log was rotated or never written.
+ *
+ * Keyed by artifact FILE NAME (e.g. '00-requirements.md'), matching the phase
+ * keys above. `foldRun` itself is untouched: its output shape is
+ * parity-asserted by tests/status.parity.spec.ts.
+ */
+function tampersOf(status: ReturnType<typeof foldRun>): Record<string, RecursiveTamper> {
+  const tampers: Record<string, RecursiveTamper> = {}
+  for (const phase of status.phases) {
+    if (phase.status !== 'LOCKED' || phase.lockValid) continue
+    if (!phase.lockProblems.includes('LockHash mismatch')) continue
+    tampers[phase.file] = { path: phase.file, reason: phase.lockProblems.join('; ') }
+  }
+  return tampers
+}
+
 /**
  * Derive the run-level state from the folded status. The fs stores no run-level
  * state file, so the honest mapping is: 'complete' when every non-optional phase
- * exists and is lock-valid, else 'active'. Transient facts (gateBlocked, tamper,
- * subagent activity) are NOT fs-recoverable and read as absent (recorded
- * limitation; future enhancement).
+ * exists and is lock-valid, else 'active'. Tamper facts ARE fs-recoverable and
+ * are derived by tampersOf above; gateBlocked and subagent activity are not
+ * (recorded limitation; future enhancement).
  */
 function runStateOf(status: ReturnType<typeof foldRun>): RecursiveRunState {
   const mandatory = status.phases.filter(p => !p.optional)

package/src/status.ts

@@ -1,7 +1,32 @@
 import { createHash } from 'node:crypto'
-import { readFileSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import type { ArtifactState, PhaseDef, PhaseState, RecursiveStatusResult } from './types.ts'
+import type { ArtifactState, PendingWorkItem, PhaseDef, PhasePosition, PhaseState, RecursiveStatusResult } from './types.ts'
+import { PHASE_POSITIONS } from './types.ts'
+
+export { PHASE_POSITIONS }
+export type { ArtifactState, PhasePosition }
+
+/**
+ * T21 — derive the ONE named position of a phase from the fields consumers
+ * currently recombine for themselves. Total and disjoint: every reachable shape
+ * returns exactly one member of {@link PHASE_POSITIONS}, so two consumers cannot
+ * read the same phase and disagree.
+ *
+ * Order is the whole design. `tampered` outranks every other lock problem
+ * because a content/hash divergence is the more serious fact — a locked artifact
+ * whose bytes changed invalidates everything that cited it, whereas a failed gate
+ * on an otherwise-intact artifact is a fixable omission.
+ */
+export function phasePosition(state: ArtifactState): PhasePosition {
+  if (state.status === 'SKIPPED') return 'skipped'
+  if (!state.exists) return 'absent'
+  if (state.status === 'LOCKED') {
+    if (state.lockValid) return 'locked'
+    return state.lockProblems.includes('LockHash mismatch') ? 'tampered' : 'invalid-lock'
+  }
+  return state.blockers.length > 0 ? 'blocked' : 'draft'
+}
 
 export const RUN_ARTIFACT_SEQUENCE = [
   '00-requirements.md',
@@ -118,6 +143,87 @@ export function getWorkflowProfile(runDir: string): string {
 export { getLatestRunDirectory, discoverRuns, resolveRunDir } from './run.ts'
 export type { RunDiscoveryResult } from './run.ts'
 
+/**
+ * T18 — unresolved in-flight work, DERIVED from the run directory.
+ *
+ * There is no ledger, no queue and no stored flag: this reads what is already on
+ * disk, which is what makes the quiescence rule in `lockArtifact` cheap enough to
+ * run on every lock. Plan §4.0: derived beats stored wherever derivation is
+ * cheap, and losing a derived fact costs nothing because it cannot be lost.
+ *
+ * WHY THIS IS THE ONLY CASE IMPLEMENTED. The pairing is created early in the
+ * happy path — `runtime.ts` writes `subagents/<id>/handoff.md` BEFORE the bundle
+ * and before the child starts — so the exposure is exactly the window between
+ * the handoff and the reply. The plan also names "a reopen plan without a
+ * completion marker" and "a closeout phase scaffolded without a receipt"; neither
+ * exists on disk (`reopenArtifact` reverts the artifact in place and invalidates
+ * receipts; a scaffolded-but-unlocked closeout artifact is the normal pre-lock
+ * state of every phase), and enforcing either would make locking impossible.
+ * That omission is deliberate and recorded on the item.
+ *
+ * A reply that exists but is empty is NOT a submission, so it stays pending —
+ * a child that created the file and wrote nothing has not answered.
+ *
+ * Total: a missing or unreadable run directory yields an empty set, never a throw.
+ */
+export function pendingWork(runDir: string): PendingWorkItem[] {
+  const subagents = join(runDir, 'subagents')
+  let delegations: string[] = []
+  try {
+    delegations = readdirSync(subagents, { withFileTypes: true })
+      .filter((d) => {
+        if (d.isDirectory()) return true
+        if (!d.isSymbolicLink()) return false
+        try { return statSync(join(subagents, d.name)).isDirectory() } catch { return false }
+      })
+      .map((d) => d.name)
+      .sort()
+  } catch {
+    return []
+  }
+
+  const out: PendingWorkItem[] = []
+  for (const delegationId of delegations) {
+    const dir = join(subagents, delegationId)
+    // Only a delegation directory counts: a stray directory with no handoff is
+    // not evidence that work was started.
+    if (!existsSync(join(dir, 'handoff.md'))) continue
+    const handoffRel = 'subagents/' + delegationId + '/handoff.md'
+
+    let children: string[] = []
+    try {
+      children = readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith('child-'))
+        .map((d) => d.name)
+        .sort()
+    } catch { /* an unreadable delegation dir is treated as unanswered below */ }
+
+    const replies = children.map((child) => 'subagents/' + delegationId + '/' + child + '/reply.md')
+    const present = replies.filter((rel) => existsSync(join(runDir, rel)))
+    if (present.length === 0) {
+      out.push({
+        kind: 'unanswered-delegation',
+        delegationId,
+        path: handoffRel,
+        detail: 'delegation ' + delegationId + ' wrote ' + handoffRel + ' but no child has written a reply.md yet',
+      })
+      continue
+    }
+    const nonEmpty = present.filter((rel) => {
+      try { return readFileSync(join(runDir, rel), 'utf8').trim() !== '' } catch { return false }
+    })
+    if (nonEmpty.length === 0) {
+      out.push({
+        kind: 'empty-reply',
+        delegationId,
+        path: present[0]!,
+        detail: 'delegation ' + delegationId + ' has only empty reply file(s) - an empty file is not a submission',
+      })
+    }
+  }
+  return out
+}
+
 export function getArtifactState(artifactPath: string, workflowProfile: string): ArtifactState {
   let content: string | null = null
   try { content = readFileSync(artifactPath, 'utf8') } catch { /* missing */ }
@@ -168,27 +274,126 @@ export function getArtifactState(artifactPath: string, workflowProfile: string):
   return { exists: true, status, lockValid, lockProblems, blockers: dedupedBlockers, lockedAt, storedHash, actualHash, coverage, approval, audit, todoHasSection: todo.hasTodo, todoUnchecked: todo.unchecked }
 }
 
+/**
+ * T21 — the fold frame: a PURE CACHE of one run's folded state, always
+ * rebuildable from the artifacts, so losing it costs time and never correctness
+ * (plan §4.0: a cache, not a store).
+ *
+ * `stamps` records a cheap per-artifact fingerprint (`size:mtimeMs`, or `null`
+ * for absent) at the moment that artifact was folded. Opening a `size:mtimeMs`
+ * file is orders of magnitude cheaper than reading and parsing 126 KB of lint
+ * input, which is what `snapshotWorkspace` currently does per run, per request.
+ */
+interface FoldFrame {
+  profile: string
+  stamps: Record<string, string | null>
+  states: Map<string, ArtifactState>
+  result: RecursiveStatusResult
+}
+
+const foldFrames = new Map<string, FoldFrame>()
+
+/** Counters so a caller can see whether the cache is doing anything. */
+const foldStats = { folds: 0, reuses: 0, reparsed: 0 }
+
+/**
+ * Fold-cache diagnostics. Read-only observation, kept in the shipped API because
+ * "is the frame hitting?" is the first question when the board feels slow, and a
+ * counter is cheaper than guessing. `reparsed` counts EXISTING artifacts re-read
+ * (an absent one costs only an existsSync).
+ */
+export function foldDiagnostics(): { folds: number; reuses: number; reparsed: number } {
+  return { ...foldStats }
+}
+
+/** Drop every frame and counter. For tests, and for a caller that knows the tree changed underneath. */
+export function resetFoldCache(): void {
+  foldFrames.clear()
+  foldStats.folds = 0
+  foldStats.reuses = 0
+  foldStats.reparsed = 0
+}
+
+/** `size:mtimeMs`, or null when the artifact does not exist. Never throws. */
+function stampOf(path: string): string | null {
+  try {
+    const s = statSync(path)
+    return s.size + ':' + s.mtimeMs
+  } catch {
+    return null
+  }
+}
+
 export function foldRun(runDir: string, runId: string): RecursiveStatusResult {
+  foldStats.folds += 1
   const workflowProfile = getWorkflowProfile(runDir)
+
+  const stamps: Record<string, string | null> = {}
+  for (const phase of PHASES) stamps[phase.key] = stampOf(join(runDir, phase.file))
+
+  const frame = foldFrames.get(runDir)
+  if (frame) {
+    // APPEND-ONLY ASSERTION. Tardigrade's atom throws when its source shrinks;
+    // here the artifacts are the run's evidence — a hash chain and receipts cite
+    // them — so an artifact that a previous fold saw and the tree no longer has
+    // is an anomaly, not an edit. Reporting it beats quietly returning a shorter
+    // state. Scoped to the CACHE on purpose: a cold fold (below) still reports
+    // the honest current tree, so recovery is not blocked by this check.
+    for (const key of Object.keys(frame.stamps)) {
+      if (frame.stamps[key] !== null && stamps[key] === null) {
+        const file = PHASES.find((p) => p.key === key)?.file ?? key
+        throw new Error(
+          'fold frame is append-only: ' + file + ' was present at the last fold and is now missing under ' + runDir +
+          ' - a run artifact is evidence and the chain should only grow',
+        )
+      }
+    }
+    const sameProfile = frame.profile === workflowProfile
+    const unchanged = sameProfile && PHASES.every((p) => frame.stamps[p.key] === stamps[p.key])
+    if (unchanged) {
+      foldStats.reuses += 1
+      return frame.result
+    }
+  }
+
   const states = new Map<string, ArtifactState>()
   for (const phase of PHASES) {
+    const stamp = stamps[phase.key] ?? null
+    const reusable = frame && frame.profile === workflowProfile && frame.stamps[phase.key] === stamp
+      ? frame.states.get(phase.key)
+      : undefined
+    if (reusable) {
+      states.set(phase.key, reusable)
+      continue
+    }
     const state = getArtifactState(join(runDir, phase.file), workflowProfile)
+    if (stamp !== null) foldStats.reparsed += 1
     if (phase.optional && !state.exists) state.status = 'SKIPPED'
     else if (workflowProfile === 'legacy' && LATE_PHASE_KEYS.has(phase.key) && !state.exists) state.status = 'SKIPPED'
     states.set(phase.key, state)
   }
+
   let currentPhase: RecursiveStatusResult['currentPhase'] = null
   for (const phase of PHASES) {
     const state = states.get(phase.key)!
     if (state.status === 'SKIPPED') continue
     if (!state.exists || !state.lockValid) {
+      // `currentPhase` keeps its pinned four-field shape: status.parity deep-equals
+      // it, and T21 must not move a parity-asserted contract.
       currentPhase = { key: phase.key, label: phase.label, phaseName: phase.phaseName, status: state.status }
       break
     }
   }
   const phases: PhaseState[] = PHASES.map(phase => {
     const state = states.get(phase.key)!
-    return { key: phase.key, label: phase.label, file: phase.file, optional: phase.optional, exists: state.exists, status: state.status, lockValid: state.lockValid, lockProblems: state.lockProblems, blockers: state.blockers }
+    return {
+      key: phase.key, label: phase.label, file: phase.file, optional: phase.optional,
+      exists: state.exists, status: state.status, lockValid: state.lockValid,
+      lockProblems: state.lockProblems, blockers: state.blockers,
+      position: phasePosition(state),
+    }
   })
-  return { runId, currentPhase, phases, workflowProfile }
+  const result: RecursiveStatusResult = { runId, currentPhase, phases, workflowProfile }
+  foldFrames.set(runDir, { profile: workflowProfile, stamps, states, result })
+  return result
 }

package/src/teams-loop.ts

@@ -3,8 +3,7 @@
  *
  * The recursion concept's core state machine, expressed over the native
  * `agentTeams` service: ONE durable task per phase carries the loop —
- * createTask (pending) → claim (in_progress) → audit round → on REVISE
- * updateTask(edit, repair instruction) → re-audit the SAME task → on APPROVE
+ * createTask (pending) → claim (in_progress) → audit round → on REVISE* updateTask(edit, repair instruction) → re-audit the SAME task → on APPROVE
  * updateTask(complete) → lock. A stuck reviewer is interrupted through the
  * team's own kill switch; a REJECT or round-cap releases the task and fails
  * loud — a lock NEVER happens before an APPROVE verdict.
@@ -28,6 +27,15 @@ export interface TeamCallerHandle {
   readonly session?: { readonly header?: { readonly cwd?: string } }
 }
 
+/**
+ * T19: the ONLY import this module takes. Everything else it needs arrives through
+ * its injected seams, which is what keeps the loop drivable by fakes — but operation
+ * identity must be computed with the SAME canonical rule as every other operation in
+ * the plugin, so it comes from the shared module rather than a local copy. That would
+ * be the one place two implementations could silently disagree.
+ */
+import { canonicalInput, operationId } from './identity.ts'
+
 /** Minimal cancellation shape (a live AbortSignal satisfies it). */
 export interface TeamAbortSignalLike {
   readonly throwIfAborted: () => void
@@ -111,6 +119,11 @@ export interface AuditLoopRound {
   readonly verdict: AuditVerdict
   readonly repair?: string
   readonly taskRevision: number
+  /**
+   * T20: true when this round produced the SAME progress cursor as its predecessor —
+   * the same finding, restated. Rendered so the board shows a loop as a loop.
+   */
+  readonly noProgress?: boolean
 }
 
 /** The auditToPass result. */
@@ -124,6 +137,45 @@ export interface AuditToPassResult {
   readonly locked: boolean
   /** Latest task view (board-facing per-phase history). */
   readonly taskView?: TeamTaskViewLike
+  /**
+   * T19: true when this call was recognised as a repeat of an audit-to-pass that had
+   * already completed for this run and phase, so no second task was created. The
+   * caller must read the PHASE's lock state itself — this result cannot claim the
+   * artifact is locked, because a recognised repeat performs no locking.
+   */
+  readonly recognisedRepeat?: boolean
+  /**
+   * T20: how many rounds ran. The absolute backstop, reported so a caller can see how
+   * close the loop came to its cap.
+   */
+  readonly attempts?: number
+  /** T20: consecutive rounds that produced the SAME progress cursor. */
+  readonly consecutiveNoProgress?: number
+  /** T20: the last round's progress cursor — what the round said was wrong. */
+  readonly progressCursor?: string
+  /** T28: how many repairs were requested before the loop stopped. */
+  readonly repairAttempts?: number
+  /**
+   * T20: true when the loop stopped in a state that must NOT be retried
+   * automatically — no progress, or the attempt cap. The caller has to decide to
+   * resume, deliberately, rather than a loop quietly grinding on or quietly giving up.
+   */
+  readonly resumeRequired?: boolean
+}
+
+/**
+ * T19: the operation-index seam.
+ *
+ * INJECTED, not imported. `auditToPass` is pure over its seams — it has no `runDir`
+ * and no filesystem access, which is exactly what lets the whole loop be driven by
+ * fakes in tests. Reaching for `recordOperation` directly would have traded that away
+ * for one line of convenience, so the caller supplies persistence instead.
+ */
+export interface AuditOperationsSeamLike {
+  /** The previously recorded attempt for an id, or null when it is new. */
+  find?: (id: string) => { id: string; outcome?: string } | null
+  /** Record one attempt. Best-effort: a failed write must not change the loop's outcome. */
+  record?: (record: { id: string; act: string; at: string; outcome?: string }) => void
 }
 
 /** Inputs for one audit-to-pass loop. */
@@ -139,6 +191,11 @@ export interface AuditToPassInput {
   readonly blockedBy?: readonly TeamTaskIdLike[]
   /** Write scopes for the phase artifact (advisory, overlap-warned). */
   readonly writeScopes?: readonly string[]
+  /**
+   * T19: the operation index, injected. Absent it, the loop runs exactly as before —
+   * no pre-check, no records, no behaviour change.
+   */
+  readonly operations?: AuditOperationsSeamLike
   /** Run ONE audit round for the current task; live usage delegates (T4). */
   readonly runAuditRound: (round: number, task: TeamTaskViewLike) => Promise<AuditRoundOutcome>
   /** Lock the phase artifact — called ONLY after an APPROVE verdict. */
@@ -147,6 +204,22 @@ export interface AuditToPassInput {
   readonly reviewerName?: string
   /** Round cap (fail loud past it; no lock). */
   readonly maxRounds?: number
+  /**
+   * T20: how many CONSECUTIVE rounds may repeat the same progress cursor before the
+   * loop stops and demands a resume. Default 2, so three identical rounds terminate:
+   * the first sets the cursor and the next two repeat it. Absent the bound, a phase
+   * could restate one unfixed finding until the attempt cap, which is the wrong
+   * budget — a round count indulges a loop while cutting off genuine progress.
+   */
+  readonly maxNoProgress?: number
+  /**
+   * T28: the configurable caps. `maxAuditRounds` is the absolute round ceiling and
+   * `maxRepairAttempts` bounds how many times a phase may be sent back for repair
+   * even when every round finds something NEW — the case T20's no-progress bound
+   * deliberately lets run. Both are optional so an existing caller keeps its
+   * behaviour, with the round cap falling back to `maxRounds ?? 3`.
+   */
+  readonly budgets?: { readonly maxAuditRounds?: number; readonly maxRepairAttempts?: number }
   /** Per-round wait timeout before the audit round runs (skipped without the seam). */
   readonly waitTimeoutMs?: number
 }
@@ -167,7 +240,13 @@ export function renderTaskHistory(task: TeamTaskViewLike | undefined, rounds: re
   }
   for (const round of rounds) {
     const repair = round.repair ? ' — ' + round.repair : ''
-    lines.push('round ' + round.round + ': ' + round.verdict + ' (task rev ' + round.taskRevision + ')' + repair)
+    const marker = round.noProgress ? ' [no progress]' : ''
+    lines.push('round ' + round.round + ': ' + round.verdict + ' (task rev ' + round.taskRevision + ')' + repair + marker)
+  }
+  // T20: a loop should LOOK like a loop on the board, not just end like one.
+  const noProgressRounds = rounds.filter((round) => round.noProgress === true).length
+  if (noProgressRounds > 0) {
+    lines.push('no progress: ' + noProgressRounds + ' round(s) restated the same finding — an explicit resume is required')
   }
   return lines.join('\n')
 }
@@ -181,9 +260,67 @@ export function renderTaskHistory(task: TeamTaskViewLike | undefined, rounds: re
  *   → APPROVE: updateTask(complete) → lockPhase()
  *   → REJECT / cap / stuck: updateTask(release) + interrupt, NO lock.
  */
+/**
+ * T19 wrapper: recognise a repeat, then record what happened.
+ *
+ * The identity covers this run and phase. A call whose operation was already recorded
+ * as APPLIED returns immediately without creating a second task — the acceptance's
+ * "recognised no-op rather than a second execution". Every other outcome (rejected,
+ * capped, errored) records as `unaccepted`, so a retry still runs: a failed audit must
+ * stay retryable, and only a COMPLETED one is a repeat.
+ *
+ * Per-round entries are recorded after the loop from the result's own round trail.
+ * That is one write per call instead of one per round, and it keeps the loop body
+ * free of persistence — but it does mean a crash MID-loop leaves the whole operation
+ * unrecorded, which is the honest trade for not threading a writer through every
+ * branch.
+ */
 export async function auditToPass(input: AuditToPassInput): Promise<AuditToPassResult> {
+  const operation = operationId({ act: 'audit-to-pass', input: { runId: input.runId, phase: input.phase } })
+  const prior = input.operations?.find?.(operation) ?? null
+  if (prior?.outcome === 'applied') {
+    return {
+      ok: true,
+      reason: 'recognised repeat: an audit-to-pass for ' + input.runId + ' ' + input.phase +
+        ' already completed, so no second task was created',
+      rounds: [],
+      locked: false,
+      recognisedRepeat: true,
+    }
+  }
+
+  const result = await runAuditToPass(input)
+  const at = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')
+  input.operations?.record?.({
+    id: operation,
+    act: 'audit-to-pass',
+    at,
+    outcome: result.ok && result.locked ? 'applied' : 'unaccepted',
+  })
+  for (const round of result.rounds) {
+    input.operations?.record?.({
+      id: operationId({ act: 'audit-round', input: { runId: input.runId, phase: input.phase, round: round.round } }),
+      act: 'audit-round',
+      at,
+      outcome: round.verdict,
+    })
+  }
+  return result
+}
+
+async function runAuditToPass(input: AuditToPassInput): Promise<AuditToPassResult> {
   const { teams, caller, runId, phase, runAuditRound, lockPhase } = input
-  const maxRounds = input.maxRounds ?? 3
+  const maxRounds = input.maxRounds ?? input.budgets?.maxAuditRounds ?? 3
+  // T28: the repair budget. Absent a configured cap, repairs are unbounded here on
+  // purpose — the round cap and the no-progress bound still apply, and inventing a
+  // silent default would change the behaviour of every existing caller.
+  const maxRepairAttempts = input.budgets?.maxRepairAttempts ?? Number.POSITIVE_INFINITY
+  let repairAttempts = 0
+  // T20: the no-progress bound, and the counters that make it visible.
+  const maxNoProgress = input.maxNoProgress ?? 2
+  let consecutiveNoProgress = 0
+  let progressCursor = ''
+  let attempts = 0
   const waitTimeoutMs = input.waitTimeoutMs ?? 30_000
   const waitForChange = teams.waitForChange
   const interrupt = teams.interrupt
@@ -212,11 +349,23 @@ export async function auditToPass(input: AuditToPassInput): Promise<AuditToPassR
       const outcome = await runAuditRound(round, current)
       if (!isSameTask(current, task.id)) return { ok: false, reason: 'round observed a foreign task', taskId: task.id, rounds, locked: false, taskView: current }
 
+      // T20 — THE PROGRESS CURSOR. A round's statement of what is wrong is its verdict
+      // plus the repair it produced (that repair is synthesized from the findings, so
+      // it is the round's own summary of the problem). The SAME cursor twice running
+      // means the previous repair did not change anything, which is a loop; a CHANGED
+      // cursor is progress and resets the counter. Canonical JSON, so two structurally
+      // identical rounds cannot differ by key order.
+      attempts = round
+      const cursor = canonicalInput({ verdict: outcome.verdict, repair: outcome.repair ?? '', reason: outcome.reason ?? '' })
+      const repeated = cursor === progressCursor
+      consecutiveNoProgress = repeated ? consecutiveNoProgress + 1 : 0
+      progressCursor = cursor
+
       if (outcome.verdict === 'APPROVE') {
         const completed = await teams.updateTask(caller, { taskId: task.id, expectedRevision: current.revision, action: 'complete' })
         await lockPhase()
         rounds.push({ round, verdict: 'APPROVE', taskRevision: completed.revision })
-        return { ok: outcome.accepted, reason: outcome.accepted ? 'audit passed and phase locked' : 'verdict APPROVE but delegation not accepted', taskId: task.id, rounds, locked: true, taskView: completed }
+        return { ok: outcome.accepted, reason: outcome.accepted ? 'audit passed and phase locked' : 'verdict APPROVE but delegation not accepted', taskId: task.id, rounds, locked: true, taskView: completed, attempts, consecutiveNoProgress, progressCursor }
       }
 
       if (outcome.verdict === 'REJECT') {
@@ -235,11 +384,65 @@ export async function auditToPass(input: AuditToPassInput): Promise<AuditToPassR
         description: current.description + '\nround ' + round + ' repair: ' + repair,
       })
       current = edited
-      rounds.push({ round, verdict: 'REVISE', repair, taskRevision: edited.revision })
+      repairAttempts += 1
+      rounds.push({ round, verdict: 'REVISE', repair, taskRevision: edited.revision, ...(repeated ? { noProgress: true } : {}) })
+
+      // T28 — THE REPAIR BUDGET. Checked before the no-progress bound because it is
+      // the wider stopping condition: a repair budget catches a loop that keeps
+      // finding NEW things, which is precisely the loop the no-progress bound is
+      // designed not to stop.
+      if (repairAttempts >= maxRepairAttempts) {
+        const released = await teams.updateTask(caller, { taskId: task.id, expectedRevision: current.revision, action: 'release' })
+        return {
+          ok: false,
+          reason: 'repair budget reached: ' + repairAttempts + ' repair attempt(s) without an APPROVE',
+          taskId: task.id,
+          rounds,
+          locked: false,
+          taskView: released,
+          attempts,
+          repairAttempts,
+          consecutiveNoProgress,
+          progressCursor,
+          resumeRequired: true,
+        }
+      }
+
+      // T20 — STOP THE LOOP, DO NOT SPEND THE CAP ON IT. A phase that restates the
+      // same finding has not been repaired, and more rounds will not repair it. The
+      // terminal state demands an EXPLICIT resume: silently grinding on wastes the
+      // budget, and silently giving up hides an unfixed phase.
+      if (consecutiveNoProgress >= maxNoProgress) {
+        const released = await teams.updateTask(caller, { taskId: task.id, expectedRevision: current.revision, action: 'release' })
+        return {
+          ok: false,
+          reason: 'no progress: ' + consecutiveNoProgress + ' consecutive rounds repeated the same finding (' + repair + ')',
+          taskId: task.id,
+          rounds,
+          locked: false,
+          taskView: released,
+          attempts,
+          consecutiveNoProgress,
+          progressCursor,
+          resumeRequired: true,
+        }
+      }
     }
-    // Round cap: release and fail loud — never lock without an APPROVE.
+    // Round cap: release and fail loud — never lock without an APPROVE. T20 keeps the
+    // cap as the ABSOLUTE backstop for a loop that keeps making progress.
     const released = await teams.updateTask(caller, { taskId: task.id, expectedRevision: current.revision, action: 'release' })
-    return { ok: false, reason: 'max rounds reached without an APPROVE', taskId: task.id, rounds, locked: false, taskView: released }
+    return {
+      ok: false,
+      reason: 'max rounds reached without an APPROVE',
+      taskId: task.id,
+      rounds,
+      locked: false,
+      taskView: released,
+      attempts,
+      consecutiveNoProgress,
+      progressCursor,
+      resumeRequired: true,
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     // A stuck reviewer is interrupted through the team kill switch (the task
@@ -249,7 +452,18 @@ export async function auditToPass(input: AuditToPassInput): Promise<AuditToPassR
         interrupt(caller, input.reviewerName ?? 'auditor')
       } catch { /* interrupt is best-effort */ }
     }
-    return { ok: false, reason: message, taskId: task.id, rounds, locked: false, taskView: current }
+    return {
+      ok: false,
+      reason: message,
+      taskId: task.id,
+      rounds,
+      locked: false,
+      taskView: current,
+      attempts,
+      consecutiveNoProgress,
+      progressCursor,
+      resumeRequired: true,
+    }
   }
 }