refactor(agent): return request retry action

.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-2026-07-17-one-send-one-turn.md: d6c771a2b87e14c52b05c9cd8accaa44405fba16
-2026-07-17-one-send-one-turn.zh.md: a057ebce38208f0ed6be3b8b97dd4c434dd3e721
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
+2026-07-17-one-send-one-turn.md: dcc6c0aa483a0e53205dbaeef4e2b903f5f6a215
+2026-07-17-one-send-one-turn.zh.md: 8c12481defe6608c13ee81132b432b4d8b17b681

.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md

@@ -22,7 +22,7 @@ If messages A and B are both processed, B's turn starts only after A records `tu
 
 Prompt admission decides one message at a time before a turn opens. An allowed prompt becomes that turn's `user/message`; a blocked prompt is discarded without opening a turn or writing session history. Mixed-batch and all-blocked-batch branches do not exist.
 
-The no-batching rule applies only to ordinary `send()`. Running `steer()` puts input in the outbox. While a turn remains open, the loop records that input at the next step boundary and steering makes another step the default. A failure before that boundary leaves the steering staged without waking the agent; `retry()` or a later prompt takes it, while cancellation or disposal can discard it. When the agent is idle, `steer()` delegates to `send()`, so it creates an independent ordinary queue item.
+The no-batching rule applies only to ordinary `send()`. Running `steer()` puts input in the outbox. While a turn remains open, the loop records that input at the next step boundary and steering makes another step the default. A failure before that boundary leaves the steering staged without waking the agent; a request-error retry action or a later prompt takes it, while cancellation or disposal can discard it. When the agent is idle, `steer()` delegates to `send()`, so it creates an independent ordinary queue item.
 
 `inject()` continues to add model-facing context without submitting an ordinary message. During a turn it waits in the outbox for a safe step boundary; while idle it appends a `user/message` directly, without opening a turn or running the model. Persistence owns the resulting eager drain. `cancel()` remains a whole-agent operation that can clear all unstarted ordinary and steering input and abort the current step. `status` and `whenIdle()` also describe the whole agent, not one message. Several one-message turns can share one `running` interval, so `running` does not prove that a turn is open.
 

.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md

@@ -22,7 +22,7 @@ Status: implemented
 
 提示词准入会在轮次打开前，每次只决定一条消息。获准提示词成为该轮次的 `user/message`；被阻止的提示词会被丢弃，不打开轮次，也不写入会话历史。实现中不存在混合批次或全阻止批次分支。
 
-上述不合批规则只适用于普通 `send()`。agent 运行时，`steer()` 会把输入放入 outbox。只要当前轮次仍然打开，agent loop 就会在下一个步骤边界记录该输入，而 steering（中途引导）会默认让循环再执行一个步骤。在到达该边界前发生失败，会让 steering 保持暂存且不唤醒 agent；`retry()` 或后续提示词会取走它，而取消或 dispose 可以将其丢弃。agent 空闲时，`steer()` 委托给 `send()`，因此会创建一个独立的普通队列项。
+上述不合批规则只适用于普通 `send()`。agent 运行时，`steer()` 会把输入放入 outbox。只要当前轮次仍然打开，agent loop 就会在下一个步骤边界记录该输入，而 steering（中途引导）会默认让循环再执行一个步骤。在到达该边界前发生失败，会让 steering 保持暂存且不唤醒 agent；请求错误的重试动作或后续提示词会取走它，而取消或 dispose 可以将其丢弃。agent 空闲时，`steer()` 委托给 `send()`，因此会创建一个独立的普通队列项。
 
 `inject()` 继续添加面向模型的上下文，而不提交普通消息。轮次打开时，该上下文会留在 outbox 中，等待安全的步骤边界；agent 空闲时，系统会直接追加一条 `user/message`，既不打开轮次，也不运行模型。持久化层独立负责由此产生的即时排空。`cancel()` 仍是面向整个 agent 的操作，可以清空所有尚未启动的普通输入和 steering，并中止当前步骤。`status` 和 `whenIdle()` 描述的也是整个 agent，而不是某一条消息。多个单消息轮次可以共用一个 `running` 区间，因此 `running` 不表示轮次一定处于打开状态。
 

