Merge remote-tracking branch 'origin/codex/enforce-tool-cancellation' into worktree/explicit-turn-signal

# Conflicts:
#	docs/architecture.md
#	docs/cordis-catalog/events.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/loop.ts
#	packages/core/agent/README.md
#	packages/examples/cli-demo/src/cli.ts
#	packages/ui/tui/tests/tui.spec.ts

packages/core/agent-loop/src/loop.ts

@@ -6,9 +6,9 @@
  */
 
 import type { Context } from 'cordis'
-import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, LlmFailure, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
-import { BlockAssembler, HarnessError, assertNever, deepFreeze, errorChain, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm'
+import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorChain, llmFailureOf } from '@deepseek-ai/dsh-llm'
 import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
@@ -29,24 +29,29 @@ function toError(error: unknown): RequestError {
 
 /** Distinguishes final model-request failures from failures in later step processing. */
 class TerminalModelRequestFailure extends Error {
-  constructor(readonly requestError: RequestError) {
-    super(requestError.message, { cause: requestError })
+  constructor(
+    readonly requestError: RequestError,
+    readonly failure: LlmFailure,
+  ) {
+    super(failure.message, { cause: requestError })
     this.name = 'TerminalModelRequestFailure'
   }
 }
 
 /** Convert terminal failure finishes into step errors; unknown extensible finishes remain successful. */
-function finishError(finish: FinishReason): RequestError | undefined {
+function finishError(finish: FinishReason): { error: RequestError; failure: LlmFailure } | undefined {
   switch (finish.kind) {
-    case 'error': {
-      const error: RequestError = new Error(finish.message)
-      if (finish.code !== undefined) error.code = finish.code
-      return error
-    }
+    case 'error':
     case 'aborted': {
-      const error: RequestError = new Error('model stream aborted')
-      error.code = 'ABORTED'
-      return error
+      const facts = finish.failure
+      const error = new LlmError(facts.message, facts.code, {
+        ...facts.status === undefined ? {} : { status: facts.status },
+        ...facts.providerRetryAfterMs === undefined
+          ? {}
+          : { providerRetryAfterMs: facts.providerRetryAfterMs },
+        ...facts.requestId === undefined ? {} : { requestId: facts.requestId },
+      })
+      return { error, failure: error.failure }
     }
     // stop / tool-calls / max-tokens / plugin-added kinds → not a failure.
     default:
@@ -65,6 +70,12 @@ function errorData(err: RequestError): { message: string; code?: string } {
   return { message: errorChain(err), ...typeof err.code === 'string' ? { code: err.code } : {} }
 }
 
+/** Preserve cause diagnostics, falling back to adapter-normalized prose for a hostile Error. */
+function durableFailure(err: RequestError, failure: LlmFailure): LlmFailure {
+  const message = errorChain(err)
+  return { ...failure, message: message === '<unrenderable value>' ? failure.message : message }
+}
+
 /** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */
 function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
   switch (finish.kind) {
@@ -241,7 +252,7 @@ async function runTurn(
 
   let reason: TurnEndReason = { kind: 'completed' }
   let step = 0
-  let requestRetryAttempt = 0
+  let requestFailureHistory: readonly LlmFailure[] = Object.freeze([])
   let stepOpen = false
   let errorReported = false
   let terminalStopped = false
@@ -254,10 +265,12 @@ async function runTurn(
   }
 
   // Record the durable turn failure once and contain the live error notification.
-  const failTurn = (err: RequestError): void => {
+  const failTurn = (err: RequestError, failure?: LlmFailure): void => {
     if (errorReported) return
     errorReported = true
-    reason = { kind: 'error', step, ...errorData(err) }
+    reason = failure === undefined
+      ? { kind: 'error', step, ...errorData(err) }
+      : { kind: 'error', step, failure: durableFailure(err, failure) }
     try {
       events.emit('agent/error', turn, step, err)
     } catch {
@@ -352,14 +365,14 @@ async function runTurn(
 
       let stepOutcome:
         | { hadToolCalls: boolean; finish: FinishReason }
-        | { requestError: RequestError }
+        | { requestError: RequestError; failure: LlmFailure }
         | { error: RequestError }
       try {
         stepOutcome = await runStep(
           ctx, events, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, signal)
       } catch (error: unknown) {
         if (error instanceof TerminalModelRequestFailure) {
-          stepOutcome = { requestError: error.requestError }
+          stepOutcome = { requestError: error.requestError, failure: error.failure }
         } else {
           stepOutcome = { error: toError(error) }
         }
@@ -380,7 +393,7 @@ async function runTurn(
         try {
           recoveryDecision = await events.waterfall(
             'agent/request-error', turn, step, stepOutcome.requestError,
-            requestRetryAttempt, signal,
+            stepOutcome.failure, requestFailureHistory, signal,
             () => Promise.resolve(defaultDecision),
           )
         } catch (recoveryError: unknown) {
@@ -397,10 +410,10 @@ async function runTurn(
         }
         switch (recoveryDecision.action) {
           case 'retry':
-            requestRetryAttempt += 1
+            requestFailureHistory = Object.freeze([...requestFailureHistory, stepOutcome.failure])
             continue
           case 'fail':
-            failTurn(stepOutcome.requestError)
+            failTurn(stepOutcome.requestError, stepOutcome.failure)
             break
           /* v8 ignore next -- closed-union exhaustiveness guard */
           default:
@@ -421,7 +434,7 @@ async function runTurn(
         break
       }
 
-      requestRetryAttempt = 0
+      requestFailureHistory = Object.freeze([])
 
       // Preserve max-token completion unless a later disposal, abort, or error wins.
       const stepReason = stepFinishReason(stepOutcome.finish)
@@ -605,14 +618,15 @@ async function runStep(
       assembler.push(chunk)
     }
   } catch (error: unknown) {
-    if (isLlmAdapterFailure(stream, error)) throw new TerminalModelRequestFailure(error)
+    const failure = llmFailureOf(stream, error)
+    if (failure !== undefined && error instanceof Error) throw new TerminalModelRequestFailure(error, failure)
     throw error
   }
   interruptionCheckpoint(signal)
 
   // Normalize failure finish chunks into the same path as thrown stream errors.
   const stepError = finishError(assembler.finish)
-  if (stepError) throw new TerminalModelRequestFailure(stepError)
+  if (stepError) throw new TerminalModelRequestFailure(stepError.error, stepError.failure)
 
   const recordAssistantMessage = (
     assembledContent: ContentBlock[],