@defrex/autobuild 0.8.0

package/packages/core/src/processes/build-runner.ts

@@ -0,0 +1,2614 @@
+/**
+ * The build-runner process (SPEC §3.3): one per build, owns one pipeline
+ * execution end to end. The kernel's job reduced to a loop (§8): read the
+ * event log, ask `decideNext` for the next move, execute it — start sessions,
+ * run check commands, append the events execution produces — and ask again.
+ * All judgment lives in the skills behind the AgentRunner; everything here is
+ * deterministic plumbing (constitution §2.1). That split makes the runner
+ * crash-safe by construction: killed mid-phase, a re-attached runner re-reads
+ * the log and `decideNext` re-decides the same started-but-unterminated phase
+ * from its start (§15.6-C) — resumability is not a feature (§2.2).
+ *
+ * Ownership: `attach` claims or renews the build's execution lease (§7.4) so a
+ * second sandbox can never execute the same build. The local supervising kernel
+ * reserves that same holder before launch. The runner may then acknowledge a pending pause or
+ * abort without preparing the workspace; workspace-backed work starts a
+ * heartbeat interval before setup (liveness is mutable columns, never events
+ * — §15.2.6). `run` exits when the build
+ * parks (§11: a parked build's runner exits; cron re-attaches when
+ * actionable). The runner releases nothing on exit: a local execution supervisor
+ * releases ownership after full tree teardown, while abrupt loss falls back to
+ * expiry and the dispatcher's sweep re-attaches (§15.6-C).
+ *
+ * Documented pragmatisms (where SPEC forces are in tension, the choice and
+ * its reason live here):
+ *
+ * - Producer session memory (§10) vs per-run transcripts (§7.1). The producer
+ *   must *continue* its session across review rounds, but `AgentRunner.end`
+ *   destroys continuability in every adapter. A SUCCESSFUL producer run
+ *   therefore keeps its runner session live and closes its per-round
+ *   session bracket with the turn's own transcript (final text + usage,
+ *   straight off the AgentRunner interface — still "through the interface",
+ *   §9, never scraped). The handle is truly `end()`ed when the phase later
+ *   fails (a rambling session is never continued — fresh start next attempt,
+ *   D5) or when `run` exits; the cumulative turn log is discarded then,
+ *   because every round already deposited its own transcript.
+ * - Finalize checks are deterministic kernel work with no synthetic session;
+ *   finalize agents retain their session actor. Both paths are deliberately
+ *   failure-tolerant and drain through the same completion/observation writer.
+ * - The D5 retry guard also covers agent-verify steps (keyed `verify:<step>`,
+ *   round = attempt): a no-terminal or provider-failed verify session would
+ *   otherwise re-run forever, since its `verify.completed` never lands.
+ * - A throwing Exec in `run-check` propagates: deterministic checks carry no
+ *   session to fail (§8.2), and a crashed runner's dangling `verify.started`
+ *   simply re-runs the check on re-attach (§15.6-C) — the same crash model
+ *   as every phase.
+ */
+import type { Config } from '../config/schema'
+import type { AbEvent, EventWrite } from '../events/catalog'
+import type { EventPayload } from '../events/payloads'
+import { KERNEL, agentActor, type Actor } from '../events/envelope'
+import type { IdSource } from '../ids'
+import { decideNext, type Decision } from '../kernel/engine'
+import { PHASE_SPECS } from '../kernel/phases'
+import { reduceBuild, type BuildState } from '../kernel/reducer'
+import { evaluateVerifyApplicability } from '../kernel/verify-applicability'
+import {
+  verifyPhase,
+  verifyReportKind,
+  type CorePhase,
+  type Feedback,
+  type Phase,
+} from '../ontology'
+import {
+  createRuntimeResolver,
+  type ResolvedRole,
+  type ResolvedRuntime,
+  type RuntimeResolver,
+} from '../ports/runner/routing'
+import { isAlternateEligible, mayRetryPhase } from '../ports/runner/provider-error'
+import { sessionPart } from '../ports/runner/stream-parts'
+import type { SessionStreamInfo } from '../ports/runner/runtime'
+import type { RuntimeRegistry } from '../ports/runner/runtime'
+import { createSessionStreamSink } from '../store/streams/session-writer'
+import type { StreamOutcome } from '../store/streams/types'
+import type {
+  AgentRunner,
+  AgentSessionHandle,
+  AgentTurnFailure,
+  AgentTurnResult,
+  Forge,
+  SessionStreamSink,
+} from '../ports/types'
+import { BUILD_EXECUTION_LEASE_TTL_MS } from '../ports/workspace/build-execution'
+import { phaseScratchRejection, scratchPathsTouchedInRange } from '../ports/workspace/phase-scratch'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { BuildScopedStore, Clock } from '../store/types'
+import { resetsPhaseFailureBudget, type PhaseFailureResetEscalation } from './phase-failure-budget'
+import { publicationPending } from './publication-state'
+
+export { publicationPending } from './publication-state'
+
+// ── Seams ────────────────────────────────────────────────────────────────────
+
+/** Another sandbox owns the build (§7.4): its lease is live, so this runner
+ * must not execute. The dispatcher retries once the lease expires. */
+export class LeaseHeldError extends Error {
+  constructor(
+    readonly slug: string,
+    readonly instance: string,
+  ) {
+    super(
+      `build "${slug}" is leased to another runner — instance "${instance}" ` +
+        'cannot attach while the holder is live (§7.4)',
+    )
+    this.name = 'LeaseHeldError'
+  }
+}
+
+/** Recognizable launch failure whose durable detail is already in the build
+ * log. Interactive dispatch therefore renders it on the build row rather than
+ * duplicating it in process-global warning chrome. */
+export class SetupFailureError extends Error {
+  constructor(
+    readonly slug: string,
+    readonly failure: EventPayload<'runner.setup-failed'>,
+    readonly exhausted: boolean,
+  ) {
+    const status =
+      failure.exitStatus === null ? 'exit status unavailable' : `exited ${failure.exitStatus}`
+    super(
+      `[commands].setup ${JSON.stringify(failure.command)} ${status} ` +
+        `(attempt ${failure.attempt}): ${failure.output || '(no output)'}`,
+    )
+    this.name = 'SetupFailureError'
+  }
+}
+
+export interface BuildRunnerOpts {
+  /** D5 retry policy: phase.failed count per phase+round before a policy
+   * escalation replaces the next run (never loop forever). Default 2. */
+  maxPhaseAttempts?: number
+  /** Lease keep-alive interval (§15.2.6). Default 15s. */
+  heartbeatMs?: number
+  /** Lease TTL passed to claimLease (§7.4). Default 60s. */
+  leaseTtlMs?: number
+  /** Test seam for phase-session deadlines. Production uses an unref'ed timer. */
+  scheduleSessionBudget?: (expire: () => void, delayMs: number) => () => void
+  /** Session streams (SPEC §9): open one stream per session bracket for
+   * runtimes that declare the streaming capability. Default true. A failing
+   * stream path never fails a turn; disabling reproduces the event log
+   * without streams. */
+  streamSessions?: boolean
+  /** Where stream diagnostics land. Default: a stderr write. */
+  onDiagnostic?: (message: string) => void
+}
+
+export interface BuildRunnerDeps {
+  store: BuildScopedStore
+  config: Config
+  /** Current dispatcher snapshot. It is sampled once for setup and once for
+   * each engine/action boundary; omission preserves static runner callers. */
+  getConfig?: () => Config | Promise<Config>
+  /** Runtime registry: name → adapter + compatibility data (§9). The resolver
+   * applies `config.roles`, including its reserved `default` entry, to it. */
+  runtimes: RuntimeRegistry
+  workspacePath: string
+  branch: string
+  slug: string
+  /** Shell seam for deterministic checks and finalize Git guards (§8.2, D7). */
+  exec: Exec
+  /** Remote publication stays behind the kernel-owned Forge port (D7). */
+  forge: Forge
+  ids: IdSource
+  clock: Clock
+  /** Lease holder identity (§7.4) and `runner.attached` payload (§15.3). */
+  instance: string
+  host: string
+  /** Extra AB_* the launcher wants in every session env (e.g. AB_TOKEN,
+   * AB_STORE for a remote store) — D8. May override AB_STORE; never the
+   * per-session identity keys (AB_BUILD/AB_PHASE/AB_SESSION). */
+  sessionEnv?: Record<string, string>
+  opts?: BuildRunnerOpts
+}
+
+// ── Internal shapes ──────────────────────────────────────────────────────────
+
+type RunPhaseDecision = Extract<Decision, { kind: 'run-phase' }>
+type RunCheckDecision = Extract<Decision, { kind: 'run-check' }>
+type RunAgentVerifyDecision = Extract<Decision, { kind: 'run-agent-verify' }>
+type EvaluateVerifyDecision = Extract<Decision, { kind: 'evaluate-verify' }>
+type SkipVerifyDecision = Extract<Decision, { kind: 'skip-verify' }>
+type RunFinalizeStepDecision = Extract<Decision, { kind: 'run-finalize-step' }>
+type CheckReconcileProgressDecision = Extract<Decision, { kind: 'check-reconcile-progress' }>
+type RaiseEscalationDecision = Extract<Decision, { kind: 'raise-escalation' }>
+
+/** Lease acquisition can finish either workspace-backed attachment or one
+ * engine-selected stop acknowledgement that deliberately needs no workspace. */
+export type AttachmentResult =
+  | { kind: 'workspace-ready' }
+  | { kind: 'control-acknowledged'; command: 'pause' | 'abort' }
+
+/** §10 memory: a producer's live runner session, kept across review rounds. */
+interface ProducerSession {
+  handle: AgentSessionHandle
+  runner: AgentRunner
+  route: string
+}
+
+type ProviderAttempt = NonNullable<EventPayload<'phase.failed'>['providerAttempts']>[number]
+
+type TurnSettlement<T> =
+  | { kind: 'value'; value: T }
+  | { kind: 'error'; error: unknown }
+  | { kind: 'expired' }
+
+interface BudgetedTurn<T> {
+  settlement: TurnSettlement<T>
+  /** The first kernel cancellation cause. A provider result cannot overwrite it. */
+  abortCause?: 'operator' | 'budget'
+  /** Eventually settles even when the kernel has stopped waiting. */
+  pending: Promise<Exclude<TurnSettlement<T>, { kind: 'expired' }>>
+}
+
+/** One bracketed agent run (§15.3 sessions). */
+interface SessionSpec {
+  /** Event/AB_PHASE identity: core phase or `verify:<step>`. */
+  phase: Phase
+  /** Loop round; verify attempt (AB_PHASE uses attempt as round); 1 for
+   * finalize. */
+  round: number
+  role: string
+  /** Deprecated compatibility role keys, consulted in order only when `role`
+   * is undeclared (§9 routing). Today: an agent verify step's configured skill
+   * name, the key verify used to route by before step names unified the rule. */
+  roleAliases?: readonly string[]
+  skill: string
+  abPhase: string
+  /** Set for producer core phases — §10 session memory applies. */
+  producerPhase?: CorePhase
+  /** Rendered into the continue message; the CLI context (`ab context`) is
+   * the real carrier — the message just names the .ab/ inputs. */
+  feedback?: Feedback
+  /** phase.failed count for this phase+round at decision time (D5). */
+  priorFailures: number
+  /** Phase-specific terminal recognizer; the session-scoped `escalation.
+   * raised` terminal (§8.4: escalate is always available) is added here. */
+  isTerminal: (event: AbEvent) => boolean
+}
+
+/** Longest tail of check output preserved in a verify report (§8.2). */
+const REPORT_TAIL_CHARS = 10_000
+
+/**
+ * One session bracket's live stream (SPEC §9): the sink the build-runner
+ * opened through the resolved target's streaming capability, the store id it
+ * returned, and the identity already emitted as the stream's first part.
+ * Undefined ⇒ the runtime declared no capability or the opener declined —
+ * the bracket then behaves exactly as before streams existed.
+ */
+interface SessionBracketStream {
+  sink: SessionStreamSink
+  streamId: string
+  info: SessionStreamInfo
+}
+/** Git object ids are 40 hex characters for SHA-1 repositories and 64 for
+ * SHA-256 repositories. `rev-parse <ref>^{commit}` supplies the type check. */
+const GIT_OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function sessionBudgetError(seconds: number): string {
+  return `phase session budget expired after ${seconds} seconds`
+}
+
+function defaultSessionBudgetScheduler(expire: () => void, delayMs: number): () => void {
+  // Node/Bun timers clamp larger delays. Chunk against an absolute deadline so
+  // a valid large positive config value can never become an immediate expiry.
+  const maxDelayMs = 2_147_483_647
+  const deadline = Date.now() + delayMs
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const arm = (): void => {
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) {
+      expire()
+      return
+    }
+    timer = setTimeout(arm, Math.min(remaining, maxDelayMs))
+    timer.unref?.()
+  }
+  arm()
+  return () => {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+function providerAttemptSummary(attempts: readonly ProviderAttempt[] | undefined): string {
+  if (attempts === undefined) return ''
+  return (
+    '; configured provider attempts: ' +
+    attempts
+      .map(
+        (attempt) =>
+          `#${attempt.index} ${attempt.runner}` +
+          `${attempt.model !== undefined ? `/${attempt.model}` : ''}: ${attempt.error}`,
+      )
+      .join(' | ')
+  )
+}
+
+/** Latest event-checkpointed branch head that kernel plumbing published. */
+export function selectPublishedBranchHead(events: readonly AbEvent[]): string {
+  let head: string | undefined
+  for (const event of events) {
+    if (event.type === 'implement.completed') {
+      head = event.payload.commits.head
+    } else if (event.type === 'reconcile.completed') {
+      head = event.payload.mergeCommit
+    } else if (
+      event.type === 'finalize.step-completed' &&
+      event.payload.ok &&
+      event.payload.headSha !== undefined
+    ) {
+      head = event.payload.headSha
+    }
+  }
+  if (head === undefined) {
+    throw new Error(
+      'finalize publication requires a prior implement.completed, reconcile.completed, ' +
+        'or successful finalize publication head, but this build has none',
+    )
+  }
+  return head
+}
+
+/**
+ * Select the durable tree against which a conditional verifier evaluates the
+ * branch's current HEAD. The initial branch-cut SHA is authoritative until a
+ * successful reconcile; each completed reconcile promotes the latest start's
+ * refreshed base SHA. A dangling start is intentionally ignored.
+ */
+export function selectVerifyDiffBase(events: readonly AbEvent[]): string {
+  const provisioned = events.find((event) => event.type === 'workspace.provisioned')
+  if (provisioned === undefined || provisioned.type !== 'workspace.provisioned') {
+    throw new Error(
+      'conditional verify requires a workspace.provisioned base SHA, but this build has none',
+    )
+  }
+
+  let baseSha = provisioned.payload.base.sha
+  let pendingReconcileBase: string | undefined
+  for (const event of events) {
+    if (event.type === 'reconcile.started') {
+      pendingReconcileBase = event.payload.baseSha
+    } else if (event.type === 'reconcile.completed') {
+      if (pendingReconcileBase !== undefined) baseSha = pendingReconcileBase
+      pendingReconcileBase = undefined
+    }
+  }
+  return baseSha
+}
+
+/** Parse `git diff --name-only -z`; malformed output fails closed. */
+export function parseNulChangedPaths(output: string): string[] {
+  if (output.length === 0) return []
+  if (!output.endsWith('\0')) {
+    throw new Error('git diff --name-only -z returned non-NUL-terminated output')
+  }
+  const paths = output.slice(0, -1).split('\0')
+  if (paths.some((path) => path.length === 0)) {
+    throw new Error('git diff --name-only -z returned an empty path entry')
+  }
+  return paths
+}
+
+/** Terminal events of loop phases carry `round`; finalize.completed and
+ * reconcile.completed do not (§15.3). Payloads are schema-validated at
+ * append, so the loose read is safe. */
+function roundMatches(event: AbEvent, round: number): boolean {
+  const r = (event.payload as { round?: unknown }).round
+  return typeof r !== 'number' || r === round
+}
+
+/**
+ * The producer's round-N+1 prompt (§10): assembled deterministically from
+ * the feedback, naming the .ab/ inputs `ab context` materializes (§8.3) —
+ * the message is a pointer, the CLI context is the real carrier.
+ */
+function continueMessage(spec: SessionSpec): string {
+  const refresh = 'run `ab context` to refresh .ab/, then finish with your terminal command'
+  const { feedback } = spec
+  if (feedback === undefined) {
+    return `Continue ${spec.phase} (round ${spec.round}): ${refresh}.`
+  }
+  if ('findings' in feedback) {
+    return (
+      `Revise ${spec.phase} (round ${spec.round}): address findings ` +
+      `${feedback.findings.join(', ')} — materialized in .ab/findings.json; ${refresh}.`
+    )
+  }
+  if ('verify' in feedback) {
+    return (
+      `verify:${feedback.verify.step} failed — its report ` +
+      `(${feedback.verify.report.kind}@${feedback.verify.report.rev}) is in ` +
+      `.ab/verify/; fix in ${spec.phase} round ${spec.round}, ${refresh}.`
+    )
+  }
+  return (
+    `Human guidance on escalation ${feedback.guidance.escalation} (authoritative, ` +
+    `§15.6-B): ${feedback.guidance.answer} — inputs in .ab/; ${refresh}.`
+  )
+}
+
+// ── The runner ───────────────────────────────────────────────────────────────
+
+function isPublicationBoundary(event: AbEvent, spec: SessionSpec, session: string): boolean {
+  if (
+    event.type !== 'publication.requested' ||
+    event.actor.kind !== 'agent' ||
+    event.actor.session !== session
+  )
+    return false
+  if (spec.phase === 'implement')
+    return event.payload.operation === 'implement' && event.payload.round === spec.round
+  if (spec.phase === 'reconcile') return event.payload.operation === 'reconcile'
+  if (spec.phase === 'finalize') return event.payload.operation === 'finalize'
+  return false
+}
+
+export class BuildRunner {
+  private readonly maxPhaseAttempts: number
+  private readonly heartbeatMs: number
+  private readonly leaseTtlMs: number
+  private readonly streamSessions: boolean
+  private readonly onDiagnostic: (message: string) => void
+  private attached = false
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined
+  /** Set when a heartbeat reports the lease lapsed (§7.4): the store never
+   * renews an expired lease, so the holder must re-claim before doing any
+   * more work — or stop, because the sweep may already have launched a
+   * replacement runner (§15.6-C). */
+  private leaseLost = false
+  /** §10 producer session memory — in-memory by design: a new sandbox resumes
+   * with fresh sessions rehydrated from the store (§7.4, §9). */
+  private readonly producerSessions = new Map<CorePhase, ProducerSession>()
+  /** Captured only at setup/step boundaries. Async work below a boundary never
+   * consults the mutable owner again. */
+  private boundaryConfig: Config
+  private boundaryResolver: RuntimeResolver
+
+  constructor(private readonly deps: BuildRunnerDeps) {
+    this.maxPhaseAttempts = deps.opts?.maxPhaseAttempts ?? 2
+    this.heartbeatMs = deps.opts?.heartbeatMs ?? 15_000
+    this.leaseTtlMs = deps.opts?.leaseTtlMs ?? BUILD_EXECUTION_LEASE_TTL_MS
+    this.streamSessions = deps.opts?.streamSessions ?? true
+    this.onDiagnostic = deps.opts?.onDiagnostic ?? ((message) => console.error(message))
+    this.boundaryConfig = deps.config
+    this.boundaryResolver = createRuntimeResolver(
+      deps.runtimes,
+      deps.config.roles,
+      deps.config.policy.sessionBudgetSeconds,
+    )
+  }
+
+  private async captureConfig(): Promise<Config> {
+    const config = (await this.deps.getConfig?.()) ?? this.deps.config
+    this.boundaryConfig = config
+    this.boundaryResolver = createRuntimeResolver(
+      this.deps.runtimes,
+      config.roles,
+      config.policy.sessionBudgetSeconds,
+    )
+    return config
+  }
+
+  /** Consecutive durable setup failures since the latest successful attachment
+   * or explicit human answer. The answer re-arms the budget but deliberately
+   * does not erase the current diagnostic while recovery is still running. */
+  private setupStreak(events: readonly AbEvent[]): number {
+    const setupEscalations = new Set<string>()
+    let boundary = 0
+    for (const event of events) {
+      if (event.type === 'runner.attached') boundary = event.seq
+      else if (
+        event.type === 'escalation.raised' &&
+        event.payload.phase === 'setup' &&
+        event.payload.source === 'policy'
+      ) {
+        setupEscalations.add(event.payload.id)
+      } else if (event.type === 'escalation.answered' && setupEscalations.has(event.payload.id)) {
+        boundary = event.seq
+      }
+    }
+    return events.filter((event) => event.type === 'runner.setup-failed' && event.seq > boundary)
+      .length
+  }
+
+  private setupQuestion(failure: EventPayload<'runner.setup-failed'>): string {
+    const status =
+      failure.exitStatus === null ? 'exit status unavailable' : `exit status ${failure.exitStatus}`
+    return (
+      `maxSetupAttempts (${this.boundaryConfig.policy.maxSetupAttempts}) exhausted: ` +
+      `[commands].setup ${JSON.stringify(failure.command)} failed with ${status}. ` +
+      `Output: ${failure.output || '(no output)'}`
+    )
+  }
+
+  private async raiseSetupEscalation(failure: EventPayload<'runner.setup-failed'>): Promise<void> {
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'escalation.raised',
+      payload: {
+        id: this.deps.ids('esc'),
+        phase: 'setup',
+        source: 'policy',
+        policyCause: 'setup-failure-limit',
+        question: this.setupQuestion(failure),
+      },
+    } satisfies EventWrite<'escalation.raised'>)
+  }
+
+  /** Close every session open in the captured pre-attachment prefix, then
+   * announce takeover against that same boundary. If a write is interrupted,
+   * no attachment lands; the next runner reduces the newer prefix and closes
+   * only sessions that remain open. */
+  private async reclaimSessionsAndAttach(events: readonly AbEvent[]): Promise<void> {
+    const { store, slug, instance, host } = this.deps
+    const resumedFromSeq = events.at(-1)?.seq ?? 0
+    for (const session of reduceBuild([...events]).sessions.open) {
+      await store.append(slug, {
+        actor: KERNEL,
+        type: 'session.ended',
+        payload: {
+          session: session.session,
+          outcome: 'reclaimed',
+          reclaimedBy: { instance, resumedFromSeq },
+        },
+      } satisfies EventWrite<'session.ended'>)
+    }
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'runner.attached',
+      payload: {
+        instance,
+        host,
+        ...(resumedFromSeq > 0 ? { resumedFromSeq } : {}),
+      },
+    } satisfies EventWrite<'runner.attached'>)
+  }
+
+  /**
+   * Claim the lease, honor engine-selected stop controls, then run pre-phase
+   * setup for workspace-backed work. The first workspace attempt retains the
+   * historical successful-path protocol by announcing attachment before setup.
+   * Once a setup failure is current, retries delay `runner.attached` until
+   * setup succeeds; that fact then proves recovery and clears the projection.
+   */
+  async attach(): Promise<AttachmentResult> {
+    const config = await this.captureConfig()
+    const { store, slug, instance } = this.deps
+    const claimed = await store.claimLease(slug, instance, this.leaseTtlMs)
+    if (!claimed) throw new LeaseHeldError(slug, instance)
+
+    let events = await store.getEvents(slug)
+    const decision = decideNext(events, config)
+    if (
+      decision.kind === 'acknowledge' &&
+      (decision.command === 'pause' || decision.command === 'abort')
+    ) {
+      await this.acknowledge(decision.command)
+      return { kind: 'control-acknowledged', command: decision.command }
+    }
+
+    const state = reduceBuild(events)
+    const currentFailure = state.setupFailure
+    const openSetupEscalation = state.openEscalations.some(
+      (escalation) => escalation.phase === 'setup' && escalation.source === 'policy',
+    )
+    const streak = this.setupStreak(events)
+
+    // Crash-safe exhaustion: the final failure and escalation are separate
+    // appends. If only the failure landed, raise the blocker before another
+    // command execution can buy an extra attempt.
+    if (currentFailure !== undefined && streak >= config.policy.maxSetupAttempts) {
+      if (!openSetupEscalation) await this.raiseSetupEscalation(currentFailure)
+      throw new SetupFailureError(slug, currentFailure, true)
+    }
+    if (currentFailure !== undefined && openSetupEscalation) {
+      throw new SetupFailureError(slug, currentFailure, true)
+    }
+
+    const recovering = currentFailure !== undefined
+    if (!recovering) await this.reclaimSessionsAndAttach(events)
+
+    // First beat immediately (liveness visible without waiting an interval),
+    // then keep-alive. Setup runs under this heartbeat so a slow install cannot
+    // outlive the claimed lease.
+    await store.heartbeat(slug, instance)
+    this.heartbeatTimer = setInterval(() => {
+      store.heartbeat(slug, instance).then(
+        (alive) => {
+          if (!alive) this.leaseLost = true
+        },
+        () => {
+          // Store unreachable — the next beat retries; the lease TTL is the
+          // real liveness contract (§15.2.6).
+        },
+      )
+    }, this.heartbeatMs)
+    this.heartbeatTimer.unref?.()
+
+    const setup = config.commands.setup
+    if (setup !== undefined) {
+      let failure: EventPayload<'runner.setup-failed'> | undefined
+      try {
+        const result = await this.deps.exec(['sh', '-c', setup], {
+          cwd: this.deps.workspacePath,
+        })
+        if (result.exitCode !== 0) {
+          failure = {
+            command: setup,
+            attempt: streak + 1,
+            exitStatus: result.exitCode,
+            output: [result.stderr, result.stdout].filter((text) => text !== '').join('\n'),
+          }
+        }
+      } catch (error) {
+        failure = {
+          command: setup,
+          attempt: streak + 1,
+          exitStatus: null,
+          output: errorMessage(error),
+        }
+      }
+
+      if (failure !== undefined) {
+        try {
+          await store.append(slug, {
+            actor: KERNEL,
+            type: 'runner.setup-failed',
+            payload: failure,
+          } satisfies EventWrite<'runner.setup-failed'>)
+          const exhausted = failure.attempt >= config.policy.maxSetupAttempts
+          if (exhausted) await this.raiseSetupEscalation(failure)
+          throw new SetupFailureError(slug, failure, exhausted)
+        } finally {
+          this.stopHeartbeat()
+          this.attached = false
+        }
+      }
+    }
+
+    if (recovering) {
+      try {
+        events = await store.getEvents(slug)
+        await this.reclaimSessionsAndAttach(events)
+      } catch (error) {
+        this.stopHeartbeat()
+        this.attached = false
+        throw error
+      }
+    }
+    this.attached = true
+    return { kind: 'workspace-ready' }
+  }
+
+  /**
+   * One read→decide→execute cycle (§8): the unit-test surface. Returns the
+   * decision it executed; `wait` decisions execute nothing.
+   */
+  async step(): Promise<Decision> {
+    const config = await this.captureConfig()
+    const { store, slug } = this.deps
+    const events = await store.getEvents(slug)
+    const decision = decideNext(events, config)
+    switch (decision.kind) {
+      case 'wait':
+        return decision
+      case 'acknowledge':
+        await this.acknowledge(decision.command)
+        return decision
+      case 'raise-escalation':
+        await this.raiseEscalation(decision)
+        return decision
+      case 'run-phase':
+        await this.runPhase(decision, events)
+        return decision
+      case 'run-check':
+        await this.runCheck(decision)
+        return decision
+      case 'run-agent-verify':
+        await this.runAgentVerify(decision, events)
+        return decision
+      case 'evaluate-verify':
+        await this.evaluateVerify(decision, events)
+        return decision
+      case 'skip-verify':
+        await this.skipVerify(decision)
+        return decision
+      case 'run-finalize-step':
+        await this.runFinalizeStep(decision, events)
+        return decision
+      case 'check-reconcile-progress':
+        await this.checkReconcileProgress(decision, events)
+        return decision
+    }
+  }
+
+  /**
+   * The pipeline loop (§8): attach if needed, step until the build parks
+   * (`wait/*` — §11), return the final reduced state. Releases nothing on
+   * exit (leases expire; the dispatcher re-attaches) but stops the heartbeat,
+   * closes any live producer sessions (their per-round transcripts are
+   * already deposited — see module doc).
+   */
+  async run(): Promise<BuildState> {
+    if (!this.attached) {
+      const attachment = await this.attach()
+      if (attachment.kind === 'control-acknowledged') {
+        return reduceBuild(await this.deps.store.getEvents(this.deps.slug))
+      }
+    }
+    try {
+      if (publicationPending(await this.deps.store.getEvents(this.deps.slug))) {
+        return reduceBuild(await this.deps.store.getEvents(this.deps.slug))
+      }
+      for (;;) {
+        await this.ensureLease()
+        const decision = await this.step()
+        if (decision.kind === 'wait') break
+        if (publicationPending(await this.deps.store.getEvents(this.deps.slug))) break
+      }
+      return reduceBuild(await this.deps.store.getEvents(this.deps.slug))
+    } finally {
+      this.stopHeartbeat()
+      await this.closeProducerSessions()
+    }
+  }
+
+  /**
+   * §7.4 exclusivity, holder side: a lapsed lease means the sweep may already
+   * have launched a replacement, so this runner must re-claim before doing
+   * any more work. claimLease succeeds when the lease is expired or unheld
+   * (nobody took over — carry on) and fails when a live replacement holds it
+   * (stop: LeaseHeldError, mirroring attach). Checked at every loop boundary;
+   * work already in flight when the lapse happened cannot be interrupted, but
+   * nothing further executes without the lease.
+   */
+  private async ensureLease(): Promise<void> {
+    if (!this.leaseLost) return
+    const { store, slug, instance } = this.deps
+    const reclaimed = await store.claimLease(slug, instance, this.leaseTtlMs)
+    if (!reclaimed) throw new LeaseHeldError(slug, instance)
+    this.leaseLost = false
+  }
+
+  // ── Decision execution ─────────────────────────────────────────────────────
+
+  /** D2: humans append `*-requested`; the kernel acknowledges with facts. */
+  private async acknowledge(command: 'pause' | 'resume' | 'abort'): Promise<void> {
+    const { store, slug } = this.deps
+    if (command === 'pause') {
+      await store.append(slug, { actor: KERNEL, type: 'build.paused', payload: {} })
+    } else if (command === 'resume') {
+      await store.append(slug, { actor: KERNEL, type: 'build.resumed', payload: {} })
+    } else {
+      await store.append(slug, { actor: KERNEL, type: 'build.aborted', payload: {} })
+      // The execution supervisor retains ownership until the complete process
+      // tree is gone; janitor cleanup is gated by that live lease.
+    }
+  }
+
+  /** Stall/policy thresholds live in the engine (§15.4); the runner stamps
+   * the id (§15.4: ids are kernel-assigned) and appends the fact. */
+  private async raiseEscalation(decision: RaiseEscalationDecision): Promise<void> {
+    const { store, slug, ids } = this.deps
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'escalation.raised',
+      payload: {
+        id: ids('esc'),
+        phase: decision.phase,
+        ...(decision.round !== undefined ? { round: decision.round } : {}),
+        source: decision.source,
+        ...(decision.source === 'policy' ? { policyCause: decision.policyCause } : {}),
+        question: decision.question,
+        ...(decision.refs !== undefined ? { refs: decision.refs } : {}),
+      },
+    } satisfies EventWrite<'escalation.raised'>)
+  }
+
+  /**
+   * Resolve and persist the authoritative base for one repeat conflict before
+   * the engine spends reconcile policy budget. This deliberately does not
+   * reuse the snapshot as the merge target: actual phase startup refreshes
+   * again, preserving the execution-boundary freshness guarantee.
+   */
+  private async checkReconcileProgress(
+    decision: CheckReconcileProgressDecision,
+    events: AbEvent[],
+  ): Promise<void> {
+    const { nextAttempt } = decision
+    const failures = this.phaseFailures(events, 'reconcile', nextAttempt)
+    if (failures.count >= this.maxPhaseAttempts) {
+      await this.raisePolicyExhausted('reconcile', nextAttempt, failures)
+      return
+    }
+    if (failures.lastWillRetry === false) {
+      await this.raisePolicyNonRetryable('reconcile', nextAttempt, failures)
+      return
+    }
+
+    let baseSha: string
+    try {
+      baseSha = await this.refreshReconcileBase(events)
+    } catch (error) {
+      await this.failPhase(
+        'reconcile',
+        nextAttempt,
+        failures.count,
+        `failed to check reconcile progress: ${errorMessage(error)}`,
+      )
+      return
+    }
+
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'reconcile.progress-checked',
+      payload: {
+        conflictSeq: decision.conflictSeq,
+        attempt: decision.completedAttempt,
+        baseSha,
+      },
+    } satisfies EventWrite<'reconcile.progress-checked'>)
+  }
+
+  /** A core-phase run: retry guard (D5), started event (§15.3), session. */
+  private async runPhase(decision: RunPhaseDecision, events: AbEvent[]): Promise<void> {
+    const { store, slug } = this.deps
+    const { phase, round } = decision
+
+    // D5 RETRY GUARD first: at the cap, escalate instead of running — a
+    // failing phase must never loop forever.
+    const failures = this.phaseFailures(events, phase, round)
+    if (failures.count >= this.maxPhaseAttempts) {
+      await this.raisePolicyExhausted(phase, round, failures)
+      return
+    }
+    if (failures.lastWillRetry === false) {
+      await this.raisePolicyNonRetryable(phase, round, failures)
+      return
+    }
+
+    // A conflict's recorded baseSha is an observation-time snapshot. Resolve
+    // the build's frozen base branch again at the actual execution boundary,
+    // after the retry guard but before reconcile.started/the agent session.
+    // A crash re-enters this path at the same attempt and refreshes again.
+    let reconcileBaseSha: string | undefined
+    if (phase === 'reconcile') {
+      try {
+        reconcileBaseSha = await this.refreshReconcileBase(events)
+      } catch (error) {
+        await this.failPhase(
+          phase,
+          round,
+          failures.count,
+          `failed to refresh reconcile base: ${errorMessage(error)}`,
+        )
+        return
+      }
+    }
+
+    await store.append(slug, this.startedWrite(decision, reconcileBaseSha))
+
+    const spec = PHASE_SPECS[phase]
+    await this.executeSession({
+      phase,
+      round,
+      role: phase, // role name = core phase name (§9 routing)
+      skill: spec.skill,
+      abPhase: `${phase}@${round}`, // reconcile: decision.round IS the attempt
+      ...(spec.kind === 'producer' ? { producerPhase: phase } : {}),
+      ...(decision.feedback !== undefined ? { feedback: decision.feedback } : {}),
+      priorFailures: failures.count,
+      isTerminal: (event) => event.type === spec.terminalEvent && roundMatches(event, round),
+    })
+  }
+
+  /**
+   * Resolve the current remote tip of this build's immutable base branch.
+   *
+   * The fetch target is build-scoped and internal: concurrent worktrees share
+   * one Git common directory, so FETCH_HEAD or a shared remote-tracking ref
+   * would let another build overwrite the object this attempt resolves. The
+   * explicit ref also makes the fetched remote-only commit available locally.
+   */
+  private async refreshReconcileBase(events: AbEvent[]): Promise<string> {
+    const created = events.find((event) => event.type === 'build.created')
+    if (created === undefined || created.type !== 'build.created') {
+      throw new Error(
+        'this build has no build.created event — cannot resolve its frozen baseBranch (§15.3)',
+      )
+    }
+
+    const sourceRef = `refs/heads/${created.payload.baseBranch}`
+    const targetRef = `refs/autobuild/reconcile/${this.deps.slug}/base`
+    if (this.deps.forge.snapshotBase !== undefined) {
+      const sha = await this.deps.forge.snapshotBase({
+        workspacePath: this.deps.workspacePath,
+        base: created.payload.baseBranch,
+        destinationRef: targetRef,
+      })
+      if (!GIT_OBJECT_ID.test(sha)) {
+        throw new Error(
+          `${this.deps.forge.name} base snapshot did not return a commit SHA: ${JSON.stringify(sha)}`,
+        )
+      }
+      return sha
+    }
+
+    const fetchArgs = [
+      'git',
+      'fetch',
+      '--no-tags',
+      '--no-write-fetch-head',
+      'origin',
+      `+${sourceRef}:${targetRef}`,
+    ]
+    const fetched = await this.deps.exec(fetchArgs, { cwd: this.deps.workspacePath })
+    if (fetched.exitCode !== 0) {
+      throw new Error(
+        `${fetchArgs.join(' ')} exited ${fetched.exitCode}: ` +
+          `${fetched.stderr.trim() || fetched.stdout.trim() || '(no output)'}`,
+      )
+    }
+
+    const resolveArgs = ['git', 'rev-parse', '--verify', `${targetRef}^{commit}`]
+    const resolved = await this.deps.exec(resolveArgs, { cwd: this.deps.workspacePath })
+    const sha = resolved.stdout.trim()
+    if (resolved.exitCode !== 0 || !GIT_OBJECT_ID.test(sha)) {
+      throw new Error(
+        `${resolveArgs.join(' ')} did not resolve a commit SHA: ` +
+          `${resolved.stderr.trim() || sha || '(no output)'}`,
+      )
+    }
+    return sha
+  }
+
+  /**
+   * Resolve a conditional verifier against the live branch diff. Exclusion is
+   * a canonical kernel-authored skip and launches no command or session.
+   * Inclusion delegates to the existing verifier path unchanged.
+   */
+  private async evaluateVerify(decision: EvaluateVerifyDecision, events: AbEvent[]): Promise<void> {
+    const { exec, workspacePath } = this.deps
+    const baseSha = selectVerifyDiffBase(events)
+    const args = ['git', 'diff', '--no-renames', '--name-only', '-z', baseSha, 'HEAD', '--']
+    const result = await exec(args, { cwd: workspacePath })
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `${args.join(' ')} exited ${result.exitCode}: ` +
+          `${result.stderr.trim() || result.stdout.trim() || '(no output)'}`,
+      )
+    }
+    const changedPaths = parseNulChangedPaths(result.stdout)
+    const applicability = evaluateVerifyApplicability(
+      { kind: 'paths', step: decision.step, paths: decision.paths },
+      changedPaths,
+    )
+    if (!applicability.applies) {
+      await this.skipVerify({
+        kind: 'skip-verify',
+        step: decision.step,
+        attempt: decision.attempt,
+        reason: applicability.reason,
+      })
+      return
+    }
+
+    if (decision.action.kind === 'run-check') {
+      await this.runCheck(decision.action)
+    } else {
+      await this.runAgentVerify(decision.action, events)
+    }
+  }
+
+  /** Shared writer for every deterministic exclusion mechanism. A skip is a
+   * queryable two-fact phase occurrence and launches no command or session. */
+  private async skipVerify(decision: SkipVerifyDecision): Promise<void> {
+    const { store, slug } = this.deps
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'verify.started',
+      payload: { step: decision.step, attempt: decision.attempt },
+    } satisfies EventWrite<'verify.started'>)
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'verify.completed',
+      payload: {
+        step: decision.step,
+        attempt: decision.attempt,
+        outcome: 'skipped',
+        reason: decision.reason,
+      },
+    } satisfies EventWrite<'verify.completed'>)
+  }
+
+  /** Deterministic check (§8.2): NO session, NO CLI — the kernel runs the
+   * command directly; a failure deposits the output tail as the report. */
+  private async runCheck(decision: RunCheckDecision): Promise<void> {
+    const { store, slug, exec, workspacePath } = this.deps
+    const { step, command, attempt } = decision
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'verify.started',
+      payload: { step, attempt },
+    } satisfies EventWrite<'verify.started'>)
+
+    const result = await exec(['sh', '-c', command], { cwd: workspacePath })
+    if (result.exitCode === 0) {
+      await store.append(slug, {
+        actor: KERNEL,
+        type: 'verify.completed',
+        payload: { step, attempt, outcome: 'pass' },
+      } satisfies EventWrite<'verify.completed'>)
+      return
+    }
+
+    const output = [result.stdout, result.stderr].filter((s) => s !== '').join('\n')
+    const content = output.length > REPORT_TAIL_CHARS ? output.slice(-REPORT_TAIL_CHARS) : output
+    // Atomic deposit (D6): report artifact + verify.completed in one bundle;
+    // the report routes back to implement via the engine (§15.6-A).
+    await store.appendWithArtifacts(
+      slug,
+      [
+        {
+          kind: verifyReportKind(step),
+          content: content || '(no output)',
+          metadata: { step, attempt, command, exitCode: result.exitCode },
+        },
+      ],
+      (deposited) => {
+        const meta = deposited[0]
+        if (!meta) throw new Error('verify report deposit returned no metadata')
+        return {
+          actor: KERNEL,
+          type: 'verify.completed',
+          payload: {
+            step,
+            attempt,
+            outcome: 'fail',
+            report: { kind: meta.kind, rev: meta.revision },
+          },
+        } satisfies EventWrite<'verify.completed'>
+      },
+    )
+  }
+
+  /** Agent-verify step (§5): a session with a pass/fail/skip verdict. */
+  private async runAgentVerify(decision: RunAgentVerifyDecision, events: AbEvent[]): Promise<void> {
+    const { store, slug } = this.deps
+    const { step, skill, attempt, feedback } = decision
+    const phase = verifyPhase(step)
+
+    // D5 guard, extended to agent-verify (see module doc): keyed by
+    // verify:<step> with the verify attempt as the round.
+    const failures = this.phaseFailures(events, phase, attempt)
+    if (failures.count >= this.maxPhaseAttempts) {
+      await this.raisePolicyExhausted(phase, attempt, failures)
+      return
+    }
+    if (failures.lastWillRetry === false) {
+      await this.raisePolicyNonRetryable(phase, attempt, failures)
+      return
+    }
+
+    await store.append(slug, {
+      actor: KERNEL,
+      type: 'verify.started',
+      payload: { step, attempt, ...(feedback !== undefined ? { feedback } : {}) },
+    } satisfies EventWrite<'verify.started'>)
+
+    await this.executeSession({
+      phase,
+      round: attempt,
+      role: step, // role name = the verify step's logical name (§9 routing)
+      // The deprecated skill-name key, still honoured for existing configs.
+      roleAliases: [skill],
+      skill,
+      abPhase: `verify:${step}@${attempt}`,
+      priorFailures: failures.count,
+      isTerminal: (event) =>
+        event.type === 'verify.completed' &&
+        event.payload.step === step &&
+        event.payload.attempt === attempt,
+    })
+  }
+
+  /**
+   * Failure-tolerant post-step (§5). Checks run directly and agents run their
+   * exact configured skill, but either kind may commit selected repository
+   * content locally. Only this kernel boundary may publish it (D7): a clean
+   * descendant HEAD is regular-pushed and checkpointed before completion.
+   * Step, Git, and Forge failures become the ordinary failed outcome plus an
+   * observation and never route a green build backward.
+   */
+  private async runFinalizeStep(
+    decision: RunFinalizeStepDecision,
+    events: AbEvent[],
+  ): Promise<void> {
+    const { step, action } = decision
+    let actor: Actor = KERNEL
+    let durableHead: string | undefined
+    let failureNote: string | undefined
+
+    try {
+      await this.requireFinalizeWorktreeClean('before the post-step starts')
+      durableHead = selectPublishedBranchHead(events)
+    } catch (error) {
+      failureNote = `finalize publication preflight failed: ${errorMessage(error)}`
+    }
+
+    if (failureNote === undefined) {
+      if (action.kind === 'check') {
+        failureNote = await this.runFinalizeCheck(action.command)
+      } else {
+        const outcome = await this.runFinalizeAgent(step, action.skill)
+        if (outcome.cancelled) return
+        actor = outcome.actor
+        failureNote = outcome.failureNote
+      }
+    }
+
+    let pushedHead: string | undefined
+    if (failureNote === undefined && durableHead !== undefined) {
+      try {
+        await this.requireFinalizeWorktreeClean('after the post-step finishes')
+        const head = await this.resolveFinalizeHead()
+        if (head !== durableHead) {
+          await this.requirePublishedHeadAncestor(durableHead, head)
+          const scratchPaths = await scratchPathsTouchedInRange(
+            this.deps.exec,
+            this.deps.workspacePath,
+            durableHead,
+            head,
+          )
+          if (scratchPaths.length > 0) throw phaseScratchRejection(scratchPaths)
+          const remote = events.some(
+            (event) =>
+              event.type === 'workspace.provisioned' && event.payload.provider === 'vercel-sandbox',
+          )
+          if (remote) {
+            await this.deps.store.append(this.deps.slug, {
+              actor,
+              type: 'publication.requested',
+              payload: {
+                operation: 'finalize-step',
+                branch: this.deps.branch,
+                sha: head,
+                step,
+              },
+            })
+            return
+          }
+          await this.deps.forge.pushBranch(this.deps.workspacePath, this.deps.branch)
+          pushedHead = head
+        }
+      } catch (error) {
+        failureNote = `finalize publication failed: ${errorMessage(error)}`
+      }
+    }
+
+    await this.recordFinalizeOutcome(step, actor, failureNote, pushedHead)
+  }
+
+  /** A finalize check is direct kernel plumbing: no agent session is created. */
+  private async runFinalizeCheck(command: string): Promise<string | undefined> {
+    try {
+      const result = await this.deps.exec(['sh', '-c', command], {
+        cwd: this.deps.workspacePath,
+      })
+      return result.exitCode === 0 ? undefined : `command exited ${result.exitCode}`
+    } catch (error) {
+      return `command execution failed: ${errorMessage(error)}`
+    }
+  }
+
+  /** A finalize agent uses the configured skill verbatim and the logical step
+   * name for role routing. Provider/launch failures remain post-step failures,
+   * not build failures. */
+  private async runFinalizeAgent(
+    step: string,
+    skill: string,
+  ): Promise<{ actor: Actor; failureNote: string | undefined; cancelled: boolean }> {
+    const resolved = this.boundaryResolver.resolve(step)
+    if (resolved.alternates.length === 0) return this.runFinalizeAgentSingle(step, skill)
+
+    const { store, slug, ids, workspacePath } = this.deps
+    const targets: readonly ResolvedRuntime[] = [resolved, ...resolved.alternates]
+    let substitution: ProviderAttempt | undefined
+    for (let index = 0; index < targets.length; index += 1) {
+      const target = targets[index]!
+      const session = ids('s')
+      const finalizeBracket = {
+        phase: 'finalize' as const,
+        round: 1,
+        role: step,
+        runnerName: target.runtime,
+      }
+      const streamBracket = await this.openSessionStream(target, {
+        session,
+        role: step,
+        runner: target.runtime,
+        ...(target.model !== undefined ? { model: target.model } : {}),
+        phase: 'finalize',
+        round: 1,
+      })
+      const stream = streamBracket?.sink
+      const started = await store.append(slug, {
+        actor: KERNEL,
+        type: 'session.started',
+        payload: {
+          session,
+          role: step,
+          runner: target.runtime,
+          ...(target.model !== undefined ? { model: target.model } : {}),
+          args: [...target.args],
+          phase: 'finalize',
+          round: 1,
+          ...(streamBracket !== undefined ? { stream: streamBracket.streamId } : {}),
+          ...(substitution !== undefined
+            ? { substitution: { failed: substitution, selectedIndex: index } }
+            : {}),
+        },
+      } satisfies EventWrite<'session.started'>)
+      let handle: AgentSessionHandle | undefined
+      let result: AgentTurnResult | undefined
+      let turnError: unknown
+      const turn = await this.runBudgetedTurn(
+        started.seq,
+        resolved.sessionBudgetSeconds,
+        (signal) =>
+          target.runner.start({
+            skill,
+            invocation: slug,
+            buildSlug: slug,
+            workspacePath,
+            ...(target.model !== undefined ? { model: target.model } : {}),
+            ...(target.args !== undefined ? { args: target.args } : {}),
+            env: this.sessionEnvFor('finalize@1', session),
+            signal,
+            ...(stream !== undefined ? { stream } : {}),
+          }),
+      )
+      if (turn.settlement.kind === 'value') {
+        handle = turn.settlement.value.session
+        result = turn.settlement.value.result
+      } else if (turn.settlement.kind === 'error') {
+        turnError = turn.settlement.error
+      } else {
+        this.releaseLateStart(turn.pending, target.runner)
+      }
+      if (turn.abortCause === 'budget') {
+        if (handle !== undefined) {
+          this.releaseExpiredSession(
+            target.runner,
+            handle,
+            session,
+            finalizeBracket,
+            target.model,
+            streamBracket,
+          )
+        } else {
+          this.closeBracketStream(streamBracket, 'aborted')
+        }
+        return {
+          actor: agentActor(step, session),
+          failureNote: sessionBudgetError(resolved.sessionBudgetSeconds),
+          cancelled: false,
+        }
+      }
+      if (handle !== undefined) {
+        try {
+          const transcript = await target.runner.end(handle)
+          const outcome: StreamOutcome =
+            turnError === undefined && result?.kind !== 'failed' ? 'completed' : 'aborted'
+          await this.depositTranscriptAndEnd(
+            session,
+            finalizeBracket,
+            transcript.content,
+            transcript.metadata.usage,
+            transcript.metadata.model ?? target.model,
+            streamBracket !== undefined ? { stream: streamBracket, outcome } : undefined,
+          )
+        } catch {
+          // The failure-tolerant post-step still records its outcome below.
+        }
+      }
+      if (turn.abortCause === 'operator') {
+        this.closeBracketStream(streamBracket, 'aborted')
+        return { actor: agentActor(step, session), failureNote: undefined, cancelled: true }
+      }
+      if (turnError === undefined && result?.kind !== 'failed') {
+        this.closeBracketStream(streamBracket, 'completed')
+        return { actor: agentActor(step, session), failureNote: undefined, cancelled: false }
+      }
+      this.closeBracketStream(streamBracket, 'aborted')
+      const failure: AgentTurnFailure =
+        turnError !== undefined
+          ? { message: errorMessage(turnError), permanent: false, cause: 'availability' }
+          : result?.kind === 'failed'
+            ? result.failure
+            : {
+                message: 'agent session returned no result',
+                permanent: false,
+                cause: 'availability',
+              }
+      const attempt: ProviderAttempt = {
+        index,
+        session,
+        runner: target.runtime,
+        ...(target.model !== undefined ? { model: target.model } : {}),
+        error: failure.message,
+        ...(failure.cause !== undefined ? { cause: failure.cause } : {}),
+      }
+      if (index + 1 < targets.length && isAlternateEligible(failure)) {
+        substitution = attempt
+        continue
+      }
+      return {
+        actor: agentActor(step, session),
+        failureNote:
+          `${turnError !== undefined ? 'agent session failed' : 'agent turn failed'}: ` +
+          failure.message,
+        cancelled: false,
+      }
+    }
+    throw new Error('finalize alternate chain had no execution target')
+  }
+
+  private async runFinalizeAgentSingle(
+    step: string,
+    skill: string,
+  ): Promise<{ actor: Actor; failureNote: string | undefined; cancelled: boolean }> {
+    const { store, slug, ids, workspacePath } = this.deps
+    const session = ids('s')
+    const resolved = this.boundaryResolver.resolve(step)
+    const { runner, runtime: runnerName, model, args, sessionBudgetSeconds } = resolved
+    const finalizeBracket = {
+      phase: 'finalize' as const,
+      round: 1,
+      role: step,
+      runnerName,
+    }
+    const streamBracket = await this.openSessionStream(resolved, {
+      session,
+      role: step,
+      runner: runnerName,
+      ...(model !== undefined ? { model } : {}),
+      phase: 'finalize',
+      round: 1,
+    })
+    const stream = streamBracket?.sink
+
+    const started = await store.append(slug, {
+      actor: KERNEL,
+      type: 'session.started',
+      payload: {
+        session,
+        role: step,
+        runner: runnerName,
+        ...(model !== undefined ? { model } : {}),
+        args: [...args],
+        phase: 'finalize',
+        round: 1,
+        ...(streamBracket !== undefined ? { stream: streamBracket.streamId } : {}),
+      },
+    } satisfies EventWrite<'session.started'>)
+
+    let handle: AgentSessionHandle | undefined
+    let failureNote: string | undefined
+    const turn = await this.runBudgetedTurn(started.seq, sessionBudgetSeconds, (signal) =>
+      runner.start({
+        skill,
+        invocation: slug,
+        buildSlug: slug,
+        workspacePath,
+        ...(model !== undefined ? { model } : {}),
+        ...(args !== undefined ? { args } : {}),
+        env: this.sessionEnvFor('finalize@1', session),
+        signal,
+        ...(stream !== undefined ? { stream } : {}),
+      }),
+    )
+    if (turn.settlement.kind === 'value') {
+      handle = turn.settlement.value.session
+      if (turn.settlement.value.result.kind === 'failed') {
+        failureNote = `agent turn failed: ${turn.settlement.value.result.failure.message}`
+      }
+    } else if (turn.settlement.kind === 'error') {
+      failureNote = `agent session failed: ${errorMessage(turn.settlement.error)}`
+    } else {
+      this.releaseLateStart(turn.pending, runner)
+    }
+    if (turn.abortCause === 'budget') {
+      if (handle !== undefined) {
+        this.releaseExpiredSession(runner, handle, session, finalizeBracket, model, streamBracket)
+      } else {
+        this.closeBracketStream(streamBracket, 'aborted')
+      }
+      return {
+        actor: agentActor(step, session),
+        failureNote: sessionBudgetError(sessionBudgetSeconds),
+        cancelled: false,
+      }
+    }
+
+    if (handle !== undefined) {
+      try {
+        const transcript = await runner.end(handle)
+        await this.depositTranscriptAndEnd(
+          session,
+          finalizeBracket,
+          transcript.content,
+          transcript.metadata.usage,
+          transcript.metadata.model ?? model,
+          streamBracket !== undefined
+            ? {
+                stream: streamBracket,
+                outcome: failureNote === undefined ? 'completed' : 'aborted',
+              }
+            : undefined,
+        )
+      } catch {
+        // Best-effort: the step outcome below is still recorded.
+      }
+    }
+    this.closeBracketStream(
+      streamBracket,
+      failureNote === undefined && turn.abortCause !== 'operator' ? 'completed' : 'aborted',
+    )
+
+    return {
+      actor: agentActor(step, session),
+      failureNote,
+      cancelled: turn.abortCause === 'operator',
+    }
+  }
+
+  /** Both finalize kinds append the same facts and always let the engine
+   * advance. Durable-write failures still propagate; only step/publication
+   * work is failure-tolerant. */
+  private async recordFinalizeOutcome(
+    step: string,
+    actor: Actor,
+    failureNote: string | undefined,
+    pushedHead: string | undefined,
+  ): Promise<void> {
+    const { store, slug, ids } = this.deps
+    if (failureNote === undefined) {
+      await store.append(slug, {
+        actor,
+        type: 'finalize.step-completed',
+        payload: {
+          step,
+          ok: true,
+          ...(pushedHead !== undefined ? { headSha: pushedHead } : {}),
+        },
+      } satisfies EventWrite<'finalize.step-completed'>)
+      return
+    }
+
+    await store.append(slug, {
+      actor,
+      type: 'finalize.step-completed',
+      payload: { step, ok: false, note: failureNote },
+    } satisfies EventWrite<'finalize.step-completed'>)
+    // §5: a failed post-step files an observation; it never kills a green
+    // build. Store-write failures intentionally propagate: no durable fact is
+    // claimed when its append did not land.
+    await store.append(slug, {
+      actor,
+      type: 'observation.recorded',
+      payload: {
+        id: ids('o'),
+        kind: 'followup',
+        summary: `finalize step "${step}" failed — needs manual follow-up: ${failureNote}`,
+      },
+    } satisfies EventWrite<'observation.recorded'>)
+  }
+
+  private async requireFinalizeWorktreeClean(when: string): Promise<void> {
+    const args = ['git', 'status', '--porcelain']
+    const result = await this.deps.exec(args, { cwd: this.deps.workspacePath })
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `${args.join(' ')} exited ${result.exitCode}: ` +
+          `${result.stderr.trim() || result.stdout.trim() || '(no output)'}`,
+      )
+    }
+    if (result.stdout.length > 0) {
+      throw new Error(
+        `workspace must be clean ${when}; commit intended files and remove ` +
+          `temporary files before finishing:\n${result.stdout.trimEnd()}`,
+      )
+    }
+  }
+
+  private async resolveFinalizeHead(): Promise<string> {
+    const args = ['git', 'rev-parse', 'HEAD']
+    const result = await this.deps.exec(args, { cwd: this.deps.workspacePath })
+    const head = result.stdout.trim()
+    if (result.exitCode !== 0 || head.length === 0 || /\s/.test(head)) {
+      throw new Error(
+        `${args.join(' ')} did not resolve one commit: ` +
+          `${result.stderr.trim() || head || '(no output)'}`,
+      )
+    }
+    return head
+  }
+
+  private async requirePublishedHeadAncestor(
+    publishedHead: string,
+    currentHead: string,
+  ): Promise<void> {
+    const args = ['git', 'merge-base', '--is-ancestor', publishedHead, currentHead]
+    const result = await this.deps.exec(args, { cwd: this.deps.workspacePath })
+    if (result.exitCode === 0) return
+    if (result.exitCode === 1) {
+      throw new Error(
+        `finalize step rewrote branch history: published head ${publishedHead} ` +
+          `is not an ancestor of current HEAD ${currentHead}`,
+      )
+    }
+    throw new Error(
+      `${args.join(' ')} exited ${result.exitCode}: ` +
+        `${result.stderr.trim() || result.stdout.trim() || '(no output)'}`,
+    )
+  }
+
+  // ── The session bracket (§15.3) ────────────────────────────────────────────
+
+  /** Run one adapter turn under the logical role's wall-clock budget. The
+   * expiry promise is resolved one microtask after the deadline so a conforming
+   * adapter can return its endable handle first. An earlier operator abort owns
+   * classification, but does not disarm this backstop for an adapter that
+   * ignores cancellation. */
+  private async runBudgetedTurn<T>(
+    preSeq: number,
+    budgetSeconds: number,
+    run: (signal: AbortSignal) => Promise<T>,
+  ): Promise<BudgetedTurn<T>> {
+    const { store, slug } = this.deps
+    const controller = new AbortController()
+    let abortCause: 'operator' | 'budget' | undefined
+    let resolveExpiry!: (settlement: { kind: 'expired' }) => void
+    const expiry = new Promise<{ kind: 'expired' }>((resolve) => {
+      resolveExpiry = resolve
+    })
+    const pending = Promise.resolve()
+      .then(() => run(controller.signal))
+      .then(
+        (value): { kind: 'value'; value: T } => ({ kind: 'value', value }),
+        (error): { kind: 'error'; error: unknown } => ({ kind: 'error', error }),
+      )
+    const unsubscribe = store.subscribe(slug, { fromSeq: preSeq, pollMs: 25 }, (event) => {
+      if (event.type === 'build.abort-requested' && !controller.signal.aborted) {
+        abortCause = 'operator'
+        controller.abort(new Error(`build ${slug} aborted by operator`))
+      }
+    })
+    const schedule = this.deps.opts?.scheduleSessionBudget ?? defaultSessionBudgetScheduler
+    const cancelTimer = schedule(() => {
+      if (!controller.signal.aborted) {
+        abortCause = 'budget'
+        controller.abort(new Error(sessionBudgetError(budgetSeconds)))
+      }
+      queueMicrotask(() => resolveExpiry({ kind: 'expired' }))
+    }, budgetSeconds * 1000)
+
+    try {
+      const settlement = await Promise.race([pending, expiry])
+      return {
+        settlement,
+        ...(abortCause !== undefined ? { abortCause } : {}),
+        pending,
+      }
+    } finally {
+      cancelTimer()
+      unsubscribe()
+    }
+  }
+
+  /** Start resource cleanup without allowing a stuck `end()` or transcript
+   * deposit to extend an already-expired phase. Conforming adapters still end
+   * immediately; every cleanup/deposit failure remains best-effort. The
+   * bracket's stream closes `aborted` (budget cancellation) before the
+   * deposit, preserving the close-before-`session.ended` ordering. */
+  private releaseExpiredSession(
+    runner: AgentRunner,
+    handle: AgentSessionHandle,
+    session: string,
+    bracket: { phase: Phase; round: number; role: string; runnerName: string },
+    model?: string,
+    stream?: SessionBracketStream,
+  ): void {
+    void (async () => {
+      try {
+        const transcript = await runner.end(handle)
+        await this.depositTranscriptAndEnd(
+          session,
+          bracket,
+          transcript.content,
+          transcript.metadata.usage,
+          transcript.metadata.model ?? model,
+          stream !== undefined ? { stream, outcome: 'aborted' } : undefined,
+        )
+      } catch {
+        // The expiry failure must remain bounded even when cleanup is not.
+      } finally {
+        // Belt and braces: idempotent close covers a failed deposit path.
+        if (stream !== undefined) void stream.sink.close('aborted')
+      }
+    })()
+  }
+
+  /** A start call can ignore cancellation and return a handle after the kernel
+   * has advanced. End that late handle in the background so it never becomes
+   * reusable continuation state. The stale durable bracket is intentionally
+   * left for the existing recovery model; complete descendant reaping remains
+   * the execution supervisor's exit boundary. */
+  private releaseLateStart(
+    pending: Promise<Exclude<TurnSettlement<{ session: AgentSessionHandle }>, { kind: 'expired' }>>,
+    runner: AgentRunner,
+  ): void {
+    void pending.then(async (settlement) => {
+      if (settlement.kind !== 'value') return
+      try {
+        await runner.end(settlement.value.session)
+      } catch {
+        // Best-effort resource release after a non-conforming late return.
+      }
+    })
+  }
+
+  /**
+   * One bracketed agent run: `session.started` → turn → terminal check →
+   * crash-gap repair → `session.ended` (with transcript) or `phase.failed`.
+   * Producer phases with a live handle continue it (§10); reviewers always
+   * start fresh (fresh skeptic).
+   */
+  private async executeSession(spec: SessionSpec): Promise<void> {
+    const resolved = this.boundaryResolver.resolve(spec.role, ...(spec.roleAliases ?? []))
+    // Preserve the historical single-target path byte-for-byte when no chain
+    // is configured. Besides compatibility, this keeps its crash-gap and
+    // producer-continuation behavior independently well exercised.
+    if (resolved.alternates.length === 0) return this.executeSingleSession(spec)
+    return this.executeSessionChain(spec, resolved, resolved.alternates)
+  }
+
+  /** Execute all configured targets inside one phase attempt. Every target has
+   * its own durable session bracket; only exhaustion writes phase.failed. */
+  private async executeSessionChain(
+    spec: SessionSpec,
+    primary: ResolvedRole,
+    alternates: readonly ResolvedRuntime[],
+  ): Promise<void> {
+    const { store, slug, ids, workspacePath } = this.deps
+    const targets = [primary, ...alternates]
+    const attempts: ProviderAttempt[] = []
+    let substitution: ProviderAttempt | undefined
+    const primaryRoute = JSON.stringify({
+      runtime: primary.runtime,
+      model: primary.model,
+      args: primary.args,
+    })
+    let primaryLive =
+      spec.producerPhase !== undefined ? this.producerSessions.get(spec.producerPhase) : undefined
+    if (
+      primaryLive !== undefined &&
+      (primaryLive.runner !== primary.runner || primaryLive.route !== primaryRoute)
+    ) {
+      try {
+        await primaryLive.runner.end(primaryLive.handle)
+      } catch {
+        // Best-effort cleanup after the previous round reached its boundary.
+      }
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      primaryLive = undefined
+    }
+
+    for (let index = 0; index < targets.length; index += 1) {
+      const target = targets[index]!
+      const session = ids('s')
+      // SPEC §9: each chain target gets its own durable bracket and its own
+      // stream, opened before the bracket's first turn.
+      const streamBracket = await this.openSessionStream(target, {
+        session,
+        role: spec.role,
+        runner: target.runtime,
+        ...(target.model !== undefined ? { model: target.model } : {}),
+        phase: spec.phase,
+        round: spec.round,
+      })
+      const stream = streamBracket?.sink
+      const startedEnvelope = await store.append(slug, {
+        actor: KERNEL,
+        type: 'session.started',
+        payload: {
+          session,
+          role: spec.role,
+          runner: target.runtime,
+          ...(target.model !== undefined ? { model: target.model } : {}),
+          args: [...target.args],
+          phase: spec.phase,
+          round: spec.round,
+          ...(streamBracket !== undefined ? { stream: streamBracket.streamId } : {}),
+          ...(substitution !== undefined
+            ? { substitution: { failed: substitution, selectedIndex: index } }
+            : {}),
+        },
+      } satisfies EventWrite<'session.started'>)
+      const preSeq = startedEnvelope.seq
+      const live = index === 0 ? primaryLive : undefined
+
+      let handle: AgentSessionHandle | undefined = live?.handle
+      let result: AgentTurnResult | undefined
+      let turnError: unknown
+      const turn = await this.runBudgetedTurn(preSeq, primary.sessionBudgetSeconds, (signal) =>
+        live !== undefined
+          ? live.runner
+              .continue(live.handle, continueMessage(spec), {
+                env: this.sessionEnvFor(spec.abPhase, session),
+                signal,
+                ...(stream !== undefined ? { stream } : {}),
+              })
+              .then((continued) => ({ session: live.handle, result: continued }))
+          : target.runner.start({
+              skill: spec.skill,
+              invocation: slug,
+              buildSlug: slug,
+              workspacePath,
+              ...(target.model !== undefined ? { model: target.model } : {}),
+              ...(target.args !== undefined ? { args: target.args } : {}),
+              env: this.sessionEnvFor(spec.abPhase, session),
+              signal,
+              ...(stream !== undefined ? { stream } : {}),
+            }),
+      )
+      if (turn.settlement.kind === 'value') {
+        handle = turn.settlement.value.session
+        result = turn.settlement.value.result
+      } else if (turn.settlement.kind === 'error') {
+        turnError = turn.settlement.error
+      } else if (live === undefined) {
+        this.releaseLateStart(turn.pending, target.runner)
+      }
+
+      const since = await store.getEvents(slug, preSeq)
+      const terminal = since.some(
+        (event) =>
+          spec.isTerminal(event) ||
+          isPublicationBoundary(event, spec, session) ||
+          (event.type === 'escalation.raised' &&
+            event.actor.kind === 'agent' &&
+            event.actor.session === session),
+      )
+      if (spec.phase === 'plan-review' || spec.phase === 'code-review') {
+        await this.repairEscalateGap(since, spec.phase, spec.round)
+      }
+
+      const bracket = {
+        phase: spec.phase,
+        round: spec.round,
+        role: spec.role,
+        runnerName: target.runtime,
+      }
+      const owner = live?.runner ?? target.runner
+
+      if (turn.abortCause === 'operator') {
+        if (handle !== undefined) {
+          try {
+            const transcript = await owner.end(handle)
+            await this.depositTranscriptAndEnd(
+              session,
+              bracket,
+              transcript.content,
+              transcript.metadata.usage,
+              transcript.metadata.model ?? target.model,
+              streamBracket !== undefined
+                ? { stream: streamBracket, outcome: 'aborted' }
+                : undefined,
+            )
+          } catch {
+            // Cancellation remains a control boundary, never phase failure.
+          }
+        }
+        this.closeBracketStream(streamBracket, 'aborted')
+        if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+        return
+      }
+
+      // A typed terminal deposited at the deadline remains authoritative even
+      // when the adapter has not yet returned its handle/result.
+      if (terminal && turn.abortCause === 'budget') {
+        if (handle !== undefined) {
+          this.releaseExpiredSession(owner, handle, session, bracket, target.model, streamBracket)
+        } else {
+          this.closeBracketStream(streamBracket, 'aborted')
+        }
+        if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+        return
+      }
+
+      if (terminal && handle !== undefined && result !== undefined) {
+        if (spec.producerPhase !== undefined && index === 0) {
+          this.producerSessions.set(spec.producerPhase, {
+            handle,
+            runner: owner,
+            route: primaryRoute,
+          })
+          const content = JSON.stringify(
+            {
+              session,
+              phase: spec.phase,
+              round: spec.round,
+              note: 'producer session kept live for §10 continuation; per-round turn transcript',
+              turn: { text: result.text, usage: result.usage },
+            },
+            null,
+            2,
+          )
+          await this.depositTranscriptAndEnd(
+            session,
+            bracket,
+            content,
+            result.usage,
+            target.model,
+            streamBracket !== undefined
+              ? { stream: streamBracket, outcome: 'completed' }
+              : undefined,
+          )
+        } else {
+          // An alternate producer must not become sticky across the review
+          // boundary. End it like any fresh session; the next round begins on
+          // the primary and rehydrates context from durable artifacts.
+          const transcript = await owner.end(handle)
+          await this.depositTranscriptAndEnd(
+            session,
+            bracket,
+            transcript.content,
+            transcript.metadata.usage,
+            transcript.metadata.model ?? target.model,
+            streamBracket !== undefined
+              ? { stream: streamBracket, outcome: 'completed' }
+              : undefined,
+          )
+          if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+        }
+        return
+      }
+
+      if (terminal) {
+        if (handle !== undefined) {
+          try {
+            const transcript = await owner.end(handle)
+            await this.depositTranscriptAndEnd(
+              session,
+              bracket,
+              transcript.content,
+              transcript.metadata.usage,
+              transcript.metadata.model ?? target.model,
+              streamBracket !== undefined
+                ? { stream: streamBracket, outcome: 'completed' }
+                : undefined,
+            )
+          } catch {
+            // The durable terminal remains authoritative over adapter failure
+            // and best-effort transcript cleanup.
+          }
+        }
+        this.closeBracketStream(streamBracket, 'completed')
+        if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+        return
+      }
+
+      if (turn.abortCause === 'budget') {
+        if (handle !== undefined) {
+          this.releaseExpiredSession(owner, handle, session, bracket, target.model, streamBracket)
+        } else {
+          this.closeBracketStream(streamBracket, 'aborted')
+        }
+        if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+        await this.failPhase(
+          spec.phase,
+          spec.round,
+          spec.priorFailures,
+          sessionBudgetError(primary.sessionBudgetSeconds),
+          true,
+        )
+        return
+      }
+
+      if (handle !== undefined) {
+        try {
+          const transcript = await owner.end(handle)
+          await this.depositTranscriptAndEnd(
+            session,
+            bracket,
+            transcript.content,
+            transcript.metadata.usage,
+            transcript.metadata.model ?? target.model,
+            streamBracket !== undefined ? { stream: streamBracket, outcome: 'aborted' } : undefined,
+          )
+        } catch {
+          // A dead provider may leave no recoverable transcript.
+        }
+      }
+      this.closeBracketStream(streamBracket, 'aborted')
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+
+      const failure: AgentTurnFailure =
+        turnError !== undefined
+          ? { message: errorMessage(turnError), permanent: false, cause: 'availability' }
+          : result?.kind === 'failed'
+            ? result.failure
+            : { message: 'no-terminal', permanent: false }
+      const attempt: ProviderAttempt = {
+        index,
+        session,
+        runner: target.runtime,
+        ...(target.model !== undefined ? { model: target.model } : {}),
+        error: failure.message,
+        ...(failure.cause !== undefined ? { cause: failure.cause } : {}),
+      }
+      attempts.push(attempt)
+
+      const eligibleForAlternate =
+        turnError !== undefined ||
+        (result?.kind === 'failed' && isAlternateEligible(result.failure))
+      if (index + 1 < targets.length && eligibleForAlternate) {
+        substitution = attempt
+        continue
+      }
+
+      await this.failPhase(
+        spec.phase,
+        spec.round,
+        spec.priorFailures,
+        failure.message,
+        mayRetryPhase(failure),
+        attempts,
+      )
+      return
+    }
+  }
+
+  /** Historical single-target bracket, retained unchanged for repositories
+   * that declare no alternates. */
+  private async executeSingleSession(spec: SessionSpec): Promise<void> {
+    const { store, slug, ids, workspacePath } = this.deps
+    const session = ids('s')
+    // `session.started.role` records the LOGICAL name the pipeline dispatched
+    // in every case, including when a deprecated alias answered the lookup —
+    // the runtime/model on the same payload say what was resolved.
+    const resolved = this.boundaryResolver.resolve(spec.role, ...(spec.roleAliases ?? []))
+    const { runner, runtime: runnerName, model, args, sessionBudgetSeconds } = resolved
+    const route = JSON.stringify({ runtime: runnerName, model, args })
+    // SPEC §9: the stream opens before the bracket's first turn — its id is
+    // already known when `session.started` appends.
+    const streamBracket = await this.openSessionStream(resolved, {
+      session,
+      role: spec.role,
+      runner: runnerName,
+      ...(model !== undefined ? { model } : {}),
+      phase: spec.phase,
+      round: spec.round,
+    })
+    let live =
+      spec.producerPhase !== undefined ? this.producerSessions.get(spec.producerPhase) : undefined
+    if (live !== undefined && (live.runner !== runner || live.route !== route)) {
+      // A completed old round may keep provider continuation state, but a new
+      // route must begin a new provider session. The old round itself was not
+      // interrupted; it reached this boundary before being closed.
+      try {
+        await live.runner.end(live.handle)
+      } catch {
+        // Best-effort provider cleanup; route adoption must still proceed.
+      }
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      live = undefined
+    }
+
+    const startedEnvelope = await store.append(slug, {
+      actor: KERNEL,
+      type: 'session.started',
+      payload: {
+        session,
+        role: spec.role,
+        runner: runnerName,
+        ...(model !== undefined ? { model } : {}),
+        args: [...args],
+        phase: spec.phase,
+        round: spec.round,
+        ...(streamBracket !== undefined ? { stream: streamBracket.streamId } : {}),
+      },
+    } satisfies EventWrite<'session.started'>)
+    const preSeq = startedEnvelope.seq
+    const stream = streamBracket?.sink
+
+    let handle: AgentSessionHandle | undefined = live?.handle
+    let result: AgentTurnResult | undefined
+    let turnError: unknown
+    const turn = await this.runBudgetedTurn(preSeq, sessionBudgetSeconds, (signal) => {
+      if (live !== undefined) {
+        // §10: the producer continues its session; the feedback message
+        // points at the .ab/ inputs — `ab context` is the real carrier. The
+        // turn re-issues ambient auth (D8) for the NEW bracket — AB_PHASE at
+        // this round, AB_SESSION = this bracket's id — so the CLI's terminal
+        // lands on the continued round instead of being rejected as round
+        // 1's second terminal (§8.4 D5).
+        return live.runner
+          .continue(live.handle, continueMessage(spec), {
+            env: this.sessionEnvFor(spec.abPhase, session),
+            signal,
+            ...(stream !== undefined ? { stream } : {}),
+          })
+          .then((continued) => ({ session: live.handle, result: continued }))
+      }
+      return runner.start({
+        skill: spec.skill,
+        invocation: slug,
+        buildSlug: slug,
+        workspacePath,
+        ...(model !== undefined ? { model } : {}),
+        ...(args !== undefined ? { args } : {}),
+        env: this.sessionEnvFor(spec.abPhase, session),
+        signal,
+        ...(stream !== undefined ? { stream } : {}),
+      })
+    })
+    if (turn.settlement.kind === 'value') {
+      handle = turn.settlement.value.session
+      result = turn.settlement.value.result
+    } else if (turn.settlement.kind === 'error') {
+      turnError = turn.settlement.error
+    } else if (live === undefined) {
+      this.releaseLateStart(turn.pending, runner)
+    }
+
+    // The turn is over: what did the CLI leave in the log? Terminal = the
+    // phase's terminal event for this round, or an `ab escalate` from this
+    // session (§8.4: escalate is always an allowed terminal).
+    const since = await store.getEvents(slug, preSeq)
+    const terminal = since.some(
+      (event) =>
+        spec.isTerminal(event) ||
+        isPublicationBoundary(event, spec, session) ||
+        (event.type === 'escalation.raised' &&
+          event.actor.kind === 'agent' &&
+          event.actor.session === session),
+    )
+
+    // CRASH-GAP REPAIR (§8.5 makes verdict+escalation near-atomic; this keeps
+    // the log routable when the CLI died between the two).
+    if (spec.phase === 'plan-review' || spec.phase === 'code-review') {
+      await this.repairEscalateGap(since, spec.phase, spec.round)
+    }
+
+    const bracket = {
+      phase: spec.phase,
+      round: spec.round,
+      role: spec.role,
+      runnerName,
+    }
+
+    // Operator cancellation is not an infrastructure failure. Close whatever
+    // handle the adapter created, retain its transcript, and return to the
+    // engine loop; the pending durable command is acknowledged there.
+    if (turn.abortCause === 'operator') {
+      if (handle !== undefined) {
+        const owner = live?.runner ?? runner
+        try {
+          const transcript = await owner.end(handle)
+          await this.depositTranscriptAndEnd(
+            session,
+            bracket,
+            transcript.content,
+            transcript.metadata.usage,
+            transcript.metadata.model ?? model,
+            streamBracket !== undefined ? { stream: streamBracket, outcome: 'aborted' } : undefined,
+          )
+        } catch {
+          // A provider that died before yielding an endable handle leaves the
+          // open session for stale-runner recovery, but never a phase failure.
+        }
+      }
+      this.closeBracketStream(streamBracket, 'aborted')
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      return
+    }
+
+    // The typed terminal is the phase authority even when it lands on the
+    // same boundary tick as the kernel deadline.
+    if (terminal && turn.abortCause === 'budget') {
+      if (handle !== undefined) {
+        const owner = live?.runner ?? runner
+        this.releaseExpiredSession(owner, handle, session, bracket, model, streamBracket)
+      } else {
+        this.closeBracketStream(streamBracket, 'aborted')
+      }
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      return
+    }
+
+    if (terminal && handle !== undefined && result !== undefined) {
+      if (spec.producerPhase !== undefined) {
+        // §10 memory: keep the handle live for the next round; the bracket
+        // closes with THIS turn's transcript (see module doc — ending the
+        // runner session would destroy the continuation every adapter needs).
+        this.producerSessions.set(spec.producerPhase, {
+          handle,
+          runner: live?.runner ?? runner,
+          route,
+        })
+        const content = JSON.stringify(
+          {
+            session,
+            phase: spec.phase,
+            round: spec.round,
+            note: 'producer session kept live for §10 continuation; ' + 'per-round turn transcript',
+            turn: { text: result.text, usage: result.usage },
+          },
+          null,
+          2,
+        )
+        await this.depositTranscriptAndEnd(
+          session,
+          bracket,
+          content,
+          result.usage,
+          model,
+          streamBracket !== undefined ? { stream: streamBracket, outcome: 'completed' } : undefined,
+        )
+      } else {
+        // Reviewer / agent-verify: single-run session, real transcript.
+        const transcript = await runner.end(handle)
+        await this.depositTranscriptAndEnd(
+          session,
+          bracket,
+          transcript.content,
+          transcript.metadata.usage,
+          transcript.metadata.model ?? model,
+          streamBracket !== undefined ? { stream: streamBracket, outcome: 'completed' } : undefined,
+        )
+      }
+      return
+    }
+
+    if (terminal) {
+      if (handle !== undefined) {
+        const owner = live?.runner ?? runner
+        try {
+          const transcript = await owner.end(handle)
+          await this.depositTranscriptAndEnd(
+            session,
+            bracket,
+            transcript.content,
+            transcript.metadata.usage,
+            transcript.metadata.model ?? model,
+            streamBracket !== undefined
+              ? { stream: streamBracket, outcome: 'completed' }
+              : undefined,
+          )
+        } catch {
+          // The durable terminal remains authoritative over adapter failure
+          // and best-effort transcript cleanup.
+        }
+      }
+      this.closeBracketStream(streamBracket, 'completed')
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      return
+    }
+
+    if (turn.abortCause === 'budget') {
+      if (handle !== undefined) {
+        const owner = live?.runner ?? runner
+        this.releaseExpiredSession(owner, handle, session, bracket, model, streamBracket)
+      } else {
+        this.closeBracketStream(streamBracket, 'aborted')
+      }
+      if (spec.producerPhase !== undefined) this.producerSessions.delete(spec.producerPhase)
+      await this.failPhase(
+        spec.phase,
+        spec.round,
+        spec.priorFailures,
+        sessionBudgetError(sessionBudgetSeconds),
+        true,
+      )
+      return
+    }
+
+    // No terminal, a structured failed turn, or a throw: an infra failure,
+    // not a verdict (§8.4). End whatever session exists — the transcript still
+    // joins the corpus —
+    // then record the failure and drop the producer handle: a rambling
+    // session is not continued; the next attempt starts fresh (D5).
+    if (handle !== undefined) {
+      const owner = live?.runner ?? runner
+      try {
+        const transcript = await owner.end(handle)
+        await this.depositTranscriptAndEnd(
+          session,
+          bracket,
+          transcript.content,
+          transcript.metadata.usage,
+          transcript.metadata.model ?? model,
+          streamBracket !== undefined ? { stream: streamBracket, outcome: 'aborted' } : undefined,
+        )
+      } catch {
+        // Transcript deposition can still fail. A later recovering runner
+        // explicitly reclaims this open session before announcing attachment.
+      }
+    }
+    this.closeBracketStream(streamBracket, 'aborted')
+    if (spec.producerPhase !== undefined) {
+      this.producerSessions.delete(spec.producerPhase)
+    }
+    const failure =
+      turnError !== undefined
+        ? { message: errorMessage(turnError), mayRetry: true }
+        : result?.kind === 'failed'
+          ? {
+              message: result.failure.message,
+              mayRetry: !result.failure.permanent,
+            }
+          : { message: 'no-terminal', mayRetry: true }
+    await this.failPhase(
+      spec.phase,
+      spec.round,
+      spec.priorFailures,
+      failure.message,
+      failure.mayRetry,
+    )
+  }
+
+  /** Transcript artifact + `session.ended` in one atomic bundle (D6). The
+   * metadata IS the analysis corpus (§7.1): phase, round, role, runner,
+   * model, session, usage. When the bracket carried a stream, it closes
+   * here — before the `session.ended` append lands — so a reader never sees
+   * a closed session with an open stream. */
+  private async depositTranscriptAndEnd(
+    session: string,
+    bracket: { phase: Phase; round: number; role: string; runnerName: string },
+    content: string,
+    usage: { inputTokens: number; outputTokens: number; turns: number },
+    model?: string,
+    close?: { stream: SessionBracketStream; outcome: StreamOutcome },
+  ): Promise<void> {
+    const { store, slug } = this.deps
+    if (close !== undefined) {
+      // Close must land no later than `session.ended`; this makes the
+      // ordering structural rather than call-site discipline.
+      await close.stream.sink.close(close.outcome)
+    }
+    await store.appendWithArtifacts(
+      slug,
+      [
+        {
+          kind: 'transcript',
+          content,
+          metadata: {
+            phase: bracket.phase,
+            round: bracket.round,
+            role: bracket.role,
+            runner: bracket.runnerName,
+            ...(model !== undefined ? { model } : {}),
+            session,
+            usage,
+          },
+        },
+      ],
+      (deposited) => {
+        const meta = deposited[0]
+        if (!meta) throw new Error('transcript deposit returned no metadata')
+        return {
+          actor: KERNEL,
+          type: 'session.ended',
+          payload: {
+            session,
+            transcript: { kind: meta.kind, rev: meta.revision },
+            usage,
+          },
+        } satisfies EventWrite<'session.ended'>
+      },
+    )
+  }
+
+  /** A review verdict 'escalate' whose `escalation.raised` never landed →
+   * append it (kernel actor, source 'agent', question from the reason). */
+  private async repairEscalateGap(
+    since: AbEvent[],
+    phase: 'plan-review' | 'code-review',
+    round: number,
+  ): Promise<void> {
+    let verdict: { seq: number; reason?: string } | undefined
+    for (const event of since) {
+      if (event.type !== 'plan-review.verdict' && event.type !== 'code-review.verdict') {
+        continue
+      }
+      const expected = phase === 'plan-review' ? 'plan-review.verdict' : 'code-review.verdict'
+      if (event.type !== expected) continue
+      if (event.payload.round !== round || event.payload.verdict !== 'escalate') continue
+      verdict = {
+        seq: event.seq,
+        ...(event.payload.reason !== undefined ? { reason: event.payload.reason } : {}),
+      }
+    }
+    if (verdict === undefined) return
+    const raisedSeq = verdict.seq
+    if (since.some((e) => e.type === 'escalation.raised' && e.seq > raisedSeq)) return
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'escalation.raised',
+      payload: {
+        id: this.deps.ids('esc'),
+        phase,
+        round,
+        source: 'agent',
+        question: verdict.reason ?? `${phase} escalated without a recorded reason`,
+      },
+    } satisfies EventWrite<'escalation.raised'>)
+  }
+
+  // ── Session streams (SPEC §9) ────────────────────────────────────────────
+
+  /**
+   * Open one stream for this session bracket through the resolved target's
+   * streaming capability: create the store-backed sink, call the capability,
+   * and — once it returns an id — emit the bracket's `data-ab-session` part.
+   * Returns undefined (and reports once) when streaming is disabled, the
+   * runtime declared no capability, or the opener declined/failed; the
+   * bracket then proceeds exactly as without streams.
+   */
+  private async openSessionStream(
+    target: ResolvedRuntime,
+    info: SessionStreamInfo,
+  ): Promise<SessionBracketStream | undefined> {
+    if (!this.streamSessions) return undefined
+    const open = target.openSessionStream
+    if (open === undefined) return undefined
+    const sink = createSessionStreamSink({
+      store: this.deps.store,
+      scope: { kind: 'build', build: this.deps.slug },
+      onDiagnostic: this.onDiagnostic,
+    })
+    try {
+      const streamId = await open(sink, info)
+      if (streamId === undefined) return undefined
+      sink.append([sessionPart(info)])
+      return { sink, streamId, info }
+    } catch (error) {
+      this.onDiagnostic(
+        `session stream for "${info.session}" failed to open: ${errorMessage(error)}`,
+      )
+      return undefined
+    }
+  }
+
+  /** Best-effort belt-and-braces close; idempotency makes repeated calls
+   * harmless and lets the deposit path own the close-then-append ordering. */
+  private closeBracketStream(
+    stream: SessionBracketStream | undefined,
+    outcome: StreamOutcome,
+  ): void {
+    if (stream === undefined) return
+    void stream.sink.close(outcome)
+  }
+
+  /** D8 ambient auth: sessionEnv may override AB_STORE (remote stores) and
+   * add AB_TOKEN, but never the per-session identity keys. */
+  private sessionEnvFor(abPhase: string, session: string): Record<string, string> {
+    return {
+      AB_STORE: 'local',
+      ...this.deps.sessionEnv,
+      AB_BUILD: this.deps.slug,
+      AB_PHASE: abPhase,
+      AB_SESSION: session,
+    }
+  }
+
+  /**
+   * phase.failed tally for one phase+round — D5's retry-guard input.
+   *
+   * An answered escalation re-arms this budget only when its semantic class
+   * acknowledges phase-runner failures (§15.6-B). Runner-failure causes reset
+   * their matching round, the phase-level verify cause resets all rounds, and
+   * unrelated policy causes reset nothing. Cause-less historical and
+   * non-policy raises retain the legacy round-shaped behavior. Failures after
+   * an applicable answer count again, so a still-failing phase re-escalates on
+   * new evidence instead of deadlocking before its recovery session starts.
+   */
+  private phaseFailures(
+    events: AbEvent[],
+    phase: Phase,
+    round: number,
+  ): {
+    count: number
+    lastError?: string
+    lastWillRetry?: boolean
+    lastProviderAttempts?: readonly ProviderAttempt[]
+  } {
+    /** id → the raise's reset semantics — answers are matched by id (§15.3). */
+    const raised = new Map<string, PhaseFailureResetEscalation>()
+    let count = 0
+    let lastError: string | undefined
+    let lastWillRetry: boolean | undefined
+    let lastProviderAttempts: readonly ProviderAttempt[] | undefined
+    for (const event of events) {
+      switch (event.type) {
+        case 'escalation.raised':
+          raised.set(event.payload.id, {
+            phase: event.payload.phase,
+            source: event.payload.source,
+            ...(event.payload.policyCause !== undefined
+              ? { policyCause: event.payload.policyCause }
+              : {}),
+            ...(event.payload.round !== undefined ? { round: event.payload.round } : {}),
+          })
+          break
+        case 'escalation.answered': {
+          const raise = raised.get(event.payload.id)
+          if (raise !== undefined && resetsPhaseFailureBudget(raise, phase, round)) {
+            count = 0
+            lastError = undefined
+            lastWillRetry = undefined
+            lastProviderAttempts = undefined
+          }
+          break
+        }
+        case 'phase.failed':
+          if (event.payload.phase === phase && event.payload.round === round) {
+            count += 1
+            lastError = event.payload.error
+            lastWillRetry = event.payload.willRetry
+            lastProviderAttempts = event.payload.providerAttempts
+          }
+          break
+        default:
+          break
+      }
+    }
+    return {
+      count,
+      ...(lastError !== undefined ? { lastError } : {}),
+      ...(lastWillRetry !== undefined ? { lastWillRetry } : {}),
+      ...(lastProviderAttempts !== undefined ? { lastProviderAttempts } : {}),
+    }
+  }
+
+  private async failPhase(
+    phase: Phase,
+    round: number,
+    priorFailures: number,
+    error: string,
+    mayRetry = true,
+    providerAttempts?: readonly ProviderAttempt[],
+  ): Promise<void> {
+    const attempt = priorFailures + 1
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'phase.failed',
+      payload: {
+        phase,
+        round,
+        attempt,
+        error,
+        willRetry: mayRetry && attempt < this.maxPhaseAttempts,
+        ...(providerAttempts !== undefined ? { providerAttempts: [...providerAttempts] } : {}),
+      },
+    } satisfies EventWrite<'phase.failed'>)
+  }
+
+  /** A provider/runner-declared permanent failure parks immediately. The fact
+   * comes from the latest durable `phase.failed {willRetry:false}`, so a crash
+   * between that write and this escalation resumes safely without attempt 2. */
+  private async raisePolicyNonRetryable(
+    phase: Phase,
+    round: number,
+    failures: {
+      count: number
+      lastError?: string
+      lastProviderAttempts?: readonly ProviderAttempt[]
+    },
+  ): Promise<void> {
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'escalation.raised',
+      payload: {
+        id: this.deps.ids('esc'),
+        phase,
+        round,
+        source: 'policy',
+        policyCause: 'non-retryable-phase-failure',
+        question:
+          `${phase} round ${round} stopped after a non-retryable ` +
+          `provider/runner failure on attempt ${failures.count}; last error: ` +
+          `${failures.lastError ?? 'unknown'}` +
+          providerAttemptSummary(failures.lastProviderAttempts),
+      },
+    } satisfies EventWrite<'escalation.raised'>)
+  }
+
+  /** D5: the retry cap escalates (source 'policy') instead of running,
+   * naming the phase, round, and last error. */
+  private async raisePolicyExhausted(
+    phase: Phase,
+    round: number,
+    failures: {
+      count: number
+      lastError?: string
+      lastProviderAttempts?: readonly ProviderAttempt[]
+    },
+  ): Promise<void> {
+    await this.deps.store.append(this.deps.slug, {
+      actor: KERNEL,
+      type: 'escalation.raised',
+      payload: {
+        id: this.deps.ids('esc'),
+        phase,
+        round,
+        source: 'policy',
+        policyCause: 'phase-attempt-limit',
+        question:
+          `${phase} round ${round} failed ${failures.count} times ` +
+          `(maxPhaseAttempts ${this.maxPhaseAttempts}); last error: ` +
+          `${failures.lastError ?? 'unknown'}` +
+          providerAttemptSummary(failures.lastProviderAttempts),
+      },
+    } satisfies EventWrite<'escalation.raised'>)
+  }
+
+  /** The phase's started event, payload per the catalog (§15.3). */
+  private startedWrite(decision: RunPhaseDecision, reconcileBaseSha?: string): EventWrite {
+    const { phase, round } = decision
+    switch (phase) {
+      case 'plan':
+        // Feedback rides the started payload exactly like implement (§15.3
+        // symmetric by design): a parked plan loop re-attaches with a FRESH
+        // session, so `ab context` — not the continue message — is what
+        // delivers an answered guidance escalation to the producer (§15.6-B).
+        return {
+          actor: KERNEL,
+          type: 'plan.started',
+          payload: {
+            round,
+            ...(decision.feedback !== undefined ? { feedback: decision.feedback } : {}),
+          },
+        } satisfies EventWrite<'plan.started'>
+      case 'plan-review':
+        return {
+          actor: KERNEL,
+          type: 'plan-review.started',
+          payload: { round },
+        } satisfies EventWrite<'plan-review.started'>
+      case 'implement':
+        return {
+          actor: KERNEL,
+          type: 'implement.started',
+          payload: {
+            round,
+            ...(decision.feedback !== undefined ? { feedback: decision.feedback } : {}),
+          },
+        } satisfies EventWrite<'implement.started'>
+      case 'code-review':
+        return {
+          actor: KERNEL,
+          type: 'code-review.started',
+          payload: { round },
+        } satisfies EventWrite<'code-review.started'>
+      case 'finalize':
+        return {
+          actor: KERNEL,
+          type: 'finalize.started',
+          payload: {},
+        } satisfies EventWrite<'finalize.started'>
+      case 'reconcile': {
+        const reconcile = decision.reconcile
+        if (reconcile === undefined || reconcileBaseSha === undefined) {
+          // The engine supplies the attempt; runPhase resolves the current
+          // base before calling this helper. Keep the runner total anyway.
+          throw new Error('run-phase reconcile start requires an attempt and refreshed base SHA')
+        }
+        return {
+          actor: KERNEL,
+          type: 'reconcile.started',
+          payload: { attempt: reconcile.attempt, baseSha: reconcileBaseSha },
+        } satisfies EventWrite<'reconcile.started'>
+      }
+    }
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer !== undefined) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = undefined
+    }
+  }
+
+  /** End live producer sessions best-effort on exit: every round already
+   * deposited its transcript, so the cumulative turn log is discarded; no
+   * events are appended (the brackets are already closed). */
+  private async closeProducerSessions(): Promise<void> {
+    for (const entry of this.producerSessions.values()) {
+      try {
+        await entry.runner.end(entry.handle)
+      } catch {
+        // Already dead — nothing to release.
+      }
+    }
+    this.producerSessions.clear()
+  }
+}