bug: Claude Code session-limit 429 被判为 TRANSIENT 却无人重试 — 不透出 reset 时间、丢弃子代理已完成成果，并被无上限并行扇出放大

[johnsonice]

What happened?

用 Claude Code 作为 provider 时频繁出现 "rate limit" 打断 agent turn。用户去查 Claude Code 的 usage 页面，完全没有到限额 —— 因此以为是 NarraNexus 误报。

实测从本地 DB 挖出原始错误（events.event_log），429 是真的，但它不是用户以为的那种 rate limit：

due to an API error: You've hit your session limit · resets 3:20am (America/New_York)
(error type rate_limit, HTTP 429, request id req_011CeYACYtmED5ZgqkdBEwvY,
 model sent to the API: claude-opus-5)

Everything below is PARTIAL output recovered from the agent before ...

这是 Claude Code 的 5 小时 session 额度，Anthropic 用 error type rate_limit / HTTP 429 的外壳返回 —— 和 usage 页面展示的不是同一个计量，所以用户查不到。NarraNexus 没有误报。

真正的缺陷在于：这个错误进来之后，平台既不重试、也不告诉用户发生了什么、还丢掉了已完成的工作。同一次 turn 里有 3 个不同 request id 连续撞上（多个研究子代理并发），用户看到的只是 agent 用自然语言转述一句"被 API 速率限制打断了"。

仓库核对（dev @ c776e32a / v1.15.0）：

1. 归类为 TRANSIENT，然后没有任何东西重试它

loop/circuit_breaker.py:99-104 的 _TRANSIENT_MARKERS 含 "rate limit" / "429" → classify_agent_error（:131-176）返回 ErrorCategory.TRANSIENT。
TRANSIENT ∉ PAUSING_CATEGORIES（schema/agent_circuit_breaker_schema.py:67-69 只含 AUTH/QUOTA），所以不会熔断 —— 这点是对的，与 #117 无关。
但 grep 全仓 TRANSIENT 的消费方只有 wechat_trigger / model_sync / logging/_ship.py，agent turn 路径一个都没有。也就是说：系统明确判定"这是暂时性的、重试可恢复"，然后从不重试，turn 直接以残缺输出结束。

2. 错误里带着 reset 时间，但被丢弃

原文含机器可读的 resets 3:20am (America/New_York)。平台没有解析它，因此无法做退避重试、无法排程恢复、也无法在 UI 上告诉用户"几点恢复"。

3. failure.py 对 session limit 零识别 → 用户拿不到可操作指引

agent_framework/llm/failure.py 的自助错误分类（SELF_SERVICEABLE_REASON_*）里 没有 rate_limit / session limit 这一类（grep session limit|rate_limit|429|resets = 0 命中）。所以 classify_self_serviceable 返回 None，用户得不到类似 "已用完 5 小时 session 额度，3:20am 恢复" 的明确提示 —— 只能看 agent 的自然语言转述，然后去 usage 页面白查一场。

对比：同文件对 insufficient_balance / free_tier_exhausted / context_window / model_not_found 都有精确 marker + 可操作文案。session limit 是 Claude Code provider 下最常撞的一种，反而缺席。

4. 子代理扇出无并发上限 —— 这是放大器

adapters/claude/sdk.py:876-925：permission_mode="bypassPermissions"、max_turns=None、只在条件成立时禁 WebSearch，没有 agents= 配置。
grep semaphore|max_concurrent|concurrency 在整个 adapters/claude/ + loop/ 路径下 零命中；grep 429|backoff|RateLimit 在 adapters/claude/ 下也只有 stale-resume 的 cold retry（sdk.py:1293-1363，明确限定"至多一次、且只在有输出之前"，不针对 429）。

结果：模型一次 turn 里想扇出多少研究子代理就扇出多少，每个都是独立的 API 流、都在烧同一个 5 小时 session 预算，而且用的是 claude-opus-5。窗口被一次并行调研打穿，正是用户"明明没怎么用却频繁撞限"的体感来源。

5. 已完成的部分成果被丢弃

Claude Code 自己回收了部分输出（错误文本里的 Everything below is PARTIAL output recovered from the agent before ...），但 NarraNexus 既没有把这一轮标记为 incomplete，也没有提供 resume/续跑入口。多个子代理已经交付的中间成果就这么没了。

