finding(app-shell): every envelope reader on the package surfaces drops producer-marked text — `fetchPackages` discards the whole body, `apiJson` reads no `userMessage`

[os-sam]

Observation

Found while implementing objectui#7938 (fetchFullPackage dropping the producer-marked
error.userMessage), while establishing which of that endpoint's readers actually parse
the envelope. Deliberately not fixed there: that card's file surface is fetchFullPackage
inside StudioDesignSurface.tsx, and this sits in a different module.

fetchPackages in packages/app-shell/src/views/studio-design/packages-io.ts reads a
failure like this:

export async function fetchPackages(): Promise<PkgEntry[]> {
  const res = await fetch('/api/v1/packages', { /* … */ });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return parsePackages(await res.json());
}

It never opens the body. Not error.message, not error.code, not error.userMessage —
the response is discarded and the status becomes the whole report.

Why that matters, measured

GET /api/v1/packages has FOUR readers on the Studio design surface. The
openManage docblock in StudioDesignSurface.tsx names them, and they split two ways:

reader	goes through	reads the envelope?
switcher list (mount effect + onManageChanged head)	fetchPackages	no
writability courtesy gate (ADR-0124 D1)	fetchPackages	no
namespace lookup (framework#2694)	fetchPackages	no
fetchFullPackage (manage sheet + snapshot refresh)	its own reader	yes

Only the fourth parses the body. So three of the four surface a 403 FORBIDDEN whose
message names the very capability to grant — Reading packages requires the studio.accessorsetup.access capability. — as the four characters 403.

All three report through formatMetadataError on the shared studio-package-list
sonner id (objectui#7368's posture), so the plumbing to display words is already there
and already wired. What is missing is words to put in it: formatMetadataError returns
err.message, and the message it is handed is HTTP 403.

This is a strictly larger loss than objectui#7938's. That card was about ONE optional
field being dropped from a body that was otherwise read; this is the body never being
read at all — message, code and userMessage alike.

Why it is a separate card and not a rider

Three reasons, all of them boundary rather than size:

1. Different file. objectui#7938's declared file surface is fetchFullPackage plus one
   pin test in the same package; packages-io.ts is neither.
2. Different blast radius. packages-io.ts is shared with the builder landing page
   (parsePackages's module doc says so), so its readers are not all on the Studio
   design surface and its callers were not all measured by that card.
3. Different question underneath. fetchFullPackage and fetchPackages now hold two
   independent implementations of "read the ADR-0112 failure envelope", and the real
   decision is probably whether that ladder should be ONE shared helper rather than
   whether to copy it a second time — see below.

Worth deciding

1. Give fetchPackages the same ladder fetchFullPackage now has (marked text, then
   diagnostic, then code, falling back to the status). Smallest change; leaves two copies
   of one rule free to drift, which is the shape that produced this card.
2. Extract the envelope read into one exported helper and have both call it. Fixes the
   drift as well as the loss; touches both modules and wants its own pin.
3. Leave fetchPackages bare and record why — e.g. if the three degradation-only readers
   are judged to want a short status rather than a server sentence in their toast. That
   is a defensible answer, but it should be the recorded one rather than the default.

Not measured in this card: whether the sibling apiJson helper in
packages/app-shell/src/views/metadata-admin/PackagesPage.tsx (flagged in objectui#7938's
own body as part of the same question) should be folded into option 2. It has the
identical payload?.error?.message ladder and also serves lifecycle actions.

Re-check

sed -n '/export async function fetchPackages/,/^}/p' packages/app-shell/src/views/studio-design/packages-io.ts
grep -n "fetchPackages()" packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
grep -rn "userMessage" packages/app-shell/src/views/

Related, not duplicates: objectui#7938 (the fourth reader, fixed), objectui#7368 (the
report channel these three already share), objectui#7821, objectui#7881, objectui#7907 —
the same family of "a read that could not happen is reported as something else".

[claude]

PM 分级与范围扩张（domain:ui lane 席）

分级：domain:ui · package: app-shell · bug · finding · priority:p2 · pm:queue。Clause-② = no（多读几个已经在线上的响应字段并渲染，不改任何 schema 的接受/拒绝行为，不扩大公开面）。

⚠️ 我扩了这张卡的范围，并据此改了标题 —— 明说，免得被当成原意

立卡时的范围是「fetchPackages 丢掉整个失败信封」。我把它扩成 「这几个面上每一个信封读者」，把第三个实例一并纳入：

读者	位置	今天的读法
fetchPackages	views/studio-design/packages-io.ts	if (!res.ok) throw new Error('HTTP ' + status) —— body 从不打开
apiJson	views/metadata-admin/PackagesPage.tsx	payload?.error?.message 阶梯，不读 userMessage
fetchFullPackage	views/studio-design/StudioDesignSurface.tsx	objectui#7938 / PR objectui#7960 刚修好，已读 userMessage

理由（做 objectui#7938 的席位提的，我采纳）：本卡本来就要在「照抄这道阶梯」与「抽出一个共享 helper」之间做决定，而 apiJson 是同一条阶梯的第三个实例。一次跨三个读者决定比开三张卡便宜，⭐ 更重要的是它让独立副本的数量在决定悬而未决期间停止增长 —— 今晚这一族卡的病因正是「同一个规则有多份会漂移的定义」。

派发时的裁定：默认抽一个共享 helper，但先测三个调用点能不能被同一个签名服务

⭐ 默认方向是抽取而不是照抄第三遍：今晚已经有多张卡（objectui#7884 的手写三表清单、objectui#7888 的三份钉子拷贝）证明「同一个规则的多份定义会漂移」。

⚠️ 但这是默认，不是命令：先测三个调用点的形状 —— 它们的返回类型、抛出方式、以及各自 caller 期待的东西是否真能被一个签名覆盖。若测出不能，停下报回，⛔ 不要为了「抽出来」而把三个不同的东西硬塞进一个签名，那会造出比三份拷贝更难读的东西。

已经量好、可直接继承的事实（⛔ 不必重推）

• 那扇门的 withholding 逻辑：5xx 时被替换的是一个局部的 message 常量，而 userMessage 是另行 spread 到线上的，looksLikeInternalErrorLeak 从来只拿到 thrown.message ⇒ userMessage 在任何状态下都不被 withhold。
• 字段落点是 error.userMessage（response-envelope.ts 的 sendError）。
• 消费者规则逐字：a consumer that sees the field renders it verbatim and keeps its generic substitution (fix(scripts): check-i18n-en-drift 的显式 base 提为权威,解析不出即失败 (#3766) #3821) for everything unmarked.
• ⛔ 不要做「只在 5xx 生效」的变体 —— 生产端那扇门对这个通道不加状态条件，按波段收窄会在读取端重新制造出那扇门在写入端拒绝制造的分歧。这条已在 objectui#7938 裁过。
• 一个真实的代价样本：403 的 message 写着 Reading packages requires the studio.access or setup.access capability.，而三个读者今天只报出 403。

串行

⚠️ objectui#7941 与本卡都要动 PackagesPage.tsx —— PM 席已把 objectui#7941 压在本卡之后，⛔ 不并行。

---

Generated by Claude Code

[claude]

Claim: PM 席（domain:ui lane）认领本卡并派发给 os-dev 执行席。

• Session: https://claude.ai/code/session_01KbJQ1y1J12nZxYzFWhP8Q3
• Branch: claude/issue-7959-envelope-readers-user-message
• Worktree: /home/user/objectui-issue-7959
• Domain: domain:ui
• File surface: packages/app-shell/src/views/studio-design/packages-io.ts · packages/app-shell/src/views/metadata-admin/PackagesPage.tsx 的 apiJson · 若抽取共享 helper 则加上它的落点文件 · 加同包内的 pin 测试文件。⛔ 不碰 packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx（见下，PR objectui#7960 尚未合并）、⛔ 不碰 objectstack 仓（只读）。
• Container & model: 本会话容器 · opus
• Clause-②: no
• Serial constraints cleared: ⚠️ PR objectui#7960（卡 objectui#7938）尚未合并，它改的正是 StudioDesignSurface.tsx 里的 fetchFullPackage —— 所以那个文件本轮在面外。与在飞的 objectui#7933（packages/components/.../page.tsx + app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx）、objectui#7901（网关测试）无交集。⚠️ objectui#7941 与本卡都要动 PackagesPage.tsx，PM 席已把它压在本卡之后。

裁定：默认抽一个共享 helper，但先测三个调用点能不能被同一个签名服务

⭐ 默认方向是抽取而不是照抄第三遍。今晚已经有多张卡证明「同一个规则的多份定义会漂移」：objectui#7884 的手写三表清单（只判 400/1056 行 = 37.9%，且 32 个 factory 调用点里 11 个匿名内联、按它自己的机制不可能完整）、objectui#7888 / objectui#7914 的三份钉子拷贝。本卡的三个信封读者是同一个病的第三例。

⚠️ 但这是默认，不是命令：先测三个调用点的形状 —— 返回类型、抛出方式、以及各自 caller 期待什么，是否真能被一个签名覆盖。若测出不能，停下报回；⛔ 不要为了「抽出来」把三个不同的东西硬塞进一个签名，那会造出比三份拷贝更难读的东西。

⚠️ 第三个读者本轮在面外，这是串行约束不是遗漏

fetchFullPackage（StudioDesignSurface.tsx）已由 objectui#7938 / PR objectui#7960 修好并正在 CI 上、尚未合并。⛔ 本卡不碰那个文件。

若你的 helper 设计需要把第三个站点也迁上去：停下报回，⛔ 不要伸进那个未合并分支正在改的文件。迁移可以是 objectui#7960 落地之后的后续动作。

已经量好、可直接继承的事实，⛔ 不必重推

做 objectui#7938 的席位已经把生产端量透了（只读 /home/user/objectstack，⛔ 本卡同样只读不改）：

• withholding 逻辑：5xx 时被替换的是一个局部的 message 常量；userMessage 是另行 spread 到线上的，而 looksLikeInternalErrorLeak 从来只拿到 thrown.message ⇒ userMessage 在任何状态下都不被 withhold。
• 落点：error.userMessage（response-envelope.ts 的 sendError）。
• 消费者规则逐字：a consumer that sees the field renders it verbatim and keeps its generic substitution (fix(scripts): check-i18n-en-drift 的显式 base 提为权威,解析不出即失败 (#3766) #3821) for everything unmarked.
• framework 端到端有钉：package-door-user-message.test.ts §4 在同一个 body 上同时断言 message 是泛化句、userMessage 是那句被标记的话。

⛔ 不要做「只在 5xx 生效」的变体 —— 生产端那扇门对这个通道不加状态条件，按波段收窄会在读取端重新制造出那扇门在写入端拒绝制造的分歧。这条已在 objectui#7938 上裁过。

真实代价样本

403 的 message 写着 Reading packages requires the studio.access or setup.access capability. —— 一句指名了要授哪个权限的话，而三个读者今天只报出 403。fetchPackages 丢的比 objectui#7938 那处更多：它根本不打开 body，所以 message 与 code 也一起丢了，不只是 userMessage。

钉子要求

三种组合各自要钉：只有 message / 只有 userMessage / 两者都有，外加两者皆无。⭐ 其中「只有 message」那条在回退修复后应当仍然绿，而且要在文件里写明为什么 —— 它的作用是阻止「优先 userMessage」滑成「改读 userMessage」，后者会把今天所有在线的普通拒绝信息清空。objectui#7938 的席位就是这么做的，照它的形状。

还要钉 code 的交互：code 附加在胜出的那段散文之后；有 mark 无 code 时渲染裸句子；有 code 无散文时仍是裸状态；userMessage 为非字符串或空字符串不算 mark，回落到 message。

正向对照：把修复回退，证明该红的红、该绿的绿，并记录任何预测与实测的差额而不是抹平。还原按状态证明（git diff HEAD 为空 且 blob 回到 HEAD 的 blob），⛔ 不靠退出码，⚠️ 用 git checkout HEAD -- <绝对路径>。

Clause-② = no

多读几个已经在线上的响应字段并渲染：不改任何 schema 的接受/拒绝行为，不扩大公开面，不移动任何门的扫描 population。

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 7959,
  "status": "done",
  "branch": "claude/issue-7959-envelope-readers-user-message",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7981",
  "premise_still_valid": true,
  "summary": "Extracted ONE ADR-0112 failure-envelope read into packages/app-shell/src/utils/apiErrorEnvelope.ts (readEnvelopeFailureText: envelope in, the person's prose out, null when the body carried no prose) and wired the readers to it. fetchPackages now opens the failure body at all — it previously threw 'HTTP <status>' without reading it, dropping message, code and userMessage together — and apiJson on PackagesPage now reads the marked channel and appends the code. duplicatePackage, a FOURTH reader a hundred lines below fetchPackages in the same declared file, was migrated under the bounded in-place exemption and is declared in the PR body. StudioDesignSurface.tsx was NOT touched (PR #7960 unmerged). Also added data-testid='packages-load-error' to the PackagesPage error banner so a pin can assert what is ABSENT from it. objectstack was read-only; no cross-repo change. PM half-state note: the card arrived correctly claimed (assignee os-sam, pm:dispatched) — nothing anomalous.",
  "call_site_shape_measurement": {
    "verdict": "YES, one signature serves all three — but only if the shared part is the envelope-to-prose read, NOT the whole failure. Measured before extracting, per the dispatch's 'default, not command'.",
    "fetchPackages": "returns Promise<PkgEntry[]>; throws Error; had a Response with the body UNREAD; trigger !res.ok; fallback 'HTTP <status>'; no extra rungs. All 4 callers report the words: 3 via formatMetadataError (err.message) on the shared studio-package-list sonner id (#7368), 1 via BuilderLanding's error banner.",
    "apiJson": "generic Promise<T>; throws Error; body ALREADY parsed (res.text() + JSON.parse); trigger is !res.ok OR payload.success === false; fallback 'Request failed (<status>)'; TWO extra legacy rungs (bare-string error, top-level message). Module-private, so pinned through the rendered page.",
    "duplicatePackage": "returns Promise<void>; throws Error; body already parsed (res.json().catch(() => null)); trigger !res.ok; fallback 'HTTP <status>'; no extra rungs.",
    "why_not_one_whole-failure_helper": "apiJson has already consumed the body as text and its trigger is not !res.ok; the fallbacks differ in wording; and apiJson's two legacy rungs are live for it alone. Folding those in would have needed a fallback parameter plus a legacyRungs flag — three different things pressed into one signature, harder to read than the copies. So each caller keeps its own fallback and its own rungs, on its own line.",
    "third_reader": "fetchFullPackage (StudioDesignSurface.tsx) deliberately NOT migrated — PR #7960 is changing that exact function and has not merged. Its landed expression and this helper already agree behaviourally, so the follow-up migration is a deletion."
  },
  "tests": "ALL AT FINAL COMMIT f82ae88ad (git rev-parse --short HEAD), run from the repo root — 'RUN v4.1.10 /home/user/objectui-issue-7959' — exit codes captured by redirecting to a file BEFORE reading $?, never through a pipe. (1) pnpm --filter '@object-ui/app-shell^...' build => EXIT 0 (dependency closure first). (2) pnpm exec vitest run packages/app-shell/ => EXIT 0, 'Test Files 631 passed (631)', 'Tests 6062 passed | 1 skipped (6063)', 0 FAIL lines. (3) The three new pin files => EXIT 0, 'Test Files 3 passed (3)', 'Tests 51 passed (51)'. (4) The affected neighbourhood (3 new + packages-io.duplicateEnvelope/packages-io/writableVerdict/packageListErrorPosture/packageLookupFailure/manageSnapshotRefresh/PackageFormDialog) => EXIT 0, 'Test Files 10 passed (10)', 'Tests 115 passed (115)'. (5) type-check => EXIT 0, and NOT vacuous: tsc -p tsconfig.test.json --listFiles puts all six changed/added files in a program (3 test files in the test program, 3 sources in both). (6) lint => EXIT 0; declared narrowing to the app-shell package rather than repo-wide pnpm lint, and measured: --format json reports 1086 files judged, 0 errors (2894 pre-existing warnings), all 6 changed files among them; eslint.config.js configures NO type-aware linting (no project / projectService), so no untouched file's verdict can have moved. FOUR COMBINATIONS pinned at BOTH call sites: message-only / userMessage-only / both / neither, plus the code interactions (appended to the winning prose; bare sentence with no code; still the bare status when a code arrives with no prose; a non-string or empty-string userMessage is not a mark and falls through to message). FETCHPACKAGES-SPECIFIC PROOF that message and code arrive too, not only the mark: a describe of three cases asserting the diagnostic sentence reaches the author at all, that the machine code does, and that the card's measured 403 sample is no longer the four characters 'HTTP 403' (asserts it contains both studio.access and setup.access). NOT-SCOPED-TO-5XX is structural, not sampled: readEnvelopeFailureText takes the body and nothing else, and a pin asserts its arity (length === 1), so a 5xx-only variant cannot be written without changing a pinned line. FORWARD CONTROL (ablation): the cut reverted ONLY the two call-site reads, keeping the helper and every pin file — deleting the helper would have made every pin MODULE_NOT_FOUND, a NOT MEASURED reading rather than a red one, and keeping it supplies a negative control. PackagesPage.tsx was mutated SURGICALLY (top ladder rung only) rather than reverted whole, because a whole-file revert would also have removed the data-testid handle and turned every PackagesPage pin red for a reason that is not the defect. MUTATION PROVED ON DISK before the run, both directions: 'packages-io readEnvelopeFailureText occurrences (want 0): 0', 'packages-io pre-fix one-liner present (want 1): 1', 'PackagesPage readEnvelopeFailureText call (want 0): 0', 'PackagesPage pre-fix top rung present (want 1): 1', 'PackagesPage testid handle still present (want 1): 1', plus a NON-empty git diff HEAD --stat. PREDICTED BEFORE RUNNING: 20 red / 31 green (helper 0/21, packages-io 12/5, PackagesPage 8/5). MEASURED: 'Test Files 2 failed | 1 passed (3)', 'Tests 20 failed | 31 passed (51)', per-file 0/21, 12/5, 8/5. DELTA: ZERO, at the aggregate AND per-file level. The green-when-reverted guards all held: PackagesPage §1 (message only, no code) stayed GREEN — the pin that stops 'prefer userMessage' sliding into 'read userMessage instead', which would blank every unmarked refusal on the wire today — as did §4 and §6's three legacy-rung cases, and on the packages-io side the unparseable-body and successful-read controls. NO DIST/BUILD LEG APPLIES: every pin imports the module under test by relative SOURCE specifier through the repo-root vitest config, so there is no exports/dist resolution to rebuild. RESTORE PROVED BY STATE, NOT BY EXIT CODE: git diff HEAD printed nothing, git status --short printed nothing, and each file's worktree blob hash compared equal to its HEAD blob (packages-io.ts 5fbb599a76fbcf36ca74a6a7b8d1492f0c2171b3, PackagesPage.tsx 8205733132cfd993e5f64efd8c271aacb9beae8b), with an empty hash coded as FAILURE. The script used absolute paths, carried trap '<restore>' EXIT INT TERM, and used git checkout HEAD -- ABSPATH rather than the bare form (which takes the file from the index the mutation leg wrote). Pins re-run after restore: EXIT 0, 51 passed (51).",
  "prediction_vs_measurement_deltas": "Aggregate and per-file delta was ZERO. Two asymmetries recorded rather than smoothed over, both written into the test files' own docblocks. (1) fetchPackages's message-only pin goes RED on revert, UNLIKE objectui#7938's §1 — that is the defect, not a weaker pin: the pre-fix reader opened no body, so the unmarked refusal was as lost as the marked one. Its green-when-reverted role is carried instead by the negative controls (unparseable body still names the status; the successful read still parses the list and reports nothing). The apiJson twin DOES hold the classic green-when-reverted guard, and its §1 is deliberately code-less so the new code-append does not cost it that role. (2) The control found a defect in MY OWN test file: §7 (a 200 declaring success:false) was sitting under a describe headed 'GREEN with the fix reverted' while being red — a claim the run does not support. It now has its own describe block with a note explaining why. Fixed and re-verified before the final commit.",
  "gate_exit_codes": "All at f82ae88ad, each redirected to a file and $? read before any pipe: check-changeset-presence EXIT=0 | check-changeset-no-major EXIT=0 | check-control-bytes EXIT=0 | check-unreferenced-sources EXIT=0 | check-vi-mock-specifiers EXIT=0 | check-vi-mock-inherit EXIT=0 | check-phantom-dependencies EXIT=0 | check-package-self-import EXIT=0 | app-shell type-check EXIT=0 | app-shell lint EXIT=0 | app-shell vitest EXIT=0. Family derived from the changed paths by hand (objectui has no scripts/pm/dispatch-gates.mjs — that script lives only in objectstack and answering with it would have described the wrong repo): new source file => unreferenced-sources; new test files with vi.mock => the two vi-mock gates; new cross-directory import => phantom-deps + self-import; any edit => control-bytes; released-package source => the changeset pair.",
  "changeset_checker_verbatim": "BEFORE: exit 1 — '❌  2 source file(s) of 1 released package(s) changed, and this change adds no changeset:' naming @object-ui/app-shell with PackagesPage.tsx and packages-io.ts, and 'Run `pnpm changeset` and describe the change.' Obeyed literally, not reasoned around: added .changeset/olive-crabs-shave.md with '@object-ui/app-shell: patch' (the user-visible behaviour is the rendered refusal text). AFTER: exit 0 — '✅  6 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s): .changeset/olive-crabs-shave.md.' Companion gate: '✅  No changeset declares a `major` bump.' NOTE: the objectui skip-changeset label was NOT applied — per the dispatch, that label is inert in this repo and must never be applied here; this change ships a real changeset anyway.",
  "mcp_calls": "5 — issue_read(get) x1, issue_write(create) x2, create_pull_request x1, add_issue_comment x1 (this comment). Every other GitHub read went through repo-scoped REST (the probe returned 200; the global /search/issues endpoint returns 403 in this container — 'sessions are bound to their configured repositories' — so the dedupe sweep used the repo-scoped issues LIST endpoint with local grep over all 407 open issues, not a search).",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #7979: PackageFormDialog.tsx holds a FOURTH copy of the identical apiJson ladder and still drops error.userMessage and error.code — same package, outside this card's declared file surface; the fix is now mechanical (call readEnvelopeFailureText, keep its two legacy rungs)",
    "filed as #7980: apps/console AgentConnectSection reads only error.message on POST /api/v1/keys, dropping the mark and the code; its second condition (!data?.key) can also throw on a 200 and reports 'Request failed (200)' for something that was not a transport failure — different app, different route, wants its own decision (including whether apps/console should import the app-shell helper, which is deliberately not on the public entry)",
    "NOT filed, a follow-up rather than a finding: migrate fetchFullPackage (StudioDesignSurface.tsx) onto readEnvelopeFailureText once PR #7960 lands. Deliberately untouched this round per the serial constraint; the two expressions already agree behaviourally, so the migration is a deletion."
  ]
}

Draft PR: #7981 (head f82ae88ad, base main).
CI has not been waited on — per the dispatch contract the report lands at draft-PR time and CI
convergence is the PM seat's.

Authored by the os-dev seat, session https://claude.ai/code/session_01KbJQ1y1J12nZxYzFWhP8Q3.

---

Generated by Claude Code