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

package/src/recursive_audit_team.tool.ts

@@ -0,0 +1,141 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type {
+  TeamRuntimeLike,
+  TeamCallerHandle,
+  TeamTaskActionLike,
+  TeamTaskViewLike,
+  CreateTeamTaskRequestLike,
+  UpdateTeamTaskRequestLike,
+} from './teams-loop.ts'
+
+/**
+ * `recursive_audit_team` — the T3 entry path: a turn-driven adapter over the
+ * live `agentTeams` task board. ONE call advances the audit→repair→re-audit
+ * state machine by one transition, so the agent drives the loop across turns
+ * as continuable-child settlement notices arrive in its inbox.
+ *
+ * Why one step per call: the live subagents service has no public parent-side
+ * "await settlement" promise — a continuable child's verdict arrives as a
+ * `subagent-settled` message on a LATER turn. The pure whole-loop driver
+ * (`auditToPass` in teams-loop.ts) models the full state machine and is the
+ * tested reference; this tool is its honest turn-driven shell.
+ */
+
+/** Project one live task view to an owned, lossless-JSON-safe record. */
+function taskViewToJson(view: TeamTaskViewLike): JsonValue {
+  // Read only leaf fields; never pass the live service object into the model
+  // context (the tool boundary is where a live view becomes owned JSON).
+  return {
+    id: view.id,
+    revision: view.revision,
+    subject: view.subject,
+    description: view.description,
+    status: view.status,
+    blockedBy: [...view.blockedBy],
+    writeScopes: [...view.writeScopes],
+    ownerName: view.ownerName ?? null,
+    ready: view.ready,
+    writeScopeWarnings: [...view.writeScopeWarnings],
+  }
+}
+
+/** Wrap a non-JSON-pure value in the standard error envelope. */
+function errorJson(message: string): JsonValue {
+  return { error: message }
+}
+
+export function createRecursiveAuditTeamTool(teams: TeamRuntimeLike | null) {
+  return defineTool({
+    name: 'recursive_audit_team',
+    description: 'Advance one agentTeams Task-board transition for the recursive audit loop (create → claim → edit(REVISE) → complete(APPROVE) → release/interrupt). Drive one step per turn as continuable-child settlement notices arrive; complete the task (and lock the phase) ONLY after an APPROVE verdict.',
+    parameters: {
+      action: { type: 'string', description: 'create | claim | edit | complete | release | interrupt | get | list. Required.' },
+      taskId: { type: 'string', description: 'Task id for claim/edit/complete/release/interrupt/get.' },
+      expectedRevision: { type: 'number', description: 'CAS revision for claim/edit/complete/release.' },
+      subject: { type: 'string', description: 'Task subject (create).' },
+      description: { type: 'string', description: 'Task description (create) or appended repair note (edit).' },
+      blockedBy: { type: 'array', items: { type: 'string' }, description: 'Task blockers (create).' },
+      writeScopes: { type: 'array', items: { type: 'string' }, description: 'Advisory write scopes (create).' },
+      targetName: { type: 'string', description: 'Teammate name to interrupt (interrupt).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: {
+      action?: string
+      taskId?: string
+      expectedRevision?: number
+      subject?: string
+      description?: string
+      blockedBy?: string[]
+      writeScopes?: string[]
+      targetName?: string
+    }, exec) {
+      const action = args.action ?? ''
+      if (!teams) return errorJson('agentTeams service is not available in this composition')
+      // SAFETY: exec.agent is the live Team member Agent (a superset of the
+      // named opaque handle); the seam reads only id/session identity and never
+      // serializes it. When no agent owns the call, an empty handle degrades to
+      // an anonymous caller (the service admits/denies by its own authority).
+      const caller: TeamCallerHandle = exec.agent ?? {}
+
+      try {
+        switch (action) {
+          case 'create': {
+            if (!args.subject || !args.description) return errorJson('create requires subject and description')
+            const createRequest: CreateTeamTaskRequestLike = {
+              subject: args.subject,
+              description: args.description,
+            }
+            if (args.blockedBy !== undefined) createRequest.blockedBy = args.blockedBy
+            if (args.writeScopes !== undefined) createRequest.writeScopes = args.writeScopes
+            const view = await teams.createTask(caller, createRequest)
+            return taskViewToJson(view)
+          }
+          case 'claim':
+          case 'edit':
+          case 'complete':
+          case 'release': {
+            if (!args.taskId || args.expectedRevision === undefined) {
+              return errorJson(action + ' requires taskId and expectedRevision')
+            }
+            // SAFETY: this case arm is reachable only for action 'claim' | 'edit' |
+            // 'complete' | 'release' (the switch discriminates on the same string),
+            // each a member of TeamTaskActionLike's subset; the cast re-asserts that
+            // narrowing across the four fall-through labels without widening scope.
+            const updateAction = action as TeamTaskActionLike
+            const updateRequest: UpdateTeamTaskRequestLike = {
+              taskId: args.taskId,
+              expectedRevision: args.expectedRevision,
+              action: updateAction,
+            }
+            if (action === 'edit' && args.description !== undefined) updateRequest.description = args.description
+            const view = await teams.updateTask(caller, updateRequest)
+            return taskViewToJson(view)
+          }
+          case 'interrupt': {
+            if (!args.targetName) return errorJson('interrupt requires targetName')
+            if (!teams.interrupt) return errorJson('no interrupt seam')
+            const outcome = teams.interrupt(caller, args.targetName)
+            return { previousStatus: outcome.previousStatus }
+          }
+          case 'get': {
+            if (!args.taskId) return errorJson('get requires taskId')
+            if (!teams.getTask) return errorJson('no getTask seam')
+            return taskViewToJson(teams.getTask(caller, args.taskId))
+          }
+          case 'list': {
+            if (!teams.listTasks) return errorJson('no listTasks seam')
+            return teams.listTasks(caller).map(taskViewToJson)
+          }
+          default:
+            return errorJson('unsupported action: ' + action + ' (create|claim|edit|complete|release|interrupt|get|list)')
+        }
+      } catch (err) {
+        return errorJson(err instanceof Error ? err.message : String(err))
+      }
+    },
+  })
+}