.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
-2026-07-24-agent-loop-observable-state-machine.md: 2905e003a05bf1c8caa8f784787fb76f8e76b7d7
-2026-07-24-agent-loop-observable-state-machine.zh.md: 1d6b5e5d34d020ef5561b8016b5ad065c96bff12
+2026-07-24-agent-loop-observable-state-machine.md: 54730de8aa73342b609d423dc478edb076d7844b
+2026-07-24-agent-loop-observable-state-machine.zh.md: 206ac701472f14823300df0c812f2cc818f852f5

.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md

@@ -25,9 +25,9 @@ The loop keeps five machine extension events. `agent/prompt-submit` admits, rewr
 
 Continuation and termination are data rather than returned control enums. Tool calls and accepted steering require another step. A tool result carrying `concludesTurn` ends the tool loop at its step. The loop does not expose general `ContinuationDecision` or terminal-stop return channels.
 
-A model-request failure closes its step, then enters `agent/request-error` with the exact error, normalized `LlmFailure`, and live turn signal. A listener that owns recovery repairs state, calls `agent.retry()`, and returns without delegating. The loop closes the failed turn and opens one retry turn over that state without an intervening idle notification; retry is not another step inside the failed turn. `agent/settled` reports the terminal outcome, and `agent/error` remains the live error notification for consumers that report failures independently of turn settlement.
+A model-request failure closes its step, then enters `agent/request-error` with the exact error, normalized `LlmFailure`, and live turn signal. A listener that owns recovery repairs state, returns `{ kind: 'retry' }`, and stops delegating. The loop closes the failed turn and opens one retry turn over that state without an intervening idle notification; retry is not another step inside the failed turn. `agent/settled` reports the terminal outcome, and `agent/error` remains the live error notification for consumers that report failures independently of turn settlement. The [retry-action decision](2026-07-27-request-error-retry-action.md) supersedes the command-shaped part of this design.
 
-The event taxonomy removes `agent/pre-step`, `agent/post-step`, `agent/session-prefix`, `agent/step-result`, `agent/turn-continuation`, and `agent/turn-stop`. Durable turn and step boundaries remain session events. Model-facing additions use logged message channels, request configuration uses `agent/request`, response content is recorded as assembled, failed-request recovery uses `agent/request-error` plus `agent.retry()`, and end-of-turn continuation uses `agent/turn-stopping` plus steering.
+The event taxonomy removes `agent/pre-step`, `agent/post-step`, `agent/session-prefix`, `agent/step-result`, `agent/turn-continuation`, and `agent/turn-stop`. Durable turn and step boundaries remain session events. Model-facing additions use logged message channels, request configuration uses `agent/request`, response content is recorded as assembled, failed-request recovery uses the `agent/request-error` return action, and end-of-turn continuation uses `agent/turn-stopping` plus steering.
 
 ## Alternatives considered
 
