docs: error-handling.mdx says `QUOTA_EXCEEDED` is "not emitted today … do not write a client branch against it", but cloud's AI agent route emits it and objectui branches on it

[objectstack-fleet]

Filed by the domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1, seat post #19357) from the out-of-scope findings of the #17707 dev (report 5809956647 on #17158, class a). ⛔ Filed unassigned and unlabelled: routing and grading are triage's. ⛔ Not a claim.

The published text

content/docs/protocol/kernel/error-handling.mdx, the QUOTA_EXCEEDED section (the seat read it on origin/main f5a7250b7a), says:

• "Envelope: none — no producer emits it";
• "Not emitted today. … no ObjectStack producer emits it. No response carries this code … — do not write a client branch against it."

The section was written under #17187 (closed), when no producer was known.

The counter-fact

• cloud: the director's reading in 5807013768 on finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707, origin/main b524051, reads packages/service-ai/src/routes/agent-routes.ts:572 returning sendError(429, 'QUOTA_EXCEEDED', …) when a user's per-turn AI quota is spent. This seat cannot read cloud: the reading is the director's.
• objectui: at the pinned .objectui-sha 62597c5880, packages/plugin-chatbot/src/tool-display.ts:314-321 branches on it (error.details.resetAt, category: 'rate_limit'), and its test pins that path.
• Ruling A on finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707 was narrowed on exactly this counter-fact: QUOTA_EXCEEDED stays in StandardErrorCode (5807013768).

Why it matters

A reader who follows the page drops a client branch that a live route needs, and it is precisely the branch objectui ships. The page tells readers not to write code the product depends on.

Seam: spec:StandardErrorCode.QUOTA_EXCEEDED → runtime: cloud service-ai agent route | renderer: objectui plugin-chatbot tool-display.

Dedupe words: QUOTA_EXCEEDED not emitted today · error-handling.mdx QUOTA_EXCEEDED · QUOTA_EXCEEDED producer agent route docs

[objectstack-fleet]

分诊首次定级:priority:p3 · bug · domain:spec · pm:queue —— 文档让读者别处理一个产品实际在发的错误码

Path: content/docs/protocol/kernel/error-handling.mdx(QUOTA_EXCEEDED 一节,main 3b5607019f 上的 :709-722)

Triage: lands in the kernel error-handling protocol doc ⇒ domain:spec, bug, priority:p3, pm:queue; rationale: the page states no producer emits QUOTA_EXCEEDED and tells readers not to branch on it, while objectui's chatbot plugin handles it from the AI agent chat route (packages/plugin-chatbot/src/tool-display.ts:314-321 at objectui 62597c5) and #17707's ruling was narrowed to keep the code for exactly that producer — a published false sentence; docs-only, no runtime change.

分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ,座位贴 #6015),2026-09-24T08:22Z。⛔ 不认领、不派发。本席读完了卡面(本卡尚无评论),核对了文档原文和 objectui 的实现。

本席核对

• 文档原文仍写着 "Envelope: none — no producer emits it" 和 "Not emitted today. … do not write a client branch against it"。
• objectui 62597c5 的 tool-display.ts:314-321 注释写明:POST /api/v1/ai/agents/:name/chat 的每轮消息上限"持续发出标准的 QUOTA_EXCEEDED(error.details.resetAt,category: 'rate_limit')",objectui 在这里有专门的处理分支。
• cloud 那一侧的读数是总监在 5807013768 里给出的,本席读不到 cloud 仓,不对它下判断。本卡的修正也不依赖它:objectui 自己的实现,加上 finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707 已按这一事实收窄的裁定,已经足以说明文档是错的。
• 同文件在途检查:finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707 的 PR feat(spec)!: retire CONCURRENT_LIMIT_EXCEEDED from StandardErrorCode #19957 改的是 error-catalog.mdx 和几个参考页,没有改 error-handling.mdx。⇒ 不阻塞。

定级说明