Steps to reproduce

1. dev 分支（本次为 c776e32a / v1.15.0），provider 选 Claude Code，模型 claude-opus-5
2. 给 agent 一个需要大量并行调研的任务，让它扇出多个研究子代理
3. 跑几轮，直到 Anthropic 5 小时 session 额度耗尽
4. 观察：agent 用自然语言说"被 API 速率限制打断了"，turn 以残缺输出结束；无重试、无恢复时间提示、无续跑入口
5. 去 Claude Code usage 页面查 —— 看不到任何超限（因为那是另一套计量）

NarraNexus version

v1.15.0（dev @ c776e32a）

How are you running NarraNexus?

本地源码 / bash run.sh（macOS）

Logs / screenshots

原始错误取自本地 ~/.narranexus/nexus.db 的 events.event_log（event 时间 2026-08-30 02:21:49，agent_00f08eaaef23），同一 turn 内三条：

... due to an API error: You've hit your session limit · resets 3:20am (America/New_York)
    (error type rate_limit, HTTP 429, request id req_011CeYACYtmED5ZgqkdBEwvY, model sent to the API: claude-opus-5)
... (同上, request id req_011CeYACZAe7JfiKbEFyypDp)
... (同上, request id req_011CeYACaqr4T6S5f6BGbRVi)

用户侧看到的（agent 自然语言转述，非平台提示）：

这轮调研我进行了大量并行研究，但中途被 API 速率限制打断了——多个研究代理提交了部分成果后就断了。

Anything else?

建议修复（按性价比排序）：

1. 给 session-limit 429 一个专属分类 + 可操作文案。 在 failure.py 加 SELF_SERVICEABLE_REASON_SESSION_LIMIT，marker 用 "session limit"（配合 error type rate_limit），文案直接把错误里的 reset 时间透出来："Claude Code 5 小时 session 额度已用完， 恢复"。这样用户不会再去 usage 页面白查。
   注意别撞 classify_agent_error 的既有排序陷阱 —— 该函数 docstring 明确说 QUOTA 分支刻意不看 "429"/"rate limit"，新增 reason 要保持这条不变（session limit 不是余额问题，remedy 是等待而非充值）。

2. 让 TRANSIENT 在 agent turn 路径上真的有人管。 现在"判定为可重试"和"实际重试"之间是断的。至少解析 reset 时间做一次排程续跑；铁律 weekly #14 下不要做无上限轮询，按 reset 时间单次唤醒即可。

3. 给子代理扇出加并发上限。 这是根治"窗口被一次并行调研打穿"的地方。可以是固定上限，也可以按 provider 区分（Claude Code 的 session 预算比 API key 计费更容易打穿）。

4. 保住残缺成果。 Claude Code 已经把 partial output 交回来了，把这一轮标记为 incomplete 并给个续跑入口，别让多个子代理的中间成果白跑。

关联：

• bug: Agent auth 熔断后永久卡死 — 本地重新登录 + 整服务重启都无法恢复（PAUSED 状态持久化、无 half-open/自愈，record_success 被 skip-gate 死锁，只剩瞬时 banner 的手动 Resume） #117（auth 熔断永久卡死）—— 不是同一条路径，已核对：session-limit 429 落 TRANSIENT，不进 PAUSING_CATEGORIES，不会导致 bug: Agent auth 熔断后永久卡死 — 本地重新登录 + 整服务重启都无法恢复（PAUSED 状态持久化、无 half-open/自愈，record_success 被 skip-gate 死锁，只剩瞬时 banner 的手动 Resume） #117 的持久 PAUSED。这里列出来是为了让 triage 时不必重复核对。
• bug: 多 agent 并行任务缺 fan-out→join→resume:SDK 异步后台任务(TaskCreate/TaskList)对模型可达但未接线、结果孤儿化;平台真正的并行 substrate 是 JobModule(工具面错配),且 agent 常只"口头"开后台 agent 而工具调用未落地 #74（并行子代理 fan-out 无 join/resume）—— 同一个"并行扇出缺治理"主题，本 issue 补上资源侧（额度被打穿）的角度，bug: 多 agent 并行任务缺 fan-out→join→resume:SDK 异步后台任务(TaskCreate/TaskList)对模型可达但未接线、结果孤儿化;平台真正的并行 substrate 是 JobModule(工具面错配),且 agent 常只"口头"开后台 agent 而工具调用未落地 #74 是结果侧（成果无法回收）。两者的建议 3/4 可以一起做。

