Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
112 KB
Raw Blame
/**
 * TaskExecutor — runs a single task through the LLM tool-use loop.
 *
 * Disposable: created per task by AgentStateMachine, discarded on completion.
 * Holds per-task state (task, conversation, tool count) that was previously
 * singleton on the AgentStateMachine.
 */
import { randomUUID } from 'node:crypto'
import { snapshotTaskTokenBaseline } from '../budget/taskBrake'
import type { TaskTokenBaseline } from '../budget/taskBrake'
import { BRIDGE_TOOL_NAMES } from '../capabilities/toolCatalogTools'
import { config as appConfig } from '../config'
import { bindTaskSignal, withAbort } from '../core/adapters/abortableLlmPort'
import { maybeWrapFailover } from '../core/adapters/failoverLlmPort'
import { maybeWrapHookedLlmPort } from '../core/adapters/hookedLlmPort'
import { AdapterStaticContext, LlmPortAdapter } from '../core/adapters/llmPortAdapter'
import { CompositeToolRegistry, McpToolRegistryAdapter } from '../core/adapters/toolRegistryAdapter'
import {
  AttachmentReadLedger,
  mergeAttachmentReadLedgerSnapshots,
  readAttachmentReadLedgerSnapshot,
} from '../core/attachments/attachmentReadBudget'
import { compactConversation } from '../core/conversation/compaction'
import { ConversationManager } from '../core/conversation/conversation'
import { deriveAutoTitle } from '../core/conversation/sessionTitle'
import { LlmError, LlmErrorCode } from '../core/errors'
import { ApprovalController } from '../core/extensions/approvalController'
import type { ApprovalConfig } from '../core/extensions/approvalTypes'
import {
  COMPACTION_PRESSURE_THRESHOLD,
  PressureContextManager,
  tierDecisionTokens,
  toolMessageBudgetTokens,
} from '../core/extensions/contextManager'
import {
  UnifiedApprovalGateController,
  buildConnectRequiredApproval,
  extractConnectRequiredMarker,
} from '../core/extensions/mcpApprovalGateController'
import { type GuardrailsConfig, buildToolLaneGuardrail } from '../core/guardrails'
import type { AgentEventEmitter, LlmPort, LoopController, ToolRegistry } from '../core/interfaces'
import { DeferrableToolController } from '../core/orchestration/deferrableToolController'
import type { SimpleEventEmitter } from '../core/orchestration/eventEmitter'
import { buildLoopConfig } from '../core/orchestration/loopConfig'
import type { LoopConfig } from '../core/orchestration/loopConfig'
import { DefaultLoopController } from '../core/orchestration/loopConfig'
import { NativeToolPresentationController } from '../core/orchestration/nativeToolPresentationController'
import type { SpilloverResolver } from '../core/orchestration/spilloverResolver'
import { StubSpilloverResolver } from '../core/orchestration/spilloverResolver'
import {
  resolveToolPresentation,
  selectDeferredNatives,
} from '../core/orchestration/toolPresentationPolicy'
import {
  buildOutputPreview,
  executeSingleTool,
  extractInputPreview,
  runToolUseLoop,
  validateToolLinkages,
} from '../core/orchestration/toolUseLoop'
import {
  collectToolAttachments,
  mergeCollectedAttachments,
} from '../core/orchestration/toolUseLoopMessages'
import { turnStopResult } from '../core/orchestration/toolUseLoopRuntime'
import {
  type PreparedGfsFile,
  attachedFilesForTurnContext,
  buildTurnContextBlock,
} from '../core/orchestration/turnContext'
import { DefaultReasoningFactory } from '../core/reasoning'
import {
  CAPABILITY_CONTRACT_TEXT,
  DESKTOP_ENVIRONMENT_HINT,
  DefaultPromptBuilder,
  GFS_WORKSPACE_FILE_GUIDANCE_TEXT,
  MCP_SERVER_SELECTION_TEXT,
  MEMORY_GUIDANCE_TEXT,
  WORKFLOW_RECIPES_TEXT,
  toolDiscoveryText,
} from '../core/reasoning/promptBuilder'
import type { SystemPromptParts } from '../core/reasoning/systemPrompt'
import { BasicSafety } from '../core/safety/safety'
import type { SessionSearchService } from '../core/sessionSearch'
import { FsSpilloverResolver, SpilloverStorage } from '../core/spillover'
import { createTokenCounter } from '../core/tokenizer'
import type { TokenCounter } from '../core/tokenizer/tokenCounter'
import { registerDesktopTools } from '../core/tools/desktopTools'
import { NativeToolRegistry } from '../core/tools/nativeToolRegistry'
import { WorkflowBrokerClient } from '../core/tools/workflowBrokerClient'
import {
  requestEffectiveWorkflowList,
  resolveEffectiveWorkflowTarget,
} from '../core/tools/workflowEffectiveTargets'
import type { WorkflowCallerContext } from '../core/tools/workflowShared'
import { createWorkflowControlTokenProvider } from '../core/tools/workflowTokenProvider'
import type {
  AgentEvent,
  Attachment,
  ChatMessage,
  Conversation,
  LoopResult,
  MessageContentPart,
  PendingApproval,
  ToolDefinition,
  ToolResult,
} from '../core/types'
import { ApprovalExpiredError } from '../core/types'
import { prependTextToParts, textContentFromParts } from '../core/types'
import type { UsageContext } from '../core/types'
import type { GfsDownloadStore } from '../internalTools/gfsDownloadStore'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import type { SingleTurnProvider } from '../llm'
import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { stampStableHashGauge } from '../llm/promptCacheMetrics'
import { descriptorFor, isLlmProvider, resolveContextWindow } from '../llm/registryCore'
import { logger } from '../logger'
import type { McpManager } from '../mcp'
import { getDisplayName, sanitizeError } from '../progress/intentExtraction.js'
import {
  SseProgressReporter,
  ensureReporter,
  progressReporterRegistry,
} from '../progress/sseProgressReporter.js'
import type { Task, TaskError, TaskSource } from '../queue/types'
import { resolveCronTaskSessionKey, serializeSessionKey } from '../session'
import { GovernedRunReporter, UsageReporter } from '../usage/usageReporter.js'
import { resolveProviderWorkflowCallerContext } from '../workflow/providerWorkflowCallerContextClient'
import type { Workspace } from '../workspace/service'
import { attachmentContextWindow } from './attachmentContextWindow'
import type { CronScheduler } from './cronScheduler'
import { referencedFilesForTurnContext } from './fileReferenceResolver'
import {
  gfsManagedWorkspaceExecution,
  gfsStoreCallerIdentity,
  gfsWorkspaceExecutionEnabled,
} from './gfsExecutionCapability'
import { hasLargeAvailableGfsReferences, prepareGfsFiles } from './gfsFilePreparation'
import {
  type ProviderWorkflowAccessDenialReason,
  isProviderWorkflowChannel,
  looksLikeWorkflowAccessRequest,
  looksLikeWorkflowTriggerRequest,
  looksLikeWorkflowTriggerSuccess,
  workflowAccessDeniedResponseForMessage,
} from './providerWorkflowAccessGate'
import { sourceMessageForResume } from './sourceMessageForResume'
import { TaskExecutionBudget, TaskLimitError } from './taskExecutionBudget'
import { TurnTimingRecorder } from './turnTiming'
import type { AgentConfig, ExecutorFailoverSupport } from './types'

export type ExecutorState = 'processing' | 'waiting_approval' | 'completed' | 'failed'

/**
 * R2 — the serialized session key a task runs under. Extracted so the agent's
 * per-task model resolver (`executeTask`) reads the SAME key the executor's
 * `run()` uses for `getOrCreate`. INVARIANT: for `source==='cron'` this MUST
 * agree with the key `cronDispatch.ts` enqueued under.
 */
export function resolveTaskSessionKey(task: Task): string {
  const msg = task.sourceMessage
  const cronSession = task.source === 'cron' ? resolveCronTaskSessionKey(task) : undefined
  return serializeSessionKey(
    cronSession ?? {
      userId: msg?.sender || 'anonymous',
      channelType: msg?.channelType || 'internal',
      channelId: msg?.channelId || 'default',
      threadId: msg?.threadId,
    }
  )
}

/**
 * §6.3 — is there a human who can answer a guardrail `ask` in this run?
 *
 * Only `channel` tasks have one: a person is on the other end of the message that
 * started them (including channelType `rpc`, the Desktop App). `cron` fires on a
 * schedule and `internal` is a system-generated task with no requester, so an
 * `ask` there would suspend into `pending_approval` with nobody able to respond —
 * the task hangs. Unattended turns that into the fail-safe deny instead.
 *
 * Deliberately an allowlist of the attended source, not a denylist of the
 * autonomous ones: a source added later defaults to "assume nobody is watching",
 * which fails closed. The previous `source === 'cron' ? ... : 'interactive'` had
 * the opposite default and already mislabelled `internal`.
 */
export function executionModeForSource(source: TaskSource): 'interactive' | 'unattended' {
  return source === 'channel' ? 'interactive' : 'unattended'
}

/**
 * The caller root generated files go under. A message with no sender would
 * share one folder with every other sender-less message on its channel, so it
 * gets none and the generators refuse to write. A task with no message at all
 * (cron, system) keeps the reserved system folder.
 */
export function generatedOutputsRoot(
  sourceMessage: Task['sourceMessage'],
  callerRoot: string | undefined
): string | undefined {
  if (sourceMessage && !(sourceMessage.sender ?? '').trim()) return undefined
  return callerRoot
}

export interface TaskExecutorDeps {
  conversationManager: ConversationManager
  llmProvider: SingleTurnProvider
  mcpManager: McpManager | null
  workspaceService: Workspace | undefined
  /** Host-owned store shared across tasks; task registries receive caller-bound handles. */
  gfsDownloadStore?: GfsDownloadStore
  /** Trusted caller workspace root, separate from memory-tool availability. */
  gfsCallerWorkspacePath?: string
  config: AgentConfig
  modelName: string
  /**
   * R2 — context-window override for the effective model, read from the
   * allowlist entry by the per-task resolver. Feeds the reasoning-factory
   * breakdown denominator and the PressureContextManager budget. Undefined →
   * fall back to `CLERUM_CONTEXT_MAX_TOKENS` (today's behaviour).
   */
  contextWindowTokens?: number
  approvalConfig: ApprovalConfig | undefined
  guardrailsConfig?: GuardrailsConfig
  coreEvents: SimpleEventEmitter
  cronScheduler: CronScheduler | null
  taskLifecycle: TaskLifecycle
  /**
   * Returns operator-managed env vars (ConfigStore snapshot) for the
   * shell-tool spawn-time merge. Optional — falls back to {} when omitted.
   */
  dynamicEnvProvider?: () => Record<string, string>
  /**
   * Returns ConfigStore-managed secret name/value pairs for the output
   * sanitizer to redact from tool output. Optional — falls back to no
   * extra redaction when omitted.
   */
  secretEntriesProvider?: () => Array<{ name: string; value: string }>
  /**
   * Optional usage reporter + static host context. When both are present,
   * every successful LLM round-trip enqueues an LlmUsageEvent. Absent in
   * dev mode and in tests.
   */
  usageReporter?: UsageReporter
  usageStaticContext?: AdapterStaticContext
  governedRunReporter?: GovernedRunReporter

  /**
   * IronClaw invariant #2 (P.3 + T1.5): resolver for spillover refs in the
   * approval snapshot. Defaults to a fresh `FsSpilloverResolver` against
   * `spilloverStorage` if provided, else `StubSpilloverResolver` (passthrough
   * for inline content, throw for refs — useful for tests).
   */
  spilloverResolver?: SpilloverResolver

  /**
   * T1.5 — Tool-result spillover. When set, oversized tool outputs are
   * persisted out-of-band and the `tool` message ships a rich summary plus
   * the `spillover_ref` URI. Also drives `clerum__spillover_read` registration
   * in the native tool registry and the resolver default above.
   */
  spilloverStorage?: SpilloverStorage

  /**
   * T2.2 — Process-wide system-prompt cache. When set together with
   * `appConfig.promptCacheEnabled`, `buildLoopConfig` consults the cache
   * (keyed by sessionKey) to fetch the tiered `SystemPromptParts` and
   * forwards them to the cache-aware path of the LLM port. Absent in tests
   * and when the flag is OFF.
   */
  promptCache?: PromptCache

  /**
   * T3.1 — backend for `clerum__session_search`. When set together with a
   * `sourceMessage`, the tool is registered in the native registry. Absent
   * when the SQLite store is disabled (memory mode) or when the feature
   * flag `CLERUM_SESSION_SEARCH_ENABLED` is OFF.
   */
  sessionSearchService?: SessionSearchService

  /**
   * R5 — provider-fallback support for THIS task. When present with a non-empty
   * `policy.fallbacks`, `buildLoopConfig` wraps the primary `LlmPort` so an
   * eligible provider error switches to the next fallback (adapter-per-attempt
   * so `usage_events` records the pair really served). Absent → no failover.
   */
  failover?: ExecutorFailoverSupport

  /**
   * Issue #654 — live-catalog image-input capability lookup, keyed by the
   * (provider, model) the adapter is about to send. Threaded to the primary
   * port AND every failover adapter so the guard checks the pair that really
   * runs. Absent → images fail closed with `LLM_IMAGE_INPUT_UNKNOWN` and
   * text-only turns are unchanged.
   */
  imageInput?: ImageInputResolver