package/src/runtime.ts

@@ -21,7 +21,7 @@ import { readScratch, writeScratch, appendScratch, type ScratchTarget } from './
 import { buildReviewBundle, type ReviewBundleInput } from './review.ts'
 import { createHandoff, createChildBrief, replyPath, childScratchPath, buildDelegationPrompt, type HandoffInput, type ChildBriefInput } from './handoff.ts'
 import { loadRouterPolicy, routerPolicyPath, resolveRole, capabilityProbe, delegationDecisionBasis, type RouterPolicy, type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts'
-import { delegate, validateReferences, writeActionRecord, evaluateDelegationResult, reviewOutputSchema, defaultReviewToolFilter, type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type ActionRecordInput } from './delegation.ts'
+import { delegate, delegateContinuable, validateReferences, writeActionRecord, evaluateDelegationResult, reviewOutputSchema, defaultReviewToolFilter, type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type ActionRecordInput, type ContinuableDelegationLike, type SubagentParentHandle } from './delegation.ts'
 import { validateTransition, coupleGateBlockToGoal, type PhaseTransitionIntent, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts'
 import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluateToolGuard, detectTamper, type EnforcementConfig, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts'
 import type { Session } from '@deepseek-ai/dsh-session'
@@ -29,6 +29,9 @@ import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
 import { snapshotWorkspace } from './snapshot.ts'
 import { createLinkedWorktree, promoteBranch, listWorktrees, defaultWorktreeBranch, type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts'
 import { gitFacts } from './git-context.ts'
+import { syncRunGoal, blockRunGoal, resumeRunGoal, type GoalServiceLike } from './goals-projection.ts'
+import { auditToPass, renderTaskHistory, type TeamRuntimeLike, type AuditToPassResult, type TeamCallerHandle, type TeamTaskViewLike, type AuditRoundOutcome } from './teams-loop.ts'
+import type { ContinuableChildId, ContinuableMessageId } from './delegation.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -70,16 +73,86 @@ const ARTIFACT_STUB = {
 export class RecursiveRuntime extends Service {
   /** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
 
-  constructor(ctx: Context, config: { repoRoot?: string; workspaceRegistry?: WorkspaceRegistryLike } = {}) {
+  constructor(ctx: Context, config: { repoRoot?: string; workspaceRegistry?: WorkspaceRegistryLike; goals?: GoalServiceLike | null } = {}) {
     super(ctx, 'recursive')
     this.repoRoot = config.repoRoot ?? process.cwd()
     this.workspaceRegistry = config.workspaceRegistry ?? null
+    this.goalsService = config.goals ?? null
   }
 
   private readonly repoRoot: string
   private readonly workspaceRegistry: WorkspaceRegistryLike | null
+  private readonly goalsService: GoalServiceLike | null
   private _enforcementConfig: EnforcementConfig | null = null
 
+  /**
+   * T3 (agentTeams task loop): run the audit→repair→re-audit state machine on
+   * ONE durable team task. The `teams` seam (live `ctx.agentTeams`) is injected
+   * per-call so the loop stays unit-testable; `runAuditRound` is the caller's
+   * round executor (live usage wires T4's continuable delegation). Locking the
+   * phase artifact is `lockPhase` — the loop NEVER locks before an APPROVE.
+   */
+  async auditToPass(input: {
+    teams: TeamRuntimeLike
+    caller: TeamCallerHandle
+    root: string
+    runId: string
+    phase: string
+    artifact: string
+    agent?: { session?: { header?: { cwd?: string } } } | null
+    runAuditRound: (round: number, task: TeamTaskViewLike) => Promise<AuditRoundOutcome>
+    blockedBy?: readonly string[]
+    writeScopes?: readonly string[]
+    reviewerName?: string
+    maxRounds?: number
+    waitTimeoutMs?: number
+  }): Promise<AuditToPassResult & { history?: string; lock?: LockArtifactResult }> {
+    const { teams, caller, runId, phase, artifact, runAuditRound, agent } = input
+    let lockResult: LockArtifactResult | undefined
+    const lockPhase = async () => { lockResult = await this.lockArtifact(runId, artifact, false, agent) }
+    const result = await auditToPass({
+      teams,
+      caller,
+      runId,
+      phase,
+      blockedBy: input.blockedBy,
+      writeScopes: input.writeScopes,
+      reviewerName: input.reviewerName,
+      maxRounds: input.maxRounds,
+      waitTimeoutMs: input.waitTimeoutMs,
+      runAuditRound,
+      lockPhase,
+    })
+    const report: AuditToPassResult & { history?: string; lock?: LockArtifactResult } = {
+      ...result,
+      history: renderTaskHistory(result.taskView, result.rounds),
+    }
+    if (lockResult !== undefined) report.lock = lockResult
+    return report
+  }
+
+  /**
+   * T1 (goals projection): project the run into the native goals service so it is
+   * a first-class durable, resumable, blockable object. Best-effort — the run's
+   * filesystem state is the source of truth; a goal is the durable projection.
+   */
+  projectRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string, state: Parameters<typeof syncRunGoal>[3] = 'active') {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return syncRunGoal(this.goalsService, agent, runId, state)
+  }
+
+  /** T1: block the run's goal on a gate-block (durable + UI-visible). */
+  blockRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string, reason: { code: string; message: string }) {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return blockRunGoal(this.goalsService, agent, runId, reason)
+  }
+
+  /** T1: re-arm the run's goal on a reopen (blocked/paused -> active). */
+  resumeRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string) {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return resumeRunGoal(this.goalsService, agent, runId)
+  }
+
   /**
    * Workspace-scoped control-plane root (R1 binding invariant).
    * Resolves the session agent's canonical cwd -> workspace path via the
@@ -138,8 +211,16 @@ export class RecursiveRuntime extends Service {
   /**
    * Phase B (native delegation): build a review bundle (R1) + file-backed
    * handoff docs (R2), resolve the role via the router policy (R3), and call
-   * ctx.subagents.start() with the full request (R4). Workspace-scoped: every
-   * path resolves under the session's control-plane root.
+   * ctx.subagents with the full request (R4). Workspace-scoped: every path
+   * resolves under the session's control-plane root.
+   *
+   * `mode: 'continuable'` (T4) runs the audit→repair→re-audit loop on ONE
+   * durable continuable child (startContinuable → followup with the repair
+   * instruction → settle) and drains the child on closeout. It requires an
+   * `awaitRoundResult` observer (the parent-side settlement seam) AND the exact
+   * live `parent` Agent (continuable followup is object-identity authority);
+   * when either is absent it falls back to one-shot `delegate()` with a flag —
+   * never silently. One-shot `start()` is never called on the continuable path.
    */
   async delegateReview(input: {
     root: string
@@ -160,6 +241,11 @@ export class RecursiveRuntime extends Service {
     subagents?: SubagentsRuntimeLike
     maxDepth?: number
     toolFilter?: unknown
+    mode?: 'one-shot' | 'continuable'
+    awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>
+    maxRounds?: number
+    /** T4: the exact live direct-parent Agent (object-identity authority). */
+    parent?: SubagentParentHandle
   }) {
     const policy = loadRouterPolicy(input.policyPath ?? routerPolicyPath(input.root))
     const providers = input.providers ?? {}
@@ -213,7 +299,9 @@ export class RecursiveRuntime extends Service {
       briefPath,
     })
 
-    // R4: plugin-driven delegation with the full request shape.
+    // R4: plugin-driven delegation with the full request shape. `parent` is the
+    // exact live direct-parent Agent (object-identity authority in the live
+    // subagent service); absent it, the live start() rejects the request.
     const request: SubagentStartRequestLike = {
       prompt: [{ type: 'text', text: prompt }],
       label: input.delegationId + '/' + input.childId,
@@ -221,12 +309,38 @@ export class RecursiveRuntime extends Service {
       toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
       maxDepth: input.maxDepth ?? 2,
     }
+    if (input.parent !== undefined) request.parent = input.parent
 
     let result: SubagentResultLike | null = null
     let error: string | null = null
+    let continuable: ContinuableDelegationLike | null = null
     if (decision.tier === 'native' || decision.tier === 'external-cli') {
       if (!input.subagents) {
         error = 'no ctx.subagents runtime available (self-audit fallback)'
+      } else if (input.mode === 'continuable') {
+        // T4: one durable child carries every round; start() is never called.
+        continuable = await delegateContinuable({
+          subagents: input.subagents,
+          provider: decision.provider as string,
+          label: input.delegationId + '/' + input.childId,
+          prompt,
+          childId: input.childId,
+          maxDepth: input.maxDepth ?? 2,
+          toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
+          maxRounds: input.maxRounds ?? 3,
+          awaitRoundResult: input.awaitRoundResult,
+          parent: input.parent,
+        })
+        if (continuable.fellBackToOneShot) {
+          // The seam has no continuable capability — keep the one-shot result.
+          result = continuable.rounds[0]?.result ?? null
+          if (!result) error = 'continuable fallback produced no result'
+        } else if (continuable.ok && continuable.rounds.length > 0) {
+          result = continuable.rounds[continuable.rounds.length - 1].result ?? null
+          if (!result) error = 'continuable child produced no final result'
+        } else {
+          error = continuable.reason ?? 'continuable delegation failed'
+        }
       } else {
         try {
           result = await delegate({
@@ -251,7 +365,7 @@ export class RecursiveRuntime extends Service {
       subagentId: input.childId,
       phase: input.phase,
       purpose: input.role + ' for run ' + input.runId,
-      executionMode: decision.tier,
+      executionMode: decision.tier + (input.mode === 'continuable' ? ' (continuable)' : ''),
       artifactPath: input.artifactPath,
       upstreamArtifacts: input.upstreamArtifacts,
       reviewBundle: bundle.repoRelativePath,
@@ -263,6 +377,10 @@ export class RecursiveRuntime extends Service {
       stopReason: result?.stopReason,
     })
 
+    // T4: the durable child id is reported for the caller (a tool/closeout that
+    // holds the live parent Agent may drain it explicitly); the HOST owns the
+    // teardown drain (drainContinuableDescendants) at session close — this loop
+    // never forces a drain with a wrong authority credential (childId ≠ parent).
     return {
       decision,
       probe,
@@ -277,6 +395,7 @@ export class RecursiveRuntime extends Service {
       evaluation,
       actionRecordPath,
       error,
+      continuable: continuable ? { rounds: continuable.rounds, childId: continuable.childId, fellBackToOneShot: continuable.fellBackToOneShot } : null,
     }
   }
 
@@ -431,6 +550,9 @@ export class RecursiveRuntime extends Service {
 
     const result: { runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult } = { runDir, runId, created, existing }
     if (worktree) result.worktree = worktree
+    // T1 (goals projection): arm a durable run goal for the driving session.
+    // Best-effort — never fails a run init if the goals service is absent/odd.
+    try { this.projectRunToGoal(agent, runId, 'active') } catch { /* goal projection is best-effort */ }
     return result
   }
 
@@ -486,6 +608,10 @@ export class RecursiveRuntime extends Service {
     // durable commit below is what the live fs route folds. No phase-intent event.
     const blockers = getPrerequisiteBlockers(runDir, artifact)
     if (blockers.length > 0) {
+      // T1 (goals projection): a gate-block becomes a durable, UI-visible goal
+      // block rather than a one-line advisory. Best-effort before the throw.
+      const message = 'monotonic lock-order: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', ')
+      try { this.blockRunToGoal(agent, runId, { code: 'prerequisite-blockers', message }) } catch { /* best-effort */ }
       throw new Error('Prerequisite blockers: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', '))
     }
     let content = readFileSync(artifactPath, 'utf8')
@@ -521,6 +647,8 @@ export class RecursiveRuntime extends Service {
     const stale = getStaleDownstreamPhases(runDir, artifact)
     for (const entry of stale) invalidateReceipt(runDir, entry.artifact)
     // B2: reopen reverts to DRAFT — the live fs route folds the reverted state.
+    // T1 (goals projection): re-arm the durable run goal (reopen un-blocks).
+    try { this.resumeRunToGoal(agent, runId) } catch { /* best-effort */ }
     return {
       artifact,
       runId,

package/src/teams-loop.ts

@@ -0,0 +1,259 @@
+/**
+ * T3: model the audit→repair→re-audit loop as agentTeams Tasks.
+ *
+ * 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
+ * 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.
+ *
+ * Everything here is a structural seam (TeamRuntimeLike / TeamTaskViewLike)
+ * so the whole loop is unit-testable with a fake team; the live `agentTeams`
+ * service satisfies the seam without an adapter. The caller Agent passes
+ * through as an opaque `TeamCallerHandle` (never serialized; workspace-scoped
+ * invariant).
+ */
+
+/** Verdict vocabulary shared with T4 (matches the delegated review schema). */
+export type AuditVerdict = 'APPROVE' | 'REVISE' | 'REJECT'
+
+/**
+ * Opaque handle to the live Team member/lead Agent authorizing task mutations.
+ * The seam uses it only for identity/authority and never inspects or serializes it.
+ */
+export interface TeamCallerHandle {
+  readonly id?: string
+  readonly session?: { readonly header?: { readonly cwd?: string } }
+}
+
+/** Minimal cancellation shape (a live AbortSignal satisfies it). */
+export interface TeamAbortSignalLike {
+  readonly throwIfAborted: () => void
+}
+
+/** Task identity: a branded string in the live service. */
+export type TeamTaskIdLike = string
+
+/** Task status vocabulary (mirrors the live TeamTaskStatus). */
+export type TeamTaskStatusLike = 'pending' | 'in_progress' | 'completed' | 'deleted'
+
+/** Task action vocabulary (mirrors the live TeamTaskAction; the loop uses a subset). */
+export type TeamTaskActionLike = 'claim' | 'release' | 'edit' | 'complete'
+
+/** One runtime-enriched task view (the fields the loop reads/writes). */
+export interface TeamTaskViewLike {
+  readonly id: TeamTaskIdLike
+  readonly revision: number
+  readonly subject: string
+  readonly description: string
+  readonly status: TeamTaskStatusLike
+  readonly blockedBy: TeamTaskIdLike[]
+  readonly writeScopes: string[]
+  readonly ownerName?: string
+  readonly ready: boolean
+  readonly writeScopeWarnings: string[]
+}
+
+/** A wait observation (mirrors TeamWaitResult). */
+export interface TeamWaitResultLike {
+  readonly timedOut: boolean
+}
+
+/** Create-task request (mirrors CreateTeamTaskRequest). */
+export interface CreateTeamTaskRequestLike {
+  subject: string
+  description: string
+  blockedBy?: readonly TeamTaskIdLike[]
+  writeScopes?: readonly string[]
+}
+
+/** Compare-and-set task transition (mirrors UpdateTeamTaskRequest). */
+export interface UpdateTeamTaskRequestLike {
+  taskId: TeamTaskIdLike
+  expectedRevision: number
+  action: TeamTaskActionLike
+  subject?: string
+  description?: string
+  blockedBy?: readonly TeamTaskIdLike[]
+  writeScopes?: readonly string[]
+  owner?: string
+}
+
+/**
+ * The agentTeams seam the loop calls. `waitForChange`/`interrupt`/`getTask`/
+ * `listTasks` are optional (loops degrade: no wait, no kill switch, no board
+ * re-read) — `createTask`/`updateTask` are hard requirements.
+ */
+export interface TeamRuntimeLike {
+  createTask(caller: TeamCallerHandle, request: CreateTeamTaskRequestLike): Promise<TeamTaskViewLike>
+  updateTask(caller: TeamCallerHandle, request: UpdateTeamTaskRequestLike): Promise<TeamTaskViewLike>
+  getTask?(caller: TeamCallerHandle, id: TeamTaskIdLike): TeamTaskViewLike
+  listTasks?(caller: TeamCallerHandle): TeamTaskViewLike[]
+  waitForChange?(caller: TeamCallerHandle, timeoutMs: number, signal: TeamAbortSignalLike | undefined): Promise<TeamWaitResultLike>
+  interrupt?(caller: TeamCallerHandle, targetName: string): { previousStatus: 'running' | 'idle' | 'inactive' }
+}
+
+/** One audit round's outcome (the verdict + synthesized repair + acceptance). */
+export interface AuditRoundOutcome {
+  readonly verdict: AuditVerdict
+  /** Repair instruction synthesized from findings (REVISE only). */
+  readonly repair?: string
+  /** Whether the underlying delegation result itself was accepted. */
+  readonly accepted: boolean
+  readonly reason?: string
+}
+
+/** One completed loop round (the task revision trail for the board history). */
+export interface AuditLoopRound {
+  readonly round: number
+  readonly verdict: AuditVerdict
+  readonly repair?: string
+  readonly taskRevision: number
+}
+
+/** The auditToPass result. */
+export interface AuditToPassResult {
+  readonly ok: boolean
+  readonly reason?: string
+  /** The durable task the loop ran on (revision trail lives on the team log). */
+  readonly taskId?: TeamTaskIdLike
+  readonly rounds: AuditLoopRound[]
+  /** True only when an APPROVE verdict completed the task and locked the phase. */
+  readonly locked: boolean
+  /** Latest task view (board-facing per-phase history). */
+  readonly taskView?: TeamTaskViewLike
+}
+
+/** Inputs for one audit-to-pass loop. */
+export interface AuditToPassInput {
+  /** The agentTeams seam. */
+  readonly teams: TeamRuntimeLike
+  /** Exact live Team member/lead authorizing the task mutations. */
+  readonly caller: TeamCallerHandle
+  /** Phase + run identity (task subject/description vocabulary). */
+  readonly runId: string
+  readonly phase: string
+  /** Optional task blockers (previous-phase task ids). */
+  readonly blockedBy?: readonly TeamTaskIdLike[]
+  /** Write scopes for the phase artifact (advisory, overlap-warned). */
+  readonly writeScopes?: readonly string[]
+  /** 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. */
+  readonly lockPhase: () => Promise<void>
+  /** Team member name to interrupt on a stuck reviewer (defaults to the role). */
+  readonly reviewerName?: string
+  /** Round cap (fail loud past it; no lock). */
+  readonly maxRounds?: number
+  /** Per-round wait timeout before the audit round runs (skipped without the seam). */
+  readonly waitTimeoutMs?: number
+}
+
+/** Whether a view is the loop's expected task (guards CAS against foreign ids). */
+function isSameTask(task: TeamTaskViewLike, id: TeamTaskIdLike): boolean {
+  return task.id === id
+}
+
+/**
+ * Render a per-phase task history (board-facing; pure). One line per round plus
+ * the final task status — no live data, no mutation.
+ */
+export function renderTaskHistory(task: TeamTaskViewLike | undefined, rounds: readonly AuditLoopRound[]): string {
+  const lines: string[] = []
+  if (task !== undefined) {
+    lines.push('task ' + task.id + ' (' + task.status + ', rev ' + task.revision + '): ' + task.subject)
+  }
+  for (const round of rounds) {
+    const repair = round.repair ? ' — ' + round.repair : ''
+    lines.push('round ' + round.round + ': ' + round.verdict + ' (task rev ' + round.taskRevision + ')' + repair)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * T3 driver: audit the phase until it passes, on ONE durable team task.
+ *
+ * Transition trail (the fake records exactly this order):
+ *   createTask(pending) → claim(in_progress) → waitForChange → audit round
+ *   → REVISE: updateTask(edit, repair) → waitForChange → re-audit SAME task
+ *   → APPROVE: updateTask(complete) → lockPhase()
+ *   → REJECT / cap / stuck: updateTask(release) + interrupt, NO lock.
+ */
+export async function auditToPass(input: AuditToPassInput): Promise<AuditToPassResult> {
+  const { teams, caller, runId, phase, runAuditRound, lockPhase } = input
+  const maxRounds = input.maxRounds ?? 3
+  const waitTimeoutMs = input.waitTimeoutMs ?? 30_000
+  const waitForChange = teams.waitForChange
+  const interrupt = teams.interrupt
+  const rounds: AuditLoopRound[] = []
+
+  const createRequest: CreateTeamTaskRequestLike = {
+    subject: 'Audit to pass: ' + runId + ' ' + phase,
+    description: 'drive ' + phase + ' through draft → audit → repair → re-audit → pass → lock for run ' + runId,
+  }
+  if (input.blockedBy !== undefined) createRequest.blockedBy = input.blockedBy
+  if (input.writeScopes !== undefined) createRequest.writeScopes = input.writeScopes
+  const task = await teams.createTask(caller, createRequest)
+
+  const claim = await teams.updateTask(caller, { taskId: task.id, expectedRevision: task.revision, action: 'claim' })
+  if (!isSameTask(claim, task.id)) return { ok: false, reason: 'claim returned a foreign task', taskId: task.id, rounds, locked: false, taskView: claim }
+
+  let current = claim
+  rounds.push({ round: 0, verdict: 'REVISE', taskRevision: current.revision })
+
+  try {
+    for (let round = 1; round <= maxRounds; round += 1) {
+      // Wait for team activity before the round (bounded; skipped without the seam).
+      if (waitForChange !== undefined) {
+        await waitForChange(caller, waitTimeoutMs, undefined)
+      }
+      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 }
+
+      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 }
+      }
+
+      if (outcome.verdict === 'REJECT') {
+        // A rejected audit is not a pass: release the task and fail loud.
+        const released = await teams.updateTask(caller, { taskId: task.id, expectedRevision: current.revision, action: 'release' })
+        rounds.push({ round, verdict: 'REJECT', taskRevision: released.revision })
+        return { ok: false, reason: 'audit rejected at round ' + round, taskId: task.id, rounds, locked: false, taskView: released }
+      }
+
+      // REVISE: record the repair instruction on the SAME task and re-audit.
+      const repair = outcome.repair ?? 'REVISE: address the review findings and re-submit.'
+      const edited = await teams.updateTask(caller, {
+        taskId: task.id,
+        expectedRevision: current.revision,
+        action: 'edit',
+        description: current.description + '\nround ' + round + ' repair: ' + repair,
+      })
+      current = edited
+      rounds.push({ round, verdict: 'REVISE', repair, taskRevision: edited.revision })
+    }
+    // Round cap: release and fail loud — never lock without an APPROVE.
+    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 }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    // A stuck reviewer is interrupted through the team kill switch (the task
+    // itself stays for a later resume); best-effort, never replaces the error.
+    if (interrupt !== undefined) {
+      try {
+        interrupt(caller, input.reviewerName ?? 'auditor')
+      } catch { /* interrupt is best-effort */ }
+    }
+    return { ok: false, reason: message, taskId: task.id, rounds, locked: false, taskView: current }
+  }
+}
+
+/** Whether a task view is currently claimed by the named owner (board-facing). */
+export function isTaskClaimedBy(task: TeamTaskViewLike, ownerName: string): boolean {
+  return task.ownerName === ownerName && task.status === 'in_progress'
+}