[johnsonice]

更正与补强：session limit 是平台自己在 23 分钟内烧掉的，不是用户正常用量撞线

原报告把 "You've hit your session limit" 呈现为一次普通的额度耗尽，并把并行扇出列为"放大器"。用户质疑"我自己的 Claude Code usage 完全没到 5 小时限制"——这个质疑是对的，重新取证后结论要倒过来：额度不是用户用掉的，是单个 turn 在 23 分钟内烧光的。

硬数据（本地 ~/.narranexus/nexus.db，evt_836106f32e934ac0）

字段	值
started_at	2026-08-30T02:21:49Z（22:21 EDT）
finished_at	2026-08-30T02:44:53Z（22:44 EDT）
时长	23 分钟
tool_call_count	1465
模型	claude-opus-5（provider 配置为 bare alias opus）
同 turn 内 429 次数	7（7 个不同 request id，全部记于 02:44:53）
state	completed（注意：不是 failed）

对照同库 event 的 tool_call_count 分布（近 30 天，n=223）：中位数 9，均值 22，历史第二高 705。这一条 1465 = 中位数的 160 倍。

时间线反推证明是自伤

错误文本给出 resets 3:20am (America/New_York)。5 小时窗口反推 ⇒ 该 session 起点约 22:20 EDT。而 turn 的 started_at 正是 22:21 EDT。

即：session 窗口几乎与这个 turn 同时开始，并在 23 分钟内被同一个 turn 耗尽。 用户此前的日常用量与这次耗尽无关——所以他去查 usage「完全没到限制」是如实的，不是看错了地方。

这修正了原报告的两处

1. 归因：原文暗示用户额度本就快满、并行只是压垮的最后一根稻草。实际是单 turn 独立打穿，用户日常用量不是成因。
2. "频繁"的来源：本地全库只有 2 个 event 含 session limit（08-28 一次、08-30 七次）。用户体感的"频繁"来自一个 turn 内连撞 7 次把整轮调研毁掉，而非高频率发生。（用户截图那条的原文在本地库零命中，应来自另一部署——cloud / Manyfold——同类问题在那边也存在。）

原报告仍然成立的部分：_TRANSIENT_MARKERS 归类 TRANSIENT 但 agent turn 路径零重试、reset 时间被丢弃、failure.py 无 session-limit reason、partial output 无续跑入口、adapters/claude/ 全路径 grep semaphore|max_concurrent|concurrency 零命中。

另一处值得注意：turn 被标为 completed

烧光额度、7 个子代理被 429 截断、大量成果丢失——这一轮在 DB 里的 state 仍是 completed，error_message 为空。也就是说平台自身的可观测性里，这次事故不存在。任何基于 state/error_message 的告警或统计都看不到它。

修复建议修订（遵守铁律 #14 / #15）

原建议里"给子代理扇出加并发上限"需要澄清定位，另两条按铁律调整：

1. 并发背压（非终止）：对子代理扇出做串行化/限流，agent 该做的工作一件不少、只是不同时打。这是 backpressure，不是 weekly #14 禁止的 hard ceiling——不 force-stop、不砍迭代。
2. 诊断指标 + 告警（weekly #14 明确允许的路子）：一个 turn 的 tool_call / token 消耗偏离基线 N 倍时告警而不阻断。本例 160× 中位数，任何合理阈值都会亮灯。
3. turn 结果如实标记：这种"额度打穿 + 子代理被截断 + 成果丢失"的轮次不应记为 completed。至少写入 error_message 或加 incomplete 标记，否则事故在自家可观测性里是隐形的。
4. 原 1/2/4 条（SESSION_LIMIT reason + 透出 reset 时间、TRANSIENT 在 turn 路径真有人管、保住 partial output）不变。

不建议由平台强制换模型（铁律 #15：不干预用户的 LLM 选择）。用户侧自愿的缓解手段（限制并行度、非关键调研用更省的模型）属于用户自己的选择，不应写成平台策略。

[johnsonice]

第二次更正：账号并未被限流——"session limit · resets 3:20am" 的说法与事实不符