@@ -35,7 +35,7 @@ The event taxonomy removes `agent/pre-step`, `agent/post-step`, `agent/session-p
 
 **Represent disposal as a third `AgentStatus`.** This gives retained handles a terminal status value but duplicates the registry lifecycle already expressed by `agent/disposed`. The decision keeps `AgentStatus` about live activity and makes registration lifetime a separate dimension.
 
-**Return a retry decision from `agent/request-error`.** A returned instruction duplicates the existing `agent.retry()` command and requires the loop to carry policy history across attempts. The waterfall remains useful for ordered ownership: an unhandled listener delegates, while a handling listener performs its awaited repair, calls `agent.retry()`, and stops delegation.
+**Return a retry decision from `agent/request-error`.** This alternative is superseded by the [retry-action decision](2026-07-27-request-error-retry-action.md), which removes the duplicate command and keeps the decision local to the waterfall result.
 
 **Mirror durable turn and step boundaries as agent events.** This gives live consumers a second event stream for the same facts. The decision keeps the session log as the source of truth and exposes only extension checkpoints or live-only facts that the durable stream cannot carry.
 
@@ -45,7 +45,7 @@ The observable machine is smaller and compositional: registration lifetime, acti
 
 Plugins no longer rewrite every phase of the loop. There is no request-only message prefix, assistant-message transform, post-step checkpoint, generic continuation enum, generic terminal-stop result, or in-turn request retry. Extensions use the remaining owned channels instead of recreating those phases.
 
-Continuation plugins publish durable steering rather than returning an unlogged reason. Recovery plugins act after the failed step and explicitly schedule another turn through `agent.retry()`. This makes every attempt a complete turn while keeping asynchronous repair and policy ownership at one narrow waterfall boundary.
+Continuation plugins publish durable steering rather than returning an unlogged reason. Recovery plugins act after the failed step and return an explicit retry action. This makes every attempt a complete turn while keeping asynchronous repair and policy ownership at one narrow waterfall boundary.
 
 The inbox lifecycle complements, rather than replaces, the durable session log. `AgentMessageId` correlates acceptance with claim or discard; turn and step numbers, messages, tool activity, and terminal reasons remain session facts.
 

.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md

@@ -25,9 +25,9 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 是否继续和终止执行由数据表达，不再由返回的控制枚举表达。工具调用和已接受的 steering 要求再执行一个步骤。携带 `concludesTurn` 的工具结果会在其所属步骤终止工具循环。循环不再暴露通用的 `ContinuationDecision` 或终止停止返回通道。
 
-模型请求失败会先关闭当前步骤，再携带准确错误、标准化 `LlmFailure` 和仍有效的轮次信号进入 `agent/request-error`。负责恢复的监听器修复状态、调用 `agent.retry()`，并停止继续委托。循环会关闭失败轮次，并基于该状态开启一个重试轮次，中间不发布空闲通知；重试不是失败轮次内的另一个步骤。`agent/settled` 报告终态结果；对于需要脱离轮次结算单独报告失败的消费方，`agent/error` 仍作为实时错误通知保留。
+模型请求失败会先关闭当前步骤，再携带准确错误、标准化 `LlmFailure` 和仍有效的轮次信号进入 `agent/request-error`。负责恢复的监听器修复状态、返回 `{ kind: 'retry' }`，并停止继续委托。循环会关闭失败轮次，并基于该状态开启一个重试轮次，中间不发布空闲通知；重试不是失败轮次内的另一个步骤。`agent/settled` 报告终态结果；对于需要脱离轮次结算单独报告失败的消费方，`agent/error` 仍作为实时错误通知保留。[重试动作决策](2026-07-27-request-error-retry-action.md)取代了本设计中命令形式的部分。
 
-事件分类体系移除了 `agent/pre-step`、`agent/post-step`、`agent/session-prefix`、`agent/step-result`、`agent/turn-continuation` 和 `agent/turn-stop`。持久的轮次与步骤边界仍由会话事件记录。面向模型的新增内容使用有日志记录的消息通道，请求配置使用 `agent/request`，响应内容按组装后的原样记录，失败请求恢复使用 `agent/request-error` 加 `agent.retry()`，轮次结束时是否继续则使用 `agent/turn-stopping` 加 steering 表达。
+事件分类体系移除了 `agent/pre-step`、`agent/post-step`、`agent/session-prefix`、`agent/step-result`、`agent/turn-continuation` 和 `agent/turn-stop`。持久的轮次与步骤边界仍由会话事件记录。面向模型的新增内容使用有日志记录的消息通道，请求配置使用 `agent/request`，响应内容按组装后的原样记录，失败请求恢复使用 `agent/request-error` 返回动作，轮次结束时是否继续则使用 `agent/turn-stopping` 加 steering 表达。
 
 ## 考虑过的替代方案
 
@@ -35,7 +35,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 **将 dispose 表示为第三种 `AgentStatus`。** 这样会让仍被持有的句柄得到一个终止状态值，但也会重复表达 `agent/disposed` 已经体现的注册表生命周期。当前决策让 `AgentStatus` 只表示活动中 agent 的状态，并将注册生命周期作为独立维度。
 
-**让 `agent/request-error` 返回重试决策。** 返回指令会与现有的 `agent.retry()` 命令重复，还要求循环跨尝试携带策略历史。Waterfall 只需保留有序归属能力：未处理的监听器继续委托，负责处理的监听器完成可等待的修复、调用 `agent.retry()`，然后停止委托。
+**让 `agent/request-error` 返回重试决策。** 这一替代方案已由[重试动作决策](2026-07-27-request-error-retry-action.md)取代；新决策移除了重复命令，并将决策局限于 waterfall 的返回结果。
 
 **将持久的轮次与步骤边界映射为 agent 事件。** 这样会为同一事实向实时消费方提供第二条事件流。当前决策将会话日志保留为真源，仅暴露扩展检查点或持久事件流无法承载的纯实时事实。
 
@@ -45,7 +45,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 插件不再能够改写循环的每个阶段。不再提供仅用于请求的消息前缀、助手消息变换、步骤后检查点、通用的继续执行枚举、通用的终止停止结果或轮次内请求重试。扩展改用剩余的归属明确的通道，而不是重新构造这些阶段。
 
-负责继续执行的插件发布可持久化的 steering，而不是返回未记录到日志中的原因。恢复插件在失败步骤结束后处理错误，并通过 `agent.retry()` 显式安排另一个轮次。这样，每次尝试都会成为完整轮次，同时异步修复和策略归属集中在一个狭窄的 waterfall 边界。
+负责继续执行的插件发布可持久化的 steering，而不是返回未记录到日志中的原因。恢复插件在失败步骤结束后处理错误，并返回显式重试动作。这样，每次尝试都会成为完整轮次，同时异步修复和策略归属集中在一个狭窄的 waterfall 边界。
 
 收件箱生命周期用于补充持久会话日志，而非取代它。`AgentMessageId` 将接受操作与领取或丢弃操作关联起来；轮次编号与步骤编号、消息、工具活动和终止原因仍属于会话事实。
 

.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md
+2026-07-27-request-error-retry-action.md: 3057b9fa28cf203c9374930fe97421918b4c1a6f
+2026-07-27-request-error-retry-action.zh.md: bcb4e592f0c3d86f896e279cf0e3ea400741a1bb

.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.md

@@ -0,0 +1,29 @@
+# Agent Note: Request-error retry action
+
+Status: implemented
+
+English | [中文](2026-07-27-request-error-retry-action.zh.md)
+
+## Problem
+
+Model-request recovery was decided inside `agent/request-error` but communicated through `Agent.retry()`. That public command was valid during one narrow waterfall window and while idle, rejected other running states, and required `ReactLoopAgent` to retain a mutable retry window beside the waterfall result. The recovery plugins were the only production callers, so the wider live-agent capability exposed states and behavior unrelated to their policy decision.
+
+## Decision
+
+`agent/request-error` returns `RequestErrorAction`, whose handling action is `{ kind: 'retry' }`; the default `undefined` keeps the failed turn terminal. A listener that does not own the failure calls `next()`. A listener that owns it performs any awaited repair and returns the retry action without delegating.
+
+The loop reads the action after the waterfall settles, closes the failed turn, and opens one retry turn from durable history. It rechecks the turn signal when consuming the action, so cancellation or disposal during recovery prevents the retry even if a listener returns it afterward. A thrown recovery never produces an action.
+
+`Agent` and `ReactLoopAgent` expose no `retry()` method. Ordinary new work enters through `send()` and its `followup()`, `steer()`, and `inject()` presets; only a handled model-request failure can open a promptless retry turn.
+
+## Alternatives considered
+
+**Keep `Agent.retry()` as the recovery command.** Runtime guards can restrict the command to the request-error window, but the interface still advertises an idle resummon operation with no production consumer and the loop still needs mutable side-channel state to recover a decision already owned by the waterfall.
+
+**Return an explicit terminal action.** `undefined` already represents the waterfall's unhandled default and composes directly through `next()`. A second `{ kind: 'fail' }` value would add no distinct behavior or ownership information.
+
+## Consequences
+
+Recovery ownership, asynchronous repair, and the retry decision share one typed return path. The live-agent interface and concrete loop lose the idle resummon capability and retry-window state. Callers cannot restart arbitrary failed non-request work without submitting a later prompt, while transient and context-overflow policies retain numbered retry turns, durable-history reconstruction, finite private budgets, and cancellation precedence.
+
+Focused agent-loop tests pin retry chaining, terminal fallthrough, recovery failure, and cancellation races. The llm-retry and compact-basic suites pin their policy-owned action returns, and the ACP, goal-session, and plan-mode integrations pin successor-turn adoption.

.agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.zh.md

@@ -0,0 +1,29 @@
+# Agent Note: 请求错误重试动作
+
+Status: implemented
+
+[English](2026-07-27-request-error-retry-action.md) | 中文
+
+## 问题
+
+模型请求恢复由 `agent/request-error` 内部决定，却通过 `Agent.retry()` 传达。这个公开命令只在一个狭窄的 waterfall（瀑布式事件）窗口内和空闲时有效，在其他运行状态下会被拒绝，并要求 `ReactLoopAgent` 在 waterfall 结果旁保留一个可变的重试窗口。恢复插件是仅有的生产调用方，因此更宽泛的活跃 agent（智能体）能力暴露了与其策略决策无关的状态与行为。
+
+## 决策
+
+`agent/request-error` 返回 `RequestErrorAction`，其中负责处理的动作是 `{ kind: 'retry' }`；默认的 `undefined` 会让失败轮次保持终态。不拥有该失败的监听器调用 `next()`。拥有该失败的监听器执行所有需要等待的修复，然后直接返回重试动作而不继续委托。
+
+waterfall 结算后，循环读取该动作，关闭失败轮次，并从持久历史开启一个重试轮次。循环在使用该动作时会再次检查轮次信号，因此即使监听器随后返回重试动作，恢复期间发生的取消或资源释放仍会阻止重试。抛出异常的恢复不会产生动作。
+
+`Agent` 与 `ReactLoopAgent` 均不暴露 `retry()` 方法。普通新工作通过 `send()` 及其 `followup()`、`steer()` 和 `inject()` 预设进入；只有已处理的模型请求失败才能开启没有提示词的重试轮次。
+
+## 曾考虑的替代方案
+
+**保留 `Agent.retry()` 作为恢复命令。** 运行时防护检查可以将该命令限制在请求错误窗口内，但接口仍会暴露一个没有生产消费方的空闲无提示词再运行操作，循环也仍需通过可变的旁路状态恢复已经由 waterfall 决定的结果。
+
+**返回显式终态动作。** `undefined` 已经表示 waterfall 未处理时的默认值，并可直接通过 `next()` 组合。再添加一个 `{ kind: 'fail' }` 值不会提供不同的行为或归属信息。
+
+## 后果
+
+恢复归属、异步修复和重试决策共用一条类型化返回路径。活跃 agent 接口与具体循环不再具有空闲无提示词再运行能力和重试窗口状态。调用方如果不提交后续提示词，就无法重启任意失败的非请求工作；瞬时策略与上下文溢出策略则保留编号重试轮次、从持久历史重建、有限的策略私有预算和取消优先级。
+
+聚焦的 agent-loop 测试固定了重试链、未处理失败保持终态、恢复失败和取消竞态。llm-retry 与 compact-basic 测试套件固定其策略自有的动作返回，而 ACP、goal-session 和 plan-mode 集成测试固定后继轮次承接。