  // Callbacks to coordinator
  onApprovalNeeded: (requestId: string, taskId: string, approval: PendingApproval) => void
  onComplete: (task: Task) => void
  onFail: (task: Task, error: TaskError, attachments?: Attachment[]) => void
}

interface TaskToolRegistry {
  registry: ToolRegistry
  nativeRegistry: NativeToolRegistry
  loopController: LoopController
  /** Natives hidden from `tools[]` by native `auto`; empty in `direct`. */
  discoverableNatives: ToolDefinition[]
  bridge?: LoopConfig['bridge']
}

export class TaskExecutor {
  private readonly responseSafety: BasicSafety
  readonly taskId: string
  private task: Task
  private conversation: Conversation | null = null
  private state: ExecutorState = 'processing'
  private deps: TaskExecutorDeps
  private abortController = new AbortController()
  private readonly executionBudget: TaskExecutionBudget
  private legacyApprovalBudget = false
  private readonly completedAttachments: Attachment[] = []
  private toolRegistryPromise: Promise<TaskToolRegistry> | null = null
  private preparedGfsFiles: PreparedGfsFile[] = []
  private readonly spilloverResolver: SpilloverResolver
  /**
   * P.2 token counter. Built lazily on the first call to
   * `getOrCreateTokenCounter()` and shared across `runAgentLoop`,
   * `LlmPortAdapter`, and `PressureContextManager` so `recordObservedUsage`
   * accumulates across iterations of the same task.
   */
  private tokenCounter: TokenCounter | null = null
  /** #731 — the task's context window, resolved and logged once. */
  private contextWindow: number | null = null
  /**
   * C15/C16 — one turn-owned attachment read ledger per executor. An executor
   * runs one task, and a task is one turn, so the ledger starts zeroed and is
   * never reset. The native tool registry is memoized for the life of this
   * executor, so the tool holds THIS instance by reference and the ledger
   * mutates in place; `restore()` loads the persisted snapshot on an approval
   * resume that continues the same turn.
   */
  private readonly attachmentReadLedger = new AttachmentReadLedger()
  /**
   * P2 token budgets (§5.2) — snapshot of the conversation's lifetime token
   * counters captured at task start, used as the per-task brake baseline.
   * Set in `run()` (once per task) only when the P1 verdict carried a per-task
   * cap; reused unchanged across `resumeAfterApproval`. `null` → brake disabled.
   */
  private taskTokenBaseline: TaskTokenBaseline | null = null
  private workflowCallerContextOverride: WorkflowCallerContext | null | undefined
  private workflowAccessDeniedResponse: string | null = null
  private workflowAccessDeniedReason: ProviderWorkflowAccessDenialReason | null = null
  private currentTurnToolNames = new Set<string>()
  private gfsRetentionOwnerSettlement: Promise<void> | undefined
  /**
   * Latency attribution (stateless-agents): per-turn phase timing. Created at
   * run() start; emits one [TurnTiming] info line when the task completes.
   * Purely observational — never affects control flow (fail-safe recorder).
   */
  private turnTiming: TurnTimingRecorder | null = null

  // Completion tracking for graceful shutdown
  private resolveCompletion: (() => void) | null = null
  private completionPromise: Promise<void>

  constructor(task: Task, deps: TaskExecutorDeps) {
    this.task = task
    this.taskId = task.id
    this.deps = deps
    this.executionBudget = new TaskExecutionBudget(
      deps.config.maxTaskDuration,
      deps.config.maxToolCallsPerTask
    )
    this.responseSafety = new BasicSafety(deps.secretEntriesProvider)
    // T1.5 — prefer a caller-supplied resolver (tests/mocks); else build the
    // FS-backed one from the storage; else fall back to the P.3 stub so
    // dev/test paths without spillover wired still work.
    this.spilloverResolver =
      deps.spilloverResolver ??
      (deps.spilloverStorage
        ? new FsSpilloverResolver({ storage: deps.spilloverStorage })
        : new StubSpilloverResolver())
    this.completionPromise = new Promise<void>(resolve => {
      this.resolveCompletion = resolve
    })
  }

  get executorState(): ExecutorState {
    return this.state
  }

  get pendingApproval(): PendingApproval | undefined {
    return this.conversation?.pending_approval
  }

  private approvedToolCorrelation: { toolCallId: string; approvalRequestId: string } | undefined

  /**
   * The serialized session key this executor owns (the store's LRU/evict key,
   * `<userId>:<channelType>:<channelId>[:<threadId>]`). Exposed so callers
   * (e.g. `AgentStateMachine.compactSession`) can detect "this session is
   * currently owned by an executor" without reaching into the private
   * conversation field.
   *
   * MUST agree with the key the store evicts by and the prompt-cache key.
   * Prefers `conversation.session_key` (the serialized key); falls back to
   * `user_id` only for conversations created before that field existed.
   * Do NOT return the bare `user_id`: `user_id` is `msg.sender`, which would
   * (a) never match the serialized `opts.sessionKey` in the busy guard and
   * (b) collide across channels/threads of the same user in the prompt cache.
   */
  get sessionKey(): string | undefined {
    return this.conversation?.session_key ?? this.conversation?.user_id
  }

  get sourceTask(): Task {
    return this.task
  }

  /** The AbortSignal for this executor's loop. Used by Task 3 tests. */
  get signal(): AbortSignal {
    return this.abortController.signal
  }

  async rehydrateWaitingApproval(sessionKey: string, approval: PendingApproval): Promise<void> {
    const message = this.task.sourceMessage
    this.conversation = await this.deps.conversationManager.getOrCreate(sessionKey, {
      userId: message?.sender,
      channelType: message?.channelType,
      channelId: message?.channelId,
      threadId: message?.threadId,
      source: message?.channelType,
    })
    if (
      this.conversation.pending_approval?.request_id !== approval.request_id ||
      this.conversation.activeTaskId !== this.taskId
    ) {
      throw new Error('persisted approval does not match its active conversation task')
    }
    if (approval.task_budget !== undefined) this.executionBudget.restore(approval.task_budget)
    else if (approval.legacy_budget === true) this.legacyApprovalBudget = true
    else throw new Error('Pending approval has no verifiable execution budget')
    if (approval.authorization_scope !== 'turn_tools') {
      // Legacy rows predate consent provenance. A wildcard retained by an old
      // process must not authorize a different risky tool after cold resume.
      this.conversation.auto_approved_tools.delete('*')
    }
    this.task.traceContext = approval.traceContext ?? this.conversation.traceContext ?? null
    this.state = 'waiting_approval'
  }

  /**
   * Returns a promise that resolves when the executor finishes (completed, failed, or denied).
   * Used by AgentStateMachine.stop() to await graceful shutdown.
   */
  waitForCompletion(): Promise<void> {
    return this.completionPromise
  }