用户坚持"我自己的 Claude Code usage 完全没到 rate limit"。第一次更正我仍然假定额度确实被烧光（只是烧的人是平台）。再次取证后，这个假定也是错的。

决定性反证：宣称锁到 3:20am，35 分钟后同账号正常跑

时间 (UTC / EDT)	事件
02:21:49 / 22:21	evt_836106f32e934ac0 开始
02:44:53 / 22:44	结束；7 次 hit your session limit · resets 3:20am，7 个不同 request id
03:19 / 23:19	另一个 run 正常 completed，零 429（距宣称的解锁时间还有 4 小时）

sqlite> SELECT created_at, state,
        CASE WHEN event_log LIKE '%hit your session limit%' THEN 'YES' ELSE 'no' END
        FROM events WHERE created_at > '2026-08-30 02:44';
2026-08-30 03:19 | completed | no

若账号真的耗尽 5 小时窗口并锁到 3:20am，这次 03:19 的 run 不可能成功。 结论：这不是 5 小时 session 额度耗尽，用户的 usage 页面显示正常是如实的。

那 429 到底是什么

同一 turn 内 7 个不同 request id 在同一毫秒级时间点（全部记于 02:44:53.0144xx）撞上 429 —— 这是 并发突发被限流（7+ 条 Opus 流同时在跑），持续时间以秒/分钟计，不是 5 小时锁定。

Claude Code 把这类 429 用 "You've hit your session limit · resets <time>" 的文案渲染出来，<time> 是按窗口推算的投影值，不代表账号真的被锁到那一刻。平台和用户都被这个文案误导了——这也是原报告和第一次更正连续判断失误的原因。

凭证事实（补充，供 triage 参考）

出事 turn 的日志：

Provider config: model=opus, base_url=(official), auth_type=oauth_token, ...
subprocess provider (effective): base_url=(official), auth=none,
                                 config_dir=/Users/huang/.nexusagent/claude_config

provider 配置为 oauth_token，但实际注入子进程的 auth=none —— ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 都没设进去（sdk.py:861 的三元判定）。CLI 因此回落到 CLAUDE_CONFIG_DIR 的凭证；该目录无 .credentials.json，实际走 macOS Keychain 的命名空间条目。

比对（只比哈希，不涉明文）：

	用户自己的 claude	NarraNexus
Keychain svce	Claude Code-credentials	Claude Code-credentials-050b8eac
subscriptionType	max	max
rateLimitTier	default_claude_max_20x	default_claude_max_20x
blob sha256[:16]	19119602b0f71aa3	278406ceff60d102

同账号同档位，但是两份不同的 refresh token / 两条独立登录会话。（另注：Keychain 里共 25 个 Claude Code-credentials-* 命名空间条目，其余 24 个是 MCP OAuth，与此无关，但隔离 config dir 每次都新建条目这件事本身值得关注。）

修订后的缺陷清单

原报告 §1/§2/§3/§5 与第一次更正的"turn 被标 completed"仍然成立。§4 的定性要改，且新增一条：

• 并行扇出打穿 5 小时额度 → 并行扇出触发瞬时并发限流。 不是额度问题，是突发并发。adapters/claude/ + loop/ 全路径 grep semaphore|max_concurrent|concurrency 零命中，一个 turn 可以同时开任意多条 Opus 流。该 turn 23 分钟内 1465 次工具调用（同库近 30 天中位数 9、均值 22、历史第二高 705 —— 160× 中位数）。
• 新增：一次可自愈的瞬时限流，摧毁了一个 23 分钟、1465 次工具调用的 turn。 这是本 issue 最重的伤害点。429 在 adapters/claude/ 无任何退避重试（sdk.py:1293-1363 的 cold retry 只针对 stale-resume，且限定"至多一次、仅在无输出前"），7 个子代理的已完成成果直接丢弃。35 分钟后同账号即可正常工作——只要有退避重试，这一轮本可以自愈，不该有任何损失。

修复优先级相应调整：退避重试（第 2 条）从"锦上添花"升为最高优先级——它单独就能消除本次事故的全部损失；并发背压（第 1 条）次之，用于降低触发频率。透出 reset 时间一条需谨慎：该时间是投影值、并不可靠，直接展示给用户会复现同一误导。