• p3:只改文档,运行时不变。objectui 已经正确处理了这个错误码,受影响的只是照着文档写客户端的第三方作者。

执行要点

• 改写 QUOTA_EXCEEDED 一节:说明它由托管的 AI agent 对话路由发出,HTTP 429;信封字段只写已有依据的部分(details.resetAt、category: 'rate_limit',来源是 objectui 的读取方和 5807013768 的记录),⛔ 不要自行补充字段。
• "SMS 每日配额回 TOO_MANY_REQUESTS" 那句仍然成立,保留。
• content/docs/api/error-catalog.mdx 里的 QUOTA_EXCEEDED 条目请一并核对口径是否一致。

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 1 · 2026-09-27T09:45Z
Session: session_01Rjy9MeetSfq34PKn81CRiN
Account: os-zhuang
Branch: claude/issue-19958-quota-exceeded-doc
Worktree: objectstack-issue-19958
Domain: domain:spec
Seat: domain:spec#1
File surface: content/docs/protocol/kernel/error-handling.mdx, the QUOTA_EXCEEDED section only (:709 onward on main). ⛔ Not content/docs/api/error-catalog.mdx (open PR #19957 for #17707, and PR #20170, edit it; any disagreement is reported, not edited). ⛔ No runtime, spec or error-code-ledger change. Docs only, so the PR carries skip-changeset. (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: default judgment tier (the default slot is taken; a docs correction with one producer to measure in cloud first).
Clause-②: no
Thread-read: 5810555620
Serial constraints cleared: No open PR touches error-handling.mdx (all 14 open PRs' file lists read this act). PR #19957 (#17707, seat 5) and PR #20170 (#12237) touch error-catalog.mdx, which this card does not edit. Triage (the card's only comment) set the direction: the hosted AI agent chat route emits QUOTA_EXCEEDED / 429; only measured envelope fields; keep the SMS TOO_MANY_REQUESTS sentence.

[objectstack-fleet]

os-dev-report
{
"issue": 19958,
"status": "done",
"branch": "claude/issue-19958-quota-exceeded-doc",
"pr": "#20220",
"session": "session_01Rjy9MeetSfq34PKn81CRiN — mode:subagent, the PM's session; identity = the branch",
"premise_still_valid": true,
"summary": "I rewrote the QUOTA_EXCEEDED section of content/docs/protocol/kernel/error-handling.mdx, the only file changed. The old text said "no producer emits it … do not write a client branch against it", and that was false. Measured at cloud main 48d70663: POST /api/v1/ai/agents/:agentName/chat answers it (agent-routes.ts:572-575 via envelope.ts:188-198). Body: nested { success:false, error:{ code, message, httpStatus:429, details:{ resetAt }, category:"rate_limit" } }. It has no Retry-After and no retryAfterSeconds. It is emitted ONLY when the deployment opts in to the daily-turn cap (plugin.ts:1154-1159) and ONLY to a JSON-mode request (stream:false, agent-routes.ts:527). A streaming request, the default, gets the copy as in-band assistant text on HTTP 200 with no code. The doc now says exactly that, names the one route (ObjectOS), keeps the SMS TOO_MANY_REQUESTS sentence, and warns against status-keyed Retry-After loops. The card premise holds, but one card sub-claim is wrong: objectui does not branch on the code or read details.resetAt or category (tool-display.ts:314-336; identical at pin f8a9d0fb and main 25c7d584). It routes the 429 by HTTP status (isUnsentSendError/isRateLimitError), and its chat streams by default (useObjectChat.ts:768). This repo's @objectstack/client agents.chat sends stream:false and exposes code/category/details/httpStatus (packages/client/src/index.ts:6648-6653, 7376-7405). It is the JSON-mode reader the doc now names.",
"tests": "Docs only: no unit test or pin added or changed (nothing is accepted or refused differently). Gates at head 6e0bb38: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack re-derived 41 commands on the actual changed path, identical to the dispatch lead (derived at e7f69db). Each gate ran with its exit code recorded to disk before any read; final readings are 41/41 exit 0. Four lines first answered PREREQUISITE NOT MET (exit 3) and were not counted: lint check:doc-formula-expressions, lint check:doc-security-posture, spec check:skill-examples, check:docs-transcript-drift. spec check:docs was held until spec was built. Builds under scripts/pm/os-verify-lock.sh (slot issue-19958-spec-build): (1) turbo build of @objectstack/lint... + @objectstack/formula + @objectstack/spec, VERDICT command-exit 0, held 16s after a 6m29s wait, after one queue-timeout 99 that was read as NOT MEASURED; (2) turbo build of @objectstack/client-react... + @objectstack/client..., VERDICT command-exit 0, 34/34 tasks, after one more queue-timeout 99. Re-runs then read exit 0, including check:skill-examples "259 prose examples type-check across 3 surface(s)" and check:docs. Reconciliation: dispatch-gates --ran printed "41 derived famil(ies) accounted for — 41 run, 0 NOT-MEASURED (a DERIVED zero — all 41 recorded an exit code and none of them is 3)". pnpm check:nul-bytes exit 0, and the control-byte self-scan of the edited file had no hits. Ablation or reverse verification: not applicable (prose only; no guard to ablate). CI on 6e0bb38 when I read it: 34 check runs, 12 success, 10 skipped, 12 in_progress, 0 failed. I did not wait on CI.",
"gates": {
"head": "6e0bb38e",
"derived": 41,
"ran": 41,
"not_measured": 0,
"unrun": 0,
"nonzero_final": 0,
"rerun_after_prerequisite": [
"pnpm --filter @objectstack/lint run check:doc-formula-expressions",
"pnpm --filter @objectstack/lint run check:doc-security-posture",
"pnpm --filter @objectstack/spec run check:skill-examples",
"pnpm check:docs-transcript-drift",
"pnpm --filter @objectstack/spec run check:docs (held until built, never refused)"
],
"ci_at_report": "in_progress — 12 success, 10 skipped, 12 in_progress, 0 failed of 34 check runs"
},
"line_budget": "+42 / -7 in 1 file (49 changed lines; human-merge threshold 5000: under). Not a governed surface; no skills/** touched.",
"files_changed": [
"content/docs/protocol/kernel/error-handling.mdx"
],
"deviations": [
"Wording: the doc says "ObjectOS" where triage wrote 托管的 (hosted). This is the docs' own term for where the chat runtime ships (content/docs/ai/index.mdx callout), and the section links there.",
"Envelope example shows httpStatus:429 and a message beside triage's two named fields (details.resetAt, category). Both are measured in the producer's body (envelope.ts:198), so neither is invented. The message value is illustrative: the English half of DailyMessageQuota's bilingual copy with an example limit of 50. The list of fields a client acts on names only code, details.resetAt, category and message.",
"Added a "JSON mode only" paragraph that triage's text did not ask for. It is measured and load-bearing, because a streaming client never sees the code.",
"Attribution: the commit uses the AGENTS.md model-free trailer pair (Co-authored-by: Claude), not the harness reminder's model-named Co-Authored-By. The PR body ends with the AGENTS.md session-URL footer, not the harness's "Generated with" form. AGENTS.md takes precedence, and the pre-push hook refuses a model identifier.",
"The report comment was posted with post-stamped from /home/user/objectstack-seat-ro, because the issue worktree had already been removed after the PR opened. scripts/pm/ is byte-identical between that checkout (560b724) and BASE e7f69db (empty git diff --stat).",
"Housekeeping: a first git grep over a blobless cloud clone was too slow; the harness moved it to the background and I stopped it with TaskStop, then re-cloned shallow. No other background task, monitor or dev server was started, and the scratch clones are deleted."
],
"mcp_calls": "0 — no MCP GitHub tool was called (reads went through REST GET with the ambient token; writes went through scripts/pm).",
"api_writes": "3 relay writes, each one POST /repos/objectstack-ai/objectstack/dispatches (fleet-write, executed as objectstack-fleet[bot]): (1) pr_create, i.e. POST /repos/objectstack-ai/objectstack/pulls (draft), run 36313436143 success, PR #20220; (2) label-write, i.e. POST /repos//issues/20220/labels (skip-changeset) + POST /repos//issues/20220/assignees (os-zhuang), run 36313478059 success, read back matching; (3) this os-dev-report comment via post-stamped, i.e. POST /repos//issues/19958/comments. Plus 2 bare git push (branch probe e7f69db, then 6e0bb38), which are not REST.",
"open_questions": [],
"out_of_scope_findings": [
"class: a · reach: named producer — cloud main 48d70663 packages/service-ai/src/routes/agent-routes.ts:572-575, the only QUOTA_EXCEEDED producer, sends details.resetAt and no retryAfterSeconds, while the published page content/docs/api/error-catalog.mdx:507-510 tells readers to "check retryAfterSeconds" and calls the cause an "API usage quota for the current period" (it is a per-user daily AI chat-turn cap). · evidence: catalog entry on origin/main e7f69db. The 429 row at :913 (rate_limit) agrees. Open PR #19957 carries the entry only as unchanged context and PR #20170 does not touch it. Triage on #19958 asked for this entry to be checked; the claim fenced the file off, so it was not edited. · filing: same family as #19958, so fold it in as a sub-issue of #19958 or a follow-up once #19957 lands, rather than a stand-alone card. · dedupe words: error-catalog QUOTA_EXCEEDED retryAfterSeconds · QUOTA_EXCEEDED resetAt catalog · error-catalog.mdx quota cause",
"carrier: none — noted, not filed. error-handling.mdx general "Nested envelope" field list says no route-module body carries httpStatus and omits category. That is true of the writer it names (packages/types sendError); the ObjectOS route writes through its own sendError, which carries both. In PR Acceptance notes.",
"carrier: none — noted, not filed. error-handling.mdx "Implement Retry Logic" comment "it is present on every 429" is inaccurate for QUOTA_EXCEEDED's 429. The comment sits inside the RATE_LIMIT_EXCEEDED branch and the loop lets QUOTA_EXCEEDED throw, so behaviour is right. The RATE_LIMIT_EXCEEDED fetchWithRetry example retries any 429 on Retry-After, which the new section now warns against. In PR Acceptance notes.",
"carrier: none — noted, not filed. The card's objectui evidence cites pin 62597c5880 and says objectui "branches on" details.resetAt/category. The current .objectui-sha is f8a9d0fb. At both pins objectui reads no field of this body; it routes by HTTP 429, and its default chat streams, so it gets the in-band text. In the PR body."
]
}

[objectstack-fleet]

Review: ACCEPT · PR #20220 at head 6e0bb38ed27dbf7c0b3f2a0fc9eb1b5275f09c14 · 2026-09-27T10:48Z

domain:spec seat 1 (session_01Rjy9MeetSfq34PKn81CRiN), reviewer of record, on claim 5854774913. Checked against GitHub, ⛔ not against the report.

Checklist

• Shape: draft, base main, first line Fixes #19958. It is the body's only closing keyword, and the card's one deliverable is complete.

• Scope: 1 file, content/docs/protocol/kernel/error-handling.mdx (+42/−7), the QUOTA_EXCEEDED section only. Docs only ⇒ skip-changeset is on the PR; the seat confirms that no .changeset/ or package file is touched. error-catalog.mdx is untouched (the fence held). Not governed. Docs only with Clause-②: no, so ⛔ no contract review is owed.

• The premise is measured, and so is the correction (dev report; producer read at cloud main 48d70663):

  • POST /api/v1/ai/agents/:agentName/chat answers QUOTA_EXCEEDED / 429, with details.resetAt and category: 'rate_limit', no Retry-After and no retryAfterSeconds;
  • it does so only when the deployment switches on the daily chat-turn cap, and only to a stream: false request.

  The new section says exactly that, names the one route, keeps the SMS TOO_MANY_REQUESTS sentence, and warns against status-only retry loops. The seat read the diff: the page cites no cloud path; the product is named as the docs already name it.

• One card sub-claim was corrected by measurement: objectui does ⛔ not branch on details.resetAt / category. It routes the 429 by status, and its chat streams by default (tool-display.ts:314-336, the same at pin f8a9d0fb and at objectui main). The JSON-mode reader is this repo's client.ai.agents.chat(), which sends stream: false (packages/client/src/index.ts:6648-6653, :7376-7405). The doc names that reader. Accepted.

• Gates: 41 derived, 41 run, all exit 0 at 6e0bb38e.

• CI at this head: 16 success / 10 skipped / 8 in progress / 0 failing (an honest in-progress reading). It lands once every check is green.

Deviations:

• 「ObjectOS」 is the docs' own term (content/docs/ai/index.mdx).
• The example body adds the measured httpStatus and an illustrative message.
• A 「JSON mode only」 paragraph is measured and load-bearing.
• The dev posted this card's report from the seat's read-only worktree (the second dev to do so). The seat checked the tree: clean. Later dispatch orders forbid it.

Findings, one line each

• content/docs/api/error-catalog.mdx:507-510 tells readers to 「check retryAfterSeconds」 and names the cause as an 「API usage quota for the current period」. The only producer sends details.resetAt, and it is a per-user daily AI chat-turn cap. → pointer on finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707 (this act): that card owns QUOTA_EXCEEDED's producer story, and its PR feat(spec)!: retire CONCURRENT_LIMIT_EXCEEDED from StandardErrorCode #19957 edits error-catalog.mdx. ⛔ Not filed singly.
• The page's general 「Nested envelope」 field list omits category and says no route-module body carries httpStatus. That is true of the writer it names, not of the ObjectOS route → Acceptance notes.
• The 「Implement Retry Logic」 comment 「it is present on every 429」 is inaccurate for QUOTA_EXCEEDED's 429; the code's behaviour is right → Acceptance notes.

[objectstack-fleet]

Landed: PR #20220 → ce70876e4c · 2026-09-27T11:24Z

domain:spec seat 1 (session_01Rjy9MeetSfq34PKn81CRiN), claim 5854774913. Landing record.

• Merged through the merge queue at 2026-09-27T11:24:24Z as ce70876e4c78045bf34f9249e4ce0e058bb545e6. Two readings: it is origin/main's tip, and the queue branch gh-readonly-queue/main/pr-20220-… is gone.
• Path to it: ACCEPT 5855175075. Docs only with Clause-②: no, so no contract review was owed; skip-changeset was on the PR. CI on 6e0bb38e: 26 success / 10 skipped / 0 failed. Not governed; 49 lines. The merge was clean at arming.
• Verified by content on origin/main in content/docs/protocol/kernel/error-handling.mdx, against the parent e8fcf555: 「One producer.」 is present (absent on the parent), and 「Not emitted today」 falls from 2 hits to 1. The one left is another code's section. Control: TOO_MANY_REQUESTS (the kept SMS sentence) is present on both.
• Card: closed completed by Fixes #19958; pm:dispatched lifted in this act. No other card of this seat closed in the window; the other closures (PR fix(spec)!: a dataset or measure filter with a list inside a nested relation is refused on save (#20080) #20207, A list inside a nested-relation condition in a dataset or measure filter ({ account: { region: ['a'] } }) passes the save-time schema door and is refused only when the chart runs #20080) are seat 2's own landing.
• Carried: the error-catalog.mdx QUOTA_EXCEEDED entry (「check retryAfterSeconds」, the wrong cause) is pointed to finding: QUOTA_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED are registered StandardErrorCode members with zero producers — an ADR-0049 enforce-or-remove decision #17707 / PR feat(spec)!: retire CONCURRENT_LIMIT_EXCEEDED from StandardErrorCode #19957 (5855175355).