  /**
   * Run the task through the LLM tool-use loop.
   * On completion, calls onComplete or onFail callback.
   * On need_approval, sets state and calls onApprovalNeeded.
   */
  async run(): Promise<void> {
    logger.info({ taskId: this.taskId }, 'Task starting')

    try {
      this.state = 'processing'
      this.executionBudget.start(this.abortController)
      this.turnTiming = new TurnTimingRecorder(this.task.createdAt)

      // 1. Resolve session key, get/create conversation
      // INVARIANT: for source==='cron' this MUST produce the same session key that
      // cronDispatch.ts enqueued the task under (both call resolveCronTaskSessionKey).
      // A divergence would run the task in a different session than it was queued in.
      const msg = this.task.sourceMessage
      const cronSession =
        this.task.source === 'cron' ? resolveCronTaskSessionKey(this.task) : undefined
      const sessionKey = resolveTaskSessionKey(this.task)
      logger.debug({ taskId: this.taskId }, 'Session resolved')

      const sessionLoadStart = Date.now()
      this.conversation = await this.deps.conversationManager.getOrCreate(sessionKey, {
        userId: cronSession?.userId ?? msg?.sender,
        channelType: cronSession?.channelType ?? msg?.channelType,
        channelId: cronSession?.channelId ?? msg?.channelId,
        threadId: cronSession?.threadId ?? msg?.threadId,
        source: cronSession?.channelType ?? msg?.channelType,
        // R2 — record the effective model served (resolved by the agent from the
        // session's saved selection before this executor was built) in the
        // `sessions.model` telemetry column at INSERT time.
        model: this.deps.modelName,
      })
      if (this.task.traceContext?.origin === 'channel_event' && !this.task.traceContext.sessionId) {
        this.task.traceContext = {
          ...this.task.traceContext,
          sessionId: this.conversation.id,
        }
      }
      const userInput = msg?.content || this.task.conversationHistory[0]?.content || ''
      // Auto-title (spec 15): on turn 1 only, derive the server-authoritative
      // session title. Security order is FIXED (§5): redact the FULL input with
      // the operator secret list FIRST, then collapse+truncate — truncating
      // first would split a secret across the cut and defeat the literal match.
      // `sanitizeFreeformContent` (not `sanitizeOutput`) so we don't emit a log
      // line per turn. Applies to channel sessions too (same sanitization).
      //
      // "Turn 1" gate: `turns.length === 0` is a RAM proxy for the durable
      // turn-1 signal. It MUST stay in lock-step with the durable write gate in
      // `SqliteConversationStore.persistTurnStart` (`turnNumber === 1`): if this
      // set a RAM title on a turn the durable write skips, the memory store would
      // project a title the SQLite store does not, breaking dual-store parity.
      // The two agree today because a fresh session starts at `turns.length === 0`
      // AND `nextTurnNumber === 1`, and a cold-load rehydrates both together.
      // They would diverge only if compaction/LRU/paginated cold-load ever shrank
      // `turns` without resetting the durable `turnNumber` — none of which exist
      // yet. If any is enabled, gate this on the durable turn number instead
      // (there is no clean durable turn-1 value at this call site today: the
      // count lives in each store, so plumbing it up would change the
      // ConversationStore contract — hence the proxy).
      const derivedTitle =
        this.conversation.turns.length === 0
          ? deriveAutoTitle(
              this.responseSafety.sanitizeFreeformContent(userInput, {
                secretWarning: 'Potential secret detected in session title',
              }).content
            )
          : ''
      // Empty first input (or whitespace-only) → no title; let the client keep
      // its placeholder rather than persisting an empty string via COALESCE.
      const autoTitle = derivedTitle.length > 0 ? derivedTitle : undefined
      // D3 — awaited durability barrier: the user message must be durable
      // before the LLM loop runs (it is the replay anchor after a crash). A
      // rejected write rolls back the turn inside startTurn and lands in
      // run()'s catch as a clean task failure.
      await this.deps.conversationManager.startTurn(
        this.conversation,
        userInput,
        this.taskId,
        this.task.traceContext ?? null,
        autoTitle
      )
      this.turnTiming?.addSessionLoadMs(Date.now() - sessionLoadStart)

      // P2 token budgets (§5.2) — capture the per-task brake baseline NOW, before
      // this task consumes anything. The conversation's lifetime counters are
      // session-cumulative (persist across restarts), so the brake measures the
      // DELTA vs this snapshot — a long-lived session is never aborted just for
      // accumulated history. Gated on the P1 verdict carrying a per-task cap so
      // the no-cap path stays identical to before (no baseline, brake disabled).
      this.captureTaskTokenBaseline()

      await withAbort(() => this.prepareChannelWorkflowCallerContext(), this.abortController.signal)
      this.enqueueGovernedRunEvent('run_start', `task:${this.taskId}:start`)
      if (this.workflowAccessDeniedResponse && looksLikeWorkflowAccessRequest(userInput)) {
        this.logProviderWorkflowAccessDenied('request')
        await this.completeWithStaticResponse(this.workflowAccessDeniedResponse)
        return
      }

      // A durable turn and authorized caller context precede all file writes.
      // Only metadata receipts join the first provider request; no source bytes
      // or visual projection are requested by this generic preparation stage.
      const references = this.task.sourceMessage?.fileReferenceResolutions
      if (hasLargeAvailableGfsReferences(references)) {
        const preparationLoopConfig = await withAbort(
          () => this.buildLoopConfig({ skipContextManager: true }),
          this.abortController.signal
        )
        // Await the transfer itself; withAbort would release the task while a
        // signal-ignoring producer could still settle. The shared execution path
        // carries the signal and cleanup must finish before terminal settlement.
        this.preparedGfsFiles = await prepareGfsFiles(references!, {
          config: preparationLoopConfig,
          callerIdentity: this.task.sourceMessage?.sender,
          toolTimeoutMs: appConfig.nativeTool.toolTimeout,
          budget: this.executionBudget,
        })
        this.executionBudget.assertTime()
      }

      // 2. Run the tool-use loop
      this.currentTurnToolNames.clear()
      const result = await this.runAgentLoop()

      // 3. Handle result
      await this.handleLoopResult(result)

      if (
        (this.state as ExecutorState) !== 'waiting_approval' &&
        !this.abortController.signal.aborted
      ) {
        this.state = 'completed'
        logger.info({ taskId: this.taskId }, 'Task completed')
        this.turnTiming?.emit(this.taskId)
        this.deps.onComplete(this.task)
      } else if (this.abortController.signal.aborted) {
        logger.info({ taskId: this.taskId }, 'Task cancelled')
      }
    } catch (error) {
      if (
        this.abortController.signal.aborted &&
        !(this.abortController.signal.reason instanceof TaskLimitError)
      ) {
        if (this.conversation)
          await this.handleLoopResult({ type: 'cancelled', reason: 'signal_aborted' })
        return
      }
      if (this.abortController.signal.reason instanceof TaskLimitError)
        error = this.abortController.signal.reason
      if (error instanceof TaskLimitError && this.conversation) {
        this.executionBudget.pause()
        try {
          if (this.conversation.state === 'processing')
            await this.deps.conversationManager.completeTurn(this.conversation, error.message)
          else await this.deps.conversationManager.failTurn(this.conversation)
        } catch (persistError) {
          // A failed durable write must not prevent lifecycle failure or completion release.
          logger.error(
            { taskId: this.taskId, err: persistError },
            'Failed to persist task limit interruption'
          )
        }
      }
      const taskError = this.toTaskError(error)
      logger.error(
        { taskId: this.taskId, code: taskError.code, retryable: taskError.retryable, err: error },
        'Task failed'
      )
      this.state = 'failed'
      if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
        this.deps.onFail(this.task, taskError, [...this.completedAttachments])
      } else {
        this.deps.onFail(this.task, taskError)
      }
    } finally {
      await this.settleGfsRetentionOwner()
      this.executionBudget.pause()
      if (this.state !== 'waiting_approval' || this.abortController.signal.aborted)
        this.resolveCompletion?.()
    }
  }

  /**
   * Resume execution after approval was granted.
   */
  async resumeAfterApproval(alwaysApprove: boolean): Promise<void> {
    if (this.state !== 'waiting_approval' || !this.conversation) {
      throw new Error(`Cannot resume: executor state is ${this.state}`)
    }

    logger.info({ taskId: this.taskId }, 'Resuming after approval')

    try {
      this.state = 'processing'

      // Guard: abort may have been called between approval request and resume.
      // The subscriber that aborted us already transitioned the task to cancelled.
      // Just clean up our own execution state. (PR-186 review M2; Invariant I1)
      if (this.abortController.signal.aborted) {
        logger.info({ taskId: this.taskId }, 'Resume cancelled: already aborted')
        return
      }

      const savedApproval = this.conversation.pending_approval
      // Restore before legacy renewal or missing-context recovery can re-pause
      // this turn. Those branches must not stamp a fresh attachment budget.
      if (savedApproval) this.restoreAttachmentReadLedger(savedApproval)
      mergeCollectedAttachments(this.completedAttachments, savedApproval?.attachments ?? [])
      collectToolAttachments(savedApproval?.completed_results ?? [], this.completedAttachments)
      this.executionBudget.start(this.abortController)
      const approvalBeforeResolution = this.conversation.pending_approval
      if (this.legacyApprovalBudget && approvalBeforeResolution) {
        await this.handleLoopResult({
          type: 'need_approval',
          approval: {
            ...approvalBeforeResolution,
            request_id: randomUUID(),
            replaces_request_id: approvalBeforeResolution.request_id,
            legacy_budget: false,
            description:
              'Confirm continuation with a new execution budget; prior consumption was not recorded. ' +
              approvalBeforeResolution.description,
          },
        })
        this.legacyApprovalBudget = false
        return
      }
      await this.deps.conversationManager.approve(this.conversation, alwaysApprove)
      if (approvalBeforeResolution?.tool_call_id) {
        this.approvedToolCorrelation = {
          toolCallId: approvalBeforeResolution.tool_call_id,
          approvalRequestId: approvalBeforeResolution.request_id,
        }
      }
      this.currentTurnToolNames.clear()

      const approval = this.conversation.pending_approval

      // Fallback: no snapshot, re-run from scratch
      if (!approval?.context_snapshot?.length) {
        // There is no frozen call to execute. A regenerated call must not
        // consume the old approval through a name-only approval/guardrail gate.
        this.executionBudget.assertTime()
        this.conversation.pending_approval = undefined
        logger.info({ taskId: this.taskId }, 'No snapshot, re-running from scratch')
        const result = await this.runAgentLoop()
        await this.handleLoopResult(result)
        if (
          (this.state as ExecutorState) !== 'waiting_approval' &&
          !this.abortController.signal.aborted
        ) {
          this.state = 'completed'
          this.deps.onComplete(this.task)
        } else if (this.abortController.signal.aborted) {
          logger.info({ taskId: this.taskId }, 'Task cancelled')
        }
        return
      }

      // IronClaw invariant #2 (P.3 §4.3): resolve any spillover refs in the
      // snapshot BEFORE we execute the approved tool. If a ref is dead (TTL
      // expired or GC'd) we abort early — the audit invariant is that what
      // executes equals what the user approved. Re-running prior tools to
      // regenerate the blob could yield different output (web page changed,
      // file modified) → audit broken.
      const resolveCtx = {
        taskId: this.taskId,
        requestId: approval.request_id,
        toolName: approval.tool_name,
      }
      const resolveOnce = async (
        m: Pick<ToolResult, 'content' | 'spillover_ref'>
      ): Promise<string> => {
        // FsSpilloverResolver attaches `resolveCtx` to any ApprovalExpiredError
        // it throws. Other resolver implementations (e.g. test mocks) are
        // expected to throw their own ApprovalExpiredError directly.
        const resolver = this.spilloverResolver
        if (resolver instanceof FsSpilloverResolver) {
          return resolver.withContext(resolveCtx, () => resolver.resolve(m))
        }
        return resolver.resolve(m)
      }
      const resolvedCompletedResults: ToolResult[] = []
      try {
        for (const tr of approval.completed_results ?? []) {
          const resolvedContent = await resolveOnce({
            content: tr.content,
            spillover_ref: tr.spillover_ref,
          })
          resolvedCompletedResults.push({ ...tr, content: resolvedContent })
        }
      } catch (error) {
        if (error instanceof ApprovalExpiredError) {
          logger.warn({ taskId: this.taskId }, 'Approval expired before tool execution')
          await this.deps.conversationManager.failTurn(this.conversation!)
          this.state = 'failed'
          this.deps.onFail(this.task, {
            code: 'approval_expired',
            message: error.payload.user_message,
            retryable: false,
            provider: this.deps.llmProvider.getProviderType(),
          })
          return
        }
        throw error
      }

      // Execute approved tool outside loop.
      // IronClaw invariant #1: the snapshot's frozen messages must reach the
      // LLM verbatim — compaction would invalidate validateToolLinkages.
      const loopConfig = await withAbort(
        () => this.buildLoopConfig({ skipContextManager: true }),
        this.abortController.signal
      )
      const suspendedCall = {
        id: approval.tool_call_id,
        name: approval.tool_name,
        arguments: approval.parameters,
      }
      const displayName = getDisplayName(suspendedCall.name)
      logger.info({ taskId: this.taskId, toolName: suspendedCall.name }, 'Executing approved tool')
      this.currentTurnToolNames.add(suspendedCall.name)

      // executeToolCalls emits reportToolStart AFTER the approval gate, so approved
      // tools bypass it entirely. Emit the SSE bookends here so the UI sees the
      // full tool_start → tool_progress × N → tool_complete sequence (matching the
      // normal non-approval path). Without this, the UI has no step card to update
      // on tool_progress and is stuck visually on the approval dialog.
      const reporter = progressReporterRegistry.get(this.taskId)
      if (reporter) {
        reporter.reportToolStart({
          taskId: '', // overridden by SseProgressReporter
          toolCallId: suspendedCall.id,
          toolName: suspendedCall.name,
          displayName,
          intentSummary: approval.intent_summary ?? `Using ${displayName}...`,
          iteration: 0,
          stepIndex: 0,
          totalSteps: 1,
          inputPreview: extractInputPreview(suspendedCall.name, suspendedCall.arguments),
        })
      }

      const execStart = Date.now()
      this.executionBudget.assertTime()
      // approve() already resolved the durable approval. Consume its retained
      // RAM copy before execution so the next model-generated call cannot reuse
      // it through either approval gate. The local frozen approval still owns
      // message reconstruction and any connect_required re-suspension below.
      this.conversation.pending_approval = undefined
      const toolResult = await executeSingleTool(suspendedCall, loopConfig)
      collectToolAttachments([toolResult], this.completedAttachments)
      this.executionBudget.assertTime()

      if (reporter) {
        reporter.reportToolComplete({
          taskId: '',
          toolCallId: toolResult.tool_call_id,
          toolName: toolResult.name,
          displayName,
          durationMs: Date.now() - execStart,
          isError: toolResult.is_error ?? false,
          errorSummary: toolResult.is_error ? sanitizeError(toolResult.content) : undefined,
          iteration: 0,
          stepIndex: 0,
          totalSteps: 1,
          outputPreview: buildOutputPreview(toolResult.rawContent ?? toolResult.content),
          metadata: toolResult.metadata,
        })
      }

      // U5 — the re-executed tool surfaced a 401 on an oauth mcp-server. Suspend
      // durably for reactive OAuth consent INSTEAD of feeding the auth error to
      // the LLM. The connect suspension inherits the SAME tool coordinates
      // (via `suspendedCall`) + the frozen `context_snapshot`/`completed_results`
      // so the NEXT resume (after the user connects) re-executes the SAME tool.
      // The failed connect `toolResult` is intentionally dropped — it never
      // enters the reconstructed message history. No machine loop: each resume is
      // human-gated (approve/connect), and the client already exhausted its
      // single 401 refresh-retry before throwing (McpAuthError).
      const connectMarker = extractConnectRequiredMarker(toolResult.metadata)
      if (connectMarker) {
        const connectApproval = buildConnectRequiredApproval(suspendedCall, connectMarker)
        connectApproval.context_snapshot = approval.context_snapshot
        connectApproval.completed_results = approval.completed_results
        connectApproval.intent_summary = approval.intent_summary
        connectApproval.attachments = approval.attachments
        connectApproval.traceContext = approval.traceContext ?? this.task.traceContext ?? null
        await this.handleLoopResult({ type: 'need_approval', approval: connectApproval })
        if (
          (this.state as ExecutorState) !== 'waiting_approval' &&
          !this.abortController.signal.aborted
        ) {
          this.state = 'completed'
          this.turnTiming?.emit(this.taskId)
          this.deps.onComplete(this.task)
        } else if (this.abortController.signal.aborted) {
          logger.info({ taskId: this.taskId }, 'Task cancelled')
        }
        return
      }

      // Reconstruct messages using the resolved completed_results.
      // `resolvedCompletedResults` is `approval.completed_results` with any
      // spillover refs swapped in for their blob bodies (invariant #2).
      const messages: ChatMessage[] = [
        ...approval.context_snapshot,
        ...resolvedCompletedResults.map((tr: ToolResult) => ({
          role: 'tool' as const,
          content: tr.content,
          tool_call_id: tr.tool_call_id,
          name: tr.name,
        })),
        {
          role: 'tool' as const,
          content: toolResult.content,
          tool_call_id: toolResult.tool_call_id,
          name: toolResult.name,
        },
      ]

      validateToolLinkages(messages)

      const previousAttachments = [
        ...(approval.attachments || []),
        ...this.collectAttachments([...(approval.completed_results || []), toolResult]),
      ]
      // A15 U1 — the approved tool ended the turn: no further model call.
      const result: LoopResult = toolResult.stopTurn
        ? turnStopResult(loopConfig, 0, toolResult.stopTurn.message, [])
        : await runToolUseLoop(loopConfig, messages)

      // Preserve attachments
      if (previousAttachments.length > 0) {
        if (result.type === 'response' || result.type === 'exhaustion') {
          result.attachments = [...previousAttachments, ...(result.attachments || [])]
        } else if (result.type === 'need_approval') {
          result.approval.attachments = [
            ...(result.approval.attachments || []),
            ...previousAttachments,
          ]
          result.approval.completed_results = [
            ...(approval.completed_results || []),
            toolResult,
            ...(result.approval.completed_results || []),
          ]
        }
      }

      await this.handleLoopResult(result)
      if (
        (this.state as ExecutorState) !== 'waiting_approval' &&
        !this.abortController.signal.aborted
      ) {
        this.state = 'completed'
        this.turnTiming?.emit(this.taskId)
        this.deps.onComplete(this.task)
      } else if (this.abortController.signal.aborted) {
        logger.info({ taskId: this.taskId }, 'Task cancelled')
      }
    } catch (error) {
      if (
        this.legacyApprovalBudget &&
        !this.abortController.signal.aborted &&
        !(error instanceof TaskLimitError) &&
        this.conversation?.pending_approval?.legacy_budget === true
      ) {
        this.state = 'waiting_approval'
        const pending = this.conversation.pending_approval
        this.deps.onApprovalNeeded(pending.request_id, this.taskId, pending)
        logger.error(
          { taskId: this.taskId, err: error },
          'Approval renewal failed; existing approval retained'
        )
        return
      }
      if (
        this.abortController.signal.aborted &&
        !(this.abortController.signal.reason instanceof TaskLimitError)
      ) {
        if (this.conversation)
          await this.handleLoopResult({ type: 'cancelled', reason: 'signal_aborted' })
        return
      }
      if (this.abortController.signal.reason instanceof TaskLimitError)
        error = this.abortController.signal.reason
      if (error instanceof TaskLimitError && this.conversation) {
        this.executionBudget.pause()
        try {
          if (this.conversation.state === 'processing')
            await this.deps.conversationManager.completeTurn(this.conversation, error.message)
          else await this.deps.conversationManager.failTurn(this.conversation)
        } catch (persistError) {
          // A failed durable write must not prevent lifecycle failure or completion release.
          logger.error(
            { taskId: this.taskId, err: persistError },
            'Failed to persist task limit interruption'
          )
        }
      }
      const taskError = this.toTaskError(error)
      logger.error(
        { taskId: this.taskId, code: taskError.code, retryable: taskError.retryable, err: error },
        'Resume failed'
      )
      this.state = 'failed'
      if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
        this.deps.onFail(this.task, taskError, [...this.completedAttachments])
      } else {
        this.deps.onFail(this.task, taskError)
      }
    } finally {
      await this.settleGfsRetentionOwner()
      this.executionBudget.pause()
      if (this.state !== 'waiting_approval' || this.abortController.signal.aborted)
        this.resolveCompletion?.()
    }
  }

  /**
   * Convert an unknown thrown error into a structured TaskError.
   * LlmError → pass through its code/message/retryable/provider.
   * Anything else → retryable ApiCallFailed with provider from the LLM.
   */
  private toTaskError(error: unknown): TaskError {
    if (error instanceof TaskLimitError)
      return {
        code: error.code,
        message: error.message,
        retryable: false,
        provider: this.deps.llmProvider.getProviderType(),
      }
    if (error instanceof LlmError) {
      return {
        code: error.code,
        message: error.message,
        retryable: error.retryable,
        provider: error.provider,
        httpStatus: error.httpStatus,
        providerCode: error.providerCode,
      }
    }
    return {
      code: LlmErrorCode.ApiCallFailed,
      message: error instanceof Error ? error.message : String(error),
      retryable: true,
      provider: this.deps.llmProvider.getProviderType(),
    }
  }

  /**
   * Deny the pending approval.
   *
   * **IronClaw write-through (T2.1)**: `ConversationManager.deny` awaits the
   * durable pending_approval delete before returning, so we await here too —
   * the channel notification (responseCallback) only fires after the DB
   * mutation lands. Callers that fire-and-forget should attach `.catch(...)`.
   */
  async deny(): Promise<void> {
    if (this.state !== 'waiting_approval' || !this.conversation) return

    const toolName = this.conversation.pending_approval?.tool_name || 'unknown'
    await this.deps.conversationManager.deny(this.conversation)

    // Terminal SSE event emitted automatically when onComplete → queue.completeTask
    // → lifecycle.transition('completed') fires (SseProgressReporter subscription).

    const denialMessage = `Tool \`${toolName}\` was denied by the user. The operation was not performed.`
    if (this.task.responseCallback) {
      this.task.responseCallback({ response: denialMessage }).catch(err => {
        logger.error({ taskId: this.taskId, err }, 'Failed to send denial')
      })
    }

    this.state = 'completed'
    await this.settleGfsRetentionOwner()
    this.deps.onComplete(this.task)
    this.resolveCompletion?.()
  }

  /**
   * Signal an abort. The loop exits at its next checkpoint.
   *
   * Idempotent self-healing: drives the TaskLifecycle transition to 'cancelled'
   * before firing the AbortController. In the normal v2 flow the AgentStateMachine
   * lifecycle subscriber already transitioned the task before calling abort(), so
   * this transition() call returns AlreadyTerminal — a zero-cost no-op. For any
   * future direct caller that bypasses the subscriber (shutdown paths, test helpers,
   * new approval-denial flows), the task self-heals to 'cancelled' instead of being
   * stranded at 'processing'.
   *
   * Critically this does NOT write task.status directly — only TaskLifecycle writes
   * task state (Invariant I1 preserved). PR-193 review #1.
   */
  abort(): void {
    const suspended = this.state === 'waiting_approval'
    this.deps.taskLifecycle.transition(this.task.id, 'cancelled', 'user_requested')
    this.abortController.abort()
    if (suspended) {
      // A suspended run has already returned, so its finally block will not
      // re-enter. Its producers have settled; join owner release explicitly.
      void this.settleGfsRetentionOwner().then(() => this.resolveCompletion?.())
    }
  }

  // ── Private helpers ───────────────────────────────────────────────

  /**
   * P2 token budgets (§5.2) — snapshot the conversation's lifetime token
   * counters as the per-task brake baseline. No-op (leaves `taskTokenBaseline`
   * null → brake disabled) unless the P1 verdict carried a per-task cap.
   */
  private captureTaskTokenBaseline(): void {
    if (!this.hasTaskBudgetCap() || !this.conversation) return
    this.taskTokenBaseline = snapshotTaskTokenBaseline(this.conversation)
  }

  /**
   * A retention owner spans preparation and an approval suspension in this
   * process; pins live in memory, so after a Host restart a cold resume finds
   * no pin and its file may have expired or been evicted, and the model
   * downloads it again. Release happens only after this executor reaches a
   * terminal state. A failed release leaves the pin in place, so its files stay
   * protected until the Host restarts or until each copy reaches its
   * `expiresAt`, whichever comes first: expiry is absolute and a pin never
   * protects an expired copy.
   */
  private settleGfsRetentionOwner(): Promise<void> {
    if (this.state === 'waiting_approval' && !this.abortController.signal.aborted)
      return Promise.resolve()
    if (this.gfsRetentionOwnerSettlement) return this.gfsRetentionOwnerSettlement
    this.gfsRetentionOwnerSettlement = (async () => {
      const callerIdentity = gfsStoreCallerIdentity(this.task.sourceMessage)
      const store = this.deps.gfsDownloadStore
      if (!store?.isAvailable()) return
      try {
        await store.releaseReceiptOwner(this.taskId, callerIdentity)
      } catch (error) {
        logger.error(
          { taskId: this.taskId, callerIdentity, err: error },
          'GFS retention owner release failed; retained records remain protected until restart or expiry'
        )
      }
    })()
    return this.gfsRetentionOwnerSettlement
  }

  /** True when the P1 budget verdict carried a per-task cap (tokens or cost). */
  private hasTaskBudgetCap(): boolean {
    const v = this.task.budgetVerdict
    return !!v && (v.maxTaskTokens != null || v.maxTaskCost != null)
  }

  /**
   * R2.6 — model-aware context window. The allowlist entry for the effective
   * model wins. Without one, a subscription provider uses its 256k default and
   * every other provider the fixed `CLERUM_CONTEXT_MAX_TOKENS` env (#731).
   * Subscription tasks log the window and its source once.
   */
  private contextMaxTokens(): number {
    if (this.contextWindow !== null) return this.contextWindow
    const provider = this.deps.llmProvider.getProviderType()
    const { contextWindowTokens, source } = resolveContextWindow(
      provider,
      this.deps.contextWindowTokens,
      appConfig.contextMaxTokens
    )
    if (isLlmProvider(provider) && descriptorFor(provider).defaultContextWindowTokens) {
      logger.info(
        {
          event: 'context_window_resolved',
          component: 'TaskExecutor',
          taskId: this.taskId,
          provider,
          model: this.deps.modelName,
          // Not `contextWindowTokens`: SENSITIVE_KEY_RE in logger.ts redacts it;
          // logPayloadKeys.test.ts rejects such keys.
          contextWindow: contextWindowTokens,
          source,
        },
        'Context window resolved for the task'
      )
    }
    this.contextWindow = contextWindowTokens
    return contextWindowTokens
  }

  /**
   * C15/C16 — restore the turn ledger from the approval's own snapshot. The
   * persisted value is authoritative and independent of message history, so
   * compaction and earlier turns cannot change it. A missing or invalid
   * snapshot fails closed: compacted history cannot prove that nothing was
   * spent. New approvals always carry even the valid zero snapshot.
   */
  private restoreAttachmentReadLedger(approval: PendingApproval): void {
    const persisted = readAttachmentReadLedgerSnapshot(approval.task_budget?.attachmentReadLedger)
    if (persisted) {
      // Warm resume must never decrease what the live turn already recorded.
      this.attachmentReadLedger.restore(
        mergeAttachmentReadLedgerSnapshots(this.attachmentReadLedger.snapshot(), persisted)
      )
      return
    }
    logger.warn(
      { component: 'TaskExecutor', taskId: this.taskId, reason: 'attachment_read_ledger_missing' },
      'Approval has no usable attachment ledger; failing closed for the rest of the turn'
    )
    this.attachmentReadLedger.exhaust(this.contextMaxTokens())
  }

  /**
   * #731 — the attempt contract's `maxMessages` for the provider, or
   * `undefined` when it has none. An unregistered provider type has no
   * contract, the same case `buildSourceMessageContentParts` guards with
   * `isLlmProvider`.
   */
  private contractMaxMessages(): number | undefined {
    const providerType = this.deps.llmProvider.getProviderType()
    if (!isLlmProvider(providerType)) return undefined
    return descriptorFor(providerType).maxMessages
  }

  private getOrCreateTokenCounter(): TokenCounter {
    if (!this.tokenCounter) {
      this.tokenCounter = createTokenCounter(this.deps.llmProvider, this.deps.modelName, {
        offline: appConfig.tokenizerOffline,
      })
      // Fire warmup asynchronously. `count()` awaits internally if it races.
      void this.tokenCounter.warmup().catch(err => {
        logger.warn({ taskId: this.taskId, err }, 'Token counter warmup failed')
      })
    }
    return this.tokenCounter
  }

  private async runAgentLoop(): Promise<LoopResult> {
    const historyStart = Date.now()
    let messages = this.deps.conversationManager.buildMessageHistory(this.conversation!)
    // #731: the history is compacted at the same share of the model's window
    // at which the context manager starts compacting, not at a fixed count,
    // and measured the way the manager measures it for that decision (#739).
    const compactionThreshold = Math.floor(COMPACTION_PRESSURE_THRESHOLD * this.contextMaxTokens())
    const tokenCounter = this.getOrCreateTokenCounter()
    messages = await compactConversation(
      messages,
      undefined,
      compactionThreshold,
      msgs => tierDecisionTokens(msgs, [], tokenCounter, appConfig.tokenizerDryrun),
      {
        enabled: appConfig.compactionPrePruneEnabled,
        options: {
          protectedTailTurns: appConfig.compactionPrePruneProtectedTailTurns,
          summaryThresholdTokens: appConfig.compactionPrePruneSummaryTokens,
          maxArgsBytes: appConfig.compactionPrePruneMaxArgsBytes,
          dedupEnabled: appConfig.compactionPrePruneDedup,
          oneLineSummariesEnabled: appConfig.compactionPrePruneOneLine,
          jsonSafeTruncateEnabled: appConfig.compactionPrePruneJsonTruncate,
          stripMediaEnabled: appConfig.compactionPrePruneStripMedia,
        },
      }
    )
    // History rehydration + pre-prune compaction are part of the session-load
    // cost the user pays before the first model byte.
    this.turnTiming?.addSessionLoadMs(Date.now() - historyStart)
    const lastMessage = messages[messages.length - 1]
    const sourceMessageAttachments = this.buildSourceMessageContentParts(
      lastMessage?.role === 'user' ? lastMessage.content : ''
    )
    if (sourceMessageAttachments.length > 0) {
      if (lastMessage?.role === 'user') {
        messages[messages.length - 1] = {
          ...lastMessage,
          // Parts are authoritative: `content` is restated from the text parts
          // so a message with images cannot contradict its own projection.
          content: textContentFromParts(sourceMessageAttachments),
          contentParts: sourceMessageAttachments,
        }
      }
    }
    // T2.2 — when the prompt cache is on, the volatile per-turn metadata
    // (date, channel, sender, cron) moves out of the (now byte-stable) system
    // prompt and into a `<turn-context>` block prepended to the LAST user
    // message of the turn. Only the first user message of the turn gets it;
    // `tool` messages keep their content untouched.
    // #666 — the block is also the only carrier of the `attached_file` and
    // `referenced_file` lines, so a message with file attachments or resolved
    // file references gets it with the cache off too; the attachment
    // condition also registers `clerum__attachment_read`.
    const hasFileAttachments =
      this.task.sourceMessage?.attachments?.some(attachment => attachment.kind === 'file') === true
    const hasFileReferences = (this.task.sourceMessage?.fileReferenceResolutions?.length ?? 0) > 0
    if (appConfig.promptCacheEnabled || hasFileAttachments || hasFileReferences) {
      this.prependTurnContextBlock(messages)
    }
    const promptAssemblyStart = Date.now()
    const loopConfig = await withAbort(() => this.buildLoopConfig(), this.abortController.signal)
    if (this.turnTiming) {
      // buildLoopConfig assembles the tool registry (MCP schemas) and the
      // system identity (workspace files / tiered prompt parts).
      this.turnTiming.addPromptAssemblyMs(Date.now() - promptAssemblyStart)
      let inputChars = 0
      for (const m of messages) {
        if (typeof m.content === 'string') inputChars += m.content.length
      }
      this.turnTiming.setInputCharsApprox(inputChars)
    }
    return runToolUseLoop(loopConfig, messages)
  }

  /**
   * T2.2 — prepend the `<turn-context>` block to the latest user message
   * (mutates in place). The block carries date/channel/sender/cron; an empty
   * cron source still produces a valid block. For cron-originated turns with
   * no human user text we inject a synthetic `<cron task>` placeholder so the
   * wire shape stays consistent (P1-004 §5.5).
   */
  private prependTurnContextBlock(messages: ChatMessage[]): void {
    for (let i = messages.length - 1; i >= 0; i--) {
      const m = messages[i]
      if (m.role !== 'user') continue
      const block = buildTurnContextBlock({
        date: new Date(),
        channel: {
          type: this.task.sourceMessage?.channelType ?? 'internal',
          sender: this.task.sourceMessage?.sender ?? null,
        },
        cron: this.task.cronJobId
          ? {
              jobId: this.task.cronJobId,
              scheduledFor: new Date().toISOString(),
            }
          : undefined,
        attachedFiles: attachedFilesForTurnContext(this.task.sourceMessage?.attachments),
        referencedFiles: referencedFilesForTurnContext(
          this.task.sourceMessage?.fileReferenceResolutions
        ),
        preparedGfsFiles: this.preparedGfsFiles,
      })
      const isCron = this.task.cronJobId !== undefined
      if (m.contentParts && m.contentParts.length > 0) {
        // Keep the parts/`content` invariant the Codex V2 parser enforces: the
        // block moves with the text it is prepended to.
        const contentParts = prependTextToParts(m.contentParts, block)
        messages[i] = { ...m, contentParts, content: textContentFromParts(contentParts) }
        return
      }
      const baseContent =
        m.content && m.content.length > 0 ? m.content : isCron ? '<cron task>' : m.content
      messages[i] = { ...m, content: block + baseContent }
      return
    }
  }

  private async handleLoopResult(result: LoopResult): Promise<void> {
    if (result.type === 'need_approval') {
      mergeCollectedAttachments(this.completedAttachments, result.approval.attachments ?? [])
      collectToolAttachments(result.approval.completed_results ?? [], this.completedAttachments)
    } else if ('attachments' in result) {
      mergeCollectedAttachments(this.completedAttachments, result.attachments ?? [])
    }
    if (this.abortController.signal.reason instanceof TaskLimitError)
      throw this.abortController.signal.reason
    if (result.type !== 'cancelled') this.executionBudget.assertTime()
    // T1.4 — clear anti-thrash bookkeeping at any terminal outcome. `need_approval`
    // is NOT terminal (it suspends), so the state must survive into resume.
    if (this.conversation && result.type !== 'need_approval' && this.conversation.compactionState) {
      this.conversation.compactionState = undefined
    }
    switch (result.type) {
      case 'response':
      case 'exhaustion': {
        if (
          result.type === 'exhaustion' &&
          result.reason !== 'task_budget' &&
          result.reason !== 'turn_stop'
        )
          throw new TaskLimitError(
            'TASK_ITERATION_LIMIT',
            `Task stopped before completion after ${this.executionBudget.maxIterations} iterations. Continuation requires a new budget.`
          )
        const rawContent = result.type === 'response' ? result.content : result.message
        const guardedContent = await withAbort(
          () => this.guardProviderWorkflowTriggerClaim(rawContent),
          this.abortController.signal
        )
        this.executionBudget.assertTime()
        const sanitized = this.responseSafety.sanitizeAssistantResponse(guardedContent)
        const content = sanitized.content
        if (sanitized.was_modified) {
          this.deps.coreEvents.emit({
            type: 'safety:output_sanitized',
            data: {
              toolName: 'assistant_response',
              originalLength: guardedContent.length,
              sanitizedLength: content.length,
              taskId: this.taskId,
            },
            timestamp: new Date(),
          })
        }
        // D3 — awaited durability barrier: the turn must be durable BEFORE the
        // client ACK (responseCallback). On a rejected write, follow the
        // need_approval pattern below: fail the turn and rethrow so run()'s
        // catch surfaces a clean failure — the client never gets an ACK for a
        // turn that was not persisted.
        this.executionBudget.assertTime()
        this.executionBudget.pause()
        try {
          await this.deps.conversationManager.completeTurn(this.conversation!, content)
        } catch (err) {
          await this.deps.conversationManager.failTurn(this.conversation!)
          throw err
        }
        if (this.task.responseCallback) {
          await this.task.responseCallback({
            response: content,
            attachments: result.attachments,
          })
        }
        // Terminal SSE event emitted automatically when onComplete → queue.completeTask
        // → lifecycle.transition('completed') fires (SseProgressReporter subscription).
        break
      }

      case 'need_approval': {
        // C15/C16 — every pause (first, legacy re-pause, connect re-pause)
        // funnels through here, so the turn's attachment read ledger is stamped
        // inside the existing `task_budget` JSON column. Compaction cannot
        // lose it; no new column or migration is needed.
        const attachmentReadLedger = this.attachmentReadLedger.snapshot()
        result.approval.task_budget = {
          ...this.executionBudget.pause(),
          attachmentReadLedger,
        }
        // #666 R4-M2 — persist the sanitized source message so a cold restart
        // rebuilds the file-reference pins and attachment metadata. The inline
        // bytes (dataBase64) never persist.
        result.approval.sourceMessage = sourceMessageForResume(this.task.sourceMessage)
        // Durable write FIRST: under sqlite/dual the suspend can reject. We
        // must not tell the client "suspended" (SSE) or register the approval
        // before the durable state lands — otherwise a rejected write leaves a
        // contradictory SSE + an un-resolvable, poisoned conversation. On
        // failure, reset the turn (→ Idle) and rethrow so run()'s catch
        // surfaces it as a clean failure (CRIT-1 / sqlite-stores-10).
        try {
          await this.deps.conversationManager.suspendForApproval(
            this.conversation!,
            result.approval
          )
        } catch (err) {
          if (!result.approval.replaces_request_id)
            await this.deps.conversationManager.failTurn(this.conversation!)
          throw err
        }
        if (result.approval.replaces_request_id) this.legacyApprovalBudget = false
        const reporter = progressReporterRegistry.get(this.taskId)
        if (reporter) {
          // U5 — carry the reason (+ mcpServerName for connect_required)
          // so the desktop distinguishes an OAuth-consent suspension from the
          // default HITL gate. Absent reason → 'approval_required' (back-compat).
          reporter.emitSuspended(
            getDisplayName(result.approval.tool_name),
            result.approval.request_id,
            {
              reason: result.approval.reason ?? 'approval_required',
              mcpServerName: result.approval.mcpServerName,
              toolName: result.approval.tool_name,
              parameters: result.approval.parameters,
            }
          )
        }
        this.state = 'waiting_approval'
        this.deps.onApprovalNeeded(result.approval.request_id, this.taskId, result.approval)
        break
      }

      case 'cancelled': {
        // Release the conversation turn lock AND scrub the cancelled user_input from
        // LLM history so it does not leak into the next turn (BUG-9).
        // cancelTurn sets a synthetic assistant response on the current turn so that
        // buildMessageHistory emits a clean user↔assistant alternation.
        this.deps.conversationManager.cancelTurn(this.conversation!)
        // NOTE: We do NOT write task.status or task.completedAt here — TaskLifecycle is the
        // single writer (Invariant I1). The cancel subscriber in AgentStateMachine already
        // transitioned the task to cancelled before the loop checkpoint fired executor.abort().
        // Calling lifecycle.transition again would return AlreadyTerminal — redundant and
        // misleading.
        logger.info({ taskId: this.taskId }, 'Task cancelled')
        this.enqueueGovernedRunEvent('run_end', `task:${this.taskId}:end`, {
          status: 'cancelled',
        })
        break
      }

      case 'error': {
        await this.deps.conversationManager.failTurn(this.conversation!)
        throw result.error
      }

      default: {
        const _exhaustive: never = result
        void _exhaustive
      }
    }
  }

  private async completeWithStaticResponse(rawContent: string): Promise<void> {
    this.abortController.signal.throwIfAborted()
    this.executionBudget.assertTime()
    this.ensureProgressReporter()
    const sanitized = this.responseSafety.sanitizeAssistantResponse(rawContent)
    const content = sanitized.content
    if (sanitized.was_modified) {
      this.deps.coreEvents.emit({
        type: 'safety:output_sanitized',
        data: {
          toolName: 'assistant_response',
          originalLength: rawContent.length,
          sanitizedLength: content.length,
          taskId: this.taskId,
        },
        timestamp: new Date(),
      })
    }
    // D3 — same barrier-before-ACK contract as handleLoopResult 'response'.
    this.executionBudget.assertTime()
    this.executionBudget.pause()
    try {
      await this.deps.conversationManager.completeTurn(this.conversation!, content)
    } catch (err) {
      await this.deps.conversationManager.failTurn(this.conversation!)
      throw err
    }
    this.task.result = {
      response: content,
      model: this.deps.modelName,
      toolsUsed: [],
    }
    if (this.task.responseCallback) {
      await this.task.responseCallback({ response: content })
    }
    this.state = 'completed'
    logger.info({ taskId: this.taskId }, 'Completed with static response')
    this.deps.onComplete(this.task)
  }

  private ensureProgressReporter(): SseProgressReporter {
    // Idempotent get-or-create via the shared registry helper (same construction
    // site now reused by AgentStateMachine.handleTaskFailure for pre-executor
    // failures). Static fail-closed responses bypass the tool loop, but channel
    // readers still rely on the task lifecycle terminal event to update the user.
    return ensureReporter(
      this.taskId,
      this.deps.taskLifecycle,
      new BasicSafety(this.deps.secretEntriesProvider)
    )
  }

  /**
   * R5 — wrap the primary `LlmPort` with provider-failover when a policy is
   * wired for this task. Fallback entries are served by their OWN adapters,
   * built with the SAME per-task usage sink as the primary (so session token
   * accounting + `usage_events` stay correct) and a per-pair token counter.
   * Returns the primary unchanged when no policy / no fallbacks (byte-identical).
   */
  private wrapFailoverPort(primaryPort: LlmPortAdapter, conversation: Conversation): LlmPort {
    const support = this.deps.failover
    if (!support || support.policy.fallbacks.length === 0) return primaryPort
    const primaryProvider = this.deps.llmProvider.getProviderType()
    const primaryModel = this.deps.modelName
    return maybeWrapFailover({
      primaryPort,
      primaryPair: { provider: primaryProvider, model: primaryModel },
      engine: support.engine,
      policy: support.policy,
      buildFallbackPort: index => {
        const entry = support.policy.fallbacks[index]
        // R5.7 — a SAME-provider fallback (other key) respects the session's
        // model; a CROSS-provider fallback serves its fixed entry model
        // (ignoring the session selection). #654: resolve the effective model
        // BEFORE building so the provider's SDK, the token counter, the usage
        // event and the image guard all name the model that is really sent.
        const servedModel = entry.provider === primaryProvider ? primaryModel : entry.model
        const provider = support.buildProvider({ ...entry, model: servedModel })
        if (!provider) return null
        const counter = createTokenCounter(provider, servedModel, {
          offline: appConfig.tokenizerOffline,
        })
        return new LlmPortAdapter(
          provider,
          servedModel,
          provider.getProviderType(),
          this.deps.usageReporter,
          this.deps.usageStaticContext,
          this.buildDefaultUsageContext(),
          counter,
          usage => {
            this.deps.conversationManager.recordSessionUsage(conversation, usage)
            if (conversation.contextBreakdown && usage.input_tokens > 0) {
              conversation.contextBreakdown.totalInputTokens = usage.input_tokens
            }
          },
          this.deps.imageInput
        )
      },
    })
  }

  private async buildLoopConfig(opts?: {
    /**
     * IronClaw invariant #1 (P.3): when `true`, the loop will skip
     * `contextManager.manage()` for the entire run. Set by
     * `resumeAfterApproval` so the snapshot reaches the LLM verbatim.
     *
     * When omitted, derived from `this.conversation.pending_approval`. The
     * fall-through default exists so that callers (e.g. `runAgentLoop` on
     * the initial turn) don't need to know about IronClaw — the conversation
     * shape decides.
     */
    skipContextManager?: boolean
  }): Promise<LoopConfig> {
    const progressReporter = this.ensureProgressReporter()

    const tokenCounter = this.getOrCreateTokenCounter()

    // Capture the conversation in a local const (not `this.conversation!` inside
    // the closure) so a later reassignment of `this.conversation` can't re-point
    // the usage sink at a different session.
    const conversation = this.conversation!
    const llmPort = new LlmPortAdapter(
      this.deps.llmProvider,
      this.deps.modelName,
      this.deps.llmProvider.getProviderType(),
      this.deps.usageReporter,
      this.deps.usageStaticContext,
      this.buildDefaultUsageContext(),
      tokenCounter,
      usage => {
        this.deps.conversationManager.recordSessionUsage(conversation, usage)
        // F1.3b — finalize the send-time breakdown's provisional total
        // (Σbuckets) with the provider's authoritative `input_tokens` from the
        // SAME call. Runs inside the usage sink so there is no lag/race (#8).
        if (conversation.contextBreakdown && usage.input_tokens > 0) {
          conversation.contextBreakdown.totalInputTokens = usage.input_tokens
        }
      },
      this.deps.imageInput
    )

    // R5 — wrap the primary port with provider-failover when a policy is wired.
    // Each fallback entry gets its OWN adapter (built with the SAME per-task
    // usage sink + a per-pair token counter) so `usage_events` records the pair
    // really served. No policy → returns `llmPort` unchanged (byte-identical).
    const effectiveLlmPort = this.wrapFailoverPort(llmPort, conversation)
    // LLM-lane guardrails (spec §7): wrap ABOVE failover so built-in request
    // shaping fires once per logical request, not per fallback attempt. Inert
    // (returns the port unchanged) when no built-ins are configured (§5).
    const hookedLlmPort = bindTaskSignal(
      maybeWrapHookedLlmPort(effectiveLlmPort, this.deps.guardrailsConfig),
      this.abortController.signal
    )

    const metadata: Record<string, unknown> = {}
    if (this.task.sourceMessage) {
      if (this.task.sourceMessage.channelType === 'rpc') {
        metadata.channelType = 'desktop'
      } else {
        metadata.channelType = this.task.sourceMessage.channelType
        metadata.sender = this.task.sourceMessage.sender
      }
    }

    const { registry, loopController, bridge, discoverableNatives } = await this.buildToolRegistry()
    const applicableToolCounters = registry
      .listDefinitions()
      .some(tool => tool.name === 'clerum__attachment_read')
      ? (effectiveLlmPort.getToolTokenCounters?.() ?? [tokenCounter])
      : [tokenCounter]
    const toolCounters = [...new Set(applicableToolCounters)]
    await Promise.all(
      toolCounters.filter(counter => counter !== tokenCounter).map(counter => counter.warmup())
    )

    // T2.2 — when the prompt-cache flag is ON and we have the dependencies
    // wired (PromptCache + WorkspaceService), build the tiered
    // `SystemPromptParts` once per session via the cache and ship them
    // out-of-band through `ReasoningPort`. Otherwise fall back to the legacy
    // single-string identity built by `buildSystemIdentity`.
    const reasoningFactory = new DefaultReasoningFactory(
      hookedLlmPort,
      new DefaultPromptBuilder({
        nativeToolPresentation: appConfig.nativeToolPresentation,
        discoverableNatives,
      }),
      metadata,
      // F1.4 — wire the send-time context-window-breakdown capture. The sink is
      // bound to the captured `conversation` local (not `this.conversation!`) so
      // a later reassignment can't re-point it at a different session.
      tokenCounter,
      raw => this.deps.conversationManager.recordContextBreakdown(conversation, raw),
      this.contextMaxTokens()
    )
    const parts = await this.maybeGetOrBuildParts(registry.listDefinitions())
    const identity = parts ? undefined : await this.buildSystemIdentity(llmPort)
    const reasoning = parts
      ? reasoningFactory.createWithParts(parts)
      : reasoningFactory.create(identity)
    // R9-14 / R21-1 — the text of the system prompt `reasoning` sends with a
    // request that presents `tools`, for the context manager to count. The
    // cache path sends the parts it built once, joined as `LlmPortAdapter`
    // joins them, whatever the loop presents; the legacy path runs the builder
    // `DefaultReasoningPort` runs, over the presented list. That builder stamps
    // `new Date().toISOString()`, so the counted copy carries a different
    // timestamp from the sent one; the ISO string is always 24 characters, so
    // the byte count, which is all the gauge reads, is the same.
    let systemPromptFor: (tools: ToolDefinition[]) => string
    if (parts) {
      const cachedPrompt = [parts.stable, parts.context].filter(s => s.length > 0).join('\n\n')
      systemPromptFor = () => cachedPrompt
    } else {
      const promptBuilder = new DefaultPromptBuilder({
        nativeToolPresentation: appConfig.nativeToolPresentation,
        discoverableNatives,
      })
      systemPromptFor = tools => promptBuilder.buildSystemPrompt(tools, identity, metadata).content
    }

    const contextManager = new PressureContextManager(
      this.contextMaxTokens(),
      this.deps.workspaceService,
      hookedLlmPort,
      tokenCounter,
      {
        dryRun: appConfig.tokenizerDryrun,
        ineffectiveRatio: appConfig.compactionIneffectiveRatio,
        ineffectiveMaxRun: appConfig.compactionIneffectiveMaxRun,
        events: this.deps.coreEvents,
        taskId: this.taskId,
        prePruneEnabled: appConfig.compactionPrePruneEnabled,
        prePruneOptions: {
          protectedTailTurns: appConfig.compactionPrePruneProtectedTailTurns,
          summaryThresholdTokens: appConfig.compactionPrePruneSummaryTokens,
          maxArgsBytes: appConfig.compactionPrePruneMaxArgsBytes,
          dedupEnabled: appConfig.compactionPrePruneDedup,
          oneLineSummariesEnabled: appConfig.compactionPrePruneOneLine,
          jsonSafeTruncateEnabled: appConfig.compactionPrePruneJsonTruncate,
          stripMediaEnabled: appConfig.compactionPrePruneStripMedia,
        },
        // T1.1 — structured summary template. Default OFF until the
        // bake-week confirms ≥80% `parseStatus:'ok'` on the configured model.
        structuredSummaryEnabled: appConfig.compactionStructuredSummary,
        // T2.2 — when a `summarize` tier runs we invalidate the prompt cache
        // (P0-005 §5.7): the daily-log snapshot is now stale (the summary just
        // got appended to it), and the next turn should re-snapshot.
        onCompactionEffective: this.deps.promptCache
          ? () => {
              const key = this.sessionKey
              if (key) this.deps.promptCache!.invalidate(key, 'compact')
            }
          : undefined,
        // #731 — the subscription contracts refuse a request on message count
        // alone; the registry carries that bound from each contract's LIMITS.
        maxMessages: this.contractMaxMessages(),
      }
    )

    const loopConfig = buildLoopConfig({
      reasoning,
      toolRegistry: registry,
      safety: new BasicSafety(this.deps.secretEntriesProvider),
      events: this.buildTrackingEventEmitter(),
      // P.5: conversation is always set by the time buildLoopConfig runs —
      // runAgentLoop / resumeAfterApproval both construct it after
      // `getOrCreate(sessionKey)`. The non-null assertion mirrors how the
      // surrounding code already accesses `this.conversation!`.
      conversation: this.conversation!,
      loopController,
      contextManager,
      progressReporter,
      maxIterations: this.executionBudget.remainingIterations,
      toolTimeout: appConfig.nativeTool.toolTimeout,
      toolProgressInterval: appConfig.nativeTool.toolProgressInterval,
    })
    loopConfig.abortSignal = this.abortController.signal
    loopConfig.visualInput = {
      budget: this.executionBudget.visualInputs,
      resolveCapability: signal =>
        effectiveLlmPort.getImageInputCapability?.(signal) ??
        Promise.resolve({ status: 'unknown' as const }),
    }
    loopConfig.systemPromptFor = systemPromptFor
    loopConfig.imageSourceIdentity = this.providerChainRequiresImageSourceIdentity()
    loopConfig.onAttachments = attachments =>
      mergeCollectedAttachments(this.completedAttachments, attachments)
    // Guardrails (spec §6) — build the tool-lane guardrail from the Host block.
    // Undefined when no rules are configured (no-config compatibility, §5); a
    // malformed set throws here (fail-closed admission, §3/§5).
    loopConfig.guardrails = buildToolLaneGuardrail(this.deps.guardrailsConfig)
    // §6.3: a run with no human to answer an approval must fail safe to deny.
    loopConfig.executionMode = executionModeForSource(this.task.source)
    loopConfig.skipContextManager =
      opts?.skipContextManager ?? this.conversation?.pending_approval !== undefined
    // T1.5 — pass the storage + taskId down so `executeSingleTool` can persist
    // oversized outputs and stamp `spillover_ref` on the result.
    loopConfig.spilloverStorage = this.deps.spilloverStorage
    loopConfig.taskId = this.taskId
    // C15/C16 — the exact synchronous measurement the bounded native readers
    // use for a result: the full tool message (framing + the larger applicable
    // provider/BPE estimate), never a content-only shortcut.
    // Page limits are enforced even when compaction is in tokenizer dry-run.
    // Use the largest applicable synchronous estimate for every destination;
    // emitted pages can survive a provider change in a later reasoning round.
    loopConfig.measureToolMessage = message =>
      Math.max(...toolCounters.map(counter => toolMessageBudgetTokens(message, counter, false)))
    // F3 (dynamic-tool-loading): context the `clerum__tool_call` bridge intercept
    // needs in `executeToolCalls`. Undefined when the registry registered no
    // bridge tools (no MCP discovery with an McpManager, and native `direct`).
    loopConfig.bridge = bridge
    // P2 token budgets (§5.2): wire the per-task emergency brake when the P1
    // verdict carried a per-task cap AND we captured a start-of-task baseline.
    // Same baseline is reused across resumeAfterApproval (set once in run()), so
    // the delta spans the whole task. Left undefined otherwise → loop no-op.
    const verdict = this.task.budgetVerdict
    if (this.taskTokenBaseline && this.hasTaskBudgetCap() && verdict) {
      loopConfig.taskBrake = {
        maxTaskTokens: verdict.maxTaskTokens ?? null,
        maxTaskCost: verdict.maxTaskCost ?? null,
        price: verdict.price ?? null,
        baseline: this.taskTokenBaseline,
      }
    }
    return loopConfig
  }

  private buildTrackingEventEmitter(): AgentEventEmitter {
    return {
      emit: (event: AgentEvent) => {
        if (event.type === 'loop:iteration') this.executionBudget.consumeIteration()
        if (event.type === 'tool:called') {
          const toolName = typeof event.data.toolName === 'string' ? event.data.toolName.trim() : ''
          if (toolName) this.currentTurnToolNames.add(toolName)
        }
        if (event.type === 'llm:completed') {
          const iteration = typeof event.data.iteration === 'number' ? event.data.iteration : 0
          // Each approval resume starts a fresh loop at iteration zero.
          const occurrence = `${event.timestamp.getTime()}-${iteration}`
          this.enqueueGovernedRunEvent(
            'llm_call',
            `task:${this.taskId}:llm:${occurrence}`,
            {
              status: 'succeeded',
              model: this.deps.modelName,
              attempt: iteration + 1,
            },
            event.timestamp
          )
        }
        if (event.type === 'tool:completed') {
          const callId =
            typeof event.data.toolCallId === 'string'
              ? event.data.toolCallId
              : `${event.data.toolName ?? 'tool'}:${event.timestamp.getTime()}`
          this.enqueueGovernedToolCompletion(
            callId,
            typeof event.data.toolName === 'string' ? event.data.toolName : 'tool',
            event.data.toolKind === 'mcp_server_tool' || event.data.toolKind === 'workflow'
              ? event.data.toolKind
              : 'internal_tool',
            typeof event.data.toolSourceRef === 'string'
              ? event.data.toolSourceRef.trim() || null
              : null,
            Boolean(event.data.is_error),
            event.timestamp
          )
        }
        this.turnTiming?.recordEvent(event.type, event.data)
        this.deps.coreEvents.emit(event)
      },
      on: this.deps.coreEvents.on.bind(this.deps.coreEvents),
      off: this.deps.coreEvents.off.bind(this.deps.coreEvents),
    }
  }

  private enqueueGovernedToolCompletion(
    toolCallId: string,
    toolName: string,
    toolKind: 'internal_tool' | 'mcp_server_tool' | 'workflow',
    toolSourceRef: string | null,
    isError: boolean,
    occurredAt: Date
  ): void {
    const approvalRequestId =
      this.approvedToolCorrelation?.toolCallId === toolCallId
        ? this.approvedToolCorrelation.approvalRequestId
        : undefined
    this.enqueueGovernedRunEvent(
      'tool_call',
      `task:${this.taskId}:tool:${toolCallId}`,
      {
        status: isError ? 'failed' : 'succeeded',
        tool_name: toolName,
        tool_kind: toolKind,
        ...(toolSourceRef ? { tool_source_ref: toolSourceRef } : {}),
      },
      occurredAt,
      approvalRequestId
    )
    if (approvalRequestId) this.approvedToolCorrelation = undefined
  }

  private enqueueGovernedRunEvent(
    eventType: 'run_start' | 'llm_call' | 'tool_call' | 'approval' | 'token_usage' | 'run_end',
    sourceEventId: string,
    payload?: {
      status?: string
      error_class?: string
      tool_name?: string
      tool_kind?: 'internal_tool' | 'mcp_server_tool' | 'workflow'
      tool_source_ref?: string
      model?: string
      attempt?: number
      count?: number
    },
    occurredAt = new Date(),
    approvalRequestId?: string
  ): void {
    const trace = this.task.traceContext
    const hostRef = this.deps.usageStaticContext?.host_ref
    if (!trace || !hostRef) return
    this.deps.governedRunReporter?.enqueue({
      sourceEventId,
      occurredAt: occurredAt.toISOString(),
      eventType,
      runId: trace.runId,
      approvalRequestId,
      hostRef,
      sessionId: trace.sessionId ?? null,
      origin: trace.origin,
      ...(payload ? { payload } : {}),
    })
  }

  private async guardProviderWorkflowTriggerClaim(rawContent: string): Promise<string> {
    if (this.currentTurnToolNames.has('workflow_trigger')) return rawContent
    const sourceMessageContent = this.task.sourceMessage?.content ?? ''
    const sourceLooksLikeTriggerRequest = looksLikeWorkflowTriggerRequest(sourceMessageContent)
    const usedWorkflowReadTool = [...this.currentTurnToolNames].some(
      toolName => toolName.startsWith('workflow_') && toolName !== 'workflow_trigger'
    )
    if (usedWorkflowReadTool && !sourceLooksLikeTriggerRequest) return rawContent
    if (!looksLikeWorkflowTriggerSuccess(rawContent) && !sourceLooksLikeTriggerRequest) {
      return rawContent
    }

    const context = this.workflowCallerContextOverride
    if (
      !context ||
      !context.targetUserId ||
      (context.originChannelType !== 'telegram' &&
        context.originChannelType !== 'slack' &&
        context.originChannelType !== 'teams')
    ) {
      if (
        this.workflowAccessDeniedResponse &&
        isProviderWorkflowChannel(this.task.sourceMessage?.channelType)
      ) {
        this.logProviderWorkflowAccessDenied('trigger_claim')
        return this.workflowAccessDeniedResponse
      }
      return rawContent
    }
    const workflowContext: WorkflowCallerContext & { targetUserId: string } = {
      ...context,
      targetUserId: context.targetUserId,
    }

    try {
      return await this.resolveUnverifiedProviderWorkflowTriggerClaim(workflowContext)
    } catch (error) {
      logger.warn(
        { taskId: this.taskId, err: error },
        'Could not verify provider workflow trigger claim'
      )
      return 'I could not verify that a workflow was triggered from this message. List workflows and run the workflow by name again.'
    }
  }

  private async resolveUnverifiedProviderWorkflowTriggerClaim(
    context: WorkflowCallerContext & { targetUserId: string }
  ): Promise<string> {
    const workflowName = await this.workflowNameMentionedInCurrentMessage(context)
    if (!workflowName) {
      return 'I could not verify which workflow should be triggered. List workflows and run the workflow by name again.'
    }

    const client = this.workflowBrokerClient()
    const resolution = await resolveEffectiveWorkflowTarget(client, context, workflowName)
    if (resolution.kind !== 'unique') {
      return resolution.message
    }

    return `I could not verify that ${workflowName} was triggered. Run ${workflowName} again so I can request approval from this conversation.`
  }

  private async workflowNameMentionedInCurrentMessage(
    context: WorkflowCallerContext & { targetUserId: string }
  ): Promise<string | null> {
    const content = this.task.sourceMessage?.content ?? ''
    const normalizedContent = content.toLocaleLowerCase('en-US')
    if (!normalizedContent.trim()) return null

    const result = await requestEffectiveWorkflowList(this.workflowBrokerClient(), context)
    const record =
      result && typeof result === 'object' && !Array.isArray(result)
        ? (result as Record<string, unknown>)
        : {}
    const items = Array.isArray(record.items) ? record.items : []
    const names = items
      .flatMap(item => {
        if (!item || typeof item !== 'object' || Array.isArray(item)) return []
        const name = (item as Record<string, unknown>).name
        return typeof name === 'string' && name.trim() ? [name.trim()] : []
      })
      .sort((a, b) => b.length - a.length)

    const listedName =
      names.find(name => normalizedContent.includes(name.toLocaleLowerCase('en-US'))) ?? null
    if (listedName) return listedName

    const commandMatch = normalizedContent.match(
      /\b(?:run|trigger|start|execute)\s+([a-z0-9][a-z0-9._-]*)/
    )
    return commandMatch?.[1] ?? null
  }

  private workflowBrokerClient(): WorkflowBrokerClient {
    const getEnv = (key: string) => process.env[key]
    return new WorkflowBrokerClient(getEnv, createWorkflowControlTokenProvider(getEnv))
  }

  /**
   * Build the default UsageContext for this task. The adapter falls back to
   * this when an individual CompletionRequest doesn't carry its own.
   *
   * Mapping rules (v1):
   * - task.source = 'channel' + channelType = 'rpc' → source_kind = 'desktop',
   *     user_id = sender (the Desktop App is *not* a third-party channel; the
   *     RPC route stamps message.sender with the authenticated user's `sub`,
   *     so the UUID belongs in user_id, not sender.)
   * - task.source = 'channel'  → source_kind = 'channel', sender + channel_type from sourceMessage
   * - task.source = 'cron'     → source_kind = 'cron', cron_job_id from task.cronJobId
   * - task.source = 'internal' → source_kind = 'desktop'
   * Workflow-recipe LLM calls go through workflowService and are tagged
   * separately at that call site.
   */
  private buildDefaultUsageContext(): UsageContext | undefined {
    const t = this.task
    if (t.source === 'channel') {
      if (t.sourceMessage?.channelType === 'rpc') {
        const teamId =
          typeof t.sourceMessage.metadata?.teamId === 'string'
            ? t.sourceMessage.metadata.teamId.trim()
            : ''
        return {
          source_kind: 'desktop',
          traceContext: t.traceContext ?? null,
          team_id: teamId || null,
          user_id: t.sourceMessage.sender ?? null,
          task_id: t.id,
        }
      }
      return {
        source_kind: 'channel',
        traceContext: t.traceContext ?? null,
        sender: t.sourceMessage?.sender ?? null,
        channel_type: t.sourceMessage?.channelType ?? null,
        task_id: t.id,
      }
    }
    if (t.source === 'cron') {
      return {
        source_kind: 'cron',
        traceContext: t.traceContext ?? null,
        cron_job_id: t.cronJobId ?? null,
        task_id: t.id,
      }
    }
    if (t.source === 'internal') {
      return {
        source_kind: 'desktop',
        traceContext: t.traceContext ?? null,
        task_id: t.id,
      }
    }
    return { source_kind: 'unknown', traceContext: t.traceContext ?? null, task_id: t.id }
  }

  /**
   * T2.2 — get-or-build the tiered `SystemPromptParts` for this session.
   * Returns `undefined` when the cache flag is OFF or when no `PromptCache`
   * / `WorkspaceService` is wired (legacy path stays bit-identical). When
   * present the parts are looked up by sessionKey; a miss reads the four
   * identity files + a fresh `snapshotDailyLogs(2)` (frozen for the life of
   * this session) and runs the parts through `DefaultPromptBuilder.buildParts`.
   *
   * The lookup is per-task; the cache lives on the process and survives
   * across tasks of the same session, so multi-turn conversations get a
   * single build amortized over many LLM calls.
   */
  private async maybeGetOrBuildParts(
    tools: ToolDefinition[]
  ): Promise<SystemPromptParts | undefined> {
    if (!appConfig.promptCacheEnabled) return undefined
    if (!this.deps.promptCache || !this.deps.workspaceService) return undefined
    const sessionKey = this.sessionKey
    if (!sessionKey) return undefined

    const cached = this.deps.promptCache.get(sessionKey)
    const provider = this.deps.llmProvider.getProviderType()
    // Only instruction-presence gates belong in the cache identity. Catalog
    // count and schemas do not: discovery guidance is constant at any scale.
    const toolGuidanceKey = JSON.stringify([
      tools.some(t => t.name.startsWith('memory_')),
      tools.some(t => t.name === 'clerum__get_capabilities'),
      tools.some(t => t.name.startsWith('desktop_') || t.name.startsWith('browser_')),
      tools.some(t => t.name.startsWith('workflow_')),
      tools.some(t => t.name === 'clerum__gfs_download'),
      tools.some(t => t.name.includes('__')),
      tools.some(t => t.name === 'clerum__tool_search'),
      // #1003 — the discovery guidance text depends on the native presentation.
      appConfig.nativeToolPresentation,
    ])
    // R2 — the system prompt embeds the model name, so a cache entry built for a
    // different (e.g. just-swapped) model is a miss: rebuild, but keep the frozen
    // dailyLogSnapshot so the daily-freeze invariant holds.
    if (
      cached?.parts &&
      cached.model === this.deps.modelName &&
      cached.provider === provider &&
      cached.toolGuidanceKey === toolGuidanceKey
    )
      return cached.parts

    const dailyLogSnapshot =
      cached?.dailyLogSnapshot ?? (await this.deps.workspaceService.snapshotDailyLogs(2))
    const identityFiles = await this.deps.workspaceService.readIdentityFiles()
    const builder = new DefaultPromptBuilder({
      nativeToolPresentation: appConfig.nativeToolPresentation,
    })
    const hasMemoryTools = tools.some(t => t.name.startsWith('memory_'))
    const hasCapabilities = tools.some(t => t.name === 'clerum__get_capabilities')
    const hasDesktopTools = tools.some(
      t => t.name.startsWith('desktop_') || t.name.startsWith('browser_')
    )
    // Tool-presence gates MUST mirror `buildSystemPrompt` exactly so the cache
    // path emits byte-identical guidance to the legacy path. Note `includes('__')`
    // (not a strict MCP-server check) matches the legacy MCP-selection gate,
    // which also fires for `clerum__get_capabilities`.
    const hasWorkflowTools = tools.some(t => t.name.startsWith('workflow_'))
    const hasGfsDownloadTool = tools.some(t => t.name === 'clerum__gfs_download')
    // NOTE: this is intentionally still true when the bridge is active — the
    // `clerum__tool_search/describe/call` native/bridge tools also contain `__`,
    // so `MCP_SERVER_SELECTION_TEXT` still emits. That is fine: `TOOL_DISCOVERY_TEXT`
    // (gated below and emitted right after) clarifies the discovery flow. We do NOT
    // tighten the heuristic here — a stricter check would alter the flag-OFF default
    // path on native-only hosts and break the byte-identical guarantee. A deeper
    // suppression is deferred for that reason.
    const hasMcpTools = tools.some(t => t.name.includes('__'))
    // The registered bridge is the same source of truth as the legacy prompt.
    const hasToolDiscovery = tools.some(t => t.name === 'clerum__tool_search')
    const capabilities = hasCapabilities ? CAPABILITY_CONTRACT_TEXT : ''
    const platformHints: string[] = []
    if (hasDesktopTools) {
      platformHints.push(DESKTOP_ENVIRONMENT_HINT)
    }

    const parts = builder.buildParts({
      identityFiles,
      dailyLogSnapshot,
      model: this.deps.modelName,
      provider: this.deps.llmProvider.getProviderType(),
      platformHints,
      capabilities,
      workflowGuidance: hasWorkflowTools ? WORKFLOW_RECIPES_TEXT : '',
      gfsWorkspaceGuidance: hasGfsDownloadTool ? GFS_WORKSPACE_FILE_GUIDANCE_TEXT : '',
      mcpServerGuidance: hasMcpTools ? MCP_SERVER_SELECTION_TEXT : '',
      toolDiscoveryGuidance: hasToolDiscovery
        ? toolDiscoveryText(appConfig.nativeToolPresentation)
        : '',
      memoryGuidance: hasMemoryTools ? MEMORY_GUIDANCE_TEXT : '',
    })
    this.deps.promptCache.set(sessionKey, {
      parts,
      dailyLogSnapshot,
      model: this.deps.modelName,
      provider,
      toolGuidanceKey,
    })
    // P1-005: persist the stable_hash for auditability and so post-eviction
    // rebuilds in the same session can verify identity-files didn't drift.
    if (this.conversation) {
      this.deps.conversationManager.recordSystemPromptStableHash(
        this.conversation,
        parts.stableHash
      )
    }
    stampStableHashGauge(sessionKey, parts.stableHash)
    return parts
  }

  private async buildSystemIdentity(llmPort: LlmPortAdapter): Promise<string> {
    const providerType = this.deps.llmProvider.getProviderType()
    const modelLine =
      `You are an AI assistant powered by the ${this.deps.modelName} model (provider: ${providerType}). ` +
      'Use the available tools when needed to help the user.'

    if (this.deps.workspaceService) {
      const workspaceIdentity = await this.deps.workspaceService.assembleSystemPrompt()
      return workspaceIdentity ? `${workspaceIdentity}\n\n---\n\n${modelLine}` : modelLine
    }
    return modelLine
  }

  /**
   * Best-effort per-turn catalog bootstrap. Opens the caller's grant-backed
   * remote OAuth partitions (per-user and SHARED oauth-context) so their tools
   * are in the catalog this turn builds — a failure only forfeits that head start
   * and falls back to lazy admission, so it NEVER throws. It runs once per task
   * (createToolRegistry is cached by toolRegistryPromise), and the abort only cuts
   * this turn's wait: the admissions belong to the manager, are coalesced there,
   * and outlive the turn.
   */
  private async bootstrapMcpCatalog(): Promise<void> {
    const manager = this.deps.mcpManager
    const userId = this.task.sourceMessage?.sender
    if (!manager || !userId) return
    const started = Date.now()
    try {
      const summary = await withAbort(
        () => manager.bootstrapUserCatalog(userId, { signal: this.abortController.signal }),
        this.abortController.signal
      )
      if (summary.candidates > 0) {
        logger.info({ taskId: this.taskId, ...summary }, 'MCP catalog bootstrap')
      }
    } catch (err) {
      logger.warn(
        { taskId: this.taskId, err, elapsedMs: Date.now() - started },
        'MCP catalog bootstrap failed; continuing with lazy admission'
      )
    }
  }

  private async buildToolRegistry(): Promise<TaskToolRegistry> {
    if (!this.toolRegistryPromise) {
      this.toolRegistryPromise = this.createToolRegistry()
    }

    try {
      return await this.toolRegistryPromise
    } catch (error) {
      this.toolRegistryPromise = null
      throw error
    }
  }

  private async createToolRegistry(): Promise<TaskToolRegistry> {
    const workflowCallerContext =
      this.workflowCallerContextOverride === undefined
        ? await this.prepareChannelWorkflowCallerContext()
        : this.workflowCallerContextOverride
    // Failover reuses this registry: any Codex provider in the chain requires
    // Codex-compatible presentation before the first provider attempt.
    const presentation = resolveToolPresentation(
      this.deps.llmProvider.getProviderType(),
      appConfig,
      this.deps.failover?.policy.fallbacks
    )
    // #1003 — native-tool presentation is host-wide and provider-independent:
    // it never depends on the MCP presentation resolved above.
    const nativeAuto = appConfig.nativeToolPresentation === 'auto'
    // The store is keyed like the caller root, never by the raw sender.
    const gfsCallerIdentity = gfsStoreCallerIdentity(this.task.sourceMessage)
    const gfsWorkspace = gfsManagedWorkspaceExecution({
      approvalEnabled: appConfig.enableApproval,
      source: this.task.source,
      callerIdentity: gfsCallerIdentity,
      store: this.deps.gfsDownloadStore,
      callerWorkspacePath: this.deps.gfsCallerWorkspacePath,
      approvalConfig: this.deps.approvalConfig,
      retentionOwnerId: this.taskId,
    })
    const gfsDeliveryEligible = gfsWorkspace
      ? gfsWorkspaceExecutionEnabled({
          approvalEnabled: appConfig.enableApproval,
          source: this.task.source,
          callerIdentity: this.task.sourceMessage?.sender,
          store: gfsWorkspace.store,
          callerWorkspacePath: gfsWorkspace.callerWorkspacePath,
          approvalConfig: this.deps.approvalConfig,
          retentionOwnerId: this.taskId,
        })
      : false
    const nativeRegistry = new NativeToolRegistry(
      appConfig.nativeTool,
      this.conversation!.id,
      this.deps.cronScheduler ?? undefined,
      this.task.sourceMessage,
      this.deps.workspaceService,
      this.deps.dynamicEnvProvider,
      workflowCallerContext,
      {
        maxBytes: appConfig.attachmentMaxBytes,
        secretEntriesProvider: this.deps.secretEntriesProvider,
        // Keep the ledger and bound pages for every model this task may serve.
        ledger: this.attachmentReadLedger,
        contextWindowTokens: attachmentContextWindow(
          this.contextMaxTokens(),
          this.deps.llmProvider.getProviderType(),
          this.deps.failover?.policy.fallbacks ?? [],
          this.deps.failover?.contextWindowForPair,
          appConfig.contextMaxTokens
        ),
      },
      this.deps.spilloverStorage,
      this.deps.sessionSearchService,
      // F2 (dynamic-tool-loading): backs the read-only discovery meta-tools
      // (clerum__tool_search / clerum__tool_describe). Reuses the same manager
      // already threaded into the MCP tool registry below.
      this.deps.mcpManager ?? undefined,
      // #1003 — MCP discovery and native discovery are separate decisions;
      // either one registers the bridge tools.
      { mcpDiscovery: presentation.bridgeEnabled, nativeDiscovery: nativeAuto },
      // §13 (stateless agents): the active provider's credential slot is the
      // only one that survives into shell_exec's child env.
      this.deps.llmProvider.getProviderType(),
      gfsWorkspace ? { ...gfsWorkspace, deliveryAvailable: gfsDeliveryEligible } : undefined,
      generatedOutputsRoot(this.task.sourceMessage, this.deps.gfsCallerWorkspacePath)
    )
    await registerDesktopTools(nativeRegistry)
    // Eagerly open this caller's remote OAuth partitions before the catalog is
    // read, so grant-backed tools exist in the very first turn instead of after a
    // failed lazy call. Best-effort: a failure here must never invalidate the
    // registry promise or the task.
    await this.bootstrapMcpCatalog()
    const mcpRegistry = this.deps.mcpManager
      ? // Thread the authenticated caller identity so oauth grantScope='user'
        // tools dispatch to the caller's per-user partition (fail-closed when
        // absent). buildToolRegistry runs per turn, so one userId per adapter.
        new McpToolRegistryAdapter(
          this.deps.mcpManager,
          this.task.sourceMessage?.sender ?? undefined,
          { strictValidation: presentation.codexMode !== undefined }
        )
      : nativeRegistry
    const compositeRegistry = this.deps.mcpManager
      ? new CompositeToolRegistry(nativeRegistry, mcpRegistry)
      : nativeRegistry

    // Cron tasks run autonomously by design: the human trust decision happens at
    // job-creation time, so the runtime approval gate does NOT apply per-tool at
    // fire time (there is no user to approve). Containment is infrastructural
    // (Context allowlist, NetworkPolicy, tool-call and duration limits). See
    // issue #529.
    //
    // NARROW EXCEPTION (cron×stateless self-propagation containment): a
    // cron-sourced task may still call cron_manage. On a stateless host,
    // cron_manage create/enable each pin the pod awake (activeCronSchedules) and
    // let an already-approved schedule autonomously spawn/enable MORE schedules
    // — a prompt-injection self-propagation + cost lever. So on a stateless host
    // we DO wrap a cron-sourced task with the approval chain, but in
    // `cronManageGateOnly` mode: ONLY cron_manage create/enable can suspend;
    // every other tool call (incl. cron_manage list/get/delete/disable/trigger
    // and all non-cron_manage work) keeps #529's autonomy and proceeds. The
    // resulting suspension has no human to answer it in an autonomous run — that
    // is the desired containment: the suspicious create/enable is BLOCKED, not
    // auto-approved.
    const interactiveApprovalApplies = appConfig.enableApproval && this.task.source !== 'cron'
    const cronManageGateApplies =
      appConfig.enableApproval && this.task.source === 'cron' && appConfig.statelessLifecycle
    const approvalApplies = interactiveApprovalApplies || cronManageGateApplies
    const approvalGate = approvalApplies
      ? new UnifiedApprovalGateController(
          compositeRegistry,
          this.deps.approvalConfig,
          nativeRegistry,
          // Cron×stateless: forces HITL approval for cron_manage create/enable on
          // stateless hosts regardless of the per-tool approval override.
          // `cronManageGateOnly` narrows that to be the ONLY gate for a
          // cron-sourced task, preserving #529 autonomy for every other tool.
          {
            statelessLifecycle: appConfig.statelessLifecycle,
            cronManageGateOnly: cronManageGateApplies,
          }
        )
      : null
    const innerController = approvalGate
      ? new ApprovalController(
          this.conversation!,
          approvalGate,
          gfsWorkspace &&
            appConfig.enableApproval &&
            this.task.source === 'channel' &&
            this.deps.approvalConfig?.tools?.shell_exec !== false
            ? new Set(['clerum__gfs_download'])
            : undefined,
          // The same gate's forced approvals (stateless cron create/enable) run
          // before any stored approval, so none of them can cover such a call.
          approvalGate
        )
      : new DefaultLoopController()

    const mcpManager = this.deps.mcpManager
    // Exact native membership preserves every native/plugin capability.
    const nativeDefinitions = nativeRegistry.listDefinitions()
    const nativeNames = new Set(nativeDefinitions.map(d => d.name))

    // #1003 — native presentation wraps OUTSIDE the MCP decision on every
    // return, so it can only remove natives from the list the MCP presentation
    // produced. In `direct` it returns that list unchanged.
    const withNativePresentation = (controller: LoopController): LoopController =>
      new NativeToolPresentationController(controller, nativeDefinitions, {
        mode: appConfig.nativeToolPresentation,
        discoveryBytes: appConfig.nativeToolDiscoveryBytes,
      })
    // The natives that controller hides, for the prompt builder's guidance.
    const deferredNatives = nativeAuto
      ? selectDeferredNatives(nativeDefinitions, appConfig.nativeToolDiscoveryBytes)
      : new Set<string>()
    const discoverableNatives = nativeDefinitions.filter(d => deferredNatives.has(d.name))

    // The bridge intercept (executeToolCalls) needs `nativeNames` + the live
    // deferrable catalog. It exists exactly when NativeToolRegistry registered
    // the bridge tools (MCP discovery with an McpManager, or native `auto`), so
    // it is derived from the registry rather than repeating that predicate.
    // Codex direct with native `direct` observes presentation without
    // installing discovery interception or registering bridge tools.
    const bridge: LoopConfig['bridge'] = [...BRIDGE_TOOL_NAMES].every(name => nativeNames.has(name))
      ? {
          nativeNames,
          getDeferrableCatalogNames: () =>
            mcpManager
              ? new Set(
                  mcpManager
                    .getAllTools()
                    .map(t => t.name)
                    .filter(name => !nativeNames.has(name))
                )
              : new Set<string>(),
          nativeTargets: nativeAuto,
        }
      : undefined

    // Codex direct still observes the live catalog; observation must not enable discovery.
    if (!presentation.bridgeEnabled && presentation.codexMode === undefined) {
      return {
        registry: compositeRegistry,
        nativeRegistry,
        loopController: withNativePresentation(innerController),
        discoverableNatives,
        // Native `auto` only: MCP presentation is unchanged (no MCP decision on
        // this path) but the bridge serves natives and keeps MCP tools callable.
        bridge,
      }
    }

    // LOCKED #6: the latch lives on the session-scoped Conversation, NOT on the
    // per-task controller, so a server connecting/disconnecting BETWEEN turns
    // cannot flip `tools[]` and re-introduce cache invalidation. Ephemeral RAM
    // (not a DB column), recomputed on cold-load — consistent with #3.
    const conversation = this.conversation!
    const loopController: LoopController = new DeferrableToolController(
      innerController,
      nativeNames,
      {
        dynamicToolsEnabled: presentation.bridgeEnabled,
        codexMode: presentation.codexMode,
        codexToolDiscoveryBytes: appConfig.codexToolDiscoveryBytes,
        dynamicToolsThreshold: appConfig.dynamicToolsThreshold,
      },
      {
        get: () => conversation.dynamicToolsBridgeActive,
        set: value => {
          conversation.dynamicToolsBridgeActive = value
        },
      }
    )

    return {
      registry: compositeRegistry,
      nativeRegistry,
      loopController: withNativePresentation(loopController),
      discoverableNatives,
      bridge,
    }
  }

  private async prepareChannelWorkflowCallerContext(): Promise<
    WorkflowCallerContext | null | undefined
  > {
    if (this.workflowCallerContextOverride !== undefined) return this.workflowCallerContextOverride

    const message = this.task.sourceMessage
    if (!message || message.channelType === 'rpc') {
      this.workflowAccessDeniedResponse = null
      this.workflowAccessDeniedReason = null
      this.workflowCallerContextOverride = undefined
      return undefined
    }
    if (
      message.channelType !== 'telegram' &&
      message.channelType !== 'slack' &&
      message.channelType !== 'teams'
    ) {
      this.workflowAccessDeniedResponse = null
      this.workflowAccessDeniedReason = null
      this.workflowCallerContextOverride = null
      return null
    }
    if (!message.providerIdentity) {
      this.setProviderWorkflowAccessDenied(message, 'missing_provider_identity')
      return null
    }

    try {
      const context = await resolveProviderWorkflowCallerContext(
        message,
        key => process.env[key],
        this.task.traceContext
      )
      if (context) {
        this.workflowAccessDeniedResponse = null
        this.workflowAccessDeniedReason = null
        this.workflowCallerContextOverride = context
        return context
      }
    } catch (error) {
      logger.warn(
        { taskId: this.taskId, err: error },
        'Provider workflow identity resolution failed'
      )
    }
    this.setProviderWorkflowAccessDenied(message, 'unverified_provider_identity')
    return null
  }

  private setProviderWorkflowAccessDenied(
    message: NonNullable<Task['sourceMessage']>,
    reason: ProviderWorkflowAccessDenialReason
  ): void {
    this.workflowCallerContextOverride = null
    this.workflowAccessDeniedResponse = workflowAccessDeniedResponseForMessage(message)
    this.workflowAccessDeniedReason = reason
  }

  private logProviderWorkflowAccessDenied(stage: 'request' | 'trigger_claim'): void {
    const message = this.task.sourceMessage
    const channel = isProviderWorkflowChannel(message?.channelType)
      ? message.channelType
      : 'unknown'
    logger.warn(
      {
        taskId: this.taskId,
        channel,
        stage,
        reason: this.workflowAccessDeniedReason ?? 'unverified_provider_identity',
      },
      'Provider workflow access denied'
    )
  }

  private collectAttachments(results: ToolResult[]): Attachment[] {
    const attachments: Attachment[] = []
    collectToolAttachments(results, attachments)
    return attachments
  }

  /**
   * Codex V2 hashes each image source. Bind identity only when this chain
   * (primary or a configured fallback) requires it so a non-Codex wire stays
   * on the #654 shape.
   */
  private providerChainRequiresImageSourceIdentity(): boolean {
    return (
      this.deps.llmProvider.requiresImageSourceIdentity === true ||
      [
        this.deps.llmProvider.getProviderType(),
        ...(this.deps.failover?.policy.fallbacks.map(entry => entry.provider) ?? []),
      ].some(
        provider =>
          isLlmProvider(provider) && descriptorFor(provider).requiresImageSourceIdentity === true
      )
    )
  }

  private buildSourceMessageContentParts(messageContent: string): MessageContentPart[] {
    const providerType = this.deps.llmProvider.getProviderType()
    // getProviderType() always returns a registered LlmProvider, so in practice
    // this never drops images for a known provider — that's the point: a new
    // registry provider keeps its image attachments instead of silently losing
    // them to a stale allow-list.
    if (!isLlmProvider(providerType)) {
      return []
    }
    const sourceAttachments = this.task.sourceMessage?.attachments
    if (!sourceAttachments || sourceAttachments.length === 0) {
      return []
    }
    // Frozen provenance identity (#650). `messageId` is the delivery identity
    // the channel supplied; internal/cron sources carry an empty id, so the
    // queued task id stands in as the real identity of that task's message.
    // Neither value is a placeholder, and neither is rewritten here: a value
    // the shared contract does not accept fails its projection check instead.
    const messageId = this.task.sourceMessage?.messageId?.trim() || this.task.id
    const bindSource = this.providerChainRequiresImageSourceIdentity()
    const imageParts = sourceAttachments
      .filter(
        att =>
          att.kind === 'image' && (att.mimeType === 'image/jpeg' || att.mimeType === 'image/png')
      )
      .map(
        (att): MessageContentPart => ({
          type: 'image',
          mimeType: att.mimeType as 'image/jpeg' | 'image/png',
          data: att.dataBase64,
          ...(bindSource
            ? { source: { kind: 'attachment' as const, attachmentId: att.id, messageId } }
            : {}),
        })
      )
    if (!imageParts.length) {
      return []
    }
    // Preserve the actual history text (including any contextual enrichment).
    // Reading sourceMessage again would overwrite text already assembled above.
    const userText = messageContent.trim() ? messageContent : 'User attached image(s).'
    return [{ type: 'text', text: userText }, ...imageParts]
  }
}