From a4da0f40d5e4ac11990ee0f6485f39ae2def66aa Mon Sep 17 00:00:00 2001
From: pku-xht <xht@deepseek.com>
Date: Wed, 19 Aug 2026 14:23:54 +0800
Subject: [PATCH 01/34] feat(web): preserve near-full cache-hit precision

---
 ...9-high-cache-hit-decimal-display.i18n.yaml |   6 +
 ...26-08-19-high-cache-hit-decimal-display.md |  50 ++++++
 ...08-19-high-cache-hit-decimal-display.zh.md |  50 ++++++
 apps/web/tests/lifecycle-chrome.e2e.ts        |   8 +-
 .../lifecycle-chrome/reloaded.expected.md     |   4 +-
 .../lifecycle-chrome/replay.override.json     | 153 ++++++++++++++++++
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../src/client/chat/StatsLine.tsx             |  32 +++-
 .../tests/chat-stats.client.spec.tsx          |  33 +++-
 11 files changed, 325 insertions(+), 19 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
 create mode 100644 apps/web/tests/snapshots/lifecycle-chrome/replay.override.json

diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml
new file mode 100644
index 0000000000..b95a27e700
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.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/feature/2026-08-19-high-cache-hit-decimal-display.md
+2026-08-19-high-cache-hit-decimal-display.md: 29e0ebc11ae690b918c7e9364f29635de1e50f2a
+2026-08-19-high-cache-hit-decimal-display.zh.md: 28cd99a4c321cc4da0ce03142e2fbf438539b0ff
diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
new file mode 100644
index 0000000000..29e0ebc11a
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
@@ -0,0 +1,50 @@
+# Agent Note: High cache-hit decimal display
+
+Status: implemented
+
+English | [中文](2026-08-19-high-cache-hit-decimal-display.zh.md)
+
+## Problem
+
+The Web conversation stats line rounded every non-empty cache-hit ratio to an integer. Once the actual ratio passed 99%, the display hid further progress, and a ratio of at least 99.5% appeared as 100% even while uncached input or cache writes remained.
+
+Users therefore could not distinguish a nearly complete cache hit from a true full hit.
+
+## Decision
+
+`StatsLine` continues to derive the ratio from the whole-session `tokenUsage` projection owned by `@deepseek-ai/dsh-token-meter`; the projection remains the only owner of the uncached-input, cache-read, cache-write, and output counts ([projection decision](../architecture/2026-07-29-projected-token-usage-and-request-context.md)). The presentation layer changes only the text inserted into the existing `stats.cacheHit` locale template.
+
+| Actual ratio | Display |
+|---|---|
+| No billed input | Cache-hit group omitted |
+| Integer rounding is below 100% | Rounded integer |
+| Non-full ratio whose current rounding is 100% | Minimum decimal precision whose rounded result is below 100% |
+| 100% | `100%` |
+
+Every non-empty ratio starts at zero decimal places. A non-full ratio increases precision one place at a time only while rounding would produce 100%, so `99.1%` and `99.49%` remain `99%`, while `99.5%`, `99.95%`, and `99.995%` retain one, two, and three decimal places respectively. `StatsLine` scales and rounds the integer token counts with `bigint`, which avoids floating-point formatting limits and imposes no precision cap or substitute label. A full hit does not carry a redundant decimal. The same derived string feeds the inline row and its overflow tooltip.
+
+## Ownership and lifecycle
+
+Token-meter continues to fold usage from the complete durable session log. `StatsLine` performs a synchronous display derivation whenever the standard projection value changes. It introduces no setting, stored percentage, event, wire field, client state, or recovery path.
+
+Live updates, reload replay, and reconnect recovery all restore the same `tokenUsage` counts and run the same display function. A missing projection still omits every token group, and a zero input denominator still omits only the cache-hit group.
+
+## Verification
+
+The component spec pins the zero denominator, ordinary integer rounding, each precision boundary through three decimal places, a near-full cumulative sample that needs fourteen decimal places, the true `100%` result, both locales, and equality between inline and tooltip values. The assembled `lifecycle-chrome` replay sidecar selects `9,950 / 10,000 = 99.5%` as a deterministic ratio that integer rounding would misreport as 100% while the base session fixture remains recordable; the live assertion and post-reload browser snapshot both display `99.5%` without another model call.
+
+## Alternatives considered
+
+**Keep integer rounding for every ratio.** Rejected because it hides all movement above 99% and still reports some non-full hits as 100%.
+
+**Truncate the high band to one decimal.** Rejected because `99.95%`, `99.995%`, and still closer ratios all collapse to `99.9%` instead of retaining the minimum precision that distinguishes them from a full hit.
+
+**Cap precision and use a substitute such as `<100%`.** Rejected because the exact cumulative counts can produce the required numeric result, and a cap would make display behavior depend on an arbitrary presentation limit.
+
+**Show one decimal at every ratio.** Rejected because the additional low-band motion adds noise and changes the established display where integer precision is sufficient.
+
+**Persist a display percentage in token-meter.** Rejected because the projection already carries the exact counts, while presentation precision belongs to the Web stats line. A second stored value would duplicate derivable state and expand replay and wire responsibilities.
+
+## Consequences
+
+High cache-hit sessions remain visually stable until integer rounding would falsely report a full hit, then expose only the decimal places needed to preserve that distinction. Extremely close non-full ratios can therefore produce long decimal strings; this is the accepted cost of having no arbitrary precision cap or nonnumeric fallback. Every delivery and recovery path stays on the existing durable projection lifecycle.
diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
new file mode 100644
index 0000000000..28cd99a4c3
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
@@ -0,0 +1,50 @@
+# Agent Note: 高缓存命中率的小数显示
+
+Status: implemented
+
+[English](2026-08-19-high-cache-hit-decimal-display.md) | 中文
+
+## 问题
+
+Web 会话统计行会把所有非空缓存命中率舍入为整数。真实比率超过 99% 后，显示会隐藏后续提升；比率达到 99.5% 时，即使仍有未缓存输入或缓存写入，也会显示为 100%。
+
+用户因此无法区分接近完整的缓存命中与真实满命中。
+
+## 决策
+
+`StatsLine` 继续从 `@deepseek-ai/dsh-token-meter` 所拥有的完整会话 `tokenUsage` 投影派生比率；该投影仍是未缓存输入、缓存读取、缓存写入与输出计数的唯一所有方（[投影决策](../architecture/2026-07-29-projected-token-usage-and-request-context.md)）。展示层只改变插入现有 `stats.cacheHit` locale 模板的文本。
+
+| 真实比率 | 显示结果 |
+|---|---|
+| 没有计费输入 | 省略缓存命中分组 |
+| 整数舍入结果低于 100% | 舍入后的整数 |
+| 当前舍入结果为 100% 的非满命中 | 舍入结果低于 100% 所需的最少小数位 |
+| 100% | `100%` |
+
+所有非空比率都从零位小数开始。非满命中只有在舍入结果会成为 100% 时才逐位增加精度，因此 `99.1%` 与 `99.49%` 仍显示为 `99%`，而 `99.5%`、`99.95%` 与 `99.995%` 分别保留一位、两位与三位小数。`StatsLine` 使用 `bigint` 缩放并舍入整数 token 计数，从而避开浮点格式化限制，且不设置精度上限或替代文案。真实满命中不会携带多余的小数。同一份派生字符串同时用于行内统计与溢出 tooltip。
+
+## 归属与生命周期
+
+token-meter 继续从完整持久会话日志折叠用量。标准投影值变化时，`StatsLine` 同步派生显示文本。本决策不引入设置、持久百分比、事件、协议字段、客户端状态或恢复路径。
+
+实时更新、刷新回放与重连恢复都会还原同一组 `tokenUsage` 计数，并运行同一个显示函数。投影缺失时仍会省略全部 token 分组；输入分母为零时仍只省略缓存命中分组。
+
+## 验证
+
+组件测试固定了零分母、普通整数舍入、直至三位小数的各个精度边界、需要十四位小数的近满累计样本、真实 `100%`、两种 locale，以及行内值与 tooltip 值的一致性。组装后的 `lifecycle-chrome` replay sidecar 将 `9,950 / 10,000 = 99.5%` 选作确定性测试输入；该比率按整数舍入会误报为 100%，同时基础会话 fixture 仍可重录。活跃页面断言与刷新后的浏览器快照都会显示 `99.5%`，且不会产生额外模型调用。
+
+## 备选方案
+
+**对所有比率继续使用整数舍入。** 不予采纳，因为它会隐藏 99% 以上的全部变化，并继续把部分非满命中显示为 100%。
+
+**把高位区间向下截取到一位小数。** 不予采纳，因为 `99.95%`、`99.995%` 以及更接近满命中的比率都会坍缩为 `99.9%`，无法保留区分真实满命中所需的最少精度。
+
+**限制精度并使用 `<100%` 等替代文案。** 不予采纳，因为精确累计计数能够产生所需的数值结果，而精度上限会让显示行为依赖任意的展示限制。
+
+**所有比率都显示一位小数。** 不予采纳，因为低位区间的额外变化会增加无效抖动，并改变整数精度已经足够的既有显示。
+
+**在 token-meter 中持久化显示百分比。** 不予采纳，因为投影已经携带精确计数，而展示精度属于 Web 统计行。第二个持久值会复制可派生状态，并扩大回放与协议职责。
+
+## 后果
+
+高缓存命中率会保持稳定的整数显示，直到整数舍入会错误地报告满命中；此时界面只展示维持区分所需的小数位。极接近满命中的非满比率可能因此产生较长的小数字符串，这是不设置任意精度上限或非数值回退所接受的代价。所有交付与恢复路径继续沿用既有持久投影生命周期。
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index dcfabacf93..869aac2f14 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -25,6 +25,7 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/lifecycle-chrome', import.meta.url))
 const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
+const REPLAY_OVERRIDE = join(SNAPSHOT_DIR, 'replay.override.json')
 const HERO_EXPECTED = join(SNAPSHOT_DIR, 'hero.expected.md')
 const COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu.expected.md')
 const FUZZY_COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu-fuzzy.expected.md')
@@ -45,7 +46,9 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
   const sessionEvents: SessionEvent[] = []
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: REPLAY_PACE_MS })
+    scaffold = await launchWebScaffold(MODE === 'record'
+      ? {}
+      : { replayFixture: FIXTURE, replayOverride: REPLAY_OVERRIDE, paceMs: REPLAY_PACE_MS })
     scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
@@ -206,6 +209,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     ).toBeGreaterThanOrEqual(1)
     await expect.poll(() => page.locator('[role="treeitem"][aria-selected="true"]').count(), { timeout: 10_000 }).toBe(1)
     await expect.poll(() => page.getByText('LIGHTHOUSE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1)
+    await expect.poll(() => page.getByText('Cache hit 99.5%', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
     // Host: the session's durable header cwd is the folder the workspace
     // flow created and adopted (<workspaceCwd>/workspace) — the proof the
     // send went through workspace materialization rather than a bare
@@ -271,7 +275,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'session.jsonl', 'command-menu.expected.md', 'command-menu-fuzzy.expected.md', 'hero.expected.md', 'plan-active.expected.md', 'reloaded.expected.md',
+      'session.jsonl', 'replay.override.json', 'command-menu.expected.md', 'command-menu-fuzzy.expected.md', 'hero.expected.md', 'plan-active.expected.md', 'reloaded.expected.md',
     ])
   })
 })
diff --git a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md
index 9221d887b0..4d3fe1aa9f 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/reloaded.expected.md
@@ -37,6 +37,6 @@
 - button "Select model, current DeepSeek-V4-Flash":
   - text: DeepSeek-V4-Flash
   - img
-- button "6% of context used"
+- button "8% of context used"
 - button "Send message" [disabled]
-- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 7.8K tok · Output 21 tok
+- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99.5% Input 10K tok · Output 21 tok
diff --git a/apps/web/tests/snapshots/lifecycle-chrome/replay.override.json b/apps/web/tests/snapshots/lifecycle-chrome/replay.override.json
new file mode 100644
index 0000000000..71317fe822
--- /dev/null
+++ b/apps/web/tests/snapshots/lifecycle-chrome/replay.override.json
@@ -0,0 +1,153 @@
+{
+  "patches": [
+    {
+      "at": 0,
+      "entry": {
+        "kind": "chunks",
+        "chunks": [
+          {
+            "type": "block-start",
+            "index": 0,
+            "blockType": "reasoning"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": "The"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " user"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " wants"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " me"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " to"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " reply"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " with"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " a"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " single"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " word"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": "."
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " Let"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " me"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": " comply"
+          },
+          {
+            "type": "reasoning-delta",
+            "index": 0,
+            "text": "."
+          },
+          {
+            "type": "block-start",
+            "index": 1,
+            "blockType": "text"
+          },
+          {
+            "type": "text-delta",
+            "index": 1,
+            "text": "L"
+          },
+          {
+            "type": "text-delta",
+            "index": 1,
+            "text": "IGH"
+          },
+          {
+            "type": "text-delta",
+            "index": 1,
+            "text": "TH"
+          },
+          {
+            "type": "text-delta",
+            "index": 1,
+            "text": "O"
+          },
+          {
+            "type": "text-delta",
+            "index": 1,
+            "text": "USE"
+          },
+          {
+            "type": "block-end",
+            "index": 0,
+            "block": {
+              "type": "reasoning",
+              "text": "The user wants me to reply with a single word. Let me comply."
+            }
+          },
+          {
+            "type": "block-end",
+            "index": 1,
+            "block": {
+              "type": "text",
+              "text": "LIGHTHOUSE"
+            }
+          },
+          {
+            "type": "usage",
+            "usage": {
+              "inputTokens": 50,
+              "outputTokens": 21,
+              "cacheReadTokens": 9950,
+              "reasoningTokens": 15
+            }
+          },
+          {
+            "type": "finish",
+            "reason": {
+              "kind": "stop"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index e1d7e10227..18c6371734 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.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 packages/client/ui-conversation/README.md
-README.md: 7793273e053142b232cf6e810cd915ddbdeb90b0
-README.zh.md: f45dfa6d72ecf5b49a12c9550d41dbcbc35f9be0
+README.md: 2e3b99fbd4fca6bbe7b12d8408edb30597f8259e
+README.zh.md: 6f3aaa313c0f9372a6191e50dd34916fadffa8f3
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 7793273e05..2e3b99fbd4 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ Image intake accepts paste and whole-page drop: the bar binds document-level dra
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop controls), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `InputTriggerController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-input-trigger's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar keeps message actions inert (machine faces absent, `disabled` owner prop), while the whole dashed card opens the existing Workspace picker by pointer and the read-only textarea opens it through Enter or Space. Disabled controls release pointer events to the card, and the card contains `pointerdown` so the open picker's outside-close cannot race a reopen. The bar never swaps in a parallel tree, so the textarea DOM survives Workspace selection; strict-session control seats stay empty until a session exists.
 
-The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. The turn and step counts, the LLM and tool wall times, and the latency/throughput group all ride the whole-log `sessionStats` projection (host-folded from step boundaries, first-token chunks, tool pairs, and assembled messages), so paging and compaction cannot change any strip figure; an assembly without that unit falls back to the window fold over visible nodes, whose fields mirror the projection's. The strip averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them, and durable count, token, and context groups remain visible when compaction leaves no assistant node in the loaded window. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy renders as the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
+The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Every non-empty ratio starts with integer rounding. A non-full ratio adds decimal places only while the current precision would round to 100%, stopping at the minimum precision that remains below 100%; only a full cache hit displays 100%, and the precision has no fixed limit. The turn and step counts, the LLM and tool wall times, and the latency/throughput group all ride the whole-log `sessionStats` projection (host-folded from step boundaries, first-token chunks, tool pairs, and assembled messages), so paging and compaction cannot change any strip figure; an assembly without that unit falls back to the window fold over visible nodes, whose fields mirror the projection's. The strip averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them, and durable count, token, and context groups remain visible when compaction leaves no assistant node in the loaded window. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy renders as the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` exports contain only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f45dfa6d72..6f3aaa313c 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -40,7 +40,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止控件之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `InputTriggerController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-input-trigger 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 会让消息操作保持不可交互（machine face 均缺席、`disabled` owner prop），整张虚线卡片可经指针打开现有 Workspace picker，只读 textarea 也可通过 Enter 或 Space 打开。禁用控件会把指针事件交给卡片，卡片也会拦下 `pointerdown`，避免已打开 picker 的外点关闭与重新打开发生竞态。它不会换入一棵平行树，因此选择 Workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
-聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。轮次与步骤计数、LLM（大语言模型）与工具墙钟时间、以及延迟／吞吐分组都来自全日志的 `sessionStats` 投影（Host 端从步边界、首 token chunk、工具配对与已组装消息折算），因此分页与压缩都无法改变统计条的任何数字；未组合该单元的装配回退为对可见节点做窗口折算，其字段与投影一一对应。统计条把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久计数、token 与上下文分组仍保持可见。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率渲染为 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
+聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。所有非空比率都先按整数舍入。非满命中只有在当前精度会舍入成 100% 时才增加小数位，并在首次得到低于 100% 的结果时停止；只有完整缓存命中才显示 100%，且精度没有固定上限。轮次与步骤计数、LLM（大语言模型）与工具墙钟时间、以及延迟／吞吐分组都来自全日志的 `sessionStats` 投影（Host 端从步边界、首 token chunk、工具配对与已组装消息折算），因此分页与压缩都无法改变统计条的任何数字；未组合该单元的装配回退为对可见节点做窗口折算，其字段与投影一一对应。统计条把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久计数、token 与上下文分组仍保持可见。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率渲染为 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
index 147d2b7c6c..022b71d890 100644
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -102,15 +102,33 @@ export function formatDuration(ms: number): string {
 }
 
 /**
- * Cache-hit share of prompt-side input over the whole durable log.
+ * Display-ready cache-hit share of prompt-side input over the whole durable log.
  * @param usage - the session's token-usage projection value.
- * @returns rounded integer percent, or null when no input was billed.
+ * @returns integer text when integer rounding stays below 100, otherwise the
+ * minimum decimal precision that still rounds below 100; a full hit returns
+ * 100, and no billed input returns null.
  */
-export function cacheHitPercent(usage: TokenUsageProjection): number | null {
-  const denominator = billedInputTokens(usage)
-  return denominator === 0
-    ? null
-    : Math.round(usage.cacheReadTokens / denominator * 100)
+export function cacheHitPercent(usage: TokenUsageProjection): string | null {
+  const cacheReadTokens = BigInt(usage.cacheReadTokens)
+  const denominator = BigInt(usage.uncachedInputTokens)
+    + cacheReadTokens
+    + BigInt(usage.cacheWriteTokens)
+  if (denominator === 0n) return null
+  if (cacheReadTokens === denominator) return '100'
+
+  let decimalPlaces = 0
+  let decimalScale = 1n
+  while (true) {
+    const fullHit = 100n * decimalScale
+    const rounded = (2n * cacheReadTokens * fullHit + denominator) / (2n * denominator)
+    if (rounded < fullHit) {
+      if (decimalPlaces === 0) return rounded.toString()
+      const digits = rounded.toString().padStart(decimalPlaces + 1, '0')
+      return `${digits.slice(0, -decimalPlaces)}.${digits.slice(-decimalPlaces)}`
+    }
+    decimalPlaces += 1
+    decimalScale *= 10n
+  }
 }
 
 /**
diff --git a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
index 01be6e0850..e0dbc6f723 100644
--- a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
@@ -191,6 +191,10 @@ describe('StatsLine', () => {
     return { useSession: bindSnapshotSelector(source), useProjection: projections(values), t: tEn }
   }
 
+  function tokenUsage(cacheReadTokens: number, uncachedInputTokens: number) {
+    return { uncachedInputTokens, outputTokens: 1, cacheReadTokens, cacheWriteTokens: 0 }
+  }
+
   it('renders the grouped stats row and hides a brand-new empty session', () => {
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
     const view = render(<StatsLine {...props(source)} />)
@@ -205,19 +209,40 @@ describe('StatsLine', () => {
     expect(emptyView.container.textContent).toBe('')
   })
 
+  it.each([
+    { actual: '98.6%', tokenUsageValue: tokenUsage(986, 14), expected: 'Cache hit 99%' },
+    { actual: '99.1%', tokenUsageValue: tokenUsage(991, 9), expected: 'Cache hit 99%' },
+    { actual: '99.49%', tokenUsageValue: tokenUsage(9_949, 51), expected: 'Cache hit 99%' },
+    { actual: '99.5%', tokenUsageValue: tokenUsage(995, 5), expected: 'Cache hit 99.5%' },
+    { actual: '99.94%', tokenUsageValue: tokenUsage(9_994, 6), expected: 'Cache hit 99.9%' },
+    { actual: '99.95%', tokenUsageValue: tokenUsage(9_995, 5), expected: 'Cache hit 99.95%' },
+    { actual: '99.995%', tokenUsageValue: tokenUsage(19_999, 1), expected: 'Cache hit 99.995%' },
+    {
+      actual: 'the closest non-full ratio available from safe integer cumulative counts',
+      tokenUsageValue: tokenUsage(Number.MAX_SAFE_INTEGER - 1, 1),
+      expected: 'Cache hit 99.99999999999999%',
+    },
+    { actual: '100%', tokenUsageValue: tokenUsage(10_000, 0), expected: 'Cache hit 100%' },
+  ])('formats an actual $actual cache-hit ratio as $expected', ({ tokenUsageValue, expected }) => {
+    const { source } = makeSource({ nodes: [assistant(1, 1)] })
+    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsageValue })} />)
+    expect(view.container.textContent).toContain(expected)
+  })
+
   it('reveals the full line in a delayed hover tooltip only while the row is clipped', () => {
     vi.useFakeTimers()
     // jsdom lays nothing out; fake a row narrower than its content.
     vi.spyOn(Element.prototype, 'scrollWidth', 'get').mockReturnValue(800)
     vi.spyOn(Element.prototype, 'clientWidth', 'get').mockReturnValue(400)
     const { source } = makeSource({ nodes: [assistant(1, 1)] })
-    const view = render(<StatsLine {...props(source)} />)
+    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsage(9_995, 5) })} />)
+    expect(view.container.textContent).toContain('Cache hit 99.95%')
     fireEvent.mouseEnter(view.container.firstElementChild!)
     act(() => { vi.advanceTimersByTime(499) })
     expect(view.container.querySelector('[role="tooltip"]')).toBeNull()
     act(() => { vi.advanceTimersByTime(1) })
     expect(view.container.querySelector('[role="tooltip"]')?.textContent)
-      .toBe('1 turns · 1 steps | Cache hit 90% | Input 100 tok · Output 5 tok')
+      .toBe('1 turns · 1 steps | Cache hit 99.95% | Input 10K tok · Output 1 tok')
   })
 
   it('suppresses the tooltip while the row fits without truncation', () => {
@@ -245,9 +270,9 @@ describe('StatsLine', () => {
       timing: { stepStartTime: 1_000, firstTokenTime: 1_800, completedTime: 4_800 },
     }
     const { source } = makeSource({ nodes: [timed] })
-    const view = render(<StatsLine {...props(source)} t={t} />)
+    const view = render(<StatsLine {...props(source, { tokenUsage: tokenUsage(9_995, 5) })} t={t} />)
     expect(view.container.textContent)
-      .toBe('1 轮 · 1 步| LLM 3.8s| 首 token 平均 0.8s · 20 tok/s| 缓存命中 90%| 输入 100 tok · 输出 5 tok')
+      .toBe('1 轮 · 1 步| LLM 3.8s| 首 token 平均 0.8s · 20 tok/s| 缓存命中 99.95%| 输入 10K tok · 输出 1 tok')
   })
 
   it('renders without ResizeObserver support', () => {

From fa2ce12162f2bf8691ead92fd5c85212a9a041da Mon Sep 17 00:00:00 2001
From: pku-xht <xht@deepseek.com>
Date: Wed, 19 Aug 2026 14:41:04 +0800
Subject: [PATCH 02/34] review fix: avoid bigint cache-hit formatting

---
 ...9-high-cache-hit-decimal-display.i18n.yaml |  4 +-
 ...26-08-19-high-cache-hit-decimal-display.md |  4 +-
 ...08-19-high-cache-hit-decimal-display.zh.md |  4 +-
 .../src/client/chat/StatsLine.tsx             | 64 ++++++++++++++-----
 .../tests/chat-stats.client.spec.tsx          |  3 +
 5 files changed, 56 insertions(+), 23 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml
index b95a27e700..114dcbfe23 100644
--- a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.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/feature/2026-08-19-high-cache-hit-decimal-display.md
-2026-08-19-high-cache-hit-decimal-display.md: 29e0ebc11ae690b918c7e9364f29635de1e50f2a
-2026-08-19-high-cache-hit-decimal-display.zh.md: 28cd99a4c321cc4da0ce03142e2fbf438539b0ff
+2026-08-19-high-cache-hit-decimal-display.md: 952d838fdf330175915e13ef767fd80d145506b2
+2026-08-19-high-cache-hit-decimal-display.zh.md: 4a72becd608e756507f3d5a6fd051b4b2b437964
diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
index 29e0ebc11a..952d838fdf 100644
--- a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.md
@@ -21,7 +21,7 @@ Users therefore could not distinguish a nearly complete cache hit from a true fu
 | Non-full ratio whose current rounding is 100% | Minimum decimal precision whose rounded result is below 100% |
 | 100% | `100%` |
 
-Every non-empty ratio starts at zero decimal places. A non-full ratio increases precision one place at a time only while rounding would produce 100%, so `99.1%` and `99.49%` remain `99%`, while `99.5%`, `99.95%`, and `99.995%` retain one, two, and three decimal places respectively. `StatsLine` scales and rounds the integer token counts with `bigint`, which avoids floating-point formatting limits and imposes no precision cap or substitute label. A full hit does not carry a redundant decimal. The same derived string feeds the inline row and its overflow tooltip.
+Every non-empty ratio starts at zero decimal places. A non-full ratio increases precision one place at a time only while rounding would produce 100%, so `99.1%` and `99.49%` remain `99%`, while `99.5%`, `99.95%`, and `99.995%` retain one, two, and three decimal places respectively. `StatsLine` uses exact small-factor comparisons over the safe-integer token counts, then scales the near-full gap only while the intermediate remains within that range. This avoids floating-point tie errors without imposing a precision cap or substitute label. A full hit does not carry a redundant decimal. The same derived string feeds the inline row and its overflow tooltip.
 
 ## Ownership and lifecycle
 
@@ -31,7 +31,7 @@ Live updates, reload replay, and reconnect recovery all restore the same `tokenU
 
 ## Verification
 
-The component spec pins the zero denominator, ordinary integer rounding, each precision boundary through three decimal places, a near-full cumulative sample that needs fourteen decimal places, the true `100%` result, both locales, and equality between inline and tooltip values. The assembled `lifecycle-chrome` replay sidecar selects `9,950 / 10,000 = 99.5%` as a deterministic ratio that integer rounding would misreport as 100% while the base session fixture remains recordable; the live assertion and post-reload browser snapshot both display `99.5%` without another model call.
+The component spec pins the zero denominator, ordinary integer rounding, half-step rounding at several decimal precisions, each precision boundary through three decimal places, a near-full cumulative sample that needs fourteen decimal places, the true `100%` result, both locales, and equality between inline and tooltip values. The assembled `lifecycle-chrome` replay sidecar selects `9,950 / 10,000 = 99.5%` as a deterministic ratio that integer rounding would misreport as 100% while the base session fixture remains recordable; the live assertion and post-reload browser snapshot both display `99.5%` without another model call.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
index 28cd99a4c3..4a72becd60 100644
--- a/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-19-high-cache-hit-decimal-display.zh.md
@@ -21,7 +21,7 @@ Web 会话统计行会把所有非空缓存命中率舍入为整数。真实比
 | 当前舍入结果为 100% 的非满命中 | 舍入结果低于 100% 所需的最少小数位 |
 | 100% | `100%` |
 
-所有非空比率都从零位小数开始。非满命中只有在舍入结果会成为 100% 时才逐位增加精度，因此 `99.1%` 与 `99.49%` 仍显示为 `99%`，而 `99.5%`、`99.95%` 与 `99.995%` 分别保留一位、两位与三位小数。`StatsLine` 使用 `bigint` 缩放并舍入整数 token 计数，从而避开浮点格式化限制，且不设置精度上限或替代文案。真实满命中不会携带多余的小数。同一份派生字符串同时用于行内统计与溢出 tooltip。
+所有非空比率都从零位小数开始。非满命中只有在舍入结果会成为 100% 时才逐位增加精度，因此 `99.1%` 与 `99.49%` 仍显示为 `99%`，而 `99.5%`、`99.95%` 与 `99.995%` 分别保留一位、两位与三位小数。`StatsLine` 对安全整数 token 计数执行精确的小因子比较，并且只在中间值仍处于该范围内时缩放接近满命中的差值。该算法既避开浮点临界值误差，也不设置精度上限或替代文案。真实满命中不会携带多余的小数。同一份派生字符串同时用于行内统计与溢出 tooltip。
 
 ## 归属与生命周期
 
@@ -31,7 +31,7 @@ token-meter 继续从完整持久会话日志折叠用量。标准投影值变
 
 ## 验证
 
-组件测试固定了零分母、普通整数舍入、直至三位小数的各个精度边界、需要十四位小数的近满累计样本、真实 `100%`、两种 locale，以及行内值与 tooltip 值的一致性。组装后的 `lifecycle-chrome` replay sidecar 将 `9,950 / 10,000 = 99.5%` 选作确定性测试输入；该比率按整数舍入会误报为 100%，同时基础会话 fixture 仍可重录。活跃页面断言与刷新后的浏览器快照都会显示 `99.5%`，且不会产生额外模型调用。
+组件测试固定了零分母、普通整数舍入、多个小数精度上的半步舍入、直至三位小数的各个精度边界、需要十四位小数的近满累计样本、真实 `100%`、两种 locale，以及行内值与 tooltip 值的一致性。组装后的 `lifecycle-chrome` replay sidecar 将 `9,950 / 10,000 = 99.5%` 选作确定性测试输入；该比率按整数舍入会误报为 100%，同时基础会话 fixture 仍可重录。活跃页面断言与刷新后的浏览器快照都会显示 `99.5%`，且不会产生额外模型调用。
 
 ## 备选方案
 
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
index 022b71d890..2d9d14483b 100644
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -101,6 +101,26 @@ export function formatDuration(ms: number): string {
   return `${Math.floor(whole / 60)}m${whole % 60}s`
 }
 
+/** Round a cache-read ratio to an integer percentage, with positive ties rounded up. */
+function roundedIntegerPercent(cacheReadTokens: number, denominator: number): number {
+  const denominatorQuotient = Math.floor(denominator / 200)
+  const denominatorRemainder = denominator % 200
+  let lower = 0
+  let upper = 100
+  while (lower < upper) {
+    const candidate = Math.floor((lower + upper + 1) / 2)
+    const factor = candidate * 2 - 1
+    const threshold = factor * denominatorQuotient
+      + Math.ceil(factor * denominatorRemainder / 200)
+    if (cacheReadTokens >= threshold) {
+      lower = candidate
+    } else {
+      upper = candidate - 1
+    }
+  }
+  return lower
+}
+
 /**
  * Display-ready cache-hit share of prompt-side input over the whole durable log.
  * @param usage - the session's token-usage projection value.
@@ -109,26 +129,36 @@ export function formatDuration(ms: number): string {
  * 100, and no billed input returns null.
  */
 export function cacheHitPercent(usage: TokenUsageProjection): string | null {
-  const cacheReadTokens = BigInt(usage.cacheReadTokens)
-  const denominator = BigInt(usage.uncachedInputTokens)
-    + cacheReadTokens
-    + BigInt(usage.cacheWriteTokens)
-  if (denominator === 0n) return null
-  if (cacheReadTokens === denominator) return '100'
+  const denominator = billedInputTokens(usage)
+  if (denominator === 0) return null
+  const missedInputTokens = usage.uncachedInputTokens + usage.cacheWriteTokens
+  if (missedInputTokens === 0) return '100'
 
-  let decimalPlaces = 0
-  let decimalScale = 1n
-  while (true) {
-    const fullHit = 100n * decimalScale
-    const rounded = (2n * cacheReadTokens * fullHit + denominator) / (2n * denominator)
-    if (rounded < fullHit) {
-      if (decimalPlaces === 0) return rounded.toString()
-      const digits = rounded.toString().padStart(decimalPlaces + 1, '0')
-      return `${digits.slice(0, -decimalPlaces)}.${digits.slice(-decimalPlaces)}`
-    }
+  const integerPercent = roundedIntegerPercent(usage.cacheReadTokens, denominator)
+  if (integerPercent < 100) return String(integerPercent)
+
+  // At the first distinguishing precision, the rounded result is 100 minus
+  // one to five units in the final decimal place. Scale only while the next
+  // multiplication remains at or below the denominator, then derive that
+  // final digit through exact small-factor comparisons.
+  let decimalPlaces = 1
+  let scaledDoubleGap = missedInputTokens * 200
+  const denominatorTens = Math.floor(denominator / 10)
+  while (scaledDoubleGap <= denominatorTens) {
+    scaledDoubleGap *= 10
     decimalPlaces += 1
-    decimalScale *= 10n
   }
+  const denominatorOnes = denominator % 10
+  let roundedLoss = 5
+  for (let loss = 1; loss < 5; loss += 1) {
+    const factor = loss * 2 + 1
+    const threshold = factor * denominatorTens + Math.floor(factor * denominatorOnes / 10)
+    if (scaledDoubleGap <= threshold) {
+      roundedLoss = loss
+      break
+    }
+  }
+  return `99.${'9'.repeat(decimalPlaces - 1)}${10 - roundedLoss}`
 }
 
 /**
diff --git a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
index e0dbc6f723..be55ee0579 100644
--- a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
@@ -216,7 +216,10 @@ describe('StatsLine', () => {
     { actual: '99.5%', tokenUsageValue: tokenUsage(995, 5), expected: 'Cache hit 99.5%' },
     { actual: '99.94%', tokenUsageValue: tokenUsage(9_994, 6), expected: 'Cache hit 99.9%' },
     { actual: '99.95%', tokenUsageValue: tokenUsage(9_995, 5), expected: 'Cache hit 99.95%' },
+    { actual: '99.955%', tokenUsageValue: tokenUsage(19_991, 9), expected: 'Cache hit 99.96%' },
+    { actual: '99.985%', tokenUsageValue: tokenUsage(19_997, 3), expected: 'Cache hit 99.99%' },
     { actual: '99.995%', tokenUsageValue: tokenUsage(19_999, 1), expected: 'Cache hit 99.995%' },
+    { actual: '99.9975%', tokenUsageValue: tokenUsage(39_999, 1), expected: 'Cache hit 99.998%' },
     {
       actual: 'the closest non-full ratio available from safe integer cumulative counts',
       tokenUsageValue: tokenUsage(Number.MAX_SAFE_INTEGER - 1, 1),

From 000ab970f3a82a799701d3deb47464c1de104328 Mon Sep 17 00:00:00 2001
From: 07akioni <07akioni2@gmail.com>
Date: Wed, 19 Aug 2026 19:58:14 +0800
Subject: [PATCH 03/34] feat(web): size markdown tables by column count, widen
 wide ones past the column

Markdown tables were always rendered at natural width, so anything wider
than the 748px message column could only be read through horizontal
scrolling. Following the deepsuite chat TableWrapper treatment: tables
under four columns (and any table inside a blockquote) now fill the column
and wrap cell text down to the cells' minimum readable width, while
four-or-more-column tables keep their natural width behind the wrapper's
horizontal scroll and carry the stable md-table-wide hook. The chat
transcript widens hooked tables past the message column with a pure-CSS
container-query breakout (100cqw against ChatView's scroll container
standing in for deepsuite's JS-measured list width), keeping the table
content aligned with the message column and clamping to neutral when the
transcript is narrower than the column.
---
 ...-19-web-markdown-wide-table-view.i18n.yaml |   6 +
 ...2026-08-19-web-markdown-wide-table-view.md |  37 ++
 ...6-08-19-web-markdown-wide-table-view.zh.md |  37 ++
 apps/web/tests/markdown-wide-table.e2e.ts     | 454 ++++++++++++++++++
 .../markdown-wide-table/geometry.expected.md  |  18 +
 apps/web/tsconfig.json                        |   1 +
 .../client/chat/AssistantMarkdown.module.css  |  22 +
 .../src/client/chat/ChatView.module.css       |   5 +
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 .../src/markdown/MarkdownText.module.css      |  19 +
 .../ui-primitives/src/markdown/render.tsx     |  17 +-
 .../markdown-dom/math-edge-cases.settled.txt  |   2 +-
 .../math-edge-cases.streaming.txt             |   2 +-
 .../table-header-only.settled.txt             |   2 +-
 .../table-header-only.streaming.txt           |   2 +-
 .../table-wide-and-blockquote.settled.txt     |  46 ++
 .../table-wide-and-blockquote.streaming.txt   |  46 ++
 .../table-with-alignment.settled.txt          |   2 +-
 .../table-with-alignment.streaming.txt        |   2 +-
 .../tests/markdown-dom-parity.client.spec.tsx |  11 +
 .../markdown-render-units.client.spec.tsx     |   8 +
 tsconfig.host.json                            |   1 +
 24 files changed, 736 insertions(+), 12 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
 create mode 100644 apps/web/tests/markdown-wide-table.e2e.ts
 create mode 100644 apps/web/tests/snapshots/markdown-wide-table/geometry.expected.md
 create mode 100644 packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
 create mode 100644 packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt

diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml
new file mode 100644
index 0000000000..19561bb6f0
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.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/feature/2026-08-19-web-markdown-wide-table-view.md
+2026-08-19-web-markdown-wide-table-view.md: 847b3f055edd29eeb0b6f3f8bec5b97252aca4f4
+2026-08-19-web-markdown-wide-table-view.zh.md: d2fcc18f883f71a3fdbfbab6476c87b1c9840b21
diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
new file mode 100644
index 0000000000..847b3f055e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
@@ -0,0 +1,37 @@
+# Agent Note: Web markdown tables fill the column by count, wide ones break out
+
+Status: implemented
+
+English | [中文](2026-08-19-web-markdown-wide-table-view.zh.md)
+
+## Problem
+
+`MarkdownText` rendered every GFM table at its natural width (`.tableScroll table { width: max-content; max-width: max-content }`, `packages/client/ui-primitives/src/markdown/MarkdownText.module.css`), so any table wider than the 748px message column could only be read through horizontal scrolling. A three-column table whose cells could comfortably wrap still forced a scroll, and a genuinely wide table could never use more than the message column even when the transcript around it had hundreds of spare pixels. Issue #1761 (with external feedback dsh-external/issues#520) asks for wrap-first adaptation and a wider view for tables that need it. The deepsuite chat product solved the same problem CSS-first; per review direction this change mirrors that solution instead of the interactive expand-dialog approach first drafted here.
+
+## Decision
+
+**Column count picks the sizing arm, statically, in the renderer.** `renderTable` reads the parsed column count (the `align` array, header-row fallback): tables under four columns — and any table inside a blockquote (`inBlockquote` render-context flag) — get the module's `tableFill` class, `table { width: 100%; max-width: none }`, filling the column with cells wrapping down to their existing `min-width: 100px` floor. Four-or-more-column tables keep the natural-width rules and instead carry the stable global hook class `md-table-wide` (the `md-code-block` precedent), so a hosting layout can widen them. This is deepsuite chat's discriminator (`.wrapper:not(:has(th:nth-child(4), td:nth-child(4)))` plus its blockquote exemption) computed in the renderer, which already knows the column count. No measurement, observers, or interaction state anywhere.
+
+**The chat transcript widens hooked tables with container-query CSS.** ChatView's `.scroll` declares `container-type: inline-size`, and `AssistantMarkdown.module.css` gives `.body :global(.md-table-wide)` the breakout: `--dsh-table-spare` is the per-side spare width `max(0px, (100cqw - --dsh-chat-content-width) / 2)`, `--dsh-table-lead` adds the wrapper's own indent (`min(--dsh-chat-content-width, 100cqw) - 100%`), and width/negative-margin/lead-padding combine so the wrapper's scroll area spans the full transcript while the table content keeps starting at the message column's left edge. `100cqw` is the CSS stand-in for deepsuite chat's JS-measured `--dsl-virtual-list-width`; the `max(0px, …)` clamp replaces its below-SM JS gate, degrading continuously to the plain in-column scroll when the transcript is narrower than the message column. Scoping the rule under `AssistantMarkdown .body` keeps tool cards, compaction rows, and every other `MarkdownText` surface at plain in-column behavior.
+
+**The parity fixtures change deliberately.** The table-containing markdown-dom fixtures pin the discriminator: `tableScroll tableFill` for narrow and blockquote tables, `tableScroll md-table-wide` for wide ones, and a new `table-wide-and-blockquote` corpus document pins both arms of the blockquote exemption.
+
+## Alternatives considered
+
+**Overflow-measured chrome: a ResizeObserver-gated expand entry opening the table in a `Modal` wide view.** Implemented first, then rejected on review direction in favor of deepsuite chat parity: the CSS solution needs no per-table observers, no dialog state that the streaming finalize swap would drop, no label plumbing through the cordis-free package, and gives the wide view permanently instead of behind an interaction.
+
+**`:has()`-based column counting in CSS, as deepsuite chat does.** Rejected: their wrapper is generic while this renderer already walks the table node, so the count is available statically; a class is cheaper than a `:has()` selector re-evaluated on DOM changes and pins the decision in the DOM for fixtures.
+
+**Breaking out to the viewport rather than the transcript.** Rejected: the conversation column pins `overflow-x: hidden` (the one-axis contract in `apps/web/tests/conversation-column-overflow.e2e.ts`), and anything wider than the transcript box would clip; the transcript width is exactly the space the layout actually has.
+
+## Consequences
+
+An ordinary wide table reads in place with wrapped cells; a many-column table keeps its readable natural width, spans the whole transcript where the layout has spare width, and scrolls for the remainder — with no interaction required and nothing to restore. Chromium keyboard-focuses scrollable containers by default, so the wrapper stays keyboard-scrollable without added attributes (a `:focus-visible` ring marks it). Two knowledge edges: `container-type: inline-size` on ChatView's `.scroll` makes it the nearest query container for anything inside the transcript that later uses container units, and sub-four-column tables now always stretch to the full column width (deepsuite chat behavior) rather than shrink-wrapping short content.
+
+## Testing
+
+The markdown-dom parity fixtures pin the wrapper classes per arm, including the new `table-wide-and-blockquote` document; `markdown-render-units.client.spec.tsx` covers the hand-built rowless/align-less fallback. `apps/web/tests/markdown-wide-table.e2e.ts` seeds a closed turn with three tables (three-column fill, twelve-column wide, long-token/CJK long-cell) and, in real Chromium, pins the relations golden across viewport stops — fill and long-cell tables fill the column with no residual scroll at every stop and grow taller as the column narrows, the wide table always scrolls, breaks out past the message column exactly at the stops where the transcript is wider than it, keeps its content left-aligned with the fill table's under the breakout, and clamps to neutral at the narrow stop — plus arrow-key scrolling of the focused wrapper, a zoom arm, and a deviceScaleFactor-2 arm that must report the same relations.
+
+## Related
+
+- [Web markdown incremental AST renderer](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) — the renderer and DOM-parity contract this change extends.
diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
new file mode 100644
index 0000000000..d2fcc18f88
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
@@ -0,0 +1,37 @@
+# Agent Note：Web markdown 表格按列数填充消息列，宽表突破列宽
+
+Status: implemented
+
+[English](2026-08-19-web-markdown-wide-table-view.md) | 中文
+
+## 问题
+
+`MarkdownText` 把每个 GFM 表格都按自然宽度渲染（`.tableScroll table { width: max-content; max-width: max-content }`，`packages/client/ui-primitives/src/markdown/MarkdownText.module.css`），于是任何比 748px 消息列更宽的表格都只能靠横向滚动阅读。单元格本可以舒适换行的三列表格也被迫滚动；而真正宽的表格即便转录区周围有几百像素的空余，也永远只能用消息列那么宽。Issue #1761（含外部反馈 dsh-external/issues#520）要求先换行适应，并为需要的表格提供更宽的视图。deepsuite chat 产品已用 CSS 优先的方式解决了同一问题；按评审方向，本变更对齐该方案，替换此前起草的交互式展开对话框方案。
+
+## 决定
+
+**列数在渲染器里静态决定尺寸分支。**`renderTable` 读取解析出的列数（`align` 数组，缺省回退表头行）：不足四列的表格——以及 blockquote 内的任何表格（渲染上下文的 `inBlockquote` 标志）——获得模块的 `tableFill` 类，`table { width: 100%; max-width: none }`，填满消息列，单元格按既有 `min-width: 100px` 下限换行。四列及以上的表格保持自然宽度规则，改挂稳定的全局钩子类 `md-table-wide`（沿用 `md-code-block` 先例），供宿主布局加宽。这正是 deepsuite chat 的判别式（`.wrapper:not(:has(th:nth-child(4), td:nth-child(4)))` 及其 blockquote 豁免），只是移到已经掌握列数的渲染器里计算。全程没有测量、observer 或交互状态。
+
+**聊天转录区用容器查询 CSS 加宽挂钩表格。**ChatView 的 `.scroll` 声明 `container-type: inline-size`，`AssistantMarkdown.module.css` 给 `.body :global(.md-table-wide)` 定义突破：`--dsh-table-spare` 是单侧空余宽度 `max(0px, (100cqw - --dsh-chat-content-width) / 2)`，`--dsh-table-lead` 再加上包裹层自身的缩进（`min(--dsh-chat-content-width, 100cqw) - 100%`），宽度/负 margin/前导 padding 组合起来，让包裹层的滚动区横跨整个转录区，而表格内容仍从消息列左缘起排。`100cqw` 是 deepsuite chat 用 JS 测量的 `--dsl-virtual-list-width` 的 CSS 等价物；`max(0px, …)` 钳制取代其 below-SM 的 JS 开关，转录区窄于消息列时连续退化为普通列内滚动。规则限定在 `AssistantMarkdown .body` 之下，工具卡片、压缩行等其他 `MarkdownText` 表面保持普通列内行为。
+
+**一致性 fixture 的变化是有意的。**含表格的 markdown-dom fixture pin 住判别结果：窄表与 blockquote 表为 `tableScroll tableFill`，宽表为 `tableScroll md-table-wide`；新增的 `table-wide-and-blockquote` 语料文档同时 pin 住 blockquote 豁免的两个分支。
+
+## 曾考虑的替代方案
+
+**实测溢出的交互件：ResizeObserver 门控的展开入口，用 `Modal` 打开宽视图。**先行实现，后按评审方向否决、改为对齐 deepsuite chat：CSS 方案不需要逐表 observer，没有会被流式定稿替换丢弃的对话框状态，不用穿过 cordis-free 包的文案管道，且宽视图是常驻的而非藏在交互后面。
+
+**像 deepsuite chat 那样用 `:has()` 在 CSS 里数列。**否决：它们的包裹层是通用组件，而本渲染器本来就在遍历表格节点，列数是静态可得的；类名比随 DOM 变化反复求值的 `:has()` 选择器更便宜，还把决定固化进 DOM 供 fixture pin 住。
+
+**突破到视口宽而不是转录区宽。**否决：会话列 pin 死了 `overflow-x: hidden`（`apps/web/tests/conversation-column-overflow.e2e.ts` 的单轴契约），超出转录区盒子的部分会被裁剪；转录区宽度正是布局实际拥有的空间。
+
+## 后果
+
+普通宽表原地换行阅读；多列表格保持可读的自然宽度，在布局有空余处横跨整个转录区，剩余部分滚动——无需任何交互，也没有状态要恢复。Chromium 默认让可滚动容器可键盘聚焦，因此包裹层无需附加属性即可键盘滚动（`:focus-visible` 有焦点圈）。两个需要知道的点：ChatView `.scroll` 上的 `container-type: inline-size` 使它成为转录区内后续使用容器单位的最近查询容器；不足四列的表格现在总是拉伸到整列宽（deepsuite chat 行为），而不是按内容收缩。
+
+## 测试
+
+markdown-dom 一致性 fixture 按分支 pin 住包裹层类名，含新增的 `table-wide-and-blockquote` 文档；`markdown-render-units.client.spec.tsx` 覆盖手工树的无行无 align 兜底。`apps/web/tests/markdown-wide-table.e2e.ts` seed 一个含三个表格的已关闭轮次（三列填充表、十二列宽表、长 token/中文长单元格表），在真实 Chromium 中跨视口档 pin 关系 golden——填充表与长单元格表在每一档都填满消息列、无残余滚动、随列变窄而变高；宽表始终滚动、恰好在转录区宽于消息列的档位突破列宽、突破时内容与填充表左对齐、窄档钳制为中性——外加聚焦包裹层的方向键滚动、缩放分支、以及必须报告相同关系的 deviceScaleFactor-2 分支。
+
+## 相关
+
+- [Web markdown 增量 AST 渲染器](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) —— 本变更所扩展的渲染器与 DOM 一致性契约。
diff --git a/apps/web/tests/markdown-wide-table.e2e.ts b/apps/web/tests/markdown-wide-table.e2e.ts
new file mode 100644
index 0000000000..da2c371085
--- /dev/null
+++ b/apps/web/tests/markdown-wide-table.e2e.ts
@@ -0,0 +1,454 @@
+// Web e2e scenario: markdown tables in the message column, deepsuite-chat
+// parity. Tables under four columns (and long-cell tables) fill the 748px
+// message column and wrap; four-or-more-column tables keep their natural
+// width, scroll horizontally inside their wrapper, and — through the
+// renderer's `md-table-wide` hook plus AssistantMarkdown's container-query
+// breakout — span the whole transcript width instead of clipping at the
+// message column, with the table content still starting at the message
+// column's left edge. When the transcript is narrower than the message
+// column the breakout clamps to neutral and the plain in-column scroll
+// remains.
+//
+// Only a real engine lays out CSS tables and resolves container-query
+// units, so the fill/scroll/breakout relations, the lead-padding alignment,
+// arrow-key scrolling, and the zoom/DPR arms are all measured in Chromium
+// across viewport stops. The golden records relations and booleans, never
+// pixels: absolute widths document the platform, not the behavior.
+//
+// Zero model calls: the transcript is a closed turn assembled through the
+// Session API and seeded cold; a stray stream would fail loud with
+// NO_ADAPTER.
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { createMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import {
+  SESSION_FORMAT_VERSION,
+  Session,
+  SessionId,
+} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
+import {
+  assertFixtureInventory,
+  compareOrRefreshGolden,
+  launchWebScaffold,
+  seedSession,
+  watchConsole,
+  webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/markdown-wide-table', import.meta.url))
+const GEOMETRY_EXPECTED = fileURLToPath(
+  new URL('./snapshots/markdown-wide-table/geometry.expected.md', import.meta.url),
+)
+const MODE = webSnapshotMode()
+const SEED_ID = 'markdown-wide-table-web-e2e'
+/** Painted into the final paragraph; the open barrier waits for it. */
+const TAIL_MARKER = 'MWT_TABLES_DONE'
+
+/**
+ * First-header-cell markers identify each table without depending on CSS
+ * module hashes or DOM order.
+ */
+const FILL_MARKER = 'MWT_FILL_C1'
+const WIDE_MARKER = 'MWT_WIDE_C01'
+const LONG_CELL_MARKER = 'MWT_LONGCELL_F1'
+const MARKERS = [FILL_MARKER, WIDE_MARKER, LONG_CELL_MARKER]
+/** Golden-facing names, in {@link MARKERS} order. */
+const TABLE_NAMES = ['fill', 'wide', 'long-cell']
+
+/**
+ * Viewport sweep. The wide stops leave the transcript far wider than the
+ * 748px message column, so the breakout relation holds with a fat margin on
+ * every platform; the narrow stop drops the transcript below the message
+ * column, which must clamp the breakout to neutral. The sidebar is collapsed
+ * for the whole sweep (see beforeAll), so the transcript width follows the
+ * viewport identically on overlay- and classic-scrollbar platforms.
+ */
+const WIDTHS = [1680, 1100, 640]
+
+/** A sentence long enough that three of them cannot sit unwrapped in the 748px column. */
+const SENTENCE = 'This cell carries one full sentence so the unwrapped table is far wider than the message column.'
+/** Unbroken path-like token (no scheme, so GFM does not autolink it and no anchor joins the tab order). */
+const LONG_TOKEN = 'workspace/deepseek-harness/packages/client/ui-primitives/src/markdown/render.tsx/'.repeat(3)
+const CJK_SENTENCE = '这个单元格包含一段较长的中文说明，用来验证长内容在窄列宽下按最小可读宽度换行而不是把列压缩到无法阅读。'
+
+/** The assistant markdown: one 3-column fill, one 12-column wide, one long-cell table. */
+function tablesMarkdown(): string {
+  const wideHeader = [WIDE_MARKER, ...Array.from({ length: 11 }, (_, i) => `C${String(i + 2).padStart(2, '0')}`)]
+  const wideRow = (row: number): string[] =>
+    Array.from({ length: 12 }, (_, i) => `v${String(row)}${String(i + 1).padStart(2, '0')}`)
+  return [
+    'Three markdown tables exercise the wide-table layout rules.',
+    '',
+    `| ${FILL_MARKER} | Current approach | Proposed approach |`,
+    '| --- | --- | --- |',
+    `| Rendering | ${SENTENCE} | ${SENTENCE} |`,
+    `| Memory | ${SENTENCE} | ${SENTENCE} |`,
+    '',
+    `| ${wideHeader.join(' | ')} |`,
+    `|${' --- |'.repeat(12)}`,
+    `| ${wideRow(1).join(' | ')} |`,
+    `| ${wideRow(2).join(' | ')} |`,
+    '',
+    `| ${LONG_CELL_MARKER} | Value |`,
+    '| --- | --- |',
+    `| path | ${LONG_TOKEN} |`,
+    `| 说明 | ${CJK_SENTENCE} |`,
+    '',
+    TAIL_MARKER,
+  ].join('\n')
+}
+
+/** Build one closed, invariant-checked session fixture carrying the three tables. */
+function wideTableFixture(): string {
+  const session = Session.create(SessionId('markdown-wide-table-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
+  session.append('turn/start', { turn: 1 })
+  const user = session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text: 'Show the wide-table layout scenarios.' }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+  session.append('session/title', {
+    title: 'Markdown wide tables',
+    messageSeqs: [user.seq],
+    source: { kind: 'fallback' },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
+  session.append('assistant/message', {
+    turn: 1,
+    step: 1,
+    message: createMessage({
+      role: 'assistant',
+      content: [{ type: 'text', text: tablesMarkdown() }],
+      source: { kind: 'model', provider: 'fixture', model: 'fixture' },
+    }),
+  }, { surfaceOp: 'append' })
+  session.append('step/end', { turn: 1, step: 1 })
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+  const header = {
+    type: 'session',
+    version: SESSION_FORMAT_VERSION,
+    id: '{{sessionId}}',
+    createdAt: 0,
+    cwd: '{{cwd}}',
+  }
+  return [
+    JSON.stringify(header),
+    // Spaced event times, as the sibling markdown fixtures pin them.
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
+    '',
+  ].join('\n')
+}
+
+/** One table's layout relations at the current viewport. */
+interface TableReading {
+  /** Identifying first-header-cell marker. */
+  marker: string
+  /** `scrollWidth - clientWidth` of the wrapper: the residual horizontal scroll. */
+  overflow: number
+  /** Wrapper content width. */
+  clientWidth: number
+  /** Rendered wrapper height; wrapping shows up as growth when the column narrows. */
+  height: number
+  /** Renderer marked the table with the `md-table-wide` breakout hook. */
+  wideHook: boolean
+  /** Resolved lead padding (the breakout's alignment compensation). */
+  paddingLeft: number
+  /** The table's own left x, for the content-alignment relation. */
+  tableLeft: number
+}
+
+/** Read all three tables' relations in one pass. */
+function readTables(page: Page): Promise<TableReading[]> {
+  return page.evaluate((markers) => {
+    const wrappers = [...document.querySelectorAll<HTMLElement>('[class*="tableScroll"]')]
+    return markers.map((marker) => {
+      const wrapper = wrappers.find(candidate => candidate.textContent?.includes(marker) ?? false)
+      if (wrapper === undefined) throw new Error(`table wrapper ${marker} not rendered`)
+      const table = wrapper.querySelector('table')
+      if (table === null) throw new Error(`table ${marker} not rendered`)
+      return {
+        marker,
+        overflow: wrapper.scrollWidth - wrapper.clientWidth,
+        clientWidth: wrapper.clientWidth,
+        height: wrapper.getBoundingClientRect().height,
+        wideHook: wrapper.classList.contains('md-table-wide'),
+        paddingLeft: Number.parseFloat(getComputedStyle(wrapper).paddingLeft),
+        tableLeft: table.getBoundingClientRect().left,
+      }
+    })
+  }, MARKERS)
+}
+
+/** A sweep stop: the three tables' readings at one viewport width. */
+interface TableStop {
+  width: number
+  tables: TableReading[]
+}
+
+/**
+ * Close the details pane so the transcript spans the viewport. Open, it pins
+ * the transcript to exactly the message column and every breakout relation
+ * would go vacuous.
+ * @param target - the page whose pane to close.
+ */
+async function closeDetailsPane(target: Page): Promise<void> {
+  await target.getByRole('button', { name: 'Close details', exact: true }).waitFor({ timeout: 10_000 })
+  await target.evaluate(() => {
+    document.querySelector<HTMLElement>('button[aria-label="Close details"]')?.click()
+  })
+  // Closed details resolve to zero width but never unmount (ui-layout
+  // columns contract), so the settled signal is the frame's collapse marker,
+  // not the button's detachment.
+  await target.waitForSelector('[data-details-collapsed]', { timeout: 5_000 })
+}
+
+/**
+ * Render the golden body: relations only. `fills` is the wrap-first claim
+ * (the wrapper has no residual horizontal scroll), `scrolls` the many-column
+ * fallback, and `breaks out` whether the wide wrapper spans past the message
+ * column (compared against the fill table, which by construction is exactly
+ * the message column's width).
+ * @param stops - the measured stops, in sweep order.
+ * @param wrapTighter - per table name, whether the block grew taller at the
+ * narrowest stop than at the widest (the proof wrapping engaged).
+ * @returns the golden body, without a trailing newline.
+ */
+function renderGeometry(stops: TableStop[], wrapTighter: Map<string, boolean>): string {
+  return [
+    '# Markdown wide-table relations',
+    '',
+    '| viewport | table | fills the column | scrolls | breaks out past the column |',
+    '| --- | --- | --- | --- | --- |',
+    ...stops.flatMap((stop) => {
+      const columnWidth = stop.tables[0]!.clientWidth
+      return stop.tables.map((table, index) =>
+        `| ${String(stop.width)}px | ${TABLE_NAMES[index]} | ${String(table.overflow <= 1)} `
+        + `| ${String(table.overflow > 1)} | ${String(table.clientWidth > columnWidth + 8)} |`,
+      )
+    }),
+    '',
+    'Wrap-first engagement (taller at the narrowest stop than at the widest):',
+    '',
+    ...[...wrapTighter.entries()].map(([name, tighter]) => `- ${name}: ${String(tighter)}`),
+  ].join('\n')
+}
+
+describe('web e2e: markdown tables fill the column, wide ones break out and scroll', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, wideTableFixture(), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await page.getByText(TAIL_MARKER, { exact: true }).waitFor({ timeout: 15_000 })
+    // Collapse the sidebar and close the details pane for the whole sweep:
+    // classic-scrollbar platforms (Linux CI) lose ~15px of layout width,
+    // which shifts how much of a narrow viewport the panes leave the
+    // transcript and lands the narrow stop's readings far from the macOS
+    // ones — and the details pane alone pins the transcript to exactly the
+    // message column, which would make every breakout relation vacuous.
+    // With both out of the equation the transcript follows the viewport
+    // identically on every platform, which is what keeps one committed
+    // golden true for all lanes.
+    await page.getByRole('button', { name: 'Collapse sidebar', exact: true }).click()
+    // JS click: after the transcript scrolled to its tail, the pane's close
+    // button can sit under the sticky header where a pointer click is
+    // intercepted; the pane itself is scaffolding, not the behavior under
+    // test, so actionability adds nothing here.
+    await closeDetailsPane(page)
+  }, 180_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  /**
+   * Resize to a viewport and read the tables once layout settles (the frame
+   * eases its column tracks, so a read straight after a resize can catch a
+   * mid-transition width).
+   * @param width - viewport width to settle at.
+   * @returns the three tables' readings at that width.
+   */
+  const settleAt = async (width: number): Promise<TableReading[]> => {
+    await page.setViewportSize({ width, height: 900 })
+    // The wide wrapper follows the transcript width (the fill wrapper caps
+    // at the message column and would report "settled" mid-transition).
+    let previousWidth = -1
+    await expect.poll(async () => {
+      const current = (await readTables(page))[1]!.clientWidth
+      const settled = current === previousWidth
+      previousWidth = current
+      return settled
+    }, { timeout: 10_000 }).toBe(true)
+    return readTables(page)
+  }
+
+  /** Sweep once; every assertion reads the same measurement. */
+  let swept: Promise<TableStop[]> | undefined
+  const sweep = (): Promise<TableStop[]> => {
+    swept ??= (async () => {
+      const stops: TableStop[] = []
+      for (const width of WIDTHS) stops.push({ width, tables: await settleAt(width) })
+      return stops
+    })()
+    return swept
+  }
+
+  it('fills narrow tables, scrolls wide ones, and breaks them out where the transcript is wider', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table'))
+    const stops = await sweep()
+    for (const stop of stops) {
+      const [fill, wide, longCell] = stop.tables
+      const columnWidth = fill!.clientWidth
+      // #520: an ordinary wide table fills the message column and wraps…
+      expect(fill!.overflow, `fill viewport ${String(stop.width)}`).toBeLessThanOrEqual(1)
+      // …a long unbroken token and long CJK prose wrap instead of forcing a scroll…
+      expect(longCell!.overflow, `long-cell viewport ${String(stop.width)}`).toBeLessThanOrEqual(1)
+      // …and a many-column table keeps its natural width behind the scroll fallback.
+      expect(wide!.overflow, `wide viewport ${String(stop.width)}`).toBeGreaterThan(1)
+      // The hook is column-count static, present at every stop.
+      expect(wide!.wideHook).toBe(true)
+      expect(fill!.wideHook).toBe(false)
+      expect(longCell!.wideHook).toBe(false)
+      if (stop.width > 748) {
+        // Breakout: the wide wrapper spans past the message column, and its
+        // lead padding keeps the table content starting at the message
+        // column's left edge (compared to the fill table's content).
+        expect(wide!.clientWidth, `wide breakout at ${String(stop.width)}`).toBeGreaterThan(columnWidth + 8)
+        expect(wide!.paddingLeft, `lead at ${String(stop.width)}`).toBeGreaterThan(0)
+        expect(Math.abs(wide!.tableLeft - fill!.tableLeft), `alignment at ${String(stop.width)}`).toBeLessThan(1.5)
+      } else {
+        // Below the message column there is no spare width: the breakout
+        // clamps to neutral and the wrapper stays the column's width.
+        expect(Math.abs(wide!.clientWidth - columnWidth), `neutral at ${String(stop.width)}`).toBeLessThan(1.5)
+        expect(wide!.paddingLeft, `no lead at ${String(stop.width)}`).toBeLessThan(1.5)
+      }
+    }
+    // Wrap-first engaged for real: the filling tables grow taller as the
+    // column narrows (the wide table only scrolls, so it is exempt).
+    const widest = stops[0]!
+    const narrowest = stops[stops.length - 1]!
+    expect(narrowest.tables[0]!.height).toBeGreaterThan(widest.tables[0]!.height)
+    expect(narrowest.tables[2]!.height).toBeGreaterThan(widest.tables[2]!.height)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('keeps the wide table keyboard-scrollable', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table-keyboard'))
+    await sweep()
+    await settleAt(1680)
+    const wide = page.locator('[class*="tableScroll"]', { hasText: WIDE_MARKER })
+    // Chromium makes scrollable containers keyboard-focusable by default;
+    // arrow keys then scroll the focused wrapper.
+    await wide.focus()
+    await page.keyboard.press('ArrowRight')
+    await page.keyboard.press('ArrowRight')
+    await expect.poll(() => wide.evaluate(element => element.scrollLeft), { timeout: 5_000 })
+      .toBeGreaterThan(0)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('keeps the fill/scroll relations under page zoom', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table-zoom'))
+    await sweep()
+    await settleAt(1100)
+    try {
+      await page.evaluate(() => { document.documentElement.style.zoom = '1.25' })
+      await expect.poll(async () => {
+        const [fill, wide, longCell] = await readTables(page)
+        return fill!.overflow <= 1 && longCell!.overflow <= 1 && wide!.overflow > 1
+      }, { timeout: 10_000 }).toBe(true)
+    } finally {
+      await page.evaluate(() => { document.documentElement.style.zoom = '' })
+    }
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('reports the same relations on a high-DPI page', async () => {
+    const hidpiPage = await browser.newPage({
+      viewport: { width: 1100, height: 900 },
+      deviceScaleFactor: 2,
+      locale: 'en-US',
+    })
+    const hidpiTripwire = watchConsole(hidpiPage)
+    try {
+      onTestFailed(() => saveFailureShot(hidpiPage, 'web-e2e-markdown-wide-table-hidpi'))
+      await hidpiPage.goto(scaffold.baseUrl, { waitUntil: 'load' })
+      await hidpiPage.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+      const groupRow = hidpiPage.locator('[role="treeitem"]').first()
+      await groupRow.waitFor({ timeout: 15_000 })
+      await groupRow.click()
+      const sessionRow = hidpiPage.locator('[role="treeitem"]').nth(1)
+      await sessionRow.waitFor({ timeout: 10_000 })
+      await sessionRow.click()
+      await hidpiPage.getByText(TAIL_MARKER, { exact: true }).waitFor({ timeout: 15_000 })
+      await hidpiPage.getByRole('button', { name: 'Collapse sidebar', exact: true }).click()
+      await closeDetailsPane(hidpiPage)
+      // The pane collapses ease over the layout transition: compare only a
+      // settled reading (two consecutive equal wide-wrapper widths).
+      let readings: TableReading[] = []
+      let previousWide = -1
+      await expect.poll(async () => {
+        readings = await readTables(hidpiPage)
+        const settled = readings[1]!.clientWidth === previousWide
+        previousWide = readings[1]!.clientWidth
+        return settled
+      }, { timeout: 10_000 }).toBe(true)
+      const baseline = (await sweep()).find(stop => stop.width === 1100)!
+      const relations = (tables: TableReading[]) => tables.map(table => ({
+        marker: table.marker,
+        fills: table.overflow <= 1,
+        breaksOut: table.clientWidth > tables[0]!.clientWidth + 8,
+      }))
+      expect(relations(readings)).toEqual(relations(baseline.tables))
+      expect(hidpiTripwire.pageErrors).toEqual([])
+    } finally {
+      await hidpiPage.close()
+    }
+  }, 120_000)
+
+  it('matches the committed geometry golden', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table-golden'))
+    const stops = await sweep()
+    const widest = stops[0]!
+    const narrowest = stops[stops.length - 1]!
+    const wrapTighter = new Map<string, boolean>([
+      ['fill', narrowest.tables[0]!.height > widest.tables[0]!.height],
+      ['long-cell', narrowest.tables[2]!.height > widest.tables[2]!.height],
+    ])
+    await compareOrRefreshGolden(GEOMETRY_EXPECTED, renderGeometry(stops, wrapTighter), MODE)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('commits exactly the fixtures it reads', async () => {
+    // No model calls, so no replay log: the golden is the whole inventory.
+    await assertFixtureInventory(SNAPSHOT_DIR, ['geometry.expected.md'])
+  })
+
+  it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', () => {
+    expect(tripwire.warnings).toEqual([])
+    expect(tripwire.pageErrors).toEqual([])
+  })
+})
diff --git a/apps/web/tests/snapshots/markdown-wide-table/geometry.expected.md b/apps/web/tests/snapshots/markdown-wide-table/geometry.expected.md
new file mode 100644
index 0000000000..0e195a6bba
--- /dev/null
+++ b/apps/web/tests/snapshots/markdown-wide-table/geometry.expected.md
@@ -0,0 +1,18 @@
+# Markdown wide-table relations
+
+| viewport | table | fills the column | scrolls | breaks out past the column |
+| --- | --- | --- | --- | --- |
+| 1680px | fill | true | false | false |
+| 1680px | wide | false | true | true |
+| 1680px | long-cell | true | false | false |
+| 1100px | fill | true | false | false |
+| 1100px | wide | false | true | true |
+| 1100px | long-cell | true | false | false |
+| 640px | fill | true | false | false |
+| 640px | wide | false | true | false |
+| 640px | long-cell | true | false | false |
+
+Wrap-first engagement (taller at the narrowest stop than at the widest):
+
+- fill: true
+- long-cell: true
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 111aefe63c..38a0438ef9 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -64,6 +64,7 @@
     "tests/message-feedback-layout.e2e.ts",
     "tests/markdown-images.e2e.ts",
     "tests/reference-composer.e2e.ts",
+    "tests/markdown-wide-table.e2e.ts",
     "tests/math-rendering.e2e.ts",
     "tests/markdown-cjk-strong.e2e.ts",
     "tests/markdown-inline-code-links.e2e.ts",
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
index 8fdba2baa0..c9e8d19d77 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
@@ -17,6 +17,28 @@
   gap: 16px;
 }
 
+/* Wide markdown tables (the renderer's ≥4-column md-table-wide hook) span
+   the whole transcript width instead of clipping at the 748px message
+   column, while the table content keeps starting at its normal x (the lead
+   padding compensates the negative margin) — deepsuite chat TableWrapper
+   parity, with 100cqw (the ChatView scroll container) standing in for its
+   JS-measured --dsl-virtual-list-width. `--dsh-table-spare` clamps to zero
+   when the transcript is narrower than the message column, so narrow
+   viewports keep the plain in-column scroll with no sideways shift.
+   Percentages resolve against the wrapper's containing block, so a table
+   indented inside a list still reaches the same transcript edges. */
+.body :global(.md-table-wide) {
+  --dsh-table-spare: max(0px, calc((100cqw - var(--dsh-chat-content-width)) / 2));
+  --dsh-table-lead: calc(var(--dsh-table-spare) + min(var(--dsh-chat-content-width), 100cqw) - 100%);
+  box-sizing: border-box;
+  width: calc(100% + var(--dsh-table-lead) + var(--dsh-table-spare));
+  /* The base .tableScroll caps at the column (max-width: 100%); the breakout
+     is exactly the case that must exceed it. */
+  max-width: none;
+  margin-left: calc(-1 * var(--dsh-table-lead));
+  padding-left: var(--dsh-table-lead);
+}
+
 /* Interrupted-turn terminal marker: quiet inline tag, no animation. */
 .stopped {
   align-self: flex-start;
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
index ffee12984f..73fa688f95 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -18,6 +18,11 @@
   /* Sides = composer clearance + 16px: on narrow viewports the transcript
      stays exactly 32px narrower than the input card (the shared width rule). */
   padding: 16px calc(var(--dsh-composer-side-clearance) + 16px);
+  /* Inline-size query container: wide markdown tables size their breakout
+     against this box's content width (100cqw in AssistantMarkdown's
+     md-table-wide rule) — the CSS stand-in for deepsuite chat's JS-measured
+     --dsl-virtual-list-width. */
+  container-type: inline-size;
 }
 
 :global([data-conversation-scroll]) .root {
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 06ca10e568..6856283fcc 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.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 packages/client/ui-primitives/README.md
-README.md: a675b3cd0aa9e09e243b69065110e1d2b67ff1d9
-README.zh.md: aa67993ec879635fc0677501665d2e23de996dcf
+README.md: 0d7848112b650a322965ad52a38d23e0145e7921
+README.zh.md: 475af21d5a7bc1bc48115b171d92b9a0d44df309
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index a675b3cd0a..0d7848112b 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -14,7 +14,7 @@ Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/P
 
 ## Markdown rendering
 
-`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
+`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). Tables size by column count (deepsuite chat parity): under four columns — or inside a blockquote — a table fills its column and wraps cell text down to the cells' minimum readable width, while four-or-more-column tables keep their natural width, scroll horizontally inside their wrapper, and carry the stable `md-table-wide` class so a hosting layout can widen the wrapper past its column (the chat transcript's container-query breakout in `dsh-client-ui-conversation`); Chromium keyboard-focuses the scrollable wrapper by default ([decision record](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
 
 ## Terminal output
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index aa67993ec8..475af21d5a 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -14,7 +14,7 @@
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。表格按列数决定尺寸（对齐 deepsuite chat）：不足四列——或位于 blockquote 内——的表格填满所在列，单元格文本换行收缩至最小可读列宽；四列及以上的表格保持自然宽度、在包裹层内横向滚动，并携带稳定的 `md-table-wide` 类，供宿主布局把包裹层加宽到所在列之外（`dsh-client-ui-conversation` 中聊天转录区的容器查询突破样式）；Chromium 默认让可滚动包裹层可键盘聚焦（[决策记录](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index b62e66e86e..969cf41342 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -177,12 +177,31 @@
   overscroll-behavior-x: contain;
 }
 
+/* Chromium keyboard-focuses scrollable containers by default; the ring uses
+   the sheet's link focus color. */
+.tableScroll:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--dsw-alias-state-business-primary);
+}
+
+/* Many-column tables (the renderer's `md-table-wide` hook) keep their
+   natural width and scroll inside the wrapper; a hosting layout may widen
+   the wrapper through the hook (deepsuite chat TableWrapper parity). */
 .tableScroll table {
   border-collapse: collapse;
   width: max-content;
   max-width: max-content;
 }
 
+/* Tables under four columns, and any table inside a blockquote, fill the
+   column instead: cells wrap down to their minimum readable width, and the
+   wrapper's scroll only remains for the below-floor case (deepsuite chat
+   parity: `.wrapper:not(:has(th:nth-child(4), td:nth-child(4)))`). */
+.tableFill table {
+  width: 100%;
+  max-width: none;
+}
+
 .tableScroll th {
   text-align: start;
   padding: 10px 16px;
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 452e0fc475..12d73bb44b 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -18,6 +18,7 @@
 
 import { Fragment, createElement } from 'react'
 import type { Key, ReactNode } from 'react'
+import clsx from 'clsx'
 import type * as Md from 'mdast'
 import type {} from 'mdast-util-math'
 import { normalizeUri } from 'micromark-util-sanitize-uri'
@@ -123,6 +124,8 @@ export interface MarkdownRenderContext {
   readonly streaming: boolean
   /** Localized fence copy-button labels. */
   readonly codeLabels: MarkdownCodeLabels | undefined
+  /** Inside a blockquote's children: tables there always fill the quote's width. */
+  readonly inBlockquote?: boolean
   /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
   readonly fileMentions: MarkdownFileMentions | undefined
   /** Inside an anchor's children: interactive mentions must not nest there. */
@@ -213,7 +216,10 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
     case 'blockquote':
       return (
         <blockquote key={key}>
-          {wrapBlockChildren(renderChildren(node.children, context).filter(child => child !== null), true)}
+          {wrapBlockChildren(
+            renderChildren(node.children, { ...context, inBlockquote: true }).filter(child => child !== null),
+            true,
+          )}
         </blockquote>
       )
     case 'thematicBreak':
@@ -393,8 +399,15 @@ function renderListItem(
 function renderTable(node: Md.Table, key: Key, context: MarkdownRenderContext): ReactNode {
   const align = node.align ?? null
   const [headRow, ...bodyRows] = node.children
+  const columns = align === null ? headRow?.children.length ?? 0 : align.length
+  // Four or more columns read as a comparison matrix: the wrapper keeps the
+  // table at natural width and exposes the stable `md-table-wide` hook so a
+  // hosting layout (the chat transcript) can widen it past the message
+  // column. Narrower tables — and any table inside a blockquote — fill the
+  // column and wrap instead (deepsuite chat TableWrapper parity).
+  const wide = columns >= 4 && context.inBlockquote !== true
   return (
-    <div key={key} className={css.tableScroll}>
+    <div key={key} className={clsx(css.tableScroll, wide ? 'md-table-wide' : css.tableFill)}>
       <table>
         {headRow !== undefined && <thead>{renderTableRow(headRow, 'th', align, 0, context)}</thead>}
         {bodyRows.length > 0 && (
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.settled.txt
index cf6b2ba4ad..83b008e2d5 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.settled.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.settled.txt
@@ -22,7 +22,7 @@
     #text "Unbalanced errors render the error arm: "
     <span class="katex-error" style="color: rgb(204, 0, 0);" title="ParseError: KaTeX parse error: Unexpected end of input in a macro argument, expected '}' at end of input: \\frac{">
       #text "\\frac{"
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 _tableFill_404681">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.streaming.txt
index 639a2fca84..a56b3c338d 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.streaming.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/math-edge-cases.streaming.txt
@@ -3,7 +3,7 @@
     #text "Trusted commands stay off: $\\href{javascript:alert(1)}{unsafe}$."
   <p>
     #text "Unbalanced errors render the error arm: $\\frac{$"
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 _tableFill_404681">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.settled.txt
index 2c2d9d7e0f..ba1552d480 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.settled.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.settled.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 _tableFill_404681">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.streaming.txt
index 2c2d9d7e0f..ba1552d480 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.streaming.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-header-only.streaming.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 _tableFill_404681">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
new file mode 100644
index 0000000000..9b805440be
--- /dev/null
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
@@ -0,0 +1,46 @@
+<div class="_markdown_404681">
+  <div class="_tableScroll_404681 md-table-wide">
+    <table>
+      <thead>
+        <tr>
+          <th>
+            #text "C1"
+          <th>
+            #text "C2"
+          <th>
+            #text "C3"
+          <th>
+            #text "C4"
+      <tbody>
+        <tr>
+          <td>
+            #text "a"
+          <td>
+            #text "b"
+          <td>
+            #text "c"
+          <td>
+            #text "d"
+  <blockquote>
+    <div class="_tableScroll_404681 _tableFill_404681">
+      <table>
+        <thead>
+          <tr>
+            <th>
+              #text "Q1"
+            <th>
+              #text "Q2"
+            <th>
+              #text "Q3"
+            <th>
+              #text "Q4"
+        <tbody>
+          <tr>
+            <td>
+              #text "a"
+            <td>
+              #text "b"
+            <td>
+              #text "c"
+            <td>
+              #text "d"
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt
new file mode 100644
index 0000000000..9b805440be
--- /dev/null
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt
@@ -0,0 +1,46 @@
+<div class="_markdown_404681">
+  <div class="_tableScroll_404681 md-table-wide">
+    <table>
+      <thead>
+        <tr>
+          <th>
+            #text "C1"
+          <th>
+            #text "C2"
+          <th>
+            #text "C3"
+          <th>
+            #text "C4"
+      <tbody>
+        <tr>
+          <td>
+            #text "a"
+          <td>
+            #text "b"
+          <td>
+            #text "c"
+          <td>
+            #text "d"
+  <blockquote>
+    <div class="_tableScroll_404681 _tableFill_404681">
+      <table>
+        <thead>
+          <tr>
+            <th>
+              #text "Q1"
+            <th>
+              #text "Q2"
+            <th>
+              #text "Q3"
+            <th>
+              #text "Q4"
+        <tbody>
+          <tr>
+            <td>
+              #text "a"
+            <td>
+              #text "b"
+            <td>
+              #text "c"
+            <td>
+              #text "d"
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
index 6a669ffe2f..2ce936ddcc 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 md-table-wide">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
index 6a669ffe2f..2ce936ddcc 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681">
+  <div class="_tableScroll_404681 md-table-wide">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
index 70197763da..093b84a133 100644
--- a/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
@@ -163,6 +163,17 @@ const CORPUS: Record<string, string> = {
     'after',
   ].join('\n'),
   'table-header-only': '| a | b |\n| --- | --- |\n\nafter',
+  // Four columns take the md-table-wide hook at top level; the same table
+  // inside a blockquote falls back to the fill arm.
+  'table-wide-and-blockquote': [
+    '| C1 | C2 | C3 | C4 |',
+    '| --- | --- | --- | --- |',
+    '| a | b | c | d |',
+    '',
+    '> | Q1 | Q2 | Q3 | Q4 |',
+    '> | --- | --- | --- | --- |',
+    '> | a | b | c | d |',
+  ].join('\n'),
   'inline-code-with-newline': 'Spans `a\nb` across a line.',
   'links-and-autolinks': [
     '[https ok](https://example.com "with title") and [mailto ok](mailto:dev@example.com).',
diff --git a/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
index 48f59c7479..dbad9ef164 100644
--- a/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
@@ -101,6 +101,14 @@ describe('renderBlocks over hand-built trees', () => {
     expect(container.querySelector('td')?.textContent).toBe('short')
   })
 
+  it('renders a rowless align-less table as an empty fill wrapper', () => {
+    // Zero columns is below the wide threshold, so the fill arm applies.
+    const container = renderNodes([{ type: 'table', children: [] }])
+    const wrapper = container.querySelector('table')?.parentElement
+    expect(wrapper?.className).not.toContain('md-table-wide')
+    expect(container.querySelector('table')?.childElementCount).toBe(0)
+  })
+
   it('pads rows against the alignment width with empty cells', () => {
     const container = renderNodes([
       {
diff --git a/tsconfig.host.json b/tsconfig.host.json
index bb885e7ecc..d0b5808a48 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -51,6 +51,7 @@
     "apps/web/tests/message-feedback-layout.e2e.ts",
     "apps/web/tests/markdown-images.e2e.ts",
     "apps/web/tests/reference-composer.e2e.ts",
+    "apps/web/tests/markdown-wide-table.e2e.ts",
     "apps/web/tests/math-rendering.e2e.ts",
     "apps/web/tests/markdown-cjk-strong.e2e.ts",
     "apps/web/tests/markdown-inline-code-links.e2e.ts",

From a33ed4ddf8c762e98759b7725f5095046ca270b4 Mon Sep 17 00:00:00 2001
From: Chinesezjc <jczhai@deepseek.com>
Date: Thu, 20 Aug 2026 13:15:58 +0800
Subject: [PATCH 04/34] ci: stop PR gray checks from lifecycle and release
 publish jobs

Remove the three skipped (gray) checks from the PR check panel without changing
functional semantics:

- issue-lifecycle: remove the job-level 'if' that skipped the lifecycle job on
  non-changes-requested pull_request_review events, so it now runs and reports
  success (the lifecycle handler already no-ops for approved/commented reviews).
  The changes-requested board transition is unchanged.
- release.yml / release-vendor.yml: drop the publish job (and its
  workflow_dispatch 'publish' input + RELEASE_PUBLISH pass-through) so it no
  longer appears as a skipped Publish-to-npm check on PRs; the files keep the
  pack job that validates tarballs on PR/push.
- new release-publish.yml / release-vendor-publish.yml: manual workflow_dispatch
  only, repack on the current tree then publish, so publication behaves exactly
  as the old publish job (explicit dispatch, uses the packed bytes) but never
  shows as a PR check.

Update the 2026-08-10 review-status note (en/zh/i18n) and the issue-lifecycle
spec assertion to match the unconditional lifecycle job.

Verification: ci-workflow.spec.ts 19/19, all five workflows YAML-parse, typecheck
clean, verify-translation-pairing consistent, note-format 582.
---
 ...-event-directed-pr-review-status.i18n.yaml |   4 +-
 ...6-08-10-event-directed-pr-review-status.md |   4 +-
 ...8-10-event-directed-pr-review-status.zh.md |   4 +-
 .github/workflows/issue-lifecycle.yml         |   5 +-
 .github/workflows/release-publish.yml         | 131 ++++++++++++++++++
 .github/workflows/release-vendor-publish.yml  | 114 +++++++++++++++
 .github/workflows/release-vendor.yml          |  61 +-------
 .github/workflows/release.yml                 |  63 +--------
 scripts/ci-workflow.spec.ts                   |  22 +--
 9 files changed, 279 insertions(+), 129 deletions(-)
 create mode 100644 .github/workflows/release-publish.yml
 create mode 100644 .github/workflows/release-vendor-publish.yml

diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml
index 08607d5317..f3f9f10975 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.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/process/2026-08-10-event-directed-pr-review-status.md
-2026-08-10-event-directed-pr-review-status.md: 9db9c64fc87c1701028ae825357c3cbd7fef44d1
-2026-08-10-event-directed-pr-review-status.zh.md: 381a3f64a62930a584f48cfbc3571679bbcbcef7
+2026-08-10-event-directed-pr-review-status.md: bdaaa07c47d45eb002ed7c026683a800f67d0fca
+2026-08-10-event-directed-pr-review-status.zh.md: 0ca4154a78e82156687b4fc5efb62745f3b2af63
diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
index 9db9c64fc8..bdaaa07c47 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
@@ -12,7 +12,7 @@ A monotonic projection also cannot return an automation-owned Issue from `In rev
 
 ## Decision
 
-The Issue lifecycle workflow treats review webhooks as commands. `pull_request.review_requested`, including a repeated request, targets `In review`. `pull_request_review.submitted` targets `In progress` only when `review.state` is `changes_requested`; the submitted event remains necessary because a reviewer can request changes without an earlier review-request event. Approved and commented submissions skip their lifecycle job before it creates a Project token, while dismissed reviews are not subscribed.
+The Issue lifecycle workflow treats review webhooks as commands. `pull_request.review_requested`, including a repeated request, targets `In review`. `pull_request_review.submitted` targets `In progress` only when `review.state` is `changes_requested`; the submitted event remains necessary because a reviewer can request changes without an earlier review-request event. Approved and commented submissions run their lifecycle job but no-op (they never reach the Project token step), while dismissed reviews are not subscribed.
 
 Ordinary subscribed pull-request events remain forward-only implementation signals: they can move `Inbox`, `Backlog`, or `Ready` to `In progress`, but they cannot move `In review` backward. Review-request commands can move any earlier active status to `In review`. Changes-requested commands can move earlier active statuses forward to `In progress` and can move `In review` back only when the latest status event for the target Project was written by the configured lifecycle actor. A human or unknown latest actor preserves the current status.
 
@@ -22,7 +22,7 @@ The handler resolves only exact same-repository `Fixes`, `Closes`, or `Resolves`
 
 ## Verification
 
-[Issue-management tests](../../../../.github/issue-management/policy.test.mjs) pin the event-to-command mapping, the repeated-review-request transition after a changes-requested command, the changes-requested regression, terminal protection, and human override preservation. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the subscribed events, the changes-requested job condition, and the separate `ready_for_review` policy trigger.
+[Issue-management tests](../../../../.github/issue-management/policy.test.mjs) pin the event-to-command mapping, the repeated-review-request transition after a changes-requested command, the changes-requested regression, terminal protection, and human override preservation. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the subscribed events, the absence of a job-level `if` (so approved/commented reviews pass rather than skip), and the separate `ready_for_review` policy trigger.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
index 381a3f64a6..0ca4154a78 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
@@ -12,7 +12,7 @@ Issue 所在 Project 中的状态记录了解决工作的下一步由谁负责
 
 ## 决策
 
-Issue 生命周期工作流把评审 webhook 视为命令。`pull_request.review_requested`（包括重复请求）将目标状态指定为 `In review`。`pull_request_review.submitted` 将目标状态指定为 `In progress`，但仅在 `review.state` 为 `changes_requested` 时生效；submitted 事件仍不可省略，因为评审人即使没有先触发 review-request 事件，也可以直接提出修改要求。对于 approved 和 commented 提交，工作流会在生命周期作业创建 Project token 前跳过该作业；dismissed 评审则不在订阅范围内。
+Issue 生命周期工作流把评审 webhook 视为命令。`pull_request.review_requested`（包括重复请求）将目标状态指定为 `In review`。`pull_request_review.submitted` 将目标状态指定为 `In progress`，但仅在 `review.state` 为 `changes_requested` 时生效；submitted 事件仍不可省略，因为评审人即使没有先触发 review-request 事件，也可以直接提出修改要求。对于 approved 和 commented 提交，生命周期作业会运行但空操作（不会走到创建 Project token 一步）；dismissed 评审则不在订阅范围内。
 
 工作流订阅的普通 PR 事件仍是只向前推进的实现信号：它们可以将 `Inbox`、`Backlog` 或 `Ready` 推进至 `In progress`，但不能让 `In review` 倒退。请求评审命令可将任意较早的活跃状态推进至 `In review`。请求修改命令可将较早的活跃状态推进至 `In progress`；它也可以让 `In review` 状态回退，但仅在目标 Project 的最新状态事件由配置的生命周期执行主体写入时进行。若最新状态事件的执行主体是人工用户或未知主体，则保留当前状态。
 
@@ -22,7 +22,7 @@ Issue 生命周期工作流把评审 webhook 视为命令。`pull_request.review
 
 ## 验证
 
-[Issue 管理测试](../../../../.github/issue-management/policy.test.mjs)锁定事件到命令的映射、请求修改命令后重复请求评审所触发的状态转换、请求修改后的状态回退、终态保护，以及保留人工覆盖状态。[工作流测试](../../../../scripts/ci-workflow.spec.ts)锁定订阅事件、请求修改作业的条件，以及独立的 `ready_for_review` 策略触发器。
+[Issue 管理测试](../../../../.github/issue-management/policy.test.mjs)锁定事件到命令的映射、请求修改命令后重复请求评审所触发的状态转换、请求修改后的状态回退、终态保护，以及保留人工覆盖状态。[工作流测试](../../../../scripts/ci-workflow.spec.ts)锁定订阅事件、作业无 job 级 `if`（使 approved/commented 评审以 pass 而非 skip 呈现），以及独立的 `ready_for_review` 策略触发器。
 
 ## 考虑过的替代方案
 
diff --git a/.github/workflows/issue-lifecycle.yml b/.github/workflows/issue-lifecycle.yml
index e324cfefc2..70732de6a2 100644
--- a/.github/workflows/issue-lifecycle.yml
+++ b/.github/workflows/issue-lifecycle.yml
@@ -36,7 +36,10 @@ concurrency:
 jobs:
   lifecycle:
     name: Issue lifecycle
-    if: ${{ github.event_name != 'pull_request_review' || (github.event.action == 'submitted' && github.event.review.state == 'changes_requested') }}
+    # Run on every pull_request_review event, not only changes_requested, so the
+    # check shows a passing result instead of a gray "skipped" segment. The
+    # lifecycle handler itself no-ops (returns success) for approved/commented
+    # reviews; only a changes_requested review drives the Project board.
     runs-on: ubuntu-latest
     steps:
       - name: Check out trusted policy
diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml
new file mode 100644
index 0000000000..7107ba0073
--- /dev/null
+++ b/.github/workflows/release-publish.yml
@@ -0,0 +1,131 @@
+# Publish the dsh release sequence to npm. This workflow is manual-only
+# (workflow_dispatch) and intentionally does not listen to pull_request or push:
+# publication must always be an explicit, reviewed act from a dsh-v* tag, and it
+# must never appear as a PR check. It repacks the current tree before publishing
+# so the bytes uploaded are exactly what this dispatch produced.
+name: Release publish (dsh)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PRIMARY_NODE_VERSION: '24'
+  DSH_TELEMETRY_DISABLED: '1'
+
+jobs:
+  pack:
+    name: Pack npm tarballs
+    runs-on: ubuntu-24.04
+    steps:
+      # Complete history: the release scripts read tags.
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Configure pnpm store path
+        id: pnpm-store
+        run: |
+          store_root="$HOME/.local/share/pnpm/store"
+          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
+          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
+          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      - name: Install (immutable)
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify release version
+        env:
+          RELEASE_PUBLISH: 'true'
+        run: pnpm run release:verify --family dsh
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Pack release tarballs
+        run: pnpm run release:pack --family dsh --out dist/npm
+
+      # The harness packages declare the vendored framework as a peer, and this
+      # verification must not depend on the registry already carrying matching
+      # versions — one pull request may bump both families before either
+      # publishes — so it installs that family's pack output too. Only dist/npm
+      # is published.
+      - name: Pack the vendored framework for verification
+        run: pnpm run release:pack --family vendor --out dist/npm-vendor
+
+      # dsh-sandbox-local declares the Landlock entry as a runtime dependency, so
+      # the verification needs its tarball. Its platform packages stay out: they
+      # are optional, and building them needs a musl toolchain per architecture.
+      - name: Pack the Landlock entry for verification
+        run: |
+          pnpm --dir native/landlock-run run build:ts
+          pnpm --dir native/landlock-run/packages/entry pack --pack-destination "$PWD/dist/npm-landlock"
+
+      - name: Verify packed install
+        run: pnpm run release:verify-packed-install --family dsh --from dist/npm --from dist/npm-vendor --from dist/npm-landlock
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dsh-npm-tarballs
+          path: dist/npm/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to npm
+    needs: pack
+    runs-on: ubuntu-24.04
+    # Required reviewers and the allowed tags live on the environment; this is
+    # the only job in the sequence that can write to the registry.
+    environment: npm-publish
+    concurrency:
+      group: Release-publish
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    steps:
+      # Checkout and install carry the release scripts only. There is no build
+      # step: publication uploads the bytes the pack job produced.
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Install (immutable, no package scripts)
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dsh-npm-tarballs
+          path: dist/npm
+
+      - name: Publish tarballs
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm run release:publish --family dsh --from dist/npm
diff --git a/.github/workflows/release-vendor-publish.yml b/.github/workflows/release-vendor-publish.yml
new file mode 100644
index 0000000000..a50a408025
--- /dev/null
+++ b/.github/workflows/release-vendor-publish.yml
@@ -0,0 +1,114 @@
+# Publish the vendored framework sequence to npm. This workflow is manual-only
+# (workflow_dispatch) and intentionally does not listen to pull_request or push:
+# publication must always be an explicit, reviewed act from a vendor-* tag, and
+# it must never appear as a PR check. It repacks the current tree before
+# publishing so the bytes uploaded are exactly what this dispatch produced.
+name: Release publish (vendor)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PRIMARY_NODE_VERSION: '24'
+  DSH_TELEMETRY_DISABLED: '1'
+
+jobs:
+  pack:
+    name: Pack npm tarballs
+    runs-on: ubuntu-24.04
+    steps:
+      # Complete history: the release scripts read tags.
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Configure pnpm store path
+        id: pnpm-store
+        run: |
+          store_root="$HOME/.local/share/pnpm/store"
+          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
+          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
+          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      - name: Install (immutable)
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify release version
+        env:
+          RELEASE_PUBLISH: 'true'
+        run: pnpm run release:verify --family vendor
+
+      # The vendored packages publish their own sources and build outputs; the
+      # host build produces what their manifests select.
+      - name: Build
+        run: pnpm run build:lib:host
+
+      - name: Pack release tarballs
+        run: pnpm run release:pack --family vendor --out dist/npm-vendor
+
+      - name: Verify packed install
+        run: pnpm run release:verify-packed-install --family vendor --from dist/npm-vendor
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: vendor-npm-tarballs
+          path: dist/npm-vendor/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to npm
+    needs: pack
+    runs-on: ubuntu-24.04
+    environment: npm-publish
+    concurrency:
+      group: Release-publish
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    steps:
+      # Checkout and install carry the release scripts only; no build step.
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Install (immutable, no package scripts)
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: vendor-npm-tarballs
+          path: dist/npm-vendor
+
+      - name: Publish tarballs
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm run release:publish --family vendor --from dist/npm-vendor
diff --git a/.github/workflows/release-vendor.yml b/.github/workflows/release-vendor.yml
index c8af47251e..34290bb7a2 100644
--- a/.github/workflows/release-vendor.yml
+++ b/.github/workflows/release-vendor.yml
@@ -1,10 +1,11 @@
-# Pack and publish the vendored framework sequence: the nine rescoped Cordis
-# packages under vendor/, each on its own version line. This sequence releases
-# independently of dsh and of the native packages.
+# Pack the vendored framework sequence: the nine rescoped Cordis packages under
+# vendor/, each on its own version line. This sequence releases independently of
+# dsh and of the native packages.
 #
 # Pack runs without credentials on every pull request and master push.
-# Publication is a manual dispatch from a vendor-* tag; a vendor release can
-# carry several versions, so each package has its own tag.
+# Publication is a manual workflow_dispatch of release-vendor-publish.yml from a
+# vendor-* tag; a vendor release can carry several versions, so each package has
+# its own tag.
 name: Release (vendor)
 
 on:
@@ -12,19 +13,12 @@ on:
   push:
     branches: [master]
   workflow_dispatch:
-    inputs:
-      publish:
-        description: Publish the packed tarballs to npm. Must run from a vendor-* tag.
-        required: true
-        type: boolean
-        default: false
 
 permissions:
   contents: read
 
 concurrency:
-  # Pack runs per ref so concurrent pull requests never displace each
-  # other; the publish job below serializes the shared dist-tag state.
+  # Pack runs per ref so concurrent pull requests never displace each other.
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: false
 
@@ -70,8 +64,6 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Verify release version
-        env:
-          RELEASE_PUBLISH: ${{ inputs.publish }}
         run: pnpm run release:verify --family vendor
 
       # The vendored packages publish their own sources and build outputs; the
@@ -91,42 +83,3 @@ jobs:
           path: dist/npm-vendor/*
           if-no-files-found: error
           retention-days: 7
-
-  publish:
-    name: Publish to npm
-    if: inputs.publish
-    needs: pack
-    runs-on: ubuntu-24.04
-    environment: npm-publish
-    concurrency:
-      group: Release-publish
-      cancel-in-progress: false
-    permissions:
-      contents: read
-    steps:
-      # Checkout and install carry the release scripts only; no build step.
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: pnpm/action-setup@v4
-        with:
-          dest: ${{ runner.temp }}/setup-pnpm
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.PRIMARY_NODE_VERSION }}
-          registry-url: https://registry.npmjs.org
-
-      - name: Install (immutable, no package scripts)
-        run: pnpm install --frozen-lockfile --ignore-scripts
-
-      - uses: actions/download-artifact@v4
-        with:
-          name: vendor-npm-tarballs
-          path: dist/npm-vendor
-
-      - name: Publish tarballs
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm run release:publish --family vendor --from dist/npm-vendor
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 08296468bf..2b84a299b9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,10 +1,10 @@
-# Pack and publish the dsh release sequence: every package under packages/ plus
-# the apps/ entries, all on one version. The vendored framework and the native
-# packages are separate sequences with their own workflows and version lines.
+# Pack the dsh release sequence: every package under packages/ plus the apps/
+# entries, all on one version. The vendored framework and the native packages are
+# separate sequences with their own workflows and version lines.
 #
 # Pack runs without credentials on every pull request and master push, so a
-# pull request proves the whole publish set still packs. Publication is a
-# manual dispatch from a dsh-v* tag and consumes exactly the packed bytes.
+# pull request proves the whole publish set still packs. Publication is a manual
+# workflow_dispatch of release-publish.yml from a dsh-v* tag.
 name: Release (dsh)
 
 on:
@@ -12,19 +12,12 @@ on:
   push:
     branches: [master]
   workflow_dispatch:
-    inputs:
-      publish:
-        description: Publish the packed tarballs to npm. Must run from a dsh-v* tag.
-        required: true
-        type: boolean
-        default: false
 
 permissions:
   contents: read
 
 concurrency:
-  # Pack runs per ref so concurrent pull requests never displace each
-  # other; the publish job below serializes the shared dist-tag state.
+  # Pack runs per ref so concurrent pull requests never displace each other.
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: false
 
@@ -70,8 +63,6 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Verify release version
-        env:
-          RELEASE_PUBLISH: ${{ inputs.publish }}
         run: pnpm run release:verify --family dsh
 
       - name: Build
@@ -105,45 +96,3 @@ jobs:
           path: dist/npm/*
           if-no-files-found: error
           retention-days: 7
-
-  publish:
-    name: Publish to npm
-    if: inputs.publish
-    needs: pack
-    runs-on: ubuntu-24.04
-    # Required reviewers and the allowed tags live on the environment; this is
-    # the only step in the sequence that can write to the registry.
-    environment: npm-publish
-    concurrency:
-      group: Release-publish
-      cancel-in-progress: false
-    permissions:
-      contents: read
-    steps:
-      # Checkout and install carry the release scripts only. There is no build
-      # step: publication uploads the bytes the pack job produced.
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: pnpm/action-setup@v4
-        with:
-          dest: ${{ runner.temp }}/setup-pnpm
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.PRIMARY_NODE_VERSION }}
-          registry-url: https://registry.npmjs.org
-
-      - name: Install (immutable, no package scripts)
-        run: pnpm install --frozen-lockfile --ignore-scripts
-
-      - uses: actions/download-artifact@v4
-        with:
-          name: dsh-npm-tarballs
-          path: dist/npm
-
-      - name: Publish tarballs
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm run release:publish --family dsh --from dist/npm
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 721c9987b6..a13ceafe47 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -417,20 +417,20 @@ describe('Python release workflows', () => {
 })
 
 describe('Issue lifecycle workflow', () => {
-  it('uses explicit review handoff events without rerunning when a draft becomes ready', () => {
+  it('runs the lifecycle job on every PR/review event so it passes instead of skipping', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
-    const lifecyclePullRequest = workflowEvent(lifecycle, 'pull_request')
-    const lifecycleReview = workflowEvent(lifecycle, 'pull_request_review')
-    const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
     const policy = loadWorkflow('.github/workflows/issue-policy.yml')
-    const policyPullRequest = workflowEvent(policy, 'pull_request')
+    const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
 
-    expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
-    expect(lifecyclePullRequest.types).toContain('review_requested')
-    expect(lifecycleReview.types).toEqual(['submitted'])
-    expect(lifecycleJob.if).toBe(
-      "${{ github.event_name != 'pull_request_review' || (github.event.action == 'submitted' && github.event.review.state == 'changes_requested') }}",
-    )
+    // The lifecycle job has no workflow-level `if`, so it is listed on every
+    // pull_request / pull_request_review event and reports success (the handler
+    // no-ops for non-changes-requested reviews) instead of a gray "skipped" check.
+    expect(lifecycle.on).toHaveProperty('pull_request')
+    expect(lifecycle.on).toHaveProperty('pull_request_review')
+    expect(lifecycleJob.if).toBeUndefined()
+
+    // issue-policy owns PR validation; it is read-only and a real gate.
+    const policyPullRequest = workflowEvent(policy, 'pull_request')
     expect(policyPullRequest.types).toContain('ready_for_review')
   })
 })

From c9ce61136d3665c3d9e8591281c33d4600093c9f Mon Sep 17 00:00:00 2001
From: 07akioni <07akioni2@gmail.com>
Date: Thu, 20 Aug 2026 14:45:15 +0800
Subject: [PATCH 05/34] feat(web): reveal the wide-table scrollbar on hover
 instead of painting it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The themed WebKit scrollbar skin keeps a wide table's horizontal bar
permanently painted. Chromium never repaints state-conditioned scrollbar
styles (hover-conditioned ::-webkit-scrollbar* rules and :hover
scrollbar-color changes both compute but never reach the painted bar,
measured headed and headless), so the hover reveal toggles overflow-x
itself: hidden at rest with a padding-bottom matching the themed bar
height, auto on hover or keyboard focus with the padding released — the
appearing bar exactly replaces the padding and nothing below shifts.
Resting hidden overflow drops Chromium's implicit scroller focusability,
so wide wrappers carry an explicit tabindex for arrow-key scrolling.
---
 ...-19-web-markdown-wide-table-view.i18n.yaml |  4 +--
 ...2026-08-19-web-markdown-wide-table-view.md |  2 +-
 ...6-08-19-web-markdown-wide-table-view.zh.md |  2 +-
 apps/web/tests/markdown-wide-table.e2e.ts     | 28 +++++++++++++++++++
 .../client/ui-primitives/README.i18n.yaml     |  4 +--
 packages/client/ui-primitives/README.md       |  2 +-
 packages/client/ui-primitives/README.zh.md    |  2 +-
 .../src/markdown/MarkdownText.module.css      | 20 +++++++++++++
 .../ui-primitives/src/markdown/render.tsx     | 12 ++++++--
 .../table-wide-and-blockquote.settled.txt     |  2 +-
 .../table-wide-and-blockquote.streaming.txt   |  2 +-
 .../table-with-alignment.settled.txt          |  2 +-
 .../table-with-alignment.streaming.txt        |  2 +-
 13 files changed, 70 insertions(+), 14 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml
index 19561bb6f0..e4b5654510 100644
--- a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.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/feature/2026-08-19-web-markdown-wide-table-view.md
-2026-08-19-web-markdown-wide-table-view.md: 847b3f055edd29eeb0b6f3f8bec5b97252aca4f4
-2026-08-19-web-markdown-wide-table-view.zh.md: d2fcc18f883f71a3fdbfbab6476c87b1c9840b21
+2026-08-19-web-markdown-wide-table-view.md: fc025f6755caa2ca160b02f0c03ae80fd04cc1c7
+2026-08-19-web-markdown-wide-table-view.zh.md: 4d13a29f69fac31f9796dae064726d4d3a779ffd
diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
index 847b3f055e..fc025f6755 100644
--- a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md
@@ -26,7 +26,7 @@ English | [中文](2026-08-19-web-markdown-wide-table-view.zh.md)
 
 ## Consequences
 
-An ordinary wide table reads in place with wrapped cells; a many-column table keeps its readable natural width, spans the whole transcript where the layout has spare width, and scrolls for the remainder — with no interaction required and nothing to restore. Chromium keyboard-focuses scrollable containers by default, so the wrapper stays keyboard-scrollable without added attributes (a `:focus-visible` ring marks it). Two knowledge edges: `container-type: inline-size` on ChatView's `.scroll` makes it the nearest query container for anything inside the transcript that later uses container units, and sub-four-column tables now always stretch to the full column width (deepsuite chat behavior) rather than shrink-wrapping short content.
+An ordinary wide table reads in place with wrapped cells; a many-column table keeps its readable natural width, spans the whole transcript where the layout has spare width, and scrolls for the remainder — with no interaction required and nothing to restore. A wide table's horizontal bar reveals on hover instead of staying painted: Chromium never repaints state-conditioned scrollbar styles (neither hover-conditioned `::-webkit-scrollbar*` rules nor a `:hover` `scrollbar-color` change reaches the painted bar — measured headed and headless), so the reveal toggles `overflow-x` itself (`hidden` at rest, `auto` on hover or focus), with resting `padding-bottom` matching the themed bar height so the appearing bar replaces it without moving content below. Resting `overflow-x: hidden` drops Chromium's implicit scroller focusability, so wide wrappers carry an explicit `tabindex="0"` (a `:focus-visible` ring marks them, and focus restores scrolling for arrow keys). Two knowledge edges: `container-type: inline-size` on ChatView's `.scroll` makes it the nearest query container for anything inside the transcript that later uses container units, and sub-four-column tables now always stretch to the full column width (deepsuite chat behavior) rather than shrink-wrapping short content.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
index d2fcc18f88..4d13a29f69 100644
--- a/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 ## 后果
 
-普通宽表原地换行阅读；多列表格保持可读的自然宽度，在布局有空余处横跨整个转录区，剩余部分滚动——无需任何交互，也没有状态要恢复。Chromium 默认让可滚动容器可键盘聚焦，因此包裹层无需附加属性即可键盘滚动（`:focus-visible` 有焦点圈）。两个需要知道的点：ChatView `.scroll` 上的 `container-type: inline-size` 使它成为转录区内后续使用容器单位的最近查询容器；不足四列的表格现在总是拉伸到整列宽（deepsuite chat 行为），而不是按内容收缩。
+普通宽表原地换行阅读；多列表格保持可读的自然宽度，在布局有空余处横跨整个转录区，剩余部分滚动——无需任何交互，也没有状态要恢复。宽表的横向滚动条悬停才出现、不再常驻：Chromium 从不重绘状态条件化的滚动条样式（悬停条件化的 `::-webkit-scrollbar*` 规则和 `:hover` 下的 `scrollbar-color` 变化都到不了已绘制的滚动条——有头与无头模式均已实测），因此显隐切换的是 `overflow-x` 本身（静止 `hidden`，悬停或聚焦 `auto`），静止时的 `padding-bottom` 与主题滚动条高度一致，出现的滚动条恰好顶替它、下方内容不动。静止的 `overflow-x: hidden` 会失去 Chromium 对滚动容器的隐式可聚焦性，因此宽表包裹层带显式 `tabindex="0"`（`:focus-visible` 有焦点圈，聚焦后方向键可滚）。两个需要知道的点：ChatView `.scroll` 上的 `container-type: inline-size` 使它成为转录区内后续使用容器单位的最近查询容器；不足四列的表格现在总是拉伸到整列宽（deepsuite chat 行为），而不是按内容收缩。
 
 ## 测试
 
diff --git a/apps/web/tests/markdown-wide-table.e2e.ts b/apps/web/tests/markdown-wide-table.e2e.ts
index da2c371085..bb897ea364 100644
--- a/apps/web/tests/markdown-wide-table.e2e.ts
+++ b/apps/web/tests/markdown-wide-table.e2e.ts
@@ -370,6 +370,34 @@ describe('web e2e: markdown tables fill the column, wide ones break out and scro
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 
+  it('reveals the wide table scrollbar on hover only', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table-scrollbar'))
+    await sweep()
+    await settleAt(1680)
+    const wide = page.locator('[class*="tableScroll"]', { hasText: WIDE_MARKER })
+    // Chromium never repaints state-conditioned scrollbar STYLES, so the
+    // hover reveal toggles overflow-x itself; the resting padding matches
+    // the bar height so the swap does not move anything below. Both are
+    // ordinary properties whose computed values follow :hover.
+    const overflowState = () => wide.evaluate(element => [
+      getComputedStyle(element).overflowX,
+      getComputedStyle(element).paddingBottom,
+    ].join(' '))
+    // Park the pointer away and drop focus: the keyboard case above leaves
+    // the wrapper focused, and focus-visible also reveals the bar.
+    await page.mouse.move(4, 4)
+    await wide.evaluate((element) => { element.blur() })
+    await expect.poll(overflowState, { timeout: 5_000 }).toBe('hidden 8px')
+    // Resting hidden overflow keeps the scroll position reachable and intact.
+    expect(await wide.evaluate(element => element.scrollLeft)).toBeGreaterThanOrEqual(0)
+    await wide.hover()
+    await expect.poll(overflowState, { timeout: 5_000 }).toBe('auto 0px')
+    // Pointer leaves: the bar rests hidden again.
+    await page.mouse.move(4, 4)
+    await expect.poll(overflowState, { timeout: 5_000 }).toBe('hidden 8px')
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
   it('keeps the fill/scroll relations under page zoom', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-wide-table-zoom'))
     await sweep()
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 6856283fcc..e6ed8300ac 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.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 packages/client/ui-primitives/README.md
-README.md: 0d7848112b650a322965ad52a38d23e0145e7921
-README.zh.md: 475af21d5a7bc1bc48115b171d92b9a0d44df309
+README.md: 7822a5d41e8125752b8bc28fea3db2232323fd81
+README.zh.md: 5a78e683f3bb94f8b9d3a64b0d4ba1f3f3df9d85
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 0d7848112b..7822a5d41e 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -14,7 +14,7 @@ Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/P
 
 ## Markdown rendering
 
-`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). Tables size by column count (deepsuite chat parity): under four columns — or inside a blockquote — a table fills its column and wraps cell text down to the cells' minimum readable width, while four-or-more-column tables keep their natural width, scroll horizontally inside their wrapper, and carry the stable `md-table-wide` class so a hosting layout can widen the wrapper past its column (the chat transcript's container-query breakout in `dsh-client-ui-conversation`); Chromium keyboard-focuses the scrollable wrapper by default ([decision record](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
+`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). Tables size by column count (deepsuite chat parity): under four columns — or inside a blockquote — a table fills its column and wraps cell text down to the cells' minimum readable width, while four-or-more-column tables keep their natural width, scroll horizontally inside their wrapper, and carry the stable `md-table-wide` class so a hosting layout can widen the wrapper past its column (the chat transcript's container-query breakout in `dsh-client-ui-conversation`); a wide table's horizontal bar reveals on hover or keyboard focus (the wrapper carries `tabindex="0"`) instead of staying painted ([decision record](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
 
 ## Terminal output
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 475af21d5a..5a78e683f3 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -14,7 +14,7 @@
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。表格按列数决定尺寸（对齐 deepsuite chat）：不足四列——或位于 blockquote 内——的表格填满所在列，单元格文本换行收缩至最小可读列宽；四列及以上的表格保持自然宽度、在包裹层内横向滚动，并携带稳定的 `md-table-wide` 类，供宿主布局把包裹层加宽到所在列之外（`dsh-client-ui-conversation` 中聊天转录区的容器查询突破样式）；Chromium 默认让可滚动包裹层可键盘聚焦（[决策记录](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。表格按列数决定尺寸（对齐 deepsuite chat）：不足四列——或位于 blockquote 内——的表格填满所在列，单元格文本换行收缩至最小可读列宽；四列及以上的表格保持自然宽度、在包裹层内横向滚动，并携带稳定的 `md-table-wide` 类，供宿主布局把包裹层加宽到所在列之外（`dsh-client-ui-conversation` 中聊天转录区的容器查询突破样式）；宽表的横向滚动条在悬停或键盘聚焦（包裹层带 `tabindex="0"`）时才出现、不再常驻（[决策记录](../../../.agents/notes/implemented/feature/2026-08-19-web-markdown-wide-table-view.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index 969cf41342..f8d45cd4f6 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -177,6 +177,26 @@
   overscroll-behavior-x: contain;
 }
 
+/* Wide tables reveal their horizontal bar on hover (or keyboard focus)
+   instead of keeping it painted. Chromium never repaints state-conditioned
+   scrollbar STYLES (neither hover-conditioned `::-webkit-scrollbar*` rules
+   nor a :hover `scrollbar-color` change reaches the painted bar), so the
+   toggle is `overflow-x` itself — a layout change repaints reliably. The
+   resting padding matches the themed bar's height, so on an overflowing
+   table the appearing bar exactly replaces it and nothing below shifts.
+   Wheel and trackpad scrolling need the pointer over the table, which is
+   already the hover that re-enables `auto`. */
+.tableScroll:global(.md-table-wide) {
+  overflow-x: hidden;
+  padding-bottom: var(--dsh-scrollbar-width, 8px);
+}
+
+.tableScroll:global(.md-table-wide):hover,
+.tableScroll:global(.md-table-wide):focus-visible {
+  overflow-x: auto;
+  padding-bottom: 0;
+}
+
 /* Chromium keyboard-focuses scrollable containers by default; the ring uses
    the sheet's link focus color. */
 .tableScroll:focus-visible {
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 12d73bb44b..de713858cf 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -400,14 +400,22 @@ function renderTable(node: Md.Table, key: Key, context: MarkdownRenderContext):
   const align = node.align ?? null
   const [headRow, ...bodyRows] = node.children
   const columns = align === null ? headRow?.children.length ?? 0 : align.length
-  // Four or more columns read as a comparison matrix: the wrapper keeps the
+  // Four or more columns read as a comparison matrix: the block keeps the
   // table at natural width and exposes the stable `md-table-wide` hook so a
   // hosting layout (the chat transcript) can widen it past the message
   // column. Narrower tables — and any table inside a blockquote — fill the
   // column and wrap instead (deepsuite chat TableWrapper parity).
   const wide = columns >= 4 && context.inBlockquote !== true
   return (
-    <div key={key} className={clsx(css.tableScroll, wide ? 'md-table-wide' : css.tableFill)}>
+    // Wide tables rest with overflow-x hidden (the hover-revealed bar in
+    // MarkdownText.module.css), which drops Chromium's implicit scroller
+    // focusability — the explicit tabindex keeps them keyboard-reachable,
+    // and :focus-visible restores scrolling.
+    <div
+      key={key}
+      className={clsx(css.tableScroll, wide ? 'md-table-wide' : css.tableFill)}
+      tabIndex={wide ? 0 : undefined}
+    >
       <table>
         {headRow !== undefined && <thead>{renderTableRow(headRow, 'th', align, 0, context)}</thead>}
         {bodyRows.length > 0 && (
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
index 9b805440be..c105766edf 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.settled.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681 md-table-wide">
+  <div class="_tableScroll_404681 md-table-wide" tabindex="0">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt
index 9b805440be..c105766edf 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-wide-and-blockquote.streaming.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681 md-table-wide">
+  <div class="_tableScroll_404681 md-table-wide" tabindex="0">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
index 2ce936ddcc..99a45c4e77 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.settled.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681 md-table-wide">
+  <div class="_tableScroll_404681 md-table-wide" tabindex="0">
     <table>
       <thead>
         <tr>
diff --git a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
index 2ce936ddcc..99a45c4e77 100644
--- a/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
+++ b/packages/client/ui-primitives/tests/fixtures/markdown-dom/table-with-alignment.streaming.txt
@@ -1,5 +1,5 @@
 <div class="_markdown_404681">
-  <div class="_tableScroll_404681 md-table-wide">
+  <div class="_tableScroll_404681 md-table-wide" tabindex="0">
     <table>
       <thead>
         <tr>

From 63d9de0eb3c580c08dd1a11be95c0a42066e8bff Mon Sep 17 00:00:00 2001
From: Chinesezjc <jczhai@deepseek.com>
Date: Thu, 20 Aug 2026 15:21:59 +0800
Subject: [PATCH 06/34] fix(cic): address gray-check PR review - official
 build, step-level gate, note sync
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address ds-review-bot findings on PR #2798:

- release-publish.yml: use pnpm run build:official (not build) so the dsh
  pack step's verifyBuildArtifacts (families.ts:327, readClientBuildRecord with
  officialClientBuildEnvironment) finds the official client-build record; build
  would fail Pack release tarballs on a clean runner.
- issue-lifecycle.yml: move the previous job-level if to step level on
  Create project token and Handle repository event, so approved/commented
  reviews pass (job reported success, no gray segment) without minting a
  write-capable App token or touching the board — preserving the original
  least-privilege property.
- ci-workflow.spec.ts: lock the step-level gate on the two lifecycle steps, and
  add a release-workflow invariant test (release.yml/vendor are pack-only;
  release-publish.yml/vendor-publish.yml are workflow_dispatch-only with the
  npm-publish environment and Release-publish group) to prevent #2797 recurrence.
- Update 2026-08-10-event-directed-pr-review-status and 2026-08-10-npm-release-
  sequences notes (en/zh/i18n) to the new split and step-level behavior.

Verification: ci-workflow.spec.ts 14/14, typecheck clean, all five workflows
YAML-parse, verify-translation-pairing consistent, note-format 582.
---
 ...-event-directed-pr-review-status.i18n.yaml |  4 +-
 ...6-08-10-event-directed-pr-review-status.md |  2 +-
 ...8-10-event-directed-pr-review-status.zh.md |  2 +-
 ...2026-08-10-npm-release-sequences.i18n.yaml |  4 +-
 .../2026-08-10-npm-release-sequences.md       |  6 +--
 .../2026-08-10-npm-release-sequences.zh.md    |  6 +--
 .github/workflows/issue-lifecycle.yml         | 11 ++++--
 .github/workflows/release-publish.yml         |  2 +-
 scripts/ci-workflow.spec.ts                   | 39 +++++++++++++++++--
 9 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml
index f3f9f10975..d8c333dd88 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.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/process/2026-08-10-event-directed-pr-review-status.md
-2026-08-10-event-directed-pr-review-status.md: bdaaa07c47d45eb002ed7c026683a800f67d0fca
-2026-08-10-event-directed-pr-review-status.zh.md: 0ca4154a78e82156687b4fc5efb62745f3b2af63
+2026-08-10-event-directed-pr-review-status.md: 3ed6038929d3c2c1e9cd82182978262ee363f5ab
+2026-08-10-event-directed-pr-review-status.zh.md: 1fa8650057e53ab894c597b712720a3ee7a5c46a
diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
index bdaaa07c47..3ed6038929 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.md
@@ -22,7 +22,7 @@ The handler resolves only exact same-repository `Fixes`, `Closes`, or `Resolves`
 
 ## Verification
 
-[Issue-management tests](../../../../.github/issue-management/policy.test.mjs) pin the event-to-command mapping, the repeated-review-request transition after a changes-requested command, the changes-requested regression, terminal protection, and human override preservation. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the subscribed events, the absence of a job-level `if` (so approved/commented reviews pass rather than skip), and the separate `ready_for_review` policy trigger.
+[Issue-management tests](../../../../.github/issue-management/policy.test.mjs) pin the event-to-command mapping, the repeated-review-request transition after a changes-requested command, the changes-requested regression, terminal protection, and human override preservation. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the subscribed events, the job-level absence of `if` plus the step-level gate on the token/board steps (so approved/commented reviews pass without minting a token), and the separate `ready_for_review` policy trigger.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
index 0ca4154a78..1fa8650057 100644
--- a/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-event-directed-pr-review-status.zh.md
@@ -22,7 +22,7 @@ Issue 生命周期工作流把评审 webhook 视为命令。`pull_request.review
 
 ## 验证
 
-[Issue 管理测试](../../../../.github/issue-management/policy.test.mjs)锁定事件到命令的映射、请求修改命令后重复请求评审所触发的状态转换、请求修改后的状态回退、终态保护，以及保留人工覆盖状态。[工作流测试](../../../../scripts/ci-workflow.spec.ts)锁定订阅事件、作业无 job 级 `if`（使 approved/commented 评审以 pass 而非 skip 呈现），以及独立的 `ready_for_review` 策略触发器。
+[Issue 管理测试](../../../../.github/issue-management/policy.test.mjs)锁定事件到命令的映射、请求修改命令后重复请求评审所触发的状态转换、请求修改后的状态回退、终态保护，以及保留人工覆盖状态。[工作流测试](../../../../scripts/ci-workflow.spec.ts)锁定订阅事件、job 级无 `if` 且 token/看板步骤带 step 级门控（使 approved/commented 评审以 pass 呈现且不铸 token），以及独立的 `ready_for_review` 策略触发器。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
index e3a181f63d..763362d57c 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.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/process/2026-08-10-npm-release-sequences.md
-2026-08-10-npm-release-sequences.md: efeda91b6a85e1316c563cc04411878122096953
-2026-08-10-npm-release-sequences.zh.md: d905ac4b58691890d2aad955b87713a278dcb4f8
+2026-08-10-npm-release-sequences.md: c2cf540ff130f2a17a40068a0684c9bbc0e07ee3
+2026-08-10-npm-release-sequences.zh.md: 378c0a007ec30ad05fe9bcb9d068d095ccb658bc
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
index efeda91b6a..c2cf540ff1 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
@@ -105,11 +105,11 @@ The entity in this domain is a **release family**: a set of packages sharing one
 
 The dsh family applies the repository's publication payload policy, which rejects sources and declaration maps. The vendored family keeps upstream's payload, because those manifests export `./src/*` and dropping `src` would publish an export map pointing at absent files.
 
-### Workflow shape: pack everything at once, then publish as one set
+### Workflow shape: pack on PR/push, publish from a manual dispatch workflow
 
-The `pack` job walks the whole release set once, packing each member into one directory, writes the upload order, and uploads that directory as one artifact; the `publish` job downloads that artifact and publishes each entry in order. The release set is one unit — half the packages can never reach the registry while the other half is still building.
+The `pack` job walks the whole release set once, packing each member into one directory, writes the upload order, and uploads that directory as one artifact; it lives in `release.yml` / `release-vendor.yml`. The release set is one unit — half the packages can never reach the registry while the other half is still building.
 
-`pack` carries no credentials and runs on every pull request and master push, so a pull request proves the release set still packs. `publish` is a manual dispatch, sits behind the `npm-publish` environment for human approval, and neither builds nor rebuilds — it uploads the bytes pack produced. Pack runs are grouped per ref so concurrent pull requests do not displace each other; the publish job carries the global group, because dist-tags are shared registry state.
+`pack` carries no credentials and runs on every pull request and master push, so a pull request proves the release set still packs. Publication lives in a separate `release-publish.yml` / `release-vendor-publish.yml` workflow that is `workflow_dispatch`-only (so it never appears as a PR check): it repacks the current tree and then publishes each entry in order, behind the `npm-publish` environment for human approval. Pack runs are grouped per ref so concurrent pull requests do not displace each other; the publish workflow carries the global `Release-publish` group, because dist-tags are shared registry state.
 
 A dsh verification installs the vendored family's pack output too. The harness packages declare the vendored framework as a peer, those packages live in another sequence, and the credential-free job cannot fetch them from a private registry — so `release.yml` packs the vendored family for verification while publishing only its own set.
 
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
index d905ac4b58..378c0a007e 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
@@ -105,11 +105,11 @@ registry 的两个行为决定了「怎么尝试一次发布」。写入之间
 
 dsh 族套用仓库的发布 payload 策略（拒绝源码与声明映射）。vendored 族保留上游 payload，因为那些 manifest 导出 `./src/*`，去掉 `src` 会发出一个导出映射指向不存在文件的包。
 
-### workflow 形状：一次性 pack 全部，再统一 publish
+### workflow 形状：PR/push 上 pack，从手动 dispatch 工作流发布
 
-`pack` job 一趟遍历整个发布集，把每个成员打进同一个目录，写出上传顺序，整个目录作为一份 artifact 上传；`publish` job 下载那一份 artifact，按顺序逐个发布。发布集是一个整体——绝不会出现一半的包已经上了 registry、另一半还在构建。
+`pack` job 一趟遍历整个发布集，把每个成员打进同一个目录，写出上传顺序，整个目录作为一份 artifact 上传；它位于 `release.yml` / `release-vendor.yml`。发布集是一个整体——绝不会出现一半的包已经上了 registry、另一半还在构建。
 
-`pack` 无凭据，在每个 pull request 和每次 master push 上跑，所以一个 pull request 就能证明发布集仍能完整打出来。`publish` 是手动 dispatch，挂在 `npm-publish` environment 后面等人工审批，且既不构建也不重建——它上传的就是 pack 产出的字节。pack 的 run 按 ref 分组，并发的 pull request 不会互相顶掉；全局分组落在 publish job 上，因为 dist-tag 是共享的 registry 状态。
+`pack` 无凭据，在每个 pull request 和每次 master push 上跑，所以一个 pull request 就能证明发布集仍能完整打出来。发布则位于独立的 `release-publish.yml` / `release-vendor-publish.yml` 工作流，仅 `workflow_dispatch`（因此不会作为 PR check 出现）：它重新打包当前树，再按顺序逐个发布，挂在 `npm-publish` environment 后面等人工审批。pack 的 run 按 ref 分组，并发的 pull request 不会互相顶掉；全局 `Release-publish` 分组落在发布工作流上，因为 dist-tag 是共享的 registry 状态。
 
 dsh 的验证会一并安装 vendored 族的 pack 产物。harness 的包把 vendored 框架声明成 peer，而那些包属于另一条序列，无凭据的 job 无法从私有 registry 取到——所以 `release.yml` 为验证而打包 vendored 族，发布的仍只有自己那一份。
 
diff --git a/.github/workflows/issue-lifecycle.yml b/.github/workflows/issue-lifecycle.yml
index 70732de6a2..8e2265fb19 100644
--- a/.github/workflows/issue-lifecycle.yml
+++ b/.github/workflows/issue-lifecycle.yml
@@ -36,10 +36,11 @@ concurrency:
 jobs:
   lifecycle:
     name: Issue lifecycle
-    # Run on every pull_request_review event, not only changes_requested, so the
-    # check shows a passing result instead of a gray "skipped" segment. The
-    # lifecycle handler itself no-ops (returns success) for approved/commented
-    # reviews; only a changes_requested review drives the Project board.
+    # Runs on every pull_request_review event so the check reports success rather
+    # than a gray "skipped" segment. The token-creating and board-mutating steps
+    # are gated at step level (a skipped step does not gray the job): only a
+    # changes_requested review drives the Project board; approved/commented
+    # reviews never mint a write-capable App token.
     runs-on: ubuntu-latest
     steps:
       - name: Check out trusted policy
@@ -49,6 +50,7 @@ jobs:
           persist-credentials: false
       - name: Create project token
         id: app-token
+        if: ${{ github.event_name != 'pull_request_review' || github.event.review.state == 'changes_requested' }}
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
         with:
           client-id: ${{ vars.DSH_ISSUE_APP_CLIENT_ID }}
@@ -56,6 +58,7 @@ jobs:
           owner: deepseek-harness
           repositories: deepseek-harness
       - name: Handle repository event
+        if: ${{ github.event_name != 'pull_request_review' || github.event.review.state == 'changes_requested' }}
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
         run: node .github/issue-management/policy.mjs lifecycle
diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml
index 7107ba0073..143df14caa 100644
--- a/.github/workflows/release-publish.yml
+++ b/.github/workflows/release-publish.yml
@@ -58,7 +58,7 @@ jobs:
         run: pnpm run release:verify --family dsh
 
       - name: Build
-        run: pnpm run build
+        run: pnpm run build:official
 
       - name: Pack release tarballs
         run: pnpm run release:pack --family dsh --out dist/npm
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index a13ceafe47..0740a6a6fb 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -417,17 +417,25 @@ describe('Python release workflows', () => {
 })
 
 describe('Issue lifecycle workflow', () => {
-  it('runs the lifecycle job on every PR/review event so it passes instead of skipping', () => {
+  it('runs the lifecycle job on every PR/review event but gates token and board steps', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
     const policy = loadWorkflow('.github/workflows/issue-policy.yml')
     const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
+    if (!Array.isArray(lifecycleJob.steps)) throw new TypeError('Issue lifecycle job must define steps')
 
-    // The lifecycle job has no workflow-level `if`, so it is listed on every
-    // pull_request / pull_request_review event and reports success (the handler
-    // no-ops for non-changes-requested reviews) instead of a gray "skipped" check.
+    // The job has no job-level `if`, so it is listed on every pull_request /
+    // pull_request_review event and reports success instead of a gray skip. The
+    // write-capable steps are gated at step level so approved/commented reviews
+    // never mint a Project/Issue App token nor touch the board.
     expect(lifecycle.on).toHaveProperty('pull_request')
     expect(lifecycle.on).toHaveProperty('pull_request_review')
     expect(lifecycleJob.if).toBeUndefined()
+    const gated = "${{ github.event_name != 'pull_request_review' || github.event.review.state == 'changes_requested' }}"
+    const steps = lifecycleJob.steps.filter(isRecord)
+    const tokenStep = steps.find(s => s.name === 'Create project token')
+    const handleStep = steps.find(s => s.name === 'Handle repository event')
+    expect(tokenStep).toMatchObject({ if: gated })
+    expect(handleStep).toMatchObject({ if: gated })
 
     // issue-policy owns PR validation; it is read-only and a real gate.
     const policyPullRequest = workflowEvent(policy, 'pull_request')
@@ -435,6 +443,29 @@ describe('Issue lifecycle workflow', () => {
   })
 })
 
+describe('npm release workflows', () => {
+  it('keeps publication dispatch-only and pack in the PR workflow', () => {
+    // pack stays in the PR/master release workflows so a PR proves the set packs.
+    for (const file of ['release.yml', 'release-vendor.yml']) {
+      const workflow = loadWorkflow(`.github/workflows/${file}`)
+      if (!isRecord(workflow.jobs)) throw new TypeError(`${file} must define jobs`)
+      expect(Object.keys(workflow.jobs).sort()).toEqual(['pack'])
+    }
+
+    // publication is workflow_dispatch-only (never a PR check) and keeps the
+    // npm-publish environment plus the shared dist-tag group.
+    for (const file of ['release-publish.yml', 'release-vendor-publish.yml']) {
+      const workflow = loadWorkflow(`.github/workflows/${file}`)
+      if (!isRecord(workflow.on) || !isRecord(workflow.jobs)) throw new TypeError(`${file} must define on and jobs`)
+      expect(Object.keys(workflow.on)).toEqual(['workflow_dispatch'])
+      const publish = workflow.jobs.publish
+      if (!isRecord(publish)) throw new TypeError(`${file} must define a publish job`)
+      expect(publish.environment).toBe('npm-publish')
+      expect(publish.concurrency).toMatchObject({ group: 'Release-publish' })
+    }
+  })
+})
+
 describe('Git hooks', () => {
   it('leaves frozen Agent Note sidecars to the archive verifier', () => {
     const lefthook = loadWorkflow('lefthook.yml')

From 9616790b6cc6623aa4663f550e920cf6989664c7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 20 Aug 2026 15:27:58 +0800
Subject: [PATCH 07/34] feat(web): answer ask_user_question over multiple lines

A question that carried options collected its free-text answer in a
single-line input: a long sentence scrolled sideways inside one line and
Shift+Enter was inert, so an answer with structure could not be typed.
The optionless question already used a textarea, but a fixed 64-140px box
that never followed the draft.

Both shapes now answer into one AnswerField: a `textarea rows=1` sharing a
grid cell with a hidden mirror that renders the draft plus a trailing
newline and so owns the height. Soft wraps are invisible to a '\n' count,
so the mirror is what grows the box; growth stops at eight lines and the
textarea scrolls from there, keeping the choices the answer belongs to in
view. Enter still continues and submits, Shift+Enter breaks the line, and
the IME guard is unchanged.
---
 ...-multiline-question-answer-field.i18n.yaml |  6 ++
 ...6-08-20-multiline-question-answer-field.md | 43 ++++++++++
 ...8-20-multiline-question-answer-field.zh.md | 43 ++++++++++
 apps/web/tests/question-composer.e2e.ts       | 32 +++++++-
 .../client/ui-user-questions/README.i18n.yaml |  4 +-
 packages/client/ui-user-questions/README.md   |  2 +-
 .../client/ui-user-questions/README.zh.md     |  2 +-
 .../src/client/QuestionComposer.module.css    | 75 +++++++++++-------
 .../src/client/QuestionComposer.tsx           | 78 +++++++++++++++----
 .../user-questions-composer.client.spec.tsx   | 37 +++++++++
 10 files changed, 278 insertions(+), 44 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml
new file mode 100644
index 0000000000..2040f0c481
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.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/feature/2026-08-20-multiline-question-answer-field.md
+2026-08-20-multiline-question-answer-field.md: dbe146f1cd56b0f757784283269ba5061c425366
+2026-08-20-multiline-question-answer-field.zh.md: 7adb5bb37bf4393a5be21f1dc56b2be46fbfe9cb
diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
new file mode 100644
index 0000000000..dbe146f1cd
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
@@ -0,0 +1,43 @@
+# Agent Note: Multi-line answers in the question composer
+
+Status: implemented
+
+English | [中文](2026-08-20-multiline-question-answer-field.zh.md)
+
+## Problem
+
+`ask_user_question` offers a free-text answer beside the model's own options. On a question that carried options, that answer was a single-line `<input>`: a long sentence scrolled sideways inside one 24px line, Shift+Enter did nothing, and an answer with structure — two requirements, a short list, a paragraph — could not be typed at all. The optionless question already used a textarea, but a fixed 64–140px box that neither followed the draft nor opened wider.
+
+The chat composer next to it grows with the draft and takes Shift+Enter as a newline. A user who has just typed a multi-line prompt there meets a field that silently flattens the same answer.
+
+## Decision
+
+Both question shapes answer into one `AnswerField`: a `<textarea rows={1}>` sharing a single CSS-grid cell with a hidden mirror `<div>` that renders the draft plus a trailing newline.
+
+The mirror sits in normal flow and so sizes the grid row; the textarea stretches to that row, and `rows={1}` keeps the control's own intrinsic height out of the row sizing, leaving the mirror the only input to the height. Soft wraps are invisible to a `'\n'` count, so the mirror is what makes a wrapped answer grow the box rather than scroll one line. The trailing newline covers the last line the textarea's caret can reach and the block container drops. Mirror and textarea must keep identical type, padding, and wrapping rules; a divergence sizes the box wrong for the text being typed.
+
+Growth stops at the mirror's `max-height` of eight lines, and past that the textarea scrolls itself. It is the only scrollport in the stack: unlike the chat composer, this field paints its own glyphs, so there is no second layer whose scroll offset would have to match.
+
+Enter continues the flow and submits the batch on the last question, Shift+Enter breaks the line, and the IME guard is unchanged — Enter during composition confirms the candidate without advancing. The `variant` prop names which of the two looks the field takes, so the field owns both and neither caller assembles one out of class names.
+
+## Alternatives considered
+
+**`field-sizing: content`.** Rejected for the same reason [the composer's Safari recovery](../bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md) rejected it: Safari reproduces a stale intrinsic height after a deletion crosses a wrap threshold. The mirror is a plain block whose height Safari computes correctly, and it is already the technique this repository runs in the chat composer.
+
+**Resize in JS on every keystroke** — set `height: auto`, read `scrollHeight`, write it back. Rejected: it pays two forced layouts per keystroke and reintroduces the stale-geometry class of defect the mirror avoids, in exchange for no capability the mirror lacks.
+
+**Reuse the InputBar stack verbatim.** Rejected because that stack carries a decoration backdrop between mirror and textarea, which forces both layers into one outer scrollport so the caret and the glyphs cannot drift apart. This field has no backdrop, so letting the textarea own its own scroll removes the outer scrollport and that obligation with it.
+
+**A separate expand-to-dialog entry for long answers.** Rejected as unnecessary: growing in place already satisfies the requirement, and a dialog would take the options the answer is an alternative to off screen at the moment the user is weighing them.
+
+**Uncapped growth.** Rejected because the card tops out at `min(60vh, 520px)` and still owes that budget to the title, the option rows, and the footer actions; an unbounded field pushes the choices the answer belongs to out of view.
+
+## Testing
+
+Component tests pin the round trip: both shapes render a textarea, the mirror follows the draft, Shift+Enter never advances the flow, and line breaks reach the answer batch verbatim. The assembled `question-composer` web e2e measures the live engine — a soft-wrapped draft grows the field without scrolling it, two Shift+Enter presses leave `"\n\n"` in a taller field with the question still open, and a draft past the cap scrolls instead of growing.
+
+## Consequences
+
+An answer can now carry the structure the question asks for, and the field the user sees behaves like the chat composer above it. The cost is a second element per field and the standing obligation to keep mirror and textarea metrics identical, which the JSDoc at `AnswerField` states and the e2e growth assertion detects.
+
+The [single-select highlight item](https://github.com/deepseek-harness/deepseek-harness/issues/1687) of the same issue is untouched: focusing the custom field still leaves the previously chosen option visually selected until the first character lands.
diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md
new file mode 100644
index 0000000000..7adb5bb37b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: Multi-line answers in the question composer
+
+Status: implemented
+
+[English](2026-08-20-multiline-question-answer-field.md) | 中文
+
+## Problem
+
+`ask_user_question`在模型给出的选项旁提供一个自由文本答案。在带选项的问题上，该答案曾是单行 `<input>`：长句子在 24px 的一行内横向滚动，Shift+Enter 毫无作用，带结构的答案——两条要求、一个短列表、一段话——根本无法输入。无选项问题虽已使用 textarea，但那是固定 64–140px 的框，既不跟随草稿，也无法展开。
+
+紧邻它的聊天输入框会随草稿增高，并把 Shift+Enter 当作换行。刚在那里敲完多行提示词的用户，转身遇到的却是一个会悄悄抹平同一个答案的输入框。
+
+## Decision
+
+两种问题形状都写入同一个 `AnswerField`：一个 `<textarea rows={1}>`，与一个渲染「草稿 + 结尾换行」的隐藏镜像 `<div>` 共享同一个 CSS grid 单元格。
+
+镜像位于常规流中，因而决定 grid 行的高度；textarea 拉伸到该行，而 `rows={1}` 使控件自身的固有高度不参与行尺寸计算，于是镜像是高度的唯一输入。软换行对 `'\n'` 计数不可见，因此正是镜像让换行后的答案把输入框撑高，而不是在一行内滚动。结尾的换行补上 textarea 光标可达、而块级容器会丢弃的最后一行。镜像与 textarea 必须保持完全一致的字体、内边距与换行规则；一旦偏离，输入框的高度就与正在输入的文本不符。
+
+增高在镜像 `max-height` 的八行处停止，此后由 textarea 自身滚动。它是这个结构里唯一的滚动容器：与聊天输入框不同，本输入框自己绘制字形，因此不存在第二个需要对齐滚动偏移的图层。
+
+Enter 继续流程并在最后一题提交整批，Shift+Enter 换行，IME 保护不变——组合输入期间按 Enter 只确认候选，不前进。`variant` 属性指明该输入框采用两种外观中的哪一种，因此外观归输入框自己所有，任何调用方都不必用类名拼装。
+
+## Alternatives considered
+
+**`field-sizing: content`。** 与[聊天输入框的 Safari 恢复方案](../bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md)出于同一理由否决：当删除跨过换行阈值后，Safari 会复现陈旧的固有高度。镜像是一个 Safari 能正确计算高度的普通块，而且它已经是本仓库在聊天输入框中运行的技术。
+
+**在 JS 中逐次按键重算高度**——置 `height: auto`、读 `scrollHeight`、再写回。否决：每次按键要付两次强制布局，并重新引入镜像所避开的那类陈旧几何缺陷，换来的却是镜像本就具备的能力。
+
+**原样复用 InputBar 的图层结构。** 否决，因为该结构在镜像与 textarea 之间还有一层装饰背板，这迫使两个图层共用一个外层滚动容器，以免光标与字形彼此漂移。本输入框没有背板，因此让 textarea 自己滚动，既去掉了外层滚动容器，也一并去掉了那项对齐义务。
+
+**为长答案单独提供展开为对话框的入口。** 作为多余方案否决：就地增高已满足需求，而对话框会在用户正权衡选项时，把答案所要替代的那些选项挤出屏幕。
+
+**不设增高上限。** 否决，因为卡片上限为 `min(60vh, 520px)`，还要把这份额度分给标题、选项行与底部操作；不设上限的输入框会把答案所属的选项挤出视野。
+
+## Testing
+
+组件测试固定了整条往返：两种形状都渲染 textarea、镜像跟随草稿、Shift+Enter 绝不前进流程、换行原样进入答案批次。组装后的 `question-composer` web e2e 则在真实引擎上测量——软换行的草稿把输入框撑高而不滚动，两次 Shift+Enter 之后 `"\n\n"` 留在更高的输入框里且问题仍未关闭，超过上限的草稿改为滚动而不再增高。
+
+## Consequences
+
+答案现在能承载问题所要求的结构，用户看到的输入框与其上方的聊天输入框行为一致。代价是每个输入框多一个元素，以及保持镜像与 textarea 度量完全一致的长期义务——`AnswerField` 的 JSDoc 陈述了这项义务，e2e 的增高断言负责发现违反。
+
+同一 Issue 中的[单选高亮项](https://github.com/deepseek-harness/deepseek-harness/issues/1687)未被触及：聚焦自定义输入框时，先前选中的选项在第一个字符落下之前仍保持视觉选中。
diff --git a/apps/web/tests/question-composer.e2e.ts b/apps/web/tests/question-composer.e2e.ts
index 589ed054ac..96b6575678 100644
--- a/apps/web/tests/question-composer.e2e.ts
+++ b/apps/web/tests/question-composer.e2e.ts
@@ -132,9 +132,39 @@ describe('web e2e: resident question composer round trip', () => {
       await page.setViewportSize(original)
     }
 
+    // Multi-line custom answer: the field is a textarea whose hidden mirror
+    // owns the box height, so a soft-wrapped or line-broken draft GROWS the
+    // field instead of scrolling one line, and Shift+Enter breaks the line
+    // rather than continuing the flow. Measured on the live composer because
+    // only a real engine soft-wraps; growth stops at the mirror's cap, past
+    // which the textarea is the one thing that scrolls. Replay only, same as
+    // the squeeze above: record mode must reach the recording write.
+    const custom = composer.getByRole('textbox')
+    if (MODE !== 'record') {
+      const lineHeight = await custom.evaluate(el => el.getBoundingClientRect().height)
+      await custom.fill('a'.repeat(120))
+      const wrapped = await custom.evaluate(el => ({
+        height: el.getBoundingClientRect().height,
+        scrolls: el.scrollHeight > el.clientHeight,
+      }))
+      expect(wrapped.height).toBeGreaterThan(lineHeight * 1.5)
+      expect(wrapped.scrolls).toBe(false)
+
+      await custom.fill('')
+      await custom.press('Shift+Enter')
+      await custom.press('Shift+Enter')
+      expect(await custom.inputValue()).toBe('\n\n')
+      expect(await composer.getByText('Which color do you prefer?').count()).toBeGreaterThan(0)
+      expect(await custom.evaluate(el => el.getBoundingClientRect().height))
+        .toBeGreaterThan(lineHeight * 2.5)
+
+      await custom.fill('x\n'.repeat(40))
+      expect(await custom.evaluate(el => el.scrollHeight > el.clientHeight)).toBe(true)
+      await custom.fill('')
+    }
+
     const blue = composer.getByRole('checkbox', { name: 'Blue' })
     await blue.click()
-    const custom = composer.getByRole('textbox')
     await custom.fill('Include accessibility notes')
     expect(await blue.getAttribute('aria-checked')).toBe('true')
     expect(await custom.inputValue()).toBe('Include accessibility notes')
diff --git a/packages/client/ui-user-questions/README.i18n.yaml b/packages/client/ui-user-questions/README.i18n.yaml
index 964bbf36ce..f90dd99881 100644
--- a/packages/client/ui-user-questions/README.i18n.yaml
+++ b/packages/client/ui-user-questions/README.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 packages/client/ui-user-questions/README.md
-README.md: ba4b23150a7f3a2536db97df99410cb92238210e
-README.zh.md: 96c81800ef85514c565defecc779da7d2e6523b7
+README.md: 90af68315e28a3a89d7eaec1d9e3da1472318164
+README.zh.md: 33e47eb983c7ec832120a8be2188fb8afe4449fe
diff --git a/packages/client/ui-user-questions/README.md b/packages/client/ui-user-questions/README.md
index ba4b23150a..90af68315e 100644
--- a/packages/client/ui-user-questions/README.md
+++ b/packages/client/ui-user-questions/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Web question feature plugin: its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot. Its host half is empty on purpose — mounting `dsh-tool-ask-user` there put the tool in the registry's GLOBAL layer, which merges into every agent regardless of the preset that composed it, so a two-tool benchmark preset really presented three. Rendering a question is a host UI capability; having the tool is an agent capability, so the `tool-ask-user` row belongs to the presets that want it (and to the TUI composition, which has no presets).
 
-The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
+The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Both question shapes answer into a textarea over a hidden height mirror, so a long answer soft-wraps and grows the field in place; growth stops at eight lines and the field scrolls from there, keeping the choices the answer belongs to in view. Single-select choices advance immediately, Enter continues the flow and submits once every question is answered or skipped, and Shift+Enter breaks a line instead; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
 
 A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. The card claims a request only when it can send every answer that request allows: one question, the intent declared, the plan present as `detail`, the named approve label offered, and a binary single choice (at most one option besides approve, not multi-select). Anything else — no intent, a batch of several questions, a missing plan, an approve label naming no option, a third option, a multi-select decision — stays on the generic flow, which can express it. An intent changes the layout, never which answers are reachable.
 
diff --git a/packages/client/ui-user-questions/README.zh.md b/packages/client/ui-user-questions/README.zh.md
index 96c81800ef..33e47eb983 100644
--- a/packages/client/ui-user-questions/README.zh.md
+++ b/packages/client/ui-user-questions/README.zh.md
@@ -4,7 +4,7 @@
 
 Web 提问功能插件：其浏览器侧把 `question` 条目注册到会话拥有的 `conversation.composer` 键控 slot 中。其主机侧刻意为空——在那里挂载 `dsh-tool-ask-user` 会把工具放进注册表的**全局层**，而全局层会并入每一个 agent（智能体），无论它由哪个 preset 组装，于是一个「两工具」的 benchmark preset 实际会呈现三个。渲染提问是宿主的 UI 能力，拥有该工具则是 agent 的能力，因此 `tool-ask-user` 行属于需要它的各个 preset（以及没有 preset 的 TUI 组装）。
 
-组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信任内容策略。限高卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。选择单选选项后会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 组合输入期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
+组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信任内容策略。限高卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。两种问题形状的自定义答案都写入一个带隐藏高度镜像的 textarea，因此长答案会软换行并就地把输入框撑高；增高到八行为止，此后由输入框自身滚动，使答案所属的选项仍留在视野内。选择单选选项后会立即前进；Enter 继续流程，所有问题均已回答或跳过后即提交，Shift+Enter 则改为换行；IME 组合输入期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
 
 若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review`——由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置——采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。卡片只在能够发出该请求允许的每一个答案时才接管：只有一个问题、声明了意图、计划以 `detail` 存在、提供了被指名的批准标签，且是二元单选（除批准外最多一个选项，且非多选）。其他任何情形——没有意图、一批含多个问题、缺少计划、批准标签未命中任何选项、出现第三个选项、多选决定——都留在能够表达它的通用流程上。意图改变的只是布局，从不改变可达的答案。
 
diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
index 8d01f8e3df..995a01cbb1 100644
--- a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
+++ b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
@@ -321,54 +321,77 @@
   border-color: var(--dsw-alias-border-l2);
 }
 
-.customInput {
-  flex: 1;
+/* Auto-growing free-text answer (see AnswerField): mirror and textarea share
+   one grid cell, the mirror sizes it, and the textarea stretches to it. The
+   two layers MUST keep identical type, padding and wrapping — a mismatch
+   makes the box the wrong height for the text the user is typing. */
+.field {
+  display: grid;
   min-width: 0;
-  padding: 0;
+  --dsh-answer-field-padding: 0;
+}
+
+.field > * {
+  grid-area: 1 / 1;
+  min-width: 0;
+  padding: var(--dsh-answer-field-padding);
+  font: inherit;
+  font-size: 14px;
+  line-height: 24px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow-wrap: anywhere;
+}
+
+/* The height ruler, never painted. Growth stops at 8 lines: the card body is
+   capped at 520px and still owes that budget to the title, the option rows and
+   the footer actions, so a long answer scrolls in the textarea instead of
+   pushing the choices it belongs to out of view. */
+.fieldMirror {
+  max-height: 192px;
+  overflow: hidden;
+  visibility: hidden;
+}
+
+.fieldInput {
+  resize: none;
+  /* The stack's only scrollport: past the mirror's cap the field stops growing
+     and this scrolls. */
+  overflow-y: auto;
   border: none;
   outline: none;
   background: transparent;
   color: var(--dsw-alias-label-primary);
   caret-color: var(--dsw-alias-state-business-primary);
-  font: inherit;
-  font-size: 14px;
-  line-height: 24px;
 }
 
-.customInput::placeholder {
+.fieldInput::placeholder {
   color: var(--dsw-alias-label-caption);
 }
 
-/* Optionless question: the free-form answer is the whole body. The 12px side
-   margins add to the .options 12px padding so both edges align with the
-   title's 24px inset; type matches the option rows, no resize handle. */
-.customTextarea {
-  display: block;
+/* Inline variant: the custom row's copy column, borrowing the row's chrome. */
+.customInline {
+  flex: 1;
+}
+
+/* Optionless question: the free-form answer is the whole body, so it carries
+   its own frame. The 12px side margins add to the .options 12px padding so both
+   edges align with the title's 24px inset; two lines are reserved before the
+   answer starts growing. */
+.customBlock {
   min-height: 64px;
-  max-height: 140px;
   flex-shrink: 0;
   margin: 0 12px;
-  padding: 8px 12px;
-  resize: none;
   border: 1px solid var(--dsw-alias-border-l2);
   border-radius: 10px;
-  outline: none;
   background: var(--dsw-alias-bg-module-platform);
-  color: var(--dsw-alias-label-primary);
-  caret-color: var(--dsw-alias-state-business-primary);
-  font: inherit;
-  font-size: 14px;
-  line-height: 24px;
+  --dsh-answer-field-padding: 8px 12px;
 }
 
-.customTextarea:focus {
+.customBlock:focus-within {
   border-color: var(--dsw-alias-state-business-primary);
 }
 
-.customTextarea::placeholder {
-  color: var(--dsw-alias-label-caption);
-}
-
 .footer {
   display: flex;
   align-items: center;
diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.tsx b/packages/client/ui-user-questions/src/client/QuestionComposer.tsx
index 8aa7f0daef..b2085cc151 100644
--- a/packages/client/ui-user-questions/src/client/QuestionComposer.tsx
+++ b/packages/client/ui-user-questions/src/client/QuestionComposer.tsx
@@ -39,12 +39,67 @@ export function parseRecommendedLabel(label: string): { label: string; recommend
 }
 
 /** Return whether a text-field key event belongs to an active IME composition. */
-function isComposing(event: KeyboardEvent<HTMLTextAreaElement | HTMLInputElement>): boolean {
+function isComposing(event: KeyboardEvent<HTMLTextAreaElement>): boolean {
   // keyCode 229 is the legacy IME-composition signal engines emit without isComposing.
   // oxlint-disable-next-line typescript/no-deprecated
   return event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229
 }
 
+/** The free-text answer field shared by both question shapes. */
+interface AnswerFieldProps {
+  /** Which shape the field takes: the custom row's inline column, or the optionless question's own framed block. */
+  variant: 'inline' | 'block'
+  /** Current draft text. */
+  value: string
+  /** Empty-field prompt. */
+  placeholder: string
+  /** Whether a submission in flight has frozen the field. */
+  disabled: boolean
+  /** Whether this field takes focus on mount. */
+  autoFocus?: boolean
+  /** Called when the field takes focus. */
+  onFocus?: () => void
+  /** Called with each edit of the draft. */
+  onChange: (event: ChangeEvent<HTMLTextAreaElement>) => void
+  /** Called with each key press, before the browser's own handling. */
+  onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void
+}
+
+/**
+ * Auto-growing free-text answer: a textarea, so a long answer soft-wraps and
+ * Shift+Enter breaks a line, over a hidden mirror that owns the height.
+ *
+ * The mirror renders the draft plus a trailing newline in normal flow and so
+ * sizes the grid row (counting rows by '\n' cannot see soft wraps); the
+ * textarea shares that one cell and stretches to it, and `rows={1}` keeps the
+ * control's own intrinsic height out of the row sizing so the mirror alone
+ * decides. Past the mirror's cap the textarea scrolls itself — it is the only
+ * scrollport in the stack, there being no second glyph layer to keep aligned.
+ * Mirror and textarea MUST share font, line-height, padding and wrapping rules
+ * or the two heights diverge.
+ *
+ * @param props - field shape, draft text, and the field's event handlers.
+ * @returns The mirrored auto-growing field.
+ */
+function AnswerField(props: AnswerFieldProps) {
+  return (
+    <div className={clsx(css.field, props.variant === 'inline' ? css.customInline : css.customBlock)}>
+      <div aria-hidden className={css.fieldMirror}>{`${props.value}\n`}</div>
+      <textarea
+        autoFocus={props.autoFocus}
+        className={css.fieldInput}
+        value={props.value}
+        disabled={props.disabled}
+        rows={1}
+        placeholder={props.placeholder}
+        onFocus={props.onFocus}
+        onChange={props.onChange}
+        onKeyDown={props.onKeyDown}
+      />
+    </div>
+  )
+}
+
 /**
  * Composer takeover boundary; the carrier key keys local drafts, so a
  * same-request replay (same key, new carrier object) preserves them.
@@ -164,11 +219,10 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick<Questi
     submitDrafts(drafts)
   }
 
-  // Shared by the inline custom input and the optionless textarea: a
-  // multi-select draft retains checked labels, while a single-select custom
-  // answer replaces its selection. Enter continues the flow (Shift+Enter
-  // stays a newline in the textarea; on the single-line input it is inert).
-  const draftCustom = (event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>): void => {
+  // Shared by the inline custom field and the optionless one: a multi-select
+  // draft retains checked labels, while a single-select custom answer replaces
+  // its selection. Enter continues the flow, Shift+Enter breaks a line.
+  const draftCustom = (event: ChangeEvent<HTMLTextAreaElement>): void => {
     const value = event.target.value
     updateDraft(current => ({
       ...current,
@@ -178,7 +232,7 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick<Questi
     }))
   }
 
-  const continueFromCustom = (event: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>): void => {
+  const continueFromCustom = (event: KeyboardEvent<HTMLTextAreaElement>): void => {
     if (event.key !== 'Enter' || event.shiftKey || isComposing(event)) return
     event.preventDefault()
     continueFlow()
@@ -295,9 +349,8 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick<Questi
                             <IconEditOutline16 size={12} />
                           </span>
                         )}
-                      <input
-                        type="text"
-                        className={css.customInput}
+                      <AnswerField
+                        variant="inline"
                         value={draft.custom}
                         disabled={busy !== null}
                         placeholder={t('custom.placeholder')}
@@ -307,12 +360,11 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick<Questi
                     </div>
                   )
                   : (
-                    <textarea
+                    <AnswerField
                       autoFocus={!focusedQuestions.current.has(index)}
-                      className={css.customTextarea}
+                      variant="block"
                       value={draft.custom}
                       disabled={busy !== null}
-                      rows={2}
                       placeholder={t('custom.placeholder')}
                       onFocus={() => { focusedQuestions.current.add(index) }}
                       onChange={draftCustom}
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index cb00543200..7c16c6e61b 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -204,6 +204,43 @@ describe('QuestionComposer', () => {
     expect(respond).not.toHaveBeenCalled()
   })
 
+  it('answers over multiple lines: both fields grow with the draft and keep Shift+Enter a newline', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    // Both question shapes answer into a textarea, so the engine soft-wraps a
+    // long answer and Shift+Enter breaks the line natively.
+    const inline = screen.getByPlaceholderText('输入你的答案')
+    expect(inline.tagName).toBe('TEXTAREA')
+
+    const multiline = '第一行\n第二行'
+    fireEvent.change(inline, { target: { value: multiline } })
+    // The hidden height ruler carries the draft plus the trailing newline the
+    // textarea's own last line needs, so the box is as tall as the answer.
+    expect(inline.previousElementSibling?.textContent).toBe(`${multiline}\n`)
+    // Shift+Enter belongs to the field, never to the flow.
+    fireEvent.keyDown(inline, { key: 'Enter', shiftKey: true })
+    expect(screen.getByText('1 / 3')).toBeTruthy()
+
+    fireEvent.keyDown(inline, { key: 'Enter' })
+    const optionless = screen.getByPlaceholderText('输入你的答案')
+    expect(optionless.tagName).toBe('TEXTAREA')
+    fireEvent.change(optionless, { target: { value: multiline } })
+    expect(optionless.previousElementSibling?.textContent).toBe(`${multiline}\n`)
+    fireEvent.keyDown(optionless, { key: 'Enter', shiftKey: true })
+    expect(screen.getByText('2 / 3')).toBeTruthy()
+
+    fireEvent.keyDown(optionless, { key: 'Enter' })
+    fireEvent.click(screen.getByRole('checkbox', { name: '系统设计' }))
+    fireEvent.click(screen.getByRole('button', { name: '提交' }))
+    // Line breaks reach the model verbatim: nothing along the way flattens them.
+    expect(respond).toHaveBeenCalledWith(answeredEnvelope('question-1', [
+      { id: 'profile', selected: [], custom: multiline },
+      { id: 'detail', selected: [], custom: multiline },
+      { id: 'signals', selected: ['系统设计'] },
+    ]))
+  })
+
   it('surfaces cancellation failures: rejected receipt text and raw transport reasons', async () => {
     const respond = vi.fn()
       .mockResolvedValueOnce({ accepted: false, reason: 'bad-response' })

From 4562616c9b5b13ca1fb4f51a7a55fe7b6def2a7a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 20 Aug 2026 15:27:59 +0800
Subject: [PATCH 08/34] docs(apiproxy): record that a pending question dies
 with the host

The pending-question registry holds the awaiting tool call's own
resolve/reject, so it is host-process memory. events.mux replays every
still-pending question on reopen, which covers a browser reload or a
reconnect, but a host restart takes the awaiting turn with it and the
reopened Session offers no composer for that question.
---
 packages/host/apiproxy/README.i18n.yaml | 4 ++--
 packages/host/apiproxy/README.md        | 1 +
 packages/host/apiproxy/README.zh.md     | 1 +
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index b658b72b5b..25ad8e88a5 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.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 packages/host/apiproxy/README.md
-README.md: 27efe5a75eb6947d71f95c0a60e590c15a35887c
-README.zh.md: 71f4e63a013170c6822a5c8dae28bc5f899b271a
+README.md: a9fb07519c1d8b3b2e2d759bd9138dac60f2306f
+README.zh.md: 9bde3583b0f5e6ce172bfe145f440150aabfa230
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 27efe5a75e..a9fb07519c 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -76,6 +76,7 @@ None; this package neither assembles nor sends a provider request.
 
 - **Forwarded Remote events are parasitic on this legacy frame union** — `host/remote-event` lives in `HostFrame` so the delivery path could reuse the existing host stream instead of opening a third downlink, which makes it read as if this package owned the Remote event contract. It does not: the allowlist is `dsh-api-remotes`' and the consumer verb is `ctx.remote.$on`. When the host stream moves off this package, the frame moves with it and the consumer contract is unaffected ([rationale](../../../.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md)).
 - **Pending-interaction state is host-side** — the wire uses POST `/api/respond` plus `RpcReceipt`; the table in `src/api-proxy.ts` handles questions only and has no approval entries.
+- **A pending question does not survive a host restart** — the registry holds the awaiting tool call's own `resolve`/`reject`, so it is host-process memory. `events.mux` replays every still-pending question on each reopen, which covers a browser reload or a reconnect; a host restart takes the awaiting turn with it, and the reopened Session offers no composer for that question. Restoring one across a host restart needs a durable pending-interaction record and is deferred.
 - **Reserved seams stay out of `RpcMethodMap`** — `prompt.mode: 'inject'`, `job.list`, and a describe `hostInstanceId` are documented reservations; model discovery uses `llm.models`. An unknown method fails loud at envelope parse rather than getting a not-implemented code.
 - **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.
 - **Search failures include provider diagnostics** — the gateway is a single-user local service. A carrier that exposes it to multiple users must replace internal search details with a public-safe diagnostic.
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 71f4e63a01..9bde3583b0 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -76,6 +76,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 - **转发的 Remote 事件寄居在这套 legacy 帧联合里**：`host/remote-event` 住在 `HostFrame` 中，是为了让投递路径复用现有宿主流、不必新开第三条下行通道，因此读起来像是本包拥有 Remote 事件契约。并非如此：名单归 `dsh-api-remotes`，消费端动词是 `ctx.remote.$on`。将来宿主流整体搬离本包时，该帧随之搬走，消费端契约不受影响（[原委](../../../.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md)）。
 - **待处理交互状态位于宿主侧**：wire 使用 POST `/api/respond` 加 `RpcReceipt`；`src/api-proxy.ts` 中的表只处理问题，不包含审批条目。
+- **待回答的提问无法跨宿主重启存活**：登记表持有等待中那次工具调用自身的 `resolve`／`reject`，因此它是宿主进程内存。`events.mux` 在每次重开时重放所有仍在等待的提问，这覆盖了浏览器刷新与重连；宿主重启则把等待中的 turn 一并带走，重新打开的 Session 不会为该提问提供任何作答界面。要让它跨宿主重启恢复，需要一份持久化的待处理交互记录，此项暂缓。
 - **预留 seam 不进入 `RpcMethodMap`**：`prompt.mode: 'inject'`、`job.list` 和描述字段 `hostInstanceId` 都是已记录的预留项；模型发现使用 `llm.models`。未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。
 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
 - **搜索失败会包含提供方诊断信息**：网关是单用户本地服务。将其暴露给多名用户的载体必须用可安全公开的诊断信息替代内部搜索细节。

From 16affb84fb9b350fdd57d3e886b2edbd9bfdbe4e Mon Sep 17 00:00:00 2001
From: Chinesezjc <jczhai@deepseek.com>
Date: Thu, 20 Aug 2026 15:41:24 +0800
Subject: [PATCH 09/34] fix(cic): restore subscription-type gates and note
 table for split publish

Address the fresh review pass on PR #2798:

- ci-workflow.spec.ts: restore the subscription-type assertions the rewrite had
  dropped (issue-lifecycle pull_request types omit ready_for_review and include
  review_requested; pull_request_review types == ['submitted']) alongside the
  new step-level gate checks, so the 'tests pin the subscribed events' gate
  holds.
- 2026-08-10-npm-release-sequences note (en/zh/i18n): the three-sequence table's
  Workflow column now lists the pack and publish workflows for dsh/vendor, and
  line 114 no longer claims release.yml publishes (the dsh pack job packs the
  vendored family for verification; release-publish.yml repacks and publishes).

Follow-up for the pack-job copy drift is filed as #2816.
---
 .../process/2026-08-10-npm-release-sequences.i18n.yaml    | 4 ++--
 .../process/2026-08-10-npm-release-sequences.md           | 6 +++---
 .../process/2026-08-10-npm-release-sequences.zh.md        | 6 +++---
 scripts/ci-workflow.spec.ts                               | 8 ++++++++
 4 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
index 763362d57c..e398a80e6d 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.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/process/2026-08-10-npm-release-sequences.md
-2026-08-10-npm-release-sequences.md: c2cf540ff130f2a17a40068a0684c9bbc0e07ee3
-2026-08-10-npm-release-sequences.zh.md: 378c0a007ec30ad05fe9bcb9d068d095ccb658bc
+2026-08-10-npm-release-sequences.md: fe823e22997e5a3238d0e239d0f00f331549a5a1
+2026-08-10-npm-release-sequences.zh.md: d7aaaeaed33f639a890962cf9a95f24284eb9a35
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
index c2cf540ff1..fe823e2299 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
@@ -22,8 +22,8 @@ Two hard blockers sat in the way. All 217 workspace manifests set `private: true
 
 | Sequence | Members | Version baseline | Tag | Workflow |
 |---|---|---|---|---|
-| dsh | Publish set: non-experimental `packages/*/*` + `apps/*`; private experimental packages join only the shared version bump | one version for the publish set, private dsh packages, and workspace root, `0.0.x` | `dsh-v<version>` | `release.yml` |
-| vendored framework | the nine `vendor/*` packages | each package on its own version line | `vendor-<package>-v<version>` (one per package) | `release-vendor.yml` |
+| dsh | Publish set: non-experimental `packages/*/*` + `apps/*`; private experimental packages join only the shared version bump | one version for the publish set, private dsh packages, and workspace root, `0.0.x` | `dsh-v<version>` | `release.yml` (pack) / `release-publish.yml` (publish) |
+| vendored framework | the nine `vendor/*` packages | each package on its own version line | `vendor-<package>-v<version>` (one per package) | `release-vendor.yml` (pack) / `release-vendor-publish.yml` (publish) |
 | native | `native/landlock-run/packages/*` | its own `0.0.x` | `landlock-run-v<version>` | `landlock-run-release.yml` |
 
 All three publish to the `@deepseek-ai` scope on npmjs.com, and access is per sequence rather than per scope: the vendored framework and the native packages are `public`, the dsh family is `restricted` ([rationale](2026-08-13-public-vendor-and-native-sequences.md)). No publish path passes `--access`, because one flag cannot serve sequences that disagree and would override the manifest that owns the level.
@@ -111,7 +111,7 @@ The `pack` job walks the whole release set once, packing each member into one di
 
 `pack` carries no credentials and runs on every pull request and master push, so a pull request proves the release set still packs. Publication lives in a separate `release-publish.yml` / `release-vendor-publish.yml` workflow that is `workflow_dispatch`-only (so it never appears as a PR check): it repacks the current tree and then publishes each entry in order, behind the `npm-publish` environment for human approval. Pack runs are grouped per ref so concurrent pull requests do not displace each other; the publish workflow carries the global `Release-publish` group, because dist-tags are shared registry state.
 
-A dsh verification installs the vendored family's pack output too. The harness packages declare the vendored framework as a peer, those packages live in another sequence, and the credential-free job cannot fetch them from a private registry — so `release.yml` packs the vendored family for verification while publishing only its own set.
+A dsh verification installs the vendored family's pack output too. The harness packages declare the vendored framework as a peer, those packages live in another sequence, and the credential-free job cannot fetch them from a private registry — so the dsh `pack` job packs the vendored family for verification while publishing only the dsh set. The publish workflow (`release-publish.yml`) repacks the current tree and publishes only the dsh set.
 
 The verification also packs the Landlock entry, which `dsh-sandbox-local` declares as a plain dependency, and omits optional dependencies. The platform packages behind those optional entries need a musl toolchain and one build per architecture, so a job on one runner cannot produce them; a consumer that cannot install them must still start, which is what optional means here. The verification therefore reads a directory by its contents rather than a pack order, because a directory can hold tarballs packed only to satisfy a cross-sequence dependency.
 
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
index 378c0a007e..d7aaaeaed3 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
@@ -22,8 +22,8 @@ Status: implemented
 
 | 序列 | 成员 | 版本基线 | tag | workflow |
 |---|---|---|---|---|
-| dsh | 发布集：非 experimental 的 `packages/*/*` + `apps/*`；私有实验性包仅加入共享版本 bump | 发布集、私有 dsh 包与 workspace 根共用一个 `0.0.x` | `dsh-v<版本>` | `release.yml` |
-| vendored framework | `vendor/*` 九个包 | 每包各自一条版本线 | `vendor-<包名>-v<版本>`（每包一个） | `release-vendor.yml` |
+| dsh | 发布集：非 experimental 的 `packages/*/*` + `apps/*`；私有实验性包仅加入共享版本 bump | 发布集、私有 dsh 包与 workspace 根共用一个 `0.0.x` | `dsh-v<版本>` | `release.yml`（pack）/ `release-publish.yml`（发布） |
+| vendored framework | `vendor/*` 九个包 | 每包各自一条版本线 | `vendor-<包名>-v<版本>`（每包一个） | `release-vendor.yml`（pack）/ `release-vendor-publish.yml`（发布） |
 | native | `native/landlock-run/packages/*` | 自己的 `0.0.x` | `landlock-run-v<版本>` | `landlock-run-release.yml` |
 
 三组一律发到 npmjs.com 的 `@deepseek-ai` scope，且 access 按序列而非按 scope 区分：vendored 框架与 native 包是 `public`，dsh 族是 `restricted`（[理由](2026-08-13-public-vendor-and-native-sequences.md)）。没有任何发布路径传 `--access`——一个选项无法服务级别互不相同的序列，且会覆盖真正拥有该级别的 manifest。
@@ -111,7 +111,7 @@ dsh 族套用仓库的发布 payload 策略（拒绝源码与声明映射）。v
 
 `pack` 无凭据，在每个 pull request 和每次 master push 上跑，所以一个 pull request 就能证明发布集仍能完整打出来。发布则位于独立的 `release-publish.yml` / `release-vendor-publish.yml` 工作流，仅 `workflow_dispatch`（因此不会作为 PR check 出现）：它重新打包当前树，再按顺序逐个发布，挂在 `npm-publish` environment 后面等人工审批。pack 的 run 按 ref 分组，并发的 pull request 不会互相顶掉；全局 `Release-publish` 分组落在发布工作流上，因为 dist-tag 是共享的 registry 状态。
 
-dsh 的验证会一并安装 vendored 族的 pack 产物。harness 的包把 vendored 框架声明成 peer，而那些包属于另一条序列，无凭据的 job 无法从私有 registry 取到——所以 `release.yml` 为验证而打包 vendored 族，发布的仍只有自己那一份。
+dsh 的验证会一并安装 vendored 族的 pack 产物。harness 的包把 vendored 框架声明成 peer，而那些包属于另一条序列，无凭据的 job 无法从私有 registry 取到——所以 dsh 的 `pack` job 为验证而打包 vendored 族，发布的仍只有 dsh 那一份。发布工作流（`release-publish.yml`）重新打包当前树，只发布 dsh 族。
 
 验证还会打一份 Landlock entry 的 tarball——`dsh-sandbox-local` 把它声明为普通 `dependencies`——同时略去可选依赖。那些可选项背后的平台包需要 musl 工具链且每个架构各构建一次，单台 runner 产不出来；而装不到它们的消费方也必须能起，这正是「可选」在这里的含义。因此验证按目录内容读取 tarball，而不是读发布顺序：一个目录可能只装着为满足跨序列依赖而打出来的包，任何发布顺序都不描述它。
 
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 0740a6a6fb..ac4535bc1b 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -430,6 +430,14 @@ describe('Issue lifecycle workflow', () => {
     expect(lifecycle.on).toHaveProperty('pull_request')
     expect(lifecycle.on).toHaveProperty('pull_request_review')
     expect(lifecycleJob.if).toBeUndefined()
+    // Keep the subscription-type gates: issue-lifecycle does not re-subscribe
+    // ready_for_review (issue-policy owns that) and only reacts to submitted
+    // review events.
+    const lifecyclePullRequest = workflowEvent(lifecycle, 'pull_request')
+    const lifecycleReview = workflowEvent(lifecycle, 'pull_request_review')
+    expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
+    expect(lifecyclePullRequest.types).toContain('review_requested')
+    expect(lifecycleReview.types).toEqual(['submitted'])
     const gated = "${{ github.event_name != 'pull_request_review' || github.event.review.state == 'changes_requested' }}"
     const steps = lifecycleJob.steps.filter(isRecord)
     const tokenStep = steps.find(s => s.name === 'Create project token')

From 56a8f7d325baaf8cd8016b2954bd0f587e153dfc Mon Sep 17 00:00:00 2001
From: Chinesezjc <jczhai@deepseek.com>
Date: Thu, 20 Aug 2026 15:59:40 +0800
Subject: [PATCH 10/34] fix(cic): cover release-publish in client-build gate
 and correct group wording

Address the latest review pass on PR #2798:

- client-build-environment.client.spec.ts: add release-publish.yml to
  dshBuildWorkflows so the 'workflow env must not set DSH_CLIENT_*' gate covers
  the new dsh publish path (it runs build:official and writes a dsh client
  build record). vendor-publish runs only build:lib:host, so it is not added.
- 2026-08-10-npm-release-sequences note (en/zh/i18n): the Release-publish group
  is carried by the publish job (job-level concurrency), not the whole
  workflow; corrected the wording.
---
 .../process/2026-08-10-npm-release-sequences.i18n.yaml        | 4 ++--
 .../implemented/process/2026-08-10-npm-release-sequences.md   | 2 +-
 .../process/2026-08-10-npm-release-sequences.zh.md            | 2 +-
 scripts/client-build-environment.client.spec.ts               | 1 +
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
index e398a80e6d..379585f190 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.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/process/2026-08-10-npm-release-sequences.md
-2026-08-10-npm-release-sequences.md: fe823e22997e5a3238d0e239d0f00f331549a5a1
-2026-08-10-npm-release-sequences.zh.md: d7aaaeaed33f639a890962cf9a95f24284eb9a35
+2026-08-10-npm-release-sequences.md: 487f2dbe717375b2adb7daf18550799544d2e147
+2026-08-10-npm-release-sequences.zh.md: 051c1c9fd0e8d5330477c5e3053c55f1b51d1802
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
index fe823e2299..487f2dbe71 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md
@@ -109,7 +109,7 @@ The dsh family applies the repository's publication payload policy, which reject
 
 The `pack` job walks the whole release set once, packing each member into one directory, writes the upload order, and uploads that directory as one artifact; it lives in `release.yml` / `release-vendor.yml`. The release set is one unit — half the packages can never reach the registry while the other half is still building.
 
-`pack` carries no credentials and runs on every pull request and master push, so a pull request proves the release set still packs. Publication lives in a separate `release-publish.yml` / `release-vendor-publish.yml` workflow that is `workflow_dispatch`-only (so it never appears as a PR check): it repacks the current tree and then publishes each entry in order, behind the `npm-publish` environment for human approval. Pack runs are grouped per ref so concurrent pull requests do not displace each other; the publish workflow carries the global `Release-publish` group, because dist-tags are shared registry state.
+`pack` carries no credentials and runs on every pull request and master push, so a pull request proves the release set still packs. Publication lives in a separate `release-publish.yml` / `release-vendor-publish.yml` workflow that is `workflow_dispatch`-only (so it never appears as a PR check): it repacks the current tree and then publishes each entry in order, behind the `npm-publish` environment for human approval. Pack runs are grouped per ref so concurrent pull requests do not displace each other; the `publish` job carries the global `Release-publish` group, because dist-tags are shared registry state.
 
 A dsh verification installs the vendored family's pack output too. The harness packages declare the vendored framework as a peer, those packages live in another sequence, and the credential-free job cannot fetch them from a private registry — so the dsh `pack` job packs the vendored family for verification while publishing only the dsh set. The publish workflow (`release-publish.yml`) repacks the current tree and publishes only the dsh set.
 
diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
index d7aaaeaed3..051c1c9fd0 100644
--- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
+++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md
@@ -109,7 +109,7 @@ dsh 族套用仓库的发布 payload 策略（拒绝源码与声明映射）。v
 
 `pack` job 一趟遍历整个发布集，把每个成员打进同一个目录，写出上传顺序，整个目录作为一份 artifact 上传；它位于 `release.yml` / `release-vendor.yml`。发布集是一个整体——绝不会出现一半的包已经上了 registry、另一半还在构建。
 
-`pack` 无凭据，在每个 pull request 和每次 master push 上跑，所以一个 pull request 就能证明发布集仍能完整打出来。发布则位于独立的 `release-publish.yml` / `release-vendor-publish.yml` 工作流，仅 `workflow_dispatch`（因此不会作为 PR check 出现）：它重新打包当前树，再按顺序逐个发布，挂在 `npm-publish` environment 后面等人工审批。pack 的 run 按 ref 分组，并发的 pull request 不会互相顶掉；全局 `Release-publish` 分组落在发布工作流上，因为 dist-tag 是共享的 registry 状态。
+`pack` 无凭据，在每个 pull request 和每次 master push 上跑，所以一个 pull request 就能证明发布集仍能完整打出来。发布则位于独立的 `release-publish.yml` / `release-vendor-publish.yml` 工作流，仅 `workflow_dispatch`（因此不会作为 PR check 出现）：它重新打包当前树，再按顺序逐个发布，挂在 `npm-publish` environment 后面等人工审批。pack 的 run 按 ref 分组，并发的 pull request 不会互相顶掉；全局 `Release-publish` 分组落在 `publish` job 上，因为 dist-tag 是共享的 registry 状态。
 
 dsh 的验证会一并安装 vendored 族的 pack 产物。harness 的包把 vendored 框架声明成 peer，而那些包属于另一条序列，无凭据的 job 无法从私有 registry 取到——所以 dsh 的 `pack` job 为验证而打包 vendored 族，发布的仍只有 dsh 那一份。发布工作流（`release-publish.yml`）重新打包当前树，只发布 dsh 族。
 
diff --git a/scripts/client-build-environment.client.spec.ts b/scripts/client-build-environment.client.spec.ts
index cce5cff2a0..e2eb0ebe72 100644
--- a/scripts/client-build-environment.client.spec.ts
+++ b/scripts/client-build-environment.client.spec.ts
@@ -26,6 +26,7 @@ const dshBuildWorkflows = [
   'e2b-e2e.yml',
   'e2e.yml',
   'release.yml',
+  'release-publish.yml',
   'sandbox.yml',
 ]
 

From 156bd075a9c8cdbd7fcfb075e15807e961add968 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 10:54:03 +0800
Subject: [PATCH 11/34] feat(webserver): structured index injection table and
 the client boot seams

Replace per-plugin tapIndex regex edits with pure-data IndexInjection rows
collected fresh per render over one webserver/index-inject event. One table,
two renderers: the served form renders rows into index.html; a static worker
form ships the same rows over its boot payload. tapIndex survives as the
raw-HTML escape hatch, applied after row rendering; client-modules and
ui-theme move to the event, and the manifest global renders as
globalThis["__DSH_BOOT__"].

The client boot chain gains the seams a pre-injected transport needs: the
module loader takes loadBundle from the transport global by default, HTTP
prefetch stands down when a transport owns bundle bytes, the web-app bundle
can decline frontend serving, the gateway client installs a namespace's
whole method group inside its fiber apply so a parked dependent never
observes the service without its methods, and the dynamic-code precheck
gates through new Function so hosts without a real node:vm keep the
define-time parse gate.
---
 ...-08-19-web-index-injection-table.i18n.yaml |   6 +
 .../2026-08-19-web-index-injection-table.md   |  30 ++++
 ...2026-08-19-web-index-injection-table.zh.md |  30 ++++
 apps/web/tests/assembled-boot.ts              |   9 +-
 packages/api/gateway/src/client/index.ts      | 161 +++++++++++-------
 packages/bundle/web-app/tests/web-app.spec.ts |   2 +-
 .../client/connection/src/client/index.ts     |  32 +++-
 packages/client/connection/src/client/rpc.ts  |   9 +-
 packages/client/modules/src/index.ts          |  60 +++----
 .../modules/tests/node-half.client.spec.ts    |  13 +-
 packages/client/ui-theme/package.json         |   6 +-
 packages/client/ui-theme/src/boot-theme.ts    |  34 ++--
 packages/client/ui-theme/src/index.ts         |  16 +-
 .../ui-theme/tests/boot-theme.client.spec.ts  |  32 ++--
 .../client/ui-theme/tests/host.client.spec.ts |  46 ++---
 packages/client/web/src/boot.ts               |   9 +
 .../cordis-host-runner/src/sandbox.ts         |  35 +++-
 packages/host/frontend-static/src/index.ts    |   8 +-
 packages/host/webserver/src/index.ts          |  42 ++++-
 packages/host/webserver/src/injections.ts     | 104 +++++++++++
 .../host/webserver/tests/webserver.spec.ts    |  50 +++++-
 21 files changed, 533 insertions(+), 201 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
 create mode 100644 packages/host/webserver/src/injections.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml
new file mode 100644
index 0000000000..1c228865dc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.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/architecture/2026-08-19-web-index-injection-table.md
+2026-08-19-web-index-injection-table.md: a4c21974ef6770320b61cd7c2b19fc20372e8111
+2026-08-19-web-index-injection-table.zh.md: 4ccfa8afe6353e9af7e341ce73f5fb3213257ba2
diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
new file mode 100644
index 0000000000..a4c21974ef
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
@@ -0,0 +1,30 @@
+# Agent Note: structured index injection table (webserver/index-inject)
+
+Status: implemented
+
+English | [中文](2026-08-19-web-index-injection-table.zh.md)
+
+## Problem
+
+The web shell's boot HTML needs three kinds of injection: client-modules' boot protocol (the `__ModuleLoader__` registration queue inline script, the parser-blocking preload `<script src>` tags, the `__DSH_BOOT__` graph global) and ui-theme's first-paint theme script. The old mechanism was `webServer.tapIndex(html => html)` string transforms: each registrant regex-located `<head>`/`<body>` and spliced HTML on its own. The static worker deployment (the page is a build artifact; the host tree runs in a Web Worker) has no serve-HTML step at all, so the worker side hand-copied the same data into its `/__boot__` payload (`graph` + `theme` via `ctx.get`), and the page side re-implemented what the taps did (a facade installer, a theme applier, a preload loop) — one boot semantics, three implementations.
+
+## Decision
+
+Make the injection surface an event over pure data: the webserver declares the `webserver/index-inject` event and the `IndexInjection` row union (`global`/`script`/`script-src`/`style`/`html`, `head|body` placement). A plugin that wants to inject subscribes and pushes rows; every collection (`collectIndexInjections()`) is a fresh emit, so subscribers read live state at emit time (module graph, theme preference — no re-registration staleness), and a subscription dies with its fiber.
+
+One table, two renderers: the served form's `webServer.renderIndex(html)` renders rows into index.html deterministically (head rows after the opening head tag, body rows after the opening body tag; `<` JSON-escaped in global values, attribute-escaped `src`); the worker form's `/__boot__` payload is `{ injections }`, executed row by row by a small page-side interpreter (set global / create script element / load external through the tunnel's `loadBundle` / mount style and markup). Rows are pure JSON data — that is the both-ends-equivalent discipline.
+
+`tapIndex`/`applyIndexTaps` survive as the raw-HTML escape hatch, applied after row rendering; every internal consumer moved to the event.
+
+## Consequences
+
+- client-modules and ui-theme no longer regex-edit HTML; the worker's `readBootPayload` service-poking (`clientModules`, `settings`, theme constants through `loader.load`) is deleted; the page-side `installModuleLoaderFacade`, `applyBootTheme`, and `PARSER_PRELOAD_IDS` re-implementations retire.
+- Ordering: across subscribers, subscription order (same as the old tap order); within one subscriber, push order — modules itself guarantees queue → preloads → global.
+- The served rendering of the manifest global changed from `window.__DSH_BOOT__ =` to `globalThis["__DSH_BOOT__"] =`; snapshot expectations carrying that text need re-recording.
+- New model-visible or page-visible boot inputs extend the row union; no new tap consumers.
+
+## Alternatives considered
+
+- **Keep tap functions, add a worker-side renderer that re-runs them over a fake document** — rejected: taps are opaque `html => html` closures, so the worker cannot serialize or replay them without shipping a DOM emulation into the boot path.
+- **A registration-style table (`registerInjection(row): dispose`)** — rejected for the two problems the event dissolves: rows staled against live state (theme preference, module graph) unless every producer re-registered on change, and every producer owned one more disposer. The per-emit pull reads fresh state with fiber-scoped cleanup for free.
+- **Deleting `tapIndex` outright** — rejected: an escape hatch for raw HTML transforms costs nothing while the table is young, and external compositions may have transforms no row kind expresses yet.
diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
new file mode 100644
index 0000000000..4ccfa8afe6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
@@ -0,0 +1,30 @@
+# Agent Note: 结构化 index 注入表（webserver/index-inject 事件）
+
+Status: implemented
+
+[English](2026-08-19-web-index-injection-table.md) | 中文
+
+## Problem
+
+Web 壳的启动 HTML 需要三类注入：client-modules 的引导协议（`__ModuleLoader__` 注册队列内联脚本、parser 阻塞的 preload `<script src>`、`__DSH_BOOT__` 全局图）与 ui-theme 的首帧主题脚本。旧机制是 `webServer.tapIndex(html => html)` 字符串变换：每个注册方各自用正则找 `<head>`/`<body>` 改 HTML。静态 worker 部署（页面是构建产物、host 树在 Web Worker 里）没有「服 HTML」这一步，于是 worker 侧只能在 `/__boot__` 载荷里手工重抄同一批数据（graph + theme，经 `ctx.get` 硬掏），页面侧再用手写代码（facade 安装、theme 应用、preload 循环）把 tap 干的事重演一遍——同一份启动语义存在三份实现。
+
+## Decision
+
+注入面事件化、数据化：webserver 声明 `webserver/index-inject` 事件与纯数据行类型 `IndexInjection`（`global`/`script`/`script-src`/`style`/`html`，`head|body` 定位）。想注入的插件订阅事件、往表里 push 行；每次收集（`collectIndexInjections()`）都是一次全新 emit，订阅方现读现填（模块图、主题偏好天然新鲜，无重注册问题），订阅随 fiber 销毁自动摘除。
+
+一张表两个渲染器：served 形态 `webServer.renderIndex(html)` 确定性把行渲染进 index.html（head 行插 head 首、body 行插 body 首，全局值 JSON `<` 转义、src 属性转义）；worker 形态 `/__boot__` 载荷就是 `{ injections }`，页面侧小解释器逐行执行（设全局 / 建脚本元素 / 经 tunnel loadBundle 载外链 / 挂样式与 DOM）。行是纯 JSON 数据，这是双端等价的纪律。
+
+`tapIndex`/`applyIndexTaps` 保留为原始 HTML 变换的逃生口，在行渲染之后执行；内部消费者全部迁走。
+
+## Consequences
+
+- client-modules 与 ui-theme 不再各自正则改 HTML；worker 侧 `readBootPayload` 的 `ctx.get` 手掏（clientModules、settings、theme 常量 loader.load）删除；页面侧 `installModuleLoaderFacade`、`applyBootTheme`、`PARSER_PRELOAD_IDS` 三份重抄退役。
+- 顺序语义：跨订阅方按订阅注册顺序（与旧 tap 顺序一致），单订阅方内按 push 顺序；modules 自己保证 队列→preload→全局 三行有序。
+- `__DSH_BOOT__` 的 served 渲染文本从 `window.__DSH_BOOT__ =` 变为 `globalThis["__DSH_BOOT__"] =`；含此文本的快照期望需重录。
+- 新的模型可见/页面可见注入一律走行类型扩展，不再新增 tap 消费者。
+
+## Alternatives considered
+
+- **保留 tap 函数、worker 侧对假 document 重放**——否决：tap 是不透明的 `html => html` 闭包，worker 无法序列化或重放，除非把 DOM 仿真塞进启动链。
+- **注册表式（`registerInjection(row): dispose`）**——否决于事件天然化解的两个问题：行数据会相对活状态（主题偏好、模块图）过期，除非每个生产者变更时重注册；且每个生产者多背一个 disposer。按次 emit 的拉取免费获得新鲜读取与 fiber 级清理。
+- **直接删除 `tapIndex`**——否决：表还年轻，原始 HTML 变换的逃生口零成本，外部组合可能还有行类型暂不能表达的变换。
diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
index cb079a344c..981836775c 100644
--- a/apps/web/tests/assembled-boot.ts
+++ b/apps/web/tests/assembled-boot.ts
@@ -13,7 +13,7 @@ import { dirname, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { act, cleanup } from '@testing-library/react'
 import { afterEach, beforeEach, vi } from 'vitest'
-import { injectBootManifest, orderByModuleGraph } from '@deepseek-ai/dsh-client-modules'
+import { bootInjections, orderByModuleGraph } from '@deepseek-ai/dsh-client-modules'
 import type { ClientModuleLoaderTarget, WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
 import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
 
@@ -194,10 +194,9 @@ export function mountAssembledApp(search = '?fixture'): void {
   root.id = 'root'
   document.body.appendChild(root)
   win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ bundlePath: _bundlePath, ...plugin }) => plugin) }
-  const html = injectBootManifest('<head></head>', win.__DSH_BOOT__)
-  const facadeSource = /<head><script>([\s\S]*?)<\/script>/.exec(html)?.[1]
-  if (facadeSource === undefined) throw new Error('missing injected ModuleLoader facade')
-  ;(0, eval)(facadeSource)
+  const [facadeRow] = bootInjections(win.__DSH_BOOT__)
+  if (facadeRow?.kind !== 'script') throw new Error('missing injected ModuleLoader facade row')
+  ;(0, eval)(facadeRow.text)
   // Mirror the blocking Host-injected scripts before the Vite entry calls create().
   for (const id of ['@deepseek-ai/dsh-client-modules', '@deepseek-ai/dsh-client-runtime']) {
     const plugin = PLUGINS.find(candidate => candidate.id === id)
diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index c4b087fd5d..31e3db6711 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -52,6 +52,14 @@ interface RemoteNamespaceHandle {
   readonly dispose: TypertDisposer
 }
 
+/** One descriptor's mounted variants, for the group disposer to unwind. */
+interface InstalledMethod {
+  readonly descriptor: InvocationDescriptor
+  readonly token: MountToken
+  direct: boolean
+  scoped: boolean
+}
+
 /** Typed Remote service augmented by generated direct namespaces. */
 export type ClientRemote = TypertClientRemote
 
@@ -177,9 +185,17 @@ class ClientRemoteService extends Service implements TypertClientRemote {
   ): Promise<TypertDisposer> {
     this.validateContribution(contribution)
     const disposeRemote = callerCtx.typert.remotes.register(contribution)
+    const groups = new Map<string, InvocationDescriptor[]>()
+    for (const descriptor of contribution.descriptors) {
+      const group = groups.get(descriptor.namespace)
+      if (group === undefined) groups.set(descriptor.namespace, [descriptor])
+      else group.push(descriptor)
+    }
     const installed: TypertDisposer[] = []
     try {
-      for (const descriptor of contribution.descriptors) installed.push(await this.install(descriptor))
+      for (const [namespace, descriptors] of groups) {
+        installed.push(await this.installNamespace(namespace, descriptors))
+      }
     } catch (error) {
       for (const dispose of installed.reverse()) await dispose()
       await disposeRemote()
@@ -235,66 +251,47 @@ class ClientRemoteService extends Service implements TypertClientRemote {
     }
   }
 
-  private async install(descriptor: InvocationDescriptor): Promise<TypertDisposer> {
-    const token: MountToken = { active: true, abort: new AbortController() }
-    const installed: TypertDisposer[] = []
-    try {
-      if (descriptor.invocation.kind === 'direct') {
-        installed.push(await this.installDirect(descriptor, token))
-      }
-      const projection = scopedProjection(descriptor)
-      if (projection !== undefined) installed.push(await this.installScoped(descriptor, projection, token))
-    } catch (error) {
-      token.active = false
-      token.abort.abort()
-      for (const dispose of installed.reverse()) await dispose()
-      throw error
-    }
-    return async () => {
-      /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
-      if (!token.active) return
-      token.active = false
-      token.abort.abort()
-      for (const dispose of installed.reverse()) await dispose()
-    }
-  }
-
-  private async installDirect(descriptor: InvocationDescriptor, token: MountToken): Promise<TypertDisposer> {
-    const namespace = await this.namespace(descriptor.namespace)
-    try {
-      namespace.service.installDirect(descriptor, token)
-    } catch (error) {
-      await this.disposeNamespace(descriptor.namespace, namespace)
-      throw error
-    }
-    return async () => {
-      namespace.service.remove('direct', descriptor.method, token)
-      await this.disposeNamespace(descriptor.namespace, namespace)
-    }
-  }
-
-  private async installScoped(
-    descriptor: InvocationDescriptor,
-    projection: ScopedProjection,
-    token: MountToken,
+  /**
+   * Mount one namespace's descriptor group with no visibility gap: a fresh
+   * namespace installs its whole group synchronously inside its fiber's
+   * apply, so a plugin parked on the namespace service never observes it
+   * without the methods the same contribution carries; an existing namespace
+   * takes the group in one synchronous step.
+   * @param name - Remote namespace.
+   * @param descriptors - Every contribution descriptor naming that namespace.
+   * @returns disposer unmounting the group and the namespace once empty.
+   */
+  private async installNamespace(
+    name: string,
+    descriptors: readonly InvocationDescriptor[],
   ): Promise<TypertDisposer> {
-    const namespace = await this.namespace(descriptor.namespace)
-    try {
-      namespace.service.installScoped(descriptor, projection, token)
-    } catch (error) {
-      await this.disposeNamespace(descriptor.namespace, namespace)
-      throw error
+    let namespace = this.namespaces.get(name)
+    let installed: InstalledMethod[]
+    if (namespace === undefined) {
+      ({ namespace, installed } = await this.createNamespace(name, descriptors))
+    } else {
+      installed = installMethods(namespace.service, descriptors)
     }
+    const handle = namespace
     return async () => {
-      namespace.service.remove('scoped', descriptor.method, token)
-      await this.disposeNamespace(descriptor.namespace, namespace)
+      for (const method of [...installed].reverse()) {
+        /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
+        if (!method.token.active) continue
+        method.token.active = false
+        method.token.abort.abort()
+        if (method.scoped) handle.service.remove('scoped', method.descriptor.method, method.token)
+        if (method.direct) handle.service.remove('direct', method.descriptor.method, method.token)
+      }
+      await this.disposeNamespace(name, handle)
     }
   }
 
-  private async namespace(name: string): Promise<RemoteNamespaceHandle> {
-    let namespace = this.namespaces.get(name)
-    if (namespace !== undefined) return namespace
+  private async createNamespace(
+    name: string,
+    descriptors: readonly InvocationDescriptor[],
+  ): Promise<{ namespace: RemoteNamespaceHandle; installed: InstalledMethod[] }> {
     let service: RemoteNamespaceService | undefined
+    let installed: InstalledMethod[] | undefined
     const fiber = this.ownerCtx.plugin({
       name: remoteServiceKey(name),
       apply: (ctx: Context) => {
@@ -303,6 +300,9 @@ class ClientRemoteService extends Service implements TypertClientRemote {
           name,
           (direct, scoped, caller, args) => this.invokeMethod(direct, scoped, caller, args),
         )
+        // Same synchronous window as the service registration: a dependent the
+        // new service unparks runs only after the methods exist.
+        installed = installMethods(service, descriptors)
       },
     })
     try {
@@ -311,11 +311,13 @@ class ClientRemoteService extends Service implements TypertClientRemote {
       await fiber.dispose()
       throw error
     }
-    /* v8 ignore next -- a settled namespace fiber synchronously constructs its Service. */
-    if (service === undefined) throw new Error(`client api: namespace ${JSON.stringify(name)} did not start`)
-    namespace = { service, dispose: fiber.dispose }
+    /* v8 ignore next 3 -- a settled namespace fiber synchronously constructs its Service and installs the group. */
+    if (service === undefined || installed === undefined) {
+      throw new Error(`client api: namespace ${JSON.stringify(name)} did not start`)
+    }
+    const namespace = { service, dispose: fiber.dispose }
     this.namespaces.set(name, namespace)
-    return namespace
+    return { namespace, installed }
   }
 
   private async disposeNamespace(name: string, namespace: RemoteNamespaceHandle): Promise<void> {
@@ -504,6 +506,49 @@ class RemoteNamespaceService extends Service {
   }
 }
 
+/**
+ * Install one descriptor group on a namespace service, unwinding the partial
+ * group when a descriptor is refused.
+ * @param service - Namespace service taking the methods.
+ * @param descriptors - Descriptor group of one contribution.
+ * @returns per-descriptor records for the group disposer.
+ */
+function installMethods(
+  service: RemoteNamespaceService,
+  descriptors: readonly InvocationDescriptor[],
+): InstalledMethod[] {
+  const installed: InstalledMethod[] = []
+  try {
+    for (const descriptor of descriptors) {
+      const method: InstalledMethod = {
+        descriptor,
+        token: { active: true, abort: new AbortController() },
+        direct: false,
+        scoped: false,
+      }
+      installed.push(method)
+      if (descriptor.invocation.kind === 'direct') {
+        service.installDirect(descriptor, method.token)
+        method.direct = true
+      }
+      const projection = scopedProjection(descriptor)
+      if (projection !== undefined) {
+        service.installScoped(descriptor, projection, method.token)
+        method.scoped = true
+      }
+    }
+  } catch (error) {
+    for (const method of [...installed].reverse()) {
+      method.token.active = false
+      method.token.abort.abort()
+      if (method.scoped) service.remove('scoped', method.descriptor.method, method.token)
+      if (method.direct) service.remove('direct', method.descriptor.method, method.token)
+    }
+    throw error
+  }
+  return installed
+}
+
 const REMOTE_NAMESPACE_FIELDS = new Set(['ctx', 'empty', 'invokeRemote', 'methods', 'name', 'namespace'])
 
 function remoteServiceKey(namespace: string): string {
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index ee4593cfd0..39b9d7ac6b 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -78,7 +78,7 @@ function fakeHttpServer(host: '127.0.0.1' | '0.0.0.0' = '127.0.0.1'): { server:
       fallback = handler
       return () => { fallback = undefined }
     },
-    applyIndexTaps: (html: string) => html,
+    renderIndex: (html: string) => html,
   } as unknown as WebServer
   return { server, seat: () => fallback }
 }
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 9847d48cdf..dce8d030bf 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -8,7 +8,7 @@ import type { HostDescription, IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
 import { WebApiClient } from './web-api-client.ts'
-import { createWebConnectionRpc } from './rpc.ts'
+import { createWebConnectionRpc, type RpcFetch } from './rpc.ts'
 import { isLoopbackHostname } from '../loopback-hostname.ts'
 import type { ClientConnectionRpc } from '../rpc.ts'
 
@@ -40,6 +40,7 @@ export {
 // controller remains package-internal.
 export type { ConnectionConfig, ConnectionSinks, ConnectionState }
 export type { ClientConnectionRpc } from '../rpc.ts'
+export type { RpcFetch } from './rpc.ts'
 
 /** Observable Host description published by each completed connection handshake. */
 export interface HostDescriptionSource {
@@ -52,6 +53,30 @@ export interface HostDescriptionSource {
 /** Required services (none — this is the wire root). */
 export const inject: string[] = []
 
+/**
+ * Carrier override installed on the page global before plugin boot. The served
+ * web app leaves it unset and gets HTTP + WebSocket; a shell that owns a
+ * different physical transport (the worker preview's postMessage tunnel)
+ * provides both halves here instead of forking this plugin.
+ */
+export interface ClientTransportHooks {
+  /** Build the API carrier: unary calls plus the two downstream event streams. */
+  createApiClient(): IApiClient
+  /** Transport for generic unary RPC channels (the Typert gateway). */
+  fetch: RpcFetch
+  /**
+   * Bundle transport for the module system, present when the carrier also owns
+   * bundle bytes (the worker tunnel). Absent in the served web app, whose
+   * bundles load over HTTP.
+   */
+  loadBundle?(url: string): Promise<void>
+}
+
+/** Page global carrying {@link ClientTransportHooks}; absent in the served web app. */
+interface ClientTransportGlobal {
+  __DSH_TRANSPORT__?: ClientTransportHooks
+}
+
 /**
  * The ctx.connection service API: the API client plus a one-shot
  * controller starter (the runtime plugin supplies sinks when its object layer
@@ -85,8 +110,9 @@ export function apply(ctx: Context): void {
   const pageLocation = typeof location === 'undefined' ? undefined : location
   const fixture = pageLocation !== undefined && new URLSearchParams(pageLocation.search).has('fixture')
   const fixtureClient = fixture ? new FixtureApiClient() : undefined
-  const api: IApiClient = fixtureClient ?? new WebApiClient()
-  const rpc = fixtureClient?.rpc ?? createWebConnectionRpc()
+  const transport = (globalThis as ClientTransportGlobal).__DSH_TRANSPORT__
+  const api: IApiClient = fixtureClient ?? transport?.createApiClient() ?? new WebApiClient()
+  const rpc = fixtureClient?.rpc ?? createWebConnectionRpc(transport?.fetch)
   let started = false
   let description: HostDescription | undefined
   const descriptionListeners = new Set<() => void>()
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
index f8bacb1553..8781b3ee34 100644
--- a/packages/client/connection/src/client/rpc.ts
+++ b/packages/client/connection/src/client/rpc.ts
@@ -12,11 +12,16 @@ const INTERNAL_BASE = 'http://dsh.internal'
 const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
 const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
 
+/** Transport this caller posts through; same signature as the global `fetch`. */
+export type RpcFetch = (input: URL, init: RequestInit) => Promise<Response>
+
 /**
  * Create the browser-backed generic RPC caller.
+ * @param doFetch - transport override; defaults to the page's global fetch.
  * @returns caller that owns request correlation and response-envelope validation.
  */
-export function createWebConnectionRpc(): ClientConnectionRpc {
+export function createWebConnectionRpc(doFetch?: RpcFetch): ClientConnectionRpc {
+  const send: RpcFetch = doFetch ?? ((input, init) => globalThis.fetch(input, init))
   return {
     async call(channel, endpoint, payload, signal) {
       assertTarget(channel, endpoint)
@@ -27,7 +32,7 @@ export function createWebConnectionRpc(): ClientConnectionRpc {
         method: endpoint,
         payload,
       }
-      const response = await globalThis.fetch(
+      const response = await send(
         new URL(`${channel}/${endpoint}`, resolveBase()),
         {
           method: 'POST',
diff --git a/packages/client/modules/src/index.ts b/packages/client/modules/src/index.ts
index a64e879ea3..58800dda2a 100644
--- a/packages/client/modules/src/index.ts
+++ b/packages/client/modules/src/index.ts
@@ -3,10 +3,10 @@
  * the host Loader's entries for packages declaring `dsh.client`, composes the
  * `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
  * in `./client/manifest.ts`) in module-graph order, serves
- * `/plugins/<id>/client.js` and its source map, taps the index render to
- * inject the boot manifest plus the parser-blocking bootstrap preloads, and
- * provides the `clientModuleHost` service (the HMR node half's
- * registration/notification face).
+ * `/plugins/<id>/client.js` and its source map, contributes the boot manifest
+ * plus the parser-blocking bootstrap preloads to the webserver's index
+ * injection table, and provides the `clientModuleHost` service (the HMR node
+ * half's registration/notification face).
  *
  * Scanning is incremental per package — there is no full-rescan code path.
  * Every cordis `internal/plugin` emission (fiber construction/disposal) marks
@@ -30,7 +30,7 @@ import { dirname, join } from 'node:path'
 import { Service } from '@deepseek-ai/cordis'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/cordis-plugin-loader'
-import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver'
 import { optionalStringArray, stripClientSuffix } from './client/manifest.ts'
 import type { WebBootEntry, WebBootGraph } from './client/manifest.ts'
 
@@ -228,31 +228,19 @@ const CLIENT_RUNTIME_ID = '@deepseek-ai/dsh-client-runtime'
 /** Ordinary dynamic bundles the HTML parser executes before the Vite shell. */
 const PARSER_PRELOAD_IDS = [CLIENT_MODULES_ID, CLIENT_RUNTIME_ID] as const
 
-/** Escape a graph URL before placing it in a quoted HTML attribute. */
-function escapeHtmlAttribute(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-}
-
 /**
- * Inject the boot protocol into index.html. The inline registration queue precedes
- * blocking classic scripts for modules' and runtime's ordinary
+ * The boot protocol as index injection rows. The inline registration queue
+ * precedes blocking classic scripts for modules' and runtime's ordinary
  * `lib/client.js` artifacts. Its `create()` method materializes the modules
  * bundle, delegates construction to that bundle, and leaves the same facade
- * in live-registration mode. The graph script follows before the shell reads
- * it. `<` is escaped in JSON so a plugin-controlled string cannot break out
- * of the script element.
- * @param html - the index.html source.
+ * in live-registration mode. The graph global follows before the shell reads
+ * it.
  * @param graph - the composed entry graph.
- * @returns the html with the graph script injected.
+ * @returns head rows in execution order: queue script, preload scripts, graph global.
  */
-export function injectBootManifest(html: string, graph: WebBootGraph): string {
-  const json = JSON.stringify(graph).replaceAll('<', '\\u003c')
+export function bootInjections(graph: WebBootGraph): IndexInjection[] {
   const bootstrapId = JSON.stringify(CLIENT_MODULES_ID)
-  const queue = `<script>(()=>{
+  const queue = `(()=>{
 const pendingQueue=[]
 window.__ModuleLoader__={
   mode:"queue",
@@ -273,21 +261,20 @@ window.__ModuleLoader__={
     return exports.createClientModuleSystem(this,{id:registration.id,exports},options)
   }
 }
-})()</script>`
+})()`
   const preload = PARSER_PRELOAD_IDS.map(id => graph.entries.find(entry => entry.id === id))
     .filter((entry): entry is WebBootEntry => entry !== undefined)
-    .map(entry => `<script src="${escapeHtmlAttribute(entry.url)}"></script>`)
-    .join('')
-  const script = `${queue}${preload}<script>window.__DSH_BOOT__ = ${json}</script>`
-  const head = html.indexOf('<head>')
-  if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
-  // Headless fixture pages may lack <head>; prepending keeps the read-before-shell ordering.
-  return `${script}${html}`
+    .map((entry): IndexInjection => ({ kind: 'script-src', placement: 'head', src: entry.url }))
+  return [
+    { kind: 'script', placement: 'head', text: queue },
+    ...preload,
+    { kind: 'global', name: '__DSH_BOOT__', value: graph },
+  ]
 }
 
 /**
  * The web plugin table service: incremental `dsh.client` scan + wire composition
- * + bundle route + index tap. Construction runs the activation scan
+ * + bundle route + index injection rows. Construction runs the activation scan
  * synchronously — a malformed declaration or missing bundle among the
  * already-loaded entries aggregates into one loud throw (FAILED fiber; the
  * boot activation audit reports it).
@@ -353,10 +340,9 @@ export class ClientModuleRegistry extends Service {
       () => ctx.webServer.register({ kind: 'prefix', path: '/plugins', handler: this.serveBundle }),
       'client-modules: bundle route',
     )
-    ctx.effect(
-      () => ctx.webServer.tapIndex(html => injectBootManifest(html, this.composed)),
-      'client-modules: boot manifest injection',
-    )
+    ctx.on('webserver/index-inject', (table) => {
+      table.push(...bootInjections(this.composed))
+    })
   }
 
   /**
diff --git a/packages/client/modules/tests/node-half.client.spec.ts b/packages/client/modules/tests/node-half.client.spec.ts
index 0dc6ea0e3c..8577d2a57d 100644
--- a/packages/client/modules/tests/node-half.client.spec.ts
+++ b/packages/client/modules/tests/node-half.client.spec.ts
@@ -8,9 +8,9 @@ import { pathToFileURL } from 'node:url'
 import { runInNewContext } from 'node:vm'
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { WebServer, WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { renderIndexInjections, type WebServer, type WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import * as modulesClient from '../src/client/index.ts'
-import { ClientModuleRegistry, injectBootManifest, orderByModuleGraph } from '../src/index.ts'
+import { ClientModuleRegistry, bootInjections, orderByModuleGraph } from '../src/index.ts'
 import type { ClientModuleLoaderTarget, WebBootEntry, WebBootGraph } from '../src/client/index.ts'
 
 const MODULES_ID = '@deepseek-ai/dsh-client-modules'
@@ -81,9 +81,12 @@ function construct(packageNames: string[]): ClientModuleRegistry {
   return constructWithRoute(packageNames).service
 }
 
-/** Execute the exact first inline script emitted by the Host HTML transform. */
+/** Execute the exact first inline script emitted by the Host boot rows. */
 function injectedFacade(graph: WebBootGraph): { html: string; target: ClientModuleLoaderTarget } {
-  const html = injectBootManifest('<html><head></head><body><script type="module" src="/index.js"></script></body></html>', graph)
+  const html = renderIndexInjections(
+    '<html><head></head><body><script type="module" src="/index.js"></script></body></html>',
+    bootInjections(graph),
+  )
   const source = /<head><script>([\s\S]*?)<\/script>/.exec(html)?.[1]
   if (source === undefined) throw new Error('missing injected ModuleLoader facade script')
   const window: { __ModuleLoader__?: ClientModuleLoaderTarget } = {}
@@ -107,7 +110,7 @@ describe('HTML bootstrap facade', () => {
     const facadeAt = html.indexOf('window.__ModuleLoader__=')
     const modulesAt = html.indexOf('<script src="/plugins/modules.js?rev=m"></script>')
     const runtimeAt = html.indexOf('<script src="/plugins/runtime.js?rev=r"></script>')
-    const graphAt = html.indexOf('window.__DSH_BOOT__ = ')
+    const graphAt = html.indexOf('globalThis["__DSH_BOOT__"] = ')
     const entryAt = html.indexOf('<script type="module" src="/index.js"></script>')
     expect([facadeAt, modulesAt, runtimeAt, graphAt, entryAt]).toEqual([...new Set([
       facadeAt, modulesAt, runtimeAt, graphAt, entryAt,
diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json
index eb7d3f176c..dd969c69f2 100644
--- a/packages/client/ui-theme/package.json
+++ b/packages/client/ui-theme/package.json
@@ -57,6 +57,7 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
@@ -65,10 +66,9 @@
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@types/react": "~18.3.1",
-    "react": "^18.2.0",
     "@deepseek-ai/dsh-settings": "workspace:^",
-    "@deepseek-ai/dsh-client-connection": "workspace:^"
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-theme/src/boot-theme.ts b/packages/client/ui-theme/src/boot-theme.ts
index 89b81b9de1..e6430cc6b9 100644
--- a/packages/client/ui-theme/src/boot-theme.ts
+++ b/packages/client/ui-theme/src/boot-theme.ts
@@ -1,15 +1,16 @@
 /**
- * Host-rendered theme bootstrap for the browser's pre-plugin interval. Each
- * index response embeds the current durable built-in preference; the browser
- * resolves only `system`, then writes the same DOM fields ui-layout's
- * ThemePresenter owns after the client plugin tree activates.
+ * Theme bootstrap row for the browser's pre-plugin interval. Each index
+ * render embeds the current durable built-in preference; the browser resolves
+ * only `system`, then writes the same DOM fields ui-layout's ThemePresenter
+ * owns after the client plugin tree activates.
  */
 
+import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver'
 import { DEFAULT_PREFERENCE, type ThemePreference } from './theme-settings.ts'
 
-/** Build the inline script for one schema-validated built-in preference. */
+/** Build the inline script body for one schema-validated built-in preference. */
 function bootThemeScript(preference: ThemePreference): string {
-  return `<script>(() => {
+  return `(() => {
   const preference = ${JSON.stringify(preference)}
   const systemDark = preference === 'system'
     && typeof matchMedia !== 'undefined'
@@ -17,24 +18,17 @@ function bootThemeScript(preference: ThemePreference): string {
   const dark = preference === 'dark' || systemDark
   document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
   document.body.toggleAttribute('data-ds-dark-theme', dark)
-})()</script>`
+})()`
 }
 
 /**
- * Insert the theme bootstrap immediately after the opening body tag, before
- * the shell mount and module script. Body-less fragments receive it at the
- * end, where the HTML parser has already synthesized a body.
- * @param html - Raw application index HTML.
+ * The theme bootstrap as an injection row: an inline script immediately after
+ * the opening body tag, before the shell mount and module script.
  * @param preference - Current Host-backed built-in preference.
- * @returns HTML containing the theme bootstrap.
+ * @returns the body script row.
  */
-export function injectBootTheme(
-  html: string,
+export function bootThemeInjection(
   preference: ThemePreference = DEFAULT_PREFERENCE,
-): string {
-  const script = bootThemeScript(preference)
-  const body = /<body(?:\s[^>]*)?>/i.exec(html)
-  if (body === null) return `${html}${script}`
-  const at = body.index + body[0].length
-  return `${html.slice(0, at)}${script}${html.slice(at)}`
+): IndexInjection {
+  return { kind: 'script', placement: 'body', text: bootThemeScript(preference) }
 }
diff --git a/packages/client/ui-theme/src/index.ts b/packages/client/ui-theme/src/index.ts
index c56c030e17..cc119d1825 100644
--- a/packages/client/ui-theme/src/index.ts
+++ b/packages/client/ui-theme/src/index.ts
@@ -3,7 +3,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
-import { injectBootTheme } from './boot-theme.ts'
+import { bootThemeInjection } from './boot-theme.ts'
 import {
   DEFAULT_PREFERENCE, THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema,
   type ThemePreference, type ThemeSettings,
@@ -26,18 +26,16 @@ function readPreference(ctx: Context): ThemePreference {
 }
 
 /**
- * Register the durable theme section and initial-theme index transform when
- * their optional Host services are composed.
- * @param ctx - Host context that may acquire settings and HTTP services.
+ * Register the durable theme section when the optional settings service is
+ * composed, and answer every index injection collection with the current
+ * theme bootstrap row.
+ * @param ctx - Host context that may acquire the settings service.
  */
 export function apply(ctx: Context): void {
   ctx.inject(['settings'], (settingsCtx) => {
     settingsCtx.settings.register(THEME_NAMESPACE, ThemeSettingsSchema)
   })
-  ctx.inject(['webServer'], (httpCtx) => {
-    httpCtx.effect(
-      () => httpCtx.webServer.tapIndex(html => injectBootTheme(html, readPreference(ctx))),
-      'client-ui-theme: initial theme bootstrap',
-    )
+  ctx.on('webserver/index-inject', (table) => {
+    table.push(bootThemeInjection(readPreference(ctx)))
   })
 }
diff --git a/packages/client/ui-theme/tests/boot-theme.client.spec.ts b/packages/client/ui-theme/tests/boot-theme.client.spec.ts
index a8d0dff235..ab737059c1 100644
--- a/packages/client/ui-theme/tests/boot-theme.client.spec.ts
+++ b/packages/client/ui-theme/tests/boot-theme.client.spec.ts
@@ -1,8 +1,8 @@
 // @vitest-environment jsdom
-/** Host index injection and the resulting pre-plugin browser theme. */
+/** The theme bootstrap injection row and the resulting pre-plugin browser theme. */
 import { runInNewContext } from 'node:vm'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { injectBootTheme } from '../src/boot-theme.ts'
+import { bootThemeInjection } from '../src/boot-theme.ts'
 import type { ThemePreference } from '../src/theme-settings.ts'
 
 const DARK_ATTRIBUTE = 'data-ds-dark-theme'
@@ -11,15 +11,10 @@ function mockSystemDark(matches: boolean): void {
   vi.stubGlobal('matchMedia', vi.fn(() => ({ matches }) as MediaQueryList))
 }
 
-function executeBootstrap(
-  preference?: ThemePreference,
-  html = '<html><body><div id="root"></div><script type="module"></script></body></html>',
-): string {
-  const injected = injectBootTheme(html, preference)
-  const source = /<script>([\s\S]*?)<\/script>/.exec(injected)?.[1]
-  if (source === undefined) throw new Error('theme bootstrap script missing')
-  runInNewContext(source, { document, matchMedia: globalThis.matchMedia })
-  return injected
+function executeBootstrap(preference?: ThemePreference): void {
+  const row = bootThemeInjection(preference)
+  if (row.kind !== 'script') throw new Error('theme bootstrap row is not a script')
+  runInNewContext(row.text, { document, matchMedia: globalThis.matchMedia })
 }
 
 afterEach(() => {
@@ -29,12 +24,12 @@ afterEach(() => {
   document.body.removeAttribute(DARK_ATTRIBUTE)
 })
 
-describe('theme boot index transform', () => {
-  it('runs immediately inside the body before the shell mount', () => {
+describe('theme bootstrap row', () => {
+  it('is a body script row, so it runs before the shell mount', () => {
     mockSystemDark(false)
-    const html = executeBootstrap('dark', '<html><body class="app"><div id="root"></div></body></html>')
-    expect(html.indexOf('<script>')).toBeGreaterThan(html.indexOf('<body class="app">'))
-    expect(html.indexOf('<script>')).toBeLessThan(html.indexOf('<div id="root">'))
+    const row = bootThemeInjection('dark')
+    expect(row).toMatchObject({ kind: 'script', placement: 'body' })
+    executeBootstrap('dark')
     expect(document.documentElement.style.colorScheme).toBe('dark')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(true)
   })
@@ -63,9 +58,4 @@ describe('theme boot index transform', () => {
     expect(document.documentElement.style.colorScheme).toBe('light')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
   })
-
-  it('appends the script to a body-less fragment', () => {
-    const html = injectBootTheme('<main>loading</main>', 'dark')
-    expect(html.startsWith('<main>loading</main><script>')).toBe(true)
-  })
 })
diff --git a/packages/client/ui-theme/tests/host.client.spec.ts b/packages/client/ui-theme/tests/host.client.spec.ts
index 944988fe11..18f6ed42b8 100644
--- a/packages/client/ui-theme/tests/host.client.spec.ts
+++ b/packages/client/ui-theme/tests/host.client.spec.ts
@@ -1,6 +1,6 @@
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it } from 'vitest'
-import type { WebServer } from '@deepseek-ai/dsh-host-webserver'
+import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver'
 import { SettingsProvider, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import {
   DEFAULT_PREFERENCE, THEME_SETTINGS_NAMESPACE, apply,
@@ -14,6 +14,19 @@ class MemorySettings extends SettingsProvider {
   }
 }
 
+/** Collect the injection table the way an index render or boot payload does. */
+function collect(ctx: Context): IndexInjection[] {
+  const table: IndexInjection[] = []
+  ctx.emit('webserver/index-inject', table)
+  return table
+}
+
+/** Narrow the theme row and return its script body. */
+function scriptText(row: IndexInjection | undefined): string {
+  if (row?.kind !== 'script') throw new Error('expected a script row')
+  return row.text
+}
+
 describe('ui-theme host', () => {
   it('registers, validates, and disposes the durable theme namespace with its fiber', async () => {
     const ctx = new Context()
@@ -29,37 +42,24 @@ describe('ui-theme host', () => {
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
   })
 
-  it('renders the current durable preference and disposes the index transform', async () => {
+  it('answers each collection with the current durable preference until disposal', async () => {
     const ctx = new Context()
     await ctx.plugin(MemorySettings).await()
-    let transform: ((html: string) => string) | undefined
-    let disposed = false
-    ctx.provide('webServer', {
-      tapIndex: (next: (html: string) => string) => {
-        transform = next
-        return () => { disposed = true }
-      },
-    } as WebServer)
     const fiber = ctx.plugin({ apply })
     await fiber.await()
-    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+    const rows = collect(ctx)
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ kind: 'script', placement: 'body' })
+    expect(scriptText(rows[0])).toContain('const preference = "system"')
     await ctx.settings.update(settingsNamespace(THEME_SETTINGS_NAMESPACE), { preference: 'dark' })
-    expect(transform?.('<body></body>')).toContain('const preference = "dark"')
+    expect(scriptText(collect(ctx)[0])).toContain('const preference = "dark"')
     await fiber.dispose()
-    expect(disposed).toBe(true)
-    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+    expect(collect(ctx)).toEqual([])
   })
 
-  it('uses the system preference when only an HTTP server exists', async () => {
+  it('uses the system preference without a settings provider', async () => {
     const ctx = new Context()
-    let transform: ((html: string) => string) | undefined
-    ctx.provide('webServer', {
-      tapIndex: (next: (html: string) => string) => {
-        transform = next
-        return () => undefined
-      },
-    } as WebServer)
     await ctx.plugin({ apply }).await()
-    expect(transform?.('<body></body>')).toContain('const preference = "system"')
+    expect(scriptText(collect(ctx)[0])).toContain('const preference = "system"')
   })
 })
diff --git a/packages/client/web/src/boot.ts b/packages/client/web/src/boot.ts
index fc6299c3c6..5495a86379 100644
--- a/packages/client/web/src/boot.ts
+++ b/packages/client/web/src/boot.ts
@@ -50,9 +50,15 @@ export class AppWebEntry {
       if (moduleLoader === undefined) {
         throw new Error('web boot: window.__ModuleLoader__ bootstrap facade is missing')
       }
+      // A pre-injected transport (the worker preview page) owns bundle bytes;
+      // its loadBundle is the default and explicit seams still win.
+      const transport = (globalThis as {
+        __DSH_TRANSPORT__?: { loadBundle?: ClientModuleCreateOptions['loadBundle'] }
+      }).__DSH_TRANSPORT__
       this.modules = moduleLoader.create({
         boot: win.__DSH_BOOT__,
         staticModules: getStaticModules(),
+        ...transport?.loadBundle === undefined ? {} : { loadBundle: transport.loadBundle },
         ...this.seams,
       })
       this.manifest = this.modules.manifest
@@ -86,6 +92,9 @@ export class AppWebEntry {
 
   /** Prefetch stage-one bundles; their import path owns any eventual failure. */
   private async prefetchImmediateTier(): Promise<void> {
+    // A pre-injected transport owns bundle bytes; HTTP prefetch against the
+    // static deployment answers nothing.
+    if ((globalThis as { __DSH_TRANSPORT__?: unknown }).__DSH_TRANSPORT__ !== undefined) return
     await Promise.all(this.manifest.plugins
       .filter(row => row.immediately)
       .map(row => this.modules.prefetch(row.id).catch((_prefetchError: unknown) => {
diff --git a/packages/extensions/cordis-host-runner/src/sandbox.ts b/packages/extensions/cordis-host-runner/src/sandbox.ts
index 83324b1ec7..f359801af1 100644
--- a/packages/extensions/cordis-host-runner/src/sandbox.ts
+++ b/packages/extensions/cordis-host-runner/src/sandbox.ts
@@ -196,23 +196,46 @@ export function parseErrorMessage(half: 'code.host' | 'code.client', context: st
 /**
  * Parse one half's source without running it: the define-time precheck that
  * keeps unparseable code out of the registry, so a model fixes it and defines
- * again instead of discovering the failure at run time. Compiling through `vm`
- * rather than `new Function` is what makes the two agree — same wrapper, same
- * compiler, and the same source-line-and-caret prelude in the failure.
+ * again instead of discovering the failure at run time. `new Function` is the
+ * gate — hosts without a real `node:vm` (the browser worker) still refuse
+ * unparseable code — and `vm.Script` is only the best-effort prettifier: on a
+ * Node host its failure carries the source-line-and-caret prelude the
+ * teaching text builds on, and where the vm is a stub the message stays bare.
  * @param code - the model-written function body.
  * @param half - which define argument carried it, for the error text.
  * @throws when the body does not parse, with the offending line and a teaching hint.
  */
 export function precheckCode(code: string, half: 'code.host' | 'code.client'): void {
+  const wrapped = `(async () => {\n${code}\n})()`
   try {
-    // Compile-only: constructing the Script parses the source and runs nothing.
-    new Script(`(async () => {\n${code}\n})()`, { filename: `cordis-dyn-${half}.js` })
+    // Compile-only: constructing the function parses the source and runs nothing.
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval -- parse gate over model-written code; nothing is invoked
+    new Function(wrapped)
   } catch (error) {
     if (!isSyntaxError(error)) throw error
-    throw new Error(parseErrorMessage(half, syntaxErrorContext(error)))
+    throw new Error(parseErrorMessage(half, prettyParseContext(wrapped, half, error)))
   }
 }
 
+/**
+ * Best-effort vm recompile of a body `new Function` already refused, for the
+ * source-line-and-caret prelude only.
+ * @param wrapped - the wrapped source that failed to parse.
+ * @param half - which define argument carried it, for the vm filename.
+ * @param refusal - the gate's own `SyntaxError`, the fallback context source.
+ * @returns the vm prelude when a real vm produced one, else the bare refusal.
+ */
+function prettyParseContext(wrapped: string, half: 'code.host' | 'code.client', refusal: Error): string {
+  try {
+    new Script(wrapped, { filename: `cordis-dyn-${half}.js` })
+  } catch (vmError) {
+    if (isSyntaxError(vmError)) return syntaxErrorContext(vmError)
+    // A stubbed vm (the browser worker) refuses Script itself; the gate's
+    // error is the only context there is.
+  }
+  return String(refusal)
+}
+
 /**
  * Evaluate a host half as the body of an async function inside the sandbox. `vmTimeoutMs` only
  * bounds the SYNCHRONOUS portion; an async body escapes it — acceptable under the module's
diff --git a/packages/host/frontend-static/src/index.ts b/packages/host/frontend-static/src/index.ts
index 7d0f409f03..ad516f1c79 100644
--- a/packages/host/frontend-static/src/index.ts
+++ b/packages/host/frontend-static/src/index.ts
@@ -4,8 +4,8 @@
  * Web shell locked at step1 — traversal outside the dist root is 403, any
  * miss falls back to index.html with HTTP 200 (SPA routing), unknown
  * extensions ship as octet-stream, non-GET/HEAD is 405. Every index response
- * runs through the webserver's registered index taps (boot-manifest
- * injection). The dist location is workspace knowledge of the composing
+ * runs through the webserver's index render (structured injection rows, then
+ * raw taps). The dist location is workspace knowledge of the composing
  * application, so `distIndex` is typically supplied through a `!!js`
  * expression, never hardcoded by a deployment.
  * @module @deepseek-ai/dsh-host-frontend-static
@@ -50,7 +50,7 @@ const MIME: Record<string, string> = {
  * @param res - the node:http response to write.
  * @param distRoot - absolute dist root directory (resolved by the caller).
  * @param distIndex - absolute path of index.html inside distRoot.
- * @param renderIndex - produces the index.html body (index-tap injection) for
+ * @param renderIndex - produces the index.html body (injection rendering) for
  * `/` and every SPA fallback.
  */
 export async function serveStatic(
@@ -94,7 +94,7 @@ export function apply(ctx: Context, config: Config): void {
   const distIndex = config.distIndex
   const distRoot = dirname(distIndex)
   const renderIndex = async (): Promise<string> =>
-    ctx.webServer.applyIndexTaps(await readFile(distIndex, 'utf8'))
+    ctx.webServer.renderIndex(await readFile(distIndex, 'utf8'))
   ctx.effect(() => ctx.webServer.registerFallback(async (req, res) => {
     // Non-GET/HEAD without a matching named route is 405 (fallback-only
     // semantics: named routes own their method handling).
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index a6c335b8d5..94aba72382 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -1,8 +1,8 @@
 /**
  * @deepseek-ai/dsh-host-webserver — Web route-registration plugin: a node:http
- * server plus the `webServer` service (HTTP and upgrade route registries,
- * index transform taps, and the single fallback seat for everything no route
- * claims). Knows no harness concepts and serves no files; the composing
+ * server plus the `webServer` service (HTTP and upgrade route registries, the
+ * structured index injection table with raw transform taps behind it, and the
+ * single fallback seat for everything no route claims). Knows no harness concepts and serves no files; the composing
  * application's frontend plugin owns dist serving through the fallback hook.
  * Web shape only — Electron loads dist over file:// and carries fetch over an
  * IPC bridge. This package never prints: the URL line belongs to the shell.
@@ -14,11 +14,25 @@ import type { AddressInfo } from 'node:net'
 import type { Duplex } from 'node:stream'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
+import { renderIndexInjections, type IndexInjection } from './injections.ts'
+
+export { renderIndexInjections } from './injections.ts'
+export type { IndexInjection, IndexInjectionPlacement } from './injections.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
     webServer: WebServer
   }
+  interface Events {
+    /**
+     * Collect the structured index injection table. Emitted on every index
+     * render and every worker boot-payload request; listeners push their
+     * current rows, so a row's data is read fresh at emit time.
+     * @param table - Mutable row table; listeners append in activation order.
+     * @mode emit
+     */
+    'webserver/index-inject'(table: IndexInjection[]): void
+  }
 }
 
 /** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
@@ -261,6 +275,28 @@ export class WebServer extends Service {
     for (const transform of this.indexTaps) out = transform(out)
     return out
   }
+
+  /**
+   * Gather the structured injection table: one `webserver/index-inject` emit,
+   * every subscriber pushes its current rows. Fresh per call, so subscribers
+   * read live state (module graph, theme preference) at emit time.
+   * @returns rows in subscriber activation order.
+   */
+  collectIndexInjections(): IndexInjection[] {
+    const table: IndexInjection[] = []
+    this.ctx.emit('webserver/index-inject', table)
+    return table
+  }
+
+  /**
+   * Render one index.html body: the structured injection table first, then
+   * the raw `tapIndex` transforms over the result.
+   * @param html - the raw index.html body.
+   * @returns the transformed body.
+   */
+  renderIndex(html: string): string {
+    return this.applyIndexTaps(renderIndexInjections(html, this.collectIndexInjections()))
+  }
 }
 
 export default WebServer
diff --git a/packages/host/webserver/src/injections.ts b/packages/host/webserver/src/injections.ts
new file mode 100644
index 0000000000..cb1e5336a5
--- /dev/null
+++ b/packages/host/webserver/src/injections.ts
@@ -0,0 +1,104 @@
+/**
+ * Structured index injections: the typed rows plugins contribute to the boot
+ * HTML instead of raw `tapIndex` string transforms. Rows are pure
+ * JSON-serializable data because one table feeds two renderers: the served
+ * form renders rows into the index.html text ({@link renderIndexInjections}),
+ * and a static worker deployment ships the same rows over its boot payload
+ * for a page-side interpreter. Anything not expressible as a row stays on
+ * `tapIndex`, which runs after row rendering.
+ */
+
+/** Document region a rendered row lands in: after the opening head or body tag. */
+export type IndexInjectionPlacement = 'head' | 'body'
+
+/** One structured index injection row. */
+export type IndexInjection =
+  /** Assign a JSON-serializable value to a `globalThis` property, ahead of later script rows. */
+  | { kind: 'global'; name: string; value: unknown }
+  /** Inline classic script. `text` must not contain `</script`, which would close the element early. */
+  | { kind: 'script'; placement: IndexInjectionPlacement; text: string }
+  /**
+   * External classic script, executed in table order: a parser-blocking tag
+   * when served, an awaited fetch-and-execute in the worker form (whose
+   * loader resolves worker-only URLs such as `/plugins/...`).
+   */
+  | { kind: 'script-src'; placement: IndexInjectionPlacement; src: string }
+  /** A `<style>` element in the head. */
+  | { kind: 'style'; text: string }
+  /** Raw markup fragment. */
+  | { kind: 'html'; placement: IndexInjectionPlacement; html: string }
+
+/** Escape a row value before placing it in a quoted HTML attribute. */
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}
+
+function assertNever(row: never): never {
+  throw new Error(`webserver: unknown index injection row ${JSON.stringify(row)}`)
+}
+
+/** Render one row to markup with its placement. */
+function renderRow(row: IndexInjection): { placement: IndexInjectionPlacement; markup: string } {
+  switch (row.kind) {
+    case 'global': {
+      // `<` is escaped in JSON so a row-controlled string cannot break out of
+      // the script element.
+      const name = JSON.stringify(row.name).replaceAll('<', '\\u003c')
+      const value = row.value === undefined
+        ? 'undefined'
+        : JSON.stringify(row.value).replaceAll('<', '\\u003c')
+      return { placement: 'head', markup: `<script>globalThis[${name}] = ${value}</script>` }
+    }
+    case 'script':
+      return { placement: row.placement, markup: `<script>${row.text}</script>` }
+    case 'script-src':
+      return { placement: row.placement, markup: `<script src="${escapeHtmlAttribute(row.src)}"></script>` }
+    case 'style':
+      return { placement: 'head', markup: `<style>${row.text}</style>` }
+    case 'html':
+      return { placement: row.placement, markup: row.html }
+    default:
+      return assertNever(row)
+  }
+}
+
+/** Insert `markup` into `html` at `at`. */
+function splice(html: string, at: number, markup: string): string {
+  return `${html.slice(0, at)}${markup}${html.slice(at)}`
+}
+
+/**
+ * Render rows into an index.html body: head rows immediately after the
+ * opening head tag, body rows immediately after the opening body tag, each
+ * group in table order.
+ * @param html - the raw index.html body.
+ * @param rows - the collected injection table.
+ * @returns the html with every row rendered.
+ */
+export function renderIndexInjections(html: string, rows: readonly IndexInjection[]): string {
+  let head = ''
+  let body = ''
+  for (const row of rows) {
+    const rendered = renderRow(row)
+    if (rendered.placement === 'head') head += rendered.markup
+    else body += rendered.markup
+  }
+  let out = html
+  if (head !== '') {
+    const open = /<head(?:\s[^>]*)?>/i.exec(out)
+    // Headless fixture pages may lack <head>; prepending keeps the rows ahead
+    // of every document script.
+    out = open === null ? `${head}${out}` : splice(out, open.index + open[0].length, head)
+  }
+  if (body !== '') {
+    const open = /<body(?:\s[^>]*)?>/i.exec(out)
+    // Body-less fragments receive the rows at the end, where the HTML parser
+    // has already synthesized a body.
+    out = open === null ? `${out}${body}` : splice(out, open.index + open[0].length, body)
+  }
+  return out
+}
diff --git a/packages/host/webserver/tests/webserver.spec.ts b/packages/host/webserver/tests/webserver.spec.ts
index 2cbd285856..ffe5b4648d 100644
--- a/packages/host/webserver/tests/webserver.spec.ts
+++ b/packages/host/webserver/tests/webserver.spec.ts
@@ -15,7 +15,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Include from '@deepseek-ai/cordis-plugin-include'
-import HttpServer from '../src/index.ts'
+import HttpServer, { renderIndexInjections } from '../src/index.ts'
 
 let root: string | undefined
 let context: Context | undefined
@@ -200,6 +200,54 @@ describe('real Loader composition', () => {
     await expect(request(port, '/probe')).rejects.toThrow()
   })
 
+  it('collects injection rows fresh per render and layers taps over the rendered rows', { timeout: 60_000 }, async () => {
+    const loaded = await loadComposition()
+    const server = loaded.webServer
+    let flag = 'dark'
+    loaded.on('webserver/index-inject', (table) => {
+      table.push(
+        { kind: 'script', placement: 'head', text: 'window.__Q__=1' },
+        { kind: 'script-src', placement: 'head', src: '/plugins/a.js?rev="1"&x=<y>' },
+        { kind: 'global', name: '__DSH_BOOT__', value: { rev: '</script><b>' } },
+        { kind: 'style', text: 'body{margin:0}' },
+        { kind: 'html', placement: 'head', html: '<meta name="probe">' },
+        { kind: 'script', placement: 'body', text: `window.__P__=${JSON.stringify(flag)}` },
+      )
+    })
+
+    const html = server.renderIndex('<html><head></head><body>shell</body></html>')
+    // Head rows land right after the opening head tag in table order; the body
+    // row lands right after the opening body tag.
+    const order = [
+      '<head>',
+      '<script>window.__Q__=1</script>',
+      '<script src="/plugins/a.js?rev=&quot;1&quot;&amp;x=&lt;y&gt;"></script>',
+      'globalThis["__DSH_BOOT__"] = {"rev":"\\u003c/script>\\u003cb>"}',
+      '<style>body{margin:0}</style>',
+      '<meta name="probe">',
+      '<body>',
+      '<script>window.__P__="dark"</script>',
+      'shell',
+    ].map(part => html.indexOf(part))
+    expect(order).toEqual([...order].sort((a, b) => a - b))
+    expect(order.every(at => at !== -1)).toBe(true)
+
+    // Fresh collection per render: the listener reads live state at emit time.
+    flag = 'light'
+    expect(server.renderIndex('<head></head><body></body>')).toContain('window.__P__="light"')
+
+    // Raw taps still run, over the already-rendered rows.
+    const untap = server.tapIndex(h => h.replace('window.__Q__=1', 'window.__Q__=2'))
+    expect(server.renderIndex('<head></head><body></body>')).toContain('window.__Q__=2')
+    untap()
+
+    // Tag-less fragments: head rows prepend, body rows append.
+    expect(renderIndexInjections('<main>x</main>', [
+      { kind: 'script', placement: 'head', text: 'H' },
+      { kind: 'script', placement: 'body', text: 'B' },
+    ])).toBe('<script>H</script><main>x</main><script>B</script>')
+  })
+
   it('fails the fiber when the port is already taken (fail-loud at activation)', { timeout: 60_000 }, async () => {
     const first = await loadComposition()
     const takenPort = first.webServer.port

From d4fd03ae539b3bfb12a811efce457fc00cb15282 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 12:16:00 +0800
Subject: [PATCH 12/34] chore(docs): classify IndexInjection and regenerate the
 catalog surfaces

---
 docs/config-catalog.i18n.yaml                 |  4 +-
 docs/config-catalog.md                        |  2 +-
 docs/config-catalog.zh.md                     |  2 +-
 docs/event-producer-consumer.i18n.yaml        |  4 +-
 docs/event-producer-consumer.md               |  1 +
 docs/event-producer-consumer.zh.md            |  1 +
 docs/subsystems/client-modules.i18n.yaml      |  4 +-
 docs/subsystems/client-modules.md             |  4 +-
 docs/subsystems/client-modules.zh.md          |  4 +-
 docs/subsystems/web-server.i18n.yaml          |  4 +-
 docs/subsystems/web-server.md                 | 41 ++++++++++++++++++-
 docs/subsystems/web-server.zh.md              | 41 ++++++++++++++++++-
 .../extensions/tool-cordis/src/api-catalog.ts | 32 ++++++++++++++-
 scripts/gen-cordis-catalog.ts                 |  2 +
 14 files changed, 128 insertions(+), 18 deletions(-)

diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 6cdc1e42ee..e3de095ad5 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 5a265c583382b846507f7aae6f59be4341d0a823
-config-catalog.zh.md: d410d383bf7cbe576227edf792f92bb019ad043a
+config-catalog.md: d25843091d453687bad5035c49bcb200cb03fff2
+config-catalog.zh.md: 1cc3002799afc10ca84f74044c7b28f91490ffa3
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 5a265c5833..d25843091d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -863,7 +863,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:59`](../packages/host/webserver/src/index.ts)
 
 <a id="deepseek-aidsh-invariants"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index d410d383bf..1cc3002799 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -865,7 +865,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
+来源：[`packages/host/webserver/src/index.ts:59`](../packages/host/webserver/src/index.ts)
 
 <a id="deepseek-aidsh-invariants"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 5fdbf36ed6..77c2dd6536 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: d75d64b58b041c117bf2eaa1612c1b4683378a00
-event-producer-consumer.zh.md: adfc11782e179077b17199fc4ea6e8f52b3c465b
+event-producer-consumer.md: d3901b1ddc7d99d4960324ab7459388fa4612bbe
+event-producer-consumer.zh.md: 346a293a226719f781a9587eb0adefcf3f6bed08
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index d75d64b58b..d3901b1ddc 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -57,6 +57,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
 | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:152`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
 | `tools/result` | `emit` | [`packages/core/tools/src/index.ts:197`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
+| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | - |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index adfc11782e..346a293a22 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -59,6 +59,7 @@
 | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
 | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:152`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
 | `tools/result` | `emit` | [`packages/core/tools/src/index.ts:197`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
+| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | - |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 130e99d258..4c8f701de2 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 52fa4ef73766e8e7e7601e604f78aded9940328f
-client-modules.zh.md: e830349be77000759684a76b2834478a803e3e11
+client-modules.md: 81c85e2f0eb1d7248459f6ca092ed89f602e8415
+client-modules.zh.md: 37b8acc0d6d335802333100b5e55e709153911da
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 52fa4ef737..81c85e2f0e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -82,7 +82,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.clientModules` — `ClientModuleRegistry`
 
-The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
 
 ```ts cordis-catalog
 /**
@@ -122,5 +122,5 @@ onRebuilt(listener: (id: string, rev: string) => void): () => void
 onGraphChanged(listener: () => void): () => void
 ```
 
-Source: [`packages/client/modules/src/index.ts:295`](../../packages/client/modules/src/index.ts)
+Source: [`packages/client/modules/src/index.ts:282`](../../packages/client/modules/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index e830349be7..37b8acc0d6 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -82,7 +82,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.clientModules` — `ClientModuleRegistry`
 
-The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
 
 ```ts cordis-catalog
 /**
@@ -122,5 +122,5 @@ onRebuilt(listener: (id: string, rev: string) => void): () => void
 onGraphChanged(listener: () => void): () => void
 ```
 
-Source: [`packages/client/modules/src/index.ts:295`](../../packages/client/modules/src/index.ts)
+Source: [`packages/client/modules/src/index.ts:282`](../../packages/client/modules/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web-server.i18n.yaml b/docs/subsystems/web-server.i18n.yaml
index 8ed53c1fa7..519c6e7043 100644
--- a/docs/subsystems/web-server.i18n.yaml
+++ b/docs/subsystems/web-server.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 docs/subsystems/web-server.md
-web-server.md: 414863d88cdc34163882cdc3dfe8dc7c1471ac77
-web-server.zh.md: d756192ce733a3fe79c9eaf44e5d556c4bac90a8
+web-server.md: 7dd700d24f63d31f34d8711069477414292e3bf6
+web-server.zh.md: ca67ff231e9aad9144fa5203ee46435f636a93da
diff --git a/docs/subsystems/web-server.md b/docs/subsystems/web-server.md
index 414863d88c..7dd700d24f 100644
--- a/docs/subsystems/web-server.md
+++ b/docs/subsystems/web-server.md
@@ -102,7 +102,46 @@ tapIndex(transform: (html: string) => string): () => void
  * @returns the transformed body.
  */
 applyIndexTaps(html: string): string
+
+/**
+ * Gather the structured injection table: one `webserver/index-inject` emit,
+ * every subscriber pushes its current rows. Fresh per call, so subscribers
+ * read live state (module graph, theme preference) at emit time.
+ * @returns rows in subscriber activation order.
+ */
+collectIndexInjections(): IndexInjection[]
+
+/**
+ * Render one index.html body: the structured injection table first, then
+ * the raw `tapIndex` transforms over the result.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+renderIndex(html: string): string
 ```
 
-Source: [`packages/host/webserver/src/index.ts:59`](../../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:73`](../../packages/host/webserver/src/index.ts)
+
+<a id="webserver-events"></a>
+
+### `webserver/*` events
+
+<a id="webserverindex-inject--emit"></a>
+
+#### `webserver/index-inject` — emit
+
+Collect the structured index injection table. Emitted on every index render and every worker boot-payload request; listeners push their current rows, so a row's data is read fresh at emit time.
+
+```ts cordis-catalog
+/**
+ * Collect the structured index injection table. Emitted on every index
+ * render and every worker boot-payload request; listeners push their
+ * current rows, so a row's data is read fresh at emit time.
+ * @param table - Mutable row table; listeners append in activation order.
+ * @mode emit
+ */
+'webserver/index-inject'(table: IndexInjection[]): void
+```
+
+Source: [`packages/host/webserver/src/index.ts:34`](../../packages/host/webserver/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web-server.zh.md b/docs/subsystems/web-server.zh.md
index d756192ce7..ca67ff231e 100644
--- a/docs/subsystems/web-server.zh.md
+++ b/docs/subsystems/web-server.zh.md
@@ -102,7 +102,46 @@ tapIndex(transform: (html: string) => string): () => void
  * @returns the transformed body.
  */
 applyIndexTaps(html: string): string
+
+/**
+ * Gather the structured injection table: one `webserver/index-inject` emit,
+ * every subscriber pushes its current rows. Fresh per call, so subscribers
+ * read live state (module graph, theme preference) at emit time.
+ * @returns rows in subscriber activation order.
+ */
+collectIndexInjections(): IndexInjection[]
+
+/**
+ * Render one index.html body: the structured injection table first, then
+ * the raw `tapIndex` transforms over the result.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+renderIndex(html: string): string
 ```
 
-Source: [`packages/host/webserver/src/index.ts:59`](../../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:73`](../../packages/host/webserver/src/index.ts)
+
+<a id="webserver-events"></a>
+
+### `webserver/*` events
+
+<a id="webserverindex-inject--emit"></a>
+
+#### `webserver/index-inject` — emit
+
+Collect the structured index injection table. Emitted on every index render and every worker boot-payload request; listeners push their current rows, so a row's data is read fresh at emit time.
+
+```ts cordis-catalog
+/**
+ * Collect the structured index injection table. Emitted on every index
+ * render and every worker boot-payload request; listeners push their
+ * current rows, so a row's data is read fresh at emit time.
+ * @param table - Mutable row table; listeners append in activation order.
+ * @mode emit
+ */
+'webserver/index-inject'(table: IndexInjection[]): void
+```
+
+Source: [`packages/host/webserver/src/index.ts:34`](../../packages/host/webserver/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 708c179df5..a20c0b9aff 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -459,8 +459,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'clientModules',
-    summary: 'The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap.',
-    description: 'The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).',
+    summary: 'The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows.',
+    description: 'The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).',
     methods: [
       {
         signature: 'graph(): WebBootGraph',
@@ -2217,6 +2217,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [{ name: 'html', description: 'the raw index.html body.' }],
         returns: 'the transformed body.',
       },
+      {
+        signature: 'collectIndexInjections(): IndexInjection[]',
+        description: 'Gather the structured injection table: one `webserver/index-inject` emit, every subscriber pushes its current rows. Fresh per call, so subscribers read live state (module graph, theme preference) at emit time.',
+        parameters: [],
+        returns: 'rows in subscriber activation order.',
+      },
+      {
+        signature: 'renderIndex(html: string): string',
+        description: 'Render one index.html body: the structured injection table first, then the raw `tapIndex` transforms over the result.',
+        parameters: [{ name: 'html', description: 'the raw index.html body.' }],
+        returns: 'the transformed body.',
+      },
     ],
   },
   {
@@ -2685,6 +2697,14 @@ export const EVENT_API: readonly EventApiEntry[] = [
     description: 'Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.',
     parameters: [{ name: 'exec', description: 'the execution object that traversed the pipeline.' }, { name: 'result', description: 'a deep-frozen snapshot of the final returned result.' }],
   },
+  {
+    name: 'webserver/index-inject',
+    mode: 'emit',
+    signature: '\'webserver/index-inject\'(table: IndexInjection[]): void',
+    summary: 'Collect the structured index injection table.',
+    description: 'Collect the structured index injection table. Emitted on every index render and every worker boot-payload request; listeners push their current rows, so a row\'s data is read fresh at emit time.',
+    parameters: [{ name: 'table', description: 'Mutable row table; listeners append in activation order.' }],
+  },
   {
     name: 'workflow/agent-end',
     mode: 'emit',
@@ -3297,6 +3317,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'InboxTarget',
     declaration: 'export type InboxTarget = \'next-turn\' | \'next-step\';',
   },
+  {
+    name: 'IndexInjection',
+    declaration: 'export type IndexInjection = {\n    kind: \'global\';\n    name: string;\n    value: unknown;\n} | {\n    kind: \'script\';\n    placement: IndexInjectionPlacement;\n    text: string;\n} | {\n    kind: \'script-src\';\n    placement: IndexInjectionPlacement;\n    src: string;\n} | {\n    kind: \'style\';\n    text: string;\n} | {\n    kind: \'html\';\n    placement: IndexInjectionPlacement;\n    html: string;\n};',
+  },
+  {
+    name: 'IndexInjectionPlacement',
+    declaration: 'export type IndexInjectionPlacement = \'head\' | \'body\';',
+  },
   {
     name: 'InvariantFailure',
     declaration: 'export type InvariantFailure = (message: string) => never;',
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index a088890413..4b1f71c5e9 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -184,6 +184,7 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'system-prompt': 'system-prompt.md',
   'session-telemetry': 'session-telemetry.md',
   'tools': 'tools.md',
+  'webserver': 'web-server.md',
   'workflow': 'workflow.md',
 }
 
@@ -480,6 +481,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PresetSpec: 'permission-presets.md',
   InvariantInstaller: 'invariants.md',
   WebRoute: 'web-server.md',
+  IndexInjection: 'web-server.md',
   StorageBackend: 'storage.md',
   StorageForms: 'storage.md',
   Domain: 'storage.md',

From 3ca4997cd27b9fc352746a3d7bfe3b2a4e4ca4fb Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 12:16:17 +0800
Subject: [PATCH 13/34] test: cover gateway rollback and theme fallback
 branches

---
 .../api/gateway/tests/gateway.client.spec.ts  | 70 +++++++++++++++++++
 .../client/ui-theme/tests/host.client.spec.ts |  9 +++
 2 files changed, 79 insertions(+)

diff --git a/packages/api/gateway/tests/gateway.client.spec.ts b/packages/api/gateway/tests/gateway.client.spec.ts
index 59add544ea..c6d4a03eb3 100644
--- a/packages/api/gateway/tests/gateway.client.spec.ts
+++ b/packages/api/gateway/tests/gateway.client.spec.ts
@@ -458,6 +458,76 @@ describe('Client Typert API', () => {
     await disposeContext()
   })
 
+  it('unwinds an already-installed namespace when a later namespace fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const { scope: _scope, ...probe } = directDescriptor()
+    const vault: InvocationDescriptor = {
+      ...probe,
+      id: '@fixture/vault#vault/seal',
+      service: 'vault',
+      namespace: 'vault',
+      method: 'seal',
+    }
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'seal') throw new Error('fixture later-namespace failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({ package: '@fixture/two-namespaces', descriptors: [probe, vault] }))
+        .rejects.toThrow('fixture later-namespace failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.remote as unknown as Record<string, unknown>).probe).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).vault).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+  })
+
+  it('rolls back an earlier scoped projection when a later descriptor fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const { scope: _scope, ...direct } = directDescriptor()
+    const failing: InvocationDescriptor = {
+      ...direct,
+      id: '@fixture/probe#probe/archive',
+      method: 'archive',
+    }
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'archive') throw new Error('fixture trailing failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({
+        package: '@fixture/scoped-then-failing',
+        descriptors: [contextDescriptor(), failing],
+      })).rejects.toThrow('fixture trailing failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.remote as unknown as Record<string, unknown>).probe).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+  })
+
+  it('keeps a namespace another contribution still populates when a group leaves', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const { scope: _scope, ...direct } = directDescriptor()
+    const disposeDirect = await ctx.remote.$mount({ package: '@fixture/direct-owner', descriptors: [direct] })
+    const disposeScoped = await ctx.remote.$mount({ package: '@fixture/scoped-owner', descriptors: [contextDescriptor()] })
+
+    await disposeDirect()
+    // The namespace survives its first group: the second contribution still owns methods on it.
+    const surviving = ctx.get('remote.probe') as unknown as Record<string, unknown> | undefined
+    expect(surviving).toBeDefined()
+    expect(surviving?.create).toBeUndefined()
+    await disposeScoped()
+    expect(ctx.get('remote.probe')).toBeUndefined()
+  })
+
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()
diff --git a/packages/client/ui-theme/tests/host.client.spec.ts b/packages/client/ui-theme/tests/host.client.spec.ts
index 18f6ed42b8..692158cba0 100644
--- a/packages/client/ui-theme/tests/host.client.spec.ts
+++ b/packages/client/ui-theme/tests/host.client.spec.ts
@@ -62,4 +62,13 @@ describe('ui-theme host', () => {
     await ctx.plugin({ apply }).await()
     expect(scriptText(collect(ctx)[0])).toContain('const preference = "system"')
   })
+
+  it('falls back to the schema default while the theme namespace holds no section', async () => {
+    // A settings provider whose namespace read comes back empty (registration
+    // still pending or a provider without schema defaults).
+    const ctx = new Context()
+    ctx.provide('settings', { register: () => () => {}, get: () => undefined } as never)
+    await ctx.plugin({ apply }).await()
+    expect(scriptText(collect(ctx)[0])).toContain('const preference = "system"')
+  })
 })

From 10f9f506e2268d5f5a441ad8450625890cc3d956 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 13:44:17 +0800
Subject: [PATCH 14/34] fix(web): stand down prefetch only when the transport
 owns bundle bytes

---
 packages/client/web/src/boot.ts | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/packages/client/web/src/boot.ts b/packages/client/web/src/boot.ts
index 5495a86379..9aee3b0b59 100644
--- a/packages/client/web/src/boot.ts
+++ b/packages/client/web/src/boot.ts
@@ -51,7 +51,10 @@ export class AppWebEntry {
         throw new Error('web boot: window.__ModuleLoader__ bootstrap facade is missing')
       }
       // A pre-injected transport (the worker preview page) owns bundle bytes;
-      // its loadBundle is the default and explicit seams still win.
+      // its loadBundle is the default and explicit seams still win. The global
+      // is `ClientTransportHooks`, owned by @deepseek-ai/dsh-client-connection;
+      // this structural slice reads one optional member without adding a
+      // package edge.
       const transport = (globalThis as {
         __DSH_TRANSPORT__?: { loadBundle?: ClientModuleCreateOptions['loadBundle'] }
       }).__DSH_TRANSPORT__
@@ -92,9 +95,13 @@ export class AppWebEntry {
 
   /** Prefetch stage-one bundles; their import path owns any eventual failure. */
   private async prefetchImmediateTier(): Promise<void> {
-    // A pre-injected transport owns bundle bytes; HTTP prefetch against the
-    // static deployment answers nothing.
-    if ((globalThis as { __DSH_TRANSPORT__?: unknown }).__DSH_TRANSPORT__ !== undefined) return
+    // A transport carrying loadBundle owns the bundle bytes; HTTP prefetch
+    // against its static deployment answers nothing. A transport without
+    // loadBundle leaves bundles on HTTP, prefetch included.
+    const transport = (globalThis as {
+      __DSH_TRANSPORT__?: { loadBundle?: unknown }
+    }).__DSH_TRANSPORT__
+    if (transport?.loadBundle !== undefined) return
     await Promise.all(this.manifest.plugins
       .filter(row => row.immediately)
       .map(row => this.modules.prefetch(row.id).catch((_prefetchError: unknown) => {

From 97f4d4608baf97949dbc0ba07db23289bb26fedb Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 13:44:23 +0800
Subject: [PATCH 15/34] test(gateway): pin the namespace atomic-visibility
 guarantee

---
 packages/api/gateway/tests/gateway.client.spec.ts | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/api/gateway/tests/gateway.client.spec.ts b/packages/api/gateway/tests/gateway.client.spec.ts
index c6d4a03eb3..99fe477bf2 100644
--- a/packages/api/gateway/tests/gateway.client.spec.ts
+++ b/packages/api/gateway/tests/gateway.client.spec.ts
@@ -528,6 +528,21 @@ describe('Client Typert API', () => {
     expect(ctx.get('remote.probe')).toBeUndefined()
   })
 
+  it('unparks a namespace dependent only after its contribution methods exist', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const { scope: _scope, ...direct } = directDescriptor()
+    let observed: string | undefined
+    // Parked before the mount: the unpark moment is the observation — the
+    // atomic-visibility guarantee says the service never appears methodless.
+    const parked = ctx.inject(['remote.probe'], (probeCtx) => {
+      observed = typeof (probeCtx.get('remote.probe') as { create?: unknown } | undefined)?.create
+    })
+    const dispose = await ctx.remote.$mount({ package: '@fixture/atomic-visibility', descriptors: [direct] })
+    await parked
+    expect(observed).toBe('function')
+    await dispose()
+  })
+
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()

From d5829397832416182d0fac952aa9a535970e8eb6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 13:44:29 +0800
Subject: [PATCH 16/34] docs(web): align injection-surface JSDoc, notes, and
 bilingual READMEs

---
 .../2026-08-19-web-index-injection-table.i18n.yaml          | 4 ++--
 .../architecture/2026-08-19-web-index-injection-table.md    | 2 +-
 .../architecture/2026-08-19-web-index-injection-table.zh.md | 2 +-
 docs/subsystems/web-server.i18n.yaml                        | 4 ++--
 docs/subsystems/web-server.md                               | 5 +++--
 docs/subsystems/web-server.zh.md                            | 5 +++--
 packages/extensions/cordis-host-runner/src/sandbox.ts       | 6 +++++-
 packages/extensions/tool-cordis/src/api-catalog.ts          | 2 +-
 packages/host/frontend-static/README.i18n.yaml              | 4 ++--
 packages/host/frontend-static/README.md                     | 2 +-
 packages/host/frontend-static/README.zh.md                  | 2 +-
 packages/host/webserver/README.i18n.yaml                    | 4 ++--
 packages/host/webserver/README.md                           | 2 +-
 packages/host/webserver/README.zh.md                        | 2 +-
 packages/host/webserver/src/index.ts                        | 5 +++--
 packages/host/webserver/src/injections.ts                   | 2 +-
 16 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml
index 1c228865dc..90d1f96dff 100644
--- a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.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/architecture/2026-08-19-web-index-injection-table.md
-2026-08-19-web-index-injection-table.md: a4c21974ef6770320b61cd7c2b19fc20372e8111
-2026-08-19-web-index-injection-table.zh.md: 4ccfa8afe6353e9af7e341ce73f5fb3213257ba2
+2026-08-19-web-index-injection-table.md: 9ed02aa94cd318d107a32802d8723652e6b10ea2
+2026-08-19-web-index-injection-table.zh.md: 8ad036766faa14071b20da12ef907ab012cae23f
diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
index a4c21974ef..9ed02aa94c 100644
--- a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.md
@@ -20,7 +20,7 @@ One table, two renderers: the served form's `webServer.renderIndex(html)` render
 
 - client-modules and ui-theme no longer regex-edit HTML; the worker's `readBootPayload` service-poking (`clientModules`, `settings`, theme constants through `loader.load`) is deleted; the page-side `installModuleLoaderFacade`, `applyBootTheme`, and `PARSER_PRELOAD_IDS` re-implementations retire.
 - Ordering: across subscribers, subscription order (same as the old tap order); within one subscriber, push order — modules itself guarantees queue → preloads → global.
-- The served rendering of the manifest global changed from `window.__DSH_BOOT__ =` to `globalThis["__DSH_BOOT__"] =`; snapshot expectations carrying that text need re-recording.
+- The served rendering of the manifest global changed from `window.__DSH_BOOT__ =` to `globalThis["__DSH_BOOT__"] =`; no committed snapshot expectation carries that text, so none needed re-recording.
 - New model-visible or page-visible boot inputs extend the row union; no new tap consumers.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
index 4ccfa8afe6..8ad036766f 100644
--- a/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-19-web-index-injection-table.zh.md
@@ -20,7 +20,7 @@ Web 壳的启动 HTML 需要三类注入：client-modules 的引导协议（`__M
 
 - client-modules 与 ui-theme 不再各自正则改 HTML；worker 侧 `readBootPayload` 的 `ctx.get` 手掏（clientModules、settings、theme 常量 loader.load）删除；页面侧 `installModuleLoaderFacade`、`applyBootTheme`、`PARSER_PRELOAD_IDS` 三份重抄退役。
 - 顺序语义：跨订阅方按订阅注册顺序（与旧 tap 顺序一致），单订阅方内按 push 顺序；modules 自己保证 队列→preload→全局 三行有序。
-- `__DSH_BOOT__` 的 served 渲染文本从 `window.__DSH_BOOT__ =` 变为 `globalThis["__DSH_BOOT__"] =`；含此文本的快照期望需重录。
+- `__DSH_BOOT__` 的 served 渲染文本从 `window.__DSH_BOOT__ =` 变为 `globalThis["__DSH_BOOT__"] =`；已核实无已提交快照期望含此文本，无需重录。
 - 新的模型可见/页面可见注入一律走行类型扩展，不再新增 tap 消费者。
 
 ## Alternatives considered
diff --git a/docs/subsystems/web-server.i18n.yaml b/docs/subsystems/web-server.i18n.yaml
index 519c6e7043..f04a35b545 100644
--- a/docs/subsystems/web-server.i18n.yaml
+++ b/docs/subsystems/web-server.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 docs/subsystems/web-server.md
-web-server.md: 7dd700d24f63d31f34d8711069477414292e3bf6
-web-server.zh.md: ca67ff231e9aad9144fa5203ee46435f636a93da
+web-server.md: 70bc0a2631418c102bdb79c1df29a73df5edf30a
+web-server.zh.md: 870c9209dcfacd191da408be2e195edc047ab25d
diff --git a/docs/subsystems/web-server.md b/docs/subsystems/web-server.md
index 7dd700d24f..70bc0a2631 100644
--- a/docs/subsystems/web-server.md
+++ b/docs/subsystems/web-server.md
@@ -88,8 +88,9 @@ registerUpgrade(route: WebUpgradeRoute): () => void
 registerFallback(handler: WebRoute['handler']): () => void
 
 /**
- * Register an index.html transform, applied by the fallback owner to every
- * index response ({@link applyIndexTaps}) in registration order.
+ * Register a raw-HTML index transform, the escape hatch for markup no
+ * {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
+ * registration order after rendering the structured rows.
  * @param transform - pure html-to-html function.
  * @returns the disposer removing the transform.
  */
diff --git a/docs/subsystems/web-server.zh.md b/docs/subsystems/web-server.zh.md
index ca67ff231e..870c9209dc 100644
--- a/docs/subsystems/web-server.zh.md
+++ b/docs/subsystems/web-server.zh.md
@@ -88,8 +88,9 @@ registerUpgrade(route: WebUpgradeRoute): () => void
 registerFallback(handler: WebRoute['handler']): () => void
 
 /**
- * Register an index.html transform, applied by the fallback owner to every
- * index response ({@link applyIndexTaps}) in registration order.
+ * Register a raw-HTML index transform, the escape hatch for markup no
+ * {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
+ * registration order after rendering the structured rows.
  * @param transform - pure html-to-html function.
  * @returns the disposer removing the transform.
  */
diff --git a/packages/extensions/cordis-host-runner/src/sandbox.ts b/packages/extensions/cordis-host-runner/src/sandbox.ts
index f359801af1..fc0a771e4f 100644
--- a/packages/extensions/cordis-host-runner/src/sandbox.ts
+++ b/packages/extensions/cordis-host-runner/src/sandbox.ts
@@ -201,6 +201,10 @@ export function parseErrorMessage(half: 'code.host' | 'code.client', context: st
  * unparseable code — and `vm.Script` is only the best-effort prettifier: on a
  * Node host its failure carries the source-line-and-caret prelude the
  * teaching text builds on, and where the vm is a stub the message stays bare.
+ * The two parsers' syntax faces differ at the margin (`new.target` parses in
+ * a function body but not at the vm wrapper's top level), an accepted cost of
+ * a vm-free gate; and under a page CSP without `'unsafe-eval'`, `new Function`
+ * throws `EvalError`, which propagates unwrapped.
  * @param code - the model-written function body.
  * @param half - which define argument carried it, for the error text.
  * @throws when the body does not parse, with the offending line and a teaching hint.
@@ -209,7 +213,7 @@ export function precheckCode(code: string, half: 'code.host' | 'code.client'): v
   const wrapped = `(async () => {\n${code}\n})()`
   try {
     // Compile-only: constructing the function parses the source and runs nothing.
-    // eslint-disable-next-line @typescript-eslint/no-implied-eval -- parse gate over model-written code; nothing is invoked
+    // oxlint-disable-next-line typescript/no-implied-eval -- parse gate over model-written code; nothing is invoked
     new Function(wrapped)
   } catch (error) {
     if (!isSyntaxError(error)) throw error
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index a20c0b9aff..bf0f6a9e79 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -2207,7 +2207,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'tapIndex(transform: (html: string) => string): () => void',
-        description: 'Register an index.html transform, applied by the fallback owner to every index response (applyIndexTaps) in registration order.',
+        description: 'Register a raw-HTML index transform, the escape hatch for markup no IndexInjection row expresses: renderIndex applies taps in registration order after rendering the structured rows.',
         parameters: [{ name: 'transform', description: 'pure html-to-html function.' }],
         returns: 'the disposer removing the transform.',
       },
diff --git a/packages/host/frontend-static/README.i18n.yaml b/packages/host/frontend-static/README.i18n.yaml
index 0514c3889e..2255848c81 100644
--- a/packages/host/frontend-static/README.i18n.yaml
+++ b/packages/host/frontend-static/README.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 packages/host/frontend-static/README.md
-README.md: e53a369384fb8d7fe020e99da0d2cacca59e8afd
-README.zh.md: 7018d80182d477f2bdff7b1d8510971dc98c71d5
+README.md: fb9ab0c9fea6fdaffdc08ecb63b17ffff9ff1e16
+README.zh.md: b0fd0f3aac7e54ccd50f8e87a186fd080c925610
diff --git a/packages/host/frontend-static/README.md b/packages/host/frontend-static/README.md
index e53a369384..fb9ab0c9fe 100644
--- a/packages/host/frontend-static/README.md
+++ b/packages/host/frontend-static/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-SPA dist server for the Web shell: a function plugin (config `{distIndex}`) that claims the [webserver](../webserver/README.md)'s single fallback seat and serves the built frontend directory with the shell's locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as `application/octet-stream`, and non-GET/HEAD without a matching named route is 405. Every index response runs through the webserver's registered index taps (`applyIndexTaps`), which is how the boot manifest reaches the page. `distIndex` is an assembly fact of the composing application: [`dsh-web-app`](../../bundle/web-app/README.md) resolves it through the frontend package's exports and mounts this plugin; a deployment never hardcodes it.
+SPA dist server for the Web shell: a function plugin (config `{distIndex}`) that claims the [webserver](../webserver/README.md)'s single fallback seat and serves the built frontend directory with the shell's locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as `application/octet-stream`, and non-GET/HEAD without a matching named route is 405. Every index response is rendered through the webserver's `renderIndex` — structured injection rows first, then the raw index taps — which is how the boot manifest reaches the page. `distIndex` is an assembly fact of the composing application: [`dsh-web-app`](../../bundle/web-app/README.md) resolves it through the frontend package's exports and mounts this plugin; a deployment never hardcodes it.
 
 The fallback seat is single-owner (a second claim throws) and effect-scoped: disposing the plugin's fiber releases the seat, after which the unclaimed webserver answers 404.
 
diff --git a/packages/host/frontend-static/README.zh.md b/packages/host/frontend-static/README.zh.md
index 7018d80182..b0fd0f3aac 100644
--- a/packages/host/frontend-static/README.zh.md
+++ b/packages/host/frontend-static/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换器（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都经 webserver 的 `renderIndex` 渲染——先结构化注入行、后原始 index 转换器——启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
 
 回退席位只有单一所有者（第二次占据会抛错），并受 effect 作用域约束：dispose（资源释放）插件的 fiber 会释放席位，此后无人占据的 webserver 回答 404。
 
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index 591ca04216..a9301ea812 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/README.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 packages/host/webserver/README.md
-README.md: 7927c791a809ad272edce1310b3c50bbe30720a5
-README.zh.md: 82252adb3945f22c83abddbd3bbdd11556383add
+README.md: b6424262305b062f4c57774c446ac1d50e490a03
+README.zh.md: cdeeb26159b98048f8ba5e821e7d6e733f447351
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
index 7927c791a8..b642426230 100644
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Web HTTP and upgrade-route registration plugin (default-exported `WebServer`, config `{host, port}`): a `node:http` server that listens on activation and provides `ctx.webServer`. `register(route)` adds a named `exact`/`prefix` HTTP route; `registerUpgrade(route)` adds an upgrade route for an exact pathname. A duplicate path within either table throws because route patterns are a composition-level contract and a collision is a misconfiguration; both methods return a disposer that removes the registration. `registerFallback(handler)` registers the one handler for requests that match no named route. A second registration throws; the SPA dist server [`dsh-host-frontend-static`](../frontend-static/README.md) is the shipped owner, and the server returns 404 while none is registered. `tapIndex(transform)` adds an index.html transform, and `applyIndexTaps(html)` runs a body through the registered transforms in order; the fallback handler calls it on every index response. `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). HTTP match order is fixed: exact over the whole table, then longest prefix, then the fallback handler. Upgrades match exactly and unmatched connections are closed; registration order carries no request-facing semantics.
+Web HTTP and upgrade-route registration plugin (default-exported `WebServer`, config `{host, port}`): a `node:http` server that listens on activation and provides `ctx.webServer`. `register(route)` adds a named `exact`/`prefix` HTTP route; `registerUpgrade(route)` adds an upgrade route for an exact pathname. A duplicate path within either table throws because route patterns are a composition-level contract and a collision is a misconfiguration; both methods return a disposer that removes the registration. `registerFallback(handler)` registers the one handler for requests that match no named route. A second registration throws; the SPA dist server [`dsh-host-frontend-static`](../frontend-static/README.md) is the shipped owner, and the server returns 404 while none is registered. Index startup inputs are structured rows: `collectIndexInjections()` gathers a fresh `IndexInjection` table over one `webserver/index-inject` emit per call, and `renderIndex(html)` renders the rows into an index.html body before applying the raw `tapIndex(transform)` transforms in registration order (`applyIndexTaps(html)`, the escape hatch for markup no row expresses); the fallback handler calls `renderIndex` on every index response, and a static deployment ships the same rows over its boot payload, rendering with the exported `renderIndexInjections`. `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). HTTP match order is fixed: exact over the whole table, then longest prefix, then the fallback handler. Upgrades match exactly and unmatched connections are closed; registration order carries no request-facing semantics.
 
 The package knows no harness concepts and serves no files: the `/api` HTTP bridge and downlink WebSockets are routes owned by the connection plugin, plugin bundles and the HMR event stream are routes owned by the modules/hmr plugins, and dist serving belongs to the fallback owner. The upgrade handler owns the protocol handshake and connection contents; the webserver only delivers the raw socket and request. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure). This server serves browsers only; Electron loads dist over `file://` and carries fetch over an IPC bridge. This package never prints; the URL line belongs to the shell.
 
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index 82252adb39..cdeeb26159 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `WebServer`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 注册一个 handler，处理所有未被具名 route 命中的请求。第二次注册会抛错；随附的 SPA dist 服务器 [`dsh-host-frontend-static`](../frontend-static/README.md) 是该 handler 的所有者，没有注册 handler 时服务器返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换；fallback handler 在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给 fallback handler。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不影响请求处理。
+Web HTTP 与 upgrade route 注册插件（默认导出 `WebServer`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 注册一个 handler，处理所有未被具名 route 命中的请求。第二次注册会抛错；随附的 SPA dist 服务器 [`dsh-host-frontend-static`](../frontend-static/README.md) 是该 handler 的所有者，没有注册 handler 时服务器返回 404。index 的启动输入是结构化行：`collectIndexInjections()` 每次调用经一次 `webserver/index-inject` emit 现收一张全新的 `IndexInjection` 表，`renderIndex(html)` 先把行渲染进 index.html 响应体，再按注册顺序应用原始的 `tapIndex(transform)` 转换（`applyIndexTaps(html)`，行无法表达的标记的逃生口）；fallback handler 在每次 index 响应时调用 `renderIndex`，静态部署则把同一批行经 boot 载荷下发，用导出的 `renderIndexInjections` 渲染。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给 fallback handler。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不影响请求处理。
 
 该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认安全姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务浏览器；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch。该包从不打印内容；URL 行属于 shell。
 
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index 94aba72382..2257e79623 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -145,8 +145,9 @@ export class WebServer extends Service {
   }
 
   /**
-   * Register an index.html transform, applied by the fallback owner to every
-   * index response ({@link applyIndexTaps}) in registration order.
+   * Register a raw-HTML index transform, the escape hatch for markup no
+   * {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
+   * registration order after rendering the structured rows.
    * @param transform - pure html-to-html function.
    * @returns the disposer removing the transform.
    */
diff --git a/packages/host/webserver/src/injections.ts b/packages/host/webserver/src/injections.ts
index cb1e5336a5..dc38213e85 100644
--- a/packages/host/webserver/src/injections.ts
+++ b/packages/host/webserver/src/injections.ts
@@ -23,7 +23,7 @@ export type IndexInjection =
    * loader resolves worker-only URLs such as `/plugins/...`).
    */
   | { kind: 'script-src'; placement: IndexInjectionPlacement; src: string }
-  /** A `<style>` element in the head. */
+  /** A `<style>` element in the head. `text` must not contain `</style`, which would close the element early. */
   | { kind: 'style'; text: string }
   /** Raw markup fragment. */
   | { kind: 'html'; placement: IndexInjectionPlacement; html: string }

From be3a630da857a6d07f364e1be3fc8030fe06d5b6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 19 Aug 2026 13:53:00 +0800
Subject: [PATCH 17/34] docs(web): retire tap-era prose across READMEs,
 subsystems, and notes

---
 ...-web-config-tree-boot-and-transport-layering.i18n.yaml | 4 ++--
 ...6-07-24-web-config-tree-boot-and-transport-layering.md | 2 +-
 ...7-24-web-config-tree-boot-and-transport-layering.zh.md | 2 +-
 .../2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml       | 4 ++--
 .../bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md      | 2 +-
 .../bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md   | 2 +-
 docs/subsystems/client-modules.i18n.yaml                  | 4 ++--
 docs/subsystems/client-modules.md                         | 8 ++++----
 docs/subsystems/client-modules.zh.md                      | 8 ++++----
 docs/subsystems/web-server.i18n.yaml                      | 4 ++--
 docs/subsystems/web-server.md                             | 2 +-
 docs/subsystems/web-server.zh.md                          | 2 +-
 packages/client/connection/README.i18n.yaml               | 4 ++--
 packages/client/connection/README.md                      | 2 +-
 packages/client/connection/README.zh.md                   | 2 +-
 packages/client/web/README.i18n.yaml                      | 4 ++--
 packages/client/web/README.md                             | 2 +-
 packages/client/web/README.zh.md                          | 2 +-
 18 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 340f07b15c..ef95863be1 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: f397ca6a25cffa0ba709d0a8e84717a1c228b951
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: e1cde78bad16d618913e52894eff1271dac74be1
+2026-07-24-web-config-tree-boot-and-transport-layering.md: eb30ba84ef293a169931ef6519a9d6d2ea98af7f
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 7a175b44fa8806b4b73eca538f32f16aa778fdee
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index f397ca6a25..eb30ba84ef 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -18,7 +18,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Config sources have one declaration place each.** Bundle yml values are engineering defaults, Settings sections are writable user preferences, CLI flags address their owning launcher rows, and env values enter through yml `!!js` expressions. Patches replace a row's config wholesale. The resolved frontend `distIndex` uses that patch channel as an assembly fact. The transport-independent provider/model default belongs to `ctx.agentDefaultModel`; the [direct headless entry point](2026-08-09-headless-direct-core-entry-point.md) and the Web gateway consume the same state.
 
-**The transport splits five ways.** `dsh-host-apiproxy` is the gateway plugin (`api-gateway` row): it default-exports `ApiProxyService`, configures only `{nativeOpen?}`, consumes the base layer's entry-point-neutral `ctx.agentDefaultModel`, provides `ctx.apiProxy`, remains transport-agnostic, and registers no routes. `dsh-host-webserver` is a plain route-registration plugin: `WebServer` provides `ctx.webServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, answers per-request failures with 400 and logging, and knows no harness concepts. The connection node half owns the `/api` binding from `ctx.apiProxy` through `toFetchHandler`. The modules node half (`ClientModuleRegistry`, providing `ctx.clientModules`) owns incremental package scanning, the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload through `fs.watchFile` membership and the `/plugins/events` SSE route.
+**The transport splits five ways.** `dsh-host-apiproxy` is the gateway plugin (`api-gateway` row): it default-exports `ApiProxyService`, configures only `{nativeOpen?}`, consumes the base layer's entry-point-neutral `ctx.agentDefaultModel`, provides `ctx.apiProxy`, remains transport-agnostic, and registers no routes. `dsh-host-webserver` is a plain route-registration plugin: `WebServer` provides `ctx.webServer` (`register(route) → disposer` with duplicate-pattern throw, `renderIndex` rendering — structured `webserver/index-inject` rows, then raw `tapIndex` transforms in registration order — and `port`), listens on activation, answers per-request failures with 400 and logging, and knows no harness concepts. The connection node half owns the `/api` binding from `ctx.apiProxy` through `toFetchHandler`. The modules node half (`ClientModuleRegistry`, providing `ctx.clientModules`) owns incremental package scanning, the bundle route, the boot injection rows, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload through `fs.watchFile` membership and the `/plugins/events` SSE route.
 
 **Package export discipline.** The modules package exposes exactly `.` (node half) and `./client` (the complete browser half: `ClientModuleSystem`, `parseBootManifest`, the adoption plugin face) — no bespoke subpaths; wire types re-export through the root for host-side consumers. The adoption handshake: the kernel writes the constructed instance to `window.__DSH_MODULES__` before cordis exists; the `./client` apply reads the slot (missing = loud throw) and provides `ctx.modules`.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index e1cde78bad..7a175b44fa 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **每个配置源有唯一声明位置。** 组合包 yml 值是工程默认，Settings 分节是可写的用户偏好，CLI（命令行界面）flags 面向其归属的启动器配置行，env 值则通过 yml `!!js` 表达式进入。patch 会整体替换一行的 config。解析后的前端 `distIndex` 通过同一条 patch 通道作为组装事实传递。与传输无关的提供方／模型默认值归 `ctx.agentDefaultModel` 所有；[直接 headless 入口](2026-08-09-headless-direct-core-entry-point.md)与 Web 网关消费同一份状态。
 
-**传输五分。** `dsh-host-apiproxy` 是网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，只配置 `{nativeOpen?}`，消费 base 层不偏向特定入口的 `ctx.agentDefaultModel`，provide `ctx.apiProxy`，保持传输无关且不注册路由。`dsh-host-webserver` 是朴素的路由注册插件：`WebServer` provide `ctx.webServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败时答 400 并记日志，且不认识任何 harness 概念。connection node 半拥有从 `ctx.apiProxy` 经 `toFetchHandler` 绑定到 `/api` 的逻辑。modules node 半（`ClientModuleRegistry`，provide `ctx.clientModules`）拥有单包增量扫描、bundle 路由、index tap 与 `onRebuilt`/`onGraphChanged` 通知。HMR（热模块替换） node 半通过 `fs.watchFile` membership 与 `/plugins/events` SSE 路由拥有开发期重载。
+**传输五分。** `dsh-host-apiproxy` 是网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，只配置 `{nativeOpen?}`，消费 base 层不偏向特定入口的 `ctx.agentDefaultModel`，provide `ctx.apiProxy`，保持传输无关且不注册路由。`dsh-host-webserver` 是朴素的路由注册插件：`WebServer` provide `ctx.webServer`（`register(route) → disposer`、重复 pattern 即抛、`renderIndex` 渲染——先结构化 `webserver/index-inject` 行、后原始 `tapIndex` 按注册序应用——与 `port`），激活即 listen，单请求失败时答 400 并记日志，且不认识任何 harness 概念。connection node 半拥有从 `ctx.apiProxy` 经 `toFetchHandler` 绑定到 `/api` 的逻辑。modules node 半（`ClientModuleRegistry`，provide `ctx.clientModules`）拥有单包增量扫描、bundle 路由、启动注入行与 `onRebuilt`/`onGraphChanged` 通知。HMR（热模块替换） node 半通过 `fs.watchFile` membership 与 `/plugins/events` SSE 路由拥有开发期重载。
 
 **包出口纪律。** modules 包只暴露 `.`（node 半）与 `./client`（完整浏览器半：`ClientModuleSystem`、`parseBootManifest`、收编插件面）——不设专用子路径；wire 类型经根出口 re-export 给 host 侧消费方。收编握手：内核在 cordis 之前把建好的实例写入 `window.__DSH_MODULES__`；`./client` 的 apply 读取该槽位（缺少时显式抛错）并 provide `ctx.modules`。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml
index c96e63cc6a..7c446795c9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.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/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
-2026-08-10-pre-plugin-theme-bootstrap.md: 7f5c57316d7dd022b08918459282a6f6128eb93b
-2026-08-10-pre-plugin-theme-bootstrap.zh.md: 7152bf8dc2bbfae2a671c4da899cbebda0bd4b39
+2026-08-10-pre-plugin-theme-bootstrap.md: cf3b2d5b6c8e8b102df6a37bab0fc63d81d8736b
+2026-08-10-pre-plugin-theme-bootstrap.zh.md: 2836f7b6d32528796bf64bf708229d5677866364
diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
index 7f5c57316d..cf3b2d5b6c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.md
@@ -12,7 +12,7 @@ The web shell renders `Loading plugins…` before the browser-side plugin tree a
 
 ## Decision
 
-ui-theme's host half transforms each index HTML document through `ctx.webServer.tapIndex()`, inserting a synchronous inline script immediately after the opening `<body>` tag. The transform registers under an optional `httpServer` injection, so compositions without that service still activate ui-theme and install no transform. When the HTML parser executes the script, the body exists, but the shell's module script and framework-free boot page have not yet run.
+ui-theme's host half answers every `webserver/index-inject` collection with one body-placed script row (`bootThemeInjection`), which `renderIndex` renders as a synchronous inline script immediately after the opening `<body>` tag. The subscription is unconditional — a composition without a web server never emits the event, so ui-theme still activates and contributes nothing. When the HTML parser executes the script, the body exists, but the shell's module script and framework-free boot page have not yet run.
 
 The host half registers the [`ui-theme.preference` settings section](2026-08-06-host-backed-web-preferences.md) when a settings provider exists. For each index response, it embeds that schema-validated built-in preference in the inline script; without a settings provider or active registration, it embeds the `system` default. The browser resolves `system` through `prefers-color-scheme`, falling back to light when `matchMedia` is unavailable. It writes only the two pieces of DOM state that ThemePresenter later owns: `document.documentElement.style.colorScheme` and `body[data-ds-dark-theme]`.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
index 7152bf8dc2..2836f7b6d3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-10-pre-plugin-theme-bootstrap.zh.md
@@ -12,7 +12,7 @@ Web 壳在浏览器侧插件树激活前呈现 `Loading plugins…`。ui-theme 
 
 ## 决策
 
-ui-theme 的主机侧通过 `ctx.webServer.tapIndex()` 转换每份 index HTML，在 `<body>` 起始标签后紧接一段同步内联脚本。该转换通过可选的 `httpServer` 注入注册，因此不含该服务的组合仍会激活 ui-theme，但不会安装转换。HTML 解析器执行该脚本时，body 已存在，而壳的模块脚本与不依赖框架的启动页尚未运行。
+ui-theme 的主机侧以一条 body 定位的 script 行（`bootThemeInjection`）回应每次 `webserver/index-inject` 收集，`renderIndex` 把它渲染为 `<body>` 起始标签后紧接的一段同步内联脚本。订阅是无条件的——没有 web server 的组合根本不会 emit 该事件，ui-theme 照常激活且不贡献任何行。HTML 解析器执行该脚本时，body 已存在，而壳的模块脚本与不依赖框架的启动页尚未运行。
 
 settings provider 存在时，主机侧会注册 [`ui-theme.preference` settings 分节](2026-08-06-host-backed-web-preferences.md)。它为每份 index 响应把经过 schema 校验的内建偏好嵌入内联脚本；不存在 settings provider 或有效注册时则嵌入默认值 `system`。浏览器通过 `prefers-color-scheme` 解析 `system`，不支持 `matchMedia` 时回退为浅色。脚本只写 ThemePresenter 后续拥有的两项 DOM 状态：`document.documentElement.style.colorScheme` 与 `body[data-ds-dark-theme]`。
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 4c8f701de2..f45825acd5 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 81c85e2f0eb1d7248459f6ca092ed89f602e8415
-client-modules.zh.md: 37b8acc0d6d335802333100b5e55e709153911da
+client-modules.md: d939cbbafa186b82d9110a6ccc41e9892b53eb95
+client-modules.zh.md: 8f407de0bd44ea2cc95b6d29ca7e149648785c0f
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 81c85e2f0e..d939cbbafa 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -2,13 +2,13 @@
 
 English | [中文](client-modules.zh.md)
 
-The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModules` (`ClientModuleRegistry`). It scans the host Loader's entries for packages declaring `dsh.client`, composes the `window.__DSH_BOOT__` entry graph, serves each bundle at `/plugins/<id>/client.js`, and taps the index render to inject the boot manifest — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [web-server.md](web-server.md) supplies the prefix route and index tap this service registers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
+The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModules` (`ClientModuleRegistry`). It scans the host Loader's entries for packages declaring `dsh.client`, composes the `window.__DSH_BOOT__` entry graph, serves each bundle at `/plugins/<id>/client.js`, and answers every index-injection collection with the boot manifest rows — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [web-server.md](web-server.md) supplies the prefix route and the `webserver/index-inject` event this service answers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
 
 Source: [`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
 
 ## The wire
 
-The graph is the wire single source between the Node and browser halves: the host composes `WebBootEntry` rows from scanned packages, injects the graph as the first script in `<head>` (`window.__DSH_BOOT__`, with `<` escaped so plugin-controlled strings cannot break out of the script element), and the shell parses it before booting anything. A page without a valid manifest cannot boot — the browser-side parser throws loud on a missing or malformed graph.
+The graph is the wire single source between the Node and browser halves: the host composes `WebBootEntry` rows from scanned packages, publishes the graph as a `global` injection row rendered ahead of later script rows (`globalThis["__DSH_BOOT__"]`, with `<` escaped so plugin-controlled strings cannot break out of the script element), and the shell parses it before booting anything. A page without a valid manifest cannot boot — the browser-side parser throws loud on a missing or malformed graph.
 
 ```ts type-equiv
 /**
@@ -60,9 +60,9 @@ Scanning is incremental per package; there is no full-rescan code path. Every co
 
 Package metadata — including the negative "not a client package" verdict — is cached per name and never expires: plugin-set changes take effect on restart. A fiber restart reuses its row and rev untouched; bundle content changes reach the graph only through `rebuilt()`.
 
-## The bundle route and index tap
+## The bundle route and index injection
 
-`GET`/`HEAD /plugins/<id>/client.js` serves the registered bundle from disk with `no-cache` (the rev query, not HTTP caching, anchors consistency); other methods are 405. An unknown id — or a registered row whose bundle is unreadable because it has not been built yet — answers a loud 404 rather than letting the carrier's SPA fallback ship HTML as JavaScript. The index tap injects the current graph on every index render, so a reload always boots against the live composition.
+`GET`/`HEAD /plugins/<id>/client.js` serves the registered bundle from disk with `no-cache` (the rev query, not HTTP caching, anchors consistency); other methods are 405. An unknown id — or a registered row whose bundle is unreadable because it has not been built yet — answers a loud 404 rather than letting the carrier's SPA fallback ship HTML as JavaScript. The injection rows carry the current graph on every index render, so a reload always boots against the live composition.
 
 ## The service
 
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index 37b8acc0d6..8f407de0bd 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -2,13 +2,13 @@
 
 [English](client-modules.md) | 中文
 
-Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 模块系统的 Node 半，以 `ctx.clientModules`（`ClientModuleRegistry`）形式提供。它扫描宿主 Loader 的 entry，找出声明了 `dsh.client` 的包，组合出 `window.__DSH_BOOT__` entry 图，在 `/plugins/<id>/client.js` 提供各个 bundle，并经 index 转换（index tap）注入启动 manifest（元数据清单）——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 [dsh-host-webserver](../../packages/host/webserver) 的消费方：[web-server.md](web-server.md) 所述的载体提供本服务注册的前缀路由与 index 转换。同一个包的浏览器半（`ctx.modules`，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在[包 README](../../packages/client/modules/README.md)中，不在本页。
+Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 模块系统的 Node 半，以 `ctx.clientModules`（`ClientModuleRegistry`）形式提供。它扫描宿主 Loader 的 entry，找出声明了 `dsh.client` 的包，组合出 `window.__DSH_BOOT__` entry 图，在 `/plugins/<id>/client.js` 提供各个 bundle，并以启动 manifest（元数据清单）行回应每次 index 注入收集——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 [dsh-host-webserver](../../packages/host/webserver) 的消费方：[web-server.md](web-server.md) 所述的载体提供本服务注册的前缀路由与其回应的 `webserver/index-inject` 事件。同一个包的浏览器半（`ctx.modules`，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在[包 README](../../packages/client/modules/README.md)中，不在本页。
 
 源码：[`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
 
 ## wire
 
-图是 Node 半与浏览器半之间协议层的唯一真源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
+图是 Node 半与浏览器半之间协议层的唯一真源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图发布为一条 `global` 注入行、渲染在后续 script 行之前（`globalThis["__DSH_BOOT__"]`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
 
 ```ts type-equiv
 /**
@@ -60,9 +60,9 @@ interface WebBootGraph {
 
 包元数据——包括「非 client 包」这一否定结论——按名缓存且永不过期：插件集合的变更在重启后生效。fiber 重启原样复用其行与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
 
-## bundle 路由与 index 转换
+## bundle 路由与 index 注入
 
-`GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。index 转换在每次 index 渲染时注入当前图，因此刷新页面总是针对实时组合启动。
+`GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。注入行在每次 index 渲染时携带当前图，因此刷新页面总是针对实时组合启动。
 
 ## 服务
 
diff --git a/docs/subsystems/web-server.i18n.yaml b/docs/subsystems/web-server.i18n.yaml
index f04a35b545..31690c360d 100644
--- a/docs/subsystems/web-server.i18n.yaml
+++ b/docs/subsystems/web-server.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 docs/subsystems/web-server.md
-web-server.md: 70bc0a2631418c102bdb79c1df29a73df5edf30a
-web-server.zh.md: 870c9209dcfacd191da408be2e195edc047ab25d
+web-server.md: 6a33eb2bacb7dd9e85a13d7f2ef9cf870b5c44d9
+web-server.zh.md: 5dcc4b6e002c4bdeb0d839e67a750f67f40eb0a6
diff --git a/docs/subsystems/web-server.md b/docs/subsystems/web-server.md
index 70bc0a2631..6a33eb2bac 100644
--- a/docs/subsystems/web-server.md
+++ b/docs/subsystems/web-server.md
@@ -42,7 +42,7 @@ interface Config {
 
 ## The service
 
-`WebServer` (`ctx.webServer`) listens immediately on activation; a listen failure (EADDRINUSE…) rejects initialization, and the boot process reports the failed fiber. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](../../packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, including the port assigned by the OS when `config.port` is 0.
+`WebServer` (`ctx.webServer`) listens immediately on activation; a listen failure (EADDRINUSE…) rejects initialization, and the boot process reports the failed fiber. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws because route patterns are a composition-level contract and a collision is a misconfiguration. `collectIndexInjections()` gathers structured `IndexInjection` rows over one `webserver/index-inject` emit, and `renderIndex(html)` renders them into every index response — `/` and each SPA fallback — before applying the raw `tapIndex(transform)` escape-hatch transforms in registration order; [dsh-client-modules](../../packages/client/modules) answers the event with the boot manifest rows. `port` reads the listening port, including the port assigned by the OS when `config.port` is 0.
 
 A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
 
diff --git a/docs/subsystems/web-server.zh.md b/docs/subsystems/web-server.zh.md
index 870c9209dc..5dcc4b6e00 100644
--- a/docs/subsystems/web-server.zh.md
+++ b/docs/subsystems/web-server.zh.md
@@ -42,7 +42,7 @@ interface Config {
 
 ## 服务
 
-`WebServer`（`ctx.webServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会使初始化被拒绝，启动进程会报告失败的 fiber。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层约定，冲突即配置错误。`tapIndex(transform)` 添加一个纯 HTML 到 HTML 转换函数，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，包括 `config.port` 为 0 时操作系统分配的端口。
+`WebServer`（`ctx.webServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会使初始化被拒绝，启动进程会报告失败的 fiber。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层约定，冲突即配置错误。`collectIndexInjections()` 经一次 `webserver/index-inject` emit 收集结构化 `IndexInjection` 行，`renderIndex(html)` 把它们渲染进每个 index 响应（`/` 和每次 SPA 回退），随后再按注册顺序应用原始的 `tapIndex(transform)` 逃生口转换；[dsh-client-modules](../../packages/client/modules) 以启动 manifest（元数据清单）行回应该事件。`port` 读取监听端口，包括 `config.port` 为 0 时操作系统分配的端口。
 
 处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
 
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 4745644cc5..7570def38d 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.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 packages/client/connection/README.md
-README.md: f0a707cc5f3a962c7852f7323c727d0a39a57b10
-README.zh.md: b529eebf9af93e36b6b92c19964678b7f5a04ea1
+README.md: a7562b9dac57930b1abc0b76b9079a6865a38b35
+README.zh.md: c18740e98721a9aa7ec95037da45c739c58a06f7
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index f0a707cc5f..a7562b9dac 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + observable generation-scoped `hostDescription` + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` abstraction, and the loop's sink/config types. Each successful readiness handshake publishes the exact `host.describe` value before `onConnected`; generation loss and explicit stop clear it, so native-capability consumers never retain a disconnected answer. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered Typert interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from — and the agent-preset authoring plane, `agentPreset.read`/`copy`/`openDocument`/`remove`, since a composition names the plugins a session runs, so reading one is reconnaissance, and copy/remove/openDocument manage the roster and drive the host desktop (authoring is copy-only, so none of them accepts composition text or a path); `agentPreset.list` and `agentPreset.select` stay out — the roster carries only ids and trust, and choosing a preset grants nothing `session.create`'s own `agentPreset` did not, over a default that already carries bash) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md).
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + observable generation-scoped `hostDescription` + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` abstraction, and the loop's sink/config types. Each successful readiness handshake publishes the exact `host.describe` value before `onConnected`; generation loss and explicit stop clear it, so native-capability consumers never retain a disconnected answer. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The exported `ClientTransportHooks` names the page global `__DSH_TRANSPORT__` that replaces the browser carrier wholesale: the served web app leaves it unset and gets HTTP + WebSocket, while a shell owning a different physical transport (the worker preview's postMessage tunnel) provides `createApiClient` and `fetch` — plus `loadBundle` when it also owns bundle bytes — instead of forking the plugin. The Host half owns the single `/api` route and its Fetch bridge; a registered Typert interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from — and the agent-preset authoring plane, `agentPreset.read`/`copy`/`openDocument`/`remove`, since a composition names the plugins a session runs, so reading one is reconnaissance, and copy/remove/openDocument manage the roster and drive the host desktop (authoring is copy-only, so none of them accepts composition text or a path); `agentPreset.list` and `agentPreset.select` stay out — the roster carries only ids and trust, and choosing a preset grants nothing `session.create`'s own `agentPreset` did not, over a default that already carries bash) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md).
 
 ## /api browser-trust fence
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index b529eebf9a..c18740e987 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 可观察且按 generation 生效的 `hostDescription` + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。每次就绪握手成功后，都会在 `onConnected` 之前发布完整的 `host.describe` 值；generation 失效或显式 stop 会清空它，因此原生能力消费者不会保留已经断线的判断。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 Typert interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处——以及 agent（智能体） preset 的创作面 `agentPreset.read`/`copy`/`openDocument`/`remove`，因为组装指明了一个会话所运行的插件，读取它是侦察，而 copy/remove/openDocument 管理名单并驱动宿主桌面（创作只有复制一种写入，因此这些方法都不接收组装文本或路径）；`agentPreset.list` 与 `agentPreset.select` 不在其中——名单只携带 id 与信任级别，而选择一个 preset 并不比 `session.create` 自带的 `agentPreset` 多给任何能力，何况默认 preset 本就带着 bash）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 可观察且按 generation 生效的 `hostDescription` + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。每次就绪握手成功后，都会在 `onConnected` 之前发布完整的 `host.describe` 值；generation 失效或显式 stop 会清空它，因此原生能力消费者不会保留已经断线的判断。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。导出的 `ClientTransportHooks` 命名了整体替换浏览器载体的页面全局量 `__DSH_TRANSPORT__`：served web app 不设置它、走 HTTP + WebSocket；拥有另一种物理传输的壳（worker 预览的 postMessage 隧道）则在此提供 `createApiClient` 与 `fetch`——当它同时持有 bundle 字节时再加 `loadBundle`——而不必 fork 本插件。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 Typert interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处——以及 agent（智能体） preset 的创作面 `agentPreset.read`/`copy`/`openDocument`/`remove`，因为组装指明了一个会话所运行的插件，读取它是侦察，而 copy/remove/openDocument 管理名单并驱动宿主桌面（创作只有复制一种写入，因此这些方法都不接收组装文本或路径）；`agentPreset.list` 与 `agentPreset.select` 不在其中——名单只携带 id 与信任级别，而选择一个 preset 并不比 `session.create` 自带的 `agentPreset` 多给任何能力，何况默认 preset 本就带着 bash）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)。
 
 ## /api 浏览器信任栅栏
 
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index e837a4e834..23499090a1 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/README.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 packages/client/web/README.md
-README.md: c7b77d3eba8cf56017c816362e9ffc4fcb3be403
-README.zh.md: 2a52bcdfe7395466866b80160f0646cf3b7fe111
+README.md: b4304ddc3f7d8fc0f8bfc5cb8373196a97e0273f
+README.zh.md: aebaccf819f02ed49afdf4f20027738c19c6cde0
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
index c7b77d3eba..b4304ddc3f 100644
--- a/packages/client/web/README.md
+++ b/packages/client/web/README.md
@@ -8,7 +8,7 @@ The boot page uses plain DOM and local CSS, so client-bundle and plugin-activati
 
 `PLATFORM_MODULES` (src/platform.ts) is the single source of truth for shell-seeded shared modules. Together with `PRELOADED_CLIENT_EXTERNALS`, it defines the implicit external baseline for every dynamic bundle; `dsh.client.external` adds only exact non-baseline requests.
 
-The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
+The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it. A pre-injected page transport is the default ahead of it: when `globalThis.__DSH_TRANSPORT__` (the connection package's `ClientTransportHooks`) carries `loadBundle`, the module stage adopts it as the bundle transport and skips the immediate-tier HTTP prefetch — explicit `seams` still win.
 
 ## Model Experience
 
diff --git a/packages/client/web/README.zh.md b/packages/client/web/README.zh.md
index 2a52bcdfe7..aebaccf819 100644
--- a/packages/client/web/README.zh.md
+++ b/packages/client/web/README.zh.md
@@ -8,7 +8,7 @@ Web 启动内核：`new AppWebEntry(el, seams?).run()` 分两个阶段挂载客
 
 `PLATFORM_MODULES`（src/platform.ts）是外壳播种共享模块的唯一事实来源。它与 `PRELOADED_CLIENT_EXTERNALS` 一起定义全部动态 bundle 的隐式 external 基座；`dsh.client.external` 只添加基座之外的精确请求。
 
-可选的覆盖参数 `seams` 会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
+可选的覆盖参数 `seams` 会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。预注入的页面传输是位于其前的默认值：当 `globalThis.__DSH_TRANSPORT__`（connection 包的 `ClientTransportHooks`）携带 `loadBundle` 时，模块阶段将其采纳为 bundle 传输并跳过 immediately 层级的 HTTP 预取——显式 `seams` 仍然优先。
 
 ## 模型体验
 

From 7260f4cf649021024241a7b67979a6bf0e674cb3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 20 Aug 2026 16:58:41 +0800
Subject: [PATCH 18/34] fix(web): cap the answer field at six text lines in
 both variants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The card-wide `border-box` reached `.fieldMirror`, so the growth cap counted
text plus padding. The inline variant carries none and landed on the declared
line count, while the optionless variant's 16px inset spent two thirds of a
line and delivered its last one as an 8px sliver. The e2e measured only the
inline shape, so nothing caught the drift.

The mirror now takes `box-sizing: content-box`, which states the cap in the
units it is written in, and the cap moves to six lines. The e2e asserts whole
text lines rather than a box height, and covers the optionless shape — asked
straight through the user-questions seam, since a layout metric needs no model
round — including that the reserved empty field is fully covered by its own
control.
---
 ...-multiline-question-answer-field.i18n.yaml |  4 +-
 ...6-08-20-multiline-question-answer-field.md |  6 +-
 ...8-20-multiline-question-answer-field.zh.md |  6 +-
 apps/web/tests/question-composer.e2e.ts       | 80 +++++++++++++++++--
 .../client/ui-user-questions/README.i18n.yaml |  4 +-
 packages/client/ui-user-questions/README.md   |  2 +-
 .../client/ui-user-questions/README.zh.md     |  2 +-
 .../src/client/QuestionComposer.module.css    | 12 ++-
 8 files changed, 97 insertions(+), 19 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml
index 2040f0c481..13aaf1b69d 100644
--- a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.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/feature/2026-08-20-multiline-question-answer-field.md
-2026-08-20-multiline-question-answer-field.md: dbe146f1cd56b0f757784283269ba5061c425366
-2026-08-20-multiline-question-answer-field.zh.md: 7adb5bb37bf4393a5be21f1dc56b2be46fbfe9cb
+2026-08-20-multiline-question-answer-field.md: 5e411d6728205ce1b72ef8355bbf2493f28873eb
+2026-08-20-multiline-question-answer-field.zh.md: 6b98f017bbee2e8d89810c5b193b3707c85d1e95
diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
index dbe146f1cd..5e411d6728 100644
--- a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.md
@@ -16,7 +16,7 @@ Both question shapes answer into one `AnswerField`: a `<textarea rows={1}>` shar
 
 The mirror sits in normal flow and so sizes the grid row; the textarea stretches to that row, and `rows={1}` keeps the control's own intrinsic height out of the row sizing, leaving the mirror the only input to the height. Soft wraps are invisible to a `'\n'` count, so the mirror is what makes a wrapped answer grow the box rather than scroll one line. The trailing newline covers the last line the textarea's caret can reach and the block container drops. Mirror and textarea must keep identical type, padding, and wrapping rules; a divergence sizes the box wrong for the text being typed.
 
-Growth stops at the mirror's `max-height` of eight lines, and past that the textarea scrolls itself. It is the only scrollport in the stack: unlike the chat composer, this field paints its own glyphs, so there is no second layer whose scroll offset would have to match.
+Growth stops at the mirror's `max-height` of six lines, and past that the textarea scrolls itself. The mirror takes `box-sizing: content-box` against the card-wide `border-box` so that cap counts text lines rather than text plus padding: the optionless variant carries 16px of vertical padding, which under `border-box` spends two thirds of a line and delivers the last one as an 8px sliver, while the inline variant has no padding and would land on a different line count from the same declaration. It is the only scrollport in the stack: unlike the chat composer, this field paints its own glyphs, so there is no second layer whose scroll offset would have to match.
 
 Enter continues the flow and submits the batch on the last question, Shift+Enter breaks the line, and the IME guard is unchanged — Enter during composition confirms the candidate without advancing. The `variant` prop names which of the two looks the field takes, so the field owns both and neither caller assembles one out of class names.
 
@@ -32,9 +32,11 @@ Enter continues the flow and submits the batch on the last question, Shift+Enter
 
 **Uncapped growth.** Rejected because the card tops out at `min(60vh, 520px)` and still owes that budget to the title, the option rows, and the footer actions; an unbounded field pushes the choices the answer belongs to out of view.
 
+**A per-variant cap that absorbs each variant's padding.** Rejected because it couples the line count to a padding value: changing `.customBlock`'s inset would silently change how many lines the field grows to. `content-box` states the intent once, in the units the cap is written in.
+
 ## Testing
 
-Component tests pin the round trip: both shapes render a textarea, the mirror follows the draft, Shift+Enter never advances the flow, and line breaks reach the answer batch verbatim. The assembled `question-composer` web e2e measures the live engine — a soft-wrapped draft grows the field without scrolling it, two Shift+Enter presses leave `"\n\n"` in a taller field with the question still open, and a draft past the cap scrolls instead of growing.
+Component tests pin the round trip: both shapes render a textarea, the mirror follows the draft, Shift+Enter never advances the flow, and line breaks reach the answer batch verbatim. The assembled `question-composer` web e2e measures the live engine — a soft-wrapped draft grows the field without scrolling it, two Shift+Enter presses leave `"\n\n"` in a taller field with the question still open, and a draft past the cap scrolls instead of growing at exactly six text lines in both variants.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md
index 7adb5bb37b..6b98f017bb 100644
--- a/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-20-multiline-question-answer-field.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 镜像位于常规流中，因而决定 grid 行的高度；textarea 拉伸到该行，而 `rows={1}` 使控件自身的固有高度不参与行尺寸计算，于是镜像是高度的唯一输入。软换行对 `'\n'` 计数不可见，因此正是镜像让换行后的答案把输入框撑高，而不是在一行内滚动。结尾的换行补上 textarea 光标可达、而块级容器会丢弃的最后一行。镜像与 textarea 必须保持完全一致的字体、内边距与换行规则；一旦偏离，输入框的高度就与正在输入的文本不符。
 
-增高在镜像 `max-height` 的八行处停止，此后由 textarea 自身滚动。它是这个结构里唯一的滚动容器：与聊天输入框不同，本输入框自己绘制字形，因此不存在第二个需要对齐滚动偏移的图层。
+增高在镜像 `max-height` 的六行处停止，此后由 textarea 自身滚动。镜像用 `box-sizing: content-box` 覆盖卡片范围内的 `border-box`，使该上限计量的是文本行而不是「文本加内边距」：无选项变体带 16px 纵向内边距，在 `border-box` 下这会吃掉三分之二行、并把最后一行变成 8px 残条，而 inline 变体没有内边距，同一条声明会落到不同的行数上。它是这个结构里唯一的滚动容器：与聊天输入框不同，本输入框自己绘制字形，因此不存在第二个需要对齐滚动偏移的图层。
 
 Enter 继续流程并在最后一题提交整批，Shift+Enter 换行，IME 保护不变——组合输入期间按 Enter 只确认候选，不前进。`variant` 属性指明该输入框采用两种外观中的哪一种，因此外观归输入框自己所有，任何调用方都不必用类名拼装。
 
@@ -32,9 +32,11 @@ Enter 继续流程并在最后一题提交整批，Shift+Enter 换行，IME 保
 
 **不设增高上限。** 否决，因为卡片上限为 `min(60vh, 520px)`，还要把这份额度分给标题、选项行与底部操作；不设上限的输入框会把答案所属的选项挤出视野。
 
+**按变体各自吸收内边距的上限。** 否决，因为那会把行数与某个内边距值耦合：改动 `.customBlock` 的内边距会悄悄改变输入框能长到几行。`content-box` 只需声明一次意图，且与上限本身的单位一致。
+
 ## Testing
 
-组件测试固定了整条往返：两种形状都渲染 textarea、镜像跟随草稿、Shift+Enter 绝不前进流程、换行原样进入答案批次。组装后的 `question-composer` web e2e 则在真实引擎上测量——软换行的草稿把输入框撑高而不滚动，两次 Shift+Enter 之后 `"\n\n"` 留在更高的输入框里且问题仍未关闭，超过上限的草稿改为滚动而不再增高。
+组件测试固定了整条往返：两种形状都渲染 textarea、镜像跟随草稿、Shift+Enter 绝不前进流程、换行原样进入答案批次。组装后的 `question-composer` web e2e 则在真实引擎上测量——软换行的草稿把输入框撑高而不滚动，两次 Shift+Enter 之后 `"\n\n"` 留在更高的输入框里且问题仍未关闭，超过上限的草稿在两种变体下都恰好于六行文本处改为滚动而不再增高。
 
 ## Consequences
 
diff --git a/apps/web/tests/question-composer.e2e.ts b/apps/web/tests/question-composer.e2e.ts
index 96b6575678..47219a30d7 100644
--- a/apps/web/tests/question-composer.e2e.ts
+++ b/apps/web/tests/question-composer.e2e.ts
@@ -10,10 +10,11 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
-import type { Browser, Page } from 'playwright'
+import type { Browser, Locator, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import {
   assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
@@ -30,6 +31,31 @@ const COMPOSED_EXPECTED = join(SNAPSHOT_DIR, 'composed.expected.md')
 const ANSWERED_EXPECTED = join(SNAPSHOT_DIR, 'answered.expected.md')
 const MODE = webSnapshotMode()
 
+// The composer's own growth cap, in text lines (QuestionComposer.module.css
+// .fieldMirror). Asserted as TEXT lines, not as a box height: the two variants
+// carry different padding, and a cap measured in border-box pixels silently
+// means a different line count in each — which is exactly how the optionless
+// field came to stop two thirds of a line short.
+const CAP_LINES = 6
+
+/**
+ * Measure a saturated answer field: how many whole text lines it grew to, and
+ * whether it took over the scrolling once it stopped growing.
+ * @param field - the composer's custom-answer textarea.
+ * @returns whole text lines the content box holds, and whether the field scrolls.
+ */
+async function capMetrics(field: Locator): Promise<{ textLines: number; scrolls: boolean }> {
+  await field.fill('x\n'.repeat(40))
+  return field.evaluate((el: HTMLTextAreaElement) => {
+    const style = getComputedStyle(el)
+    const text = el.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+    return {
+      textLines: Math.round(text / parseFloat(style.lineHeight)),
+      scrolls: el.scrollHeight > el.clientHeight,
+    }
+  })
+}
+
 // The options carry long descriptions on purpose: the squeeze assertion below
 // needs option copy that WRAPS, which is the only text layout that reproduces a
 // collapsed row painting its copy outside its own box.
@@ -41,6 +67,7 @@ describe('web e2e: resident question composer round trip', () => {
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
   const sessionEvents: SessionEvent[] = []
+  let answeredSession: SessionId | undefined
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 15 })
@@ -141,13 +168,13 @@ describe('web e2e: resident question composer round trip', () => {
     // the squeeze above: record mode must reach the recording write.
     const custom = composer.getByRole('textbox')
     if (MODE !== 'record') {
-      const lineHeight = await custom.evaluate(el => el.getBoundingClientRect().height)
+      const oneLineHeight = await custom.evaluate(el => el.getBoundingClientRect().height)
       await custom.fill('a'.repeat(120))
       const wrapped = await custom.evaluate(el => ({
         height: el.getBoundingClientRect().height,
         scrolls: el.scrollHeight > el.clientHeight,
       }))
-      expect(wrapped.height).toBeGreaterThan(lineHeight * 1.5)
+      expect(wrapped.height).toBeGreaterThan(oneLineHeight * 1.5)
       expect(wrapped.scrolls).toBe(false)
 
       await custom.fill('')
@@ -156,10 +183,9 @@ describe('web e2e: resident question composer round trip', () => {
       expect(await custom.inputValue()).toBe('\n\n')
       expect(await composer.getByText('Which color do you prefer?').count()).toBeGreaterThan(0)
       expect(await custom.evaluate(el => el.getBoundingClientRect().height))
-        .toBeGreaterThan(lineHeight * 2.5)
+        .toBeGreaterThan(oneLineHeight * 2.5)
 
-      await custom.fill('x\n'.repeat(40))
-      expect(await custom.evaluate(el => el.scrollHeight > el.clientHeight)).toBe(true)
+      expect(await capMetrics(custom)).toEqual({ textLines: CAP_LINES, scrolls: true })
       await custom.fill('')
     }
 
@@ -179,6 +205,7 @@ describe('web e2e: resident question composer round trip', () => {
       await recordFixture(scaffold, sessionId, FIXTURE)
       return
     }
+    answeredSession = sessionId
     // World state: the tool result carries the chosen answer, and DONE lands.
     const results = sessionEvents.filter(e => e.type === 'tool/result')
     const answerText = results.flatMap(event => event.data.message.content.flatMap(block =>
@@ -202,6 +229,47 @@ describe('web e2e: resident question composer round trip', () => {
     expect(tripwire.warnings).toEqual([])
   }, 200_000)
 
+  // The fixture's question carries options, so the round trip above only ever
+  // exercises the inline shape. The optionless shape is the one that carries
+  // padding, which is where a cap measured in box pixels drifts off the line
+  // count — so it is asked straight through the user-questions seam (the same
+  // service the tool calls; no model round is involved in a layout metric).
+  it.skipIf(MODE === 'record')('grows the optionless answer to the same cap', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-question-optionless'))
+    const sessionId = answeredSession
+    expect(sessionId).toBeDefined()
+    const agent = scaffold.ctx.agents.get(sessionId as SessionId)
+    expect(agent).toBeDefined()
+    const asked = scaffold.ctx.userQuestions.ask({
+      agent: agent as NonNullable<typeof agent>,
+      questions: [{ id: 'free', header: 'More', question: 'Anything else?' }],
+    })
+
+    const composer = page.locator('[data-question-key]')
+    await composer.waitFor({ timeout: 30_000 })
+    const field = composer.getByRole('textbox')
+    // The empty field reserves its two lines AND the textarea fills that frame:
+    // a reserved box the control does not fill leaves a strip that looks like
+    // the field but takes no click.
+    expect(await field.evaluate((el) => {
+      const frame = el.parentElement as HTMLElement
+      const style = getComputedStyle(frame)
+      const inner = frame.getBoundingClientRect().height
+        - parseFloat(style.borderTopWidth) - parseFloat(style.borderBottomWidth)
+      return {
+        reserved: Math.round(frame.getBoundingClientRect().height),
+        fills: Math.abs(el.getBoundingClientRect().height - inner) < 0.5,
+      }
+    })).toEqual({ reserved: 64, fills: true })
+    // The same cap the inline shape stops at — the assertion a border-box cap fails.
+    expect(await capMetrics(field)).toEqual({ textLines: CAP_LINES, scrolls: true })
+
+    // Settle the wait so teardown is not racing a pending question.
+    await composer.getByRole('button', { name: 'Skip this question' }).click()
+    expect(await asked).toEqual({ answers: [{ id: 'free', selected: [] }] })
+    await expect.poll(() => page.locator('[data-question-key]').count(), { timeout: 10_000 }).toBe(0)
+  }, 60_000)
+
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'session.jsonl',
diff --git a/packages/client/ui-user-questions/README.i18n.yaml b/packages/client/ui-user-questions/README.i18n.yaml
index f90dd99881..0b88329d9f 100644
--- a/packages/client/ui-user-questions/README.i18n.yaml
+++ b/packages/client/ui-user-questions/README.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 packages/client/ui-user-questions/README.md
-README.md: 90af68315e28a3a89d7eaec1d9e3da1472318164
-README.zh.md: 33e47eb983c7ec832120a8be2188fb8afe4449fe
+README.md: 4c7c54ad3c9dd5a06f8bd0f5537044479e4ad7e2
+README.zh.md: 47d654bb7f687819558e8ef228664a815a4b46d0
diff --git a/packages/client/ui-user-questions/README.md b/packages/client/ui-user-questions/README.md
index 90af68315e..4c7c54ad3c 100644
--- a/packages/client/ui-user-questions/README.md
+++ b/packages/client/ui-user-questions/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Web question feature plugin: its browser half registers the `question` entry in the conversation-owned `conversation.composer` keyed slot. Its host half is empty on purpose — mounting `dsh-tool-ask-user` there put the tool in the registry's GLOBAL layer, which merges into every agent regardless of the preset that composed it, so a two-tool benchmark preset really presented three. Rendering a question is a host UI capability; having the tool is an agent capability, so the `tool-ask-user` row belongs to the presets that want it (and to the TUI composition, which has no presets).
 
-The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Both question shapes answer into a textarea over a hidden height mirror, so a long answer soft-wraps and grows the field in place; growth stops at eight lines and the field scrolls from there, keeping the choices the answer belongs to in view. Single-select choices advance immediately, Enter continues the flow and submits once every question is answered or skipped, and Shift+Enter breaks a line instead; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
+The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Both question shapes answer into a textarea over a hidden height mirror, so a long answer soft-wraps and grows the field in place; growth stops at six lines of text — the same count in both variants — and the field scrolls from there, keeping the choices the answer belongs to in view. Single-select choices advance immediately, Enter continues the flow and submits once every question is answered or skipped, and Shift+Enter breaks a line instead; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
 
 A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. The card claims a request only when it can send every answer that request allows: one question, the intent declared, the plan present as `detail`, the named approve label offered, and a binary single choice (at most one option besides approve, not multi-select). Anything else — no intent, a batch of several questions, a missing plan, an approve label naming no option, a third option, a multi-select decision — stays on the generic flow, which can express it. An intent changes the layout, never which answers are reachable.
 
diff --git a/packages/client/ui-user-questions/README.zh.md b/packages/client/ui-user-questions/README.zh.md
index 33e47eb983..47d654bb7f 100644
--- a/packages/client/ui-user-questions/README.zh.md
+++ b/packages/client/ui-user-questions/README.zh.md
@@ -4,7 +4,7 @@
 
 Web 提问功能插件：其浏览器侧把 `question` 条目注册到会话拥有的 `conversation.composer` 键控 slot 中。其主机侧刻意为空——在那里挂载 `dsh-tool-ask-user` 会把工具放进注册表的**全局层**，而全局层会并入每一个 agent（智能体），无论它由哪个 preset 组装，于是一个「两工具」的 benchmark preset 实际会呈现三个。渲染提问是宿主的 UI 能力，拥有该工具则是 agent 的能力，因此 `tool-ask-user` 行属于需要它的各个 preset（以及没有 preset 的 TUI 组装）。
 
-组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信任内容策略。限高卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。两种问题形状的自定义答案都写入一个带隐藏高度镜像的 textarea，因此长答案会软换行并就地把输入框撑高；增高到八行为止，此后由输入框自身滚动，使答案所属的选项仍留在视野内。选择单选选项后会立即前进；Enter 继续流程，所有问题均已回答或跳过后即提交，Shift+Enter 则改为换行；IME 组合输入期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
+组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信任内容策略。限高卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。两种问题形状的自定义答案都写入一个带隐藏高度镜像的 textarea，因此长答案会软换行并就地把输入框撑高；增高到六行文本为止——两种形状行数相同——此后由输入框自身滚动，使答案所属的选项仍留在视野内。选择单选选项后会立即前进；Enter 继续流程，所有问题均已回答或跳过后即提交，Shift+Enter 则改为换行；IME 组合输入期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
 
 若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review`——由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置——采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。卡片只在能够发出该请求允许的每一个答案时才接管：只有一个问题、声明了意图、计划以 `detail` 存在、提供了被指名的批准标签，且是二元单选（除批准外最多一个选项，且非多选）。其他任何情形——没有意图、一批含多个问题、缺少计划、批准标签未命中任何选项、出现第三个选项、多选决定——都留在能够表达它的通用流程上。意图改变的只是布局，从不改变可达的答案。
 
diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
index 995a01cbb1..3c554e22dc 100644
--- a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
+++ b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css
@@ -343,12 +343,18 @@
   overflow-wrap: anywhere;
 }
 
-/* The height ruler, never painted. Growth stops at 8 lines: the card body is
+/* The height ruler, never painted. Growth stops at 6 lines: the card body is
    capped at 520px and still owes that budget to the title, the option rows and
    the footer actions, so a long answer scrolls in the textarea instead of
-   pushing the choices it belongs to out of view. */
+   pushing the choices it belongs to out of view.
+   content-box overrides the card-wide border-box so the cap counts TEXT lines
+   in both variants: under border-box the block variant's 16px of vertical
+   padding eats two thirds of a line and the sixth one arrives as an 8px sliver.
+   Width is unaffected — a stretched grid item's used width comes from the
+   track, not from this box-sizing. */
 .fieldMirror {
-  max-height: 192px;
+  box-sizing: content-box;
+  max-height: 144px;
   overflow: hidden;
   visibility: hidden;
 }

From 26a8e6a555c42e15c7d8ceb0f3033774dbd02410 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 13 Aug 2026 14:29:59 +0800
Subject: [PATCH 19/34] feat(atomic-write): state the writer-lock wait limit
 per call

How long a contender waits is a property of the operation the lock holder
runs, not of the write protocol. The 2s default was sized for the
render-and-rename cycle every call site had; a credential mutation that
refreshes an expired token performs a network round trip while holding the
lock, and leaving the default in place would fail every other writer of that
file for the duration.

`withFileLock` takes an optional `waitMs`; the retry cadence stays fixed
because it governs how often a contender asks, which no caller varies. Every
existing call site keeps the default.
---
 packages/util/atomic-write/README.i18n.yaml   |  4 +-
 packages/util/atomic-write/README.md          |  2 +
 packages/util/atomic-write/README.zh.md       |  2 +
 packages/util/atomic-write/src/index.ts       | 36 +++++++++++++---
 .../atomic-write/tests/atomic-write.spec.ts   | 41 +++++++++++++++++++
 5 files changed, 77 insertions(+), 8 deletions(-)

diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index c54e974be8..98e35ef83a 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.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 packages/util/atomic-write/README.md
-README.md: 4d0b55291955c9d37f4788c7d37ad8e6ce728f70
-README.zh.md: c2d7f0b49fa123befbb663ac43862a40b4ef19b4
+README.md: 0e6501c0ae35bf26d7df67f28ce0ae24c85ecca6
+README.zh.md: 377f85f5c4aab74e8c04068b616de32a8ba063d6
diff --git a/packages/util/atomic-write/README.md b/packages/util/atomic-write/README.md
index 4d0b552919..0e6501c0ae 100644
--- a/packages/util/atomic-write/README.md
+++ b/packages/util/atomic-write/README.md
@@ -30,6 +30,8 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 
 `withFileLock` serializes the writers of one file across processes, for the read-render-commit cycles a bare atomic commit cannot make safe on its own. The lock is a `wx`-created `<filename>.lock` sibling, so readers never contend; waiters back off exponentially and fail with a timeout rather than block forever. `EEXIST` identifies contention directly; `EPERM` does so only when a fresh `lstat` confirms that the lock path exists, covering Windows exclusive-create behavior without hiding an unrelated permission failure. A contender never removes the existing lock: age cannot distinguish a crashed owner from a paused live writer.
 
+How long a contender waits is a property of the operation the holder runs, so it is stated per call through `waitMs`. The default is sized for file work alone; a holder whose cycle includes a network round trip — a credential mutation that refreshes an expired token — states a longer one, because leaving the default would fail every other writer of that file for the duration. The retry cadence stays fixed: it governs how often a contender asks, which no caller has a reason to vary.
+
 ## Model Experience
 
 None, as this is a pure filesystem primitive; nothing here reaches a model request.
diff --git a/packages/util/atomic-write/README.zh.md b/packages/util/atomic-write/README.zh.md
index c2d7f0b49f..377f85f5c4 100644
--- a/packages/util/atomic-write/README.zh.md
+++ b/packages/util/atomic-write/README.zh.md
@@ -30,6 +30,8 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 
 `withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。`EEXIST` 直接表示竞争；只有一次新的 `lstat` 确认锁路径存在时，`EPERM` 才表示竞争，从而兼容 Windows 的独占创建行为，又不掩盖无关的权限故障。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
 
+等待多久是持锁方所跑操作的属性，因此由每次调用经 `waitMs` 声明。默认值只按纯文件工作量级选定；若持锁方的循环包含一次网络往返——例如刷新过期 token 的凭据变更——就应声明更长的值，否则该文件的其他写入方会在这段时间内全部失败。退避节奏保持固定：它决定竞争者多久问一次，调用方没有理由改变它。
+
 ## 模型体验
 
 无：本包是纯文件系统原语，此处没有任何内容会到达模型请求。
diff --git a/packages/util/atomic-write/src/index.ts b/packages/util/atomic-write/src/index.ts
index 21c9de5f35..3e5764a329 100644
--- a/packages/util/atomic-write/src/index.ts
+++ b/packages/util/atomic-write/src/index.ts
@@ -78,14 +78,36 @@ async function isLockContention(error: unknown, lockPath: string): Promise<boole
 }
 
 /**
- * Writer-lock protocol constants. These are robustness invariants of the
- * cross-process write protocol, not deployment tunables: contention normally
- * resolves within the retry deadline, while expiry fails the contender without
- * guessing whether the existing lock still has an owner.
+ * Retry cadence for a contended lock. These stay robustness invariants of the
+ * cross-process write protocol rather than deployment tunables: they govern how
+ * often a contender asks, which no caller has a reason to vary.
  */
 const LOCK_RETRY_INITIAL_MS = 20
 const LOCK_RETRY_MAX_MS = 200
-const LOCK_TIMEOUT_MS = 2_000
+
+/**
+ * How long a contender waits when the caller states no limit — sized for the
+ * render-and-rename cycle every call site had when this package was written.
+ * Expiry fails the contender rather than guessing whether the existing lock
+ * still has an owner. How long is *worth* waiting is a property of the
+ * operation the lock holder runs, which is why {@link FileLockOptions.waitMs}
+ * exists; the value here is the floor for an operation that does file work
+ * alone.
+ */
+const DEFAULT_LOCK_WAIT_MS = 2_000
+
+/** Options for one {@link withFileLock} acquisition. */
+export interface FileLockOptions {
+  /**
+   * Maximum time to wait for the lock, in milliseconds. State one when the
+   * holder's operation legitimately runs longer than file work — a credential
+   * mutation that refreshes a token performs a network round trip while
+   * holding the lock, and leaving the default in place would fail every other
+   * writer of the same file for the duration. Waiting is productive: a
+   * contender that acquires the lock afterwards re-reads the committed state.
+   */
+  waitMs?: number
+}
 
 /**
  * Hold the cross-process writer lock for `filename` around one operation. The
@@ -100,14 +122,16 @@ const LOCK_TIMEOUT_MS = 2_000
  * action. The parent directory must exist.
  * @param filename - the file whose writers this lock serializes.
  * @param operation - the read-render-commit cycle to run while holding the lock.
+ * @param options - acquisition options; omitted waits {@link DEFAULT_LOCK_WAIT_MS}.
  * @returns the operation's result; the lock releases on both outcomes.
  */
 export async function withFileLock<T>(
   filename: string,
   operation: () => Promise<T>,
+  options?: FileLockOptions,
 ): Promise<T> {
   const lockPath = `${filename}.lock`
-  const deadline = Date.now() + LOCK_TIMEOUT_MS
+  const deadline = Date.now() + (options?.waitMs ?? DEFAULT_LOCK_WAIT_MS)
   let delay = LOCK_RETRY_INITIAL_MS
   for (;;) {
     try {
diff --git a/packages/util/atomic-write/tests/atomic-write.spec.ts b/packages/util/atomic-write/tests/atomic-write.spec.ts
index 42cbd287c0..683abe51bc 100644
--- a/packages/util/atomic-write/tests/atomic-write.spec.ts
+++ b/packages/util/atomic-write/tests/atomic-write.spec.ts
@@ -28,6 +28,18 @@ async function scratch(): Promise<string> {
   return mkdtemp(join(tmpdir(), 'dsh-atomic-write-'))
 }
 
+/** Resolve once the lockfile exists, so contention is measured against a held lock. */
+async function waitForLock(lockPath: string): Promise<void> {
+  for (;;) {
+    try {
+      await stat(lockPath)
+      return
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 5))
+    }
+  }
+}
+
 describe('writeFileAtomic', () => {
   it('creates the file and its parents with exactly the stated mode', async () => {
     const dir = await scratch()
@@ -105,4 +117,33 @@ describe('withFileLock', () => {
     })).rejects.toThrow(/ENOENT|ENOTDIR|not a directory/i)
     expect(called).toBe(false)
   })
+
+  it('waits for the caller-stated limit rather than the protocol default', async () => {
+    // An operation whose work includes a network round trip legitimately holds
+    // the lock far longer than the render-and-rename the default was sized
+    // for. The limit is per call so one such operation cannot fail every other
+    // writer of the same file, and a caller that states a short one still
+    // fails fast.
+    const dir = await scratch()
+    const target = join(dir, 'document')
+    let release = (): void => {}
+    const held = new Promise<void>((resolve) => { release = resolve })
+    const holder = withFileLock(target, () => held)
+    // The holder owns the lock once its lockfile exists; contending before
+    // that would measure nothing.
+    await waitForLock(`${target}.lock`)
+
+    // Elapsed time is the assertion that distinguishes a honoured limit from
+    // the ignored argument: without it the contender simply waits out the
+    // protocol default and fails with the same message.
+    const startedAt = Date.now()
+    await expect(withFileLock(target, async () => 'impatient', { waitMs: 50 }))
+      .rejects.toThrow(/timed out waiting for the writer lock/)
+    expect(Date.now() - startedAt).toBeLessThan(1_000)
+
+    const patient = withFileLock(target, async () => 'patient', { waitMs: 10_000 })
+    release()
+    await holder
+    expect(await patient).toBe('patient')
+  })
 })

From 86a9f8c8620a29544adb7510bd0a452cda377fe4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 13 Aug 2026 15:00:09 +0800
Subject: [PATCH 20/34] feat(credentials): store durable credential records
 beside references
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The seam answered one question — what is behind this environment-variable
name — and that shape cannot hold what an authorization grant is: a
multi-field, rotating value keyed by a provider id rather than by a POSIX
identifier. The Models page already works around the gap by inventing a
synthetic environment name (`MINIMAX_CN_API_KEY`) for a route the user added
by hand, because the store's key must look like one.

`CredentialKey` is `<scope>/<id>`, where the scope is the owning plugin's
registered name. The owner is in the key because a `grant` payload is written
in its owner's format: two plugins serving the same provider name would
otherwise read each other's payload, and a record left by an uninstalled
plugin could not be told from a live one. The `/` also keeps the grammar
disjoint from `CredentialRef`, so the key spaces cannot collide.

`CredentialRecord` is `api-key` (key and/or provider environment values) or
`grant` (an opaque, owner-owned payload). The asymmetry is deliberate: an api
key is the harness's own data, a grant is a package it carries for someone
else. `modifyRecord` is the only write path because a correct write depends
on the current value — a token refresh is read-decide-replace under one
cross-process lock, without which two processes rotating one refresh token
lose whichever wrote first.

`.credentials.yaml` becomes a versioned two-section document. The pre-release
flat layout is refused by name, with the entry count and the one edit needed,
rather than read as an empty store — which would surface as an authentication
failure on the first request instead of at load. A grant payload is admitted
in both directions, so a value the document could not read back exactly as
written is refused rather than stored lossily.
---
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   2 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/event-producer-consumer.i18n.yaml        |   4 +-
 docs/event-producer-consumer.md               |   3 +-
 docs/event-producer-consumer.zh.md            |   3 +-
 docs/subsystems/credentials.i18n.yaml         |   4 +-
 docs/subsystems/credentials.md                |  76 +++-
 docs/subsystems/credentials.zh.md             |  76 +++-
 .../credentials-local/README.i18n.yaml        |   4 +-
 .../credentials/credentials-local/README.md   |  30 +-
 .../credentials-local/README.zh.md            |  30 +-
 .../credentials-local/src/index.ts            | 400 ++++++++++++++++--
 .../credentials-local/tests/drain.spec.ts     |  32 +-
 .../credentials-local/tests/local.spec.ts     |  80 ++--
 .../credentials-local/tests/records.spec.ts   | 331 +++++++++++++++
 .../tests/review-fixes.spec.ts                |   7 +-
 .../credentials-local/tests/watcher.spec.ts   |  28 +-
 .../credentials/credentials/README.i18n.yaml  |   4 +-
 packages/credentials/credentials/README.md    |  28 +-
 packages/credentials/credentials/README.zh.md |  28 +-
 packages/credentials/credentials/src/index.ts | 172 +++++++-
 packages/credentials/credentials/src/types.ts |  66 ++-
 .../credentials/credentials/tests/memory.ts   |  45 +-
 .../extensions/tool-cordis/src/api-catalog.ts |  65 ++-
 .../apiproxy/tests/api-proxy-config.spec.ts   |  35 +-
 scripts/gen-cordis-catalog.ts                 |   4 +
 27 files changed, 1434 insertions(+), 129 deletions(-)
 create mode 100644 packages/credentials/credentials-local/tests/records.spec.ts

diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index e3de095ad5..cca52f4aee 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: d25843091d453687bad5035c49bcb200cb03fff2
-config-catalog.zh.md: 1cc3002799afc10ca84f74044c7b28f91490ffa3
+config-catalog.md: f4e813238b89ef32c097f9ee274347e37ba11efc
+config-catalog.zh.md: 4eec1d6d172365d9a16f420a639d09a3bbae1147
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index d25843091d..f4e813238b 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -567,7 +567,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:63`](../packages/credentials/credentials-local/src/index.ts)
 
 <a id="deepseek-aidsh-e2b"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 1cc3002799..4eec1d6d17 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -569,7 +569,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
+来源：[`packages/credentials/credentials-local/src/index.ts:63`](../packages/credentials/credentials-local/src/index.ts)
 
 <a id="deepseek-aidsh-e2b"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 77c2dd6536..f34d32a007 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: d3901b1ddc7d99d4960324ab7459388fa4612bbe
-event-producer-consumer.zh.md: 346a293a226719f781a9587eb0adefcf3f6bed08
+event-producer-consumer.md: 11dbce044cdbcae1f7ee49a6b5b4d0d369f80bf8
+event-producer-consumer.zh.md: ef9b7ead7e9951b68cbf84f6031d60411e46480f
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index d3901b1ddc..11dbce044c 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -29,7 +29,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
-| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:29`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | - |
+| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 346a293a22..ef9b7ead7e 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -31,7 +31,8 @@
 | `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
-| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:29`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | - |
+| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 5015fb84a6..68696cb3d5 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: fe480c4311dd5f7e0b1f26996ad53d5f0cd79e7d
-credentials.zh.md: 1d8712f8b01a6d6b92e2036172c151d22728f2a4
+credentials.md: 59ab18d3f9fb9db7668f766484fc6a7ac7d3c950
+credentials.zh.md: 5b941c7f360bb3904f91a16bdfd862f5d13d6b39
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index fe480c4311..59ab18d3f9 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -61,7 +61,11 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
 
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+Abstract credential service over two key spaces that answer two questions.
+
+A CredentialRef answers "what is behind this environment-variable name", layered over the process environment, the provider-managed store, and `.env` files. One seam-wide rule binds that half: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+A CredentialKey answers "what credential does this plugin hold for this id". Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and modifyRecord is the only write path because a correct write depends on the current value (a token refresh is read-decide-replace under one lock).
 
 ```ts cordis-catalog
 /**
@@ -99,14 +103,80 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
  * @param ref - the reference to remove.
  */
 abstract unset(ref: CredentialRef): Promise<void>
+
+/**
+ * Read one stored record. The value is returned as its owner wrote it; a
+ * {@link GrantRecord} payload is not interpreted on the way out.
+ * @param key - the record to read.
+ * @returns the record, or `undefined` while none is stored.
+ */
+abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>
+
+/**
+ * Describe one record for configuration surfaces without exposing its value.
+ * @param key - the record to describe.
+ * @returns presence, discriminant, and writability.
+ */
+abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>
+
+/**
+ * Enumerate every stored record's address and tag. Unlike the reference
+ * half, which has no enumeration because configuration surfaces learn which
+ * references exist from settings schemas, records have no such discovery
+ * path: a surface that cannot list them cannot show what a user is
+ * authorized for, nor find an orphan left by an uninstalled plugin.
+ * @returns every stored record, values excluded.
+ */
+abstract listRecords(): Promise<readonly CredentialRecordEntry[]>
+
+/**
+ * Serialized read-modify-write over one record — the only write path.
+ * `mutate` sees the record as it stands at the moment the write is
+ * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+ * holds across processes where the backing store supports it, which is what
+ * makes a token refresh safe: two processes rotating one refresh token
+ * concurrently would otherwise lose whichever wrote first.
+ * @param key - the record to modify.
+ * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+ * @returns the record after the write, or the current one when `mutate` declined.
+ */
+abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>, ): Promise<CredentialRecord | undefined>
+
+/**
+ * Remove one record; removing an absent record is a no-op.
+ * @param key - the record to remove.
+ */
+abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
 
+<a id="credentialsrecord-updated--emit"></a>
+
+#### `credentials/record-updated` — emit
+
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.
+
+```ts cordis-catalog
+/**
+ * Committed change to a stored credential record: a `modifyRecord` that
+ * wrote, a `deleteRecord` that removed, or an external edit observed in
+ * storage. Separate from `credentials/updated` because the two key
+ * grammars are disjoint — a listener that received both on one event could
+ * not tell which space a subject belongs to. Listener failures are
+ * contained on the same terms as `credentials/updated`.
+ * @param key - the record whose stored value changed.
+ * @mode emit
+ */
+'credentials/record-updated'(key: CredentialKey): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts:87`](../../packages/credentials/credentials/src/types.ts)
+
 <a id="credentialsupdated--emit"></a>
 
 #### `credentials/updated` — emit
@@ -129,5 +199,5 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
 'credentials/updated'(ref: CredentialRef): void
 ```
 
-Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+Source: [`packages/credentials/credentials/src/types.ts:75`](../../packages/credentials/credentials/src/types.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 1d8712f8b0..5b941c7f36 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -61,7 +61,11 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
 
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+Abstract credential service over two key spaces that answer two questions.
+
+A CredentialRef answers "what is behind this environment-variable name", layered over the process environment, the provider-managed store, and `.env` files. One seam-wide rule binds that half: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+A CredentialKey answers "what credential does this plugin hold for this id". Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and modifyRecord is the only write path because a correct write depends on the current value (a token refresh is read-decide-replace under one lock).
 
 ```ts cordis-catalog
 /**
@@ -99,14 +103,80 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
  * @param ref - the reference to remove.
  */
 abstract unset(ref: CredentialRef): Promise<void>
+
+/**
+ * Read one stored record. The value is returned as its owner wrote it; a
+ * {@link GrantRecord} payload is not interpreted on the way out.
+ * @param key - the record to read.
+ * @returns the record, or `undefined` while none is stored.
+ */
+abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>
+
+/**
+ * Describe one record for configuration surfaces without exposing its value.
+ * @param key - the record to describe.
+ * @returns presence, discriminant, and writability.
+ */
+abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>
+
+/**
+ * Enumerate every stored record's address and tag. Unlike the reference
+ * half, which has no enumeration because configuration surfaces learn which
+ * references exist from settings schemas, records have no such discovery
+ * path: a surface that cannot list them cannot show what a user is
+ * authorized for, nor find an orphan left by an uninstalled plugin.
+ * @returns every stored record, values excluded.
+ */
+abstract listRecords(): Promise<readonly CredentialRecordEntry[]>
+
+/**
+ * Serialized read-modify-write over one record — the only write path.
+ * `mutate` sees the record as it stands at the moment the write is
+ * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+ * holds across processes where the backing store supports it, which is what
+ * makes a token refresh safe: two processes rotating one refresh token
+ * concurrently would otherwise lose whichever wrote first.
+ * @param key - the record to modify.
+ * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+ * @returns the record after the write, or the current one when `mutate` declined.
+ */
+abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>, ): Promise<CredentialRecord | undefined>
+
+/**
+ * Remove one record; removing an absent record is a no-op.
+ * @param key - the record to remove.
+ */
+abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:60`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
 
+<a id="credentialsrecord-updated--emit"></a>
+
+#### `credentials/record-updated` — emit
+
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.
+
+```ts cordis-catalog
+/**
+ * Committed change to a stored credential record: a `modifyRecord` that
+ * wrote, a `deleteRecord` that removed, or an external edit observed in
+ * storage. Separate from `credentials/updated` because the two key
+ * grammars are disjoint — a listener that received both on one event could
+ * not tell which space a subject belongs to. Listener failures are
+ * contained on the same terms as `credentials/updated`.
+ * @param key - the record whose stored value changed.
+ * @mode emit
+ */
+'credentials/record-updated'(key: CredentialKey): void
+```
+
+Source: [`packages/credentials/credentials/src/types.ts:87`](../../packages/credentials/credentials/src/types.ts)
+
 <a id="credentialsupdated--emit"></a>
 
 #### `credentials/updated` — emit
@@ -129,5 +199,5 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
 'credentials/updated'(ref: CredentialRef): void
 ```
 
-Source: [`packages/credentials/credentials/src/types.ts:29`](../../packages/credentials/credentials/src/types.ts)
+Source: [`packages/credentials/credentials/src/types.ts:75`](../../packages/credentials/credentials/src/types.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index df8fd03313..ba58baf497 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/README.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 packages/credentials/credentials-local/README.md
-README.md: 63895d34fe8396d55c1d6ef29b3e3d9a9dc17264
-README.zh.md: 3c60fb7bbf06a0ae9ec905f36a5c543c2fb6af1b
+README.md: cc9c63bd689f3e5dd028add77fb72ca9eb541623
+README.zh.md: 2368d5ff7db3c515e3826d53efad2c35768328f0
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 63895d34fe..cc9c63bd68 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -28,14 +28,36 @@ Under the product CLI, resolution reads the launcher's frozen [environment snaps
 
 ## The document
 
-A YAML mapping of credential reference to value, and nothing else:
+A versioned YAML document with one section per key space, and nothing else:
 
 ```yaml
-DEEPSEEK_API_KEY: sk-…
-OPENAI_API_KEY: sk-…
+version: 1
+
+refs:
+  DEEPSEEK_API_KEY: sk-…
+  OPENAI_API_KEY: sk-…
+
+records:
+  llm-pi-ai/openai-codex:
+    kind: grant
+    payload:                    # written verbatim; this provider does not interpret it
+      type: oauth
+      access: eyJhbGciOi…
+      refresh: rft_9f8e7d…
+      expires: 1786000000000
+  llm-pi-ai/amazon-bedrock:
+    kind: api-key               # environment values, no key: this route uses an AWS profile
+    env:
+      AWS_PROFILE: prod
+  llm-pi-ai/amazon-bedrock-dev:
+    kind: api-key               # neither: the owner confirmed the ambient credential chain
 ```
 
-The document holds credentials only, so every deviation is a rejection rather than a skipped entry — a silently ignored key would read as "the secret I stored has no effect". A non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail: loud at boot, and warn-and-keep-the-last-good-snapshot on a live reload. There is no `version` field and no wrapper level; the format is the mapping.
+The document holds credentials only, so every deviation is a rejection rather than a skipped entry — a silently ignored key would read as "the credential I stored has no effect". A non-mapping root, an unknown top-level key, a key that is not addressable in its space, a wrong-typed value, an empty string, an unknown record tag or field, a duplicate key, and malformed YAML all fail: loud at boot, and warn-and-keep-the-last-good-snapshot on a live reload.
+
+A `grant` payload must survive a JSON round trip, enforced in both directions. YAML spells values JSON has none for — `.inf`, alias cycles — and an owner may hand over a `Date` or a `bigint`; either way the store refuses rather than saving something it could not read back exactly as written.
+
+The pre-release layout was a flat mapping with no `version`. It is refused by name, with the entry count and the one edit needed (`version: 1`, nest under `refs:`) — never read as an empty store, which would surface as an authentication failure on the first request instead of at load.
 
 Writes patch the parsed document rather than rebuilding it, so comments and the formatting of every untouched entry survive. A comment directly above an entry is that entry's annotation and is removed with it. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten. An on-disk document that no longer parses fails the write instead of overwriting content the provider could not understand.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 3c60fb7bbf..2368d5ff7d 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -28,14 +28,36 @@
 
 ## 文档本身
 
-一个从凭据引用到值的 YAML mapping，除此之外别无他物：
+一个带版本的 YAML 文档，每个键空间一个分节，除此之外别无他物：
 
 ```yaml
-DEEPSEEK_API_KEY: sk-…
-OPENAI_API_KEY: sk-…
+version: 1
+
+refs:
+  DEEPSEEK_API_KEY: sk-…
+  OPENAI_API_KEY: sk-…
+
+records:
+  llm-pi-ai/openai-codex:
+    kind: grant
+    payload:                    # written verbatim; this provider does not interpret it
+      type: oauth
+      access: eyJhbGciOi…
+      refresh: rft_9f8e7d…
+      expires: 1786000000000
+  llm-pi-ai/amazon-bedrock:
+    kind: api-key               # environment values, no key: this route uses an AWS profile
+    env:
+      AWS_PROFILE: prod
+  llm-pi-ai/amazon-bedrock-dev:
+    kind: api-key               # neither: the owner confirmed the ambient credential chain
 ```
 
-该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的密钥没有生效」。非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败：启动时明确报错，运行期热重载则告警并保留最后可用快照。没有 `version` 字段，也没有包装层；格式就是这个 mapping。
+该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的凭据没有生效」。非 mapping 的根、未知的顶层键、在其空间中不可寻址的键、类型不符的值、空字符串、未知的记录标签或字段、重复键以及格式错误的 YAML 全部失败：启动时明确报错，运行期热重载则告警并保留最后可用快照。
+
+`grant` 的 payload 必须能经受 JSON 往返，读写两个方向都强制。YAML 能拼写出 JSON 没有的值——`.inf`、别名环——拥有者也可能递来 `Date` 或 `bigint`；无论哪种，存储都选择拒绝，而不是存下一个自己无法逐字读回的东西。
+
+发布前的旧布局是没有 `version` 的扁平 mapping。它会被指名拒绝，并给出条目数与唯一需要做的编辑（`version: 1`，条目下沉到 `refs:`）——绝不当作空存储读过去，否则它会以第一次请求认证失败的形式出现，而不是在加载时。
 
 写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖提供方读不懂的内容。
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index 4e8592760e..e394d8ade0 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -40,12 +40,20 @@ import z from '@deepseek-ai/schemastery'
 import { watch as chokidarWatch } from 'chokidar'
 import { mkdir, readFile, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
-import { Document, parseDocument, type YAMLError } from 'yaml'
+import { Document, isMap, isScalar, parseDocument, type YAMLError } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
-import { CredentialProvider, credentialRef } from '@deepseek-ai/dsh-credentials'
-import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+import { CredentialProvider, credentialRef, parseCredentialKey } from '@deepseek-ai/dsh-credentials'
+import type {
+  CredentialInfo,
+  CredentialKey,
+  CredentialRecord,
+  CredentialRecordEntry,
+  CredentialRecordInfo,
+  CredentialRef,
+  ResolvedCredential,
+} from '@deepseek-ai/dsh-credentials'
 import type { LaunchEnvironmentEntry } from '@deepseek-ai/dsh-launch-environment'
 
 /** Basename of the credentials document inside the harness home. */
@@ -87,6 +95,18 @@ export function resolveSpec(config: Config): ResolvedSpec {
 /** Permission bits outside the owner; a credentials document must have none of them. */
 const GROUP_OTHER_BITS = 0o077
 
+/**
+ * How long a record write waits for the cross-process writer lock. A record
+ * mutation runs its caller's decision while holding the lock, and for the
+ * operation this half exists to serve — an owner refreshing an expired token —
+ * that decision includes a network round trip. The file-work default would
+ * fail every other writer of this document for its duration. Like the retry
+ * cadence in `dsh-atomic-write`, this is a robustness bound of the write
+ * protocol rather than a deployment choice: it is sized by what a provider
+ * request costs, which no deployment varies.
+ */
+const RECORD_LOCK_WAIT_MS = 30_000
+
 /**
  * Reject a credentials document other OS users can read, before its contents
  * are read at all. The provider creates and replaces the file at `0600`, but a
@@ -139,19 +159,29 @@ function describeYamlError(error: YAMLError): string {
   return `${error.code}${where}`
 }
 
+/** The document layout this build reads and writes. */
+export const DOCUMENT_VERSION = 1
+
+/** One parsed credentials document: the two key spaces it stores, keyed as written. */
+export interface CredentialsDocument {
+  /** Reference entries, keyed by {@link CredentialRef}. */
+  refs: Map<string, string>
+  /** Stored records, keyed by {@link CredentialKey}. */
+  records: Map<string, CredentialRecord>
+}
+
 /**
- * Parse one credentials document into its entries. The document is a strict
- * mapping of {@link CredentialRef} to non-empty string: a non-mapping root, a
- * key that is not a POSIX identifier, a non-string value, and an empty string
- * are all rejected rather than skipped, because this file holds nothing but
- * credentials and a silently ignored entry reads as "the key I stored has no
- * effect". Duplicate keys surface as parser errors. An empty document is an
- * empty store.
+ * Parse one credentials document. Everything is rejected rather than skipped —
+ * an unversioned root, an unknown top-level key, a key that is not addressable,
+ * a wrong-typed value, an unknown record tag or field — because this file holds
+ * nothing but credentials and a silently ignored entry reads as "the credential
+ * I stored has no effect". Duplicate keys surface as parser errors. An empty
+ * document is an empty store and needs no version.
  * @param text - the document's text.
  * @param filename - absolute path, quoted in errors.
- * @returns the parsed entries, keyed by reference.
+ * @returns the parsed references and records.
  */
-export function parseCredentialsDocument(text: string, filename: string): Map<string, string> {
+export function parseCredentialsDocument(text: string, filename: string): CredentialsDocument {
   // `prettyErrors` is on only for `linePos`; `error.message` is never used,
   // because the parser quotes the offending source line and in this document
   // that line is a secret. Only the code and position leave this function, and
@@ -164,10 +194,38 @@ export function parseCredentialsDocument(text: string, filename: string): Map<st
   }
   const root: unknown = document.toJS() ?? {}
   if (typeof root !== 'object' || root === null || Array.isArray(root)) {
-    throw new TypeError(`credentials-local: ${filename} must be a mapping of credential reference to value`)
+    throw new TypeError(`credentials-local: ${filename} must be a mapping`)
   }
+  const fields = root as Record<string, unknown>
+  const keys = Object.keys(fields)
+  // An empty (or comment-only) document is the empty store and needs no
+  // version: there is nothing in it a later layout could have meant.
+  if (keys.length === 0) return { refs: new Map(), records: new Map() }
+  if (!('version' in fields)) {
+    throw new Error(
+      `credentials-local: ${filename} uses the pre-release flat layout. Add \`version: ${DOCUMENT_VERSION}\``
+      + ` and nest the existing ${keys.length} ${keys.length === 1 ? 'entry' : 'entries'} under \`refs:\`.`
+      + ' No values need to change.',
+    )
+  }
+  if (fields['version'] !== DOCUMENT_VERSION) {
+    throw new Error(
+      `credentials-local: ${filename} declares version ${JSON.stringify(fields['version'])};`
+      + ` this build reads version ${DOCUMENT_VERSION}`,
+    )
+  }
+  for (const key of keys) {
+    if (key !== 'version' && key !== 'refs' && key !== 'records') {
+      throw new Error(`credentials-local: unknown top-level key "${key}" in ${filename}`)
+    }
+  }
+  return { refs: parseRefs(fields['refs'], filename), records: parseRecords(fields['records'], filename) }
+}
+
+/** Admit a `refs` section: POSIX-identifier keys over non-empty string values. */
+function parseRefs(section: unknown, filename: string): Map<string, string> {
   const entries = new Map<string, string>()
-  for (const [key, value] of Object.entries(root as Record<string, unknown>)) {
+  for (const [key, value] of Object.entries(asSection(section, 'refs', filename))) {
     // credentialRef throws on anything that is not a POSIX identifier, which
     // is exactly the constraint a stored reference must satisfy to be
     // addressable through the seam.
@@ -185,24 +243,209 @@ export function parseCredentialsDocument(text: string, filename: string): Map<st
   return entries
 }
 
+/** Admit a `records` section: `<scope>/<id>` keys over tagged record mappings. */
+function parseRecords(section: unknown, filename: string): Map<string, CredentialRecord> {
+  const entries = new Map<string, CredentialRecord>()
+  for (const [key, value] of Object.entries(asSection(section, 'records', filename))) {
+    parseCredentialKey(key)
+    entries.set(key, parseRecord(key, value, filename))
+  }
+  return entries
+}
+
+/** One section of the document as a plain mapping; absent and null both mean empty. */
+function asSection(section: unknown, name: string, filename: string): Record<string, unknown> {
+  if (section === undefined || section === null) return {}
+  if (typeof section !== 'object' || Array.isArray(section)) {
+    throw new TypeError(`credentials-local: "${name}" in ${filename} must be a mapping`)
+  }
+  return section as Record<string, unknown>
+}
+
+/** Admit one record entry, rejecting an unknown tag or field rather than dropping it. */
+function parseRecord(key: string, value: unknown, filename: string): CredentialRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`credentials-local: record "${key}" in ${filename} must be a mapping`)
+  }
+  const fields = value as Record<string, unknown>
+  const kind = fields['kind']
+  if (kind === 'api-key') {
+    assertFields(key, fields, ['kind', 'key', 'env'], filename)
+    const apiKey = fields['key']
+    if (apiKey !== undefined && (typeof apiKey !== 'string' || apiKey.length === 0)) {
+      throw new TypeError(`credentials-local: record "${key}" in ${filename} has a non-string or empty key`)
+    }
+    const env = parseRecordEnv(key, fields['env'], filename)
+    return {
+      kind: 'api-key',
+      ...apiKey === undefined ? {} : { key: apiKey },
+      ...env === undefined ? {} : { env },
+    }
+  }
+  if (kind === 'grant') {
+    assertFields(key, fields, ['kind', 'payload'], filename)
+    if (!('payload' in fields)) {
+      throw new Error(`credentials-local: record "${key}" in ${filename} has no payload`)
+    }
+    assertJsonValue(`record "${key}" payload in ${filename}`, fields['payload'], new Set())
+    return { kind: 'grant', payload: fields['payload'] }
+  }
+  if (kind === undefined) throw new Error(`credentials-local: record "${key}" in ${filename} has no kind`)
+  throw new Error(`credentials-local: record "${key}" in ${filename} has unknown kind ${JSON.stringify(kind)}`)
+}
+
+/** Reject a field the tag does not define, so a typo is not silently dropped. */
+function assertFields(key: string, fields: Record<string, unknown>, allowed: string[], filename: string): void {
+  for (const field of Object.keys(fields)) {
+    if (!allowed.includes(field)) {
+      throw new Error(`credentials-local: record "${key}" in ${filename} has unknown field "${field}"`)
+    }
+  }
+}
+
+/** Admit an api-key record's provider environment: POSIX names over non-empty strings. */
+function parseRecordEnv(key: string, env: unknown, filename: string): Record<string, string> | undefined {
+  if (env === undefined) return undefined
+  if (typeof env !== 'object' || env === null || Array.isArray(env)) {
+    throw new TypeError(`credentials-local: record "${key}" in ${filename} has a non-mapping env`)
+  }
+  const parsed: Record<string, string> = {}
+  for (const [name, value] of Object.entries(env as Record<string, unknown>)) {
+    credentialRef(name)
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new TypeError(
+        `credentials-local: record "${key}" env "${name}" in ${filename} must be a non-empty string`,
+      )
+    }
+    parsed[name] = value
+  }
+  return parsed
+}
+
 /**
- * Render the next document text with one reference set or deleted. Editing
- * the parsed document rather than rebuilding it keeps comments and the
- * formatting of every untouched entry; an absent document starts a fresh one.
+ * Reject a payload that cannot survive a JSON round trip, on the way in and on
+ * the way out. The seam promises owners their payload comes back exactly as
+ * written, and both directions can break that: a document may spell `.inf` or
+ * an alias cycle, and an owner may hand over a `Date`, a class instance, or a
+ * `bigint` that this document has no faithful spelling for. Neither the value
+ * nor any nested value is quoted in a diagnostic.
+ * @param where - the subject named in a diagnostic, already free of any value.
+ * @param value - the payload or nested value to admit.
+ * @param seen - objects on the current path, for cycle detection.
+ * @throws TypeError naming `where` when the value cannot round-trip.
+ */
+function assertJsonValue(where: string, value: unknown, seen: Set<object>): void {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return
+    throw new TypeError(`credentials-local: ${where} holds a non-finite number`)
+  }
+  if (typeof value === 'object') {
+    if (seen.has(value)) throw new TypeError(`credentials-local: ${where} is cyclic`)
+    if (Object.getPrototypeOf(value) === Object.prototype || Array.isArray(value)) {
+      seen.add(value)
+      for (const nested of Object.values(value)) assertJsonValue(where, nested, seen)
+      seen.delete(value)
+      return
+    }
+  }
+  throw new TypeError(`credentials-local: ${where} holds a value JSON cannot represent`)
+}
+
+/**
+ * The comment-preserving mutable tree one edit renders from. Editing the
+ * parsed document rather than rebuilding it keeps comments and the formatting
+ * of every untouched entry; an absent document starts a fresh one.
+ * @param text - the current document text, `undefined` while the file is absent.
+ * @returns the tree to edit, carrying this build's version stamp.
+ */
+function mutableDocument(text: string | undefined): Document {
+  // `text` only ever caches content that parsed successfully, so this re-parse
+  // for the mutable comment-preserving tree cannot fail.
+  const document = text === undefined ? new Document({}) : parseDocument(text)
+  // Stamped on every edit so a document this provider creates is readable by
+  // the same parser that admitted the one it edits; an existing stamp is
+  // rewritten to the identical value.
+  document.setIn(['version'], DOCUMENT_VERSION)
+  return document
+}
+
+/**
+ * Render the next document text with one reference set or deleted.
  * @param text - the current document text, `undefined` while the file is absent.
  * @param ref - the reference to write.
  * @param value - the new value, or `undefined` to delete the key.
  * @returns the text to persist.
  */
-function renderDocument(text: string | undefined, ref: CredentialRef, value: string | undefined): string {
-  // `text` only ever caches content that parsed successfully, so this re-parse
-  // for the mutable comment-preserving tree cannot fail.
-  const document = text === undefined ? new Document({}) : parseDocument(text)
-  if (value === undefined) document.deleteIn([ref])
-  else document.setIn([ref], value)
+function renderRef(text: string | undefined, ref: CredentialRef, value: string | undefined): string {
+  const document = mutableDocument(text)
+  if (value === undefined) deleteSectionEntry(document, 'refs', ref)
+  else document.setIn(['refs', ref], value)
   return document.toString()
 }
 
+/**
+ * Render the next document text with one record written or deleted. The record
+ * node is replaced wholesale rather than edited field by field: records are
+ * machine-written, so there is no hand formatting inside one to preserve.
+ * @param text - the current document text, `undefined` while the file is absent.
+ * @param key - the record to write.
+ * @param record - the new record, or `undefined` to delete it.
+ * @returns the text to persist.
+ */
+function renderRecord(text: string | undefined, key: CredentialKey, record: CredentialRecord | undefined): string {
+  const document = mutableDocument(text)
+  if (record === undefined) deleteSectionEntry(document, 'records', key)
+  else document.setIn(['records', key], record)
+  return document.toString()
+}
+
+/**
+ * Remove one entry from a section, taking its annotation with it. A comment
+ * block written above a section's first entry annotates that entry, but the
+ * parser attaches it to the section's map rather than to the pair — leaving it
+ * behind would move it onto whichever entry became first, which reads as an
+ * annotation of a credential nobody wrote it for.
+ * @param document - the mutable tree being edited.
+ * @param section - the section holding the entry.
+ * @param key - the entry to remove.
+ */
+function deleteSectionEntry(document: Document, section: 'refs' | 'records', key: string): void {
+  const map: unknown = document.get(section, true)
+  /* v8 ignore next -- both callers render a delete only for an entry they just
+     found in the parsed snapshot, so the section it lives in is always a map;
+     the guard is what narrows `get`'s `unknown`. */
+  if (isMap(map)) {
+    const first = map.items[0]
+    /* v8 ignore next -- a map that holds the entry has a first item, and the
+       parser admits only scalar keys, so only the identity test can be false. */
+    if (first !== undefined && isScalar(first.key) && first.key.value === key) {
+      map.commentBefore = null
+    }
+  }
+  document.deleteIn([section, key])
+}
+
+/**
+ * Structural equality over two admitted JSON values. Records reach this after
+ * {@link assertJsonValue}, so the walk meets only JSON shapes; key order is
+ * ignored because an external editor may reorder a record's fields without
+ * changing what it stores.
+ * @param left - one value.
+ * @param right - the other value.
+ * @returns whether the two carry the same JSON content.
+ */
+function sameJsonValue(left: unknown, right: unknown): boolean {
+  if (left === right) return true
+  if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) return false
+  if (Array.isArray(left) !== Array.isArray(right)) return false
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  if (leftKeys.length !== rightKeys.length) return false
+  return leftKeys.every(key => key in right
+    && sameJsonValue((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]))
+}
+
 /** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
 export class LocalCredentialProvider extends CredentialProvider {
   /* jscpd:ignore-start -- deliberate config-surface and lifecycle symmetry with
@@ -222,8 +465,10 @@ export class LocalCredentialProvider extends CredentialProvider {
    * which is also the self-write suppression.
    */
   private text: string | undefined
-  /** Parsed document snapshot; replaced wholesale on every reload. */
+  /** Parsed reference snapshot; replaced wholesale on every reload. */
   private values = new Map<string, string>()
+  /** Parsed record snapshot; replaced wholesale on every reload. */
+  private records = new Map<string, CredentialRecord>()
   /**
    * Single exclusive operation chain: watcher reloads and line edits run one
    * at a time in queue order (settled tail), so an edit can never render from
@@ -341,6 +586,81 @@ export class LocalCredentialProvider extends CredentialProvider {
     await this.write(ref, undefined)
   }
 
+  override readRecord(key: CredentialKey): Promise<CredentialRecord | undefined> {
+    return Promise.resolve(this.records.get(key))
+  }
+
+  override describeRecord(key: CredentialKey): Promise<CredentialRecordInfo> {
+    const stored = this.records.get(key)
+    // Presence is the whole fact here: no layer ranks above this document for
+    // a record, so nothing can shadow one, and an api-key record carrying
+    // neither a key nor environment values is a deliberate statement rather
+    // than a blank.
+    if (stored === undefined) return Promise.resolve({ configured: false, writable: true })
+    return Promise.resolve({ configured: true, kind: stored.kind, writable: true })
+  }
+
+  override listRecords(): Promise<readonly CredentialRecordEntry[]> {
+    return Promise.resolve([...this.records].map(([key, record]) => ({
+      // The parser has already proven every stored key addressable.
+      key: parseCredentialKey(key),
+      kind: record.kind,
+    })))
+  }
+
+  override async modifyRecord(
+    key: CredentialKey,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined> {
+    if (this.isClosed()) throw new Error(`credentials-local is disposed: cannot modify "${key}"`)
+    return this.enqueue(async () => {
+      if (this.isClosed()) {
+        throw new Error(`credentials-local was disposed before the queued "${key}" modify ran`)
+      }
+      await mkdir(dirname(this.spec.filename), { recursive: true, mode: 0o700 })
+      return withFileLock(this.spec.filename, async () => {
+        // Read-modify-write: `mutate` must decide against the record as it
+        // stands now, not as this process last saw it — another process may
+        // have rotated it since.
+        await this.reconcileFromDisk()
+        const current = this.records.get(key)
+        const next = await mutate(current)
+        if (next === undefined) return current
+        // Admitted before it is rendered: the promise that a payload comes
+        // back exactly as written is only keepable for values this document
+        // can spell, and a value rejected here has not been stored.
+        if (next.kind === 'grant') assertJsonValue(`record "${key}" payload`, next.payload, new Set())
+        const nextText = renderRecord(this.text, key, next)
+        // 0600: a document holding secrets is never world-readable.
+        await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
+        this.text = nextText
+        this.records.set(key, next)
+        // After the commit, on the same terms as a reference write.
+        this.notifyRecordUpdated(key)
+        return next
+      }, { waitMs: RECORD_LOCK_WAIT_MS })
+    })
+  }
+
+  override async deleteRecord(key: CredentialKey): Promise<void> {
+    if (this.isClosed()) throw new Error(`credentials-local is disposed: cannot delete "${key}"`)
+    await this.enqueue(async () => {
+      if (this.isClosed()) {
+        throw new Error(`credentials-local was disposed before the queued "${key}" delete ran`)
+      }
+      await mkdir(dirname(this.spec.filename), { recursive: true, mode: 0o700 })
+      await withFileLock(this.spec.filename, async () => {
+        await this.reconcileFromDisk()
+        if (!this.records.has(key)) return
+        const nextText = renderRecord(this.text, key, undefined)
+        await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
+        this.text = nextText
+        this.records.delete(key)
+        this.notifyRecordUpdated(key)
+      })
+    })
+  }
+
   /* jscpd:ignore-start -- the operation-chain and reload lifecycle is the same
      reviewed contract as settings-file, deliberately mirrored (prefer symmetry
      for parallel values); the two providers own different documents and
@@ -389,7 +709,7 @@ export class LocalCredentialProvider extends CredentialProvider {
         await this.reconcileFromDisk()
         const existing = this.values.get(ref)
         if (value === undefined && existing === undefined) return
-        const nextText = renderDocument(this.text, ref, value)
+        const nextText = renderRef(this.text, ref, value)
         // 0600: a document holding secrets is never world-readable.
         await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
         this.text = nextText
@@ -430,7 +750,9 @@ export class LocalCredentialProvider extends CredentialProvider {
       if (!isENOENT(error)) throw error
       return
     }
-    this.values = parseCredentialsDocument(text, this.spec.filename)
+    const document = parseCredentialsDocument(text, this.spec.filename)
+    this.values = document.refs
+    this.records = document.records
     this.text = text
   }
 
@@ -474,11 +796,16 @@ export class LocalCredentialProvider extends CredentialProvider {
       text = undefined
     }
     if (text === this.text || this.isClosed()) return
-    const next = text === undefined ? new Map<string, string>() : parseCredentialsDocument(text, this.spec.filename)
-    const changed = this.changedRefs(this.values, next)
+    const next = text === undefined
+      ? { refs: new Map<string, string>(), records: new Map<string, CredentialRecord>() }
+      : parseCredentialsDocument(text, this.spec.filename)
+    const changedRefs = this.changedRefs(this.values, next.refs)
+    const changedRecords = this.changedRecords(this.records, next.records)
     this.text = text
-    this.values = next
-    for (const ref of changed) this.notifyUpdated(ref)
+    this.values = next.refs
+    this.records = next.records
+    for (const ref of changedRefs) this.notifyUpdated(ref)
+    for (const key of changedRecords) this.notifyRecordUpdated(key)
   }
   /* jscpd:ignore-end */
 
@@ -491,6 +818,19 @@ export class LocalCredentialProvider extends CredentialProvider {
     }
     return changed
   }
+
+  /** Records whose stored value changed; the parser has already proven every key addressable. */
+  private changedRecords(
+    prev: Map<string, CredentialRecord>,
+    next: Map<string, CredentialRecord>,
+  ): CredentialKey[] {
+    const changed: CredentialKey[] = []
+    for (const key of new Set([...prev.keys(), ...next.keys()])) {
+      if (sameJsonValue(prev.get(key), next.get(key))) continue
+      changed.push(parseCredentialKey(key))
+    }
+    return changed
+  }
 }
 
 export default LocalCredentialProvider
diff --git a/packages/credentials/credentials-local/tests/drain.spec.ts b/packages/credentials/credentials-local/tests/drain.spec.ts
index 8aff8db267..2a4a6ca36f 100644
--- a/packages/credentials/credentials-local/tests/drain.spec.ts
+++ b/packages/credentials/credentials-local/tests/drain.spec.ts
@@ -3,7 +3,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
 import { LocalCredentialProvider } from '../src/index.ts'
 
 // The atomic write is the gated asynchronous hold point inside a queued
@@ -29,6 +29,8 @@ async function setGate(next: Promise<void>): Promise<void> {
 
 const KEY = credentialRef('DSH_CRED_DRAIN_A')
 const OTHER = credentialRef('DSH_CRED_DRAIN_B')
+const RECORD = credentialKey('llm-drain', 'alpha')
+const OTHER_RECORD = credentialKey('llm-drain', 'beta')
 
 const cleanups: Array<() => Promise<void>> = []
 
@@ -68,4 +70,32 @@ describe('write-drain teardown', () => {
     expect(await service.resolve(KEY)).toEqual({ value: 'one', source: 'file' })
     expect(await service.resolve(OTHER)).toBeUndefined()
   })
+
+  it('fails a queued record write after disposal on the same terms', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-credentials-drain-record-'))
+    cleanups.push(() => rm(dir, { recursive: true, force: true }))
+    const ctx = new Context()
+    const fiber = ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+    await fiber
+    const service = ctx.credentials
+
+    let release!: () => void
+    await setGate(new Promise<void>((resolveGate) => {
+      release = resolveGate
+    }))
+    const first = service.modifyRecord(RECORD, () => Promise.resolve({ kind: 'grant', payload: { v: 1 } }))
+    await new Promise(resolvePause => setTimeout(resolvePause, 5))
+    const queuedModify = expect(service.modifyRecord(OTHER_RECORD, () => Promise.resolve({ kind: 'api-key' })))
+      .rejects.toThrow(/disposed before the queued/)
+    const queuedDelete = expect(service.deleteRecord(OTHER_RECORD)).rejects.toThrow(/disposed before the queued/)
+    const disposal = fiber.dispose()
+    await new Promise(resolvePause => setTimeout(resolvePause, 10))
+    release()
+    await disposal
+
+    await expect(first).resolves.toEqual({ kind: 'grant', payload: { v: 1 } })
+    await queuedModify
+    await queuedDelete
+    expect(await service.readRecord(OTHER_RECORD)).toBeUndefined()
+  })
 })
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 9fd0c1b319..1f24a50a0b 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -70,7 +70,7 @@ describe('layering and reads', () => {
   it('serves file entries alongside comments and quoted values', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, '# notes\nDSH_CRED_TEST: plain\nDSH_CRED_OTHER: "with space"\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  # notes\n  DSH_CRED_TEST: plain\n  DSH_CRED_OTHER: "with space"\n')
     const ctx = await boot({ path, watch: false })
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'plain', source: 'file' })
     expect(await ctx.credentials.resolve(OTHER)).toEqual({ value: 'with space', source: 'file' })
@@ -80,7 +80,7 @@ describe('layering and reads', () => {
   it('lets a non-empty process environment win read-only over the file', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: from-file\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: from-file\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', 'from-env')
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-env', source: 'env' })
@@ -90,7 +90,7 @@ describe('layering and reads', () => {
   it('treats an empty environment value as absent, falling through to the file', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', '')
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
@@ -124,7 +124,7 @@ describe('layer ladder', () => {
   it('lets the stored value beat the user .env, so a UI write takes effect immediately', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: stored\n')
     const ctx = await bootLayered(path, [
       { source: 'process', values: {} },
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'older-user-env' } },
@@ -163,7 +163,7 @@ describe('layer ladder', () => {
     expect(await bare.credentials.resolve(KEY)).toEqual({ value: 'from-project', source: 'project-env' })
     expect(await bare.credentials.describe(KEY)).toEqual({ configured: true, source: 'project-env', writable: true })
 
-    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: stored\n')
     const stored = await bootLayered(path, layers)
     expect(await stored.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
   })
@@ -171,7 +171,7 @@ describe('layer ladder', () => {
   it.skipIf(process.platform === 'win32')('refuses a document other OS users can read', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: leaked\n', { mode: 0o644 })
+    await writeFile(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: leaked\n', { mode: 0o644 })
     const ctx = new Context()
     // Before the contents are read at all: serving secrets out of a
     // world-readable file would make the 0600 the provider writes meaningless.
@@ -212,7 +212,7 @@ describe('layer ladder', () => {
   it('lets only the inherited environment shadow the store, read-only', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: stored\n')
     const ctx = await bootLayered(path, [
       { source: 'process', values: { DSH_CRED_TEST: 'from-shell' } },
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'from-user-env' } },
@@ -230,10 +230,41 @@ describe('document validation', () => {
   it.each([
     ['a non-mapping root', 'just a string\n', /must be a mapping/],
     ['a sequence root', '- DSH_CRED_TEST\n', /must be a mapping/],
-    ['a key that is not a POSIX identifier', 'not-a-ref: value\n', /credential ref/],
-    ['a non-string value', 'DSH_CRED_TEST: 123\n', /must be a string/],
-    ['an empty value', 'DSH_CRED_TEST: ""\n', /is empty/],
-    ['duplicate keys', 'DSH_CRED_TEST: one\nDSH_CRED_TEST: two\n', /invalid document/],
+    // The pre-release layout is refused by name rather than read as an empty
+    // store: a silently ignored document would surface as an authentication
+    // failure on the first request instead of at load.
+    ['the pre-release flat layout', 'DSH_CRED_TEST: stored\n', /nest the existing 1 entry under/],
+    ['the pre-release flat layout with several entries', 'DSH_CRED_TEST: a\nDSH_CRED_OTHER: b\n',
+      /nest the existing 2 entries under/],
+    ['a future version', 'version: 2\nrefs: {}\n', /this build reads version 1/],
+    ['an unknown top-level key', 'version: 1\nsecrets: {}\n', /unknown top-level key "secrets"/],
+    ['a non-mapping refs section', 'version: 1\nrefs: nope\n', /"refs" .* must be a mapping/],
+    ['a key that is not a POSIX identifier', 'version: 1\nrefs:\n  not-a-ref: value\n', /credential ref/],
+    ['a non-string value', 'version: 1\nrefs:\n  DSH_CRED_TEST: 123\n', /must be a string/],
+    ['an empty value', 'version: 1\nrefs:\n  DSH_CRED_TEST: ""\n', /is empty/],
+    ['a record key that is not scoped', 'version: 1\nrecords:\n  codex:\n    kind: grant\n    payload: 1\n',
+      /must be "<scope>\/<id>"/],
+    ['a record that is not a mapping', 'version: 1\nrecords:\n  llm-pi-ai/codex: token\n',
+      /record "llm-pi-ai\/codex" .* must be a mapping/],
+    ['a record with no kind', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    payload: 1\n', /has no kind/],
+    ['a record with an unknown kind', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    kind: token\n',
+      /unknown kind "token"/],
+    ['a record with an unknown field', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    kind: grant\n'
+      + '    payload: 1\n    extra: 2\n', /unknown field "extra"/],
+    ['a grant with no payload', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    kind: grant\n', /has no payload/],
+    // YAML spells values JSON has none for. The seam promises an owner its
+    // payload comes back exactly as written, which a lossy round trip breaks.
+    ['a non-finite payload number', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    kind: grant\n'
+      + '    payload:\n      ratio: .inf\n', /non-finite number/],
+    ['a cyclic payload', 'version: 1\nrecords:\n  llm-pi-ai/codex:\n    kind: grant\n'
+      + '    payload: &loop\n      self: *loop\n', /is cyclic/],
+    ['an api-key record with an empty key', 'version: 1\nrecords:\n  llm-pi-ai/acme:\n    kind: api-key\n'
+      + '    key: ""\n', /non-string or empty key/],
+    ['an api-key record env that is not a mapping', 'version: 1\nrecords:\n  llm-pi-ai/acme:\n    kind: api-key\n'
+      + '    env: nope\n', /non-mapping env/],
+    ['an api-key record env value that is empty', 'version: 1\nrecords:\n  llm-pi-ai/acme:\n    kind: api-key\n'
+      + '    env:\n      AWS_PROFILE: ""\n', /env "AWS_PROFILE" .* must be a non-empty string/],
+    ['duplicate keys', 'version: 1\nrefs:\n  DSH_CRED_TEST: one\n  DSH_CRED_TEST: two\n', /invalid document/],
     ['malformed yaml', 'DSH_CRED_TEST: "unterminated\n', /invalid document/],
   ])('fails boot on %s', async (_case, text, message) => {
     const dir = await tempDir()
@@ -280,7 +311,7 @@ describe('document writes', () => {
     const ctx = await boot({ path, watch: false })
     const seen = updates(ctx)
     await ctx.credentials.set(KEY, 'sk-fresh')
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST: sk-fresh\n')
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrefs:\n  DSH_CRED_TEST: sk-fresh\n')
     if (process.platform !== 'win32') expect((await stat(path)).mode & 0o777).toBe(0o600)
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'sk-fresh', source: 'file' })
     expect(seen).toEqual([KEY])
@@ -289,11 +320,12 @@ describe('document writes', () => {
   it('patches one entry, preserving comments and every untouched entry', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: old\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  # deployment notes\n  DSH_CRED_OTHER: keep\n\n  # the one under edit\n  DSH_CRED_TEST: old\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(KEY, 'new value!')
     expect(await readFile(path, 'utf8')).toBe(
-      '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: new value!\n',
+      'version: 1\nrefs:\n  # deployment notes\n  DSH_CRED_OTHER: keep\n\n'
+      + '  # the one under edit\n  DSH_CRED_TEST: new value!\n',
     )
   })
 
@@ -317,11 +349,11 @@ describe('document writes', () => {
     // Comments above an entry are that entry's annotation and go with it when
     // it is removed — including anything above the document's first entry.
     // Every other entry keeps its own comments.
-    await writeCredentials(path, '# about the doomed one\nDSH_CRED_TEST: gone\n# about the survivor\nDSH_CRED_OTHER: stays\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  # about the doomed one\n  DSH_CRED_TEST: gone\n  # about the survivor\n  DSH_CRED_OTHER: stays\n')
     const ctx = await boot({ path, watch: false })
     const seen = updates(ctx)
     await ctx.credentials.unset(KEY)
-    expect(await readFile(path, 'utf8')).toBe('# about the survivor\nDSH_CRED_OTHER: stays\n')
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrefs:\n  # about the survivor\n  DSH_CRED_OTHER: stays\n')
     await ctx.credentials.unset(KEY)
     expect(seen).toEqual([KEY])
   })
@@ -329,7 +361,7 @@ describe('document writes', () => {
   it('rejects empty values and writes the environment would shadow', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
 
     await expect(ctx.credentials.set(KEY, '')).rejects.toThrow(/empty value/)
@@ -342,10 +374,10 @@ describe('document writes', () => {
   it('leaves an empty mapping after unsetting the only entry', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_TEST: only\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: only\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.unset(KEY)
-    expect(await readFile(path, 'utf8')).toBe('{}\n')
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrefs: {}\n')
     // The emptied document still reloads as an empty store, not a parse error.
     const reread = await boot({ path, watch: false })
     expect(await reread.credentials.resolve(KEY)).toBeUndefined()
@@ -369,7 +401,7 @@ describe('document writes', () => {
     const good = ctx.credentials.set(OTHER, 'lands')
     await bad
     await good
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_OTHER: lands\n')
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrefs:\n  DSH_CRED_OTHER: lands\n')
   })
 
   it('serializes concurrent writes so both land in the one document', async () => {
@@ -380,7 +412,7 @@ describe('document writes', () => {
       ctx.credentials.set(KEY, 'one'),
       ctx.credentials.set(OTHER, 'two'),
     ])
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST: one\nDSH_CRED_OTHER: two\n')
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrefs:\n  DSH_CRED_TEST: one\n  DSH_CRED_OTHER: two\n')
   })
 
   it('refuses writes after disposal', async () => {
@@ -401,17 +433,17 @@ describe('real hot reload', () => {
     const path = join(dir, '.credentials.yaml')
     // Watching starts on an existing document: creation racing watcher setup
     // is a chokidar readiness gap, not the reload contract under test.
-    await writeCredentials(path, 'DSH_CRED_TEST: boot\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: boot\n')
     const ctx = await boot({ path, debounceMs: 10 })
     const seen = updates(ctx)
 
-    await writeCredentials(path, 'DSH_CRED_TEST: live\nDSH_CRED_OTHER: extra\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: live\n  DSH_CRED_OTHER: extra\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'live', source: 'file' })
     })
 
     // Wholesale replacement: an entry deleted on disk never lingers in memory.
-    await writeCredentials(path, 'DSH_CRED_TEST: live\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_TEST: live\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(OTHER)).toBeUndefined()
     })
diff --git a/packages/credentials/credentials-local/tests/records.spec.ts b/packages/credentials/credentials-local/tests/records.spec.ts
new file mode 100644
index 0000000000..dfae94a093
--- /dev/null
+++ b/packages/credentials/credentials-local/tests/records.spec.ts
@@ -0,0 +1,331 @@
+// The record half of the seam: the store keeps an owner's payload verbatim,
+// presence rather than content answers "configured", and every write goes
+// through one serialized read-modify-write so a rotating credential cannot be
+// lost between processes.
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { credentialKey, credentialKeyScope, credentialRef, parseCredentialKey } from '@deepseek-ai/dsh-credentials'
+import type { CredentialKey, CredentialRecord } from '@deepseek-ai/dsh-credentials'
+import { LocalCredentialProvider } from '../src/index.ts'
+
+/** Credential documents are seeded owner-only, exactly as the provider creates them. */
+function writeCredentials(file: string, text: string): Promise<void> {
+  return writeFile(file, text, { mode: 0o600 })
+}
+
+const CODEX = credentialKey('llm-pi-ai', 'openai-codex')
+const BEDROCK = credentialKey('llm-pi-ai', 'amazon-bedrock')
+const OTHER_OWNER = credentialKey('llm-kimi', 'openai-codex')
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-cred-records-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof LocalCredentialProvider>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(LocalCredentialProvider, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+/** Store one record outright; the seam offers only the read-modify-write path. */
+function put(ctx: Context, key: CredentialKey, record: CredentialRecord): Promise<CredentialRecord | undefined> {
+  return ctx.credentials.modifyRecord(key, () => Promise.resolve(record))
+}
+
+function recordUpdates(ctx: Context): CredentialKey[] {
+  const seen: CredentialKey[] = []
+  ctx.on('credentials/record-updated', (key) => { seen.push(key) })
+  return seen
+}
+
+describe('credential keys', () => {
+  it('rejects a segment that is not a lowercase hyphenated identifier', () => {
+    expect(() => credentialKey('llm-pi-ai', 'OpenAI')).toThrow(/credential key segment/)
+    expect(() => credentialKey('', 'codex')).toThrow(/credential key segment/)
+  })
+
+  it('stays disjoint from the reference grammar', () => {
+    // The `/` is what makes the two key spaces incapable of colliding, so a
+    // record address can never be mistaken for an environment-variable name.
+    expect(() => credentialRef(CODEX)).toThrow(/credential ref/)
+  })
+
+  it('reads back the owning plugin, which is what makes an orphan recognizable', () => {
+    expect(credentialKeyScope(CODEX)).toBe('llm-pi-ai')
+    expect(credentialKeyScope(OTHER_OWNER)).toBe('llm-kimi')
+  })
+
+  it('admits a stored key and refuses one that is not two segments', () => {
+    expect(parseCredentialKey('llm-pi-ai/openai-codex')).toBe(CODEX)
+    expect(() => parseCredentialKey('openai-codex')).toThrow(/must be "<scope>\/<id>"/)
+    expect(() => parseCredentialKey('a/b/c')).toThrow(/must be "<scope>\/<id>"/)
+  })
+})
+
+describe('record storage', () => {
+  it('returns a grant payload exactly as its owner wrote it', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    // Fields the seam has never heard of ride along: an owner's SDK gains them
+    // between releases, and a whitelist here would silently eat the new ones.
+    const payload = { type: 'oauth', access: 'at', refresh: 'rt', expires: 1786000000000, accountId: 'acct_1' }
+    await put(ctx, CODEX, { kind: 'grant', payload })
+
+    expect(await ctx.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload })
+    const reread = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    expect(await reread.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload })
+  })
+
+  it('treats a record carrying no key and no environment as configured', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    // The owner confirmed this route authenticates from its own ambient
+    // discovery. That is a stored decision, not a blank — the opposite reading
+    // of the empty-value rule the reference half follows.
+    await put(ctx, BEDROCK, { kind: 'api-key' })
+
+    expect(await ctx.credentials.describeRecord(BEDROCK)).toEqual({ configured: true, kind: 'api-key', writable: true })
+  })
+
+  it('describes an absent record as unconfigured but writable', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+
+    expect(await ctx.credentials.describeRecord(CODEX)).toEqual({ configured: false, writable: true })
+    expect(await ctx.credentials.readRecord(CODEX)).toBeUndefined()
+  })
+
+  it('stores provider environment values beside or instead of a key', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    await put(ctx, BEDROCK, { kind: 'api-key', env: { AWS_PROFILE: 'prod' } })
+
+    expect(await ctx.credentials.readRecord(BEDROCK)).toEqual({ kind: 'api-key', env: { AWS_PROFILE: 'prod' } })
+  })
+
+  it('keeps references and records in one document without either disturbing the other', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(credentialRef('DSH_RECORDS_KEY'), 'sk-live')
+    await put(ctx, CODEX, { kind: 'grant', payload: { token: 't' } })
+
+    const text = await readFile(path, 'utf8')
+    expect(text).toBe(
+      'version: 1\nrefs:\n  DSH_RECORDS_KEY: sk-live\nrecords:\n'
+      + '  llm-pi-ai/openai-codex:\n    kind: grant\n    payload:\n      token: t\n',
+    )
+    expect(await ctx.credentials.resolve(credentialRef('DSH_RECORDS_KEY'))).toEqual({ value: 'sk-live', source: 'file' })
+  })
+
+  it('reads every record shape back off disk', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    // Written by hand rather than through the API: this is the parse path, and
+    // an api-key record is legal with a key, with environment values, with
+    // both, or with neither.
+    await writeCredentials(path, 'version: 1\nrecords:\n'
+      + '  llm-pi-ai/openai-codex:\n    kind: grant\n    payload:\n      access: at\n'
+      + '  llm-pi-ai/amazon-bedrock:\n    kind: api-key\n    env:\n      AWS_PROFILE: prod\n'
+      + '  llm-pi-ai/azure:\n    kind: api-key\n    key: sk-azure\n'
+      + '  llm-pi-ai/both:\n    kind: api-key\n    key: sk-both\n    env:\n      REGION: eu\n'
+      + '  llm-pi-ai/ambient:\n    kind: api-key\n')
+    const ctx = await boot({ path, watch: false })
+
+    expect(await ctx.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload: { access: 'at' } })
+    expect(await ctx.credentials.readRecord(BEDROCK)).toEqual({ kind: 'api-key', env: { AWS_PROFILE: 'prod' } })
+    expect(await ctx.credentials.readRecord(credentialKey('llm-pi-ai', 'azure')))
+      .toEqual({ kind: 'api-key', key: 'sk-azure' })
+    expect(await ctx.credentials.readRecord(credentialKey('llm-pi-ai', 'both')))
+      .toEqual({ kind: 'api-key', key: 'sk-both', env: { REGION: 'eu' } })
+    expect(await ctx.credentials.readRecord(credentialKey('llm-pi-ai', 'ambient'))).toEqual({ kind: 'api-key' })
+  })
+
+  it('publishes a record an external edit reshaped, whatever shape it took', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { scopes: ['a'] } })
+    const seen = recordUpdates(ctx)
+
+    // A sequence where a mapping stood, then a mapping that gained a field:
+    // neither is caught by an identity check, and reporting them as unchanged
+    // would leave a stale credential on every configuration surface.
+    for (const payload of ['[1]', '{a: 1}', '{a: 1, b: 2}']) {
+      await writeCredentials(path, 'version: 1\nrecords:\n  llm-pi-ai/openai-codex:\n'
+        + `    kind: grant\n    payload: ${payload}\n`)
+      // Any write folds the unobserved document in before committing its own.
+      await put(ctx, BEDROCK, { kind: 'api-key' })
+    }
+
+    expect(seen.filter(key => key === CODEX)).toHaveLength(3)
+    expect(await ctx.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload: { a: 1, b: 2 } })
+  })
+
+  it('keeps two owners of the same provider id apart', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { owner: 'pi-ai' } })
+    await put(ctx, OTHER_OWNER, { kind: 'grant', payload: { owner: 'kimi' } })
+
+    expect(await ctx.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload: { owner: 'pi-ai' } })
+    expect(await ctx.credentials.readRecord(OTHER_OWNER)).toEqual({ kind: 'grant', payload: { owner: 'kimi' } })
+  })
+})
+
+describe('record mutation', () => {
+  it('shows the mutation the record as it stands and commits its replacement', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { expires: 1 } })
+    const seen: Array<CredentialRecord | undefined> = []
+
+    const next = await ctx.credentials.modifyRecord(CODEX, (current) => {
+      seen.push(current)
+      return Promise.resolve({ kind: 'grant', payload: { expires: 2 } })
+    })
+
+    expect(seen).toEqual([{ kind: 'grant', payload: { expires: 1 } }])
+    expect(next).toEqual({ kind: 'grant', payload: { expires: 2 } })
+  })
+
+  it('leaves the entry untouched when the mutation declines', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { expires: 1 } })
+    const before = await readFile(path, 'utf8')
+    const seen = recordUpdates(ctx)
+
+    // The refresh path declines whenever a second reader finds the credential
+    // already rotated; declining must not rewrite the document or announce a
+    // change that did not happen.
+    const result = await ctx.credentials.modifyRecord(CODEX, () => Promise.resolve(undefined))
+
+    expect(result).toEqual({ kind: 'grant', payload: { expires: 1 } })
+    expect(await readFile(path, 'utf8')).toBe(before)
+    expect(seen).toEqual([])
+  })
+
+  it('announces a committed write and a committed delete, and stays silent on an absent delete', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    const seen = recordUpdates(ctx)
+
+    await put(ctx, CODEX, { kind: 'grant', payload: 1 })
+    await ctx.credentials.deleteRecord(CODEX)
+    await ctx.credentials.deleteRecord(CODEX)
+
+    expect(seen).toEqual([CODEX, CODEX])
+    expect(await ctx.credentials.readRecord(CODEX)).toBeUndefined()
+  })
+
+  it('removes a later record without disturbing the annotation above the first', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    // The comment sits above the section's first entry, where the parser
+    // attaches it to the section rather than to the pair. Removing a *later*
+    // entry must leave it exactly where it is.
+    await writeCredentials(path, 'version: 1\nrecords:\n  # the one to keep\n'
+      + '  llm-pi-ai/openai-codex:\n    kind: grant\n    payload: 1\n'
+      + '  llm-pi-ai/amazon-bedrock:\n    kind: api-key\n')
+    const ctx = await boot({ path, watch: false })
+
+    await ctx.credentials.deleteRecord(BEDROCK)
+
+    expect(await readFile(path, 'utf8')).toBe('version: 1\nrecords:\n  # the one to keep\n'
+      + '  llm-pi-ai/openai-codex:\n    kind: grant\n    payload: 1\n')
+  })
+
+  it('folds an unobserved external record edit into a write instead of overwriting it', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { v: 1 } })
+    // Landed on disk with no watcher to report it — the same blind spot as a
+    // debounce window, a missed event, or another process's write.
+    await writeCredentials(path, 'version: 1\nrecords:\n'
+      + '  llm-pi-ai/openai-codex:\n    kind: grant\n    payload:\n      v: 1\n'
+      + '  llm-pi-ai/amazon-bedrock:\n    kind: api-key\n    env:\n      AWS_PROFILE: prod\n')
+
+    await put(ctx, CODEX, { kind: 'grant', payload: { v: 2 } })
+
+    expect(await ctx.credentials.readRecord(BEDROCK)).toEqual({ kind: 'api-key', env: { AWS_PROFILE: 'prod' } })
+    expect(await ctx.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload: { v: 2 } })
+  })
+
+  it('keeps both records when two providers write the same document concurrently', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const first = await boot({ path, watch: false })
+    const second = await boot({ path, watch: false })
+
+    await Promise.all([
+      (async () => {
+        for (const v of [1, 2, 3]) await put(first, CODEX, { kind: 'grant', payload: { v } })
+      })(),
+      (async () => {
+        for (const v of [1, 2, 3]) await put(second, BEDROCK, { kind: 'grant', payload: { v } })
+      })(),
+    ])
+
+    const reread = await boot({ path, watch: false })
+    expect(await reread.credentials.readRecord(CODEX)).toEqual({ kind: 'grant', payload: { v: 3 } })
+    expect(await reread.credentials.readRecord(BEDROCK)).toEqual({ kind: 'grant', payload: { v: 3 } })
+  })
+
+  it('enumerates stored records by address and tag, never by value', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
+    await put(ctx, CODEX, { kind: 'grant', payload: { secret: 'do-not-list' } })
+    await put(ctx, BEDROCK, { kind: 'api-key', key: 'sk-listed' })
+
+    const listed = await ctx.credentials.listRecords()
+
+    expect(listed).toEqual([{ key: CODEX, kind: 'grant' }, { key: BEDROCK, kind: 'api-key' }])
+    expect(JSON.stringify(listed)).not.toContain('do-not-list')
+    expect(JSON.stringify(listed)).not.toContain('sk-listed')
+  })
+
+  it('refuses a payload this document could not read back', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+
+    // An owner's SDK value that YAML would either lose or re-read as another
+    // type. Rejecting on the way in is what keeps the round-trip promise
+    // keepable; a rejected value must also leave nothing behind.
+    for (const payload of [{ at: new Date(0) }, { size: 1n }, { run: () => undefined }, { ratio: Number.NaN }]) {
+      await expect(put(ctx, CODEX, { kind: 'grant', payload }))
+        .rejects.toThrow(/record "llm-pi-ai\/openai-codex" payload/)
+    }
+    expect(await ctx.credentials.readRecord(CODEX)).toBeUndefined()
+    await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
+  it('refuses record writes once disposed', async () => {
+    const dir = await tempDir()
+    const ctx = new Context()
+    const fiber = ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+    await fiber
+    const credentials = ctx.credentials
+    await fiber.dispose()
+
+    await expect(credentials.modifyRecord(CODEX, () => Promise.resolve({ kind: 'grant', payload: 1 })))
+      .rejects.toThrow(/disposed/)
+    await expect(credentials.deleteRecord(CODEX)).rejects.toThrow(/disposed/)
+  })
+})
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index 13c85873f9..495fe22b33 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -49,7 +49,7 @@ describe('read-modify-write', () => {
     await ctx.credentials.set(ALPHA, 'one')
     // The external edit has landed on disk but no watcher reported it (watch
     // is off — the same blind spot as a debounce window or a missed event).
-    await writeCredentials(path, `${ALPHA}: one\n${BETA}: external\n`)
+    await writeCredentials(path, `version: 1\nrefs:\n  ${ALPHA}: one\n  ${BETA}: external\n`)
     await ctx.credentials.set(ALPHA, 'two')
     const text = await readFile(path, 'utf8')
     expect(text).toContain(`${BETA}: external`)
@@ -128,11 +128,12 @@ describe('document editor', () => {
   it('leaves a sibling multi-line value untouched while patching one entry', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    const wrapped = `DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: a\n`
+    const wrapped = `version: 1\nrefs:\n  DSH_REVIEW_WRAPPED: |-\n    line1\n    line2\n  ${ALPHA}: a\n`
     await writeCredentials(path, wrapped)
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(ALPHA, 'b')
-    expect(await readFile(path, 'utf8')).toBe(`DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: b\n`)
+    expect(await readFile(path, 'utf8'))
+      .toBe(`version: 1\nrefs:\n  DSH_REVIEW_WRAPPED: |-\n    line1\n    line2\n  ${ALPHA}: b\n`)
     expect(await ctx.credentials.resolve(credentialRef('DSH_REVIEW_WRAPPED')))
       .toEqual({ value: 'line1\nline2', source: 'file' })
   })
diff --git a/packages/credentials/credentials-local/tests/watcher.spec.ts b/packages/credentials/credentials-local/tests/watcher.spec.ts
index 40dba1786f..58c83a0407 100644
--- a/packages/credentials/credentials-local/tests/watcher.spec.ts
+++ b/packages/credentials/credentials-local/tests/watcher.spec.ts
@@ -105,7 +105,7 @@ describe('watcher pipeline', () => {
     instance!.watcher.emit('error', new Error('watch backend failure'))
     expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
 
-    await writeCredentials(path, 'DSH_CRED_PIPE: arrived\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: arrived\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'arrived', source: 'file' })
@@ -115,7 +115,7 @@ describe('watcher pipeline', () => {
   it('keeps the last good snapshot when the file turns unreadable at runtime', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_PIPE: good\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: good\n')
     const ctx = await boot({ path, debounceMs: 5 })
 
     await chmod(path, 0o000)
@@ -130,9 +130,9 @@ describe('watcher pipeline', () => {
   it('keeps the last good snapshot when the read fails after its permission check', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_PIPE: good\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: good\n')
     const ctx = await boot({ path, debounceMs: 5 })
-    fsHarness.nextReadError = Object.assign(new Error('EACCES: injected read failure'), { code: 'EACCES' })
+    fsHarness.nextReadError = Object.assign(new Error('version: 1\nrefs:\n  EACCES: injected read failure\n'), { code: 'EACCES' })
 
     const [instance] = await fakeInstances()
     instance!.watcher.emit('all', 'change', path)
@@ -153,7 +153,7 @@ describe('watcher pipeline', () => {
     })
     const [instance] = await fakeInstances()
 
-    await writeCredentials(path, 'DSH_CRED_PIPE: first\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: first\n')
     instance!.watcher.emit('all', 'change', path)
     // The snapshot commits before the fan-out, so the value lands even though
     // the listener threw out of the refresh.
@@ -162,7 +162,7 @@ describe('watcher pipeline', () => {
     })
 
     arm = false
-    await writeCredentials(path, 'DSH_CRED_PIPE: second\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: second\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'second', source: 'file' })
@@ -172,7 +172,7 @@ describe('watcher pipeline', () => {
   it('quiesces the refresh pipeline before dispose completes', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_PIPE: initial\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: initial\n')
     const ctx = new Context()
     const fiber = ctx.plugin(LocalCredentialProvider, { path, debounceMs: 5 })
     await fiber
@@ -182,7 +182,7 @@ describe('watcher pipeline', () => {
       if (disposed) postDisposeCommits += 1
     })
 
-    await writeCredentials(path, 'DSH_CRED_PIPE: changed\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: changed\n')
     const [instance] = await fakeInstances()
     // Two queued refreshes: dispose interrupts one mid-flight and the other
     // before it starts, so both closed guards must hold.
@@ -199,7 +199,7 @@ describe('watcher pipeline', () => {
   it('empties the snapshot when the document is deleted and emits the removals', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_PIPE: doomed\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: doomed\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
@@ -218,7 +218,7 @@ describe('watcher pipeline', () => {
   it('keeps the last good snapshot when an external edit makes the document invalid', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, 'DSH_CRED_PIPE: a\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: a\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
@@ -229,7 +229,7 @@ describe('watcher pipeline', () => {
     // this document holds nothing but credentials. A live reload must warn
     // and keep serving the last good snapshot rather than take the process
     // down or silently drop the entry it could not validate.
-    await writeCredentials(path, 'BAD-KEY: 2\nDSH_CRED_PIPE: b\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  BAD-KEY: 2\n  DSH_CRED_PIPE: b\n')
     const [instance] = await fakeInstances()
     instance!.watcher.emit('all', 'change', path)
     await new Promise(resolve => setTimeout(resolve, 50))
@@ -237,7 +237,7 @@ describe('watcher pipeline', () => {
     expect(seen).toEqual([])
 
     // Repairing the document resumes publishing.
-    await writeCredentials(path, 'DSH_CRED_PIPE: b\n')
+    await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: b\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'b', source: 'file' })
@@ -258,11 +258,11 @@ describe('watcher pipeline', () => {
   it('reconciles at watcher ready so a change during setup is not missed', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeCredentials(path, `${KEY}: a\n`)
+    await writeCredentials(path, `version: 1\nrefs:\n  ${KEY}: a\n`)
     const ctx = await boot({ path, debounceMs: 5 })
     // Written after the initial load but before the watcher became active:
     // no 'all' event will ever fire for it.
-    await writeCredentials(path, `${KEY}: written-before-ready\n`)
+    await writeCredentials(path, `version: 1\nrefs:\n  ${KEY}: written-before-ready\n`)
     const [instance] = await fakeInstances()
     instance!.watcher.emit('ready')
     await vi.waitFor(async () => {
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 55069ea782..39ca7ff15c 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/README.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 packages/credentials/credentials/README.md
-README.md: 62f5c6318ec04e9820a3d18ffa159d1561215760
-README.zh.md: 3c6ca0b454d4ff8a78bfcd29d1031584da27a5f1
+README.md: 0a8a10d48e9166ced2fd99613207060c06892a38
+README.zh.md: 9e621ccfa4f58b1cddfebe3bf0c9fe598d8dcf42
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index 62f5c6318e..0a8a10d48e 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -10,11 +10,19 @@ Credential Service Definition (`ctx.credentials`). One doctrine, three consequen
 
 **An empty stored value is absent.** Everywhere: `resolve` skips it, `describe` reports it unconfigured. A blank can never masquerade as a configured secret.
 
+## Two key spaces, two questions
+
+A `CredentialRef` answers *what is behind this environment-variable name*, layered over the process environment, the managed store, and `.env` files. Everything above describes that half.
+
+A `CredentialKey` answers *what credential does this plugin hold for this id*. Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and the empty-value rule does not apply: an `api-key` record carrying neither a key nor environment values states that its owner confirmed ambient authentication, which is configured.
+
+The key is `<scope>/<id>`, where `scope` is the **owning plugin's registered name**. The scope is the owner rather than the domain because a `grant` payload is written in its owner's format: two plugins serving the same provider name would otherwise read each other's payload, and a record left behind by an uninstalled plugin could not be told apart from a live one. The `/` also keeps the two grammars disjoint, so the key spaces can never collide.
+
 ## Surface
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
 
 declare const ctx: Context
 
@@ -23,8 +31,21 @@ const hit = await ctx.credentials.resolve(ref)           // { value, source } |
 const info = await ctx.credentials.describe(ref)         // { configured, source?, writable } — never the value
 await ctx.credentials.set(ref, 'sk-…')                   // rejects while a read-only source shadows the ref
 await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')   // <owner>/<id>, branded
+await ctx.credentials.readRecord(key)                    // CredentialRecord | undefined
+await ctx.credentials.describeRecord(key)                // { configured, kind?, writable } — never the value
+await ctx.credentials.listRecords()                      // [{ key, kind }] — never values
+await ctx.credentials.modifyRecord(key, async () => ({ kind: 'grant', payload: { token: '…' } }))
+await ctx.credentials.deleteRecord(key)                  // no-op when absent
 ```
 
+`modifyRecord` is the only write path because a correct write depends on the current value: a token refresh is read-decide-replace, and the mutation must see the record as it stands at the moment the write is exclusive. Exclusion holds across processes, which is what stops two of them rotating one refresh token and losing whichever wrote first. Returning `undefined` from the mutation leaves the entry untouched and announces nothing.
+
+`listRecords` exists even though the reference half has no enumeration by design. References are discovered from settings schemas (`apiKeyEnv` fields); records have no such path, so a surface that cannot list them cannot show what a user is authorized for, nor find an orphan left by an uninstalled plugin.
+
+A `grant` record's `payload` is opaque: the seam never reads, validates, or reshapes it. The one constraint is that it survives a JSON round trip, which the provider enforces on the way in and on the way out — a value the store could not read back exactly as written is refused rather than stored lossily.
+
 `credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration UIs refreshing a "configured" badge. Its declaration lives in the client-safe `./types` subpath export together with the `CredentialRef` type it names (the package root re-exports the type), so a consumer outside the Host compilation face reads the very signature the Host emits instead of restating it.
 
 The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only source (the live process environment, in the local provider) currently supplies the reference, a write would appear to succeed while resolution keeps returning the shadowing value — the seam rejects instead, and `describe().writable` lets a UI render the reference read-only up front.
@@ -43,6 +64,7 @@ No direct invalidation; credentials never enter a request prefix.
 
 ## Known Limitations and Deferred Work
 
-- **No enumeration** — the seam answers questions about references it is given; configuration surfaces learn the references from settings schemas, so a `list()` has no current consumer.
-- **References are environment-variable-shaped** — one flat POSIX-identifier namespace until a provider needs richer addressing.
+- **References have no enumeration** — the seam answers questions about references it is given; configuration surfaces learn them from settings schemas, so a `list()` over that half has no current consumer. Records do enumerate, for the reason above.
+- **References are environment-variable-shaped** — one flat POSIX-identifier namespace, because a reference doubles as the environment name it resolves through. Records carry the richer `<owner>/<id>` addressing.
 - **Process-environment changes are invisible** — no event can fire for them; a UI only re-reads `describe()` on its own navigation.
+- **A record's owner is its scope, and nothing verifies the scope is mounted** — the seam stores what it is given and reports what it stores. Recognizing an orphan is the caller's join between `listRecords()` and whatever registry owns that scope; the seam has no registry of its own to check against.
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index 3c6ca0b454..9e621ccfa4 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -10,11 +10,19 @@
 
 **空的存储值等于不存在。** 处处如此：`resolve` 跳过它，`describe` 报告未配置。空白永远不会伪装成已配置的机密。
 
+## 两个键空间，两个问题
+
+`CredentialRef` 回答的是*这个环境变量名背后是什么*，分层覆盖进程环境、托管存储与 `.env` 文件。以上全部描述的都是这一半。
+
+`CredentialKey` 回答的是*某个插件为某个 id 持有什么凭据*。这里没有任何东西可以分层——授权 grant 没有可供读取的环境——因此记录的存在与否就是全部事实，空值规则在此不适用：一条既无 key 也无环境值的 `api-key` 记录，陈述的是其拥有者确认该路由靠 ambient 认证，这属于已配置。
+
+键的形式是 `<scope>/<id>`，其中 `scope` 是**拥有该记录的插件的注册名**。scope 取拥有者而非领域，是因为 `grant` 的 payload 以其拥有者的格式写就：否则服务同一个提供方名称的两个插件会互相读到对方的 payload，而已卸载插件留下的记录也无法与仍在使用的区分开。`/` 同时让两种文法互斥，两个键空间因此不可能相撞。
+
 ## 接口
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
 
 declare const ctx: Context
 
@@ -23,8 +31,21 @@ const hit = await ctx.credentials.resolve(ref)           // { value, source } |
 const info = await ctx.credentials.describe(ref)         // { configured, source?, writable } — never the value
 await ctx.credentials.set(ref, 'sk-…')                   // rejects while a read-only source shadows the ref
 await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')   // <owner>/<id>, branded
+await ctx.credentials.readRecord(key)                    // CredentialRecord | undefined
+await ctx.credentials.describeRecord(key)                // { configured, kind?, writable } — never the value
+await ctx.credentials.listRecords()                      // [{ key, kind }] — never values
+await ctx.credentials.modifyRecord(key, async () => ({ kind: 'grant', payload: { token: '…' } }))
+await ctx.credentials.deleteRecord(key)                  // no-op when absent
 ```
 
+`modifyRecord` 是唯一写路径，因为正确的写入依赖当前值：刷新 token 是「读—决定—替换」，变更函数必须看到写入取得独占那一刻的记录。独占跨进程成立，这正是防止两个进程同时轮换同一个 refresh token、丢掉先写那一个的机制。变更函数返回 `undefined` 表示保持原状，不写盘也不发通知。
+
+`listRecords` 存在，尽管引用那一半刻意不提供枚举。引用可以从 settings schema（`apiKeyEnv` 字段）被发现；记录没有这条路径，无法枚举的界面就无法显示用户已授权了什么，也找不到已卸载插件留下的孤儿。
+
+`grant` 记录的 `payload` 是不透明的：seam 从不读取、校验或重塑它。唯一约束是它能经受 JSON 往返，提供方在写入与读出两个方向都强制这一点——存储无法逐字读回的值会被拒绝，而不是有损地存下。
+
 `credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。它的声明住在 client-safe 的 `./types` 子路径出口，与其点名的 `CredentialRef` 类型同处一处（包根继续 re-export 该类型），于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
 
 `set`/`unset` 的遮蔽规则有意采用明确报错的方式：当只读来源（本地提供方中即当前进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
@@ -43,6 +64,7 @@ await ctx.credentials.unset(ref)                         // no-op when absent; s
 
 ## 已知限制与暂缓事项
 
-- **不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，`list()` 没有当前消费方。
-- **引用限定为环境变量形状**——在有提供方需要更丰富的寻址方式前，保持单一扁平的 POSIX 标识符命名空间。
+- **引用不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，对这一半做 `list()` 没有当前消费方。记录出于上文的理由则可枚举。
+- **引用限定为环境变量形状**——单一扁平的 POSIX 标识符命名空间，因为引用同时就是它借以解析的环境变量名。记录使用更丰富的 `<owner>/<id>` 寻址。
 - **进程环境变化不可见**——不可能为其发事件；界面只能在自身导航时重新读取 `describe()`。
+- **记录的拥有者就是它的 scope，而没有任何环节核验该 scope 是否已挂载**——seam 存下被交予的内容，并报告它存了什么。识别孤儿是调用方在 `listRecords()` 与拥有该 scope 的注册表之间做的连接；seam 自身没有可供核对的注册表。
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index dbea6ccba2..951448f8a3 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -9,12 +9,15 @@
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import type { CredentialRef } from './types.ts'
+import type { CredentialKey, CredentialRecord, CredentialRef } from './types.ts'
 
-export type { CredentialRef } from './types.ts'
+export type { ApiKeyRecord, CredentialKey, CredentialRecord, CredentialRef, GrantRecord } from './types.ts'
 
 const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
 
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/
+
 /**
  * Brand a raw string as a {@link CredentialRef}.
  * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
@@ -27,6 +30,51 @@ export function credentialRef(value: string): CredentialRef {
   return value as CredentialRef
 }
 
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export function credentialKey(scope: string, id: string): CredentialKey {
+  for (const segment of [scope, id]) {
+    if (!KEY_SEGMENT_PATTERN.test(segment)) {
+      throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`)
+    }
+  }
+  return `${scope}/${id}` as CredentialKey
+}
+
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export function parseCredentialKey(value: string): CredentialKey {
+  const segments = value.split('/')
+  const [scope, id] = segments
+  if (segments.length !== 2 || scope === undefined || id === undefined) {
+    throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`)
+  }
+  return credentialKey(scope, id)
+}
+
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export function credentialKeyScope(key: CredentialKey): string {
+  // The brand's only constructors both validate two segments, so the split
+  // cannot come back short here.
+  return key.slice(0, key.indexOf('/'))
+}
+
 /** One resolved credential value and the source layer that supplied it. */
 export interface ResolvedCredential {
   /** The non-empty secret value. */
@@ -45,6 +93,29 @@ export interface CredentialInfo {
   writable: boolean
 }
 
+/** Presence and writability facts for one record, safe for configuration UIs — never the value. */
+export interface CredentialRecordInfo {
+  /**
+   * Whether a record is stored. Unlike a reference, presence alone answers
+   * this: an {@link ApiKeyRecord} carrying neither a key nor environment
+   * values states that its owner confirmed ambient authentication, which is
+   * configured, not blank.
+   */
+  configured: boolean
+  /** Discriminant of the stored record; absent while none is stored. */
+  kind?: CredentialRecord['kind']
+  /** Whether {@link CredentialProvider.modifyRecord} would currently succeed. */
+  writable: boolean
+}
+
+/** One stored record's address and tag, for enumeration — never its value. */
+export interface CredentialRecordEntry {
+  /** The record's address. */
+  key: CredentialKey
+  /** Discriminant of the stored record. */
+  kind: CredentialRecord['kind']
+}
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     credentials: CredentialProvider
@@ -52,10 +123,20 @@ declare module '@deepseek-ai/cordis' {
 }
 
 /**
- * Abstract credential service. Providers implement the four operations over
- * their source layers; one seam-wide rule binds them all: an empty stored
- * value is absent everywhere — `resolve` skips it, `describe` reports it
- * unconfigured — so a blank never masquerades as a configured secret.
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link CredentialRef} answers "what is behind this environment-variable
+ * name", layered over the process environment, the provider-managed store, and
+ * `.env` files. One seam-wide rule binds that half: an empty stored value is
+ * absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+ * so a blank never masquerades as a configured secret.
+ *
+ * A {@link CredentialKey} answers "what credential does this plugin hold for
+ * this id". Nothing can layer here — an authorization grant has no
+ * environment to be read from — so presence of the record is the whole fact,
+ * and {@link modifyRecord} is the only write path because a correct write
+ * depends on the current value (a token refresh is read-decide-replace under
+ * one lock).
  */
 export abstract class CredentialProvider extends Service {
   constructor(ctx: Context) {
@@ -98,9 +179,53 @@ export abstract class CredentialProvider extends Service {
    */
   abstract unset(ref: CredentialRef): Promise<void>
 
-  /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
-     fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
-     contract, and extracting it would couple the two seams' event semantics. */
+  /**
+   * Read one stored record. The value is returned as its owner wrote it; a
+   * {@link GrantRecord} payload is not interpreted on the way out.
+   * @param key - the record to read.
+   * @returns the record, or `undefined` while none is stored.
+   */
+  abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>
+
+  /**
+   * Describe one record for configuration surfaces without exposing its value.
+   * @param key - the record to describe.
+   * @returns presence, discriminant, and writability.
+   */
+  abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>
+
+  /**
+   * Enumerate every stored record's address and tag. Unlike the reference
+   * half, which has no enumeration because configuration surfaces learn which
+   * references exist from settings schemas, records have no such discovery
+   * path: a surface that cannot list them cannot show what a user is
+   * authorized for, nor find an orphan left by an uninstalled plugin.
+   * @returns every stored record, values excluded.
+   */
+  abstract listRecords(): Promise<readonly CredentialRecordEntry[]>
+
+  /**
+   * Serialized read-modify-write over one record — the only write path.
+   * `mutate` sees the record as it stands at the moment the write is
+   * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+   * holds across processes where the backing store supports it, which is what
+   * makes a token refresh safe: two processes rotating one refresh token
+   * concurrently would otherwise lose whichever wrote first.
+   * @param key - the record to modify.
+   * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+   * @returns the record after the write, or the current one when `mutate` declined.
+   */
+  abstract modifyRecord(
+    key: CredentialKey,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined>
+
+  /**
+   * Remove one record; removing an absent record is a no-op.
+   * @param key - the record to remove.
+   */
+  abstract deleteRecord(key: CredentialKey): Promise<void>
+
   /**
    * Fan `credentials/updated` out with contained listener failures: every
    * listener runs, and a sync throw or async rejection is logged without
@@ -113,14 +238,31 @@ export abstract class CredentialProvider extends Service {
    * @param ref - the reference whose stored value changed.
    */
   protected notifyUpdated(ref: CredentialRef): void {
+    this.fanOut('credentials/updated', ref)
+  }
+
+  /**
+   * Fan `credentials/record-updated` out on exactly the terms
+   * {@link notifyUpdated} documents, for the record half of the seam.
+   * @param key - the record whose stored value changed.
+   */
+  protected notifyRecordUpdated(key: CredentialKey): void {
+    this.fanOut('credentials/record-updated', key)
+  }
+
+  /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
+     fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
+     contract, and extracting it would couple the two seams' event semantics. */
+  /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+  private fanOut(event: 'credentials/updated' | 'credentials/record-updated', subject: string): void {
     let invariantFailure: unknown
-    const args = ['credentials/updated', ref]
+    const args = [event, subject]
     for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) {
       try {
-        const returned = listener(ref)
+        const returned = listener(subject)
         if (returned != null && typeof (returned as PromiseLike<unknown>).then === 'function') {
           void Promise.resolve(returned as PromiseLike<unknown>).then(undefined, (error: unknown) => {
-            this.warnListenerFailure(ref, error)
+            this.warnListenerFailure(event, subject, error)
           })
         }
       } catch (error) {
@@ -128,7 +270,7 @@ export abstract class CredentialProvider extends Service {
           invariantFailure ??= error
           continue
         }
-        this.warnListenerFailure(ref, error)
+        this.warnListenerFailure(event, subject, error)
       }
     }
     if (invariantFailure !== undefined) throw invariantFailure as Error
@@ -136,8 +278,8 @@ export abstract class CredentialProvider extends Service {
   /* jscpd:ignore-end */
 
   /** Contained-listener diagnostic shared by the sync and async failure paths. */
-  private warnListenerFailure(ref: CredentialRef, error: unknown): void {
-    this.ctx.logger.warn('credentials: a credentials/updated listener for "%s" failed', ref)
+  private warnListenerFailure(event: string, subject: string, error: unknown): void {
+    this.ctx.logger.warn('credentials: a %s listener for "%s" failed', event, subject)
     this.ctx.logger.warn(error)
   }
 }
diff --git a/packages/credentials/credentials/src/types.ts b/packages/credentials/credentials/src/types.ts
index 5922664cbd..69f6185085 100644
--- a/packages/credentials/credentials/src/types.ts
+++ b/packages/credentials/credentials/src/types.ts
@@ -1,8 +1,8 @@
 /**
- * Client-safe type surface of the credential-reference seam: the reference
- * brand and the seam's Cordis event declaration. Types only — no runtime code,
- * and nothing here reaches a Host-only symbol, so a Client compilation face
- * reads exactly the signature the Host emits.
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signature the Host emits.
  *
  * @module @deepseek-ai/dsh-credentials/types
  */
@@ -12,6 +12,52 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
 /** Nominal reference to one credential: a POSIX-style environment-variable name. */
 export type CredentialRef = Branded<'CredentialRef'>
 
+/**
+ * Nominal address of one stored credential record: `<scope>/<id>`, where
+ * `scope` is the registered name of the plugin that owns the record and `id`
+ * is that plugin's own addressing unit (an LLM adapter uses its provider route
+ * key).
+ *
+ * The scope is the owner rather than the domain because a record's payload is
+ * written in its owner's format: two plugins serving the same provider name
+ * would otherwise read each other's payload, and a record left behind by an
+ * uninstalled plugin could not be told apart from a live one. The `/` also
+ * keeps this grammar disjoint from {@link CredentialRef}, so the two key
+ * spaces can never collide.
+ */
+export type CredentialKey = Branded<'CredentialKey'>
+
+/**
+ * A credential the harness itself understands: an api key, provider
+ * environment values, or both. Either field may be absent — a record carrying
+ * neither states that the owner confirmed this route authenticates from its
+ * own ambient discovery, which is a different fact from having no record.
+ */
+export interface ApiKeyRecord {
+  /** Discriminant. */
+  readonly kind: 'api-key'
+  /** The non-empty secret value, when this credential is a key at all. */
+  readonly key?: string
+  /** Provider environment values such as `AWS_PROFILE`; names are POSIX identifiers. */
+  readonly env?: Readonly<Record<string, string>>
+}
+
+/**
+ * The product of one authorization grant, kept verbatim for its owner. The
+ * seam never reads, validates, or reshapes {@link payload}: it is written in
+ * the owning plugin's format and only that plugin can interpret it. The single
+ * constraint is that it survives a JSON round trip.
+ */
+export interface GrantRecord {
+  /** Discriminant. */
+  readonly kind: 'grant'
+  /** Owner-defined JSON value; opaque to the seam and to every other plugin. */
+  readonly payload: unknown
+}
+
+/** One durable credential record, tagged by what the seam may do with it. */
+export type CredentialRecord = ApiKeyRecord | GrantRecord
+
 declare module '@deepseek-ai/cordis' {
   interface Events {
     /**
@@ -27,5 +73,17 @@ declare module '@deepseek-ai/cordis' {
      * @mode emit
      */
     'credentials/updated'(ref: CredentialRef): void
+
+    /**
+     * Committed change to a stored credential record: a `modifyRecord` that
+     * wrote, a `deleteRecord` that removed, or an external edit observed in
+     * storage. Separate from `credentials/updated` because the two key
+     * grammars are disjoint — a listener that received both on one event could
+     * not tell which space a subject belongs to. Listener failures are
+     * contained on the same terms as `credentials/updated`.
+     * @param key - the record whose stored value changed.
+     * @mode emit
+     */
+    'credentials/record-updated'(key: CredentialKey): void
   }
 }
diff --git a/packages/credentials/credentials/tests/memory.ts b/packages/credentials/credentials/tests/memory.ts
index ed36e62a6f..24302ee3f0 100644
--- a/packages/credentials/credentials/tests/memory.ts
+++ b/packages/credentials/credentials/tests/memory.ts
@@ -1,6 +1,14 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { CredentialProvider } from '../src/index.ts'
-import type { CredentialInfo, CredentialRef, ResolvedCredential } from '../src/index.ts'
+import type {
+  CredentialInfo,
+  CredentialKey,
+  CredentialRecord,
+  CredentialRecordEntry,
+  CredentialRecordInfo,
+  CredentialRef,
+  ResolvedCredential,
+} from '../src/index.ts'
 
 /**
  * In-memory credentials provider for interface and consumer tests: one
@@ -8,6 +16,7 @@ import type { CredentialInfo, CredentialRef, ResolvedCredential } from '../src/i
  */
 export class MemoryCredentials extends CredentialProvider {
   private readonly store = new Map<string, string>()
+  private readonly records = new Map<CredentialKey, CredentialRecord>()
 
   constructor(ctx: Context, seed: Record<string, string> = {}) {
     super(ctx)
@@ -46,4 +55,38 @@ export class MemoryCredentials extends CredentialProvider {
     }
     return Promise.resolve()
   }
+
+  override readRecord(key: CredentialKey): Promise<CredentialRecord | undefined> {
+    return Promise.resolve(this.records.get(key))
+  }
+
+  override describeRecord(key: CredentialKey): Promise<CredentialRecordInfo> {
+    const stored = this.records.get(key)
+    return Promise.resolve(stored === undefined
+      ? { configured: false, writable: true }
+      : { configured: true, kind: stored.kind, writable: true })
+  }
+
+  override listRecords(): Promise<readonly CredentialRecordEntry[]> {
+    return Promise.resolve([...this.records].map(([key, record]) => ({ key, kind: record.kind })))
+  }
+
+  override async modifyRecord(
+    key: CredentialKey,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined> {
+    const current = this.records.get(key)
+    const next = await mutate(current)
+    if (next === undefined) return current
+    this.records.set(key, next)
+    this.ctx.emit('credentials/record-updated', key)
+    return next
+  }
+
+  override deleteRecord(key: CredentialKey): Promise<void> {
+    if (this.records.delete(key)) {
+      this.ctx.emit('credentials/record-updated', key)
+    }
+    return Promise.resolve()
+  }
 }
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index bf0f6a9e79..398121fa3d 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -577,8 +577,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'credentials',
-    summary: 'Abstract credential service.',
-    description: 'Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.',
+    summary: 'Abstract credential service over two key spaces that answer two questions.',
+    description: 'Abstract credential service over two key spaces that answer two questions.\n\nA CredentialRef answers "what is behind this environment-variable name", layered over the process environment, the provider-managed store, and `.env` files. One seam-wide rule binds that half: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.\n\nA CredentialKey answers "what credential does this plugin hold for this id". Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and modifyRecord is the only write path because a correct write depends on the current value (a token refresh is read-decide-replace under one lock).',
     methods: [
       {
         signature: 'abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>',
@@ -602,6 +602,35 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         description: 'Remove one reference from the provider-managed writable source; removing an absent reference is a no-op. Rejects while a read-only source shadows the reference, like set.',
         parameters: [{ name: 'ref', description: 'the reference to remove.' }],
       },
+      {
+        signature: 'abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>',
+        description: 'Read one stored record. The value is returned as its owner wrote it; a GrantRecord payload is not interpreted on the way out.',
+        parameters: [{ name: 'key', description: 'the record to read.' }],
+        returns: 'the record, or `undefined` while none is stored.',
+      },
+      {
+        signature: 'abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>',
+        description: 'Describe one record for configuration surfaces without exposing its value.',
+        parameters: [{ name: 'key', description: 'the record to describe.' }],
+        returns: 'presence, discriminant, and writability.',
+      },
+      {
+        signature: 'abstract listRecords(): Promise<readonly CredentialRecordEntry[]>',
+        description: 'Enumerate every stored record\'s address and tag. Unlike the reference half, which has no enumeration because configuration surfaces learn which references exist from settings schemas, records have no such discovery path: a surface that cannot list them cannot show what a user is authorized for, nor find an orphan left by an uninstalled plugin.',
+        parameters: [],
+        returns: 'every stored record, values excluded.',
+      },
+      {
+        signature: 'abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>, ): Promise<CredentialRecord | undefined>',
+        description: 'Serialized read-modify-write over one record — the only write path. `mutate` sees the record as it stands at the moment the write is exclusive, and returning `undefined` leaves the entry untouched. Exclusion holds across processes where the backing store supports it, which is what makes a token refresh safe: two processes rotating one refresh token concurrently would otherwise lose whichever wrote first.',
+        parameters: [{ name: 'key', description: 'the record to modify.' }, { name: 'mutate', description: 'receives the current record and returns its replacement, or `undefined` to leave it.' }],
+        returns: 'the record after the write, or the current one when `mutate` declined.',
+      },
+      {
+        signature: 'abstract deleteRecord(key: CredentialKey): Promise<void>',
+        description: 'Remove one record; removing an absent record is a no-op.',
+        parameters: [{ name: 'key', description: 'the record to remove.' }],
+      },
     ],
   },
   {
@@ -2473,6 +2502,14 @@ export const EVENT_API: readonly EventApiEntry[] = [
     description: 'A pending Client activation request left the answerable state.',
     parameters: [{ name: 'resolved', description: 'request identity and outcome.' }],
   },
+  {
+    name: 'credentials/record-updated',
+    mode: 'emit',
+    signature: '\'credentials/record-updated\'(key: CredentialKey): void',
+    summary: 'Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage.',
+    description: 'Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.',
+    parameters: [{ name: 'key', description: 'the record whose stored value changed.' }],
+  },
   {
     name: 'credentials/updated',
     mode: 'emit',
@@ -2797,6 +2834,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AgentStatus',
     declaration: 'export type AgentStatus = \'idle\' | \'running\';',
   },
+  {
+    name: 'ApiKeyRecord',
+    declaration: 'export interface ApiKeyRecord {\n    readonly kind: \'api-key\';\n    readonly key?: string;\n    readonly env?: Readonly<Record<string, string>>;\n}',
+  },
   {
     name: 'ApprovalOutcome',
     declaration: 'export type ApprovalOutcome = \'allowed-once\' | \'rejected\' | \'cancelled\' | \'unavailable\';',
@@ -3069,6 +3110,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CredentialInfo',
     declaration: 'export interface CredentialInfo {\n    configured: boolean;\n    source?: string;\n    writable: boolean;\n}',
   },
+  {
+    name: 'CredentialKey',
+    declaration: 'export type CredentialKey = Branded<\'CredentialKey\'>;',
+  },
+  {
+    name: 'CredentialRecord',
+    declaration: 'export type CredentialRecord = ApiKeyRecord | GrantRecord;',
+  },
+  {
+    name: 'CredentialRecordEntry',
+    declaration: 'export interface CredentialRecordEntry {\n    key: CredentialKey;\n    kind: CredentialRecord[\'kind\'];\n}',
+  },
+  {
+    name: 'CredentialRecordInfo',
+    declaration: 'export interface CredentialRecordInfo {\n    configured: boolean;\n    kind?: CredentialRecord[\'kind\'];\n    writable: boolean;\n}',
+  },
   {
     name: 'CredentialRef',
     declaration: 'export type CredentialRef = Branded<\'CredentialRef\'>;',
@@ -3289,6 +3346,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'GoalView',
     declaration: 'export interface GoalView extends GoalSnapshot {\n    readonly roundsStarted: number;\n    readonly createdAt: number;\n    readonly updatedAt: number;\n    readonly activation: GoalActivation;\n}',
   },
+  {
+    name: 'GrantRecord',
+    declaration: 'export interface GrantRecord {\n    readonly kind: \'grant\';\n    readonly payload: unknown;\n}',
+  },
   {
     name: 'ImageAttachmentLimits',
     declaration: 'export interface ImageAttachmentLimits {\n    maxImageBytes: number;\n    maxImagesPerMessage: number;\n    maxMessageImageBytes: number;\n    maxImagePixels: number;\n    maxImageDimension: number;\n    mediaTypes: readonly ImageMediaType[];\n}',
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 0ca2b3d353..3537ed183a 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -18,7 +18,15 @@ import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from
 import { SettingsProvider, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { CredentialProvider } from '@deepseek-ai/dsh-credentials'
-import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+import type {
+  CredentialInfo,
+  CredentialKey,
+  CredentialRecord,
+  CredentialRecordEntry,
+  CredentialRecordInfo,
+  CredentialRef,
+  ResolvedCredential,
+} from '@deepseek-ai/dsh-credentials'
 import type { HostFrame } from '../src/api/index.ts'
 import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
@@ -127,6 +135,31 @@ class MemoryCredentials extends CredentialProvider {
     this.ctx.emit('credentials/updated', ref)
     return Promise.resolve()
   }
+
+  // The record half has no wire face on this proxy, so the double answers the
+  // empty store rather than modelling storage the tests never exercise.
+  readRecord(): Promise<CredentialRecord | undefined> {
+    return Promise.resolve(undefined)
+  }
+
+  describeRecord(): Promise<CredentialRecordInfo> {
+    return Promise.resolve({ configured: false, writable: true })
+  }
+
+  listRecords(): Promise<readonly CredentialRecordEntry[]> {
+    return Promise.resolve([])
+  }
+
+  modifyRecord(
+    _key: CredentialKey,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined> {
+    return mutate(undefined)
+  }
+
+  deleteRecord(): Promise<void> {
+    return Promise.resolve()
+  }
 }
 
 /** Catalog-serving adapter stub for the llm.models path. */
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 4b1f71c5e9..3aa31ba6f0 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -465,7 +465,11 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SettingsDescribeOptions: 'settings.md',
   SettingsUpdateSource: 'settings.md',
   CredentialRef: 'credentials.md',
+  CredentialKey: 'credentials.md',
   CredentialInfo: 'credentials.md',
+  CredentialRecord: 'credentials.md',
+  CredentialRecordEntry: 'credentials.md',
+  CredentialRecordInfo: 'credentials.md',
   ResolvedCredential: 'credentials.md',
   AskUserQuestionAnswer: 'user-questions.md',
   AskUserQuestionRequest: 'user-questions.md',

From 732a7361f570b92d8b8d84580e2d19f2db28a1cb Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 13 Aug 2026 15:33:29 +0800
Subject: [PATCH 21/34] feat(authorization): obtain a credential by asking the
 human
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Some credentials cannot be configured, only obtained: getting one means
a conversation — open this page, paste that code, pick an account. The
new seam owns that conversation and the one-attempt-per-key lifecycle,
and never the protocol, so a second authorization protocol arrives as
another flow rather than as another seam.

A flow is registered under the CredentialKey it writes, which is also
how the seam knows which plugin answers for the format inside that
record. The flow owns the write: run() resolving means the record is
already committed through ctx.credentials, and the seam confirms it.
That keeps a library persisting through its own store adapter the
single writer instead of being copied back out and written twice.

The interaction travels with the request rather than a registry,
because whoever starts an authorization is the one who can talk to the
human about it. A request already withdrawn never claims the key and
never starts the flow — relying on each flow to check its signal before
the first await would let one that does not hang holding the key.
---
 AGENTS.md                                     |   2 +-
 docs/capability-seams.i18n.yaml               |   4 +-
 docs/capability-seams.md                      |   5 +
 docs/capability-seams.zh.md                   |   5 +
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   1 +
 docs/config-catalog.zh.md                     |   1 +
 docs/event-producer-consumer.i18n.yaml        |   4 +-
 docs/event-producer-consumer.md               |   3 +-
 docs/event-producer-consumer.zh.md            |   3 +-
 docs/subsystems/credentials.i18n.yaml         |   4 +-
 docs/subsystems/credentials.md                |  83 +++++
 docs/subsystems/credentials.zh.md             |  83 +++++
 packages/README.md                            |   2 +-
 packages/README.zh.md                         |   2 +-
 packages/credentials/README.i18n.yaml         |   4 +-
 packages/credentials/README.md                |   9 +-
 packages/credentials/README.zh.md             |   9 +-
 .../authorization/README.i18n.yaml            |   6 +
 packages/credentials/authorization/README.md  |  74 ++++
 .../credentials/authorization/README.zh.md    |  74 ++++
 .../credentials/authorization/package.json    |  51 +++
 .../credentials/authorization/src/index.ts    | 324 ++++++++++++++++++
 .../authorization/src/invariant.ts            |  45 +++
 .../credentials/authorization/src/types.ts    |  91 +++++
 .../authorization/tests/authorization.spec.ts | 283 +++++++++++++++
 .../authorization/tests/invariant.spec.ts     |  87 +++++
 .../credentials/authorization/tests/memory.ts |  67 ++++
 .../credentials/authorization/tsconfig.json   |  27 ++
 .../extensions/tool-cordis/src/api-catalog.ts |  94 +++++
 pnpm-lock.yaml                                |  15 +
 scripts/gen-cordis-catalog.ts                 |  13 +
 scripts/gen-doc-graphs.ts                     |   9 +
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.base.json                            |   1 +
 tsconfig.host.json                            |   1 +
 36 files changed, 1468 insertions(+), 23 deletions(-)
 create mode 100644 packages/credentials/authorization/README.i18n.yaml
 create mode 100644 packages/credentials/authorization/README.md
 create mode 100644 packages/credentials/authorization/README.zh.md
 create mode 100644 packages/credentials/authorization/package.json
 create mode 100644 packages/credentials/authorization/src/index.ts
 create mode 100644 packages/credentials/authorization/src/invariant.ts
 create mode 100644 packages/credentials/authorization/src/types.ts
 create mode 100644 packages/credentials/authorization/tests/authorization.spec.ts
 create mode 100644 packages/credentials/authorization/tests/invariant.spec.ts
 create mode 100644 packages/credentials/authorization/tests/memory.ts
 create mode 100644 packages/credentials/authorization/tsconfig.json

diff --git a/AGENTS.md b/AGENTS.md
index 99b31077db..28208b2c87 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,7 +37,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   session/     durable session data: persistence, projection, titles, telemetry
   identity/    anonymous identity
   settings/    user-settings capability + file provider
-  credentials/ credential-reference capability + env/.env provider
+  credentials/ credential/authorization capabilities + env/.env provider
   acp/         automation-only Agent Client Protocol server
   interaction/ approval/interaction capabilities, permission, commands, ask-user
   boot/        shared app-bin glue
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index e696bc3423..dbafe8c766 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.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 docs/capability-seams.md
-capability-seams.md: a84a6d6e0836524e1f39f2fd067ae1f6570741a5
-capability-seams.zh.md: b6b0aba72729f9b9b752347ab00cd76a45c248d9
+capability-seams.md: 9e99ebbdc0e3af22f9939c690ead479d4d20b00c
+capability-seams.zh.md: 611902310e3472e05eaa92985011eb852bbeee6d
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index a84a6d6e08..9e99ebbdc0 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -51,6 +51,8 @@ flowchart LR
   pkg_credentials["credentials"]
   svc_credentials["ctx.credentials<br/>Credential seam"]
   pkg_credentials_local["credentials-local"]
+  pkg_authorization["authorization"]
+  svc_authorization["ctx.authorization<br/>Authorization flow registry"]
   pkg_session_telemetry["session-telemetry"]
   svc_sessionTelemetry["ctx.sessionTelemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -210,6 +212,7 @@ flowchart LR
   pkg_approval --> svc_approval
   pkg_attachment --> svc_attachments
   pkg_attachment_local --> svc_attachments
+  pkg_authorization --> svc_authorization
   pkg_bash_local --> svc_shell
   pkg_bash_sandbox --> svc_shell
   pkg_code_runtime --> svc_codeRuntime
@@ -315,6 +318,7 @@ flowchart LR
   svc_approval --> pkg_tools
   svc_attachments --> pkg_host_runtime
   svc_attachments --> pkg_llm_pi_ai
+  svc_authorization --> pkg_llm_pi_ai
   svc_clientModules --> pkg_hmr
   svc_codeRuntime --> pkg_tools
   svc_compaction --> pkg_compaction_basic
@@ -432,6 +436,7 @@ flowchart LR
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/shell/tool-bash), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`message-feedback`](../packages/feedback/message-feedback) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-file`](../packages/settings/settings-file) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
+| `ctx.authorization` | `seam` | [`authorization`](../packages/credentials/authorization) | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | Flows are registered by the plugin that knows how to obtain one credential and keyed by the record they write; the seam owns the conversation and the one-attempt-per-key lifecycle, never the protocol. |
 | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace), [`message-feedback`](../packages/feedback/message-feedback) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index b6b0aba727..611902310e 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -53,6 +53,8 @@ flowchart LR
   pkg_credentials["credentials"]
   svc_credentials["ctx.credentials<br/>Credential seam"]
   pkg_credentials_local["credentials-local"]
+  pkg_authorization["authorization"]
+  svc_authorization["ctx.authorization<br/>Authorization flow registry"]
   pkg_session_telemetry["session-telemetry"]
   svc_sessionTelemetry["ctx.sessionTelemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -212,6 +214,7 @@ flowchart LR
   pkg_approval --> svc_approval
   pkg_attachment --> svc_attachments
   pkg_attachment_local --> svc_attachments
+  pkg_authorization --> svc_authorization
   pkg_bash_local --> svc_shell
   pkg_bash_sandbox --> svc_shell
   pkg_code_runtime --> svc_codeRuntime
@@ -317,6 +320,7 @@ flowchart LR
   svc_approval --> pkg_tools
   svc_attachments --> pkg_host_runtime
   svc_attachments --> pkg_llm_pi_ai
+  svc_authorization --> pkg_llm_pi_ai
   svc_clientModules --> pkg_hmr
   svc_codeRuntime --> pkg_tools
   svc_compaction --> pkg_compaction_basic
@@ -434,6 +438,7 @@ flowchart LR
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/shell/tool-bash), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`message-feedback`](../packages/feedback/message-feedback) | - | 各后端持久化同一套 SessionEvent 词汇；应用在组合时选择后端。 |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-file`](../packages/settings/settings-file) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | 插件注册命名空间 schema 并解析分层值；提供方存储原始文档。LLM（大语言模型）适配器在用户分区下将其入口配置注册为组合基础；Web 网关提供经过脱敏的分层描述符，并写入用户层。 |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | 配置携带对机密信息的引用；提供方拥有实际值。消费方按操作解析，因此轮换后的凭据会在紧接着的下一次请求中生效；Web 网关提供不含实际值的视图和只写存储。 |
+| `ctx.authorization` | `seam` | [`authorization`](../packages/credentials/authorization) | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | flow 由知道如何取得某份凭据的插件注册，并以其写入的记录为键；seam 拥有这段对话与"每个键同时只跑一次尝试"的生命周期，而非协议本身。 |
 | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace), [`message-feedback`](../packages/feedback/message-feedback) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index cca52f4aee..6ddf964471 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: f4e813238b89ef32c097f9ee274347e37ba11efc
-config-catalog.zh.md: 4eec1d6d172365d9a16f420a639d09a3bbae1147
+config-catalog.md: b93b91f12703ea52225e1202d6cdc376a0b96331
+config-catalog.zh.md: 2562cae37ad4ebce7646b80d7c54cc59bcfd0abf
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f4e813238b..b93b91f127 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3192,6 +3192,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
 - `@deepseek-ai/dsh-api-gateway` — requires `typert` ([`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts))
 - `@deepseek-ai/dsh-api-remotes` ([`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts))
+- `@deepseek-ai/dsh-authorization` — requires `credentials` ([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts))
 - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
 - `@deepseek-ai/dsh-client-modules` — requires `webServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
 - `@deepseek-ai/dsh-client-runtime` ([`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts))
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 4eec1d6d17..2562cae37a 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -3195,6 +3195,7 @@ export interface Config {
 - `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
 - `@deepseek-ai/dsh-api-gateway` — 需要 `typert`（[`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts)）
 - `@deepseek-ai/dsh-api-remotes`（[`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts)）
+- `@deepseek-ai/dsh-authorization` — 需要 `credentials`（[`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)）
 - `@deepseek-ai/dsh-client-locale`（[`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)）
 - `@deepseek-ai/dsh-client-modules` — 需要 `webServer` · `loader`（[`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)）
 - `@deepseek-ai/dsh-client-runtime`（[`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts)）
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index f34d32a007..b7339dbd00 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 11dbce044cdbcae1f7ee49a6b5b4d0d369f80bf8
-event-producer-consumer.zh.md: ef9b7ead7e9951b68cbf84f6031d60411e46480f
+event-producer-consumer.md: f5ead70b691b43bf9de4507d6753e7066c2d2013
+event-producer-consumer.zh.md: 7aa0f03492561e77c94ab36b5da1ee4b4346d861
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 11dbce044c..f5ead70b69 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -22,7 +22,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, `apiproxy`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`emit`) | [`authorization`](../packages/credentials/authorization) |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index ef9b7ead7e..7aa0f03492 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -24,7 +24,8 @@
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, `apiproxy`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`emit`) | [`authorization`](../packages/credentials/authorization) |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 68696cb3d5..6c56090ca1 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 59ab18d3f9fb9db7668f766484fc6a7ac7d3c950
-credentials.zh.md: 5b941c7f360bb3904f91a16bdfd862f5d13d6b39
+credentials.md: aa3230379205eabec0b9e51596bbbbfb7ef491b9
+credentials.zh.md: ce9db1709555950d4f4e30798c560922a54d8674
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 59ab18d3f9..aa32303792 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -57,6 +57,65 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxauthorization--authorizationservice"></a>
+
+### `ctx.authorization` — `AuthorizationService`
+
+`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.
+
+```ts cordis-catalog
+/**
+ * Offer a way to obtain one credential. One flow per key: two plugins
+ * claiming the same key would each write a record in their own format, and
+ * whichever ran last would leave the other reading a payload it cannot parse.
+ *
+ * @param flow - the key it writes, its label, its methods, and its runner.
+ * @returns Disposer that withdraws this flow.
+ * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+ */
+registerFlow(flow: AuthorizationFlow): () => void
+
+/**
+ * Every registered flow, for a surface listing what can be authorized.
+ * @returns one entry per flow, in registration order.
+ */
+list(): readonly AuthorizationEntry[]
+
+/**
+ * One registered flow.
+ * @param key - the credential record to ask about.
+ * @returns the entry, or undefined when no flow claims that key.
+ */
+describe(key: CredentialKey): AuthorizationEntry | undefined
+
+/**
+ * Withdraw the attempt running for a key, if any. Separate from the
+ * request's own signal because a request/response transport answers a Cancel
+ * button on a second call, with no handle on the first one's signal.
+ * @param key - the credential record whose attempt should stop.
+ */
+cancel(key: CredentialKey): void
+
+/**
+ * Run one attempt to authorize a key, and report how it ended.
+ *
+ * One attempt per key at a time. A second caller is refused rather than
+ * joined: the two would be prompting different humans through the same flow,
+ * and the second would answer questions the first was asked.
+ *
+ * @param request - the key, the method, the surface, and the cancel signal.
+ * @returns `authorized` once the flow's record is committed and observed,
+ *   or `cancelled` when the human or the caller withdrew.
+ * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+ *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+ *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+ *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+ */
+async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
+```
+
+Source: [`packages/credentials/authorization/src/index.ts:163`](../../packages/credentials/authorization/src/index.ts)
+
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
@@ -151,6 +210,30 @@ abstract deleteRecord(key: CredentialKey): Promise<void>
 
 Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
 
+<a id="authorization-events"></a>
+
+### `authorization/*` events
+
+<a id="authorizationsettled--emit"></a>
+
+#### `authorization/settled` — emit
+
+One authorization attempt has finished and released its key. Fires for every terminal outcome, failures included, so a surface watching a key it did not start (a second browser tab) learns the attempt is over.
+
+```ts cordis-catalog
+/**
+ * One authorization attempt has finished and released its key. Fires for
+ * every terminal outcome, failures included, so a surface watching a key it
+ * did not start (a second browser tab) learns the attempt is over.
+ * @mode emit
+ * @param key - the credential record the finished attempt was authorizing.
+ * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+ */
+'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void
+```
+
+Source: [`packages/credentials/authorization/src/index.ts:57`](../../packages/credentials/authorization/src/index.ts)
+
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 5b941c7f36..ce9db17095 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -57,6 +57,65 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxauthorization--authorizationservice"></a>
+
+### `ctx.authorization` — `AuthorizationService`
+
+`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.
+
+```ts cordis-catalog
+/**
+ * Offer a way to obtain one credential. One flow per key: two plugins
+ * claiming the same key would each write a record in their own format, and
+ * whichever ran last would leave the other reading a payload it cannot parse.
+ *
+ * @param flow - the key it writes, its label, its methods, and its runner.
+ * @returns Disposer that withdraws this flow.
+ * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+ */
+registerFlow(flow: AuthorizationFlow): () => void
+
+/**
+ * Every registered flow, for a surface listing what can be authorized.
+ * @returns one entry per flow, in registration order.
+ */
+list(): readonly AuthorizationEntry[]
+
+/**
+ * One registered flow.
+ * @param key - the credential record to ask about.
+ * @returns the entry, or undefined when no flow claims that key.
+ */
+describe(key: CredentialKey): AuthorizationEntry | undefined
+
+/**
+ * Withdraw the attempt running for a key, if any. Separate from the
+ * request's own signal because a request/response transport answers a Cancel
+ * button on a second call, with no handle on the first one's signal.
+ * @param key - the credential record whose attempt should stop.
+ */
+cancel(key: CredentialKey): void
+
+/**
+ * Run one attempt to authorize a key, and report how it ended.
+ *
+ * One attempt per key at a time. A second caller is refused rather than
+ * joined: the two would be prompting different humans through the same flow,
+ * and the second would answer questions the first was asked.
+ *
+ * @param request - the key, the method, the surface, and the cancel signal.
+ * @returns `authorized` once the flow's record is committed and observed,
+ *   or `cancelled` when the human or the caller withdrew.
+ * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+ *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+ *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+ *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+ */
+async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
+```
+
+Source: [`packages/credentials/authorization/src/index.ts:163`](../../packages/credentials/authorization/src/index.ts)
+
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
 ### `ctx.credentials` — `CredentialProvider` (abstract seam)
@@ -151,6 +210,30 @@ abstract deleteRecord(key: CredentialKey): Promise<void>
 
 Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
 
+<a id="authorization-events"></a>
+
+### `authorization/*` events
+
+<a id="authorizationsettled--emit"></a>
+
+#### `authorization/settled` — emit
+
+One authorization attempt has finished and released its key. Fires for every terminal outcome, failures included, so a surface watching a key it did not start (a second browser tab) learns the attempt is over.
+
+```ts cordis-catalog
+/**
+ * One authorization attempt has finished and released its key. Fires for
+ * every terminal outcome, failures included, so a surface watching a key it
+ * did not start (a second browser tab) learns the attempt is over.
+ * @mode emit
+ * @param key - the credential record the finished attempt was authorizing.
+ * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+ */
+'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void
+```
+
+Source: [`packages/credentials/authorization/src/index.ts:57`](../../packages/credentials/authorization/src/index.ts)
+
 <a id="credentials-events"></a>
 
 ### `credentials/*` events
diff --git a/packages/README.md b/packages/README.md
index a410d7148d..c455feb384 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -46,7 +46,7 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable API |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable API |
 | [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable API |
-| [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable API |
+| [`credentials/`](credentials/README.md) | Credential reference/record seam + env-over-`.env` provider + authorization flows | Product — stable API |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable API |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable API |
 | [`sdk/`](sdk/README.md) | Out-of-process runtime SDK: JSON-RPC protocol, TypeScript client, and server plugin | Product — stable API |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 780d1356f2..14ab37d08e 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -46,7 +46,7 @@ npm scope 为 `@deepseek-ai/dsh-*`；Cordis `Service` 子类和函数插件通
 | [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、基于日志的标题、会话上报 | 产品：稳定 API |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定 API |
 | [`settings/`](settings/README.md) | 用户设置 seam + 基于文件的提供方 | 产品：稳定 API |
-| [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境变量优先于 `.env` 的提供方 | 产品：稳定 API |
+| [`credentials/`](credentials/README.md) | 凭据引用/记录 seam + 环境变量优先于 `.env` 的提供方 + 授权 flow | 产品：稳定 API |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定 API |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定 API |
 | [`sdk/`](sdk/README.md) | 进程外运行时 SDK：JSON-RPC 协议、TypeScript 客户端和服务器插件 | 产品：稳定 API |
diff --git a/packages/credentials/README.i18n.yaml b/packages/credentials/README.i18n.yaml
index 38cbbb2968..2b34534bfa 100644
--- a/packages/credentials/README.i18n.yaml
+++ b/packages/credentials/README.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 packages/credentials/README.md
-README.md: 75e3941ff6421ca7e41a71ab2bfe8b30209ce598
-README.zh.md: d7c958689fdffc82830a82b04e2a06802bc81634
+README.md: 032f0f38319e276b613241ba89a956a341eaa09c
+README.zh.md: 21e66ef6c8375ef1e4834b05f30901b0e38aebad
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
index 75e3941ff6..032f0f3831 100644
--- a/packages/credentials/README.md
+++ b/packages/credentials/README.md
@@ -1,14 +1,15 @@
-# credentials/ — credential references
+# credentials/ — credentials and authorization
 
 English | [中文](README.zh.md)
 
-The credential capability family separates reference resolution from its provider:
+The credential capability family separates reference resolution from its provider, and separates both from obtaining a credential that has to be asked for:
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`credentials/`](credentials/README.md) | Credential-reference seam | `ctx.credentials` |
+| [`credentials/`](credentials/README.md) | Credential-reference and credential-record seam | `ctx.credentials` |
 | [`credentials-local/`](credentials-local/README.md) | Environment and local-file provider | registers `ctx.credentials` |
+| [`authorization/`](authorization/README.md) | Plugin-owned flows that obtain a credential by asking a human | `ctx.authorization` |
 
-Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics.
+Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics. An authorization flow writes a credential record and is keyed by it, so the two seams meet at the record and nowhere else.
 
 The subsystem reference — `CredentialRef`, per-operation resolution, UI-safe `CredentialInfo`, provider layers — is [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md).
diff --git a/packages/credentials/README.zh.md b/packages/credentials/README.zh.md
index d7c958689f..21e66ef6c8 100644
--- a/packages/credentials/README.zh.md
+++ b/packages/credentials/README.zh.md
@@ -1,14 +1,15 @@
-# credentials/：凭据引用
+# credentials/：凭据与授权
 
 [English](README.md) | 中文
 
-凭据能力家族将引用解析与提供方分离：
+凭据能力家族将引用解析与提供方分离，并把二者与"必须开口去要才能拿到的凭据"再分开：
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
-| [`credentials/`](credentials/README.md) | 凭据引用 seam | `ctx.credentials` |
+| [`credentials/`](credentials/README.md) | 凭据引用与凭据记录 seam | `ctx.credentials` |
 | [`credentials-local/`](credentials-local/README.md) | 环境与本地文件提供方 | 注册 `ctx.credentials` |
+| [`authorization/`](authorization/README.md) | 由插件拥有、通过询问人来取得凭据的 flow | `ctx.authorization` |
 
-配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。
+配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。授权 flow 写入一条凭据记录并以它为键，因此两个 seam 只在记录处相交，别无其他接触面。
 
 子系统参考——`CredentialRef`、按操作解析、对 UI 安全的 `CredentialInfo`、提供方层——见 [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md)。
diff --git a/packages/credentials/authorization/README.i18n.yaml b/packages/credentials/authorization/README.i18n.yaml
new file mode 100644
index 0000000000..cdec37bfab
--- /dev/null
+++ b/packages/credentials/authorization/README.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 packages/credentials/authorization/README.md
+README.md: f73d2231456d0873cef7ea047fe537629a7552e0
+README.zh.md: ecceaa4f90a971deebe89e8dd6e51157aa0072a0
diff --git a/packages/credentials/authorization/README.md b/packages/credentials/authorization/README.md
new file mode 100644
index 0000000000..f73d223145
--- /dev/null
+++ b/packages/credentials/authorization/README.md
@@ -0,0 +1,74 @@
+# dsh-authorization
+
+English | [中文](README.zh.md)
+
+Authorization Service Definition (`ctx.authorization`). Some credentials cannot be configured, only obtained: getting one means a conversation with a human — open this page, paste that code, pick an account. This seam owns that conversation and the lifecycle around it, and never the protocol.
+
+**A flow is a plugin's knowledge of how to get its own credential.** It is registered under the [`CredentialKey`](../credentials/README.md#two-key-spaces-two-questions) it writes, so a flow says which record it produces and, through that key's scope, which plugin answers for the format inside it. A second authorization protocol arrives as another flow, not as another seam.
+
+**The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms it and refuses a flow that resolved without one. Committing inside the flow is what lets a library that persists through its own store adapter stay the single writer instead of being copied back out and written twice.
+
+**The interaction travels with the request, not a registry.** Whoever starts an authorization is the one who can talk to the human about it, so prompts reach exactly the surface that asked and a headless caller supplies an interaction that declines. There is no ambient provider to be absent, and no question about which of two open pages a prompt belongs to.
+
+## Surface
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type { AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+
+declare const ctx: Context
+declare const exchange: (signal: AbortSignal) => Promise<void>
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')
+
+const dispose = ctx.authorization.registerFlow({
+  key,
+  label: 'ChatGPT (Codex)',
+  methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+  async run(session: AuthorizationSession) {
+    session.notify({ message: 'Continue in your browser', url: 'https://auth.example/start' })
+    const code = await session.prompt({ kind: 'text', message: 'Paste the code' })
+    // Commits the record through ctx.credentials before resolving.
+    await exchange(session.signal)
+    void code
+  },
+})
+
+ctx.authorization.list()                    // [{ key, label, methods, inFlight }]
+ctx.authorization.describe(key)             // the same entry, or undefined
+await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
+  key,
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('headless')) },
+})
+ctx.authorization.cancel(key)               // withdraw whatever is running for the key
+dispose()
+```
+
+One attempt per key at a time. A second caller is refused with `ALREADY_IN_FLIGHT` rather than joined, because the two would be prompting different humans through one flow and the second would be answering questions the first was asked. `inFlight` is on the entry so a surface renders the button disabled instead of discovering this by error.
+
+`cancel(key)` exists beside the request's own signal because a request/response transport answers a Cancel button on a second call, holding no handle on the first one's signal. A flow whose registration is disposed mid-attempt is withdrawn the same way: its runner belongs to a plugin that is going away.
+
+An attempt whose caller has already withdrawn never claims the key and never starts the flow — relying on each flow to check its signal before the first await would let one that does not hang holding the key. Validation still runs first, so a caller naming a key or method that does not exist hears about it whether or not it also gave up.
+
+`authorization/settled (key, settlement)` fires after the key is released, for every terminal outcome. `settlement` adds `failed` to the two statuses `begin()` can return: a failure reaches its own caller as a thrown error, so the event stream is the only place a watcher that did not start the attempt can tell a refusal from a breakage.
+
+## The interaction vocabulary
+
+A notice is one-way and never carries a secret: a message, optionally the page the human must open and the code they must enter there. A prompt is a question the flow cannot answer — `text`, `secret`, or `select` — and `secret` differs from `text` only in presentation. A prompt carries its own `signal` so a flow that races a typed code against a browser callback can withdraw the losing question while the attempt continues; the request's signal withdraws the whole attempt instead.
+
+The vocabulary is deliberately smaller than any one provider's: it describes what a surface must render, so a surface that renders one flow renders all of them.
+
+## Model Experience
+
+None, as authorization is a configuration-time conversation with a human and no flow, notice, or prompt reaches a model request.
+
+#### KV Cache effect
+
+No invalidation; no authorization state enters a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **No flow is resumable** — an attempt lives in the process that started it, so a browser reload during a login abandons it and the human starts over. Durable attempts need a store this seam does not have.
+- **Nothing revokes** — signing out is `ctx.credentials.deleteRecord(key)`, which forgets the local record without telling the issuer. A provider that needs a server-side revoke has no place to declare it yet.
+- **A key with no flow is inert** — the seam reports what is registered, so a record left by an uninstalled plugin can be deleted but not re-authorized. Recognizing that orphan is the caller's join, as it is for [`listRecords()`](../credentials/README.md#surface).
diff --git a/packages/credentials/authorization/README.zh.md b/packages/credentials/authorization/README.zh.md
new file mode 100644
index 0000000000..ecceaa4f90
--- /dev/null
+++ b/packages/credentials/authorization/README.zh.md
@@ -0,0 +1,74 @@
+# dsh-authorization
+
+[English](README.md) | 中文
+
+授权 Service Definition（`ctx.authorization`）。有些凭据无法配置，只能获取：拿到它意味着与人对话——打开这个页面、粘贴那个码、选一个账号。本 seam 拥有这段对话及其生命周期，但从不拥有协议本身。
+
+**flow 是某个插件"如何取得自己那份凭据"的知识。** 它以自己写入的 [`CredentialKey`](../credentials/README.md#two-key-spaces-two-questions) 注册，因此 flow 声明了自己产出哪条记录，并通过该键的 scope 声明由哪个插件为记录内部的格式负责。第二种授权协议以另一个 flow 的形式到来，而不是另一个 seam。
+
+**写入由 flow 拥有。** `run()` 返回即表示记录已经通过 `ctx.credentials` 提交；seam 随后核实，并拒绝那些返回时没留下记录的 flow。让提交发生在 flow 内部，才能使一个通过自有 store 适配器持久化的库保持为唯一写入方，而不是把凭据复制出来再写第二遍。
+
+**交互随请求传入，而非注册表。** 发起授权的一方才是能与人对话的一方，因此提示恰好抵达发问的那个界面，无头调用方则传入一个直接拒绝的交互实现。这样既不存在"环境提供方缺席"的问题，也不会出现某个提示该归两个已打开页面中哪一个的疑问。
+
+## 接口
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type { AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+
+declare const ctx: Context
+declare const exchange: (signal: AbortSignal) => Promise<void>
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')
+
+const dispose = ctx.authorization.registerFlow({
+  key,
+  label: 'ChatGPT (Codex)',
+  methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+  async run(session: AuthorizationSession) {
+    session.notify({ message: 'Continue in your browser', url: 'https://auth.example/start' })
+    const code = await session.prompt({ kind: 'text', message: 'Paste the code' })
+    // Commits the record through ctx.credentials before resolving.
+    await exchange(session.signal)
+    void code
+  },
+})
+
+ctx.authorization.list()                    // [{ key, label, methods, inFlight }]
+ctx.authorization.describe(key)             // the same entry, or undefined
+await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
+  key,
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('headless')) },
+})
+ctx.authorization.cancel(key)               // withdraw whatever is running for the key
+dispose()
+```
+
+同一个键同时只允许一次尝试。第二个调用方会收到 `ALREADY_IN_FLIGHT` 拒绝而不是被并入：否则两者会通过同一个 flow 向不同的人发问，而第二个人回答的是问给第一个人的问题。`inFlight` 放在 entry 上，界面据此把按钮渲染为禁用，而不是靠报错才发现。
+
+`cancel(key)` 与请求自带的 signal 并存，是因为请求/响应式传输要用第二次调用来响应"取消"按钮，而它拿不到第一次调用的 signal。注册在尝试进行中被 dispose 的 flow 也以同样方式撤销：它的执行体属于一个正在离开的插件。
+
+调用方在发起前就已撤销的尝试，既不占用该键也不启动 flow——若指望每个 flow 都在首个 await 之前检查自己的 signal，那么没有检查的那个就会占着键一直挂起。校验仍然先执行，因此调用方给出的键或方法不存在时，无论它是否已经放弃都会收到报错。
+
+`authorization/settled (key, settlement)` 在键释放之后触发，覆盖每一种终态。`settlement` 在 `begin()` 能返回的两种状态之外增加了 `failed`：失败以抛出的错误抵达其调用方，因此事件流是未发起该尝试的旁观者唯一能区分"被拒绝"与"出故障"的地方。
+
+## 交互词汇
+
+notice 是单向的，且从不携带机密：一条消息，以及可选的"人需要打开的页面"和"需要在该页面输入的码"。prompt 是 flow 无法自答的问题——`text`、`secret` 或 `select`——其中 `secret` 与 `text` 的差别仅在呈现方式。prompt 自带 `signal`，使得一个让手输码与浏览器回调赛跑的 flow 可以在尝试继续的同时撤下落败的那个问题；撤销整次尝试则用请求的 signal。
+
+这套词汇刻意小于任何单个 provider 的词汇：它描述的是界面必须渲染什么，因此能渲染一个 flow 的界面就能渲染全部 flow。
+
+## Model Experience
+
+无，因为授权是配置期与人的对话，flow、notice 与 prompt 都不会抵达模型请求。
+
+#### KV Cache effect
+
+不失效；任何授权状态都不会进入请求前缀。
+
+## Known Limitations and Deferred Work
+
+- **flow 不可恢复** —— 一次尝试只存活于发起它的进程中，因此登录途中刷新浏览器会丢弃它，人需要重来。可持久的尝试需要一个本 seam 并不具备的存储。
+- **没有吊销** —— 登出即 `ctx.credentials.deleteRecord(key)`，它只遗忘本地记录而不通知签发方。需要服务端吊销的 provider 目前无处声明这一点。
+- **没有 flow 的键是惰性的** —— seam 只报告已注册的内容，因此被卸载插件遗留的记录可以删除但无法重新授权。识别这种孤儿记录由调用方自行 join，与 [`listRecords()`](../credentials/README.md#surface) 的情况相同。
diff --git a/packages/credentials/authorization/package.json b/packages/credentials/authorization/package.json
new file mode 100644
index 0000000000..05f9832e0e
--- /dev/null
+++ b/packages/credentials/authorization/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-authorization",
+  "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
+  "version": "0.0.1-rc.5",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/credentials/authorization"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}
diff --git a/packages/credentials/authorization/src/index.ts b/packages/credentials/authorization/src/index.ts
new file mode 100644
index 0000000000..c88129b7cf
--- /dev/null
+++ b/packages/credentials/authorization/src/index.ts
@@ -0,0 +1,324 @@
+/**
+ * Service Definition for the authorization capability seam (`ctx.authorization`):
+ * obtaining a credential nobody can supply from configuration alone, because
+ * getting it requires a conversation with the human — open this page, paste
+ * that code, pick an account.
+ *
+ * The seam owns the conversation and the lifecycle; it never owns the protocol.
+ * A plugin that knows how to obtain its own credential registers a flow keyed
+ * by the `CredentialKey` that flow writes, and the flow talks to whatever
+ * surface started it through one neutral vocabulary of notices and prompts. So
+ * a second authorization protocol arrives as another flow rather than as
+ * another seam, and a surface that renders one flow renders all of them.
+ *
+ * ```ts
+ * const dispose = ctx.authorization.registerFlow({
+ *   key: credentialKey('llm-pi-ai', 'openai-codex'),
+ *   label: 'ChatGPT (Codex)',
+ *   methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+ *   async run(session) {
+ *     session.notify({ message: 'Continue in your browser', url })
+ *     await commitThroughCredentials(await exchange(session.signal))
+ *   },
+ * })
+ * ```
+ *
+ * @module @deepseek-ai/dsh-authorization
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { CredentialKey } from '@deepseek-ai/dsh-credentials'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+
+import type {
+  AuthorizationEntry, AuthorizationMethod, AuthorizationNotice, AuthorizationOutcome, AuthorizationPrompt,
+  AuthorizationSettlement,
+} from './types.ts'
+
+export type {
+  AuthorizationEntry, AuthorizationMethod, AuthorizationNotice, AuthorizationOutcome, AuthorizationPrompt,
+  AuthorizationPromptOption, AuthorizationSettlement, AuthorizationStatus,
+} from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    authorization: AuthorizationService
+  }
+
+  interface Events {
+    /**
+     * One authorization attempt has finished and released its key. Fires for
+     * every terminal outcome, failures included, so a surface watching a key it
+     * did not start (a second browser tab) learns the attempt is over.
+     * @mode emit
+     * @param key - the credential record the finished attempt was authorizing.
+     * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+     */
+    'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void
+  }
+}
+
+/** Stable error taxonomy for authorization failures. */
+export class AuthorizationError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'AuthorizationError'
+  }
+}
+
+/**
+ * What a running flow is given to talk to the human. Every member is scoped to
+ * one attempt: the flow neither knows nor chooses which surface is listening.
+ */
+export interface AuthorizationSession {
+  /** The method id the caller picked, always one this flow declared. */
+  readonly method: string
+  /** Aborted when the caller withdraws or `cancel()` is called for this key. */
+  readonly signal: AbortSignal
+  /**
+   * Report progress, or tell the human what to do next. Fire-and-forget: a
+   * surface that cannot render a notice must not stall the flow.
+   * @param notice - the message, and any page or code it refers to.
+   */
+  notify(notice: AuthorizationNotice): void
+  /**
+   * Ask the human a question the flow cannot answer for itself.
+   * @param prompt - what to ask, and how it should be presented.
+   * @returns what the human typed, or the chosen option's id.
+   * @throws when the human declines, or the prompt's own signal withdraws it.
+   */
+  prompt(prompt: AuthorizationPrompt): Promise<string>
+}
+
+/**
+ * A plugin's knowledge of how to obtain one credential. The flow owns the
+ * write: `run()` resolving means the record for `key` is committed through
+ * `ctx.credentials`, which the seam then confirms before reporting success.
+ * Committing inside the flow is what lets a library that persists through its
+ * own store adapter (pi-ai's `Models.login()`) stay the single writer instead
+ * of being copied back out and written twice.
+ */
+export interface AuthorizationFlow {
+  /** The credential record this flow writes. Its scope names the owning plugin. */
+  readonly key: CredentialKey
+  /** User-facing name of what is being authorized. */
+  readonly label: string
+  /**
+   * The methods offered, most preferred first; a caller naming none gets the
+   * first. Typed non-empty because a flow with nothing to run is a flow that
+   * cannot be begun, and the type says so at the one place flows are written.
+   */
+  readonly methods: readonly [AuthorizationMethod, ...AuthorizationMethod[]]
+  /**
+   * Run one attempt to obtain and commit the credential.
+   * @param session - the chosen method, the cancellation signal, and the interaction callbacks.
+   * @returns once the record is committed.
+   * @throws when the attempt fails or the human declines.
+   */
+  run(session: AuthorizationSession): Promise<void>
+}
+
+/**
+ * The surface half of one attempt. Supplied with the request rather than
+ * registered, because the caller that starts an authorization is the one that
+ * can talk to the human about it: prompts reach exactly the page that asked,
+ * and a headless caller supplies an interaction that declines.
+ */
+export interface AuthorizationInteraction {
+  /**
+   * Render a notice from the running flow.
+   * @param notice - the message, and any page or code it refers to.
+   */
+  notify(notice: AuthorizationNotice): void
+  /**
+   * Put a question to the human and wait.
+   * @param prompt - what to ask, and how it should be presented.
+   * @returns the typed text, or the chosen option's id.
+   * @throws when the human declines or the prompt is withdrawn.
+   */
+  prompt(prompt: AuthorizationPrompt): Promise<string>
+}
+
+/** One request to authorize a key. */
+export interface AuthorizationRequest {
+  /** The credential record to authorize; a flow must be registered for it. */
+  key: CredentialKey
+  /** Which of the flow's methods to run. Defaults to the flow's first. */
+  method?: string
+  /** The surface that will render this attempt's notices and prompts. */
+  interaction: AuthorizationInteraction
+  /** Withdraws the whole attempt. */
+  signal?: AbortSignal
+}
+
+/** One attempt in flight, with the handle that withdraws it. */
+interface InFlight {
+  readonly controller: AbortController
+}
+
+/**
+ * `ctx.authorization`: a registry of credential-obtaining flows, one attempt at
+ * a time per key.
+ */
+export class AuthorizationService extends Service {
+  /** The commit this seam confirms is a credential-record write, so the store is required, not optional. */
+  static inject = ['credentials']
+
+  private readonly flows = new Map<CredentialKey, AuthorizationFlow>()
+  private readonly running = new Map<CredentialKey, InFlight>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'authorization')
+  }
+
+  /**
+   * Offer a way to obtain one credential. One flow per key: two plugins
+   * claiming the same key would each write a record in their own format, and
+   * whichever ran last would leave the other reading a payload it cannot parse.
+   *
+   * @param flow - the key it writes, its label, its methods, and its runner.
+   * @returns Disposer that withdraws this flow.
+   * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+   */
+  registerFlow(flow: AuthorizationFlow): () => void {
+    const dispose = this.ctx.effect(function* (this: AuthorizationService) {
+      if (this.flows.has(flow.key)) {
+        throw new AuthorizationError(
+          `an authorization flow for "${flow.key}" is already registered`, 'DUPLICATE_FLOW')
+      }
+      this.flows.set(flow.key, flow)
+      yield () => {
+        this.flows.delete(flow.key)
+        // A flow leaving mid-attempt takes its attempt with it: the runner
+        // belongs to a plugin that is going away, so letting it keep prompting
+        // would outlive the fiber that can answer for it.
+        this.running.get(flow.key)?.controller.abort()
+      }
+    }.bind(this), 'authorization.registerFlow()')
+    return () => void dispose()
+  }
+
+  /**
+   * Every registered flow, for a surface listing what can be authorized.
+   * @returns one entry per flow, in registration order.
+   */
+  list(): readonly AuthorizationEntry[] {
+    return [...this.flows.values()].map(flow => this.entry(flow))
+  }
+
+  /**
+   * One registered flow.
+   * @param key - the credential record to ask about.
+   * @returns the entry, or undefined when no flow claims that key.
+   */
+  describe(key: CredentialKey): AuthorizationEntry | undefined {
+    const flow = this.flows.get(key)
+    return flow === undefined ? undefined : this.entry(flow)
+  }
+
+  /** The public view of one registered flow. */
+  private entry(flow: AuthorizationFlow): AuthorizationEntry {
+    return {
+      key: flow.key,
+      label: flow.label,
+      methods: flow.methods,
+      inFlight: this.running.has(flow.key),
+    }
+  }
+
+  /**
+   * Withdraw the attempt running for a key, if any. Separate from the
+   * request's own signal because a request/response transport answers a Cancel
+   * button on a second call, with no handle on the first one's signal.
+   * @param key - the credential record whose attempt should stop.
+   */
+  cancel(key: CredentialKey): void {
+    this.running.get(key)?.controller.abort()
+  }
+
+  /**
+   * Run one attempt to authorize a key, and report how it ended.
+   *
+   * One attempt per key at a time. A second caller is refused rather than
+   * joined: the two would be prompting different humans through the same flow,
+   * and the second would answer questions the first was asked.
+   *
+   * @param request - the key, the method, the surface, and the cancel signal.
+   * @returns `authorized` once the flow's record is committed and observed,
+   *   or `cancelled` when the human or the caller withdrew.
+   * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+   *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+   *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+   *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+   */
+  async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome> {
+    const { key } = request
+    const flow = this.flows.get(key)
+    if (flow === undefined) {
+      throw new AuthorizationError(`no authorization flow is registered for "${key}"`, 'NO_FLOW')
+    }
+    const method = request.method ?? flow.methods[0].id
+    if (!flow.methods.some(candidate => candidate.id === method)) {
+      throw new AuthorizationError(
+        `authorization flow for "${key}" offers no method "${method}"`, 'UNKNOWN_METHOD')
+    }
+    if (this.running.has(key)) {
+      throw new AuthorizationError(
+        `an authorization attempt for "${key}" is already running`, 'ALREADY_IN_FLIGHT')
+    }
+    // Withdrawn before it began: never claim the slot and never run the flow.
+    // Handing an aborted signal to `run()` would rely on every flow checking it
+    // before its first await, and one that does not would hang holding the key.
+    // Validation still runs first, so a caller naming a key or method that does
+    // not exist hears about it whether or not it also gave up.
+    if (request.signal?.aborted === true) return { status: 'cancelled' }
+    const controller = new AbortController()
+    const withdraw = (): void => { controller.abort(request.signal?.reason) }
+    request.signal?.addEventListener('abort', withdraw, { once: true })
+    this.running.set(key, { controller })
+    let settlement: AuthorizationSettlement = 'failed'
+    try {
+      const outcome = await this.attempt(flow, method, controller.signal, request.interaction)
+      settlement = outcome.status
+      return outcome
+    } finally {
+      request.signal?.removeEventListener('abort', withdraw)
+      this.running.delete(key)
+      // After the slot is released, so a listener that reacts by starting the
+      // next attempt is not refused by the one that just finished.
+      this.ctx.emit('authorization/settled', key, settlement)
+    }
+  }
+
+  /** Run the flow, then hold it to its half of the commit contract. */
+  private async attempt(
+    flow: AuthorizationFlow,
+    method: string,
+    signal: AbortSignal,
+    interaction: AuthorizationInteraction,
+  ): Promise<AuthorizationOutcome> {
+    try {
+      await flow.run({
+        method,
+        signal,
+        notify: (notice) => { interaction.notify(notice) },
+        prompt: prompt => interaction.prompt(prompt),
+      })
+    } catch (error) {
+      // A withdrawn attempt is an outcome, not a failure: the human said no, or
+      // closed the page. Anything else is the flow failing and belongs to the
+      // caller, cause chain intact.
+      if (signal.aborted) return { status: 'cancelled' }
+      throw error
+    }
+    const stored = await this.ctx.credentials.describeRecord(flow.key)
+    if (!stored.configured) {
+      throw new AuthorizationError(
+        `authorization flow for "${flow.key}" resolved without committing a credential record`,
+        'NOT_COMMITTED')
+    }
+    return { status: 'authorized' }
+  }
+}
+
+export default AuthorizationService
diff --git a/packages/credentials/authorization/src/invariant.ts b/packages/credentials/authorization/src/invariant.ts
new file mode 100644
index 0000000000..ec89229566
--- /dev/null
+++ b/packages/credentials/authorization/src/invariant.ts
@@ -0,0 +1,45 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-authorization`.
+ * @module @deepseek-ai/dsh-authorization/invariant
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-authorization'
+
+/** Cordis companion plugin name. */
+export const name = 'authorization-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * Install the single-flight release contract: `authorization/settled` names a
+ * finished attempt, and the seam admits one attempt per key, so the key must
+ * already be free when the event fires. A slot still held at settlement is
+ * unrecoverable — every later `begin()` for that key is refused as
+ * `ALREADY_IN_FLIGHT` until the process restarts — and it is invisible from the
+ * outside, because a wedged key looks exactly like a busy one.
+ */
+const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => {
+  ctx.on('authorization/settled', (key) => {
+    const authorization = ctx.get('authorization')
+    if (authorization === undefined) {
+      fail(`authorization/settled for "${key}" emitted without a live authorization service`)
+      return
+    }
+    // A flow withdrawn during its own attempt settles with nothing left to
+    // describe, which is the disposer's documented behavior rather than a leak.
+    if (authorization.describe(key)?.inFlight === true) {
+      fail(`authorization/settled for "${key}" left the key in flight, wedging every later attempt`)
+    }
+  })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/credentials/authorization/src/types.ts b/packages/credentials/authorization/src/types.ts
new file mode 100644
index 0000000000..ea75db8d7c
--- /dev/null
+++ b/packages/credentials/authorization/src/types.ts
@@ -0,0 +1,91 @@
+/**
+ * Wire-safe authorization types, free of cordis/service imports so browser type
+ * chains (apiproxy api → client) can consume them without loading this
+ * package's Context augmentation.
+ * @module @deepseek-ai/dsh-authorization/types
+ */
+
+import type { CredentialKey } from '@deepseek-ai/dsh-credentials/types'
+
+/** One way a flow can obtain its credential, named by the flow that offers it. */
+export interface AuthorizationMethod {
+  /** Flow-owned identifier, echoed back when a caller picks this method. */
+  id: string
+  /** User-facing label for a picker. */
+  label: string
+}
+
+/** A running flow's report to whoever is watching it. Never carries a secret. */
+export interface AuthorizationNotice {
+  /** What is happening, or what the human must do next. */
+  message: string
+  /** A page the human must open to continue. */
+  url?: string
+  /** A short code the human must enter on that page. */
+  code?: string
+}
+
+/** One choice offered by a `select` prompt. */
+export interface AuthorizationPromptOption {
+  /** Value returned when this option is chosen. */
+  id: string
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable surfaces. */
+  description?: string
+}
+
+/**
+ * A question a flow must have answered before it can continue. `secret` differs
+ * from `text` only in presentation — a surface masks it and keeps it out of
+ * logs — and `select` answers with the chosen option's `id`.
+ */
+export type AuthorizationPrompt = {
+  /**
+   * Withdraws this prompt alone, leaving the flow running. A flow that races a
+   * typed code against a browser callback aborts the losing prompt here; the
+   * whole authorization is cancelled through the request's signal instead.
+   */
+  signal?: AbortSignal
+} & ({
+  kind: 'text'
+  message: string
+  placeholder?: string
+} | {
+  kind: 'secret'
+  message: string
+  placeholder?: string
+} | {
+  kind: 'select'
+  message: string
+  options: readonly AuthorizationPromptOption[]
+})
+
+/** How one authorization attempt ended, as its own caller sees it. */
+export type AuthorizationStatus = 'authorized' | 'cancelled'
+
+/**
+ * How one attempt ended, as an onlooker sees it. A failure reaches its caller
+ * as a thrown error rather than an outcome, so `failed` exists only here — on
+ * the event stream, where a watcher that did not start the attempt has no
+ * other way to tell a refusal from a breakage.
+ */
+export type AuthorizationSettlement = AuthorizationStatus | 'failed'
+
+/** The result of one `begin()` attempt. */
+export interface AuthorizationOutcome {
+  /** `authorized` once the record is committed and observed; `cancelled` when the human or caller withdrew. */
+  status: AuthorizationStatus
+}
+
+/** A registered flow as a surface sees it: what it authorizes and whether it is busy. */
+export interface AuthorizationEntry {
+  /** The credential record this flow writes. */
+  key: CredentialKey
+  /** User-facing name of what is being authorized. */
+  label: string
+  /** The methods this flow offers, most preferred first. */
+  methods: readonly AuthorizationMethod[]
+  /** Whether an attempt for this key is running right now. */
+  inFlight: boolean
+}
diff --git a/packages/credentials/authorization/tests/authorization.spec.ts b/packages/credentials/authorization/tests/authorization.spec.ts
new file mode 100644
index 0000000000..f5428f3b75
--- /dev/null
+++ b/packages/credentials/authorization/tests/authorization.spec.ts
@@ -0,0 +1,283 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+import AuthorizationService, {
+  type AuthorizationFlow,
+  type AuthorizationInteraction,
+  type AuthorizationSession,
+} from '@deepseek-ai/dsh-authorization'
+import { MemoryCredentials } from './memory.ts'
+
+const KEY = credentialKey('llm-pi-ai', 'openai-codex')
+const OTHER = credentialKey('llm-pi-ai', 'anthropic')
+
+/** A context with the record store the seam confirms commits against. */
+async function harness(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(MemoryCredentials)
+  await ctx.plugin(AuthorizationService)
+  return ctx
+}
+
+/** An interaction that answers every prompt with the same string. */
+function surface(answer = 'typed'): AuthorizationInteraction & {
+  notices: unknown[]
+  prompts: unknown[]
+} {
+  const notices: unknown[] = []
+  const prompts: unknown[] = []
+  return {
+    notices,
+    prompts,
+    notify: (notice) => { notices.push(notice) },
+    prompt: (prompt) => {
+      prompts.push(prompt)
+      return Promise.resolve(answer)
+    },
+  }
+}
+
+/** A flow that commits `key` through the record store and then resolves. */
+function committingFlow(
+  ctx: Context,
+  key = KEY,
+  run?: (session: AuthorizationSession) => Promise<void>,
+): AuthorizationFlow {
+  return {
+    key,
+    label: 'ChatGPT (Codex)',
+    methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }, { id: 'api-key', label: 'Paste a key' }],
+    async run(session) {
+      await run?.(session)
+      await ctx.credentials.modifyRecord(key, () =>
+        Promise.resolve({ kind: 'grant', payload: { token: 'granted' } }))
+    },
+  }
+}
+
+describe('AuthorizationService registry', () => {
+  it('lists a registered flow and drops it when the registration is disposed', async () => {
+    const ctx = await harness()
+
+    const dispose = ctx.authorization.registerFlow(committingFlow(ctx))
+
+    expect(ctx.authorization.list()).toEqual([{
+      key: KEY,
+      label: 'ChatGPT (Codex)',
+      methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }, { id: 'api-key', label: 'Paste a key' }],
+      inFlight: false,
+    }])
+    expect(ctx.authorization.describe(KEY)?.label).toBe('ChatGPT (Codex)')
+    expect(ctx.authorization.describe(OTHER)).toBeUndefined()
+
+    dispose()
+
+    expect(ctx.authorization.list()).toEqual([])
+    expect(ctx.authorization.describe(KEY)).toBeUndefined()
+  })
+
+  it('refuses a second flow for the same key', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+
+    expect(() => ctx.authorization.registerFlow(committingFlow(ctx)))
+      .toThrow(/already registered/)
+  })
+
+  it('withdraws an attempt still running when its flow leaves', async () => {
+    const ctx = await harness()
+    let started: (() => void) | undefined
+    const running = new Promise<void>((resolve) => {
+      started = resolve
+    })
+    const dispose = ctx.authorization.registerFlow(committingFlow(ctx, KEY, session =>
+      new Promise((_resolve, reject) => {
+        started?.()
+        session.signal.addEventListener('abort', () => { reject(new Error('withdrawn')) }, { once: true })
+      })))
+
+    const attempt = ctx.authorization.begin({ key: KEY, interaction: surface() })
+    await running
+    dispose()
+
+    await expect(attempt).resolves.toEqual({ status: 'cancelled' })
+  })
+})
+
+describe('AuthorizationService.begin', () => {
+  it('runs the flow, confirms the committed record, and reports the settlement', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+    const settled = vi.fn()
+    ctx.on('authorization/settled', settled)
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .resolves.toEqual({ status: 'authorized' })
+
+    expect(await ctx.credentials.readRecord(KEY)).toEqual({ kind: 'grant', payload: { token: 'granted' } })
+    expect(settled).toHaveBeenCalledWith(KEY, 'authorized')
+  })
+
+  it('runs the flow first method when the caller names none, and the named one when it does', async () => {
+    const ctx = await harness()
+    const seen: string[] = []
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, (session) => {
+      seen.push(session.method)
+      return Promise.resolve()
+    }))
+
+    await ctx.authorization.begin({ key: KEY, interaction: surface() })
+    await ctx.authorization.begin({ key: KEY, method: 'api-key', interaction: surface() })
+
+    expect(seen).toEqual(['oauth', 'api-key'])
+  })
+
+  it('carries notices and prompts between the flow and the calling surface', async () => {
+    const ctx = await harness()
+    const answers: string[] = []
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, async (session) => {
+      session.notify({ message: 'Continue in your browser', url: 'https://auth.example/start' })
+      answers.push(await session.prompt({ kind: 'text', message: 'Paste the code' }))
+    }))
+    const ui = surface('code-123')
+
+    await ctx.authorization.begin({ key: KEY, interaction: ui })
+
+    expect(ui.notices).toEqual([{ message: 'Continue in your browser', url: 'https://auth.example/start' }])
+    expect(ui.prompts).toEqual([{ kind: 'text', message: 'Paste the code' }])
+    expect(answers).toEqual(['code-123'])
+  })
+
+  it('refuses a key no flow claims', async () => {
+    const ctx = await harness()
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/no authorization flow is registered/)
+  })
+
+  it('refuses a method the flow does not offer', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+
+    await expect(ctx.authorization.begin({ key: KEY, method: 'device', interaction: surface() }))
+      .rejects.toThrow(/offers no method "device"/)
+  })
+
+  it('refuses a second attempt while one is running, and admits one after it settles', async () => {
+    const ctx = await harness()
+    // Only the first attempt blocks; the later ones must be free to complete,
+    // which is what shows the key was released rather than merely idle-looking.
+    const held = Promise.withResolvers<undefined>()
+    const started = Promise.withResolvers<undefined>()
+    let first = true
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, () => {
+      if (!first) return Promise.resolve()
+      first = false
+      started.resolve(undefined)
+      return held.promise
+    }))
+
+    const attempt = ctx.authorization.begin({ key: KEY, interaction: surface() })
+    await started.promise
+    expect(ctx.authorization.describe(KEY)?.inFlight).toBe(true)
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/already running/)
+
+    held.resolve(undefined)
+    await expect(attempt).resolves.toEqual({ status: 'authorized' })
+    expect(ctx.authorization.describe(KEY)?.inFlight).toBe(false)
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .resolves.toEqual({ status: 'authorized' })
+  })
+
+  it('never starts a flow whose caller withdrew before begin', async () => {
+    const ctx = await harness()
+    const ran = vi.fn()
+    const settled = vi.fn()
+    ctx.on('authorization/settled', settled)
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, () => {
+      ran()
+      return new Promise(() => {})
+    }))
+
+    await expect(ctx.authorization.begin({
+      key: KEY,
+      interaction: surface(),
+      signal: AbortSignal.abort(),
+    })).resolves.toEqual({ status: 'cancelled' })
+
+    expect(ran).not.toHaveBeenCalled()
+    // Nothing occupied the key, so nothing settled on it either.
+    expect(settled).not.toHaveBeenCalled()
+    expect(ctx.authorization.describe(KEY)?.inFlight).toBe(false)
+  })
+
+  it('still reports an unknown method to a caller that already withdrew', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+
+    await expect(ctx.authorization.begin({
+      key: KEY,
+      method: 'device',
+      interaction: surface(),
+      signal: AbortSignal.abort(),
+    })).rejects.toThrow(/offers no method "device"/)
+  })
+
+  it('reports a caller that withdraws mid-flight as cancelled', async () => {
+    const ctx = await harness()
+    const controller = new AbortController()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, session =>
+      new Promise((_resolve, reject) => {
+        session.signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+        controller.abort()
+      })))
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface(), signal: controller.signal }))
+      .resolves.toEqual({ status: 'cancelled' })
+  })
+
+  it('withdraws a running attempt through cancel(), and ignores cancel() for an idle key', async () => {
+    const ctx = await harness()
+    const started = Promise.withResolvers<undefined>()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, session =>
+      new Promise((_resolve, reject) => {
+        session.signal.addEventListener('abort', () => { reject(new Error('cancelled')) }, { once: true })
+        started.resolve(undefined)
+      })))
+    ctx.authorization.cancel(OTHER)
+
+    const attempt = ctx.authorization.begin({ key: KEY, interaction: surface() })
+    await started.promise
+    ctx.authorization.cancel(KEY)
+
+    await expect(attempt).resolves.toEqual({ status: 'cancelled' })
+  })
+
+  it('propagates a flow failure to its caller and settles the key as failed', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, () =>
+      Promise.reject(new Error('the token endpoint said no'))))
+    const settled = vi.fn()
+    ctx.on('authorization/settled', settled)
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow('the token endpoint said no')
+
+    expect(settled).toHaveBeenCalledWith(KEY, 'failed')
+    expect(ctx.authorization.describe(KEY)?.inFlight).toBe(false)
+  })
+
+  it('refuses a flow that resolves without committing its record', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'Forgetful',
+      methods: [{ id: 'oauth', label: 'Sign in' }],
+      run: () => Promise.resolve(),
+    })
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/resolved without committing a credential record/)
+  })
+})
diff --git a/packages/credentials/authorization/tests/invariant.spec.ts b/packages/credentials/authorization/tests/invariant.spec.ts
new file mode 100644
index 0000000000..9f49bdf58a
--- /dev/null
+++ b/packages/credentials/authorization/tests/invariant.spec.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+import InvariantRegistry from '@deepseek-ai/dsh-invariants'
+import AuthorizationService from '@deepseek-ai/dsh-authorization'
+import * as AuthorizationInvariant from '../src/invariant.ts'
+import { MemoryCredentials } from './memory.ts'
+
+const KEY = credentialKey('llm-pi-ai', 'openai-codex')
+
+describe('authorization invariant companion', () => {
+  it('accepts an attempt that released its key before settling', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantRegistry)
+    await ctx.plugin(AuthorizationInvariant)
+    await ctx.plugin(MemoryCredentials)
+    await ctx.plugin(AuthorizationService)
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'ChatGPT (Codex)',
+      methods: [{ id: 'oauth', label: 'Sign in' }],
+      run: () => ctx.credentials
+        .modifyRecord(KEY, () => Promise.resolve({ kind: 'grant', payload: {} }))
+        .then(() => undefined),
+    })
+
+    await expect(ctx.authorization.begin({
+      key: KEY,
+      interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('unused')) },
+    })).resolves.toEqual({ status: 'authorized' })
+  })
+
+  it('fails a settlement that left its key in flight', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantRegistry)
+    await ctx.plugin(AuthorizationInvariant)
+    await ctx.plugin(MemoryCredentials)
+    await ctx.plugin(AuthorizationService)
+    const started = Promise.withResolvers<undefined>()
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'ChatGPT (Codex)',
+      methods: [{ id: 'oauth', label: 'Sign in' }],
+      run: () => {
+        started.resolve(undefined)
+        return new Promise(() => {})
+      },
+    })
+    void ctx.authorization.begin({
+      key: KEY,
+      interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('unused')) },
+    })
+    await started.promise
+
+    expect(() => { ctx.emit('authorization/settled', KEY, 'authorized') })
+      .toThrow(/left the key in flight/)
+  })
+
+  it('fails a settlement emitted without a live service', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantRegistry)
+    await ctx.plugin(AuthorizationInvariant)
+
+    expect(() => { ctx.emit('authorization/settled', KEY, 'cancelled') })
+      .toThrow(/without a live authorization service/)
+  })
+
+  it('accepts a settlement whose flow left during its own attempt', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantRegistry)
+    await ctx.plugin(AuthorizationInvariant)
+    await ctx.plugin(MemoryCredentials)
+    await ctx.plugin(AuthorizationService)
+
+    expect(() => { ctx.emit('authorization/settled', KEY, 'cancelled') }).not.toThrow()
+  })
+
+  it('reserves the package name against duplicate registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantRegistry)
+    await ctx.plugin(AuthorizationInvariant)
+
+    expect(() => {
+      ctx.invariants.register('@deepseek-ai/dsh-authorization', () => {})
+    }).toThrow(/already registered/)
+  })
+})
diff --git a/packages/credentials/authorization/tests/memory.ts b/packages/credentials/authorization/tests/memory.ts
new file mode 100644
index 0000000000..94ebe091d2
--- /dev/null
+++ b/packages/credentials/authorization/tests/memory.ts
@@ -0,0 +1,67 @@
+import { CredentialProvider } from '@deepseek-ai/dsh-credentials'
+import type {
+  CredentialInfo,
+  CredentialKey,
+  CredentialRecord,
+  CredentialRecordEntry,
+  CredentialRecordInfo,
+  CredentialRef,
+  ResolvedCredential,
+} from '@deepseek-ai/dsh-credentials'
+
+/**
+ * In-memory credentials provider for the authorization suite. Only the record
+ * half is exercised — the seam's whole interest in this service is whether a
+ * flow left a record behind — so the reference half answers "nothing stored".
+ */
+export class MemoryCredentials extends CredentialProvider {
+  private readonly records = new Map<CredentialKey, CredentialRecord>()
+
+  override resolve(_ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+    return Promise.resolve(undefined)
+  }
+
+  override describe(_ref: CredentialRef): Promise<CredentialInfo> {
+    return Promise.resolve({ configured: false, writable: true })
+  }
+
+  override set(_ref: CredentialRef, _value: string): Promise<void> {
+    return Promise.resolve()
+  }
+
+  override unset(_ref: CredentialRef): Promise<void> {
+    return Promise.resolve()
+  }
+
+  override readRecord(key: CredentialKey): Promise<CredentialRecord | undefined> {
+    return Promise.resolve(this.records.get(key))
+  }
+
+  override describeRecord(key: CredentialKey): Promise<CredentialRecordInfo> {
+    const stored = this.records.get(key)
+    return Promise.resolve(stored === undefined
+      ? { configured: false, writable: true }
+      : { configured: true, kind: stored.kind, writable: true })
+  }
+
+  override listRecords(): Promise<readonly CredentialRecordEntry[]> {
+    return Promise.resolve([...this.records].map(([key, record]) => ({ key, kind: record.kind })))
+  }
+
+  override async modifyRecord(
+    key: CredentialKey,
+    mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>,
+  ): Promise<CredentialRecord | undefined> {
+    const current = this.records.get(key)
+    const next = await mutate(current)
+    if (next === undefined) return current
+    this.records.set(key, next)
+    this.ctx.emit('credentials/record-updated', key)
+    return next
+  }
+
+  override deleteRecord(key: CredentialKey): Promise<void> {
+    if (this.records.delete(key)) this.ctx.emit('credentials/record-updated', key)
+    return Promise.resolve()
+  }
+}
diff --git a/packages/credentials/authorization/tsconfig.json b/packages/credentials/authorization/tsconfig.json
new file mode 100644
index 0000000000..cdf84f6f5d
--- /dev/null
+++ b/packages/credentials/authorization/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../credentials"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../runtime-diagnostics/invariants"
+    }
+  ]
+}
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 398121fa3d..78b9368986 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -457,6 +457,44 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'authorization',
+    summary: '`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.',
+    description: '`ctx.authorization`: a registry of credential-obtaining flows, one attempt at a time per key.',
+    methods: [
+      {
+        signature: 'registerFlow(flow: AuthorizationFlow): () => void',
+        description: 'Offer a way to obtain one credential. One flow per key: two plugins claiming the same key would each write a record in their own format, and whichever ran last would leave the other reading a payload it cannot parse.',
+        parameters: [{ name: 'flow', description: 'the key it writes, its label, its methods, and its runner.' }],
+        returns: 'Disposer that withdraws this flow.',
+        throws: ['{AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.'],
+      },
+      {
+        signature: 'list(): readonly AuthorizationEntry[]',
+        description: 'Every registered flow, for a surface listing what can be authorized.',
+        parameters: [],
+        returns: 'one entry per flow, in registration order.',
+      },
+      {
+        signature: 'describe(key: CredentialKey): AuthorizationEntry | undefined',
+        description: 'One registered flow.',
+        parameters: [{ name: 'key', description: 'the credential record to ask about.' }],
+        returns: 'the entry, or undefined when no flow claims that key.',
+      },
+      {
+        signature: 'cancel(key: CredentialKey): void',
+        description: 'Withdraw the attempt running for a key, if any. Separate from the request\'s own signal because a request/response transport answers a Cancel button on a second call, with no handle on the first one\'s signal.',
+        parameters: [{ name: 'key', description: 'the credential record whose attempt should stop.' }],
+      },
+      {
+        signature: 'async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>',
+        description: 'Run one attempt to authorize a key, and report how it ended.\n\nOne attempt per key at a time. A second caller is refused rather than joined: the two would be prompting different humans through the same flow, and the second would answer questions the first was asked.',
+        parameters: [{ name: 'request', description: 'the key, the method, the surface, and the cancel signal.' }],
+        returns: '`authorized` once the flow\'s record is committed and observed, or `cancelled` when the human or the caller withdrew.',
+        throws: ['{AuthorizationError} code `NO_FLOW` when nothing claims the key, `UNKNOWN_METHOD` when the named method is not one the flow offers, `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or `NOT_COMMITTED` when the flow resolved without leaving a record behind.'],
+      },
+    ],
+  },
   {
     key: 'clientModules',
     summary: 'The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows.',
@@ -2446,6 +2484,14 @@ export const EVENT_API: readonly EventApiEntry[] = [
     description: 'Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.',
     parameters: [{ name: 'req', description: 'the pending decision (agent, tool identity, reason, signal).' }],
   },
+  {
+    name: 'authorization/settled',
+    mode: 'emit',
+    signature: '\'authorization/settled\'(key: CredentialKey, settlement: AuthorizationSettlement): void',
+    summary: 'One authorization attempt has finished and released its key.',
+    description: 'One authorization attempt has finished and released its key. Fires for every terminal outcome, failures included, so a surface watching a key it did not start (a second browser tab) learns the attempt is over.',
+    parameters: [{ name: 'key', description: 'the credential record the finished attempt was authorizing.' }, { name: 'settlement', description: 'how it ended, including the `failed` case its caller sees as a thrown error.' }],
+  },
   {
     name: 'commands/change',
     mode: 'emit',
@@ -2902,6 +2948,54 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AttachmentId',
     declaration: 'export type AttachmentId = Branded<\'AttachmentId\'>;',
   },
+  {
+    name: 'AuthorizationEntry',
+    declaration: 'export interface AuthorizationEntry {\n    key: CredentialKey;\n    label: string;\n    methods: readonly AuthorizationMethod[];\n    inFlight: boolean;\n}',
+  },
+  {
+    name: 'AuthorizationFlow',
+    declaration: 'export interface AuthorizationFlow {\n    readonly key: CredentialKey;\n    readonly label: string;\n    readonly methods: readonly [\n        AuthorizationMethod,\n        ...AuthorizationMethod[]\n    ];\n    run(session: AuthorizationSession): Promise<void>;\n}',
+  },
+  {
+    name: 'AuthorizationInteraction',
+    declaration: 'export interface AuthorizationInteraction {\n    notify(notice: AuthorizationNotice): void;\n    prompt(prompt: AuthorizationPrompt): Promise<string>;\n}',
+  },
+  {
+    name: 'AuthorizationMethod',
+    declaration: 'export interface AuthorizationMethod {\n    id: string;\n    label: string;\n}',
+  },
+  {
+    name: 'AuthorizationNotice',
+    declaration: 'export interface AuthorizationNotice {\n    message: string;\n    url?: string;\n    code?: string;\n}',
+  },
+  {
+    name: 'AuthorizationOutcome',
+    declaration: 'export interface AuthorizationOutcome {\n    status: AuthorizationStatus;\n}',
+  },
+  {
+    name: 'AuthorizationPrompt',
+    declaration: 'export type AuthorizationPrompt = {\n    signal?: AbortSignal;\n} & ({\n    kind: \'text\';\n    message: string;\n    placeholder?: string;\n} | {\n    kind: \'secret\';\n    message: string;\n    placeholder?: string;\n} | {\n    kind: \'select\';\n    message: string;\n    options: readonly AuthorizationPromptOption[];\n});',
+  },
+  {
+    name: 'AuthorizationPromptOption',
+    declaration: 'export interface AuthorizationPromptOption {\n    id: string;\n    label: string;\n    description?: string;\n}',
+  },
+  {
+    name: 'AuthorizationRequest',
+    declaration: 'export interface AuthorizationRequest {\n    key: CredentialKey;\n    method?: string;\n    interaction: AuthorizationInteraction;\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'AuthorizationSession',
+    declaration: 'export interface AuthorizationSession {\n    readonly method: string;\n    readonly signal: AbortSignal;\n    notify(notice: AuthorizationNotice): void;\n    prompt(prompt: AuthorizationPrompt): Promise<string>;\n}',
+  },
+  {
+    name: 'AuthorizationSettlement',
+    declaration: 'export type AuthorizationSettlement = AuthorizationStatus | \'failed\';',
+  },
+  {
+    name: 'AuthorizationStatus',
+    declaration: 'export type AuthorizationStatus = \'authorized\' | \'cancelled\';',
+  },
   {
     name: 'BackendRegistry',
     declaration: 'export class BackendRegistry {\n    register(name: string, backend: StorageBackend): () => void;\n    get(name: string): StorageBackend;\n    names(): string[];\n}',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 74c628dd01..3c5eab9c8f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3802,6 +3802,21 @@ importers:
         specifier: workspace:^
         version: link:../../interaction/user-approval
 
+  packages/credentials/authorization:
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-credentials':
+        specifier: workspace:^
+        version: link:../credentials
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../runtime-diagnostics/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+
   packages/credentials/credentials:
     devDependencies:
       '@deepseek-ai/cordis':
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 3aa31ba6f0..483518efd1 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -64,6 +64,7 @@ export const SERVICE_PAGE: Record<string, string> = {
   commands: 'commands.md',
   compaction: 'compaction.md',
   cordisInspect: 'extensions.md',
+  authorization: 'credentials.md',
   credentials: 'credentials.md',
   directoryPicker: 'workspace.md',
   dynamicCordisRunner: 'extensions.md',
@@ -172,6 +173,7 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'approval': 'approval.md',
   'commands': 'commands.md',
   'cordis': 'extensions.md',
+  'authorization': 'credentials.md',
   'credentials': 'credentials.md',
   'domain': 'storage.md',
   'fs': 'filesystem.md',
@@ -464,6 +466,17 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SettingsPathOp: 'settings.md',
   SettingsDescribeOptions: 'settings.md',
   SettingsUpdateSource: 'settings.md',
+  AuthorizationEntry: 'credentials.md',
+  AuthorizationFlow: 'credentials.md',
+  AuthorizationInteraction: 'credentials.md',
+  AuthorizationMethod: 'credentials.md',
+  AuthorizationNotice: 'credentials.md',
+  AuthorizationOutcome: 'credentials.md',
+  AuthorizationPrompt: 'credentials.md',
+  AuthorizationRequest: 'credentials.md',
+  AuthorizationSession: 'credentials.md',
+  AuthorizationSettlement: 'credentials.md',
+  AuthorizationStatus: 'credentials.md',
   CredentialRef: 'credentials.md',
   CredentialKey: 'credentials.md',
   CredentialInfo: 'credentials.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 420bad476c..5e19c20113 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -189,6 +189,15 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
     note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
   },
+  {
+    key: 'authorization',
+    pkg: 'authorization',
+    title: 'Authorization flow registry',
+    mode: 'seam',
+    implementations: [],
+    consumers: ['llm-pi-ai'],
+    note: 'Flows are registered by the plugin that knows how to obtain one credential and keyed by the record they write; the seam owns the conversation and the one-attempt-per-key lifecycle, never the protocol.',
+  },
   {
     key: 'sessionTelemetry',
     pkg: 'session-telemetry',
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 31399faf35..02d0e66c0e 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -133,6 +133,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/settings/settings-file': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model-facing behavior.' },
   'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model-facing use a value authorizes.' },
   'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model-facing behavior.' },
+  'packages/credentials/authorization': { kind: 'none', reason: 'A configuration-time conversation with a human; no flow, notice, or prompt reaches a model request.' },
   'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers nothing model-facing.' },
   'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers nothing model-facing.' },
   'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers nothing model-facing.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 91e623e2d1..8d8d5e1433 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -83,6 +83,7 @@
       "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"],
       "@deepseek-ai/dsh-jobs/brand": ["./packages/jobs/jobs/src/brand.ts"],
       "@deepseek-ai/dsh-credentials/types": ["./packages/credentials/credentials/src/types.ts"],
+      "@deepseek-ai/dsh-authorization/types": ["./packages/credentials/authorization/src/types.ts"],
       "@deepseek-ai/dsh-settings/types": ["./packages/settings/settings/src/types.ts"],
       "@deepseek-ai/dsh-api-remotes/types": ["./packages/api/remotes/src/types.ts"],
       "@deepseek-ai/dsh-api-remotes/invariant": ["./packages/api/remotes/src/invariant.ts"],
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 95036f727c..f37b98ea57 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -154,6 +154,7 @@
     { "path": "./packages/settings/settings-file" },
     { "path": "./packages/credentials/credentials" },
     { "path": "./packages/credentials/credentials-local" },
+    { "path": "./packages/credentials/authorization" },
     { "path": "./packages/session-query/tool-session-query" },
     { "path": "./packages/storage/storage" },
     { "path": "./packages/storage/storage-json" },

From 57c5f017ac3996ba19c0538c0770bf8db86a64ff Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 13 Aug 2026 15:54:47 +0800
Subject: [PATCH 22/34] feat(llm-pi-ai): sign in to a provider instead of
 withholding it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pi-ai's auth model reaches this adapter through three translations, all
of which live here: a CredentialStore over the harness credential
records, an AuthContext over the credential plane and the host
filesystem, and one authorization flow per installed provider that
ships a login. The seams they consume name nothing from pi-ai, so a
second adapter family can arrive with a different auth model and share
them.

Every collection is now built with the store and the context rather
than with nothing, which is what makes a signed-in provider stay signed
in across the collection rebuild a configuration change causes. With a
posture that works, the configurable-provider directory no longer
withholds OAuth-only routes and `openai-codex` is offered again; the
predicate that withheld it is gone.

The credential plane stays optional. Reads answer "nothing stored"
without a credentials service because such a composition genuinely
holds no credential, while writes refuse by name — a login whose grant
evaporated would report success and then fail every request. Flow
registration is scoped to the authorization seam, so a headless or ACP
composition mounts with no sign-in and everything else unchanged.

Two fixes found while wiring this up: pre-release credential fixtures
in the llm suites still used the flat document the record work
replaced, and a flow that ignores its cancellation signal would have
held its key for the life of the process — withdrawal now settles the
attempt either way.
---
 docs/subsystems/credentials.i18n.yaml         |   4 +-
 docs/subsystems/credentials.md                |   2 +-
 docs/subsystems/credentials.zh.md             |   2 +-
 .../credentials/authorization/src/index.ts    |  29 ++-
 .../authorization/tests/authorization.spec.ts |  23 ++
 packages/credentials/credentials/src/index.ts |  25 ++-
 .../llm/llm-deepseek/tests/adapter.e2e.ts     |   2 +-
 .../llm-deepseek/tests/dynamic-config.spec.ts |   4 +-
 .../tests/loader-composition.spec.ts          |   4 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |   4 +-
 packages/llm/llm-pi-ai/README.md              |  17 +-
 packages/llm/llm-pi-ai/README.zh.md           |  17 +-
 packages/llm/llm-pi-ai/package.json           |   2 +
 packages/llm/llm-pi-ai/src/adapter.ts         |  34 ++-
 packages/llm/llm-pi-ai/src/auth.ts            | 190 +++++++++++++++++
 packages/llm/llm-pi-ai/src/catalog.ts         |  20 --
 packages/llm/llm-pi-ai/src/index.ts           |  38 ++--
 packages/llm/llm-pi-ai/src/login.ts           | 150 +++++++++++++
 packages/llm/llm-pi-ai/tests/adapter.spec.ts  |   2 +
 packages/llm/llm-pi-ai/tests/auth-double.ts   |  39 ++++
 packages/llm/llm-pi-ai/tests/auth.spec.ts     | 155 ++++++++++++++
 packages/llm/llm-pi-ai/tests/catalog.spec.ts  |  32 ++-
 .../llm-pi-ai/tests/dynamic-config.spec.ts    |  36 +++-
 .../tests/loader-composition.spec.ts          |   2 +-
 packages/llm/llm-pi-ai/tests/login.spec.ts    | 198 ++++++++++++++++++
 .../llm/llm-pi-ai/tests/sdk-options.spec.ts   |   2 +
 packages/llm/llm-pi-ai/tsconfig.json          |   3 +
 pnpm-lock.yaml                                |   6 +
 python/sdk-runtime/package.json               |   1 +
 29 files changed, 941 insertions(+), 102 deletions(-)
 create mode 100644 packages/llm/llm-pi-ai/src/auth.ts
 create mode 100644 packages/llm/llm-pi-ai/src/login.ts
 create mode 100644 packages/llm/llm-pi-ai/tests/auth-double.ts
 create mode 100644 packages/llm/llm-pi-ai/tests/auth.spec.ts
 create mode 100644 packages/llm/llm-pi-ai/tests/login.spec.ts

diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 6c56090ca1..e2526345a5 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: aa3230379205eabec0b9e51596bbbbfb7ef491b9
-credentials.zh.md: ce9db1709555950d4f4e30798c560922a54d8674
+credentials.md: dd0f950b50fa4bcb9094f7b85227262b42e3b385
+credentials.zh.md: 3e906449db31d4889d8c87f27c765cccfc9ff539
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index aa32303792..dd0f950b50 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -208,7 +208,7 @@ abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord |
 abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:164`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="authorization-events"></a>
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index ce9db17095..3e906449db 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -208,7 +208,7 @@ abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord |
 abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:141`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:164`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="authorization-events"></a>
 
diff --git a/packages/credentials/authorization/src/index.ts b/packages/credentials/authorization/src/index.ts
index c88129b7cf..9cff052feb 100644
--- a/packages/credentials/authorization/src/index.ts
+++ b/packages/credentials/authorization/src/index.ts
@@ -297,13 +297,30 @@ export class AuthorizationService extends Service {
     signal: AbortSignal,
     interaction: AuthorizationInteraction,
   ): Promise<AuthorizationOutcome> {
+    // Withdrawal settles the attempt whether or not the flow reacts to it. A
+    // flow is supposed to stop when its signal fires, but one that does not
+    // would otherwise hold the key for the life of the process, and a wedged
+    // key is indistinguishable from a busy one from the outside. The orphaned
+    // run is left to finish on its own; nothing waits on it, and a record it
+    // still manages to commit is a record the human did authorize.
+    const withdrawn = new Promise<'withdrawn'>((resolve) => {
+      // `begin()` returns before claiming the key when its caller has already
+      // withdrawn, so this signal cannot already be aborted here.
+      signal.addEventListener('abort', () => { resolve('withdrawn') }, { once: true })
+    })
+    const running = flow.run({
+      method,
+      signal,
+      notify: (notice) => { interaction.notify(notice) },
+      prompt: prompt => interaction.prompt(prompt),
+    })
     try {
-      await flow.run({
-        method,
-        signal,
-        notify: (notice) => { interaction.notify(notice) },
-        prompt: prompt => interaction.prompt(prompt),
-      })
+      if (await Promise.race([running.then(() => 'ran' as const), withdrawn]) === 'withdrawn') {
+        // Nothing awaits the orphan any more, so its eventual failure has to be
+        // marked handled or it would take down the process.
+        void running.catch(() => { this.ctx.logger.debug('authorization: withdrawn flow failed after the fact') })
+        return { status: 'cancelled' }
+      }
     } catch (error) {
       // A withdrawn attempt is an outcome, not a failure: the human said no, or
       // closed the page. Anything else is the flow failing and belongs to the
diff --git a/packages/credentials/authorization/tests/authorization.spec.ts b/packages/credentials/authorization/tests/authorization.spec.ts
index f5428f3b75..286c99898b 100644
--- a/packages/credentials/authorization/tests/authorization.spec.ts
+++ b/packages/credentials/authorization/tests/authorization.spec.ts
@@ -254,6 +254,29 @@ describe('AuthorizationService.begin', () => {
     await expect(attempt).resolves.toEqual({ status: 'cancelled' })
   })
 
+  it('settles a withdrawn attempt even when its flow never reacts to the signal', async () => {
+    const ctx = await harness()
+    const orphan = Promise.withResolvers<undefined>()
+    const started = Promise.withResolvers<undefined>()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, () => {
+      started.resolve(undefined)
+      return orphan.promise
+    }))
+
+    const attempt = ctx.authorization.begin({ key: KEY, interaction: surface() })
+    await started.promise
+    ctx.authorization.cancel(KEY)
+
+    await expect(attempt).resolves.toEqual({ status: 'cancelled' })
+    // The key is free again immediately, rather than at the mercy of a flow
+    // that may never settle.
+    expect(ctx.authorization.describe(KEY)?.inFlight).toBe(false)
+    // The orphan's own failure is nobody's to await, and must not surface as an
+    // unhandled rejection.
+    orphan.reject(new Error('gave up long after the human left'))
+    await expect(orphan.promise).rejects.toThrow('gave up long after the human left')
+  })
+
   it('propagates a flow failure to its caller and settles the key as failed', async () => {
     const ctx = await harness()
     ctx.authorization.registerFlow(committingFlow(ctx, KEY, () =>
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index 951448f8a3..3934f51754 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -24,12 +24,25 @@ const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/
  * @returns the branded reference.
  */
 export function credentialRef(value: string): CredentialRef {
-  if (!REF_PATTERN.test(value)) {
+  if (!isCredentialRefName(value)) {
     throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`)
   }
   return value as CredentialRef
 }
 
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export function isCredentialRefName(value: string): boolean {
+  return REF_PATTERN.test(value)
+}
+
 /**
  * Brand a scope and an id as a {@link CredentialKey}.
  * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
@@ -75,6 +88,16 @@ export function credentialKeyScope(key: CredentialKey): string {
   return key.slice(0, key.indexOf('/'))
 }
 
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export function credentialKeyId(key: CredentialKey): string {
+  return key.slice(key.indexOf('/') + 1)
+}
+
 /** One resolved credential value and the source layer that supplied it. */
 export interface ResolvedCredential {
   /** The non-empty secret value. */
diff --git a/packages/llm/llm-deepseek/tests/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
index 19ce411406..a50606b568 100644
--- a/packages/llm/llm-deepseek/tests/adapter.e2e.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
@@ -72,7 +72,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', ()
     try {
       // JSON.stringify quotes the value: YAML is a JSON superset, so a real
       // key survives whatever characters it happens to carry.
-      await writeFile(join(dir, '.credentials.yaml'), `DEEPSEEK_API_KEY: ${JSON.stringify(key)}\n`, { mode: 0o600 })
+      await writeFile(join(dir, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${JSON.stringify(key)}\n`, { mode: 0o600 })
       // Scrub the ambient variable so only the credential seam can supply the
       // key: this request proves the per-request resolution path end to end.
       vi.stubEnv('DEEPSEEK_API_KEY', '')
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index be7d4e3688..d28c853c3a 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -100,7 +100,7 @@ describe('request-level dynamic configuration', () => {
   it('routes the next request with the freshly resolved base URL and credential', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: first-key\n', { mode: 0o600 })
+    await writeFile(join(dir, '.credentials.yaml'), 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: first-key\n', { mode: 0o600 })
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await boot(dir, { baseURL: serverA.url })
@@ -258,7 +258,7 @@ describe('request-level dynamic configuration', () => {
   it('falls back to the composition entry when settings detach', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: steady-key\n', { mode: 0o600 })
+    await writeFile(join(dir, '.credentials.yaml'), 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: steady-key\n', { mode: 0o600 })
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx, settingsFiber } = await boot(dir, { baseURL: serverA.url })
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index 1398d36110..ec83345b61 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -53,7 +53,7 @@ async function loadComposition(
   const credentialsPath = join(root, '.credentials.yaml')
   if (options.withDynamic && fresh) {
     await writeFile(settingsPath, '# personal settings\n')
-    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: boot-key\n', { mode: 0o600 })
+    await writeFile(credentialsPath, 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: boot-key\n', { mode: 0o600 })
   }
 
   const configPath = join(root, 'cordis.yml')
@@ -124,7 +124,7 @@ describe('llm-deepseek real dynamic composition', () => {
     await vi.waitFor(() => {
       expect((ctx.get('settings')!.get(NS) as { baseURL?: string }).baseURL).toBe(serverB.url)
     }, { timeout: 5000 })
-    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: rotated-key\n', { mode: 0o600 })
+    await writeFile(credentialsPath, 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: rotated-key\n', { mode: 0o600 })
     await vi.waitFor(async () => {
       expect(await ctx.get('credentials')!.resolve(KEY_REF)).toEqual({ value: 'rotated-key', source: 'file' })
     }, { timeout: 5000 })
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 6ea69058b9..19db6eb0fb 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/README.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 packages/llm/llm-pi-ai/README.md
-README.md: 6d62aabf954a80120bacc9049a7498af269dd067
-README.zh.md: e7e832fa356c48bf14d7aebac7351b259b924214
+README.md: 45b4815cb35e8709a6dc6cf4c50b778d2c2113f9
+README.zh.md: a1e952b70d9361e945b37ed146035fa274185003
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 6d62aabf95..45b4815cb3 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -8,7 +8,7 @@ The package root exposes the Cordis plugin contract, `PiAiAdapter`, and `support
 
 ## Config
 
-Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. Each profile may set a `retryPolicy`; omission uses normal mode with five retries. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
+Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
 
 ```yaml
 - id: llm
@@ -120,7 +120,7 @@ A model that carries reasoning metadata — from the installed catalog or from i
 
 A model **without** that metadata — a hand-declared one whose entry declares no `reasoningEfforts`, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, `maxRequestImageBytes`, and `retryPolicy`. Each resolved profile retry policy is captured with that provider route; omission uses the shared bounded normal default of five retries. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. `maxRequestImageBytes` bounds one request's base64-encoded image payload (default 20MiB, a positive integer): every image in history is re-encoded into every request, so when the accumulated payload exceeds the bound, the oldest images are replaced by a fixed text placeholder until the request fits, keeping an image-heavy session serviceable instead of permanently rejected by a gateway request-size cap. The default leaves capacity for system prompts, history, tools, and JSON; deployments behind stricter gateways lower it per route. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
@@ -170,15 +170,15 @@ pi-ai installs several provider SDKs and lazy-loads the one selected by the cata
 
 #### What the model sees
 
-The selected catalog model receives `GenerateOptions.system`, history, tools, and sampling fields supported by pi-ai's common streaming API. This package adds no prompt prose, with one exception: when a request's accumulated base64 image payload exceeds the route's `maxRequestImageBytes`, each offloaded image (oldest first) is replaced by fixed text. The text tells the model to read the file again when a path is available or ask the user to attach the image again. Provider-native replay metadata is restored only when the adapter validates it for the historical content.
+The selected catalog model receives `GenerateOptions.system`, history, tools, and sampling fields supported by pi-ai's common streaming API. This package adds no prompt prose. Provider-native replay metadata is restored only when the adapter validates it for the historical content.
 
 #### Token effect
 
-Provider tokenization governs exact input. Conversion adds no model-visible text beyond the image-offload placeholder, which replaces the offloaded image's visual tokens with a short fixed sentence; replay metadata may let a native API reuse provider-side state.
+Provider tokenization governs exact input. Conversion adds no model-visible text; replay metadata may let a native API reuse provider-side state.
 
 #### KV Cache effect
 
-Conversion preserves logical request order without adding text, while the selected provider's serialization and replay state determine reuse. Changing adapter instance, provider, model, or any upstream request token may prevent reuse from the first difference. Crossing the image bound rewrites an early message (the newly offloaded image becomes placeholder text), so reuse ends at that message until the offloaded prefix stabilizes.
+Conversion preserves logical request order without adding text, while the selected provider's serialization and replay state determine reuse. Changing adapter instance, provider, model, or any upstream request token may prevent reuse from the first difference.
 
 ### Provider response
 
@@ -196,9 +196,8 @@ Recorded response content appends to the next request and does not invalidate it
 
 ## Known Limitations and Deferred Work
 
-- **`maxRequestImageBytes` counts base64 image payload only** — text, tools, and JSON structure ride outside the bound, so it must sit below the gateway's request-body cap with headroom. Offload is decided at request conversion as a pure function of history and configuration and is not recorded as a session event; per-route capability metadata (image count, per-image size, total request size) driving admission and assembly together is deferred design work.
-- **A provider that authenticates through OAuth alone is not offered** — pi-ai resolves OAuth from a *stored* OAuth credential, and this adapter builds its `Models` collection with no credential store and runs no login flow, so every request on such a route fails `Provider is not configured` before it goes out. The configurable-provider directory withholds them; `openai-codex` is the only one the installed catalog ships. A route a settings document already names keeps its entry so a configuration surface can edit or delete it, and `apiKeyEnv` still authenticates it with that key — which for Codex is a token that expires with nothing here to refresh it.
-- **Provider-native discovery reads the process environment only** — a route naming no credential defers to the catalog provider's own resolution, which interrogates environment variables (`AZURE_OPENAI_API_KEY`, `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, and each provider's own set). It reads no local credential directory, so `~/.aws/credentials` without an exported `AWS_PROFILE` resolves as unconfigured, and a value held by the harness credential seam is invisible to it unless the process environment carries it too.
+- **A sign-in lives only in the process that started it** — an authorization attempt is not durable, so reloading the page mid-login abandons it and the human starts over. Signing out is `deleteRecord` on the stored record, which forgets it locally without telling the issuer.
+- **Provider-native discovery answers through this plugin's ambient context** — a route naming no credential defers to the catalog provider's own resolution, which asks for environment values (`AZURE_OPENAI_API_KEY`, `AWS_PROFILE`, and each provider's own set) and for local credential files. Both questions are answered here: the credential seam is consulted before the process environment, and file existence is checked against the host process's filesystem with `~` expanded. What it cannot do is *read* a credential file's contents — a provider that parses `~/.aws/credentials` itself does so directly, outside the seam.
 - **Settings can add or override routes, not remove composition routes** — the user layer merges over the composition `base`, so deleting a `cordis.yml`-provided provider is a composition change; `replace` on the namespace only resets the user layer.
 - **The layered merge has no delete for dict keys** — the settings seam merges the composition `base` and the user layer per key, recursively, so a `reasoningEfforts` level, `modelOverrides` entry, or `compat` field the base declares cannot be removed by the user layer, only overridden — and for `reasoningEfforts` absence *is* the meaning ("not offered"), so a base-declared level stays offered. This only triggers when a `cordis.yml` entry config declares per-model reasoning fields for the same model the user layer edits; the supported posture is to leave those to the settings document (the shipped composition mounts the adapter dormant), and a `models` list is an array replacing wholesale, which is the in-band escape.
 - **`headers` can carry a credential the redactor never sees** — the profile's `headers` dict is plain strings, so `Authorization` or `api-key` set there is returned verbatim by a redacted `describe()` and rendered by any configuration UI. Store credentials as `apiKeyEnv` references; making the dict write-only is deferred with the rest of the [wire-boundary work](../llm/README.md#known-limitations-and-deferred-work).
@@ -209,4 +208,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is provider-owned, not an SDK retry** — each provider profile may supply nested `retryPolicy`; omission resolves to normal mode with five retries, and the effective route policy is what `dsh-llm-retry` executes at the agent failed-step extension point. pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step extension point; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index e7e832fa35..a1e952b70d 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -8,7 +8,7 @@
 
 ## 配置
 
-按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。每个 profile 都可以设置 `retryPolicy`；省略时使用 normal 模式并重试五次。`apiKeyEnv` 是按请求解析的凭据*引用*，因此机密不进入该文件。省略它会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
+按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。`apiKeyEnv` 是按请求解析的凭据*引用*，因此机密不进入该文件。省略它会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
 
 ```yaml
 - id: llm
@@ -121,7 +121,7 @@ pi-ai 依据提供方 id 与 baseURL 决定每个请求的形状：系统提示
 
 **没有**这份元数据的模型——条目未声明 `reasoningEfforts` 的手工声明模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`modelOverrides`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`defaultInput`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs`、`maxRequestImageBytes` 和 `retryPolicy`。每条 profile 解析后的重试策略会随该提供方路由一同捕获；省略时使用共享的有界 normal 默认值并重试五次。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。`maxRequestImageBytes` 约束单个请求的 base64 编码图片载荷（默认 20MiB，正整数）：历史中的每张图片都会重新编码进每个请求，累积载荷超过上限时，从最老的图片开始替换为固定文本占位，直到请求装得下，使图片较多的会话保持可用，而不是被网关请求体上限永久拒绝。默认值为系统提示词、历史、工具与 JSON 保留请求容量；网关更严格的部署按路由调低该值。若已配置标头中有同名项，则以 Harness 应用归因为准。
+受支持的 profile 字段是 `apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`modelOverrides`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`defaultInput`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent（智能体）级重试预算。空闲超时会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
@@ -171,15 +171,15 @@ pi-ai 会安装多个提供方 SDK，并延迟加载 catalog 模型所选的 SDK
 
 #### 模型看到的内容
 
-所选 catalog 模型会收到 `GenerateOptions.system`、历史、工具，以及 pi-ai 通用流式 API 支持的采样字段。本包不添加提示词文本，仅有一个例外：请求累积的 base64 图片载荷超过路由的 `maxRequestImageBytes` 时，被 offload 的图片（从最老开始）会被替换为一段固定文本。该文本要求模型在有路径时重新读取文件，否则请用户重新附上图片。只有当适配器验证提供方原生回放元数据与历史内容匹配时，才会恢复这些元数据。
+所选 catalog 模型会收到 `GenerateOptions.system`、历史、工具，以及 pi-ai 通用流式 API 支持的采样字段。本包不添加提示词文本。只有当适配器验证提供方原生回放元数据与历史内容匹配时，才会恢复这些元数据。
 
 #### Token 影响
 
-精确输入取决于提供方 tokenization。除图片 offload 占位文本外，转换不添加模型可见文本；占位文本用一句固定短句替代被省略图片的视觉 token。回放元数据可能让原生 API 复用提供方侧状态。
+精确输入取决于提供方 tokenization。转换不添加模型可见文本；回放元数据可能让原生 API 复用提供方侧状态。
 
 #### KV Cache 影响
 
-转换保留逻辑请求顺序，不添加文本；复用取决于所选提供方的序列化与回放状态。更改适配器实例、提供方、模型或任何上游请求 token，都可能使复用从首个出现差异的 token 起失效。跨过图片上限会改写较早的一条消息（新被 offload 的图片变为占位文本），复用在该消息处截止，直到被 offload 的前缀稳定。
+转换保留逻辑请求顺序，不添加文本；复用取决于所选提供方的序列化与回放状态。更改适配器实例、提供方、模型或任何上游请求 token，都可能使复用从首个出现差异的 token 起失效。
 
 ### 提供方响应
 
@@ -197,9 +197,8 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 
 ## 已知限制与暂缓事项
 
-- **`maxRequestImageBytes` 只统计 base64 图片载荷**：文本、工具与 JSON 结构不计入上限，因此该值必须低于网关请求体上限并留出余量。offload 在请求转换时决定，是历史与配置的纯函数，不记录为会话事件；由按路由能力元数据（图片数量、单图大小、请求总大小）同时驱动准入与组装的完整设计属于暂缓工作。
-- **仅以 OAuth 认证的提供方不予提供**：pi-ai 的 OAuth 只从*已存储*的 OAuth 凭据解析，而本适配器构造 `Models` 集合时不注入凭据存储、也不运行登录流程，因此这类路由的每个请求都会在发出之前以 `Provider is not configured` 失败。可配置提供方目录因此不列出它们；已安装 catalog 中只有 `openai-codex` 属于此类。settings 文档已经写过的路由仍保留目录条目，配置界面据此可以编辑或删除；`apiKeyEnv` 也仍能用该密钥完成认证——对 Codex 而言那是一个会过期、且这里没有任何环节会去刷新的 token。
-- **提供方自带的凭据发现只读进程环境**：不指定凭据的路由交由 catalog 提供方自行解析，而它探测的是环境变量（`AZURE_OPENAI_API_KEY`、`AWS_PROFILE`、`AWS_ACCESS_KEY_ID` 以及各提供方自己的那一组）。它不读任何本地凭据目录，因此只有 `~/.aws/credentials` 而未导出 `AWS_PROFILE` 会被解析为未配置；由 harness 凭据 seam 保管的值，除非进程环境里也有，否则对它不可见。
+- **一次登录只存活于发起它的进程中**：授权尝试不可持久，登录途中刷新页面会丢弃它，人需要重来。登出即对已存储记录执行 `deleteRecord`，它只在本地遗忘而不通知签发方。
+- **提供方自带的凭据发现经由本插件的 ambient context 作答**：不指定凭据的路由交由 catalog 提供方自行解析，它会询问环境值（`AZURE_OPENAI_API_KEY`、`AWS_PROFILE` 以及各提供方自己的那一组）与本地凭据文件是否存在。两类问题都在这里作答：先查凭据 seam 再查进程环境，文件存在性则按宿主进程的文件系统判断并展开 `~`。它做不到的是*读取*凭据文件的内容——自行解析 `~/.aws/credentials` 的提供方是直接读盘的，不经过 seam。
 - **settings 能新增或覆盖路由，但不能移除组合路由**：用户层合并在组合 `base` 之上，因此删除 `cordis.yml` 提供的提供方属于组合变更；对该 namespace 执行 `replace` 只会重置用户层。
 - **分层合并对字典键没有删除语义**：settings seam 把组合 `base` 与用户层按键递归合并，因此 base 声明的某个 `reasoningEfforts` 档位、`modelOverrides` 条目或 `compat` 字段，用户层只能覆盖、无法移除——而 `reasoningEfforts` 里缺席本身*就是*语义（「不提供」），于是 base 声明过的档位会一直被提供。只有 `cordis.yml` entry config 为用户层正在编辑的同一模型声明了按模型推理字段才会触发；受支持的姿态是把这些字段留给 settings 文档（shipped 组合以 dormant 方式挂载该适配器），且 `models` 列表是数组、整体替换，这是带内的解决办法。
 - **`headers` 可能承载一条脱敏器看不见的凭据**：profile 的 `headers` 是纯字符串字典，因此设在其中的 `Authorization` 或 `api-key` 会被脱敏后的 `describe()` 原样返回，并被任何配置 UI 渲染出来。请把凭据存为 `apiKeyEnv` 引用；把该字典整体改为只写与其余[协议边界工作](../llm/README.md#known-limitations-and-deferred-work)一并暂缓。
@@ -210,4 +209,4 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
-- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以提供嵌套的 `retryPolicy`；省略时解析为 normal 模式并重试五次，`dsh-llm-retry` 会在 agent 的失败步骤扩展点上执行有效路由策略。pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
+- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤扩展点上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
diff --git a/packages/llm/llm-pi-ai/package.json b/packages/llm/llm-pi-ai/package.json
index be02e941df..ab286f006f 100644
--- a/packages/llm/llm-pi-ai/package.json
+++ b/packages/llm/llm-pi-ai/package.json
@@ -33,6 +33,7 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/dsh-attachment": "workspace:^",
+    "@deepseek-ai/dsh-authorization": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
     "@deepseek-ai/dsh-launch-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
@@ -47,6 +48,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-attachment": "workspace:^",
+    "@deepseek-ai/dsh-authorization": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
     "@deepseek-ai/dsh-launch-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index 5ecec593da..3c7ecd4a91 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -13,10 +13,15 @@
  * way down: switching models mid-reply takes effect on the next step, never
  * inside the one in flight.
  *
- * Credentials stay outside that collection. The harness resolves a route's key
- * through its own seam and passes it as the request's `apiKey` option, which
- * pi-ai treats as the highest-priority auth override — so `Models` never holds
- * a credential store and the harness keeps its fail-loud reference semantics.
+ * A route naming a credential reference still resolves it through the harness
+ * seam and passes it as the request's `apiKey` option, which pi-ai treats as
+ * the highest-priority auth override — that is what keeps the fail-loud
+ * reference semantics. Everything that override does not cover reaches pi-ai
+ * through the collection's own auth: the credential store holds the records a
+ * login wrote and a refresh rotates, and the auth context answers the ambient
+ * questions a provider asks while resolving. Both are stable across snapshots,
+ * so a configuration change rebuilds the collection without forgetting who is
+ * signed in.
  *
  * @module dsh-llm-pi-ai/adapter
  */
@@ -24,6 +29,8 @@
 import { createModels, getSupportedThinkingLevels } from '@earendil-works/pi-ai'
 import type {
   Api,
+  AuthContext,
+  CredentialStore,
   Model,
   Models,
   ModelThinkingLevel,
@@ -74,6 +81,15 @@ export interface PiAiAdapterOptions {
    * `MISSING_CREDENTIAL` rather than falling back.
    */
   resolveApiKey: (provider: string, profile: ResolvedPiAiProviderProfile) => Promise<string | undefined>
+  /**
+   * How every collection this adapter builds resolves auth the request-level
+   * `apiKey` override does not cover. Required rather than optional: a
+   * collection built without them gets pi-ai's in-memory default store, which
+   * is empty at every boot and discarded on every configuration change, so a
+   * route whose only method is a login would report itself unconfigured on
+   * every request no matter how often the human signed in.
+   */
+  auth: PiAiAuthInjection
   /** Resolve the optional durable attachment service at request time. */
   resolveAttachments?: () => AttachmentStore | undefined
   /**
@@ -83,6 +99,14 @@ export interface PiAiAdapterOptions {
   onReplayDegrade?: (detail: { provider: string; model: string; reason: string }) => void
 }
 
+/** The two auth injectables a pi-ai collection is built with. */
+export interface PiAiAuthInjection {
+  /** Durable storage for credentials pi-ai itself writes: logins, and the refreshes it runs under its own lock. */
+  credentials: CredentialStore
+  /** Ambient lookups a provider performs while resolving its own auth. */
+  authContext: AuthContext
+}
+
 /** Copy profile stream knobs into pi-ai's common option vocabulary. */
 function profileOptions(
   profile: ResolvedPiAiProviderProfile,
@@ -204,7 +228,7 @@ export class PiAiAdapter extends LlmAdapter {
   private current(): PiAiSnapshot {
     const profiles = this.config.profiles()
     if (this.snapshot?.profiles === profiles) return this.snapshot
-    const models: MutableModels = createModels()
+    const models: MutableModels = createModels(this.config.auth)
     for (const profile of profiles.values()) models.setProvider(profile.piProvider)
     this.snapshot = { profiles, models }
     return this.snapshot
diff --git a/packages/llm/llm-pi-ai/src/auth.ts b/packages/llm/llm-pi-ai/src/auth.ts
new file mode 100644
index 0000000000..8b718cdd20
--- /dev/null
+++ b/packages/llm/llm-pi-ai/src/auth.ts
@@ -0,0 +1,190 @@
+/**
+ * The three adapters between pi-ai's auth model and the harness credential
+ * plane. Every pi-ai-specific concept stays on this side of them: the harness
+ * seams they consume — `ctx.credentials` records and `ctx.authorization` flows —
+ * name nothing from this library, so another adapter family can arrive with a
+ * different auth model and share the same two seams.
+ *
+ * @module dsh-llm-pi-ai/auth
+ */
+
+import { homedir } from 'node:os'
+import { access } from 'node:fs/promises'
+import { resolve as resolvePath } from 'node:path'
+import type { AuthContext, Credential, CredentialInfo, CredentialStore } from '@earendil-works/pi-ai'
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialRefName,
+} from '@deepseek-ai/dsh-credentials'
+import type { CredentialKey, CredentialProvider, CredentialRecord } from '@deepseek-ai/dsh-credentials'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import { LlmError } from '@deepseek-ai/dsh-llm'
+
+/**
+ * The record scope every credential this adapter family stores is written
+ * under. It is the plugin's registered name, which is what tells a later
+ * reader — a configuration UI, or a second adapter family serving the same
+ * provider name — that this plugin owns the format inside the record.
+ */
+export const RECORD_SCOPE = 'llm-pi-ai'
+
+/**
+ * The record address for one pi-ai provider id.
+ * @param providerId - pi-ai's own provider id, which is also the harness route key.
+ * @returns the scoped credential key this adapter family reads and writes.
+ */
+export function recordKeyFor(providerId: string): CredentialKey {
+  return credentialKey(RECORD_SCOPE, providerId)
+}
+
+/**
+ * Translate a stored record into the credential pi-ai expects.
+ *
+ * An `api-key` record is structural on both sides, so it is rebuilt field by
+ * field. A `grant` payload is pi-ai's own OAuth credential, stored verbatim:
+ * the seam treats it as opaque JSON precisely so a library that owns a token
+ * format keeps owning it, refresh fields and all.
+ * @param record - the stored record, or undefined when nothing is stored.
+ * @returns the pi-ai credential, or undefined for an absent record.
+ */
+function toPiCredential(record: CredentialRecord | undefined): Credential | undefined {
+  if (record === undefined) return undefined
+  if (record.kind === 'api-key') {
+    return {
+      type: 'api_key',
+      ...record.key === undefined ? {} : { key: record.key },
+      ...record.env === undefined ? {} : { env: { ...record.env } },
+    }
+  }
+  return record.payload as Credential
+}
+
+/**
+ * Translate a pi-ai credential into the record to store.
+ * @param credential - what a login or refresh produced.
+ * @returns the record to commit, in the union the credential seam stores.
+ */
+function toRecord(credential: Credential): CredentialRecord {
+  if (credential.type === 'api_key') {
+    return {
+      kind: 'api-key',
+      ...credential.key === undefined ? {} : { key: credential.key },
+      ...credential.env === undefined ? {} : { env: { ...credential.env } },
+    }
+  }
+  return { kind: 'grant', payload: credential }
+}
+
+/**
+ * The credential service, or the failure that names what is missing. Reads
+ * answer "nothing stored" without a service, because a composition with no
+ * credential plane genuinely holds no credential; writes refuse, because a
+ * login whose grant silently evaporated would report success and then fail
+ * every request.
+ * @param ctx - the plugin context.
+ * @returns the live service.
+ * @throws {LlmError} code `NO_CREDENTIAL_STORE` when none is mounted.
+ */
+function writableStore(ctx: Context): CredentialProvider {
+  const credentials = ctx.get('credentials')
+  if (credentials === undefined) {
+    throw new LlmError(
+      'llm-pi-ai: this composition mounts no credentials service, so there is nowhere to store the'
+      + ' credential a sign-in produces; mount one (dsh-credentials-local) to sign in',
+      'NO_CREDENTIAL_STORE',
+    )
+  }
+  return credentials
+}
+
+/**
+ * A pi-ai `CredentialStore` over the harness credential records.
+ *
+ * pi-ai runs OAuth refresh *inside* `modify()`, so this store's exclusion has
+ * to cover a network round trip rather than a file rename — which is why the
+ * record write path takes a wait limit of its own rather than the short one a
+ * local write would need.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the store to hand `createModels()`.
+ */
+export function credentialStoreFrom(ctx: Context): CredentialStore {
+  return {
+    async read(providerId) {
+      const credentials = ctx.get('credentials')
+      if (credentials === undefined) return undefined
+      return toPiCredential(await credentials.readRecord(recordKeyFor(providerId)))
+    },
+    async list(): Promise<readonly CredentialInfo[]> {
+      const stored = await ctx.get('credentials')?.listRecords() ?? []
+      const mine: CredentialInfo[] = []
+      for (const entry of stored) {
+        // Records another plugin owns are not this collection's to report:
+        // their payloads are written in a format pi-ai never agreed to.
+        if (credentialKeyScope(entry.key) !== RECORD_SCOPE) continue
+        mine.push({
+          providerId: credentialKeyId(entry.key),
+          type: entry.kind === 'api-key' ? 'api_key' : 'oauth',
+        })
+      }
+      return mine
+    },
+    async modify(providerId, mutate) {
+      const stored = await writableStore(ctx).modifyRecord(recordKeyFor(providerId), async (current) => {
+        const next = await mutate(toPiCredential(current))
+        return next === undefined ? undefined : toRecord(next)
+      })
+      return toPiCredential(stored)
+    },
+    // `async` so a missing service reaches the caller as a rejection: pi-ai's
+    // store contract is promise-returning, and a synchronous throw would
+    // escape the `ModelsError` wrapper every other storage failure gets.
+    async delete(providerId) {
+      await writableStore(ctx).deleteRecord(recordKeyFor(providerId))
+    },
+  }
+}
+
+/**
+ * A pi-ai `AuthContext` over the harness credential plane and the host
+ * filesystem.
+ *
+ * `env()` answers from the credential seam first, so a value a deployment
+ * stored through the harness is found by a provider's own ambient discovery —
+ * without this, that discovery reads only the process environment and a stored
+ * `AWS_ACCESS_KEY_ID` is invisible to it. `fileExists()` answers about the host
+ * process's own filesystem rather than the workspace `ctx.fs` seam, because the
+ * paths it is asked about (`~/.aws/credentials`, application-default
+ * credentials) are facts about where this process runs, not about the project
+ * under edit.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the auth context to hand `createModels()`.
+ */
+export function authContextFrom(ctx: Context): AuthContext {
+  return {
+    async env(name) {
+      // pi-ai asks about arbitrary provider-declared names; one that is not a
+      // POSIX identifier can never have been stored as a reference, and asking
+      // the seam would throw instead of answering "not set".
+      if (isCredentialRefName(name)) {
+        const credentials = ctx.get('credentials')
+        const hit = await credentials?.resolve(credentialRef(name))
+        if (hit !== undefined) return hit.value
+      }
+      return launchEnvironmentOf(ctx).get(name)?.value
+    },
+    async fileExists(path) {
+      const expanded = path.startsWith('~/') || path === '~'
+        ? resolvePath(homedir(), path.slice(1).replace(/^\//, ''))
+        : path
+      try {
+        await access(expanded)
+        return true
+      } catch {
+        // Absent, unreadable, or a broken symlink — every one of which means
+        // this ambient credential source cannot be used, which is the only
+        // distinction the caller makes.
+        return false
+      }
+    },
+  }
+}
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index 229e881c98..1e9b126dd5 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -176,26 +176,6 @@ export function catalogProviderIds(): readonly string[] {
   return getBuiltinProviders()
 }
 
-/**
- * Whether the installed catalog provider for one route declares an api-key
- * method — the only authentication this adapter obtains on its own.
- *
- * A key is what the harness resolves through its own credential seam and hands
- * pi-ai per request. pi-ai's other method, OAuth, resolves from a *stored*
- * OAuth credential alone: `resolveProviderAuth` has no ambient path for it,
- * this adapter builds its `Models` collection with no credential store, and
- * nothing here runs a login flow. So a provider offering OAuth by itself
- * leaves nothing for this adapter to authenticate with, and the posture such a
- * provider invites — no key configured, credentials discovered by the provider
- * — fails every request with `Provider is not configured`.
- * @param provider - provider route key.
- * @returns whether the catalog provider takes an api key; false for a route
- *   pi-ai does not ship, which the caller answers for separately.
- */
-export function catalogProviderTakesApiKey(provider: string): boolean {
-  return catalogProvider(provider)?.auth.apiKey !== undefined
-}
-
 /**
  * The installed catalog models for one route, indexed by model id.
  * @param provider - provider route key.
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 1bbeec79db..846509f8c6 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -61,10 +61,12 @@ import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm'
 import type { AdapterRegistrationHandle, DirectoryRegistrationHandle, LlmConfigurableProvider } from '@deepseek-ai/dsh-llm'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { PiAiAdapter } from './adapter.ts'
-import { catalogProviderIds, catalogProviderTakesApiKey } from './catalog.ts'
+import { authContextFrom, credentialStoreFrom } from './auth.ts'
+import { catalogProviderIds } from './catalog.ts'
 import { assertServiceable, Config, resolveProfiles } from './config.ts'
 import type { ResolvedPiAiProviderProfile } from './config.ts'
 import { discoverModels } from './discovery.ts'
+import { registerPiAiFlows } from './login.ts'
 
 export { PiAiAdapter } from './adapter.ts'
 export type { PiAiAdapterOptions } from './adapter.ts'
@@ -79,6 +81,7 @@ export type {
   PiAiThinkingFormat,
   ResolvedPiAiProviderProfile,
 } from './config.ts'
+export { recordKeyFor } from './auth.ts'
 export { supportedProtocols } from './provider.ts'
 
 export const name = 'llm-pi-ai'
@@ -105,15 +108,10 @@ function registrationFacts(profiles: ReadonlyMap<string, ResolvedPiAiProviderPro
 }
 
 /**
- * The configurable-provider directory: every installed catalog route this
- * adapter can authenticate, plus every route the current profiles declare. A
- * hand-declared route has no catalog entry, so without this union it would
- * have no settings address and configuration surfaces could neither show nor
- * edit it.
- *
- * The profile half is unconditional, which is what keeps a route already
- * stored against a withheld provider editable and deletable rather than
- * stranded in the settings document with nothing on the page to remove it.
+ * The configurable-provider directory: every installed catalog route, plus
+ * every route the current profiles declare. A hand-declared route has no
+ * catalog entry, so without this union it would have no settings address and
+ * configuration surfaces could neither show nor edit it.
  * @param profiles - the currently resolved provider profiles.
  * @returns the directory entries in catalog order, declared routes last.
  */
@@ -134,14 +132,7 @@ function directoryEntries(
       declared: !catalog.has(provider),
     })
   }
-  // A provider whose only native method is OAuth leaves this adapter nothing
-  // to authenticate with, so offering it would put a card on the settings page
-  // whose own posture — no key, credentials discovered by the provider — fails
-  // every request. Catalog *membership* is unaffected, so `declare` above still
-  // answers what pi-ai ships.
-  for (const provider of catalog) {
-    if (catalogProviderTakesApiKey(provider)) declare(provider, provider)
-  }
+  for (const provider of catalog) declare(provider, provider)
   for (const [provider, profile] of profiles) declare(provider, profile.displayName)
   return [...entries.values()]
 }
@@ -197,9 +188,14 @@ export function apply(ctx: Context, config: Config): void {
     )
   }
 
+  // One store and one ambient context for the whole plugin instance: both read
+  // through `ctx` per call, so they stay correct across the collection rebuilds
+  // a configuration change causes, and a sign-in survives one.
+  const auth = { credentials: credentialStoreFrom(ctx), authContext: authContextFrom(ctx) }
   const adapter = new PiAiAdapter({
     profiles,
     resolveApiKey,
+    auth,
     resolveAttachments: () => ctx.get('attachments'),
     onReplayDegrade: ({ provider, model, reason }) => {
       ctx.logger.warn(
@@ -208,6 +204,12 @@ export function apply(ctx: Context, config: Config): void {
       )
     },
   })
+  // Independent of the route set: signing in is what makes a route worth
+  // adding, so the flows are offered before any profile names their provider.
+  // Scoped to the authorization seam rather than injected outright, because a
+  // composition without it (headless, ACP) simply has no surface to sign in
+  // from, while everything else this plugin does still works.
+  ctx.inject(['authorization'], (authorized) => { registerPiAiFlows(authorized, auth) })
   // The full installed catalog is configurable from the moment the plugin
   // mounts — dormant or not — so configuration surfaces can offer every
   // pi-ai provider before any route exists. Hand-declared routes join it as
diff --git a/packages/llm/llm-pi-ai/src/login.ts b/packages/llm/llm-pi-ai/src/login.ts
new file mode 100644
index 0000000000..c71d68e3b5
--- /dev/null
+++ b/packages/llm/llm-pi-ai/src/login.ts
@@ -0,0 +1,150 @@
+/**
+ * Authorization flows for the pi-ai providers that ship a login. This is the
+ * whole of the translation between the harness's neutral notice/prompt
+ * vocabulary and pi-ai's `AuthInteraction`; nothing above it knows which
+ * library ran the conversation.
+ *
+ * @module dsh-llm-pi-ai/login
+ */
+
+import { createModels } from '@earendil-works/pi-ai'
+import type { AuthEvent, AuthPrompt, AuthType, Provider } from '@earendil-works/pi-ai'
+import type { Context } from '@deepseek-ai/cordis'
+import type { AuthorizationMethod, AuthorizationPrompt, AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { catalogProvider, catalogProviderIds } from './catalog.ts'
+import { recordKeyFor } from './auth.ts'
+import type { PiAiAuthInjection } from './adapter.ts'
+
+/**
+ * The login methods one catalog provider offers.
+ *
+ * A method appears only when pi-ai can actually run it: `oauth` always carries
+ * a `login`, while an api-key method has one only when the provider collects
+ * its key interactively — which every installed one currently does, so a key is
+ * typed into pi-ai's own prompt rather than into the settings form.
+ * @param provider - the installed catalog provider, if pi-ai ships one.
+ * @returns its methods, most preferred first; empty when it offers no login.
+ */
+function loginMethods(provider: Provider | undefined): AuthorizationMethod[] {
+  const methods: AuthorizationMethod[] = []
+  const oauth = provider?.auth.oauth
+  if (oauth !== undefined) methods.push({ id: 'oauth', label: oauth.loginLabel ?? oauth.name })
+  const apiKey = provider?.auth.apiKey
+  if (apiKey?.login !== undefined) methods.push({ id: 'api-key', label: apiKey.name })
+  return methods
+}
+
+/**
+ * Restate one pi-ai login event in the seam's vocabulary.
+ *
+ * A device-code grant is the one event carrying two things the human needs at
+ * once — where to go and what to type there — which is why the neutral notice
+ * has a `code` beside its `url` rather than folding the code into the message.
+ * @param event - what pi-ai reported.
+ * @param session - the attempt to report it to.
+ */
+function relay(event: AuthEvent, session: AuthorizationSession): void {
+  switch (event.type) {
+    case 'info': {
+      const link = event.links?.[0]
+      session.notify({ message: event.message, ...link === undefined ? {} : { url: link.url } })
+      return
+    }
+    case 'auth_url':
+      session.notify({
+        message: event.instructions ?? 'Open this page to continue signing in.',
+        url: event.url,
+      })
+      return
+    case 'device_code':
+      session.notify({
+        message: 'Enter this code on the verification page to finish signing in.',
+        url: event.verificationUri,
+        code: event.userCode,
+      })
+      return
+    case 'progress':
+      session.notify({ message: event.message })
+      return
+    default:
+      // pi-ai's event union is open to new members: a build that meets one it
+      // does not know still shows the human that something is happening rather
+      // than going silent mid-login.
+      session.notify({ message: 'Signing in…' })
+  }
+}
+
+/**
+ * Restate one pi-ai prompt in the seam's vocabulary.
+ *
+ * `manual_code` becomes a plain text question because the difference pi-ai
+ * draws — a code the human copies from a browser rather than a value they know
+ * — changes nothing a surface renders. Its own `signal` is carried through, and
+ * that is the part which matters: it is how a flow racing a typed code against
+ * a browser callback withdraws the losing question.
+ * @param prompt - what pi-ai asked.
+ * @returns the neutral prompt to put to the human.
+ */
+function restate(prompt: AuthPrompt): AuthorizationPrompt {
+  const signal = prompt.signal === undefined ? {} : { signal: prompt.signal }
+  switch (prompt.type) {
+    case 'select':
+      return { ...signal, kind: 'select', message: prompt.message, options: prompt.options }
+    case 'secret':
+      return {
+        ...signal,
+        kind: 'secret',
+        message: prompt.message,
+        ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+      }
+    default:
+      return {
+        ...signal,
+        kind: 'text',
+        message: prompt.message,
+        ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+      }
+  }
+}
+
+/**
+ * Register one authorization flow per installed provider that ships a login.
+ *
+ * Registration is unconditional on configuration: a provider has to be signed
+ * into before a route for it is worth adding, so the flow exists from the
+ * moment the plugin mounts rather than appearing once a profile does.
+ * @param ctx - the plugin context carrying `ctx.authorization`.
+ * @param auth - the injectables every collection here is built with.
+ */
+export function registerPiAiFlows(ctx: Context, auth: PiAiAuthInjection): void {
+  for (const providerId of catalogProviderIds()) {
+    const provider = catalogProvider(providerId)
+    const [first, ...rest] = loginMethods(provider)
+    /* v8 ignore next 3 -- every id here names an installed provider and every
+       installed provider ships a login, so nothing is skipped today; the guard
+       is what keeps that from becoming a crash if either stops being true. */
+    if (provider === undefined || first === undefined) continue
+    ctx.authorization.registerFlow({
+      key: recordKeyFor(providerId),
+      label: provider.name,
+      methods: [first, ...rest],
+      async run(session) {
+        // A collection of its own, holding only the provider being signed
+        // into: login is not serving requests, and the credential it produces
+        // lands in the shared store either way.
+        const models = createModels(auth)
+        models.setProvider(provider)
+        // Total over the two ids declared above, and the seam only ever hands
+        // back one a flow declared.
+        const type: AuthType = session.method === 'oauth' ? 'oauth' : 'api_key'
+        // pi-ai persists what the login returns through that same store, which
+        // is what makes it the single writer of this record.
+        await models.login(providerId, type, {
+          signal: session.signal,
+          notify: (event) => { relay(event, session) },
+          prompt: prompt => session.prompt(restate(prompt)),
+        })
+      },
+    })
+  }
+}
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index 2446b10286..a36a180f7d 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -13,6 +13,7 @@ import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { getBuiltinModels } from '@earendil-works/pi-ai/providers/all'
 import { DEFAULT_MAX_REQUEST_IMAGE_BYTES, resolveProfiles } from '../src/config.ts'
+import { memoryAuth } from './auth-double.ts'
 import { assemble } from './assemble.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
 
@@ -47,6 +48,7 @@ function adapterOf(
   return new PiAiAdapter({
     profiles: () => resolveProfiles(providers),
     resolveApiKey: () => Promise.resolve(apiKey),
+    auth: memoryAuth(),
   })
 }
 
diff --git a/packages/llm/llm-pi-ai/tests/auth-double.ts b/packages/llm/llm-pi-ai/tests/auth-double.ts
new file mode 100644
index 0000000000..a05c017d04
--- /dev/null
+++ b/packages/llm/llm-pi-ai/tests/auth-double.ts
@@ -0,0 +1,39 @@
+import type { Credential } from '@earendil-works/pi-ai'
+import type { PiAiAuthInjection } from '../src/adapter.ts'
+
+/**
+ * The auth injectables for tests that exercise streaming rather than
+ * authentication: an in-process credential store and an ambient context that
+ * finds nothing. A test needing real records builds the store over
+ * `ctx.credentials` instead, through `credentialStoreFrom`.
+ * @param seed - credentials to start with, by pi-ai provider id.
+ * @returns the injection to hand `PiAiAdapter`, with its store readable.
+ */
+export function memoryAuth(seed: Record<string, Credential> = {}): PiAiAuthInjection & {
+  stored: Map<string, Credential>
+} {
+  const stored = new Map(Object.entries(seed))
+  return {
+    stored,
+    credentials: {
+      read: id => Promise.resolve(stored.get(id)),
+      list: () => Promise.resolve([...stored].map(([providerId, credential]) => ({
+        providerId,
+        type: credential.type,
+      }))),
+      async modify(id, mutate) {
+        const next = await mutate(stored.get(id))
+        if (next !== undefined) stored.set(id, next)
+        return stored.get(id)
+      },
+      delete: (id) => {
+        stored.delete(id)
+        return Promise.resolve()
+      },
+    },
+    authContext: {
+      env: () => Promise.resolve(undefined),
+      fileExists: () => Promise.resolve(false),
+    },
+  }
+}
diff --git a/packages/llm/llm-pi-ai/tests/auth.spec.ts b/packages/llm/llm-pi-ai/tests/auth.spec.ts
new file mode 100644
index 0000000000..55a20fbb66
--- /dev/null
+++ b/packages/llm/llm-pi-ai/tests/auth.spec.ts
@@ -0,0 +1,155 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import LocalCredentialProvider from '@deepseek-ai/dsh-credentials-local'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
+import { authContextFrom, credentialStoreFrom, recordKeyFor } from '../src/auth.ts'
+
+const CODEX = recordKeyFor('openai-codex')
+
+const dirs: string[] = []
+
+/** A context whose credential records live in a throwaway `$DSH_HOME`. */
+async function stored(): Promise<Context> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-pi-auth-'))
+  dirs.push(dir)
+  const ctx = new Context()
+  await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+  return ctx
+}
+
+afterEach(async () => {
+  vi.unstubAllEnvs()
+  await Promise.all(dirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+describe('pi-ai credential store over harness records', () => {
+  it('reads nothing for a provider with no record', async () => {
+    const store = credentialStoreFrom(await stored())
+
+    await expect(store.read('openai-codex')).resolves.toBeUndefined()
+  })
+
+  it('round-trips an api-key credential field by field', async () => {
+    const ctx = await stored()
+    const store = credentialStoreFrom(ctx)
+
+    await store.modify('cloudflare', () =>
+      Promise.resolve({ type: 'api_key', key: 'sk-live', env: { ACCOUNT_ID: 'acct-1' } }))
+
+    await expect(store.read('cloudflare'))
+      .resolves.toEqual({ type: 'api_key', key: 'sk-live', env: { ACCOUNT_ID: 'acct-1' } })
+    await expect(ctx.credentials.readRecord(recordKeyFor('cloudflare')))
+      .resolves.toEqual({ kind: 'api-key', key: 'sk-live', env: { ACCOUNT_ID: 'acct-1' } })
+  })
+
+  it('stores an api-key credential carrying neither a key nor env', async () => {
+    const store = credentialStoreFrom(await stored())
+
+    await store.modify('bedrock', () => Promise.resolve({ type: 'api_key' }))
+
+    await expect(store.read('bedrock')).resolves.toEqual({ type: 'api_key' })
+  })
+
+  it('keeps an OAuth credential verbatim, refresh fields and all', async () => {
+    const ctx = await stored()
+    const store = credentialStoreFrom(ctx)
+    const granted = { type: 'oauth' as const, access: 'at', refresh: 'rt', expires: 42, accountId: 'acc' }
+
+    await store.modify('openai-codex', () => Promise.resolve(granted))
+
+    await expect(store.read('openai-codex')).resolves.toEqual(granted)
+    await expect(ctx.credentials.readRecord(CODEX)).resolves.toEqual({ kind: 'grant', payload: granted })
+  })
+
+  it('shows the mutation the current credential and leaves it alone when declined', async () => {
+    const store = credentialStoreFrom(await stored())
+    await store.modify('openai-codex', () =>
+      Promise.resolve({ type: 'oauth', access: 'first', refresh: 'r', expires: 1 }))
+    const seen: unknown[] = []
+
+    const unchanged = await store.modify('openai-codex', (current) => {
+      seen.push(current)
+      return Promise.resolve(undefined)
+    })
+
+    expect(seen).toEqual([{ type: 'oauth', access: 'first', refresh: 'r', expires: 1 }])
+    expect(unchanged).toEqual({ type: 'oauth', access: 'first', refresh: 'r', expires: 1 })
+  })
+
+  it('lists only the records this adapter family owns', async () => {
+    const ctx = await stored()
+    const store = credentialStoreFrom(ctx)
+    await store.modify('openai-codex', () =>
+      Promise.resolve({ type: 'oauth', access: 'at', refresh: 'rt', expires: 1 }))
+    await store.modify('cloudflare', () => Promise.resolve({ type: 'api_key', key: 'k' }))
+    // Another plugin's record for a provider name this one also serves: its
+    // payload is written in a format pi-ai never agreed to.
+    await ctx.credentials.modifyRecord(credentialKey('llm-kimi', 'openai-codex'), () =>
+      Promise.resolve({ kind: 'grant', payload: { theirs: true } }))
+
+    await expect(store.list()).resolves.toEqual([
+      { providerId: 'openai-codex', type: 'oauth' },
+      { providerId: 'cloudflare', type: 'api_key' },
+    ])
+  })
+
+  it('forgets a credential on delete, and stays quiet when there was none', async () => {
+    const store = credentialStoreFrom(await stored())
+    await store.modify('openai-codex', () =>
+      Promise.resolve({ type: 'oauth', access: 'at', refresh: 'rt', expires: 1 }))
+
+    await store.delete('openai-codex')
+    await store.delete('openai-codex')
+
+    await expect(store.read('openai-codex')).resolves.toBeUndefined()
+  })
+
+  it('reads empty but refuses to write without a credentials service', async () => {
+    const store = credentialStoreFrom(new Context())
+
+    await expect(store.read('openai-codex')).resolves.toBeUndefined()
+    await expect(store.list()).resolves.toEqual([])
+    await expect(store.modify('openai-codex', () => Promise.resolve({ type: 'api_key', key: 'k' })))
+      .rejects.toThrow(/mounts no credentials service/)
+    await expect(store.delete('openai-codex')).rejects.toThrow(/mounts no credentials service/)
+  })
+})
+
+describe('pi-ai ambient auth context', () => {
+  beforeEach(() => {
+    vi.stubEnv('PI_AUTH_AMBIENT', 'from-environment')
+  })
+
+  it('answers an environment name from the credential seam first', async () => {
+    const ctx = await stored()
+    await ctx.credentials.set(credentialRef('PI_AUTH_SEAM'), 'from-seam')
+
+    await expect(authContextFrom(ctx).env('PI_AUTH_SEAM')).resolves.toBe('from-seam')
+  })
+
+  it('falls back to the launch environment when nothing is stored', async () => {
+    await expect(authContextFrom(await stored()).env('PI_AUTH_AMBIENT')).resolves.toBe('from-environment')
+  })
+
+  it('answers "not set" for a name no reference could ever address', async () => {
+    // pi-ai asks about provider-declared names; one outside the reference
+    // grammar has no reference to miss, and must not throw.
+    await expect(authContextFrom(await stored()).env('not a var')).resolves.toBeUndefined()
+  })
+
+  it('answers about the host filesystem, expanding a leading ~', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-pi-home-'))
+    dirs.push(dir)
+    await writeFile(join(dir, 'creds'), 'x')
+    vi.stubEnv('HOME', dir)
+    const context = authContextFrom(await stored())
+
+    await expect(context.fileExists('~/creds')).resolves.toBe(true)
+    await expect(context.fileExists('~/missing')).resolves.toBe(false)
+    await expect(context.fileExists(join(dir, 'creds'))).resolves.toBe(true)
+    await expect(context.fileExists('~')).resolves.toBe(true)
+  })
+})
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index 0322b81edf..99886cdbaf 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -15,6 +15,7 @@ import type { Api, Model, OpenAICompletionsCompat, Provider } from '@earendil-wo
 import { resolveProfiles } from '../src/config.ts'
 import { buildProvider, supportedProtocols } from '../src/provider.ts'
 import { assemble } from './assemble.ts'
+import { memoryAuth } from './auth-double.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
 
 const homes: string[] = []
@@ -1065,6 +1066,7 @@ describe('resolution snapshots', () => {
       // Credential resolution is the real await inside a stream call, and the
       // window a configuration change has to land in.
       resolveApiKey: async () => { await held; return 'k' },
+      auth: memoryAuth(),
     })
 
     const chunks: StreamChunk[] = []
@@ -1093,7 +1095,11 @@ describe('resolution snapshots', () => {
     const first = await mockServer([{ events: textEvents }])
     const second = await mockServer([{ events: textEvents }])
     let current = resolveProfiles({ deepseek: { baseURL: `${first.url}/v1` } })
-    const adapter = new PiAiAdapter({ profiles: () => current, resolveApiKey: () => Promise.resolve('k') })
+    const adapter = new PiAiAdapter({
+      profiles: () => current,
+      resolveApiKey: () => Promise.resolve('k'),
+      auth: memoryAuth(),
+    })
     const drain = async (): Promise<void> => {
       for await (const _chunk of adapter.stream({
         provider: 'deepseek', model: 'deepseek-v4-flash', messages: [],
@@ -1160,30 +1166,22 @@ describe('configurable-provider directory', () => {
     expect(ctx.llm.listConfigurableProviders()).toHaveLength(catalogOnly)
   })
 
-  it('withholds a catalog route this adapter cannot authenticate', async () => {
+  it('offers every installed catalog route, including one that only signs in', async () => {
     const ctx = await harness({})
     const offered = ctx.llm.listConfigurableProviders().map(entry => entry.provider)
 
     // `openai-codex` is the one installed provider that authenticates through
-    // OAuth alone. pi-ai resolves OAuth only from a *stored* credential, this
-    // adapter constructs its collection with no credential store, and nothing
-    // here runs a login flow — so every request on such a route fails with
-    // `Provider is not configured` before it goes out. Offering it would put a
-    // provider on the settings page that no amount of configuration can make
-    // work.
-    expect(offered).not.toContain('openai-codex')
-    // A provider that offers OAuth *beside* an api-key method keeps its entry:
-    // the key is a path this adapter can serve.
+    // OAuth alone. It is offered like any other because the collection now
+    // carries a durable credential store and a login flow writes into it, so
+    // the route has a posture that works rather than only one that fails.
+    expect(offered).toContain('openai-codex')
     expect(offered).toContain('anthropic')
     expect(offered).toContain('openai')
   })
 
-  it('still lists a withheld route a stored profile names, as a catalog route', async () => {
-    // Withholding the offer must not strand a profile someone already stored:
-    // the route keeps its entry so a configuration surface can edit or delete
-    // it, and `declared` still answers catalog membership rather than the
-    // offer, so the page does not mislabel it as a route this deployment
-    // invented.
+  it('lists a route a stored profile names as a catalog route, not a declared one', async () => {
+    // `declared` answers catalog membership, so a profile stored against a
+    // route pi-ai ships is not mislabelled as one this deployment invented.
     const ctx = await harness({ providers: { 'openai-codex': { apiKeyEnv: KEY_ENV } } })
 
     expect(ctx.llm.listConfigurableProviders()).toContainEqual({
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index 1019354156..3decff3749 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -9,6 +9,7 @@ import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { FileSettingsProvider } from '@deepseek-ai/dsh-settings-file'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
+import AuthorizationService from '@deepseek-ai/dsh-authorization'
 import { assemble } from './assemble.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
 
@@ -37,7 +38,11 @@ async function home(): Promise<string> {
 }
 
 /** Real dynamic composition mirroring the deepseek twin's harness. */
-async function boot(dir: string, config: LlmPiAi.Config): Promise<Context> {
+async function boot(
+  dir: string,
+  config: LlmPiAi.Config,
+  options: { authorization?: boolean } = {},
+): Promise<Context> {
   const ctx = new Context()
   cleanups.push(async () => {
     await ctx.fiber.dispose()
@@ -45,17 +50,38 @@ async function boot(dir: string, config: LlmPiAi.Config): Promise<Context> {
   await ctx.plugin(LlmRuntime)
   await ctx.plugin(FileSettingsProvider, { path: join(dir, 'settings.yaml'), watch: false })
   await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+  if (options.authorization === true) await ctx.plugin(AuthorizationService)
   await ctx.plugin(LlmPiAi, config)
   return ctx
 }
 
+describe('login flows in a real composition', () => {
+  it('offers a sign-in for a provider no route names, once the seam is mounted', async () => {
+    const ctx = await boot(await home(), {}, { authorization: true })
+
+    // Zero routes configured: signing in is what makes a route worth adding,
+    // so the offer cannot wait for a profile to name the provider.
+    const codex = ctx.authorization.describe(LlmPiAi.recordKeyFor('openai-codex'))
+    expect(codex?.methods.map(method => method.id)).toEqual(['oauth'])
+  })
+
+  it('mounts without the seam, and simply offers no sign-in', async () => {
+    const ctx = await boot(await home(), {})
+
+    // A headless or ACP composition has no surface to sign in from; everything
+    // else this plugin does still works.
+    expect(ctx.get('authorization')).toBeUndefined()
+    expect(ctx.llm.listConfigurableProviders().length).toBeGreaterThan(0)
+  })
+})
+
 describe('request-level dynamic profiles', () => {
   it('mounts bare and dormant, then registers routes the moment settings supply providers', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
     await writeFile(
       join(dir, '.credentials.yaml'),
-      'PI_DYNAMIC_KEY: pk-from-settings\nPI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      'version: 1\nrefs:\n  PI_DYNAMIC_KEY: pk-from-settings\n  PI_LIVE_KEY: live-key\n  PI_OTHER_KEY: other\n',
       { mode: 0o600 },
     )
     const server = await mockServer([{ events: textEvents }])
@@ -93,7 +119,7 @@ describe('request-level dynamic profiles', () => {
     const dir = await home()
     await writeFile(
       join(dir, '.credentials.yaml'),
-      'PI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      'version: 1\nrefs:\n  PI_LIVE_KEY: live-key\n  PI_OTHER_KEY: other\n',
       { mode: 0o600 },
     )
     const server = await mockServer([{ events: textEvents }])
@@ -122,7 +148,7 @@ describe('request-level dynamic profiles', () => {
   it('rotates the per-request credential referenced by apiKeyEnv', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-one\n', { mode: 0o600 })
+    await writeFile(join(dir, '.credentials.yaml'), 'version: 1\nrefs:\n  PI_DYNAMIC_KEY: pk-one\n', { mode: 0o600 })
     const server = await mockServer([{ events: textEvents }, { events: textEvents }])
     const ctx = await boot(dir, {
       providers: { deepseek: { apiKeyEnv: 'PI_DYNAMIC_KEY', baseURL: server.url } },
@@ -173,7 +199,7 @@ describe('request-level dynamic profiles', () => {
     const dir = await home()
     await writeFile(
       join(dir, '.credentials.yaml'),
-      'PI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      'version: 1\nrefs:\n  PI_LIVE_KEY: live-key\n  PI_OTHER_KEY: other\n',
       { mode: 0o600 },
     )
     const server = await mockServer([{ events: textEvents }, { events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
index a4e89424f6..6ca02f281a 100644
--- a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
@@ -49,7 +49,7 @@ async function loadComposition(): Promise<{ ctx: Context; settingsPath: string }
   root = await mkdtemp(join(tmpdir(), 'dsh-pi-composition-'))
   const settingsPath = join(root, 'settings.yaml')
   await writeFile(settingsPath, '# personal settings\n')
-  await writeFile(join(root, '.credentials.yaml'), 'PI_COMPOSITION_KEY: key-from-store\n', { mode: 0o600 })
+  await writeFile(join(root, '.credentials.yaml'), 'version: 1\nrefs:\n  PI_COMPOSITION_KEY: key-from-store\n', { mode: 0o600 })
 
   const configPath = join(root, 'cordis.yml')
   await writeFile(configPath, [
diff --git a/packages/llm/llm-pi-ai/tests/login.spec.ts b/packages/llm/llm-pi-ai/tests/login.spec.ts
new file mode 100644
index 0000000000..beb65ce188
--- /dev/null
+++ b/packages/llm/llm-pi-ai/tests/login.spec.ts
@@ -0,0 +1,198 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import AuthorizationService from '@deepseek-ai/dsh-authorization'
+import type { AuthorizationInteraction, AuthorizationNotice, AuthorizationPrompt } from '@deepseek-ai/dsh-authorization'
+import LocalCredentialProvider from '@deepseek-ai/dsh-credentials-local'
+import type { CredentialKey } from '@deepseek-ai/dsh-credentials'
+import type { AuthEvent, AuthInteraction, AuthPrompt, AuthType, Credential } from '@earendil-works/pi-ai'
+
+const login = vi.hoisted(() => vi.fn())
+
+// The whole of what this module does with pi-ai is run one provider's login
+// against a collection built with the harness store, so the collection is the
+// boundary worth observing; a real login would open a browser.
+vi.mock('@earendil-works/pi-ai', async importOriginal => ({
+  ...await importOriginal<typeof import('@earendil-works/pi-ai')>(),
+  createModels: () => ({ setProvider: () => {}, login }),
+}))
+
+const { credentialStoreFrom, authContextFrom, recordKeyFor } = await import('../src/auth.ts')
+const { registerPiAiFlows } = await import('../src/login.ts')
+
+const CODEX = recordKeyFor('openai-codex')
+const dirs: string[] = []
+
+/** A context with the record store, the seam, and every pi-ai login flow. */
+async function harness(): Promise<Context> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-pi-login-'))
+  dirs.push(dir)
+  const ctx = new Context()
+  await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+  await ctx.plugin(AuthorizationService)
+  registerPiAiFlows(ctx, { credentials: credentialStoreFrom(ctx), authContext: authContextFrom(ctx) })
+  return ctx
+}
+
+/** An interaction recording everything a flow says, answering every question. */
+function surface(answer = 'typed'): AuthorizationInteraction & {
+  notices: AuthorizationNotice[]
+  prompts: AuthorizationPrompt[]
+} {
+  const notices: AuthorizationNotice[] = []
+  const prompts: AuthorizationPrompt[] = []
+  return {
+    notices,
+    prompts,
+    notify: (notice) => { notices.push(notice) },
+    prompt: (prompt) => {
+      prompts.push(prompt)
+      return Promise.resolve(answer)
+    },
+  }
+}
+
+/** Drive one attempt, letting the mocked login talk back through `converse`. */
+async function attempt(
+  ctx: Context,
+  converse: (interaction: AuthInteraction) => Promise<void>,
+  request: { key?: CredentialKey; method?: string } = {},
+): Promise<ReturnType<typeof surface>> {
+  const ui = surface()
+  login.mockImplementation(async (providerId: string, _type: AuthType, interaction: AuthInteraction) => {
+    await converse(interaction)
+    const granted: Credential = { type: 'oauth', access: 'at', refresh: 'rt', expires: 1 }
+    await credentialStoreFrom(ctx).modify(providerId, () => Promise.resolve(granted))
+    return granted
+  })
+  await expect(ctx.authorization.begin({
+    key: request.key ?? CODEX,
+    interaction: ui,
+    ...request.method === undefined ? {} : { method: request.method },
+  })).resolves.toEqual({ status: 'authorized' })
+  return ui
+}
+
+afterEach(async () => {
+  login.mockReset()
+  await Promise.all(dirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+describe('pi-ai login flows', () => {
+  it('offers one flow per installed provider, with the methods that provider ships', async () => {
+    const ctx = await harness()
+    const offered = ctx.authorization.list()
+
+    // The OAuth-only provider is exactly the case this exists for: nothing
+    // else could ever configure it.
+    expect(offered.find(entry => entry.key === CODEX)?.methods)
+      .toEqual([{ id: 'oauth', label: expect.stringContaining('ChatGPT') as string }])
+    // A provider offering both keeps both, the subscription login first.
+    expect(offered.find(entry => entry.key === recordKeyFor('anthropic'))?.methods.map(one => one.id))
+      .toEqual(['oauth', 'api-key'])
+    // A key-only provider still gets a flow, because pi-ai collects the key
+    // through its own prompt rather than leaving it to the settings form.
+    expect(offered.find(entry => entry.key === recordKeyFor('deepseek'))?.methods.map(one => one.id))
+      .toEqual(['api-key'])
+  })
+
+  it('runs the pi-ai auth type the chosen method names', async () => {
+    const ctx = await harness()
+
+    await attempt(ctx, () => Promise.resolve())
+    expect(login).toHaveBeenLastCalledWith('openai-codex', 'oauth', expect.anything())
+
+    await attempt(ctx, () => Promise.resolve(), { key: recordKeyFor('anthropic'), method: 'api-key' })
+    expect(login).toHaveBeenLastCalledWith('anthropic', 'api_key', expect.anything())
+  })
+
+  it('commits what the login produced, where the adapter reads it back', async () => {
+    const ctx = await harness()
+
+    await attempt(ctx, () => Promise.resolve())
+
+    await expect(ctx.credentials.readRecord(CODEX)).resolves.toEqual({
+      kind: 'grant',
+      payload: { type: 'oauth', access: 'at', refresh: 'rt', expires: 1 },
+    })
+  })
+
+  it('restates every pi-ai login event in the neutral vocabulary', async () => {
+    const ctx = await harness()
+    const events: AuthEvent[] = [
+      { type: 'info', message: 'Read this first', links: [{ url: 'https://help.example' }] },
+      { type: 'info', message: 'Nothing to open' },
+      { type: 'auth_url', url: 'https://auth.example/start', instructions: 'Approve in the tab' },
+      { type: 'auth_url', url: 'https://auth.example/plain' },
+      { type: 'device_code', userCode: 'WXYZ-1234', verificationUri: 'https://device.example' },
+      { type: 'progress', message: 'Exchanging the code' },
+      // pi-ai's event union is open; an unrecognised member must still show
+      // the human that something is happening.
+      { type: 'quantum-handshake' } as unknown as AuthEvent,
+    ]
+
+    const ui = await attempt(ctx, (interaction) => {
+      for (const event of events) interaction.notify(event)
+      return Promise.resolve()
+    })
+
+    expect(ui.notices).toEqual([
+      { message: 'Read this first', url: 'https://help.example' },
+      { message: 'Nothing to open' },
+      { message: 'Approve in the tab', url: 'https://auth.example/start' },
+      { message: 'Open this page to continue signing in.', url: 'https://auth.example/plain' },
+      {
+        message: 'Enter this code on the verification page to finish signing in.',
+        url: 'https://device.example',
+        code: 'WXYZ-1234',
+      },
+      { message: 'Exchanging the code' },
+      { message: 'Signing in…' },
+    ])
+  })
+
+  it('restates every pi-ai prompt, carrying the per-prompt withdrawal signal', async () => {
+    const ctx = await harness()
+    const withdraw = new AbortController()
+    const prompts: AuthPrompt[] = [
+      { type: 'text', message: 'Your workspace', placeholder: 'acme' },
+      { type: 'secret', message: 'Paste the key' },
+      { type: 'secret', message: 'Paste the token', placeholder: 'sk-…' },
+      { type: 'select', message: 'Which account?', options: [{ id: 'a', label: 'Work' }] },
+      // The manual-code question a browser callback can win the race against.
+      { type: 'manual_code', message: 'Paste the code', signal: withdraw.signal },
+    ]
+
+    const ui = await attempt(ctx, async (interaction) => {
+      for (const prompt of prompts) await interaction.prompt(prompt)
+    })
+
+    expect(ui.prompts).toEqual([
+      { kind: 'text', message: 'Your workspace', placeholder: 'acme' },
+      { kind: 'secret', message: 'Paste the key' },
+      { kind: 'secret', message: 'Paste the token', placeholder: 'sk-…' },
+      { kind: 'select', message: 'Which account?', options: [{ id: 'a', label: 'Work' }] },
+      { kind: 'text', message: 'Paste the code', signal: withdraw.signal },
+    ])
+  })
+
+  it('hands the flow the attempt-wide cancellation signal', async () => {
+    const ctx = await harness()
+    let seen: AbortSignal | undefined
+    const controller = new AbortController()
+    login.mockImplementation((_id: string, _type: AuthType, interaction: AuthInteraction) => {
+      seen = interaction.signal
+      controller.abort()
+      return new Promise(() => {})
+    })
+
+    await expect(ctx.authorization.begin({
+      key: CODEX,
+      interaction: surface(),
+      signal: controller.signal,
+    })).resolves.toEqual({ status: 'cancelled' })
+    expect(seen?.aborted).toBe(true)
+  })
+})
diff --git a/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts b/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
index 317b803f0c..2f409c6d9d 100644
--- a/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
@@ -13,6 +13,7 @@ vi.mock('@earendil-works/pi-ai/api/openai-completions.lazy', () => ({
 
 import { PiAiAdapter } from '../src/adapter.ts'
 import { resolveProfiles } from '../src/config.ts'
+import { memoryAuth } from './auth-double.ts'
 
 afterEach(() => { streamSimple.mockReset() })
 
@@ -27,6 +28,7 @@ function gatewayAdapter(): PiAiAdapter {
       },
     }),
     resolveApiKey: () => Promise.resolve('test-key'),
+    auth: memoryAuth(),
   })
 }
 
diff --git a/packages/llm/llm-pi-ai/tsconfig.json b/packages/llm/llm-pi-ai/tsconfig.json
index 6f0b821d36..172dbe8a6e 100644
--- a/packages/llm/llm-pi-ai/tsconfig.json
+++ b/packages/llm/llm-pi-ai/tsconfig.json
@@ -29,6 +29,9 @@
     {
       "path": "../../credentials/credentials"
     },
+    {
+      "path": "../../credentials/authorization"
+    },
     {
       "path": "../../settings/settings"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3c5eab9c8f..f993dc3672 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5535,6 +5535,9 @@ importers:
       '@deepseek-ai/dsh-attachment':
         specifier: workspace:^
         version: link:../../attachment/attachment
+      '@deepseek-ai/dsh-authorization':
+        specifier: workspace:^
+        version: link:../../credentials/authorization
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../credentials/credentials
@@ -8714,6 +8717,9 @@ importers:
       '@deepseek-ai/dsh-attachment':
         specifier: workspace:^
         version: link:../../packages/attachment/attachment
+      '@deepseek-ai/dsh-authorization':
+        specifier: workspace:^
+        version: link:../../packages/credentials/authorization
       '@deepseek-ai/dsh-bash-local':
         specifier: workspace:^
         version: link:../../packages/shell/bash-local
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 86689a6bf6..befad374c1 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -30,6 +30,7 @@
     "@deepseek-ai/dsh-compaction-basic": "workspace:^",
     "@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:^",
     "@deepseek-ai/dsh-cordis-host-runner": "workspace:^",
+    "@deepseek-ai/dsh-authorization": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
     "@deepseek-ai/dsh-launch-environment": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",

From 21ea0ed9e6935c866cd95dd8ccfb39587a590ddc Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 13 Aug 2026 16:01:49 +0800
Subject: [PATCH 23/34] docs(authorization): record the credential-record and
 flow decisions

Why the record union is one step more abstract than pi-ai's credential
in exactly two places, why a record key names the owning plugin rather
than the provider, why the flow owns the write, and why the interaction
travels with the request instead of a registry. Cross-links the release
fix it supersedes, and states what is still missing: the wire contract
and the Models-page control that would let a human start a login.

The two web e2e goldens regain exactly the openai-codex option line
they lost when the provider was withheld.
---
 ...-records-and-authorization-flows.i18n.yaml |  6 ++
 ...dential-records-and-authorization-flows.md | 66 +++++++++++++++++++
 ...tial-records-and-authorization-flows.zh.md | 66 +++++++++++++++++++
 ...13-oauth-only-providers-withheld.i18n.yaml |  4 +-
 ...026-08-13-oauth-only-providers-withheld.md |  2 +
 ...-08-13-oauth-only-providers-withheld.zh.md |  2 +
 .../models-settings/empty.expected.md         |  1 +
 .../dismissed.expected.md                     |  1 +
 8 files changed, 146 insertions(+), 2 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
new file mode 100644
index 0000000000..269ef4ce46
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.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/architecture/2026-08-13-credential-records-and-authorization-flows.md
+2026-08-13-credential-records-and-authorization-flows.md: b962393f3efdf883b918ae47aa96d37846c12dd6
+2026-08-13-credential-records-and-authorization-flows.zh.md: e730b00c7be427e243abfab5206eac13079b11cc
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
new file mode 100644
index 0000000000..b962393f3e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
@@ -0,0 +1,66 @@
+# Agent Note: Credential records and authorization flows
+
+Status: implemented
+
+English | [中文](2026-08-13-credential-records-and-authorization-flows.zh.md)
+
+## Problem
+
+The harness credential plane could only express one kind of secret: a value behind an environment-variable name. `CredentialRef` is a POSIX identifier, resolution layers the process environment over a managed file and `.env` fallbacks, and every consumer reads it per operation. That covers an API key exactly and covers nothing else.
+
+Some credentials are not values a deployment can be told to store. They are obtained — by a conversation with a human who opens a page, approves an account, and pastes a code back — and what comes out is a token document with a refresh half that rotates behind the user's back. pi-ai models this directly (`Credential = ApiKeyCredential | OAuthCredential`, an app-owned `CredentialStore`, `Models.login()`), and the harness had nowhere to put any of it. `PiAiAdapter` built its collection with `createModels()` and no options, so the store was pi-ai's in-memory default: empty at every boot, discarded on every configuration change. `openai-codex`, whose only method is OAuth, therefore failed every request with `Provider is not configured` — [withheld from the directory](../bug-fix/2026-08-13-oauth-only-providers-withheld.md) as a release fix, which removed the broken offer without adding the capability.
+
+Two further gaps followed from the same missing plane. A provider's own ambient discovery ran against the raw process environment, so a key held by the credential seam was invisible to it and a local credential file was never even looked for. And a login had no surface to run from, because nothing in the harness could ask a human a question on a plugin's behalf.
+
+## Decision
+
+Three seams, each owning one question, and every pi-ai concept behind an adapter inside `llm-pi-ai`.
+
+**`dsh-credentials` grows a second key space.** A `CredentialRef` answers *what is behind this environment-variable name*; a `CredentialKey` answers *what credential does this plugin hold for this id*. The record union is `{ kind: 'api-key', key?, env? } | { kind: 'grant', payload }` — the api-key half structural because the seam can describe it, the grant half opaque because a library that owns a token format keeps owning it. The only constraint on a payload is that it survives a JSON round trip, enforced on the way in and on the way out.
+
+The key is `<scope>/<id>` where the scope is the **owning plugin's registered name**, not the provider's. A user knows `openai-codex`; which adapter family answers for the bytes inside that record is exactly what a bare provider name loses. Two plugins serving the same provider name would read each other's payload, and a record left by an uninstalled plugin could not be told from a live one. The `/` also keeps the two grammars disjoint, so the key spaces cannot collide. This assumes one adapter registers a given provider route, which the LLM registry already enforces.
+
+Records do not layer. There is no environment an authorization grant could be read from, so presence of the record is the whole fact, and the empty-value rule that governs references does not apply: an `api-key` record carrying neither a key nor env states that its owner confirmed ambient authentication, which is configured.
+
+**`dsh-authorization` owns the conversation, never the protocol.** A plugin that knows how to obtain its own credential registers a flow under the `CredentialKey` that flow writes. The seam runs one attempt per key, routes a neutral vocabulary of notices and prompts, and settles. A second authorization protocol arrives as another flow rather than as another seam, and a surface that renders one flow renders all of them.
+
+Two choices carry the weight:
+
+- **The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms it and refuses a flow that resolved without one. This is what lets `Models.login()` — which persists through the store adapter as part of logging in — stay the single writer, instead of the credential being copied back out and written a second time.
+- **The interaction travels with the request, not a registry.** Whoever starts an authorization is the one who can talk to the human about it, so prompts reach exactly the page that asked, a headless caller supplies an interaction that declines, and there is no ambient provider to be absent or ambiguous between two open tabs.
+
+**`llm-pi-ai` holds all three translations.** `credentialStoreFrom` maps pi-ai's `CredentialStore` onto records; `authContextFrom` answers pi-ai's ambient questions from the credential seam, then the launch environment, with file existence checked against the host process's filesystem; `registerPiAiFlows` restates pi-ai's `AuthEvent`/`AuthPrompt` in the neutral vocabulary and runs `Models.login()`. Every collection is built with the first two, which is what keeps a signed-in provider signed in across the collection rebuild a configuration change causes. With a posture that works, the directory stops withholding OAuth-only routes and `openai-codex` is offered again.
+
+The credential plane stays optional, as it already was for reference resolution. Reads answer "nothing stored" without a credentials service, because such a composition genuinely holds no credential; writes refuse by name, because a login whose grant evaporated would report success and then fail every request. Flow registration is scoped to the authorization seam through `ctx.inject`, so a headless or ACP composition mounts with no sign-in and nothing else changed.
+
+### Two mechanisms the seams needed underneath
+
+`withFileLock` takes a per-call wait limit. pi-ai runs an OAuth refresh *inside* `credentials.modify()`, so the record write path holds the lock across a network round trip; the 2s default was chosen for a render-and-rename and would fail every other writer of the document. The retry cadence stays fixed — that is a protocol constant — while how long to wait becomes a property of the operation holding the lock.
+
+Withdrawal settles an attempt whether or not its flow reacts to the signal. A flow is supposed to stop when its signal fires, but one that does not would hold its key for the life of the process, and a wedged key is indistinguishable from a busy one from outside. The orphaned run is left to finish on its own.
+
+## Alternatives considered
+
+- **Putting the pi-ai `CredentialStore` shape into the seam itself.** It is the shape that works and it is already designed. It also names `api_key`/`oauth` as the world's two credential kinds and keys by provider id, which is the ownership loss above; a second adapter family would have to pretend to be pi-ai to participate. The record union is deliberately one step more abstract in exactly two places — the key, and the opacity of a grant.
+- **A dedicated login-interaction seam beside `user-questions`.** Authorization prompts look like questions, and reusing `ctx.userQuestions` was tempting. But that seam is built for a model's tool call to pause on an agent's behalf: it validates the calling agent, refuses a delegated caller, and has one ambient UI provider. An authorization prompt has no agent, must reach the configuration page that started it, and can be withdrawn per prompt by a browser callback winning a race. The vocabularies overlap; the lifecycles do not.
+- **Reading `~/.codex/auth.json` into a store.** It makes Codex work without any of this, and pi-ai would own the refresh. It also binds the harness to another tool's private file format for one provider, and leaves every other login unbuilt.
+- **Joining a second `begin()` to the attempt already running.** Friendlier than refusing, until two humans are answering the same flow's questions. Refusal with `inFlight` on the entry lets a surface disable the button rather than discover the state by error.
+- **Keeping the OAuth-only withholding as a safety net.** It would now hide a provider that works. The predicate is deleted rather than left inert; `docs/subsystems/credentials.md` and the package READMEs carry what replaced it.
+
+## Consequences
+
+`.credentials.yaml` gains a version and two sections, and the pre-release flat layout is refused by name with the migration stated in the message — pre-release stance, no compatibility shim. Every fixture in the repo that wrote the flat document was rewritten; the llm suites' fixtures were missed by the record change itself and fixed here.
+
+`openai-codex` returns to the provider picker and to the Models page directory. Signing in is offered for every installed provider that ships a login, which today is all 38 — 31 collect a key through pi-ai's own prompt, six offer that beside a subscription login, and Codex offers only the subscription login.
+
+What this does not yet include is the surface: the wire contract that carries notices and prompts to the browser, and the Models-page control that starts a login. Until that lands, the flows are reachable only in-process, and a deployment still configures a key by typing it into the settings form.
+
+Two limits are recorded in the package READMEs rather than fixed. An attempt is not durable, so reloading the page mid-login abandons it. And signing out is `deleteRecord`, which forgets the record locally without telling the issuer; a provider needing a server-side revoke has nowhere to declare it.
+
+## Testing
+
+The seam's suite pins the lifecycle it owns: single-flight refusal and release, withdrawal before the flow starts and during it, a flow that ignores its signal, the commit confirmation, and the settlement event including the `failed` case a caller sees as a thrown error. The invariant companion pins that a settled key is a free key, because a wedged one is otherwise invisible.
+
+`llm-pi-ai` covers the three translations against a real `$DSH_HOME` document — an api-key credential field by field, an OAuth credential verbatim including its refresh half, a foreign plugin's record skipped by scope, and the write refusal without a credentials service — plus every `AuthEvent` and `AuthPrompt` member restated, with `Models.login()` mocked at the collection boundary since a real one opens a browser. Two real-composition tests boot the plugin with and without the authorization seam.
+
+The `models-settings` and `onboarding-usable-provider` web e2e goldens regain exactly the `openai-codex` option line they lost when it was withheld — the whole assembled-application difference this change makes today, because the Models page has no login control yet to record.
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
new file mode 100644
index 0000000000..e730b00c7b
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
@@ -0,0 +1,66 @@
+# Agent Note: 凭据记录与授权 flow
+
+Status: implemented
+
+[English](2026-08-13-credential-records-and-authorization-flows.md) | 中文
+
+## Problem
+
+harness 的凭据平面只能表达一种机密：藏在某个环境变量名之后的值。`CredentialRef` 是一个 POSIX 标识符，解析时按进程环境、受管文件、`.env` 回退分层，每个消费方按操作读取。这恰好覆盖 API key，此外什么都不覆盖。
+
+有些凭据不是"可以让部署方去存"的值。它们是被**取得**的——与人对话：对方打开页面、批准账号、把码粘回来——产出的是一份带 refresh 半边、会在用户背后轮换的 token 文档。pi-ai 直接建模了这一点（`Credential = ApiKeyCredential | OAuthCredential`、由应用拥有的 `CredentialStore`、`Models.login()`），而 harness 无处安放其中任何一项。`PiAiAdapter` 用不带参数的 `createModels()` 构造集合，于是那个 store 就是 pi-ai 的内存默认实现：每次启动为空，每次配置变更被丢弃。只以 OAuth 认证的 `openai-codex` 因此每个请求都以 `Provider is not configured` 失败——[被目录withheld](../bug-fix/2026-08-13-oauth-only-providers-withheld.md) 作为发布前修复，它移除了错误的供给，但没有补上能力。
+
+同一处缺失还带来另外两个缺口。提供方自带的凭据发现是对着裸进程环境跑的，因此凭据 seam 保管的密钥对它不可见，本地凭据文件更是从未被查找过。而登录没有任何界面可以发起，因为 harness 里没有任何东西能代替插件向人发问。
+
+## Decision
+
+三个 seam，各自拥有一个问题；所有 pi-ai 概念都藏在 `llm-pi-ai` 内部的适配器背后。
+
+**`dsh-credentials` 长出第二个键空间。** `CredentialRef` 回答*这个环境变量名背后是什么*；`CredentialKey` 回答*这个插件为这个 id 持有什么凭据*。记录联合体是 `{ kind: 'api-key', key?, env? } | { kind: 'grant', payload }`——api-key 那半是结构化的，因为 seam 能描述它；grant 那半是不透明的，因为拥有 token 格式的库应当继续拥有它。对 payload 的唯一约束是它能原样通过一次 JSON 往返，读写两个方向都会校验。
+
+键的形式是 `<scope>/<id>`，其中 scope 是**拥有该记录的插件的注册名**，不是提供方名。用户知道的是 `openai-codex`；究竟哪个 adapter 家族为记录里的字节负责，恰恰是裸提供方名会丢掉的信息。服务同一个提供方名的两个插件会互相读到对方的 payload，已卸载插件留下的记录也无法与仍在使用的区分开。`/` 同时让两种文法互斥，两个键空间因此不可能相撞。这以"同一个 provider 路由只由一个 adapter 注册"为前提，而 LLM 注册表本就强制了这一点。
+
+记录不分层。授权 grant 没有任何"环境"可供读取，因此记录是否存在就是全部事实，管辖引用的空值规则在此不适用：一条既无 key 也无 env 的 `api-key` 记录，陈述的是其拥有者确认了环境认证可用，这属于已配置。
+
+**`dsh-authorization` 拥有对话，从不拥有协议。** 知道如何取得自己那份凭据的插件，以该 flow 写入的 `CredentialKey` 注册。seam 对每个键同时只跑一次尝试，路由一套中立的 notice/prompt 词汇，然后结算。第二种授权协议以另一个 flow 的形式到来，而不是另一个 seam；能渲染一个 flow 的界面就能渲染全部 flow。
+
+两个选择承担了主要分量：
+
+- **写入由 flow 拥有。** `run()` 返回即表示记录已通过 `ctx.credentials` 提交；seam 随后核实，并拒绝返回时没留下记录的 flow。正是这一点让 `Models.login()`——它把持久化当作登录的一部分，经由 store 适配器完成——保持为唯一写入方，而不是把凭据复制出来再写第二遍。
+- **交互随请求传入，而非注册表。** 发起授权的一方才是能与人对话的一方，因此提示恰好抵达发问的那个页面，无头调用方传入一个直接拒绝的交互实现，也不存在"环境提供方缺席"或"该归两个已打开标签页中哪一个"的问题。
+
+**三处翻译全都留在 `llm-pi-ai`。** `credentialStoreFrom` 把 pi-ai 的 `CredentialStore` 映射到记录；`authContextFrom` 先查凭据 seam 再查启动环境来回答 pi-ai 的环境提问，文件存在性则按宿主进程的文件系统判断；`registerPiAiFlows` 把 pi-ai 的 `AuthEvent`/`AuthPrompt` 重述为中立词汇并运行 `Models.login()`。每个集合都用前两者构造，正是这一点让已登录的提供方在配置变更导致集合重建之后仍然处于登录状态。有了行得通的姿态之后，目录不再扣留仅 OAuth 的路由，`openai-codex` 重新被提供。
+
+凭据平面仍是可选的，正如它在引用解析上一贯如此。没有凭据服务时读取回答"未存储"，因为这样的组合确实不持有任何凭据；写入则指名拒绝，因为一次 grant 凭空蒸发的登录会先报告成功、再让每个请求失败。flow 注册通过 `ctx.inject` 限定在授权 seam 之下，因此 headless 或 ACP 组合挂载后没有登录能力，其余一切不变。
+
+### seam 底下需要的两处机制
+
+`withFileLock` 接受按调用声明的等待上限。pi-ai 在 `credentials.modify()` **内部**执行 OAuth 刷新，因此记录写入路径要跨越一次网络往返持锁；2 秒的默认值是按"渲染并 rename"的量级选的，会让该文档的每一个其他写入方失败。重试节奏保持固定——那是协议常量——而"等多久"成为持锁操作自身的属性。
+
+撤销会结算一次尝试，无论其 flow 是否响应信号。flow 本应在信号触发时停止，但不停止的那个会把键占到进程结束，而被卡住的键从外部看与忙碌中的键无法区分。被遗弃的执行体听任其自行结束。
+
+## Alternatives considered
+
+- **把 pi-ai 的 `CredentialStore` 形状直接放进 seam。** 那是行得通且已经设计好的形状。它同时把 `api_key`/`oauth` 定为世上仅有的两种凭据类别，并以 provider id 为键，也就是上文那种所有权丢失；第二个 adapter 家族将不得不假装自己是 pi-ai 才能参与。记录联合体刻意只在两处更抽象一步——键，以及 grant 的不透明性。
+- **在 `user-questions` 旁再建一个专用登录交互 seam。** 授权提示看起来就像问题，复用 `ctx.userQuestions` 很有诱惑力。但那个 seam 是为"模型的工具调用代表 agent 暂停"而建的：它校验调用方 agent、拒绝被委派的调用方、只有一个环境 UI 提供方。授权提示没有 agent，必须抵达发起它的配置页面，还可能被浏览器回调赢得竞速后按单个提示撤下。词汇重叠，生命周期不重叠。
+- **把 `~/.codex/auth.json` 读进一个 store。** 这能让 Codex 在不做上述任何事的情况下工作，刷新也由 pi-ai 负责。它同时为了一个提供方把 harness 绑死在另一个工具的私有文件格式上，且其余所有登录仍然没有着落。
+- **让第二次 `begin()` 并入已在运行的尝试。** 比拒绝更友好，直到两个人在回答同一个 flow 的问题为止。以 entry 上的 `inFlight` 配合拒绝，界面得以禁用按钮，而不是靠报错才发现状态。
+- **把"仅 OAuth 则扣留"当安全网保留。** 它现在会藏起一个能用的提供方。该判定被删除而不是留成惰性代码；`docs/subsystems/credentials.md` 与包 README 承载了取代它的内容。
+
+## Consequences
+
+`.credentials.yaml` 增加了版本与两个分区，发布前的扁平布局被指名拒绝，迁移办法写在报错信息里——发布前立场，不留兼容垫片。仓库中所有写扁平文档的 fixture 都已改写；llm 各套件的 fixture 被记录改动本身漏掉了，在此补上。
+
+`openai-codex` 回到提供方选择器与 Models 页目录。凡是自带登录的已安装提供方都会得到登录入口，而今天这是全部 38 个——31 个经 pi-ai 自己的提示收取密钥，6 个在此之外还提供订阅登录，Codex 只提供订阅登录。
+
+尚未包含的是界面：把 notice 与 prompt 送到浏览器的 wire 契约，以及 Models 页上发起登录的控件。在那之前，flow 只能在进程内触达，部署方仍然通过在设置表单里输入密钥来配置。
+
+有两项限制记在包 README 里而非就地修复。一次尝试不可持久，登录途中刷新页面会丢弃它。登出即 `deleteRecord`，它只在本地遗忘而不通知签发方；需要服务端吊销的提供方无处声明这一点。
+
+## Testing
+
+seam 自己的套件钉住它拥有的生命周期：单飞的拒绝与释放、flow 启动前与进行中的撤销、一个忽略自身信号的 flow、提交核实，以及包含"调用方看到的是抛出错误"那种 `failed` 情形的结算事件。invariant companion 钉住"已结算的键就是空闲的键"，因为被卡住的键否则不可见。
+
+`llm-pi-ai` 针对一份真实的 `$DSH_HOME` 文档覆盖三处翻译——逐字段的 api-key 凭据、连 refresh 半边一起原样保存的 OAuth 凭据、按 scope 跳过的他插件记录，以及没有凭据服务时的写入拒绝——外加每一个 `AuthEvent` 与 `AuthPrompt` 成员的重述；`Models.login()` 在集合边界处被 mock，因为真实登录会打开浏览器。两个真实组合测试分别在挂载与不挂载授权 seam 的情况下启动插件。
+
+`models-settings` 与 `onboarding-usable-provider` 两条 web e2e golden 恰好收回了被扣留时失去的那一行 `openai-codex` 选项——这是本次改动今天在装配后的应用上造成的全部差异，因为 Models 页还没有可录制的登录控件。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.i18n.yaml
index f5765160ac..cac8976398 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.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/bug-fix/2026-08-13-oauth-only-providers-withheld.md
-2026-08-13-oauth-only-providers-withheld.md: 8c85c2900fd0af7c97a3ac8f04d3c6a2f469f8b0
-2026-08-13-oauth-only-providers-withheld.zh.md: 8f05d096a5d474407585bcbd84bd47da8a1abb2e
+2026-08-13-oauth-only-providers-withheld.md: 138cae6f56c0d8355d8db3bddd27aede7caf5b09
+2026-08-13-oauth-only-providers-withheld.zh.md: da8326d1ea1772623367a4a6a1477686b41d268e
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.md b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.md
index 8c85c2900f..138cae6f56 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.md
@@ -38,6 +38,8 @@ Resolution is untouched. A profile naming `apiKeyEnv` on an OAuth-only route sti
 
 Two adjacent gaps remain and are recorded in the package README: a route naming no credential still resolves through the catalog provider's own discovery, which reads process environment variables only — not `~/.aws/credentials`, and not the harness credential seam — and the resulting failure is still the catch-all `PI_AI_ERROR`.
 
+The withholding has since been retired: [credential records and authorization flows](../architecture/2026-08-13-credential-records-and-authorization-flows.md) gave the adapter a durable credential store and a login flow, so `openai-codex` is offered again and `catalogProviderTakesApiKey` is gone. The two boundaries below are what kept that reversal to one predicate and one directory filter.
+
 ## Testing
 
 Package tests pin both halves of the union: the withheld route is absent from `listConfigurableProviders()` while `anthropic` and `openai` stay, and a stored `openai-codex` profile still produces a full entry with `declared: false`. The existing resolution tests are unchanged and still pass, which is what shows the withholding did not narrow what a hand-written profile can serve. The `models-settings` and `onboarding-usable-provider` web e2e goldens lost exactly the `openai-codex` option line, recorded against the real assembled application.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.zh.md b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.zh.md
index 8f05d096a5..da8326d1ea 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-13-oauth-only-providers-withheld.zh.md
@@ -38,6 +38,8 @@ resolution 未被触动。在仅 OAuth 的路由上指定 `apiKeyEnv` 的 profil
 
 两处相邻缺口仍在，并记录在包 README 中：不指定凭据的路由仍走 catalog 提供方自带的发现，而它只读进程环境变量——不读 `~/.aws/credentials`，也不读 harness 凭据 seam——且由此产生的失败仍是兜底的 `PI_AI_ERROR`。
 
+该扣留其后已被撤销：[凭据记录与授权 flow](../architecture/2026-08-13-credential-records-and-authorization-flows.md) 为适配器补上了可持久的凭据存储与登录 flow，因此 `openai-codex` 重新被提供，`catalogProviderTakesApiKey` 也已删除。下文那两条边界正是把这次反转限制在一个判定函数与一个目录过滤器之内的原因。
+
 ## 测试
 
 包测试钉住联合的两半：不予提供的路由不出现在 `listConfigurableProviders()` 中，而 `anthropic` 与 `openai` 仍在；已存储的 `openai-codex` profile 仍产出完整条目且 `declared: false`。既有的 resolution 测试未改动且依然通过，这正是「不提供」没有收窄手写 profile 可服务范围的证据。`models-settings` 与 `onboarding-usable-provider` 两条 web e2e golden 恰好各少了 `openai-codex` 这一行选项，录自真实装配的应用。
diff --git a/apps/web/tests/snapshots/models-settings/empty.expected.md b/apps/web/tests/snapshots/models-settings/empty.expected.md
index 2c928e2f0d..cea14113ac 100644
--- a/apps/web/tests/snapshots/models-settings/empty.expected.md
+++ b/apps/web/tests/snapshots/models-settings/empty.expected.md
@@ -44,6 +44,7 @@
     - option "moonshotai-cn"
     - option "nvidia"
     - option "openai"
+    - option "openai-codex"
     - option "opencode"
     - option "opencode-go"
     - option "openrouter"
diff --git a/apps/web/tests/snapshots/onboarding-usable-provider/dismissed.expected.md b/apps/web/tests/snapshots/onboarding-usable-provider/dismissed.expected.md
index 809e7880ff..84c7358b54 100644
--- a/apps/web/tests/snapshots/onboarding-usable-provider/dismissed.expected.md
+++ b/apps/web/tests/snapshots/onboarding-usable-provider/dismissed.expected.md
@@ -48,6 +48,7 @@
     - option "moonshotai-cn"
     - option "nvidia"
     - option "openai"
+    - option "openai-codex"
     - option "opencode"
     - option "opencode-go"
     - option "openrouter"

From 9eaaeaeb9602b46dc4d00c542ed16704435cc005 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 17 Aug 2026 13:46:13 +0800
Subject: [PATCH 24/34] fix(credentials,authorization,llm-pi-ai): harden the
 auth seams per review

Review findings on #2509, all confirmed:

- Every writer of .credentials.yaml now waits out the record-mutation
  lock (DOCUMENT_LOCK_WAIT_MS): refs and records share one file and one
  lock, so a reference write or record delete contending with an OAuth
  refresh must not fail at the 2s file-work default.
- api-key records are admitted before they are rendered: an empty key,
  a non-POSIX env name, or an empty env value is refused at the write
  instead of persisting a document the next boot rejects wholesale.
- llm-pi-ai no longer lets the credential-key grammar reject legal
  route ids: reads answer "nothing stored" via isCredentialKeySegment
  (new dsh-credentials export), deletes have nothing to remove, and only
  a write refuses, as LlmError UNSTORABLE_PROVIDER_ID; flow registration
  skips a future catalog id outside the grammar instead of failing the
  mount.
- authorization/settled fans out with contained listener failures on
  the credentials seam's terms (INVARIANT still rethrows), so a broken
  watcher can never turn a finished attempt into a failure.
- notify() is fire-and-forget at the seam: a surface that cannot render
  a notice loses the notice, never the attempt.
- A declined prompt is an outcome: interactions reject with the new
  AuthorizationDeclinedError and the attempt settles cancelled instead
  of failed.
- NOT_COMMITTED now confirms a commit observed during the attempt
  (credentials/record-updated for the flow's key), so a re-auth cannot
  pass a stale record off as fresh; a flow that deletes its record is
  refused on the same code.

READMEs, the subsystem/event/config catalogs, and the Agent Note follow
the shipped behavior; memory.ts carries the dedup TODO.
---
 ...-records-and-authorization-flows.i18n.yaml |   4 +-
 ...dential-records-and-authorization-flows.md |   6 +-
 ...tial-records-and-authorization-flows.zh.md |   6 +-
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   2 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/event-producer-consumer.i18n.yaml        |   4 +-
 docs/event-producer-consumer.md               |   4 +-
 docs/event-producer-consumer.zh.md            |   4 +-
 docs/subsystems/credentials.i18n.yaml         |   4 +-
 docs/subsystems/credentials.md                |  12 +-
 docs/subsystems/credentials.zh.md             |  12 +-
 .../authorization/README.i18n.yaml            |   4 +-
 packages/credentials/authorization/README.md  |  10 +-
 .../credentials/authorization/README.zh.md    |  10 +-
 .../credentials/authorization/src/index.ts    | 148 +++++++++++++---
 .../authorization/tests/authorization.spec.ts | 159 ++++++++++++++++++
 .../credentials/authorization/tests/memory.ts |   3 +
 .../credentials-local/src/index.ts            |  47 ++++--
 .../credentials-local/tests/records.spec.ts   |  18 ++
 .../tests/review-fixes.spec.ts                |  33 +++-
 .../credentials/credentials/README.i18n.yaml  |   4 +-
 packages/credentials/credentials/README.md    |   2 +-
 packages/credentials/credentials/README.zh.md |   2 +-
 packages/credentials/credentials/src/index.ts |  13 ++
 .../credentials/tests/credentials.spec.ts     |  15 +-
 .../extensions/tool-cordis/src/api-catalog.ts |   4 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |   4 +-
 packages/llm/llm-pi-ai/README.md              |   2 +-
 packages/llm/llm-pi-ai/README.zh.md           |   2 +-
 packages/llm/llm-pi-ai/src/auth.ts            |  19 ++-
 packages/llm/llm-pi-ai/src/login.ts           |  11 ++
 packages/llm/llm-pi-ai/tests/auth.spec.ts     |  14 ++
 33 files changed, 500 insertions(+), 88 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
index 269ef4ce46..999a35f13c 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.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/architecture/2026-08-13-credential-records-and-authorization-flows.md
-2026-08-13-credential-records-and-authorization-flows.md: b962393f3efdf883b918ae47aa96d37846c12dd6
-2026-08-13-credential-records-and-authorization-flows.zh.md: e730b00c7be427e243abfab5206eac13079b11cc
+2026-08-13-credential-records-and-authorization-flows.md: 19de5a5212e12a678a2162275f26130cf54f4f46
+2026-08-13-credential-records-and-authorization-flows.zh.md: ee79248a8c6ae1d652bb280bb9863c01655715c7
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
index b962393f3e..19de5a5212 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
@@ -26,7 +26,7 @@ Records do not layer. There is no environment an authorization grant could be re
 
 Two choices carry the weight:
 
-- **The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms it and refuses a flow that resolved without one. This is what lets `Models.login()` — which persists through the store adapter as part of logging in — stay the single writer, instead of the credential being copied back out and written a second time.
+- **The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms a commit it observed during the attempt — presence alone would let a re-authorization pass a stale record off as fresh — and refuses a flow that resolved without one. This is what lets `Models.login()` — which persists through the store adapter as part of logging in — stay the single writer, instead of the credential being copied back out and written a second time.
 - **The interaction travels with the request, not a registry.** Whoever starts an authorization is the one who can talk to the human about it, so prompts reach exactly the page that asked, a headless caller supplies an interaction that declines, and there is no ambient provider to be absent or ambiguous between two open tabs.
 
 **`llm-pi-ai` holds all three translations.** `credentialStoreFrom` maps pi-ai's `CredentialStore` onto records; `authContextFrom` answers pi-ai's ambient questions from the credential seam, then the launch environment, with file existence checked against the host process's filesystem; `registerPiAiFlows` restates pi-ai's `AuthEvent`/`AuthPrompt` in the neutral vocabulary and runs `Models.login()`. Every collection is built with the first two, which is what keeps a signed-in provider signed in across the collection rebuild a configuration change causes. With a posture that works, the directory stops withholding OAuth-only routes and `openai-codex` is offered again.
@@ -35,7 +35,9 @@ The credential plane stays optional, as it already was for reference resolution.
 
 ### Two mechanisms the seams needed underneath
 
-`withFileLock` takes a per-call wait limit. pi-ai runs an OAuth refresh *inside* `credentials.modify()`, so the record write path holds the lock across a network round trip; the 2s default was chosen for a render-and-rename and would fail every other writer of the document. The retry cadence stays fixed — that is a protocol constant — while how long to wait becomes a property of the operation holding the lock.
+`withFileLock` takes a per-call wait limit. pi-ai runs an OAuth refresh *inside* `credentials.modify()`, so the record write path holds the lock across a network round trip; the 2s default was chosen for a render-and-rename and would fail every other writer of the document. The retry cadence stays fixed — that is a protocol constant — while the wait is sized by the longest holder a contender can meet: refs and records share one file and one lock, so every writer of the document (`DOCUMENT_LOCK_WAIT_MS`, reference writes and record deletes included) waits an OAuth refresh out, not only the mutation that runs one.
+
+The seam's edges get the same discipline as its write path. A prompt decline is an outcome, not a breakage — an interaction rejects with `AuthorizationDeclinedError` and the attempt settles `cancelled` — while a notice a surface cannot render is logged and lost rather than failing the flow, and `authorization/settled` fans out with contained listener failures on the credentials seam's terms. On the store side, an api-key record is admitted before it is rendered (what `parseRecord` refuses at the next boot is refused at the write), and `llm-pi-ai` asks `isCredentialKeySegment` before addressing a record, so an arbitrary hand-declared route key reads as "nothing stored" instead of throwing mid-resolution.
 
 Withdrawal settles an attempt whether or not its flow reacts to the signal. A flow is supposed to stop when its signal fires, but one that does not would hold its key for the life of the process, and a wedged key is indistinguishable from a busy one from outside. The orphaned run is left to finish on its own.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
index e730b00c7b..ee79248a8c 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
@@ -26,7 +26,7 @@ harness 的凭据平面只能表达一种机密：藏在某个环境变量名之
 
 两个选择承担了主要分量：
 
-- **写入由 flow 拥有。** `run()` 返回即表示记录已通过 `ctx.credentials` 提交；seam 随后核实，并拒绝返回时没留下记录的 flow。正是这一点让 `Models.login()`——它把持久化当作登录的一部分，经由 store 适配器完成——保持为唯一写入方，而不是把凭据复制出来再写第二遍。
+- **写入由 flow 拥有。** `run()` 返回即表示记录已通过 `ctx.credentials` 提交；seam 核实的是本次尝试期间观察到的提交——只看记录存在与否，会让重新授权把陈旧记录冒充成新鲜的——并拒绝返回时没提交记录的 flow。正是这一点让 `Models.login()`——它把持久化当作登录的一部分，经由 store 适配器完成——保持为唯一写入方，而不是把凭据复制出来再写第二遍。
 - **交互随请求传入，而非注册表。** 发起授权的一方才是能与人对话的一方，因此提示恰好抵达发问的那个页面，无头调用方传入一个直接拒绝的交互实现，也不存在"环境提供方缺席"或"该归两个已打开标签页中哪一个"的问题。
 
 **三处翻译全都留在 `llm-pi-ai`。** `credentialStoreFrom` 把 pi-ai 的 `CredentialStore` 映射到记录；`authContextFrom` 先查凭据 seam 再查启动环境来回答 pi-ai 的环境提问，文件存在性则按宿主进程的文件系统判断；`registerPiAiFlows` 把 pi-ai 的 `AuthEvent`/`AuthPrompt` 重述为中立词汇并运行 `Models.login()`。每个集合都用前两者构造，正是这一点让已登录的提供方在配置变更导致集合重建之后仍然处于登录状态。有了行得通的姿态之后，目录不再扣留仅 OAuth 的路由，`openai-codex` 重新被提供。
@@ -35,7 +35,9 @@ harness 的凭据平面只能表达一种机密：藏在某个环境变量名之
 
 ### seam 底下需要的两处机制
 
-`withFileLock` 接受按调用声明的等待上限。pi-ai 在 `credentials.modify()` **内部**执行 OAuth 刷新，因此记录写入路径要跨越一次网络往返持锁；2 秒的默认值是按"渲染并 rename"的量级选的，会让该文档的每一个其他写入方失败。重试节奏保持固定——那是协议常量——而"等多久"成为持锁操作自身的属性。
+`withFileLock` 接受按调用声明的等待上限。pi-ai 在 `credentials.modify()` **内部**执行 OAuth 刷新，因此记录写入路径要跨越一次网络往返持锁；2 秒的默认值是按"渲染并 rename"的量级选的，会让该文档的每一个其他写入方失败。重试节奏保持固定——那是协议常量——而等待时长按争用方可能遇到的最长持锁方来定：refs 与 records 共享同一份文件、同一把锁，因此该文档的每一个写入方（`DOCUMENT_LOCK_WAIT_MS`，含引用写入与记录删除）都要等得起一次 OAuth 刷新，而不只是执行刷新的那个 mutation。
+
+seam 的边缘与写入路径同一纪律。prompt 被拒是结果而非故障——交互实现以 `AuthorizationDeclinedError` 拒绝，尝试以 `cancelled` 结算；渲染不了 notice 的界面只丢那条 notice、绝不拖垮 flow；`authorization/settled` 按 credentials seam 的条款以遏制方式分发监听器故障。存储侧，api-key 记录在渲染前先行准入（`parseRecord` 下次启动会拒绝的，写入时就拒绝），`llm-pi-ai` 在寻址记录前先问 `isCredentialKeySegment`，任意手写路由键读作「没有存储任何东西」，而不是在解析途中抛错。
 
 撤销会结算一次尝试，无论其 flow 是否响应信号。flow 本应在信号触发时停止，但不停止的那个会把键占到进程结束，而被卡住的键从外部看与忙碌中的键无法区分。被遗弃的执行体听任其自行结束。
 
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 6ddf964471..e25c7d8c31 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: b93b91f12703ea52225e1202d6cdc376a0b96331
-config-catalog.zh.md: 2562cae37ad4ebce7646b80d7c54cc59bcfd0abf
+config-catalog.md: 36f3e96e69207076b1a1bdae58032f7b3d0c1b8f
+config-catalog.zh.md: 8e66b1b2c9c4e54be33fd9c2ccff5b8a3494aab6
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b93b91f127..36f3e96e69 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -567,7 +567,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:63`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:64`](../packages/credentials/credentials-local/src/index.ts)
 
 <a id="deepseek-aidsh-e2b"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 2562cae37a..8e66b1b2c9 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -569,7 +569,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/credentials/credentials-local/src/index.ts:63`](../packages/credentials/credentials-local/src/index.ts)
+来源：[`packages/credentials/credentials-local/src/index.ts:64`](../packages/credentials/credentials-local/src/index.ts)
 
 <a id="deepseek-aidsh-e2b"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index b7339dbd00..1ac2e8f56a 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: f5ead70b691b43bf9de4507d6753e7066c2d2013
-event-producer-consumer.zh.md: 7aa0f03492561e77c94ab36b5da1ee4b4346d861
+event-producer-consumer.md: 49c7a128fcf2539d342ad263bb856c40f2a33f0c
+event-producer-consumer.zh.md: dec8b443aa73ae919ceee7cd282846bea4e8ce18
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index f5ead70b69..49c7a128fc 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -22,7 +22,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, `apiproxy`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`emit`) | [`authorization`](../packages/credentials/authorization) |
+| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
@@ -30,7 +30,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
-| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | - |
+| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 7aa0f03492..dec8b443aa 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -24,7 +24,7 @@
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, `apiproxy`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`emit`) | [`authorization`](../packages/credentials/authorization) |
+| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
@@ -32,7 +32,7 @@
 | `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
-| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | - |
+| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index e2526345a5..8f9e2f9474 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: dd0f950b50fa4bcb9094f7b85227262b42e3b385
-credentials.zh.md: 3e906449db31d4889d8c87f27c765cccfc9ff539
+credentials.md: 8d75a254109dcce5d0b54cd4fd293a8ca4e335c5
+credentials.zh.md: 46edda84a063c539748da344d7efa66c7af666e7
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index dd0f950b50..8d75a25410 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -104,17 +104,19 @@ cancel(key: CredentialKey): void
  * and the second would answer questions the first was asked.
  *
  * @param request - the key, the method, the surface, and the cancel signal.
- * @returns `authorized` once the flow's record is committed and observed,
- *   or `cancelled` when the human or the caller withdrew.
+ * @returns `authorized` once the flow's record is committed during this
+ *   attempt and observed, or `cancelled` when the human declined or the
+ *   caller withdrew.
  * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
  *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
  *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
- *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+ *   `NOT_COMMITTED` when the flow resolved without committing a record
+ *   during the attempt.
  */
 async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
 ```
 
-Source: [`packages/credentials/authorization/src/index.ts:163`](../../packages/credentials/authorization/src/index.ts)
+Source: [`packages/credentials/authorization/src/index.ts:182`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
@@ -208,7 +210,7 @@ abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord |
 abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:164`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:177`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="authorization-events"></a>
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 3e906449db..46edda84a0 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -104,17 +104,19 @@ cancel(key: CredentialKey): void
  * and the second would answer questions the first was asked.
  *
  * @param request - the key, the method, the surface, and the cancel signal.
- * @returns `authorized` once the flow's record is committed and observed,
- *   or `cancelled` when the human or the caller withdrew.
+ * @returns `authorized` once the flow's record is committed during this
+ *   attempt and observed, or `cancelled` when the human declined or the
+ *   caller withdrew.
  * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
  *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
  *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
- *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+ *   `NOT_COMMITTED` when the flow resolved without committing a record
+ *   during the attempt.
  */
 async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>
 ```
 
-Source: [`packages/credentials/authorization/src/index.ts:163`](../../packages/credentials/authorization/src/index.ts)
+Source: [`packages/credentials/authorization/src/index.ts:182`](../../packages/credentials/authorization/src/index.ts)
 
 <a id="ctxcredentials--credentialprovider-abstract-seam"></a>
 
@@ -208,7 +210,7 @@ abstract modifyRecord( key: CredentialKey, mutate: (current: CredentialRecord |
 abstract deleteRecord(key: CredentialKey): Promise<void>
 ```
 
-Source: [`packages/credentials/credentials/src/index.ts:164`](../../packages/credentials/credentials/src/index.ts)
+Source: [`packages/credentials/credentials/src/index.ts:177`](../../packages/credentials/credentials/src/index.ts)
 
 <a id="authorization-events"></a>
 
diff --git a/packages/credentials/authorization/README.i18n.yaml b/packages/credentials/authorization/README.i18n.yaml
index cdec37bfab..21d3600aa1 100644
--- a/packages/credentials/authorization/README.i18n.yaml
+++ b/packages/credentials/authorization/README.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 packages/credentials/authorization/README.md
-README.md: f73d2231456d0873cef7ea047fe537629a7552e0
-README.zh.md: ecceaa4f90a971deebe89e8dd6e51157aa0072a0
+README.md: 373a070c1a5cbb9a60e7ae14734a752515e0a0e4
+README.zh.md: 8dcdc081a87979ec712f18189ff7bbe937328236
diff --git a/packages/credentials/authorization/README.md b/packages/credentials/authorization/README.md
index f73d223145..373a070c1a 100644
--- a/packages/credentials/authorization/README.md
+++ b/packages/credentials/authorization/README.md
@@ -6,7 +6,7 @@ Authorization Service Definition (`ctx.authorization`). Some credentials cannot
 
 **A flow is a plugin's knowledge of how to get its own credential.** It is registered under the [`CredentialKey`](../credentials/README.md#two-key-spaces-two-questions) it writes, so a flow says which record it produces and, through that key's scope, which plugin answers for the format inside it. A second authorization protocol arrives as another flow, not as another seam.
 
-**The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms it and refuses a flow that resolved without one. Committing inside the flow is what lets a library that persists through its own store adapter stay the single writer instead of being copied back out and written twice.
+**The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms a commit it observed during the attempt — presence alone would let a re-authorization pass a stale record off as fresh — and refuses a flow that resolved without one. Committing inside the flow is what lets a library that persists through its own store adapter stay the single writer instead of being copied back out and written twice.
 
 **The interaction travels with the request, not a registry.** Whoever starts an authorization is the one who can talk to the human about it, so prompts reach exactly the surface that asked and a headless caller supplies an interaction that declines. There is no ambient provider to be absent, and no question about which of two open pages a prompt belongs to.
 
@@ -14,7 +14,7 @@ Authorization Service Definition (`ctx.authorization`). Some credentials cannot
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import type { AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { AuthorizationDeclinedError, type AuthorizationSession } from '@deepseek-ai/dsh-authorization'
 import { credentialKey } from '@deepseek-ai/dsh-credentials'
 
 declare const ctx: Context
@@ -39,7 +39,7 @@ ctx.authorization.list()                    // [{ key, label, methods, inFlight
 ctx.authorization.describe(key)             // the same entry, or undefined
 await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
   key,
-  interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('headless')) },
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new AuthorizationDeclinedError()) },
 })
 ctx.authorization.cancel(key)               // withdraw whatever is running for the key
 dispose()
@@ -51,7 +51,9 @@ One attempt per key at a time. A second caller is refused with `ALREADY_IN_FLIGH
 
 An attempt whose caller has already withdrawn never claims the key and never starts the flow — relying on each flow to check its signal before the first await would let one that does not hang holding the key. Validation still runs first, so a caller naming a key or method that does not exist hears about it whether or not it also gave up.
 
-`authorization/settled (key, settlement)` fires after the key is released, for every terminal outcome. `settlement` adds `failed` to the two statuses `begin()` can return: a failure reaches its own caller as a thrown error, so the event stream is the only place a watcher that did not start the attempt can tell a refusal from a breakage.
+A human's "no" is an outcome, not a breakage. An interaction that declines rejects its prompt with `AuthorizationDeclinedError`, and an attempt that fails after a declined prompt settles as `cancelled`, exactly as a withdrawn signal does; any other prompt rejection stays a flow failure that reaches the caller. A notice is fire-and-forget on the same principle, held at the seam: a surface that cannot render one loses the notice, never the attempt.
+
+`authorization/settled (key, settlement)` fires after the key is released, for every terminal outcome. `settlement` adds `failed` to the two statuses `begin()` can return: a failure reaches its own caller as a thrown error, so the event stream is the only place a watcher that did not start the attempt can tell a refusal from a breakage. Listener failures are contained: every listener runs, a throw or rejection is logged without changing the finished attempt's outcome, and only an `INVARIANT`-coded failure rethrows after the rest ran.
 
 ## The interaction vocabulary
 
diff --git a/packages/credentials/authorization/README.zh.md b/packages/credentials/authorization/README.zh.md
index ecceaa4f90..8dcdc081a8 100644
--- a/packages/credentials/authorization/README.zh.md
+++ b/packages/credentials/authorization/README.zh.md
@@ -6,7 +6,7 @@
 
 **flow 是某个插件"如何取得自己那份凭据"的知识。** 它以自己写入的 [`CredentialKey`](../credentials/README.md#two-key-spaces-two-questions) 注册，因此 flow 声明了自己产出哪条记录，并通过该键的 scope 声明由哪个插件为记录内部的格式负责。第二种授权协议以另一个 flow 的形式到来，而不是另一个 seam。
 
-**写入由 flow 拥有。** `run()` 返回即表示记录已经通过 `ctx.credentials` 提交；seam 随后核实，并拒绝那些返回时没留下记录的 flow。让提交发生在 flow 内部，才能使一个通过自有 store 适配器持久化的库保持为唯一写入方，而不是把凭据复制出来再写第二遍。
+**写入由 flow 拥有。** `run()` 返回即表示记录已经通过 `ctx.credentials` 提交；seam 核实的是它在本次尝试期间观察到的提交——只看记录存在与否，会让重新授权把陈旧记录冒充成新鲜的——并拒绝那些返回时没提交记录的 flow。让提交发生在 flow 内部，才能使一个通过自有 store 适配器持久化的库保持为唯一写入方，而不是把凭据复制出来再写第二遍。
 
 **交互随请求传入，而非注册表。** 发起授权的一方才是能与人对话的一方，因此提示恰好抵达发问的那个界面，无头调用方则传入一个直接拒绝的交互实现。这样既不存在"环境提供方缺席"的问题，也不会出现某个提示该归两个已打开页面中哪一个的疑问。
 
@@ -14,7 +14,7 @@
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import type { AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { AuthorizationDeclinedError, type AuthorizationSession } from '@deepseek-ai/dsh-authorization'
 import { credentialKey } from '@deepseek-ai/dsh-credentials'
 
 declare const ctx: Context
@@ -39,7 +39,7 @@ ctx.authorization.list()                    // [{ key, label, methods, inFlight
 ctx.authorization.describe(key)             // the same entry, or undefined
 await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
   key,
-  interaction: { notify: () => {}, prompt: () => Promise.reject(new Error('headless')) },
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new AuthorizationDeclinedError()) },
 })
 ctx.authorization.cancel(key)               // withdraw whatever is running for the key
 dispose()
@@ -51,7 +51,9 @@ dispose()
 
 调用方在发起前就已撤销的尝试，既不占用该键也不启动 flow——若指望每个 flow 都在首个 await 之前检查自己的 signal，那么没有检查的那个就会占着键一直挂起。校验仍然先执行，因此调用方给出的键或方法不存在时，无论它是否已经放弃都会收到报错。
 
-`authorization/settled (key, settlement)` 在键释放之后触发，覆盖每一种终态。`settlement` 在 `begin()` 能返回的两种状态之外增加了 `failed`：失败以抛出的错误抵达其调用方，因此事件流是未发起该尝试的旁观者唯一能区分"被拒绝"与"出故障"的地方。
+人的"不"是一种结果，不是故障。选择拒绝的交互实现让 prompt 以 `AuthorizationDeclinedError` 拒绝，在提示被拒之后才失败的尝试以 `cancelled` 结算，与 signal 撤销完全一致；其余任何 prompt 拒绝仍是抵达调用方的 flow 故障。notice 依同一原则即发即忘，并由 seam 兜底：渲染不了 notice 的界面丢掉的是那条 notice，而不是整次尝试。
+
+`authorization/settled (key, settlement)` 在键释放之后触发，覆盖每一种终态。`settlement` 在 `begin()` 能返回的两种状态之外增加了 `failed`：失败以抛出的错误抵达其调用方，因此事件流是未发起该尝试的旁观者唯一能区分"被拒绝"与"出故障"的地方。监听器故障被就地遏制：每个监听器都会执行，抛错或拒绝只记录日志、不改变已结束尝试的结果，仅 `INVARIANT` 编码的故障在其余监听器执行完后重抛。
 
 ## 交互词汇
 
diff --git a/packages/credentials/authorization/src/index.ts b/packages/credentials/authorization/src/index.ts
index 9cff052feb..502f2f2828 100644
--- a/packages/credentials/authorization/src/index.ts
+++ b/packages/credentials/authorization/src/index.ts
@@ -66,6 +66,23 @@ export class AuthorizationError extends HarnessError {
   }
 }
 
+/**
+ * The rejection an {@link AuthorizationInteraction.prompt} uses to say the
+ * human declined — dismissed the question, chose not to answer — rather than
+ * that the surface broke. An attempt whose flow fails after a prompt was
+ * declined settles as `cancelled`, the same outcome as a withdrawn signal,
+ * because the human saying no is a refusal, not a breakage. Only a human's
+ * "no" may reject with this class: a prompt withdrawn by its own `signal` (a
+ * flow retiring the losing question of a race) must reject with something
+ * else, or a later genuine failure would be misread as a decline.
+ */
+export class AuthorizationDeclinedError extends AuthorizationError {
+  constructor(message = 'the authorization prompt was declined') {
+    super(message, 'DECLINED')
+    this.name = 'AuthorizationDeclinedError'
+  }
+}
+
 /**
  * What a running flow is given to talk to the human. Every member is scoped to
  * one attempt: the flow neither knows nor chooses which surface is listening.
@@ -93,10 +110,11 @@ export interface AuthorizationSession {
 /**
  * A plugin's knowledge of how to obtain one credential. The flow owns the
  * write: `run()` resolving means the record for `key` is committed through
- * `ctx.credentials`, which the seam then confirms before reporting success.
- * Committing inside the flow is what lets a library that persists through its
- * own store adapter (pi-ai's `Models.login()`) stay the single writer instead
- * of being copied back out and written twice.
+ * `ctx.credentials` during that run, which the seam confirms — a commit
+ * observed within the attempt, still present after it — before reporting
+ * success. Committing inside the flow is what lets a library that persists
+ * through its own store adapter (pi-ai's `Models.login()`) stay the single
+ * writer instead of being copied back out and written twice.
  */
 export interface AuthorizationFlow {
   /** The credential record this flow writes. Its scope names the owning plugin. */
@@ -134,7 +152,8 @@ export interface AuthorizationInteraction {
    * Put a question to the human and wait.
    * @param prompt - what to ask, and how it should be presented.
    * @returns the typed text, or the chosen option's id.
-   * @throws when the human declines or the prompt is withdrawn.
+   * @throws {AuthorizationDeclinedError} when the human declines; any other
+   *   rejection reads as the surface failing, not as an answer.
    */
   prompt(prompt: AuthorizationPrompt): Promise<string>
 }
@@ -244,12 +263,14 @@ export class AuthorizationService extends Service {
    * and the second would answer questions the first was asked.
    *
    * @param request - the key, the method, the surface, and the cancel signal.
-   * @returns `authorized` once the flow's record is committed and observed,
-   *   or `cancelled` when the human or the caller withdrew.
+   * @returns `authorized` once the flow's record is committed during this
+   *   attempt and observed, or `cancelled` when the human declined or the
+   *   caller withdrew.
    * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
    *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
    *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
-   *   `NOT_COMMITTED` when the flow resolved without leaving a record behind.
+   *   `NOT_COMMITTED` when the flow resolved without committing a record
+   *   during the attempt.
    */
   async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome> {
     const { key } = request
@@ -286,10 +307,52 @@ export class AuthorizationService extends Service {
       this.running.delete(key)
       // After the slot is released, so a listener that reacts by starting the
       // next attempt is not refused by the one that just finished.
-      this.ctx.emit('authorization/settled', key, settlement)
+      this.settle(key, settlement)
     }
   }
 
+  /* jscpd:ignore-start -- deliberate symmetry with the credentials seam's
+     commit fan-out (`CredentialProvider`): the contained-dispatch shape is the
+     reviewed listener-lifecycle contract, and extracting it would couple the
+     two seams' event semantics. */
+  /**
+   * Fan `authorization/settled` out with contained listener failures: every
+   * listener runs, and a sync throw or async rejection is logged without
+   * changing the finished attempt's own outcome — except `INVARIANT`-coded
+   * failures, which rethrow after every listener ran. The attempt is already
+   * over and its key released when this fires, so a broken watcher (that
+   * second browser tab) can never turn the caller's settled result into a
+   * failure of its own.
+   */
+  private settle(key: CredentialKey, settlement: AuthorizationSettlement): void {
+    let invariantFailure: unknown
+    const args = ['authorization/settled', key, settlement]
+    for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) {
+      try {
+        const returned = listener(key, settlement)
+        if (returned != null && typeof (returned as PromiseLike<unknown>).then === 'function') {
+          void Promise.resolve(returned as PromiseLike<unknown>).then(undefined, (error: unknown) => {
+            this.warnSettledListenerFailure(key, error)
+          })
+        }
+      } catch (error) {
+        if ((error as { code?: unknown } | null)?.code === 'INVARIANT') {
+          invariantFailure ??= error
+          continue
+        }
+        this.warnSettledListenerFailure(key, error)
+      }
+    }
+    if (invariantFailure !== undefined) throw invariantFailure as Error
+  }
+  /* jscpd:ignore-end */
+
+  /** Contained-listener diagnostic shared by the sync and async failure paths. */
+  private warnSettledListenerFailure(key: CredentialKey, error: unknown): void {
+    this.ctx.logger.warn('authorization: an authorization/settled listener for "%s" failed', key)
+    this.ctx.logger.warn(error)
+  }
+
   /** Run the flow, then hold it to its half of the commit contract. */
   private async attempt(
     flow: AuthorizationFlow,
@@ -308,30 +371,63 @@ export class AuthorizationService extends Service {
       // withdrawn, so this signal cannot already be aborted here.
       signal.addEventListener('abort', () => { resolve('withdrawn') }, { once: true })
     })
-    const running = flow.run({
-      method,
-      signal,
-      notify: (notice) => { interaction.notify(notice) },
-      prompt: prompt => interaction.prompt(prompt),
+    // What the seam itself witnessed during the run, held as properties
+    // because closure writes do not narrow locals across awaits: the prompt
+    // wrapper sees a decline first-hand (a flow that rewraps the rejection on
+    // its way out cannot hide it), and confirming the commit means confirming
+    // it happened *now* — on a re-auth the record already exists, so presence
+    // alone would let a flow that wrote nothing report the stale credential
+    // as freshly authorized.
+    const observed = { declined: false, committed: false }
+    const unwatch = this.ctx.on('credentials/record-updated', (key: CredentialKey) => {
+      if (key === flow.key) observed.committed = true
     })
     try {
-      if (await Promise.race([running.then(() => 'ran' as const), withdrawn]) === 'withdrawn') {
-        // Nothing awaits the orphan any more, so its eventual failure has to be
-        // marked handled or it would take down the process.
-        void running.catch(() => { this.ctx.logger.debug('authorization: withdrawn flow failed after the fact') })
-        return { status: 'cancelled' }
+      const running = flow.run({
+        method,
+        signal,
+        notify: (notice) => {
+          try {
+            interaction.notify(notice)
+          } catch (error) {
+            // Fire-and-forget is held at the seam: a surface that cannot
+            // render a notice (a page whose connection just closed) loses the
+            // notice, never the attempt.
+            this.ctx.logger.warn('authorization: the interaction surface failed to render a notice')
+            this.ctx.logger.warn(error)
+          }
+        },
+        prompt: prompt => interaction.prompt(prompt).catch((error: unknown) => {
+          if (error instanceof AuthorizationDeclinedError) observed.declined = true
+          throw error
+        }),
+      })
+      try {
+        if (await Promise.race([running.then(() => 'ran' as const), withdrawn]) === 'withdrawn') {
+          // Nothing awaits the orphan any more, so its eventual failure has to be
+          // marked handled or it would take down the process.
+          void running.catch(() => { this.ctx.logger.debug('authorization: withdrawn flow failed after the fact') })
+          return { status: 'cancelled' }
+        }
+      } catch (error) {
+        // A withdrawn attempt and a declined prompt are outcomes, not
+        // failures: the human said no, or closed the page. Anything else is
+        // the flow failing and belongs to the caller, cause chain intact.
+        if (signal.aborted || observed.declined) return { status: 'cancelled' }
+        throw error
       }
-    } catch (error) {
-      // A withdrawn attempt is an outcome, not a failure: the human said no, or
-      // closed the page. Anything else is the flow failing and belongs to the
-      // caller, cause chain intact.
-      if (signal.aborted) return { status: 'cancelled' }
-      throw error
+    } finally {
+      unwatch()
+    }
+    if (!observed.committed) {
+      throw new AuthorizationError(
+        `authorization flow for "${flow.key}" resolved without committing a credential record in this attempt`,
+        'NOT_COMMITTED')
     }
     const stored = await this.ctx.credentials.describeRecord(flow.key)
     if (!stored.configured) {
       throw new AuthorizationError(
-        `authorization flow for "${flow.key}" resolved without committing a credential record`,
+        `authorization flow for "${flow.key}" deleted its credential record instead of committing one`,
         'NOT_COMMITTED')
     }
     return { status: 'authorized' }
diff --git a/packages/credentials/authorization/tests/authorization.spec.ts b/packages/credentials/authorization/tests/authorization.spec.ts
index 286c99898b..99efb9476f 100644
--- a/packages/credentials/authorization/tests/authorization.spec.ts
+++ b/packages/credentials/authorization/tests/authorization.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { credentialKey } from '@deepseek-ai/dsh-credentials'
 import AuthorizationService, {
+  AuthorizationDeclinedError,
   type AuthorizationFlow,
   type AuthorizationInteraction,
   type AuthorizationSession,
@@ -304,3 +305,161 @@ describe('AuthorizationService.begin', () => {
       .rejects.toThrow(/resolved without committing a credential record/)
   })
 })
+
+describe('commit confirmation', () => {
+  it('refuses a re-auth that left only the record of an earlier attempt', async () => {
+    const ctx = await harness()
+    await ctx.credentials.modifyRecord(KEY, () =>
+      Promise.resolve({ kind: 'grant', payload: { token: 'stale' } }))
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'Forgetful',
+      methods: [{ id: 'oauth', label: 'Sign in' }],
+      // A commit for another key is not this flow's commit either.
+      async run() {
+        await ctx.credentials.modifyRecord(OTHER, () =>
+          Promise.resolve({ kind: 'grant', payload: { token: 'other' } }))
+      },
+    })
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/without committing a credential record in this attempt/)
+    // Refused, not cleaned up: the stale record still belongs to its owner.
+    expect(await ctx.credentials.readRecord(KEY)).toEqual({ kind: 'grant', payload: { token: 'stale' } })
+  })
+
+  it('refuses a flow that deleted its record instead of committing one', async () => {
+    const ctx = await harness()
+    await ctx.credentials.modifyRecord(KEY, () =>
+      Promise.resolve({ kind: 'grant', payload: { token: 'stale' } }))
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'Destructive',
+      methods: [{ id: 'oauth', label: 'Sign in' }],
+      run: () => ctx.credentials.deleteRecord(KEY),
+    })
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/deleted its credential record/)
+  })
+})
+
+describe('declined prompts', () => {
+  it('reports an attempt whose prompt the human declined as cancelled, not failed', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, async (session) => {
+      await session.prompt({ kind: 'text', message: 'Paste the code' })
+    }))
+    const settled = vi.fn()
+    ctx.on('authorization/settled', settled)
+    const declining: AuthorizationInteraction = {
+      notify: () => undefined,
+      prompt: () => Promise.reject(new AuthorizationDeclinedError()),
+    }
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: declining }))
+      .resolves.toEqual({ status: 'cancelled' })
+
+    expect(settled).toHaveBeenCalledWith(KEY, 'cancelled')
+  })
+
+  it('reads a decline through a flow that rewraps the rejection on its way out', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, session =>
+      session.prompt({ kind: 'text', message: 'Paste the code' }).then(
+        () => undefined,
+        () => {
+          throw new Error('sign-in aborted')
+        })))
+    const declining: AuthorizationInteraction = {
+      notify: () => undefined,
+      prompt: () => Promise.reject(new AuthorizationDeclinedError()),
+    }
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: declining }))
+      .resolves.toEqual({ status: 'cancelled' })
+  })
+
+  it('keeps a prompt failure that is not a decline a flow failure', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, async (session) => {
+      await session.prompt({ kind: 'text', message: 'Paste the code' })
+    }))
+    const settled = vi.fn()
+    ctx.on('authorization/settled', settled)
+    const broken: AuthorizationInteraction = {
+      notify: () => undefined,
+      prompt: () => Promise.reject(new Error('the transport dropped')),
+    }
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: broken }))
+      .rejects.toThrow('the transport dropped')
+
+    expect(settled).toHaveBeenCalledWith(KEY, 'failed')
+  })
+})
+
+describe('notice containment', () => {
+  it('loses the notice, never the attempt, when the surface cannot render it', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx, KEY, (session) => {
+      session.notify({ message: 'Continue in your browser' })
+      return Promise.resolve()
+    }))
+    const broken: AuthorizationInteraction = {
+      notify: () => {
+        throw new Error('page connection closed')
+      },
+      prompt: () => Promise.resolve('unused'),
+    }
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: broken }))
+      .resolves.toEqual({ status: 'authorized' })
+  })
+})
+
+describe('the settled fan-out', () => {
+  it('keeps a throwing listener from changing a finished attempt, and later listeners still run', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+    ctx.on('authorization/settled', () => {
+      throw new Error('watcher boom')
+    })
+    const second = vi.fn()
+    ctx.on('authorization/settled', second)
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .resolves.toEqual({ status: 'authorized' })
+
+    expect(second).toHaveBeenCalledWith(KEY, 'authorized')
+  })
+
+  it('contains an async listener rejection', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+    // An unknown-returning function keeps the typed surface legal while the
+    // runtime value is still the rejected promise the containment must handle.
+    const boom = (): unknown => Promise.reject(new Error('async watcher boom'))
+    ctx.on('authorization/settled', boom)
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .resolves.toEqual({ status: 'authorized' })
+    await new Promise(resolve => setTimeout(resolve, 10))
+  })
+
+  it('rethrows an invariant-coded listener failure after the remaining listeners', async () => {
+    const ctx = await harness()
+    ctx.authorization.registerFlow(committingFlow(ctx))
+    ctx.on('authorization/settled', () => {
+      throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
+    })
+    const second = vi.fn()
+    ctx.on('authorization/settled', second)
+
+    await expect(ctx.authorization.begin({ key: KEY, interaction: surface() }))
+      .rejects.toThrow(/forged relation/)
+    // Harness-fatal by design — but the record itself committed first.
+    expect(second).toHaveBeenCalledWith(KEY, 'authorized')
+    expect(await ctx.credentials.readRecord(KEY)).toEqual({ kind: 'grant', payload: { token: 'granted' } })
+  })
+})
diff --git a/packages/credentials/authorization/tests/memory.ts b/packages/credentials/authorization/tests/memory.ts
index 94ebe091d2..1d9990af99 100644
--- a/packages/credentials/authorization/tests/memory.ts
+++ b/packages/credentials/authorization/tests/memory.ts
@@ -14,6 +14,9 @@ import type {
  * half is exercised — the seam's whole interest in this service is whether a
  * flow left a record behind — so the reference half answers "nothing stored".
  */
+// TODO: near-duplicate of the record half of
+// packages/credentials/credentials/tests/memory.ts; fold both into a shared
+// test-support double when a third suite needs one.
 export class MemoryCredentials extends CredentialProvider {
   private readonly records = new Map<CredentialKey, CredentialRecord>()
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index e394d8ade0..20a8313344 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -46,6 +46,7 @@ import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-home-pat
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
 import { CredentialProvider, credentialRef, parseCredentialKey } from '@deepseek-ai/dsh-credentials'
 import type {
+  ApiKeyRecord,
   CredentialInfo,
   CredentialKey,
   CredentialRecord,
@@ -100,12 +101,15 @@ const GROUP_OTHER_BITS = 0o077
  * mutation runs its caller's decision while holding the lock, and for the
  * operation this half exists to serve — an owner refreshing an expired token —
  * that decision includes a network round trip. The file-work default would
- * fail every other writer of this document for its duration. Like the retry
- * cadence in `dsh-atomic-write`, this is a robustness bound of the write
- * protocol rather than a deployment choice: it is sized by what a provider
- * request costs, which no deployment varies.
+ * fail every other writer of this document for its duration. A contender's
+ * wait is sized by the longest holder it can meet, and refs and records share
+ * one file and one lock, so every writer of this document — reference writes
+ * and record deletes included — waits this long, not only the mutation that
+ * holds it. Like the retry cadence in `dsh-atomic-write`, this is a
+ * robustness bound of the write protocol rather than a deployment choice: it
+ * is sized by what a provider request costs, which no deployment varies.
  */
-const RECORD_LOCK_WAIT_MS = 30_000
+const DOCUMENT_LOCK_WAIT_MS = 30_000
 
 /**
  * Reject a credentials document other OS users can read, before its contents
@@ -253,6 +257,26 @@ function parseRecords(section: unknown, filename: string): Map<string, Credentia
   return entries
 }
 
+/**
+ * Refuse an api-key record the read path could not admit, before it is
+ * rendered: an empty key, an env name outside the reference grammar, or an
+ * empty env value would persist a document `parseRecord` rejects at the next
+ * boot — a durable-boundary write is validated where it is written.
+ * @param key - the record's credential key, for the failure message.
+ * @param record - the api-key record a mutation returned.
+ */
+function assertStorableApiKey(key: CredentialKey, record: ApiKeyRecord): void {
+  if (record.key !== undefined && record.key.length === 0) {
+    throw new TypeError(`credentials-local: record "${key}" has an empty key; omit the field instead`)
+  }
+  for (const [name, value] of Object.entries(record.env ?? {})) {
+    credentialRef(name)
+    if (value.length === 0) {
+      throw new TypeError(`credentials-local: record "${key}" env "${name}" must be a non-empty string`)
+    }
+  }
+}
+
 /** One section of the document as a plain mapping; absent and null both mean empty. */
 function asSection(section: unknown, name: string, filename: string): Record<string, unknown> {
   if (section === undefined || section === null) return {}
@@ -626,10 +650,11 @@ export class LocalCredentialProvider extends CredentialProvider {
         const current = this.records.get(key)
         const next = await mutate(current)
         if (next === undefined) return current
-        // Admitted before it is rendered: the promise that a payload comes
-        // back exactly as written is only keepable for values this document
-        // can spell, and a value rejected here has not been stored.
+        // Admitted before it is rendered: what the read path would refuse is
+        // refused here first, so a caller can never persist a document the
+        // next boot rejects, and a value refused here has not been stored.
         if (next.kind === 'grant') assertJsonValue(`record "${key}" payload`, next.payload, new Set())
+        else assertStorableApiKey(key, next)
         const nextText = renderRecord(this.text, key, next)
         // 0600: a document holding secrets is never world-readable.
         await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
@@ -638,7 +663,7 @@ export class LocalCredentialProvider extends CredentialProvider {
         // After the commit, on the same terms as a reference write.
         this.notifyRecordUpdated(key)
         return next
-      }, { waitMs: RECORD_LOCK_WAIT_MS })
+      }, { waitMs: DOCUMENT_LOCK_WAIT_MS })
     })
   }
 
@@ -657,7 +682,7 @@ export class LocalCredentialProvider extends CredentialProvider {
         this.text = nextText
         this.records.delete(key)
         this.notifyRecordUpdated(key)
-      })
+      }, { waitMs: DOCUMENT_LOCK_WAIT_MS })
     })
   }
 
@@ -718,7 +743,7 @@ export class LocalCredentialProvider extends CredentialProvider {
         // After the commit: a broken observer must never make the durable
         // write look failed (an INVARIANT failure still rethrows).
         this.notifyUpdated(ref)
-      })
+      }, { waitMs: DOCUMENT_LOCK_WAIT_MS })
     })
   }
 
diff --git a/packages/credentials/credentials-local/tests/records.spec.ts b/packages/credentials/credentials-local/tests/records.spec.ts
index dfae94a093..08aec98ad6 100644
--- a/packages/credentials/credentials-local/tests/records.spec.ts
+++ b/packages/credentials/credentials-local/tests/records.spec.ts
@@ -316,6 +316,24 @@ describe('record mutation', () => {
     await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
   })
 
+  it('refuses an api-key record this document could not read back', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+
+    // The same admission rule as the read path: an api-key record parseRecord
+    // would reject at the next boot is refused before it is rendered, so the
+    // current process can never report a success the next one refuses to load.
+    await expect(put(ctx, CODEX, { kind: 'api-key', key: '' }))
+      .rejects.toThrow(/empty key/)
+    await expect(put(ctx, CODEX, { kind: 'api-key', env: { 'not a name': 'value' } }))
+      .rejects.toThrow(/must match/)
+    await expect(put(ctx, CODEX, { kind: 'api-key', env: { AWS_REGION: '' } }))
+      .rejects.toThrow(/non-empty string/)
+    expect(await ctx.credentials.readRecord(CODEX)).toBeUndefined()
+    await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('refuses record writes once disposed', async () => {
     const dir = await tempDir()
     const ctx = new Context()
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index 495fe22b33..60aab4c6e1 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -7,7 +7,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
 import { LocalCredentialProvider } from '../src/index.ts'
 
 /** Credential documents are seeded owner-only, exactly as the provider creates them. */
@@ -80,6 +80,37 @@ describe('read-modify-write', () => {
     await ctx.credentials.set(ALPHA, 'one')
     if (process.platform !== 'win32') expect((await stat(home)).mode & 0o777).toBe(0o700)
   })
+
+  it('holds every writer of the document to the record-mutation lock wait', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const holder = await boot({ path, watch: false })
+    const contender = await boot({ path, watch: false })
+    const doomed = credentialKey('llm-pi-ai', 'doomed')
+    const slowKey = credentialKey('llm-pi-ai', 'slow')
+    await holder.credentials.modifyRecord(doomed, () => Promise.resolve({ kind: 'api-key', key: 'x' }))
+    const entered = Promise.withResolvers<undefined>()
+    // The mutation holds the cross-process writer lock across a stand-in for
+    // an OAuth refresh round trip — longer than withFileLock's 2s default.
+    const slow = holder.credentials.modifyRecord(slowKey, async () => {
+      entered.resolve(undefined)
+      await new Promise(resolve => setTimeout(resolve, 2_400))
+      return { kind: 'api-key', key: 'slow' }
+    })
+    await entered.promise
+    // The other two writer paths — a reference write and a record delete —
+    // share that file and that lock, so they must wait the refresh out rather
+    // than fail at the file-work default.
+    await Promise.all([
+      contender.credentials.set(ALPHA, 'waited'),
+      contender.credentials.deleteRecord(doomed),
+    ])
+    await slow
+    const reread = await boot({ path, watch: false })
+    expect(await reread.credentials.resolve(ALPHA)).toEqual({ value: 'waited', source: 'file' })
+    expect(await reread.credentials.readRecord(doomed)).toBeUndefined()
+    expect(await reread.credentials.readRecord(slowKey)).toEqual({ kind: 'api-key', key: 'slow' })
+  })
 })
 
 describe('contained update fan-out', () => {
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 39ca7ff15c..8b474edf71 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/README.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 packages/credentials/credentials/README.md
-README.md: 0a8a10d48e9166ced2fd99613207060c06892a38
-README.zh.md: 9e621ccfa4f58b1cddfebe3bf0c9fe598d8dcf42
+README.md: d1b48aa724801a482517679790bba172fa60d013
+README.zh.md: a936b97353d7a66b7f0f7f9a760f4542bb2a9b30
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index 0a8a10d48e..d1b48aa724 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -16,7 +16,7 @@ A `CredentialRef` answers *what is behind this environment-variable name*, layer
 
 A `CredentialKey` answers *what credential does this plugin hold for this id*. Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and the empty-value rule does not apply: an `api-key` record carrying neither a key nor environment values states that its owner confirmed ambient authentication, which is configured.
 
-The key is `<scope>/<id>`, where `scope` is the **owning plugin's registered name**. The scope is the owner rather than the domain because a `grant` payload is written in its owner's format: two plugins serving the same provider name would otherwise read each other's payload, and a record left behind by an uninstalled plugin could not be told apart from a live one. The `/` also keeps the two grammars disjoint, so the key spaces can never collide.
+The key is `<scope>/<id>`, where `scope` is the **owning plugin's registered name**. The scope is the owner rather than the domain because a `grant` payload is written in its owner's format: two plugins serving the same provider name would otherwise read each other's payload, and a record left behind by an uninstalled plugin could not be told apart from a live one. The `/` also keeps the two grammars disjoint, so the key spaces can never collide. A consumer whose id arrives from somewhere else — a settings dict key, a library's own provider id — asks `isCredentialKeySegment` before building a key, because an id outside the grammar can never have stored a record and should read as "nothing stored" rather than throw on the address.
 
 ## Surface
 
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index 9e621ccfa4..a936b97353 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -16,7 +16,7 @@
 
 `CredentialKey` 回答的是*某个插件为某个 id 持有什么凭据*。这里没有任何东西可以分层——授权 grant 没有可供读取的环境——因此记录的存在与否就是全部事实，空值规则在此不适用：一条既无 key 也无环境值的 `api-key` 记录，陈述的是其拥有者确认该路由靠 ambient 认证，这属于已配置。
 
-键的形式是 `<scope>/<id>`，其中 `scope` 是**拥有该记录的插件的注册名**。scope 取拥有者而非领域，是因为 `grant` 的 payload 以其拥有者的格式写就：否则服务同一个提供方名称的两个插件会互相读到对方的 payload，而已卸载插件留下的记录也无法与仍在使用的区分开。`/` 同时让两种文法互斥，两个键空间因此不可能相撞。
+键的形式是 `<scope>/<id>`，其中 `scope` 是**拥有该记录的插件的注册名**。scope 取拥有者而非领域，是因为 `grant` 的 payload 以其拥有者的格式写就：否则服务同一个提供方名称的两个插件会互相读到对方的 payload，而已卸载插件留下的记录也无法与仍在使用的区分开。`/` 同时让两种文法互斥，两个键空间因此不可能相撞。id 来自别处的消费方——settings dict 键、某个库自己的 provider id——应先问 `isCredentialKeySegment` 再构造键：文法之外的 id 不可能存过记录，应读作「没有存储任何东西」，而不是在寻址上抛错。
 
 ## 接口
 
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index 3934f51754..087672f2fd 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -43,6 +43,19 @@ export function isCredentialRefName(value: string): boolean {
   return REF_PATTERN.test(value)
 }
 
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export function isCredentialKeySegment(value: string): boolean {
+  return KEY_SEGMENT_PATTERN.test(value)
+}
+
 /**
  * Brand a scope and an id as a {@link CredentialKey}.
  * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
diff --git a/packages/credentials/credentials/tests/credentials.spec.ts b/packages/credentials/credentials/tests/credentials.spec.ts
index a4676a2ea8..2941494f48 100644
--- a/packages/credentials/credentials/tests/credentials.spec.ts
+++ b/packages/credentials/credentials/tests/credentials.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import { credentialRef } from '../src/index.ts'
+import { credentialRef, isCredentialKeySegment } from '../src/index.ts'
 import type { CredentialRef } from '../src/index.ts'
 import { MemoryCredentials } from './memory.ts'
 
@@ -26,6 +26,19 @@ describe('credentialRef', () => {
   })
 })
 
+describe('isCredentialKeySegment', () => {
+  it('answers whether credentialKey would accept the segment', () => {
+    for (const valid of ['llm-pi-ai', 'openai-codex', 'a', 'z9']) {
+      expect(isCredentialKeySegment(valid)).toBe(true)
+    }
+    // The shapes an arbitrary settings dict key can take that a record id
+    // cannot: a consumer asks here instead of learning it from a throw.
+    for (const invalid of ['', 'My_Proxy', 'z.ai', 'UPPER', '9leading', 'a/b']) {
+      expect(isCredentialKeySegment(invalid)).toBe(false)
+    }
+  })
+})
+
 describe('the credentials seam through the memory provider', () => {
   it('mounts as ctx.credentials and resolves a seeded reference with its source', async () => {
     const ctx = await boot({ DEEPSEEK_API_KEY: 'sk-seeded' })
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index 78b9368986..e520a9217e 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -490,8 +490,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>',
         description: 'Run one attempt to authorize a key, and report how it ended.\n\nOne attempt per key at a time. A second caller is refused rather than joined: the two would be prompting different humans through the same flow, and the second would answer questions the first was asked.',
         parameters: [{ name: 'request', description: 'the key, the method, the surface, and the cancel signal.' }],
-        returns: '`authorized` once the flow\'s record is committed and observed, or `cancelled` when the human or the caller withdrew.',
-        throws: ['{AuthorizationError} code `NO_FLOW` when nothing claims the key, `UNKNOWN_METHOD` when the named method is not one the flow offers, `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or `NOT_COMMITTED` when the flow resolved without leaving a record behind.'],
+        returns: '`authorized` once the flow\'s record is committed during this attempt and observed, or `cancelled` when the human declined or the caller withdrew.',
+        throws: ['{AuthorizationError} code `NO_FLOW` when nothing claims the key, `UNKNOWN_METHOD` when the named method is not one the flow offers, `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or `NOT_COMMITTED` when the flow resolved without committing a record during the attempt.'],
       },
     ],
   },
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 19db6eb0fb..611cc52db3 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/README.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 packages/llm/llm-pi-ai/README.md
-README.md: 45b4815cb35e8709a6dc6cf4c50b778d2c2113f9
-README.zh.md: a1e952b70d9361e945b37ed146035fa274185003
+README.md: 29b12996208c44328a4bc1fdd237018564f1014d
+README.zh.md: 618e85bb54eec8739bbece1099404801e48522ec
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 45b4815cb3..29b1299620 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -140,7 +140,7 @@ Most listings disclose an id and nothing else; `context_window`/`context_length`
 
 Each resolution produces one **immutable** snapshot — the profiles plus a `createModels()` collection holding the `Provider` each route built — and every operation captures a whole snapshot before its first `await`. A configuration change builds a *new* collection rather than mutating the one in use: `Models.streamSimple()` resolves its provider lazily, when the stream is first consumed, which is after the credential await, so a mutated collection would let a request that started under one configuration finish under another or fail on a provider that no longer exists. This is what makes the seam's per-step call freeze (`llm.prepareCall()`) hold end to end — switching models mid-reply takes effect on the next step, never inside the one in flight. Requests reach their provider through `Models.streamSimple()`. A catalog route that keeps its catalog protocol **reuses** the installed provider with its model list replaced, because that provider owns API implementations this package cannot reconstruct — Bedrock loads its Smithy module through a separate entry point — so rebuilding it from parts would silently narrow which providers work. Every other route is built by `createProvider()` over the protocol table behind `supportedProtocols()`, whose entries are the same factories pi-ai's own provider factories use.
 
-Credentials never enter that collection. The harness resolves a route's key through its own seam before the request reaches pi-ai and passes it as the request's `apiKey` option, which pi-ai treats as the highest-priority auth override; `Models` therefore holds no credential store, and the harness keeps its fail-loud reference semantics. A route naming no credential resolves as configured-but-keyless and leaves the requirement to the protocol, which is where it actually lives.
+A route's `apiKeyEnv` key still resolves through the harness seam before the request reaches pi-ai and rides as the request's `apiKey` option, which pi-ai treats as the highest-priority auth override — the fail-loud reference semantics stay the harness's. Beneath that override the collection carries this plugin's credential store and ambient auth context: a stored sign-in (an OAuth grant, or a key typed into pi-ai's own login prompt) authenticates its route through them and refreshes itself under the store's cross-process lock. The store addresses records as `llm-pi-ai/<provider id>`, and a hand-declared route key outside that record grammar (uppercase, dots, underscores) reads as holding nothing stored rather than as an addressing error; such a route cannot be signed into — a record write for it refuses with `LlmError('UNSTORABLE_PROVIDER_ID')` — and authenticates through `apiKeyEnv` or ambient provider settings. A route naming no credential at all resolves as configured-but-keyless and leaves the requirement to the protocol, which is where it actually lives.
 
 The selected model descriptor supplies the protocol implementation. This includes native API differences such as OpenAI models whose descriptor uses the Responses API rather than Chat Completions; the harness adapter does not hardcode endpoint selection by model name.
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index a1e952b70d..618e85bb54 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -141,7 +141,7 @@ pi-ai 依据提供方 id 与 baseURL 决定每个请求的形状：系统提示
 
 每次解析产出一份**不可变**快照——profiles 加上一个持有各路由所建 `Provider` 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份快照。配置变化会构造**新**集合，而不是改动正在被使用的那个：`Models.streamSimple()` 是惰性的，它在流首次被消费时才解析 provider，而那已在 credential await 之后，因此改动共享集合会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider。这正是 seam 的每步调用冻结（`llm.prepareCall()`）能贯通到底的原因——回复途中切换模型会在下一步生效，绝不会影响在途的那一步。请求经 `Models.streamSimple()` 抵达提供方。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换其模型列表，因为该提供方持有本包无法重建的 API 实现——Bedrock 经由独立入口加载其 Smithy 模块——从零件重建会静默收窄可用提供方的范围。其余路由都由 `createProvider()` 基于 `supportedProtocols()` 背后的协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的同一批 factory。
 
-凭据绝不进入该集合。harness 在请求抵达 pi-ai 之前经自身 seam 解析路由密钥，并作为请求的 `apiKey` 选项传入，而 pi-ai 将其视为优先级最高的 auth 覆盖；因此 `Models` 不持有任何凭据存储，harness 也保住了自己明确失败的引用语义。没有点名任何凭据的路由会解析为「已配置但无密钥」，把该要求留给协议——那才是它真正所在的位置。
+路由的 `apiKeyEnv` 密钥仍在请求抵达 pi-ai 之前经 harness 自身 seam 解析，并作为请求的 `apiKey` 选项传入——pi-ai 将其视为优先级最高的 auth 覆盖，harness 因此保住自己明确失败的引用语义。在该覆盖之下，集合携带本插件的凭据存储与 ambient auth context：已存储的登录（OAuth grant，或在 pi-ai 自己的登录提示里键入的密钥）经由它们为路由完成认证，并在存储的跨进程锁下自行刷新。存储以 `llm-pi-ai/<provider id>` 为记录地址；手写路由键若落在记录文法之外（大写、点、下划线），读取时视为「没有存储任何东西」而不是寻址错误——这样的路由无法登录（对它的记录写入会以 `LlmError('UNSTORABLE_PROVIDER_ID')` 拒绝），只能经 `apiKeyEnv` 或提供方 ambient 设置认证。完全没有点名任何凭据的路由会解析为「已配置但无密钥」，把该要求留给协议——那才是它真正所在的位置。
 
 所选模型 descriptor 提供协议实现。这包括原生 API 差异，例如 descriptor 使用 Responses API 而非 Chat Completions 的 OpenAI 模型；harness 适配器不会按模型名称硬编码端点选择。
 
diff --git a/packages/llm/llm-pi-ai/src/auth.ts b/packages/llm/llm-pi-ai/src/auth.ts
index 8b718cdd20..f729a77f85 100644
--- a/packages/llm/llm-pi-ai/src/auth.ts
+++ b/packages/llm/llm-pi-ai/src/auth.ts
@@ -14,7 +14,7 @@ import { resolve as resolvePath } from 'node:path'
 import type { AuthContext, Credential, CredentialInfo, CredentialStore } from '@earendil-works/pi-ai'
 import type { Context } from '@deepseek-ai/cordis'
 import {
-  credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialRefName,
+  credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName,
 } from '@deepseek-ai/dsh-credentials'
 import type { CredentialKey, CredentialProvider, CredentialRecord } from '@deepseek-ai/dsh-credentials'
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
@@ -104,6 +104,13 @@ function writableStore(ctx: Context): CredentialProvider {
  * to cover a network round trip rather than a file rename — which is why the
  * record write path takes a wait limit of its own rather than the short one a
  * local write would need.
+ *
+ * pi-ai asks this store about every provider in the collection, hand-declared
+ * routes included, and a route key is an arbitrary settings dict key while a
+ * record id is not. An id outside the record grammar can never have stored a
+ * record, so reads answer "nothing stored" and a delete has nothing to remove;
+ * only `modify` refuses it, because a write that cannot land must not report
+ * that it did.
  * @param ctx - the plugin context carrying the optional `ctx.credentials`.
  * @returns the store to hand `createModels()`.
  */
@@ -112,6 +119,7 @@ export function credentialStoreFrom(ctx: Context): CredentialStore {
     async read(providerId) {
       const credentials = ctx.get('credentials')
       if (credentials === undefined) return undefined
+      if (!isCredentialKeySegment(providerId)) return undefined
       return toPiCredential(await credentials.readRecord(recordKeyFor(providerId)))
     },
     async list(): Promise<readonly CredentialInfo[]> {
@@ -129,6 +137,14 @@ export function credentialStoreFrom(ctx: Context): CredentialStore {
       return mine
     },
     async modify(providerId, mutate) {
+      if (!isCredentialKeySegment(providerId)) {
+        throw new LlmError(
+          `llm-pi-ai: provider id "${providerId}" cannot address a stored credential record (a record id is a`
+          + ' lowercase hyphenated identifier); authenticate this route through apiKeyEnv instead of a stored'
+          + ' credential',
+          'UNSTORABLE_PROVIDER_ID',
+        )
+      }
       const stored = await writableStore(ctx).modifyRecord(recordKeyFor(providerId), async (current) => {
         const next = await mutate(toPiCredential(current))
         return next === undefined ? undefined : toRecord(next)
@@ -139,6 +155,7 @@ export function credentialStoreFrom(ctx: Context): CredentialStore {
     // store contract is promise-returning, and a synchronous throw would
     // escape the `ModelsError` wrapper every other storage failure gets.
     async delete(providerId) {
+      if (!isCredentialKeySegment(providerId)) return
       await writableStore(ctx).deleteRecord(recordKeyFor(providerId))
     },
   }
diff --git a/packages/llm/llm-pi-ai/src/login.ts b/packages/llm/llm-pi-ai/src/login.ts
index c71d68e3b5..578489afb4 100644
--- a/packages/llm/llm-pi-ai/src/login.ts
+++ b/packages/llm/llm-pi-ai/src/login.ts
@@ -11,6 +11,7 @@ import { createModels } from '@earendil-works/pi-ai'
 import type { AuthEvent, AuthPrompt, AuthType, Provider } from '@earendil-works/pi-ai'
 import type { Context } from '@deepseek-ai/cordis'
 import type { AuthorizationMethod, AuthorizationPrompt, AuthorizationSession } from '@deepseek-ai/dsh-authorization'
+import { isCredentialKeySegment } from '@deepseek-ai/dsh-credentials'
 import { catalogProvider, catalogProviderIds } from './catalog.ts'
 import { recordKeyFor } from './auth.ts'
 import type { PiAiAuthInjection } from './adapter.ts'
@@ -124,6 +125,16 @@ export function registerPiAiFlows(ctx: Context, auth: PiAiAuthInjection): void {
        installed provider ships a login, so nothing is skipped today; the guard
        is what keeps that from becoming a crash if either stops being true. */
     if (provider === undefined || first === undefined) continue
+    /* v8 ignore next 7 -- every installed catalog id today is a lowercase
+       hyphenated identifier; the guard keeps a future upstream id outside the
+       record grammar (dotted or uppercase, as vendor ids elsewhere already
+       are) from throwing in `recordKeyFor` and failing the whole mount. */
+    if (!isCredentialKeySegment(providerId)) {
+      ctx.logger.warn(
+        'llm-pi-ai: catalog provider "%s" cannot address a credential record; its sign-in is not offered',
+        providerId)
+      continue
+    }
     ctx.authorization.registerFlow({
       key: recordKeyFor(providerId),
       label: provider.name,
diff --git a/packages/llm/llm-pi-ai/tests/auth.spec.ts b/packages/llm/llm-pi-ai/tests/auth.spec.ts
index 55a20fbb66..fa6c635c86 100644
--- a/packages/llm/llm-pi-ai/tests/auth.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/auth.spec.ts
@@ -116,6 +116,20 @@ describe('pi-ai credential store over harness records', () => {
       .rejects.toThrow(/mounts no credentials service/)
     await expect(store.delete('openai-codex')).rejects.toThrow(/mounts no credentials service/)
   })
+
+  it('treats a provider id outside the record grammar as holding nothing', async () => {
+    const store = credentialStoreFrom(await stored())
+
+    // A hand-declared route key is an arbitrary settings dict key, and pi-ai
+    // reads it during auth resolution: the answer is "not signed in", never a
+    // thrown address error…
+    await expect(store.read('My_Proxy')).resolves.toBeUndefined()
+    // …nothing can ever be stored under it, so a logout has nothing to remove…
+    await expect(store.delete('My_Proxy')).resolves.toBeUndefined()
+    // …while a write that cannot land must refuse rather than report success.
+    await expect(store.modify('My_Proxy', () => Promise.resolve({ type: 'api_key', key: 'k' })))
+      .rejects.toThrow(/cannot address a stored credential record/)
+  })
 })
 
 describe('pi-ai ambient auth context', () => {

From 6428b844ef19a04bba4293e20ea905adebaef691 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 17 Aug 2026 14:48:17 +0800
Subject: [PATCH 25/34] fix(ci): catch the branch up with the static and smoke
 gates

- dsh-authorization's manifest becomes a release member on current
  master's terms: version matches the root 0.1.0-rc.6 and
  publishConfig.access is public, which the constraints gate and the
  tarball pack's version verify both enforce after the master merge.
- Regenerate docs/module-graph (zh mirror included) for the
  authorization package and the llm-pi-ai -> authorization edge; the
  graph gate lives outside doc-sync and was never regenerated when the
  package was added.
- The built-bin smoke seeds the versioned credentials document; this
  branch's provider refuses the pre-release flat layout by design, and
  the master-side test still wrote the old shape.
---
 apps/cli/tests/built-bin.e2e.ts               |   2 +-
 docs/module-graph.i18n.yaml                   |   4 +-
 docs/module-graph.md                          | 110 ++++++------------
 docs/module-graph.zh.md                       | 110 ++++++------------
 .../credentials/authorization/package.json    |   4 +-
 5 files changed, 79 insertions(+), 151 deletions(-)

diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index c8e551306f..75ab640fcc 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -426,7 +426,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-home-environment-'))
     const project = mkdtempSync(join(tmpdir(), 'dsh-home-project-'))
-    writeFileSync(join(home, '.credentials.yaml'), `DEEPSEEK_API_KEY: ${apiKey}\n`, { mode: 0o600 })
+    writeFileSync(join(home, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${apiKey}\n`, { mode: 0o600 })
     createEnvironmentProbeProfile(home, project)
     try {
       const result = await runBuiltBin(
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index ce5dee0e98..c76d6e283e 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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 docs/module-graph.md
-module-graph.md: 22532a825ccb65affceca16a23b73169828bf3f1
-module-graph.zh.md: 148e23eeb051c700715f242f37d98a21c9358754
+module-graph.md: 32459504c815eede558d5f8f6b3aa3c041429341
+module-graph.zh.md: c0aeb8e0c277a76dbb0fc1d361f2d48fc8d46b64
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 22532a825c..32459504c8 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -125,7 +125,6 @@ flowchart TD
     pkg_client_runtime["client-runtime"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_attachment["client-ui-attachment"]
-    pkg_client_ui_brand_official["client-ui-brand-official"]
     pkg_client_ui_commands["client-ui-commands"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_deliverables["client-ui-deliverables"]
@@ -140,7 +139,6 @@ flowchart TD
     pkg_client_ui_permission_presets["client-ui-permission-presets"]
     pkg_client_ui_plan["client-ui-plan"]
     pkg_client_ui_primitives["client-ui-primitives"]
-    pkg_client_ui_reference["client-ui-reference"]
     pkg_client_ui_renderer["client-ui-renderer"]
     pkg_client_ui_settings["client-ui-settings"]
     pkg_client_ui_settings_general["client-ui-settings-general"]
@@ -172,13 +170,12 @@ flowchart TD
   end
   subgraph group_context["packages/context"]
     pkg_agent_instructions["agent-instructions"]
-    pkg_file_reference["file-reference"]
-    pkg_file_reference_local["file-reference-local"]
     pkg_session_reference["session-reference"]
     pkg_time_context["time-context"]
     pkg_tmux_context["tmux-context"]
   end
   subgraph group_credentials["packages/credentials"]
+    pkg_authorization["authorization"]
     pkg_credentials["credentials"]
     pkg_credentials_local["credentials-local"]
   end
@@ -193,8 +190,8 @@ flowchart TD
     pkg_sdk_jsonrpc_demo["sdk-jsonrpc-demo"]
   end
   subgraph group_experimental["packages/experimental"]
-    pkg_experimental_agent_team["experimental-agent-team"]
-    pkg_experimental_tool_agent_team["experimental-tool-agent-team"]
+    pkg_team["team"]
+    pkg_tool_team["tool-team"]
   end
   subgraph group_extensions["packages/extensions"]
     pkg_client_ui_cordis["client-ui-cordis"]
@@ -293,7 +290,6 @@ flowchart TD
     pkg_tool_bash["tool-bash"]
     pkg_tool_bash_persistent["tool-bash-persistent"]
     pkg_tool_pwsh["tool-pwsh"]
-    pkg_tool_pwsh_persistent["tool-pwsh-persistent"]
   end
   subgraph group_storage["packages/storage"]
     pkg_storage["storage"]
@@ -412,20 +408,12 @@ flowchart TD
   pkg_settings_file --> pkg_invariants
   pkg_settings_file --> pkg_settings
   pkg_llm_deepseek --> pkg_anonymous_user_id
-  pkg_llm_deepseek --> pkg_attachment
   pkg_llm_deepseek --> pkg_credentials
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_launch_environment
   pkg_llm_deepseek --> pkg_llm
   pkg_llm_deepseek --> pkg_settings
   pkg_llm_deepseek --> pkg_timeout
-  pkg_llm_pi_ai --> pkg_attachment
-  pkg_llm_pi_ai --> pkg_credentials
-  pkg_llm_pi_ai --> pkg_invariants
-  pkg_llm_pi_ai --> pkg_launch_environment
-  pkg_llm_pi_ai --> pkg_llm
-  pkg_llm_pi_ai --> pkg_settings
-  pkg_llm_pi_ai --> pkg_timeout
   pkg_session --> pkg_brand
   pkg_session --> pkg_invariants
   pkg_session --> pkg_llm
@@ -439,9 +427,20 @@ flowchart TD
   pkg_skill --> pkg_scope
   pkg_web --> pkg_invariants
   pkg_web --> pkg_llm
+  pkg_authorization --> pkg_credentials
+  pkg_authorization --> pkg_invariants
+  pkg_authorization --> pkg_llm
   pkg_lsp --> pkg_brand
   pkg_lsp --> pkg_invariants
   pkg_lsp --> pkg_llm
+  pkg_llm_pi_ai --> pkg_attachment
+  pkg_llm_pi_ai --> pkg_authorization
+  pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_invariants
+  pkg_llm_pi_ai --> pkg_launch_environment
+  pkg_llm_pi_ai --> pkg_llm
+  pkg_llm_pi_ai --> pkg_settings
+  pkg_llm_pi_ai --> pkg_timeout
   pkg_agent --> pkg_invariants
   pkg_agent --> pkg_llm
   pkg_agent --> pkg_scope
@@ -515,9 +514,6 @@ flowchart TD
   pkg_web_search_deepseek --> pkg_web
   pkg_spill_local --> pkg_invariants
   pkg_spill_local --> pkg_spill
-  pkg_file_reference --> pkg_agent
-  pkg_file_reference --> pkg_invariants
-  pkg_file_reference --> pkg_typert_protocol
   pkg_time_context --> pkg_agent
   pkg_time_context --> pkg_invariants
   pkg_time_context --> pkg_session
@@ -571,7 +567,6 @@ flowchart TD
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
   pkg_session_persistence_sqlite --> pkg_invariants
-  pkg_session_persistence_sqlite --> pkg_llm
   pkg_session_persistence_sqlite --> pkg_session
   pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
@@ -843,11 +838,6 @@ flowchart TD
   pkg_agent_instructions --> pkg_llm
   pkg_agent_instructions --> pkg_session
   pkg_agent_instructions --> pkg_tools
-  pkg_file_reference_local --> pkg_agent
-  pkg_file_reference_local --> pkg_file_reference
-  pkg_file_reference_local --> pkg_invariants
-  pkg_file_reference_local --> pkg_system_prompt
-  pkg_file_reference_local --> pkg_tools
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compaction
   pkg_session_reference --> pkg_invariants
@@ -855,7 +845,6 @@ flowchart TD
   pkg_session_reference --> pkg_output_retention
   pkg_session_reference --> pkg_session
   pkg_session_reference --> pkg_session_query
-  pkg_session_reference --> pkg_typert_protocol
   pkg_cordis_host_runner --> pkg_agent
   pkg_cordis_host_runner --> pkg_brand
   pkg_cordis_host_runner --> pkg_invariants
@@ -943,11 +932,6 @@ flowchart TD
   pkg_tool_bash_persistent --> pkg_terminal
   pkg_tool_bash_persistent --> pkg_timeout
   pkg_tool_bash_persistent --> pkg_tools
-  pkg_tool_pwsh_persistent --> pkg_agent
-  pkg_tool_pwsh_persistent --> pkg_invariants
-  pkg_tool_pwsh_persistent --> pkg_terminal
-  pkg_tool_pwsh_persistent --> pkg_timeout
-  pkg_tool_pwsh_persistent --> pkg_tools
   pkg_tool_terminal --> pkg_agent
   pkg_tool_terminal --> pkg_invariants
   pkg_tool_terminal --> pkg_jobs
@@ -1032,13 +1016,13 @@ flowchart TD
   pkg_compaction_tool_result_pruner --> pkg_llm
   pkg_compaction_tool_result_pruner --> pkg_session
   pkg_compaction_tool_result_pruner --> pkg_token_meter
-  pkg_experimental_agent_team --> pkg_agent
-  pkg_experimental_agent_team --> pkg_brand
-  pkg_experimental_agent_team --> pkg_invariants
-  pkg_experimental_agent_team --> pkg_llm
-  pkg_experimental_agent_team --> pkg_session
-  pkg_experimental_agent_team --> pkg_session_persistence
-  pkg_experimental_agent_team --> pkg_subagent
+  pkg_team --> pkg_agent
+  pkg_team --> pkg_brand
+  pkg_team --> pkg_invariants
+  pkg_team --> pkg_llm
+  pkg_team --> pkg_session
+  pkg_team --> pkg_session_persistence
+  pkg_team --> pkg_subagent
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
   pkg_tool_cordis --> pkg_invariants
@@ -1050,7 +1034,6 @@ flowchart TD
   pkg_host_apiproxy --> pkg_agent_presets
   pkg_host_apiproxy --> pkg_cordis_host_runner
   pkg_host_apiproxy --> pkg_invariants
-  pkg_host_apiproxy --> pkg_permission_presets
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1138,12 +1121,12 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_jobs
   pkg_agent_spine_demo --> pkg_tool_skill
   pkg_agent_spine_demo --> pkg_tools
-  pkg_experimental_tool_agent_team --> pkg_agent
-  pkg_experimental_tool_agent_team --> pkg_experimental_agent_team
-  pkg_experimental_tool_agent_team --> pkg_invariants
-  pkg_experimental_tool_agent_team --> pkg_session
-  pkg_experimental_tool_agent_team --> pkg_system_prompt
-  pkg_experimental_tool_agent_team --> pkg_tools
+  pkg_tool_team --> pkg_agent
+  pkg_tool_team --> pkg_invariants
+  pkg_tool_team --> pkg_session
+  pkg_tool_team --> pkg_system_prompt
+  pkg_tool_team --> pkg_team
+  pkg_tool_team --> pkg_tools
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1182,7 +1165,6 @@ flowchart TD
   pkg_api_remotes --> pkg_commands
   pkg_api_remotes --> pkg_cordis_host_runner
   pkg_api_remotes --> pkg_credentials
-  pkg_api_remotes --> pkg_file_reference
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_host_plugin_inventory
   pkg_api_remotes --> pkg_invariants
@@ -1190,7 +1172,6 @@ flowchart TD
   pkg_api_remotes --> pkg_message_feedback
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
-  pkg_api_remotes --> pkg_session_reference
   pkg_api_remotes --> pkg_settings
   pkg_api_remotes --> pkg_typert_registry
   pkg_client_runtime --> pkg_agent
@@ -1228,7 +1209,6 @@ flowchart TD
   pkg_client_test_runtime --> pkg_invariants
   pkg_client_ui_input_trigger --> pkg_client_locale
   pkg_client_ui_input_trigger --> pkg_client_runtime
-  pkg_client_ui_input_trigger --> pkg_file_reference
   pkg_client_ui_input_trigger --> pkg_invariants
   pkg_client_ui_settings_models --> pkg_api_remotes
   pkg_client_ui_settings_models --> pkg_client_connection
@@ -1258,14 +1238,6 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
-  pkg_client_ui_reference --> pkg_api_remotes
-  pkg_client_ui_reference --> pkg_client_locale
-  pkg_client_ui_reference --> pkg_client_runtime
-  pkg_client_ui_reference --> pkg_client_ui_input_trigger
-  pkg_client_ui_reference --> pkg_file_reference
-  pkg_client_ui_reference --> pkg_invariants
-  pkg_client_ui_reference --> pkg_session_reference
-  pkg_client_ui_reference --> pkg_typert_protocol
   pkg_cordis_client_runner --> pkg_api_remotes
   pkg_cordis_client_runner --> pkg_client_connection
   pkg_cordis_client_runner --> pkg_client_modules
@@ -1309,10 +1281,6 @@ flowchart TD
   pkg_client_ui_attachment --> pkg_client_runtime
   pkg_client_ui_attachment --> pkg_client_ui_conversation
   pkg_client_ui_attachment --> pkg_invariants
-  pkg_client_ui_brand_official --> pkg_client_runtime
-  pkg_client_ui_brand_official --> pkg_client_ui_conversation
-  pkg_client_ui_brand_official --> pkg_client_ui_sidebar
-  pkg_client_ui_brand_official --> pkg_invariants
   pkg_client_ui_commands --> pkg_api_remotes
   pkg_client_ui_commands --> pkg_client_locale
   pkg_client_ui_commands --> pkg_client_runtime
@@ -1502,13 +1470,14 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) |
 | [`settings-file`](../packages/settings/settings-file) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
-| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
+| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`attachment`](../packages/attachment/attachment), [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) |
 | [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
@@ -1528,7 +1497,6 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) |
-| [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
@@ -1539,7 +1507,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
 | [`session-stats`](../packages/session/session-stats) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
@@ -1589,8 +1557,7 @@ flowchart TD
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`typert-protocol`](../packages/typert/protocol) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
 | [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`tools`](../packages/core/tools) |
 | [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -1607,7 +1574,6 @@ flowchart TD
 | [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`invariants`](../packages/runtime-diagnostics/invariants), [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
 | [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
@@ -1622,9 +1588,9 @@ flowchart TD
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
+| [`team`](../packages/experimental/team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
 | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1635,31 +1601,29 @@ flowchart TD
 | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
-| [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-team`](../packages/experimental/tool-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`team`](../packages/experimental/team), [`tools`](../packages/core/tools) |
 | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
 | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-title`](../packages/session/session-title), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`client-runtime`](../packages/client/runtime), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-slots`](../packages/client/ui-slots), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-settings`](../packages/client/ui-settings), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-layout`](../packages/client/ui-layout), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 148e23eeb0..c0aeb8e0c2 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -127,7 +127,6 @@ flowchart TD
     pkg_client_runtime["client-runtime"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_attachment["client-ui-attachment"]
-    pkg_client_ui_brand_official["client-ui-brand-official"]
     pkg_client_ui_commands["client-ui-commands"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_deliverables["client-ui-deliverables"]
@@ -142,7 +141,6 @@ flowchart TD
     pkg_client_ui_permission_presets["client-ui-permission-presets"]
     pkg_client_ui_plan["client-ui-plan"]
     pkg_client_ui_primitives["client-ui-primitives"]
-    pkg_client_ui_reference["client-ui-reference"]
     pkg_client_ui_renderer["client-ui-renderer"]
     pkg_client_ui_settings["client-ui-settings"]
     pkg_client_ui_settings_general["client-ui-settings-general"]
@@ -174,13 +172,12 @@ flowchart TD
   end
   subgraph group_context["packages/context"]
     pkg_agent_instructions["agent-instructions"]
-    pkg_file_reference["file-reference"]
-    pkg_file_reference_local["file-reference-local"]
     pkg_session_reference["session-reference"]
     pkg_time_context["time-context"]
     pkg_tmux_context["tmux-context"]
   end
   subgraph group_credentials["packages/credentials"]
+    pkg_authorization["authorization"]
     pkg_credentials["credentials"]
     pkg_credentials_local["credentials-local"]
   end
@@ -195,8 +192,8 @@ flowchart TD
     pkg_sdk_jsonrpc_demo["sdk-jsonrpc-demo"]
   end
   subgraph group_experimental["packages/experimental"]
-    pkg_experimental_agent_team["experimental-agent-team"]
-    pkg_experimental_tool_agent_team["experimental-tool-agent-team"]
+    pkg_team["team"]
+    pkg_tool_team["tool-team"]
   end
   subgraph group_extensions["packages/extensions"]
     pkg_client_ui_cordis["client-ui-cordis"]
@@ -295,7 +292,6 @@ flowchart TD
     pkg_tool_bash["tool-bash"]
     pkg_tool_bash_persistent["tool-bash-persistent"]
     pkg_tool_pwsh["tool-pwsh"]
-    pkg_tool_pwsh_persistent["tool-pwsh-persistent"]
   end
   subgraph group_storage["packages/storage"]
     pkg_storage["storage"]
@@ -414,20 +410,12 @@ flowchart TD
   pkg_settings_file --> pkg_invariants
   pkg_settings_file --> pkg_settings
   pkg_llm_deepseek --> pkg_anonymous_user_id
-  pkg_llm_deepseek --> pkg_attachment
   pkg_llm_deepseek --> pkg_credentials
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_launch_environment
   pkg_llm_deepseek --> pkg_llm
   pkg_llm_deepseek --> pkg_settings
   pkg_llm_deepseek --> pkg_timeout
-  pkg_llm_pi_ai --> pkg_attachment
-  pkg_llm_pi_ai --> pkg_credentials
-  pkg_llm_pi_ai --> pkg_invariants
-  pkg_llm_pi_ai --> pkg_launch_environment
-  pkg_llm_pi_ai --> pkg_llm
-  pkg_llm_pi_ai --> pkg_settings
-  pkg_llm_pi_ai --> pkg_timeout
   pkg_session --> pkg_brand
   pkg_session --> pkg_invariants
   pkg_session --> pkg_llm
@@ -441,9 +429,20 @@ flowchart TD
   pkg_skill --> pkg_scope
   pkg_web --> pkg_invariants
   pkg_web --> pkg_llm
+  pkg_authorization --> pkg_credentials
+  pkg_authorization --> pkg_invariants
+  pkg_authorization --> pkg_llm
   pkg_lsp --> pkg_brand
   pkg_lsp --> pkg_invariants
   pkg_lsp --> pkg_llm
+  pkg_llm_pi_ai --> pkg_attachment
+  pkg_llm_pi_ai --> pkg_authorization
+  pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_invariants
+  pkg_llm_pi_ai --> pkg_launch_environment
+  pkg_llm_pi_ai --> pkg_llm
+  pkg_llm_pi_ai --> pkg_settings
+  pkg_llm_pi_ai --> pkg_timeout
   pkg_agent --> pkg_invariants
   pkg_agent --> pkg_llm
   pkg_agent --> pkg_scope
@@ -517,9 +516,6 @@ flowchart TD
   pkg_web_search_deepseek --> pkg_web
   pkg_spill_local --> pkg_invariants
   pkg_spill_local --> pkg_spill
-  pkg_file_reference --> pkg_agent
-  pkg_file_reference --> pkg_invariants
-  pkg_file_reference --> pkg_typert_protocol
   pkg_time_context --> pkg_agent
   pkg_time_context --> pkg_invariants
   pkg_time_context --> pkg_session
@@ -573,7 +569,6 @@ flowchart TD
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
   pkg_session_persistence_sqlite --> pkg_invariants
-  pkg_session_persistence_sqlite --> pkg_llm
   pkg_session_persistence_sqlite --> pkg_session
   pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
@@ -845,11 +840,6 @@ flowchart TD
   pkg_agent_instructions --> pkg_llm
   pkg_agent_instructions --> pkg_session
   pkg_agent_instructions --> pkg_tools
-  pkg_file_reference_local --> pkg_agent
-  pkg_file_reference_local --> pkg_file_reference
-  pkg_file_reference_local --> pkg_invariants
-  pkg_file_reference_local --> pkg_system_prompt
-  pkg_file_reference_local --> pkg_tools
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compaction
   pkg_session_reference --> pkg_invariants
@@ -857,7 +847,6 @@ flowchart TD
   pkg_session_reference --> pkg_output_retention
   pkg_session_reference --> pkg_session
   pkg_session_reference --> pkg_session_query
-  pkg_session_reference --> pkg_typert_protocol
   pkg_cordis_host_runner --> pkg_agent
   pkg_cordis_host_runner --> pkg_brand
   pkg_cordis_host_runner --> pkg_invariants
@@ -945,11 +934,6 @@ flowchart TD
   pkg_tool_bash_persistent --> pkg_terminal
   pkg_tool_bash_persistent --> pkg_timeout
   pkg_tool_bash_persistent --> pkg_tools
-  pkg_tool_pwsh_persistent --> pkg_agent
-  pkg_tool_pwsh_persistent --> pkg_invariants
-  pkg_tool_pwsh_persistent --> pkg_terminal
-  pkg_tool_pwsh_persistent --> pkg_timeout
-  pkg_tool_pwsh_persistent --> pkg_tools
   pkg_tool_terminal --> pkg_agent
   pkg_tool_terminal --> pkg_invariants
   pkg_tool_terminal --> pkg_jobs
@@ -1034,13 +1018,13 @@ flowchart TD
   pkg_compaction_tool_result_pruner --> pkg_llm
   pkg_compaction_tool_result_pruner --> pkg_session
   pkg_compaction_tool_result_pruner --> pkg_token_meter
-  pkg_experimental_agent_team --> pkg_agent
-  pkg_experimental_agent_team --> pkg_brand
-  pkg_experimental_agent_team --> pkg_invariants
-  pkg_experimental_agent_team --> pkg_llm
-  pkg_experimental_agent_team --> pkg_session
-  pkg_experimental_agent_team --> pkg_session_persistence
-  pkg_experimental_agent_team --> pkg_subagent
+  pkg_team --> pkg_agent
+  pkg_team --> pkg_brand
+  pkg_team --> pkg_invariants
+  pkg_team --> pkg_llm
+  pkg_team --> pkg_session
+  pkg_team --> pkg_session_persistence
+  pkg_team --> pkg_subagent
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
   pkg_tool_cordis --> pkg_invariants
@@ -1052,7 +1036,6 @@ flowchart TD
   pkg_host_apiproxy --> pkg_agent_presets
   pkg_host_apiproxy --> pkg_cordis_host_runner
   pkg_host_apiproxy --> pkg_invariants
-  pkg_host_apiproxy --> pkg_permission_presets
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1140,12 +1123,12 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_jobs
   pkg_agent_spine_demo --> pkg_tool_skill
   pkg_agent_spine_demo --> pkg_tools
-  pkg_experimental_tool_agent_team --> pkg_agent
-  pkg_experimental_tool_agent_team --> pkg_experimental_agent_team
-  pkg_experimental_tool_agent_team --> pkg_invariants
-  pkg_experimental_tool_agent_team --> pkg_session
-  pkg_experimental_tool_agent_team --> pkg_system_prompt
-  pkg_experimental_tool_agent_team --> pkg_tools
+  pkg_tool_team --> pkg_agent
+  pkg_tool_team --> pkg_invariants
+  pkg_tool_team --> pkg_session
+  pkg_tool_team --> pkg_system_prompt
+  pkg_tool_team --> pkg_team
+  pkg_tool_team --> pkg_tools
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1184,7 +1167,6 @@ flowchart TD
   pkg_api_remotes --> pkg_commands
   pkg_api_remotes --> pkg_cordis_host_runner
   pkg_api_remotes --> pkg_credentials
-  pkg_api_remotes --> pkg_file_reference
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_host_plugin_inventory
   pkg_api_remotes --> pkg_invariants
@@ -1192,7 +1174,6 @@ flowchart TD
   pkg_api_remotes --> pkg_message_feedback
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
-  pkg_api_remotes --> pkg_session_reference
   pkg_api_remotes --> pkg_settings
   pkg_api_remotes --> pkg_typert_registry
   pkg_client_runtime --> pkg_agent
@@ -1230,7 +1211,6 @@ flowchart TD
   pkg_client_test_runtime --> pkg_invariants
   pkg_client_ui_input_trigger --> pkg_client_locale
   pkg_client_ui_input_trigger --> pkg_client_runtime
-  pkg_client_ui_input_trigger --> pkg_file_reference
   pkg_client_ui_input_trigger --> pkg_invariants
   pkg_client_ui_settings_models --> pkg_api_remotes
   pkg_client_ui_settings_models --> pkg_client_connection
@@ -1260,14 +1240,6 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
-  pkg_client_ui_reference --> pkg_api_remotes
-  pkg_client_ui_reference --> pkg_client_locale
-  pkg_client_ui_reference --> pkg_client_runtime
-  pkg_client_ui_reference --> pkg_client_ui_input_trigger
-  pkg_client_ui_reference --> pkg_file_reference
-  pkg_client_ui_reference --> pkg_invariants
-  pkg_client_ui_reference --> pkg_session_reference
-  pkg_client_ui_reference --> pkg_typert_protocol
   pkg_cordis_client_runner --> pkg_api_remotes
   pkg_cordis_client_runner --> pkg_client_connection
   pkg_cordis_client_runner --> pkg_client_modules
@@ -1311,10 +1283,6 @@ flowchart TD
   pkg_client_ui_attachment --> pkg_client_runtime
   pkg_client_ui_attachment --> pkg_client_ui_conversation
   pkg_client_ui_attachment --> pkg_invariants
-  pkg_client_ui_brand_official --> pkg_client_runtime
-  pkg_client_ui_brand_official --> pkg_client_ui_conversation
-  pkg_client_ui_brand_official --> pkg_client_ui_sidebar
-  pkg_client_ui_brand_official --> pkg_invariants
   pkg_client_ui_commands --> pkg_api_remotes
   pkg_client_ui_commands --> pkg_client_locale
   pkg_client_ui_commands --> pkg_client_runtime
@@ -1504,13 +1472,14 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) |
 | [`settings-file`](../packages/settings/settings-file) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
-| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
+| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`attachment`](../packages/attachment/attachment), [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) |
 | [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
@@ -1530,7 +1499,6 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) |
-| [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
@@ -1541,7 +1509,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
 | [`session-stats`](../packages/session/session-stats) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
@@ -1591,8 +1559,7 @@ flowchart TD
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`typert-protocol`](../packages/typert/protocol) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
 | [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`tools`](../packages/core/tools) |
 | [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -1609,7 +1576,6 @@ flowchart TD
 | [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`invariants`](../packages/runtime-diagnostics/invariants), [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
 | [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
@@ -1624,9 +1590,9 @@ flowchart TD
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
+| [`team`](../packages/experimental/team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
 | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1637,31 +1603,29 @@ flowchart TD
 | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
-| [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-team`](../packages/experimental/tool-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`team`](../packages/experimental/team), [`tools`](../packages/core/tools) |
 | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
 | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-title`](../packages/session/session-title), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`client-runtime`](../packages/client/runtime), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-slots`](../packages/client/ui-slots), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-settings`](../packages/client/ui-settings), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-layout`](../packages/client/ui-layout), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
diff --git a/packages/credentials/authorization/package.json b/packages/credentials/authorization/package.json
index 05f9832e0e..422328eaf5 100644
--- a/packages/credentials/authorization/package.json
+++ b/packages/credentials/authorization/package.json
@@ -1,9 +1,9 @@
 {
   "name": "@deepseek-ai/dsh-authorization",
   "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
-  "version": "0.0.1-rc.5",
+  "version": "0.1.0-rc.6",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "repository": {
     "type": "git",

From 0b2bc3d651d882ca8ba2d848097290f39042e7a4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 17 Aug 2026 15:18:24 +0800
Subject: [PATCH 26/34] fix(llm-pi-ai): stub both home spellings in the
 tilde-expansion test

os.homedir() reads HOME on POSIX and USERPROFILE on Windows; stubbing
only HOME left the Windows lane expanding ~ into the real profile
directory and failing the fileExists assertions.
---
 packages/llm/llm-pi-ai/tests/auth.spec.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/llm/llm-pi-ai/tests/auth.spec.ts b/packages/llm/llm-pi-ai/tests/auth.spec.ts
index fa6c635c86..27a496a2c3 100644
--- a/packages/llm/llm-pi-ai/tests/auth.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/auth.spec.ts
@@ -158,7 +158,10 @@ describe('pi-ai ambient auth context', () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-pi-home-'))
     dirs.push(dir)
     await writeFile(join(dir, 'creds'), 'x')
+    // Both spellings of "home": os.homedir() reads HOME on POSIX and
+    // USERPROFILE on Windows, and the expansion under test goes through it.
     vi.stubEnv('HOME', dir)
+    vi.stubEnv('USERPROFILE', dir)
     const context = authContextFrom(await stored())
 
     await expect(context.fileExists('~/creds')).resolves.toBe(true)

From 29a82543ed7b072570500a4b3b6b60200a2588a1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 17 Aug 2026 17:13:35 +0800
Subject: [PATCH 27/34] chore(sync): re-record the packages README pairing
 after the cascade

---
 packages/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index ee425f39d7..c93b3d1672 100644
--- a/packages/README.i18n.yaml
+++ b/packages/README.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 packages/README.md
-README.md: a410d7148d14503a61edb9c4848b521552050ca4
-README.zh.md: 780d1356f2095c7dcc526e5cdac8994267e4a460
+README.md: c455feb38489400b6e96101661103dfdeb0d2083
+README.zh.md: 14ab37d08e34728a6aa905e8acbe64447b936894

From a190ef580c291a4838bc57fccb9f4bf270b6bfef Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 18 Aug 2026 10:50:54 +0800
Subject: [PATCH 28/34] chore(release): carry dsh-authorization to the rc.7
 family version

---
 packages/credentials/authorization/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/credentials/authorization/package.json b/packages/credentials/authorization/package.json
index 422328eaf5..9110e37c99 100644
--- a/packages/credentials/authorization/package.json
+++ b/packages/credentials/authorization/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-authorization",
   "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.7",
   "publishConfig": {
     "access": "public"
   },

From fecfabcac4d702f9d1ec6946f2d0fc8e00f94f7f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 18 Aug 2026 17:28:43 +0800
Subject: [PATCH 29/34] fix(credentials): name reference update event
 explicitly

---
 ...al-boundaries-and-atomic-registration.i18n.yaml |  4 ++--
 ...redential-boundaries-and-atomic-registration.md |  4 ++--
 ...ential-boundaries-and-atomic-registration.zh.md |  4 ++--
 .../2026-08-10-remote-event-delivery.i18n.yaml     |  4 ++--
 .../2026-08-10-remote-event-delivery.md            |  4 ++--
 .../2026-08-10-remote-event-delivery.zh.md         |  4 ++--
 docs/event-producer-consumer.i18n.yaml             |  4 ++--
 docs/event-producer-consumer.md                    |  2 +-
 docs/event-producer-consumer.zh.md                 |  2 +-
 docs/subsystems/credentials.i18n.yaml              |  4 ++--
 docs/subsystems/credentials.md                     | 14 +++++++-------
 docs/subsystems/credentials.zh.md                  | 14 +++++++-------
 packages/api/remotes/src/remote-events.ts          |  2 +-
 .../runtime/tests/wire-events.client.spec.ts       |  6 +++---
 .../client/ui-settings-models/README.i18n.yaml     |  4 ++--
 packages/client/ui-settings-models/README.md       |  2 +-
 packages/client/ui-settings-models/README.zh.md    |  2 +-
 .../client/ui-settings-models/src/client/index.ts  |  2 +-
 .../ui-settings-models/tests/apply.client.spec.ts  |  4 ++--
 .../client/ui-settings-plugins/README.i18n.yaml    |  4 ++--
 packages/client/ui-settings-plugins/README.md      |  2 +-
 packages/client/ui-settings-plugins/README.zh.md   |  2 +-
 .../client/ui-settings-plugins/src/client/index.ts |  2 +-
 .../ui-settings-plugins/tests/apply.client.spec.ts |  4 ++--
 .../credentials/credentials-local/README.i18n.yaml |  4 ++--
 packages/credentials/credentials-local/README.md   |  2 +-
 .../credentials/credentials-local/README.zh.md     |  2 +-
 .../credentials/credentials-local/src/invariant.ts |  2 +-
 .../credentials-local/tests/local.spec.ts          |  2 +-
 .../credentials-local/tests/review-fixes.spec.ts   | 14 +++++++-------
 .../credentials-local/tests/watcher.spec.ts        |  8 ++++----
 packages/credentials/credentials/README.i18n.yaml  |  4 ++--
 packages/credentials/credentials/README.md         |  2 +-
 packages/credentials/credentials/README.zh.md      |  2 +-
 packages/credentials/credentials/src/index.ts      |  6 +++---
 packages/credentials/credentials/src/invariant.ts  |  6 +++---
 packages/credentials/credentials/src/types.ts      |  6 +++---
 .../credentials/tests/credentials.spec.ts          |  4 ++--
 .../credentials/tests/invariant.spec.ts            |  2 +-
 packages/credentials/credentials/tests/memory.ts   |  4 ++--
 packages/extensions/tool-cordis/src/api-catalog.ts |  6 +++---
 packages/host/apiproxy/README.i18n.yaml            |  4 ++--
 packages/host/apiproxy/README.md                   |  2 +-
 packages/host/apiproxy/README.zh.md                |  2 +-
 .../host/apiproxy/tests/api-proxy-config.spec.ts   |  8 ++++----
 .../client-runtime/tests/remote.client.spec.ts     |  2 +-
 46 files changed, 97 insertions(+), 97 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index c14fca60a6..61e684cafe 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 69ddfdcf3cd6c15218c672d43cc5aadfd48a0223
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: d234a073467c743aa90e8e60f1f96f4d288fd651
+2026-07-30-credential-boundaries-and-atomic-registration.md: 95c16ef2bf3d82d7b8b53e3975ece3f0c63402f3
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 56ce0d8cbfc0f9023aca406ad43797e7347fdc77
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 69ddfdcf3c..95c16ef2bf 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.m
 
 ## Problem
 
-The credential path leaked across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-file defects the settings write-path note fixes (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
+The credential path leaked across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-file defects the settings write-path note fixes (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/reference-updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
 
 Two request-path defects sat beside them. DeepSeek resolved connection and credential facts independently, so a settings generation the resolver rejected could still pair its credential choice with the previous generation's endpoint. pi-ai handed the SDK `undefined` when a configured `apiKeyEnv` resolved to nothing, letting pi-ai's own environment discovery authenticate with an unrelated provider key — another tenant, silently billed. And its route swap disposed the old registration before creating the new one: a route another adapter owned dropped every existing route, after which the facts cache could equal the registry's, so restoring the working configuration never re-applied.
 
@@ -22,7 +22,7 @@ Two request-path defects sat beside them. DeepSeek resolved connection and crede
 
 **Route replacement is a registry operation, not a caller sequence.** `registerAdapter` returns a handle carrying `replace(providers)`: the candidate set is validated in full first (conflicts, names, provider metadata), then swapped in one synchronous section. A refused replacement leaves the previous routes registered and serving, and the caller's facts cache only advances after the registry actually holds the new set, so reverting to a working configuration re-applies. pi-ai's registration facts are sorted by provider, so a settings document that merely reorders its keys is no longer a route change.
 
-**Contained publication for committed credential writes.** `CredentialProvider.notifyUpdated` fans `credentials/updated` out one listener at a time; sync throws and async rejections are logged without changing the committed operation's outcome, and `INVARIANT`-coded failures rethrow after every listener ran — the same shape the settings seam uses for `settings/updated`. `installSettingsSection`'s cleanup now distinguishes its two triggers: a provider detaching still falls back to the composition entry and re-derives, while the consumer's own unload returns immediately instead of re-registering routes during teardown.
+**Contained publication for committed credential writes.** `CredentialProvider.notifyUpdated` fans `credentials/reference-updated` out one listener at a time; sync throws and async rejections are logged without changing the committed operation's outcome, and `INVARIANT`-coded failures rethrow after every listener ran — the same shape the settings seam uses for `settings/updated`. `installSettingsSection`'s cleanup now distinguishes its two triggers: a provider detaching still falls back to the composition entry and re-derives, while the consumer's own unload returns immediately instead of re-registering routes during teardown.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index d234a07346..56ce0d8cbf 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 凭据路径越过它自己划下的边界发生了泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
 
-存储自身的写路径重演了 settings 写路径 note 在 settings-file 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
+存储自身的写路径重演了 settings 写路径 note 在 settings-file 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/reference-updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
 
 在读取一侧，文件的 `0600` 权限挡得住其他 OS 用户，却挡不住模型：它的 bash 与文件系统工具就以同一个用户身份运行。
 
@@ -26,7 +26,7 @@ Status: implemented
 
 **路由替换是注册表的操作，不是调用方的一串步骤。**`registerAdapter` 返回一个携带 `replace(providers)` 的句柄：候选集合先被完整校验（冲突、名称、提供方元数据），再在一个同步区段内完成替换。被拒绝的替换会让先前的路由保持注册并继续服务，而调用方的事实缓存只有在注册表确实持有新集合之后才会推进，因此改回可用配置时会重新生效。pi-ai 的注册事实按提供方排序，因此仅仅调换键顺序的设置文档不再算作路由变更。
 
-**已提交的凭据写入采用收容式发布。**`CredentialProvider.notifyUpdated` 逐个监听器扇出 `credentials/updated`；同步抛错与异步 rejection 都只记日志，不改变已提交操作的结果，而带 `INVARIANT` 代码的失败会在每个监听器都运行完之后重抛——与 settings seam 处理 `settings/updated` 的形状相同。`installSettingsSection` 的清理现在会区分它的两个触发来源：提供方脱离时仍回退到组合的 entry 配置并重新推导，而消费方自身卸载时立即返回，不再在拆卸过程中重新注册路由。
+**已提交的凭据写入采用收容式发布。**`CredentialProvider.notifyUpdated` 逐个监听器扇出 `credentials/reference-updated`；同步抛错与异步 rejection 都只记日志，不改变已提交操作的结果，而带 `INVARIANT` 代码的失败会在每个监听器都运行完之后重抛——与 settings seam 处理 `settings/updated` 的形状相同。`installSettingsSection` 的清理现在会区分它的两个触发来源：提供方脱离时仍回退到组合的 entry 配置并重新推导，而消费方自身卸载时立即返回，不再在拆卸过程中重新注册路由。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml
index 452705c2ba..92b54628b1 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.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/architecture/2026-08-10-remote-event-delivery.md
-2026-08-10-remote-event-delivery.md: 9c2b5087772a5a343514d1766a14e90edb261813
-2026-08-10-remote-event-delivery.zh.md: 213715f5d9efcc11290059e5c5b0c06bbd7e255d
+2026-08-10-remote-event-delivery.md: ee3d9884b53f5fa5d0b0072660888c5f4d283b1b
+2026-08-10-remote-event-delivery.zh.md: a51a0ade174e70177f438a4bbc6bcd452807f436
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
index 9c2b508777..ee3d9884b5 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-10-remote-event-delivery.zh.md)
 
 [Typert Gateway targeted method calls](../../implemented/architecture/2026-08-02-typert-remote-method-calls.md) cover only the request/response shape and deliberately leave Session event streams and stateful interactions to separate designs. Every **one-way Host-to-consumer push** therefore still rides the legacy API Proxy.
 
-The Host owns a family of one-way events whose payloads are already JSON and whose emission never binds an AgentScope: `agent-preset/selected`, `commands/change`, `credentials/updated`, `llm/adapters-updated`, and `settings/document-updated`. Reaching one UI subscriber took four hops: the Host cordis event, a hand-written `HostFrame` variant plus its zod branch in apiproxy, a hand-written bridge in client/runtime that re-emitted it as a Client cordis event, and finally the consumer's `ctx.on(...)`. Adding one such event edited five places (frame union, zod union, host-stream listener, client bridge, a duplicated Client-side `Events` declaration), and not one of them stated a new fact: the name, the payload type, and the emission point were all declared by the owner package's cordis `Events` merge.
+The Host owns a family of one-way events whose payloads are already JSON and whose emission never binds an AgentScope: `agent-preset/selected`, `commands/change`, `credentials/reference-updated`, `llm/adapters-updated`, and `settings/document-updated`. Reaching one UI subscriber took four hops: the Host cordis event, a hand-written `HostFrame` variant plus its zod branch in apiproxy, a hand-written bridge in client/runtime that re-emitted it as a Client cordis event, and finally the consumer's `ctx.on(...)`. Adding one such event edited five places (frame union, zod union, host-stream listener, client bridge, a duplicated Client-side `Events` declaration), and not one of them stated a new fact: the name, the payload type, and the emission point were all declared by the owner package's cordis `Events` merge.
 
 That duplicated declaration is also **lossy**: the Client side restates it as `settings/changed(ns: string)`, flattening a branded type into bare `string` — the opposite of the Remote method contract, where a consumer type points at the business package's one canonical symbol.
 
@@ -75,7 +75,7 @@ Delivery shares no implementation with the cordis event system: one-way only, no
 export const API_REMOTE_FORWARDED_EVENTS = [
   'agent-preset/selected',
   'commands/change',
-  'credentials/updated',
+  'credentials/reference-updated',
   'llm/adapters-updated',
   'settings/document-updated',
 ] as const
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
index 213715f5d9..a51a0ade17 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 [Typert Remote 方法调用](../../implemented/architecture/2026-08-02-typert-remote-method-calls.md)只覆盖「一次请求一个结果」的定向调用，明确把 Session 事件流与有状态交互留在别处；Host 向消费端的**单向事件推送**因此仍然全部压在遗留的 API Proxy 上。
 
-Host 拥有 `agent-preset/selected`、`commands/change`、`credentials/updated`、`llm/adapters-updated`、`settings/document-updated` 这五条单向事件；它们既不依赖 AgentScope，载荷也本来就是 JSON。过去每条都要穿过 host cordis 事件、apiproxy 手写帧、client/runtime 手写桥和 Client 事件别名才能抵达 UI，而这些层没有陈述 owner 事件之外的新事实。
+Host 拥有 `agent-preset/selected`、`commands/change`、`credentials/reference-updated`、`llm/adapters-updated`、`settings/document-updated` 这五条单向事件；它们既不依赖 AgentScope，载荷也本来就是 JSON。过去每条都要穿过 host cordis 事件、apiproxy 手写帧、client/runtime 手写桥和 Client 事件别名才能抵达 UI，而这些层没有陈述 owner 事件之外的新事实。
 
 那份重复声明还是**有损**的：client 侧写成 `settings/changed(ns: string)`，brand 类型在这一跳被拍平成裸 `string`，与 Remote 方法侧「消费端类型指向业务包唯一符号」的既有契约相反。
 
@@ -75,7 +75,7 @@ $dispatch(event: string, args: readonly unknown[]): void
 export const API_REMOTE_FORWARDED_EVENTS = [
   'agent-preset/selected',
   'commands/change',
-  'credentials/updated',
+  'credentials/reference-updated',
   'llm/adapters-updated',
   'settings/document-updated',
 ] as const
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 1ac2e8f56a..9d71486d57 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 49c7a128fcf2539d342ad263bb856c40f2a33f0c
-event-producer-consumer.zh.md: dec8b443aa73ae919ceee7cd282846bea4e8ce18
+event-producer-consumer.md: e507e0e83fa32618393d06bfaa746a3e0b1e4611
+event-producer-consumer.zh.md: 94da41dbe23a870db959f5f878d025158efd2858
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 49c7a128fc..e507e0e83f 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -31,7 +31,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index dec8b443aa..94da41dbe2 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -33,7 +33,7 @@
 | `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:87`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:75`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 8f9e2f9474..74b628e0b9 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 8d75a254109dcce5d0b54cd4fd293a8ca4e335c5
-credentials.zh.md: 46edda84a063c539748da344d7efa66c7af666e7
+credentials.md: 459511965d796cd34d1a817110016bcb922d2988
+credentials.zh.md: d833f7897008dd9f9c062d8fbefc1e4ba9c0d959
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 8d75a25410..459511965d 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -47,7 +47,7 @@ interface CredentialInfo {
 
 ## Change commits
 
-`credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
+`credentials/reference-updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -244,16 +244,16 @@ Source: [`packages/credentials/authorization/src/index.ts:57`](../../packages/cr
 
 #### `credentials/record-updated` — emit
 
-Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/reference-updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/reference-updated`.
 
 ```ts cordis-catalog
 /**
  * Committed change to a stored credential record: a `modifyRecord` that
  * wrote, a `deleteRecord` that removed, or an external edit observed in
- * storage. Separate from `credentials/updated` because the two key
+ * storage. Separate from `credentials/reference-updated` because the two key
  * grammars are disjoint — a listener that received both on one event could
  * not tell which space a subject belongs to. Listener failures are
- * contained on the same terms as `credentials/updated`.
+ * contained on the same terms as `credentials/reference-updated`.
  * @param key - the record whose stored value changed.
  * @mode emit
  */
@@ -262,9 +262,9 @@ Committed change to a stored credential record: a `modifyRecord` that wrote, a `
 
 Source: [`packages/credentials/credentials/src/types.ts:87`](../../packages/credentials/credentials/src/types.ts)
 
-<a id="credentialsupdated--emit"></a>
+<a id="credentialsreference-updated--emit"></a>
 
-#### `credentials/updated` — emit
+#### `credentials/reference-updated` — emit
 
 Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
 
@@ -281,7 +281,7 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
  * @param ref - the reference whose stored value changed.
  * @mode emit
  */
-'credentials/updated'(ref: CredentialRef): void
+'credentials/reference-updated'(ref: CredentialRef): void
 ```
 
 Source: [`packages/credentials/credentials/src/types.ts:75`](../../packages/credentials/credentials/src/types.ts)
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 46edda84a0..d833f78970 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -47,7 +47,7 @@ interface CredentialInfo {
 
 ## 已提交的变更
 
-`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后发出——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/reference-updated (ref)` 在提供方管理的来源发生已提交变更后发出——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -244,16 +244,16 @@ Source: [`packages/credentials/authorization/src/index.ts:57`](../../packages/cr
 
 #### `credentials/record-updated` — emit
 
-Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.
+Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/reference-updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/reference-updated`.
 
 ```ts cordis-catalog
 /**
  * Committed change to a stored credential record: a `modifyRecord` that
  * wrote, a `deleteRecord` that removed, or an external edit observed in
- * storage. Separate from `credentials/updated` because the two key
+ * storage. Separate from `credentials/reference-updated` because the two key
  * grammars are disjoint — a listener that received both on one event could
  * not tell which space a subject belongs to. Listener failures are
- * contained on the same terms as `credentials/updated`.
+ * contained on the same terms as `credentials/reference-updated`.
  * @param key - the record whose stored value changed.
  * @mode emit
  */
@@ -262,9 +262,9 @@ Committed change to a stored credential record: a `modifyRecord` that wrote, a `
 
 Source: [`packages/credentials/credentials/src/types.ts:87`](../../packages/credentials/credentials/src/types.ts)
 
-<a id="credentialsupdated--emit"></a>
+<a id="credentialsreference-updated--emit"></a>
 
-#### `credentials/updated` — emit
+#### `credentials/reference-updated` — emit
 
 Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
 
@@ -281,7 +281,7 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
  * @param ref - the reference whose stored value changed.
  * @mode emit
  */
-'credentials/updated'(ref: CredentialRef): void
+'credentials/reference-updated'(ref: CredentialRef): void
 ```
 
 Source: [`packages/credentials/credentials/src/types.ts:75`](../../packages/credentials/credentials/src/types.ts)
diff --git a/packages/api/remotes/src/remote-events.ts b/packages/api/remotes/src/remote-events.ts
index 2174336532..949778cbe8 100644
--- a/packages/api/remotes/src/remote-events.ts
+++ b/packages/api/remotes/src/remote-events.ts
@@ -17,7 +17,7 @@
 export const API_REMOTE_FORWARDED_EVENTS = [
   'agent-preset/selected',
   'commands/change',
-  'credentials/updated',
+  'credentials/reference-updated',
   'cordis/request-run',
   'cordis/request-run-resolved',
   'cordis/dynamic-package',
diff --git a/packages/client/runtime/tests/wire-events.client.spec.ts b/packages/client/runtime/tests/wire-events.client.spec.ts
index 13365c1462..fbc4204b0d 100644
--- a/packages/client/runtime/tests/wire-events.client.spec.ts
+++ b/packages/client/runtime/tests/wire-events.client.spec.ts
@@ -28,7 +28,7 @@ function forwardedEventContracts(ctx: Context): void {
     const bare: typeof namespace = 'plain-string'
     void bare; void namespace; void source
   })
-  ctx.remote.$on('credentials/updated', () => {})
+  ctx.remote.$on('credentials/reference-updated', () => {})
   ctx.remote.$on('commands/change', () => {})
   ctx.remote.$on('llm/adapters-updated', () => {})
   ctx.remote.$on('agent-preset/selected', (sessionId, agentPreset) => {
@@ -106,7 +106,7 @@ describe('wire event bridge', () => {
     })
     bench.sinks?.onHostEnvelope?.({
       rpcId: 'r4' as never,
-      payload: { type: 'host/remote-event', event: 'credentials/updated', args: ['OPENAI_API_KEY'] },
+      payload: { type: 'host/remote-event', event: 'credentials/reference-updated', args: ['OPENAI_API_KEY'] },
     })
     // The carrier does not second-guess the name: selecting what a consumer can
     // receive is the allowlist's job, and dropping an unsubscribed name is the
@@ -118,7 +118,7 @@ describe('wire event bridge', () => {
 
     expect(seen).toEqual([
       ['settings/document-updated', 'llm-pi-ai', 7],
-      ['credentials/updated', 'OPENAI_API_KEY'],
+      ['credentials/reference-updated', 'OPENAI_API_KEY'],
       ['nobody/listening', 'ignored'],
     ])
   })
diff --git a/packages/client/ui-settings-models/README.i18n.yaml b/packages/client/ui-settings-models/README.i18n.yaml
index 950124960a..5e6da8d9b3 100644
--- a/packages/client/ui-settings-models/README.i18n.yaml
+++ b/packages/client/ui-settings-models/README.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 packages/client/ui-settings-models/README.md
-README.md: 0d76d5f31585721ad8f5cd76dd223d72353fdd0c
-README.zh.md: 8ac336245c9d82420c10132b3b935cf00f5ea889
+README.md: 781d7a8134c8118ddf4a78f3ee153a8043bae0a6
+README.zh.md: a652e9a250d855c0e91f842ec2332f4a49f17856
diff --git a/packages/client/ui-settings-models/README.md b/packages/client/ui-settings-models/README.md
index 0d76d5f315..781d7a8134 100644
--- a/packages/client/ui-settings-models/README.md
+++ b/packages/client/ui-settings-models/README.md
@@ -10,7 +10,7 @@ The notice step owns its exact copy and version in `src/onboarding-copy.ts`. On
 
 After that notice completes, the DeepSeek step projects first-run readiness from the same joined Models snapshot. ANY provider the user can already reach ends it without rendering — a registered route whose named credential reference is stored, including a read-only launch-environment credential, or one whose profile names no reference and therefore authenticates natively. Only a user with none is asked for the official DeepSeek key. A mounted, active adapter with a missing writable reference renders the existing `ProviderEditor` in credential-only mode inside the shared onboarding modal; `credentials.set` stays the only secret write, and no provider settings are changed. Configure later completes only this coordinator pass. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering; Models remains the diagnostic surface.
 
-Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it mutates the fields it can see rather than rebuilding a section. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, with the same fields the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value matching a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that pasted-line check runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. Once loaded, the page subscribes directly to forwarded `settings/document-updated`, `credentials/updated`, and `llm/adapters-updated` owner events, plus local `connection/reset`, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it mutates the fields it can see rather than rebuilding a section. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, with the same fields the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value matching a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that pasted-line check runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. Once loaded, the page subscribes directly to forwarded `settings/document-updated`, `credentials/reference-updated`, and `llm/adapters-updated` owner events, plus local `connection/reset`, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
 ## Model list and endpoint interrogation
 
diff --git a/packages/client/ui-settings-models/README.zh.md b/packages/client/ui-settings-models/README.zh.md
index 8ac336245c..a652e9a250 100644
--- a/packages/client/ui-settings-models/README.zh.md
+++ b/packages/client/ui-settings-models/README.zh.md
@@ -10,7 +10,7 @@
 
 声明完成后，DeepSeek 步骤会从同一个 Models 联接快照得出首次运行就绪状态。只要用户已经能触达**任何**一个提供方，它就直接完成而不渲染——已注册且其具名凭据引用已存储的路由（包括来自启动环境且只读的凭据），或 profile 根本不指名引用、因而走原生认证的路由。只有二者皆无的用户才会被要求填写 DeepSeek 官方密钥。适配器已挂载且活跃、引用可写但尚未配置时，既有 `ProviderEditor` 会以仅凭据模式渲染在共用引导弹窗中；`credentials.set` 仍是唯一的 secret 写入，且不会改变提供方设置。「稍后配置」只完成协调器当前这一轮。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤不渲染并直接完成；Models 页仍是诊断界面。
 
-每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它只修改自己看得见的字段，而不重建分节。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，使用与 pi-ai 提供方表单相同的字段。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。与整行粘贴的 `NAME=value` 环境变量匹配或首尾成对引号包裹的值，会以同一条格式失败被拒绝；这项粘贴行检查只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会直接订阅转发的 owner 事件 `settings/document-updated`、`credentials/updated`、`llm/adapters-updated`，以及本地 `connection/reset`，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它只修改自己看得见的字段，而不重建分节。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，使用与 pi-ai 提供方表单相同的字段。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。与整行粘贴的 `NAME=value` 环境变量匹配或首尾成对引号包裹的值，会以同一条格式失败被拒绝；这项粘贴行检查只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会直接订阅转发的 owner 事件 `settings/document-updated`、`credentials/reference-updated`、`llm/adapters-updated`，以及本地 `connection/reset`，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
 ## 模型列表与端点询问
 
diff --git a/packages/client/ui-settings-models/src/client/index.ts b/packages/client/ui-settings-models/src/client/index.ts
index 6bb403a90f..90a2aed75a 100644
--- a/packages/client/ui-settings-models/src/client/index.ts
+++ b/packages/client/ui-settings-models/src/client/index.ts
@@ -108,7 +108,7 @@ export function apply(ctx: ClientContext): void {
     const refreshModels = (): void => { refreshIfLoaded(controller) }
     const disposers = [
       ctx.remote.$on('settings/document-updated', () => { refreshModels() }),
-      ctx.remote.$on('credentials/updated', refreshModels),
+      ctx.remote.$on('credentials/reference-updated', refreshModels),
       ctx.remote.$on('llm/adapters-updated', refreshModels),
       ctx.on('connection/reset', refreshModels),
     ]
diff --git a/packages/client/ui-settings-models/tests/apply.client.spec.ts b/packages/client/ui-settings-models/tests/apply.client.spec.ts
index f098a9b7e8..18182602d2 100644
--- a/packages/client/ui-settings-models/tests/apply.client.spec.ts
+++ b/packages/client/ui-settings-models/tests/apply.client.spec.ts
@@ -177,7 +177,7 @@ describe('pushed invalidations', () => {
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     // The fake wire face has no methods: a fetch attempt would throw.
     b.ctx.remote.$dispatch('settings/document-updated', ['llm-pi-ai', 1])
-    b.ctx.remote.$dispatch('credentials/updated', ['OPENAI_API_KEY'])
+    b.ctx.remote.$dispatch('credentials/reference-updated', ['OPENAI_API_KEY'])
     b.ctx.remote.$dispatch('llm/adapters-updated', [])
     b.ctx.emit('connection/reset')
   })
@@ -210,7 +210,7 @@ describe('pushed invalidations', () => {
     )()
     injected.controller.store.update((state) => { state.status = 'ready' })
     const load = vi.spyOn(injected.controller, 'load').mockResolvedValue()
-    b.ctx.remote.$dispatch('credentials/updated', ['DEEPSEEK_API_KEY'])
+    b.ctx.remote.$dispatch('credentials/reference-updated', ['DEEPSEEK_API_KEY'])
     expect(load).toHaveBeenCalledTimes(1)
   })
 
diff --git a/packages/client/ui-settings-plugins/README.i18n.yaml b/packages/client/ui-settings-plugins/README.i18n.yaml
index ae8c3a78bf..e8a19821f5 100644
--- a/packages/client/ui-settings-plugins/README.i18n.yaml
+++ b/packages/client/ui-settings-plugins/README.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 packages/client/ui-settings-plugins/README.md
-README.md: 92ba426b6bee3ae73e184dfcfd418e889bd47086
-README.zh.md: dc319ea9f128016b6df821575cb4d75740f04579
+README.md: 0ee0edbebadad8e8e895002cd9eb60a20f45809d
+README.zh.md: 75cc63ccf5280bba1b94bcf8930b9ee9432440e5
diff --git a/packages/client/ui-settings-plugins/README.md b/packages/client/ui-settings-plugins/README.md
index 92ba426b6b..0ee0edbeba 100644
--- a/packages/client/ui-settings-plugins/README.md
+++ b/packages/client/ui-settings-plugins/README.md
@@ -20,7 +20,7 @@ A card stages what the user types and writes it only when they save. Each contro
 
 Saving writes each staged field through the client settings scope, which fences every write with the namespace revision it read, so a form that has drifted from the document is refused rather than overwriting a concurrent change. The Host is the only authority on whether a value was accepted — its validators own the constraints no schema can express — so the card reads the section back afterwards and reports a save that did not land, keeping those drafts for the user to correct.
 
-A key can also be written from another surface — the Models page addresses the same reference — which changes no settings section, so the card re-reads on the forwarded `credentials/updated` event for the reference it watches.
+A key can also be written from another surface — the Models page addresses the same reference — which changes no settings section, so the card re-reads on the forwarded `credentials/reference-updated` event for the reference it watches.
 
 A field's presence in the raw user layer — not its value — is what marks it overridden; a reset clears that field so it re-inherits the composition layer. Secret-role fields never ride a response, so a key control starts blank, reports only whether one is configured, and writes through the credentials domain rather than the settings section; a blank draft writes nothing and keeps the stored key.
 
diff --git a/packages/client/ui-settings-plugins/README.zh.md b/packages/client/ui-settings-plugins/README.zh.md
index dc319ea9f1..75cc63ccf5 100644
--- a/packages/client/ui-settings-plugins/README.zh.md
+++ b/packages/client/ui-settings-plugins/README.zh.md
@@ -20,7 +20,7 @@
 
 保存时，每个暂存字段都通过客户端 settings scope 写入，该 scope 用读取时的命名空间 revision 为每次写入设栅，因此已与文档脱节的表单会被拒绝，而不是覆盖并发变更。某个值是否被接受只有 Host 说了算——schema 表达不了的约束归它的校验器所有——因此卡片在写入后回读分节，报告没有落盘的保存，并保留这些草稿供用户修改。
 
-密钥也可能从别的表层写入——模型页寻址的是同一个引用——而那不改变任何 settings 分节，因此卡片会在转发来的 `credentials/updated` 事件报告它所关注的引用时重读。
+密钥也可能从别的表层写入——模型页寻址的是同一个引用——而那不改变任何 settings 分节，因此卡片会在转发来的 `credentials/reference-updated` 事件报告它所关注的引用时重读。
 
 字段是否被覆盖，取决于它是否出现在原始用户层中，而非取决于它的值；重置会清除该字段，使其重新继承组装层。secret 角色的字段绝不搭乘响应，因此密钥控件初始为空、只报告是否已配置，并经由 credentials 领域而非 settings 分节写入；空草稿不写入任何东西，保留已存密钥。
 
diff --git a/packages/client/ui-settings-plugins/src/client/index.ts b/packages/client/ui-settings-plugins/src/client/index.ts
index 184511ead1..daf7a280dc 100644
--- a/packages/client/ui-settings-plugins/src/client/index.ts
+++ b/packages/client/ui-settings-plugins/src/client/index.ts
@@ -68,7 +68,7 @@ export function apply(ctx: ClientContext): void {
   // scope publishes nothing when one is written. This is the only signal that
   // a key written on another surface reached the Host.
   ctx.effect(
-    () => ctx.remote.$on('credentials/updated', (ref) => { webSearch.refreshCredential(ref) }),
+    () => ctx.remote.$on('credentials/reference-updated', (ref) => { webSearch.refreshCredential(ref) }),
     'ui-settings-plugins: credential invalidations',
   )
 
diff --git a/packages/client/ui-settings-plugins/tests/apply.client.spec.ts b/packages/client/ui-settings-plugins/tests/apply.client.spec.ts
index 23e46e15a5..539096cfcc 100644
--- a/packages/client/ui-settings-plugins/tests/apply.client.spec.ts
+++ b/packages/client/ui-settings-plugins/tests/apply.client.spec.ts
@@ -180,7 +180,7 @@ describe('ui-settings-plugins apply', () => {
 
     // A key written on another surface changes no settings section, so this
     // event is the only thing that reaches the card.
-    ctx.remote.$dispatch('credentials/updated', ['DEEPSEEK_API_KEY'])
+    ctx.remote.$dispatch('credentials/reference-updated', ['DEEPSEEK_API_KEY'])
 
     await vi.waitFor(() => { expect(describeCredentials).toHaveBeenCalledTimes(1) })
   })
@@ -192,7 +192,7 @@ describe('ui-settings-plugins apply', () => {
     await vi.waitFor(() => { expect(describeCredentials).toHaveBeenCalled() })
     describeCredentials.mockClear()
 
-    ctx.remote.$dispatch('credentials/updated', ['SOME_OTHER_KEY'])
+    ctx.remote.$dispatch('credentials/reference-updated', ['SOME_OTHER_KEY'])
     await Promise.resolve()
 
     expect(describeCredentials).not.toHaveBeenCalled()
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index ba58baf497..b54623d908 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/README.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 packages/credentials/credentials-local/README.md
-README.md: cc9c63bd689f3e5dd028add77fb72ca9eb541623
-README.zh.md: 2368d5ff7db3c515e3826d53efad2c35768328f0
+README.md: 1b8e4e5d89dc0eb5da2b04b6281c70316262c03b
+README.zh.md: 7ba7726e46a6cd5c6b26a2e55e001a750a0e6dd1
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index cc9c63bd68..1b8e4e5d89 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -69,7 +69,7 @@ The provider creates the directory `0700` and creates or atomically replaces the
 
 ## Hot reload
 
-External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix; file access and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
+External edits publish `credentials/reference-updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix; file access and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
 
 ## Security boundary
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 2368d5ff7d..7ba7726e46 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -69,7 +69,7 @@ records:
 
 ## 热重载
 
-外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/reference-updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
 
 <a id="security-boundary"></a>
 
diff --git a/packages/credentials/credentials-local/src/invariant.ts b/packages/credentials/credentials-local/src/invariant.ts
index 0ea27d0071..4f584e135b 100644
--- a/packages/credentials/credentials-local/src/invariant.ts
+++ b/packages/credentials/credentials-local/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: the Service Definition companion (`dsh-credentials/invariant`) owns the
- * `credentials/updated` lifecycle contract; this provider's file/environment layering is
+ * `credentials/reference-updated` lifecycle contract; this provider's file/environment layering is
  * asynchronous I/O pinned by its unit suite.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 1f24a50a0b..2158790b2e 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -41,7 +41,7 @@ async function boot(config: ConstructorParameters<typeof LocalCredentialProvider
 
 function updates(ctx: Context): CredentialRef[] {
   const seen: CredentialRef[] = []
-  ctx.on('credentials/updated', (ref) => {
+  ctx.on('credentials/reference-updated', (ref) => {
     seen.push(ref)
   })
   return seen
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index 60aab4c6e1..e385d0d3aa 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -1,5 +1,5 @@
 // Third-review behaviors: read-modify-write under the writer lock (external
-// edits survive an API write), the contained credentials/updated fan-out (a
+// edits survive an API write), the contained credentials/reference-updated fan-out (a
 // broken observer never fails a committed write), and the YAML document
 // editor's isolation between entries.
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -45,7 +45,7 @@ describe('read-modify-write', () => {
     const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
     const seen: string[] = []
-    ctx.on('credentials/updated', (ref) => { seen.push(ref) })
+    ctx.on('credentials/reference-updated', (ref) => { seen.push(ref) })
     await ctx.credentials.set(ALPHA, 'one')
     // The external edit has landed on disk but no watcher reported it (watch
     // is off — the same blind spot as a debounce window or a missed event).
@@ -117,11 +117,11 @@ describe('contained update fan-out', () => {
   it('does not fail a committed set when a listener throws, and later listeners still run', async () => {
     const dir = await tempDir()
     const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
-    ctx.on('credentials/updated', () => {
+    ctx.on('credentials/reference-updated', () => {
       throw new Error('observer boom')
     })
     const second = vi.fn()
-    ctx.on('credentials/updated', second)
+    ctx.on('credentials/reference-updated', second)
     await expect(ctx.credentials.set(ALPHA, 'one')).resolves.toBeUndefined()
     expect(second).toHaveBeenCalledWith(ALPHA)
     expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'one', source: 'file' })
@@ -133,7 +133,7 @@ describe('contained update fan-out', () => {
     // An unknown-returning function keeps the typed surface legal while the
     // runtime value is still the rejected promise the containment must handle.
     const boom = (): unknown => Promise.reject(new Error('async observer boom'))
-    ctx.on('credentials/updated', boom)
+    ctx.on('credentials/reference-updated', boom)
     await expect(ctx.credentials.set(ALPHA, 'one')).resolves.toBeUndefined()
     await new Promise(resolve => setTimeout(resolve, 10))
   })
@@ -142,11 +142,11 @@ describe('contained update fan-out', () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
-    ctx.on('credentials/updated', () => {
+    ctx.on('credentials/reference-updated', () => {
       throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
     })
     const second = vi.fn()
-    ctx.on('credentials/updated', second)
+    ctx.on('credentials/reference-updated', second)
     await expect(ctx.credentials.set(ALPHA, 'one')).rejects.toThrow(/forged relation/)
     // Harness-fatal by design — but the write itself committed first.
     expect(second).toHaveBeenCalledWith(ALPHA)
diff --git a/packages/credentials/credentials-local/tests/watcher.spec.ts b/packages/credentials/credentials-local/tests/watcher.spec.ts
index 58c83a0407..b51a188e5d 100644
--- a/packages/credentials/credentials-local/tests/watcher.spec.ts
+++ b/packages/credentials/credentials-local/tests/watcher.spec.ts
@@ -147,7 +147,7 @@ describe('watcher pipeline', () => {
     const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, debounceMs: 5 })
     let arm = true
-    ctx.on('credentials/updated', () => {
+    ctx.on('credentials/reference-updated', () => {
       if (!arm) return
       throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
     })
@@ -178,7 +178,7 @@ describe('watcher pipeline', () => {
     await fiber
     let disposed = false
     let postDisposeCommits = 0
-    ctx.on('credentials/updated', () => {
+    ctx.on('credentials/reference-updated', () => {
       if (disposed) postDisposeCommits += 1
     })
 
@@ -202,7 +202,7 @@ describe('watcher pipeline', () => {
     await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: doomed\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
-    ctx.on('credentials/updated', (ref) => {
+    ctx.on('credentials/reference-updated', (ref) => {
       seen.push(ref)
     })
 
@@ -221,7 +221,7 @@ describe('watcher pipeline', () => {
     await writeCredentials(path, 'version: 1\nrefs:\n  DSH_CRED_PIPE: a\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
-    ctx.on('credentials/updated', (ref) => {
+    ctx.on('credentials/reference-updated', (ref) => {
       seen.push(ref)
     })
 
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 8b474edf71..fed06eace0 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/README.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 packages/credentials/credentials/README.md
-README.md: d1b48aa724801a482517679790bba172fa60d013
-README.zh.md: a936b97353d7a66b7f0f7f9a760f4542bb2a9b30
+README.md: ff2e9a7002a3a4a2527ec0a36a4472711da5be2a
+README.zh.md: 5a21361c8dec5f98a36e5a1753ad8fc2f670bc0b
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index d1b48aa724..ff2e9a7002 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -46,7 +46,7 @@ await ctx.credentials.deleteRecord(key)                  // no-op when absent
 
 A `grant` record's `payload` is opaque: the seam never reads, validates, or reshapes it. The one constraint is that it survives a JSON round trip, which the provider enforces on the way in and on the way out — a value the store could not read back exactly as written is refused rather than stored lossily.
 
-`credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration UIs refreshing a "configured" badge. Its declaration lives in the client-safe `./types` subpath export together with the `CredentialRef` type it names (the package root re-exports the type), so a consumer outside the Host compilation face reads the very signature the Host emits instead of restating it.
+`credentials/reference-updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration UIs refreshing a "configured" badge. Its declaration lives in the client-safe `./types` subpath export together with the `CredentialRef` type it names (the package root re-exports the type), so a consumer outside the Host compilation face reads the very signature the Host emits instead of restating it.
 
 The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only source (the live process environment, in the local provider) currently supplies the reference, a write would appear to succeed while resolution keeps returning the shadowing value — the seam rejects instead, and `describe().writable` lets a UI render the reference read-only up front.
 
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index a936b97353..5a21361c8d 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -46,7 +46,7 @@ await ctx.credentials.deleteRecord(key)                  // no-op when absent
 
 `grant` 记录的 `payload` 是不透明的：seam 从不读取、校验或重塑它。唯一约束是它能经受 JSON 往返，提供方在写入与读出两个方向都强制这一点——存储无法逐字读回的值会被拒绝，而不是有损地存下。
 
-`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。它的声明住在 client-safe 的 `./types` 子路径出口，与其点名的 `CredentialRef` 类型同处一处（包根继续 re-export 该类型），于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
+`credentials/reference-updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。它的声明住在 client-safe 的 `./types` 子路径出口，与其点名的 `CredentialRef` 类型同处一处（包根继续 re-export 该类型），于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
 
 `set`/`unset` 的遮蔽规则有意采用明确报错的方式：当只读来源（本地提供方中即当前进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
 
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index 087672f2fd..9d80f4ae79 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -263,7 +263,7 @@ export abstract class CredentialProvider extends Service {
   abstract deleteRecord(key: CredentialKey): Promise<void>
 
   /**
-   * Fan `credentials/updated` out with contained listener failures: every
+   * Fan `credentials/reference-updated` out with contained listener failures: every
    * listener runs, and a sync throw or async rejection is logged without
    * changing the committed operation's outcome — except `INVARIANT`-coded
    * failures, which rethrow after every listener ran (the rethrow reaches the
@@ -274,7 +274,7 @@ export abstract class CredentialProvider extends Service {
    * @param ref - the reference whose stored value changed.
    */
   protected notifyUpdated(ref: CredentialRef): void {
-    this.fanOut('credentials/updated', ref)
+    this.fanOut('credentials/reference-updated', ref)
   }
 
   /**
@@ -290,7 +290,7 @@ export abstract class CredentialProvider extends Service {
      fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
      contract, and extracting it would couple the two seams' event semantics. */
   /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
-  private fanOut(event: 'credentials/updated' | 'credentials/record-updated', subject: string): void {
+  private fanOut(event: 'credentials/reference-updated' | 'credentials/record-updated', subject: string): void {
     let invariantFailure: unknown
     const args = [event, subject]
     for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) {
diff --git a/packages/credentials/credentials/src/invariant.ts b/packages/credentials/credentials/src/invariant.ts
index 790388ffae..3cfb89d6ab 100644
--- a/packages/credentials/credentials/src/invariant.ts
+++ b/packages/credentials/credentials/src/invariant.ts
@@ -14,7 +14,7 @@ export const name = 'credentials-invariant'
 export const inject = ['invariants']
 
 /**
- * Install the commit-event lifecycle contract: `credentials/updated` names a
+ * Install the commit-event lifecycle contract: `credentials/reference-updated` names a
  * committed provider-source change, so it can only fire while a credentials
  * service is live — an emission after disposal means a provider leaked work
  * past its teardown quiescence. The value relation itself (`describe`
@@ -22,9 +22,9 @@ export const inject = ['invariants']
  * each provider's own suite.
  */
 const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => {
-  ctx.on('credentials/updated', (ref) => {
+  ctx.on('credentials/reference-updated', (ref) => {
     if (ctx.get('credentials') === undefined) {
-      fail(`credentials/updated for "${ref}" emitted without a live credentials service`)
+      fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`)
     }
   })
 }
diff --git a/packages/credentials/credentials/src/types.ts b/packages/credentials/credentials/src/types.ts
index 69f6185085..2a76ae5c61 100644
--- a/packages/credentials/credentials/src/types.ts
+++ b/packages/credentials/credentials/src/types.ts
@@ -72,15 +72,15 @@ declare module '@deepseek-ai/cordis' {
      * @param ref - the reference whose stored value changed.
      * @mode emit
      */
-    'credentials/updated'(ref: CredentialRef): void
+    'credentials/reference-updated'(ref: CredentialRef): void
 
     /**
      * Committed change to a stored credential record: a `modifyRecord` that
      * wrote, a `deleteRecord` that removed, or an external edit observed in
-     * storage. Separate from `credentials/updated` because the two key
+     * storage. Separate from `credentials/reference-updated` because the two key
      * grammars are disjoint — a listener that received both on one event could
      * not tell which space a subject belongs to. Listener failures are
-     * contained on the same terms as `credentials/updated`.
+     * contained on the same terms as `credentials/reference-updated`.
      * @param key - the record whose stored value changed.
      * @mode emit
      */
diff --git a/packages/credentials/credentials/tests/credentials.spec.ts b/packages/credentials/credentials/tests/credentials.spec.ts
index 2941494f48..17ef2b3496 100644
--- a/packages/credentials/credentials/tests/credentials.spec.ts
+++ b/packages/credentials/credentials/tests/credentials.spec.ts
@@ -55,7 +55,7 @@ describe('the credentials seam through the memory provider', () => {
   it('stores through set, removes through unset, and emits the committed change', async () => {
     const ctx = await boot()
     const events: CredentialRef[] = []
-    ctx.on('credentials/updated', ref => void events.push(ref))
+    ctx.on('credentials/reference-updated', ref => void events.push(ref))
 
     await ctx.credentials.set(REF, 'sk-live')
     expect(await ctx.credentials.resolve(REF)).toEqual({ value: 'sk-live', source: 'memory' })
@@ -67,7 +67,7 @@ describe('the credentials seam through the memory provider', () => {
   it('rejects an empty set and keeps an absent unset silent', async () => {
     const ctx = await boot()
     const events: CredentialRef[] = []
-    ctx.on('credentials/updated', ref => void events.push(ref))
+    ctx.on('credentials/reference-updated', ref => void events.push(ref))
 
     await expect(ctx.credentials.set(REF, '')).rejects.toThrow(/empty value/)
     await ctx.credentials.unset(REF)
diff --git a/packages/credentials/credentials/tests/invariant.spec.ts b/packages/credentials/credentials/tests/invariant.spec.ts
index 8ba3b08e4a..38b786bca0 100644
--- a/packages/credentials/credentials/tests/invariant.spec.ts
+++ b/packages/credentials/credentials/tests/invariant.spec.ts
@@ -22,7 +22,7 @@ describe('credentials invariant companion', () => {
     await ctx.plugin(InvariantRegistry)
     await ctx.plugin(CredentialsInvariant)
 
-    expect(() => { ctx.emit('credentials/updated', REF) }).toThrow(/invariant violated by "@deepseek-ai\/dsh-credentials"/)
+    expect(() => { ctx.emit('credentials/reference-updated', REF) }).toThrow(/invariant violated by "@deepseek-ai\/dsh-credentials"/)
   })
 
   it('reserves the package name against duplicate registration', async () => {
diff --git a/packages/credentials/credentials/tests/memory.ts b/packages/credentials/credentials/tests/memory.ts
index 24302ee3f0..9bdf31554f 100644
--- a/packages/credentials/credentials/tests/memory.ts
+++ b/packages/credentials/credentials/tests/memory.ts
@@ -45,13 +45,13 @@ export class MemoryCredentials extends CredentialProvider {
       return Promise.reject(new Error('memory credentials: an empty value cannot be stored; use unset'))
     }
     this.store.set(ref, value)
-    this.ctx.emit('credentials/updated', ref)
+    this.ctx.emit('credentials/reference-updated', ref)
     return Promise.resolve()
   }
 
   override unset(ref: CredentialRef): Promise<void> {
     if (this.store.delete(ref)) {
-      this.ctx.emit('credentials/updated', ref)
+      this.ctx.emit('credentials/reference-updated', ref)
     }
     return Promise.resolve()
   }
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index e520a9217e..c821662e85 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -2553,13 +2553,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     mode: 'emit',
     signature: '\'credentials/record-updated\'(key: CredentialKey): void',
     summary: 'Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage.',
-    description: 'Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/updated`.',
+    description: 'Committed change to a stored credential record: a `modifyRecord` that wrote, a `deleteRecord` that removed, or an external edit observed in storage. Separate from `credentials/reference-updated` because the two key grammars are disjoint — a listener that received both on one event could not tell which space a subject belongs to. Listener failures are contained on the same terms as `credentials/reference-updated`.',
     parameters: [{ name: 'key', description: 'the record whose stored value changed.' }],
   },
   {
-    name: 'credentials/updated',
+    name: 'credentials/reference-updated',
     mode: 'emit',
-    signature: '\'credentials/updated\'(ref: CredentialRef): void',
+    signature: '\'credentials/reference-updated\'(ref: CredentialRef): void',
     summary: 'Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage.',
     description: 'Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation\'s outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.',
     parameters: [{ name: 'ref', description: 'the reference whose stored value changed.' }],
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 25ad8e88a5..362df926c3 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.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 packages/host/apiproxy/README.md
-README.md: a9fb07519c1d8b3b2e2d759bd9138dac60f2306f
-README.zh.md: 9bde3583b0f5e6ce172bfe145f440150aabfa230
+README.md: 4cf11c7ffe55484fd2c27e597931f22f8f861a14
+README.zh.md: df17e296eb5b02420825b736461ed9802adf7a17
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index a9fb07519c..4cf11c7ffe 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -58,7 +58,7 @@ The `agentPreset.list` domain exposes the deployment's preset roster so a browse
 
 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the composer's menu: it returns every user-invocable skill with its `modelInvocable` flag, so menus can mark user-only (`disable-model-invocation`) entries whose only invocation path is the slash gesture. Listing is the skill domain's only RPC — invocation itself is an ordinary `session.prompt` whose whitespace-bounded `/name` tokens `dsh-tool-skill` recognizes at the pre-step boundary and answers with injected `<skill_content>` context, so every entry point (Web, TUI, and ACP) shares one deterministic path—including for hand-typed text—with no dedicated invocation wire. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `commands/change` rides the forwarded-event frame as the registry-wide catalog invalidation signal: clients refetch `command.list` instead of diffing. Forwarded `agent-preset/selected` is its per-session counterpart, emitted from the logged selection commit: recomposing a blank session's agent re-parents its scope without registering anything, so both catalogs that session's composition decides (`command.list`, `skill.list`) go stale with no registry change to announce it.
 
-The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves every registered namespace: a plugin distributed outside this repository becomes browser-configurable by registering its section, with no change here, and this proxy adds no boundary of its own — a name no registration answers folds into the seam's own `settings-rejected`. Which surface renders a namespace is the browser's decision (the plugin configuration page keys its cards on the namespace), never this proxy's. `settings.describe` returns each namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select any filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Invalidations keep every surface converged without polling. `settings/document-updated` and `credentials/updated` ride the verbatim forwarded-event frame (see below), so a raw settings change whose resolved value is unchanged still reaches clients, and a credential invalidation still carries reference names only, never values. `llm/adapters-updated` is forwarded beside `settings/document-updated`; concrete model consumers subscribe to both owner events directly because topology commits and settings documents can independently change their directories. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
+The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves every registered namespace: a plugin distributed outside this repository becomes browser-configurable by registering its section, with no change here, and this proxy adds no boundary of its own — a name no registration answers folds into the seam's own `settings-rejected`. Which surface renders a namespace is the browser's decision (the plugin configuration page keys its cards on the namespace), never this proxy's. `settings.describe` returns each namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select any filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Invalidations keep every surface converged without polling. `settings/document-updated` and `credentials/reference-updated` ride the verbatim forwarded-event frame (see below), so a raw settings change whose resolved value is unchanged still reaches clients, and a credential invalidation still carries reference names only, never values. `llm/adapters-updated` is forwarded beside `settings/document-updated`; concrete model consumers subscribe to both owner events directly because topology commits and settings documents can independently change their directories. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
 ## Carrier layer (`/client` + root)
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 9bde3583b0..df17e296eb 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -58,7 +58,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和 skill（技能）目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的调用路径。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此所有入口（Web、TUI 与 ACP（Agent Client Protocol））共享同一条确定性路径，手动键入的文本也走该路径，且没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`commands/change` 搭乘转发事件帧作为注册表级目录失效信号：客户端重新拉取 `command.list` 而不是做差分。转发的 `agent-preset/selected` 是它按会话粒度的对应物，由落账的选择提交点发出：重组空会话的 agent 只是重新挂接其 scope，不产生任何注册，因此该会话组成所决定的两份目录（`command.list`、`skill.list`）都会失效，却没有任何注册表变化来宣告它。
 
-`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于每一个已注册 namespace：在本仓库之外分发的插件只要注册自己的分节即可变得可从浏览器配置，无需改动这里；本代理也不再自设边界——没有任何注册应答的名字会折叠为 seam 自己的 `settings-rejected`。由哪个界面渲染某个 namespace 是浏览器的决定（插件配置页按 namespace 为其卡片编键），从不由本代理决定。`settings.describe` 为每个 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。失效通知让每个面无需轮询即保持收敛。`settings/document-updated` 与 `credentials/updated` 搭乘原样转发事件帧（见下），因此解析值未变的原始设置变更同样能到达客户端，凭据失效通知也仍然只带引用名、绝不带值。`llm/adapters-updated` 与 `settings/document-updated` 一并原样转发；具体模型消费方直接订阅这两个 owner 事件，因为拓扑提交和设置文档都能独立改变其目录。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据提供方的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
+`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于每一个已注册 namespace：在本仓库之外分发的插件只要注册自己的分节即可变得可从浏览器配置，无需改动这里；本代理也不再自设边界——没有任何注册应答的名字会折叠为 seam 自己的 `settings-rejected`。由哪个界面渲染某个 namespace 是浏览器的决定（插件配置页按 namespace 为其卡片编键），从不由本代理决定。`settings.describe` 为每个 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。失效通知让每个面无需轮询即保持收敛。`settings/document-updated` 与 `credentials/reference-updated` 搭乘原样转发事件帧（见下），因此解析值未变的原始设置变更同样能到达客户端，凭据失效通知也仍然只带引用名、绝不带值。`llm/adapters-updated` 与 `settings/document-updated` 一并原样转发；具体模型消费方直接订阅这两个 owner 事件，因为拓扑提交和设置文档都能独立改变其目录。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据提供方的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
 ## 载体层（`/client` + 根路径）
 
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 3537ed183a..3ba6f3a0af 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -123,7 +123,7 @@ class MemoryCredentials extends CredentialProvider {
       return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
     }
     this.values.set(ref, value)
-    this.ctx.emit('credentials/updated', ref)
+    this.ctx.emit('credentials/reference-updated', ref)
     return Promise.resolve()
   }
 
@@ -132,7 +132,7 @@ class MemoryCredentials extends CredentialProvider {
       return Promise.reject(new Error(`credentials: ${ref} is shadowed by the read-only environment`))
     }
     this.values.delete(ref)
-    this.ctx.emit('credentials/updated', ref)
+    this.ctx.emit('credentials/reference-updated', ref)
     return Promise.resolve()
   }
 
@@ -632,8 +632,8 @@ describe('credentials domain', () => {
       expectOk(await api.credentials.unset(request({ ref: 'OPENAI_API_KEY' })))
     })
     expect(frames).toEqual([
-      { type: 'host/remote-event', event: 'credentials/updated', args: ['OPENAI_API_KEY'] },
-      { type: 'host/remote-event', event: 'credentials/updated', args: ['OPENAI_API_KEY'] },
+      { type: 'host/remote-event', event: 'credentials/reference-updated', args: ['OPENAI_API_KEY'] },
+      { type: 'host/remote-event', event: 'credentials/reference-updated', args: ['OPENAI_API_KEY'] },
     ])
   })
 
diff --git a/packages/test-support/client-runtime/tests/remote.client.spec.ts b/packages/test-support/client-runtime/tests/remote.client.spec.ts
index 3f11c82323..90b1bde56f 100644
--- a/packages/test-support/client-runtime/tests/remote.client.spec.ts
+++ b/packages/test-support/client-runtime/tests/remote.client.spec.ts
@@ -30,7 +30,7 @@ describe('TestRemote', () => {
     new TestRemote(ctx)
     // No subscriber for this name: the emit must be inert rather than throwing,
     // because the wire carries whatever the Host allowlist selected.
-    expect(() => { ctx.remote.$dispatch('credentials/updated', ['DEEPSEEK_API_KEY']) }).not.toThrow()
+    expect(() => { ctx.remote.$dispatch('credentials/reference-updated', ['DEEPSEEK_API_KEY']) }).not.toThrow()
     await ctx.fiber.dispose()
   })
 

From 120097e266c599575cfc651c0b2850c7bbc6a946 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 19 Aug 2026 11:01:34 +0800
Subject: [PATCH 30/34] chore(sync): restore the image-budget README merge on
 llm-pi-ai

---
 packages/llm/llm-pi-ai/README.i18n.yaml |  4 ++--
 packages/llm/llm-pi-ai/README.md        | 13 +++++++------
 packages/llm/llm-pi-ai/README.zh.md     | 13 +++++++------
 3 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 611cc52db3..4e7379cb05 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/README.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 packages/llm/llm-pi-ai/README.md
-README.md: 29b12996208c44328a4bc1fdd237018564f1014d
-README.zh.md: 618e85bb54eec8739bbece1099404801e48522ec
+README.md: 19dbcfa90dbefbe322800c83da6d75c70c849f05
+README.zh.md: 4066564224035561fab4ecd7f64ddb7265855ae6
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 29b1299620..19dbcfa90d 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -8,7 +8,7 @@ The package root exposes the Cordis plugin contract, `PiAiAdapter`, and `support
 
 ## Config
 
-Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
+Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. Each profile may set a `retryPolicy`; omission uses normal mode with five retries. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
 
 ```yaml
 - id: llm
@@ -120,7 +120,7 @@ A model that carries reasoning metadata — from the installed catalog or from i
 
 A model **without** that metadata — a hand-declared one whose entry declares no `reasoningEfforts`, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, `maxRequestImageBytes`, and `retryPolicy`. Each resolved profile retry policy is captured with that provider route; omission uses the shared bounded normal default of five retries. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. `maxRequestImageBytes` bounds one request's base64-encoded image payload (default 20MiB, a positive integer): every image in history is re-encoded into every request, so when the accumulated payload exceeds the bound, the oldest images are replaced by a fixed text placeholder until the request fits, keeping an image-heavy session serviceable instead of permanently rejected by a gateway request-size cap. The default leaves capacity for system prompts, history, tools, and JSON; deployments behind stricter gateways lower it per route. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
@@ -170,15 +170,15 @@ pi-ai installs several provider SDKs and lazy-loads the one selected by the cata
 
 #### What the model sees
 
-The selected catalog model receives `GenerateOptions.system`, history, tools, and sampling fields supported by pi-ai's common streaming API. This package adds no prompt prose. Provider-native replay metadata is restored only when the adapter validates it for the historical content.
+The selected catalog model receives `GenerateOptions.system`, history, tools, and sampling fields supported by pi-ai's common streaming API. This package adds no prompt prose, with one exception: when a request's accumulated base64 image payload exceeds the route's `maxRequestImageBytes`, each offloaded image (oldest first) is replaced by fixed text. The text tells the model to read the file again when a path is available or ask the user to attach the image again. Provider-native replay metadata is restored only when the adapter validates it for the historical content.
 
 #### Token effect
 
-Provider tokenization governs exact input. Conversion adds no model-visible text; replay metadata may let a native API reuse provider-side state.
+Provider tokenization governs exact input. Conversion adds no model-visible text beyond the image-offload placeholder, which replaces the offloaded image's visual tokens with a short fixed sentence; replay metadata may let a native API reuse provider-side state.
 
 #### KV Cache effect
 
-Conversion preserves logical request order without adding text, while the selected provider's serialization and replay state determine reuse. Changing adapter instance, provider, model, or any upstream request token may prevent reuse from the first difference.
+Conversion preserves logical request order without adding text, while the selected provider's serialization and replay state determine reuse. Changing adapter instance, provider, model, or any upstream request token may prevent reuse from the first difference. Crossing the image bound rewrites an early message (the newly offloaded image becomes placeholder text), so reuse ends at that message until the offloaded prefix stabilizes.
 
 ### Provider response
 
@@ -196,6 +196,7 @@ Recorded response content appends to the next request and does not invalidate it
 
 ## Known Limitations and Deferred Work
 
+- **`maxRequestImageBytes` counts base64 image payload only** — text, tools, and JSON structure ride outside the bound, so it must sit below the gateway's request-body cap with headroom. Offload is decided at request conversion as a pure function of history and configuration and is not recorded as a session event; per-route capability metadata (image count, per-image size, total request size) driving admission and assembly together is deferred design work.
 - **A sign-in lives only in the process that started it** — an authorization attempt is not durable, so reloading the page mid-login abandons it and the human starts over. Signing out is `deleteRecord` on the stored record, which forgets it locally without telling the issuer.
 - **Provider-native discovery answers through this plugin's ambient context** — a route naming no credential defers to the catalog provider's own resolution, which asks for environment values (`AZURE_OPENAI_API_KEY`, `AWS_PROFILE`, and each provider's own set) and for local credential files. Both questions are answered here: the credential seam is consulted before the process environment, and file existence is checked against the host process's filesystem with `~` expanded. What it cannot do is *read* a credential file's contents — a provider that parses `~/.aws/credentials` itself does so directly, outside the seam.
 - **Settings can add or override routes, not remove composition routes** — the user layer merges over the composition `base`, so deleting a `cordis.yml`-provided provider is a composition change; `replace` on the namespace only resets the user layer.
@@ -208,4 +209,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step extension point; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may supply nested `retryPolicy`; omission resolves to normal mode with five retries, and the effective route policy is what `dsh-llm-retry` executes at the agent failed-step extension point. pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 618e85bb54..4066564224 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -8,7 +8,7 @@
 
 ## 配置
 
-按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。`apiKeyEnv` 是按请求解析的凭据*引用*，因此机密不进入该文件。省略它会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
+按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。每个 profile 都可以设置 `retryPolicy`；省略时使用 normal 模式并重试五次。`apiKeyEnv` 是按请求解析的凭据*引用*，因此机密不进入该文件。省略它会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
 
 ```yaml
 - id: llm
@@ -121,7 +121,7 @@ pi-ai 依据提供方 id 与 baseURL 决定每个请求的形状：系统提示
 
 **没有**这份元数据的模型——条目未声明 `reasoningEfforts` 的手工声明模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`modelOverrides`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`defaultInput`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
+受支持的 profile 字段是 `apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`modelOverrides`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`defaultInput`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs`、`maxRequestImageBytes` 和 `retryPolicy`。每条 profile 解析后的重试策略会随该提供方路由一同捕获；省略时使用共享的有界 normal 默认值并重试五次。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。`maxRequestImageBytes` 约束单个请求的 base64 编码图片载荷（默认 20MiB，正整数）：历史中的每张图片都会重新编码进每个请求，累积载荷超过上限时，从最老的图片开始替换为固定文本占位，直到请求装得下，使图片较多的会话保持可用，而不是被网关请求体上限永久拒绝。默认值为系统提示词、历史、工具与 JSON 保留请求容量；网关更严格的部署按路由调低该值。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent（智能体）级重试预算。空闲超时会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
@@ -171,15 +171,15 @@ pi-ai 会安装多个提供方 SDK，并延迟加载 catalog 模型所选的 SDK
 
 #### 模型看到的内容
 
-所选 catalog 模型会收到 `GenerateOptions.system`、历史、工具，以及 pi-ai 通用流式 API 支持的采样字段。本包不添加提示词文本。只有当适配器验证提供方原生回放元数据与历史内容匹配时，才会恢复这些元数据。
+所选 catalog 模型会收到 `GenerateOptions.system`、历史、工具，以及 pi-ai 通用流式 API 支持的采样字段。本包不添加提示词文本，仅有一个例外：请求累积的 base64 图片载荷超过路由的 `maxRequestImageBytes` 时，被 offload 的图片（从最老开始）会被替换为一段固定文本。该文本要求模型在有路径时重新读取文件，否则请用户重新附上图片。只有当适配器验证提供方原生回放元数据与历史内容匹配时，才会恢复这些元数据。
 
 #### Token 影响
 
-精确输入取决于提供方 tokenization。转换不添加模型可见文本；回放元数据可能让原生 API 复用提供方侧状态。
+精确输入取决于提供方 tokenization。除图片 offload 占位文本外，转换不添加模型可见文本；占位文本用一句固定短句替代被省略图片的视觉 token。回放元数据可能让原生 API 复用提供方侧状态。
 
 #### KV Cache 影响
 
-转换保留逻辑请求顺序，不添加文本；复用取决于所选提供方的序列化与回放状态。更改适配器实例、提供方、模型或任何上游请求 token，都可能使复用从首个出现差异的 token 起失效。
+转换保留逻辑请求顺序，不添加文本；复用取决于所选提供方的序列化与回放状态。更改适配器实例、提供方、模型或任何上游请求 token，都可能使复用从首个出现差异的 token 起失效。跨过图片上限会改写较早的一条消息（新被 offload 的图片变为占位文本），复用在该消息处截止，直到被 offload 的前缀稳定。
 
 ### 提供方响应
 
@@ -197,6 +197,7 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 
 ## 已知限制与暂缓事项
 
+- **`maxRequestImageBytes` 只统计 base64 图片载荷**：文本、工具与 JSON 结构不计入上限，因此该值必须低于网关请求体上限并留出余量。offload 在请求转换时决定，是历史与配置的纯函数，不记录为会话事件；由按路由能力元数据（图片数量、单图大小、请求总大小）同时驱动准入与组装的完整设计属于暂缓工作。
 - **一次登录只存活于发起它的进程中**：授权尝试不可持久，登录途中刷新页面会丢弃它，人需要重来。登出即对已存储记录执行 `deleteRecord`，它只在本地遗忘而不通知签发方。
 - **提供方自带的凭据发现经由本插件的 ambient context 作答**：不指定凭据的路由交由 catalog 提供方自行解析，它会询问环境值（`AZURE_OPENAI_API_KEY`、`AWS_PROFILE` 以及各提供方自己的那一组）与本地凭据文件是否存在。两类问题都在这里作答：先查凭据 seam 再查进程环境，文件存在性则按宿主进程的文件系统判断并展开 `~`。它做不到的是*读取*凭据文件的内容——自行解析 `~/.aws/credentials` 的提供方是直接读盘的，不经过 seam。
 - **settings 能新增或覆盖路由，但不能移除组合路由**：用户层合并在组合 `base` 之上，因此删除 `cordis.yml` 提供的提供方属于组合变更；对该 namespace 执行 `replace` 只会重置用户层。
@@ -209,4 +210,4 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
-- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤扩展点上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
+- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以提供嵌套的 `retryPolicy`；省略时解析为 normal 模式并重试五次，`dsh-llm-retry` 会在 agent 的失败步骤扩展点上执行有效路由策略。pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。

From 7d04a0235ce9a9cdb4e5ba768458bab1feb6d662 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 19 Aug 2026 12:12:56 +0800
Subject: [PATCH 31/34] chore(sync): regenerate the event matrix after the
 command-envelope merge

---
 docs/event-producer-consumer.i18n.yaml | 4 ++--
 docs/event-producer-consumer.md        | 2 +-
 docs/event-producer-consumer.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 9d71486d57..9aef71c868 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: e507e0e83fa32618393d06bfaa746a3e0b1e4611
-event-producer-consumer.zh.md: 94da41dbe23a870db959f5f878d025158efd2858
+event-producer-consumer.md: d68f92d317dec2fd05813c1ce487bb88c369bd6e
+event-producer-consumer.zh.md: 5b3454e6000f4e1e017cb494423736f2c0f75f31
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index e507e0e83f..d68f92d317 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -23,7 +23,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 94da41dbe2..5b3454e600 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -25,7 +25,7 @@
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:72`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `apiproxy` |

From 933d1f2ab2d99ba2822b2129641ae8b943368195 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 19 Aug 2026 12:57:32 +0800
Subject: [PATCH 32/34] feat(credentials): upgrade the pre-release flat
 document at boot

Internal builds before the versioned layout wrote .credentials.yaml as a flat
mapping; refusing it outright would strand every key stored through the Models
page and fail the next model request. Boot now recognizes exactly that layout
- addressable names over non-empty string scalars, no directives - and
rewrites it under the writer lock, nesting the original lines verbatim under
refs: with the values byte for byte unchanged. Everything the recognizer
declines keeps the loud by-name refusal, a live reload still never migrates,
and the parser continues to read exactly one layout. The migration step
retires with the pre-release stance at the first tagged release.
---
 ...-records-and-authorization-flows.i18n.yaml |   4 +-
 ...dential-records-and-authorization-flows.md |   2 +-
 ...tial-records-and-authorization-flows.zh.md |   2 +-
 .../credentials-local/README.i18n.yaml        |   4 +-
 .../credentials/credentials-local/README.md   |   2 +-
 .../credentials-local/README.zh.md            |   2 +-
 .../credentials-local/src/index.ts            |  76 +++++++++-
 .../credentials-local/tests/local.spec.ts     |  17 ++-
 .../credentials-local/tests/migration.spec.ts | 140 ++++++++++++++++++
 9 files changed, 235 insertions(+), 14 deletions(-)
 create mode 100644 packages/credentials/credentials-local/tests/migration.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
index 999a35f13c..980da73e47 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.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/architecture/2026-08-13-credential-records-and-authorization-flows.md
-2026-08-13-credential-records-and-authorization-flows.md: 19de5a5212e12a678a2162275f26130cf54f4f46
-2026-08-13-credential-records-and-authorization-flows.zh.md: ee79248a8c6ae1d652bb280bb9863c01655715c7
+2026-08-13-credential-records-and-authorization-flows.md: a52d85854c8c660b4965d07a13a2dbfefbac5723
+2026-08-13-credential-records-and-authorization-flows.zh.md: 1b6960cd9cff5e7320816a1528e3c621fea41691
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
index 19de5a5212..a52d85854c 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.md
@@ -51,7 +51,7 @@ Withdrawal settles an attempt whether or not its flow reacts to the signal. A fl
 
 ## Consequences
 
-`.credentials.yaml` gains a version and two sections, and the pre-release flat layout is refused by name with the migration stated in the message — pre-release stance, no compatibility shim. Every fixture in the repo that wrote the flat document was rewritten; the llm suites' fixtures were missed by the record change itself and fixed here.
+`.credentials.yaml` gains a version and two sections. A boot upgrades the recognized pre-release flat layout in place — an all-string flat mapping nests verbatim under `refs:` under the writer lock — because a key stored through the Models page by an earlier internal build must survive the layout change without a hand edit and without its model requests failing. Any flat shape the recognizer cannot prove it understands keeps the by-name refusal with the hand migration stated in the message; the parser itself still reads exactly one layout, and the migration step retires with the pre-release stance at the first tagged release. Every fixture in the repo that wrote the flat document was rewritten; the llm suites' fixtures were missed by the record change itself and fixed here.
 
 `openai-codex` returns to the provider picker and to the Models page directory. Signing in is offered for every installed provider that ships a login, which today is all 38 — 31 collect a key through pi-ai's own prompt, six offer that beside a subscription login, and Codex offers only the subscription login.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
index ee79248a8c..1b6960cd9c 100644
--- a/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-13-credential-records-and-authorization-flows.zh.md
@@ -51,7 +51,7 @@ seam 的边缘与写入路径同一纪律。prompt 被拒是结果而非故障
 
 ## Consequences
 
-`.credentials.yaml` 增加了版本与两个分区，发布前的扁平布局被指名拒绝，迁移办法写在报错信息里——发布前立场，不留兼容垫片。仓库中所有写扁平文档的 fixture 都已改写；llm 各套件的 fixture 被记录改动本身漏掉了，在此补上。
+`.credentials.yaml` 增加了版本与两个分区。启动时会把能精确识别的发布前扁平布局原地升级——全字符串的扁平 mapping 在写锁下逐字下沉到 `refs:` 之下——因为早期内测构建经模型页面存下的密钥必须在布局变更后继续可用，不能要求手工编辑，也不能让模型请求失败。识别器无法证明自己理解的扁平形态仍被指名拒绝，迁移办法写在报错信息里；解析器本身始终只读一种布局，迁移步骤将随发布前立场在首个正式版本时移除。仓库中所有写扁平文档的 fixture 都已改写；llm 各套件的 fixture 被记录改动本身漏掉了，在此补上。
 
 `openai-codex` 回到提供方选择器与 Models 页目录。凡是自带登录的已安装提供方都会得到登录入口，而今天这是全部 38 个——31 个经 pi-ai 自己的提示收取密钥，6 个在此之外还提供订阅登录，Codex 只提供订阅登录。
 
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index b54623d908..df468deda8 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/README.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 packages/credentials/credentials-local/README.md
-README.md: 1b8e4e5d89dc0eb5da2b04b6281c70316262c03b
-README.zh.md: 7ba7726e46a6cd5c6b26a2e55e001a750a0e6dd1
+README.md: 7acd89ea24be4da3d2cecc6efe619e73e05bb823
+README.zh.md: 4b62904af23dd7e907f045e0713abba59c2abba9
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 1b8e4e5d89..7acd89ea24 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -57,7 +57,7 @@ The document holds credentials only, so every deviation is a rejection rather th
 
 A `grant` payload must survive a JSON round trip, enforced in both directions. YAML spells values JSON has none for — `.inf`, alias cycles — and an owner may hand over a `Date` or a `bigint`; either way the store refuses rather than saving something it could not read back exactly as written.
 
-The pre-release layout was a flat mapping with no `version`. It is refused by name, with the entry count and the one edit needed (`version: 1`, nest under `refs:`) — never read as an empty store, which would surface as an authentication failure on the first request instead of at load.
+The pre-release layout was a flat mapping with no `version`. A boot that recognizes it exactly — addressable names over non-empty string scalars, no directives — upgrades the document in place under the writer lock: the original lines nest verbatim under `refs:`, so values, comments, and spellings survive byte for byte. Any other flat shape is refused by name, with the entry count and the one edit needed (`version: 1`, nest under `refs:`) — never read as an empty store, which would surface as an authentication failure on the first request instead of at load. A live reload never migrates: a flat document restored mid-run keeps the last good snapshot until the next boot.
 
 Writes patch the parsed document rather than rebuilding it, so comments and the formatting of every untouched entry survive. A comment directly above an entry is that entry's annotation and is removed with it. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten. An on-disk document that no longer parses fails the write instead of overwriting content the provider could not understand.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 7ba7726e46..4b62904af2 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -57,7 +57,7 @@ records:
 
 `grant` 的 payload 必须能经受 JSON 往返，读写两个方向都强制。YAML 能拼写出 JSON 没有的值——`.inf`、别名环——拥有者也可能递来 `Date` 或 `bigint`；无论哪种，存储都选择拒绝，而不是存下一个自己无法逐字读回的东西。
 
-发布前的旧布局是没有 `version` 的扁平 mapping。它会被指名拒绝，并给出条目数与唯一需要做的编辑（`version: 1`，条目下沉到 `refs:`）——绝不当作空存储读过去，否则它会以第一次请求认证失败的形式出现，而不是在加载时。
+发布前的旧布局是没有 `version` 的扁平 mapping。启动时若能精确识别它——可寻址名称对非空字符串标量、且没有文档指令——就在写锁下原地升级：原有各行逐字下沉到 `refs:` 之下，值、注释与拼写逐字节保留。其余任何扁平形态都会被指名拒绝，并给出条目数与唯一需要做的编辑（`version: 1`，条目下沉到 `refs:`）——绝不当作空存储读过去，否则它会以第一次请求认证失败的形式出现，而不是在加载时。热重载从不迁移：运行中被恢复出来的扁平文档只会保住上一份完好快照，直到下次启动。
 
 写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖提供方读不懂的内容。
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index 20a8313344..9bdece7bc6 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -226,6 +226,45 @@ export function parseCredentialsDocument(text: string, filename: string): Creden
   return { refs: parseRefs(fields['refs'], filename), records: parseRecords(fields['records'], filename) }
 }
 
+/**
+ * Render the version-1 layout for a pre-release flat document, or `undefined`
+ * for anything else. The flat layout is recognized exactly — a non-empty
+ * top-level mapping of addressable reference names to non-empty string
+ * scalars, with no `version` key and no document directives — and the rewrite
+ * nests the original lines verbatim under `refs:` at two spaces' indent, so
+ * comments, blank lines, and each value's spelling survive byte for byte.
+ * Anything the recognizer declines keeps {@link parseCredentialsDocument}'s
+ * loud rejection: a document this build cannot prove it understands is never
+ * rewritten. Remove with the pre-release stance at the first tagged release.
+ * @param text - the document's text.
+ * @returns the migrated text, or `undefined` when the text is not the recognized flat layout.
+ */
+export function renderFlatLayoutMigration(text: string): string | undefined {
+  const document = parseDocument(text, { prettyErrors: true, uniqueKeys: true })
+  if (document.errors.length > 0) return undefined
+  const flat = document.contents
+  if (!isMap(flat) || flat.items.length === 0) return undefined
+  for (const line of text.split('\n')) {
+    // A directive or document marker would not survive being indented into
+    // the `refs:` block; no shipped writer ever emitted one here.
+    if (/^(%|---|\.\.\.)/.test(line)) return undefined
+  }
+  for (const pair of flat.items) {
+    if (!isScalar(pair.key) || typeof pair.key.value !== 'string' || pair.key.value === 'version') return undefined
+    try {
+      credentialRef(pair.key.value)
+    } catch {
+      // Only credentialRef's rejection of a non-POSIX name lands here; the
+      // flat reader refused such a key too, so this is not the recognized
+      // layout and the loud rejection stands.
+      return undefined
+    }
+    if (!isScalar(pair.value) || typeof pair.value.value !== 'string' || pair.value.value.length === 0) return undefined
+  }
+  const body = text.split('\n').map(line => (line.length === 0 ? line : `  ${line}`)).join('\n')
+  return `version: ${DOCUMENT_VERSION}\nrefs:\n${body}${text.endsWith('\n') ? '' : '\n'}`
+}
+
 /** Admit a `refs` section: POSIX-identifier keys over non-empty string values. */
 function parseRefs(section: unknown, filename: string): Map<string, string> {
   const entries = new Map<string, string>()
@@ -764,7 +803,10 @@ export class LocalCredentialProvider extends CredentialProvider {
   /**
    * Boot read: an absent file is an empty store; an invalid one fails the
    * plugin's activation, because a credentials document that exists but
-   * cannot be trusted must never be treated as "no credentials stored".
+   * cannot be trusted must never be treated as "no credentials stored". The
+   * one exception is the recognized pre-release flat layout, which is
+   * upgraded in place first — a key stored by an earlier build must survive
+   * the layout change without a hand edit.
    */
   private async loadInitial(): Promise<void> {
     await assertOwnerOnly(this.spec.filename)
@@ -775,12 +817,44 @@ export class LocalCredentialProvider extends CredentialProvider {
       if (!isENOENT(error)) throw error
       return
     }
+    if (renderFlatLayoutMigration(text) !== undefined) text = await this.migrateFlatDocument()
     const document = parseCredentialsDocument(text, this.spec.filename)
     this.values = document.refs
     this.records = document.records
     this.text = text
   }
 
+  /**
+   * One-shot upgrade of the recognized pre-release flat layout, before the
+   * watcher exists. The rewrite runs under the document's writer lock and
+   * re-reads first — a concurrent boot may have migrated already — and
+   * whatever the re-read finds that is not the flat layout is returned
+   * untouched for the ordinary parse. Values are carried verbatim; only the
+   * enclosing layout changes. Remove with the pre-release stance at the
+   * first tagged release.
+   * @returns the document text this boot should parse.
+   */
+  private async migrateFlatDocument(): Promise<string> {
+    return withFileLock(this.spec.filename, async () => {
+      const current = await readFile(this.spec.filename, 'utf8')
+      const migrated = renderFlatLayoutMigration(current)
+      /* v8 ignore next 2 -- the losing side of the cross-process migration race:
+         another boot rewrote the document between the unlocked recognize and
+         this lock. That interleaving cannot be scheduled deterministically
+         through a whole boot (migration.spec drives it best-effort); the
+         decision itself is the recognizer's covered versioned-document decline. */
+      if (migrated === undefined) return current
+      // 0600: a document holding secrets is never world-readable.
+      await writeFileAtomic(this.spec.filename, migrated, { mode: 0o600, dirMode: 0o700 })
+      this.ctx.logger.info(
+        'credentials-local: migrated %s to the version %d layout; values are unchanged',
+        this.spec.filename,
+        DOCUMENT_VERSION,
+      )
+      return migrated
+    }, { waitMs: DOCUMENT_LOCK_WAIT_MS })
+  }
+
   /* jscpd:ignore-start -- same deliberate mirror of settings-file's reload and
      reconcile policy: warn-and-keep on a reload, throw on a write, invariant
      failures propagate. */
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 2158790b2e..230015fe9d 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -230,12 +230,19 @@ describe('document validation', () => {
   it.each([
     ['a non-mapping root', 'just a string\n', /must be a mapping/],
     ['a sequence root', '- DSH_CRED_TEST\n', /must be a mapping/],
-    // The pre-release layout is refused by name rather than read as an empty
-    // store: a silently ignored document would surface as an authentication
-    // failure on the first request instead of at load.
-    ['the pre-release flat layout', 'DSH_CRED_TEST: stored\n', /nest the existing 1 entry under/],
-    ['the pre-release flat layout with several entries', 'DSH_CRED_TEST: a\nDSH_CRED_OTHER: b\n',
+    // A flat document the boot migration cannot prove it understands is
+    // refused by name rather than read as an empty store or rewritten: a
+    // silently ignored document would surface as an authentication failure on
+    // the first request instead of at load. (The recognized all-string flat
+    // layout upgrades in place instead — migration.spec owns that path.)
+    ['the flat layout with a non-string value', 'DSH_CRED_TEST: [nope]\n', /nest the existing 1 entry under/],
+    ['the flat layout with several entries and a non-string value', 'DSH_CRED_TEST: a\nDSH_CRED_OTHER: [b]\n',
       /nest the existing 2 entries under/],
+    ['the flat layout with an empty value', 'DSH_CRED_TEST: ""\n', /pre-release flat layout/],
+    ['the flat layout with an unaddressable key', 'not-a-ref: value\n', /pre-release flat layout/],
+    ['the flat layout with a non-string key', '1: a\n', /pre-release flat layout/],
+    ['the flat layout under document directives', '%YAML 1.2\n---\nDSH_CRED_TEST: a\n',
+      /pre-release flat layout/],
     ['a future version', 'version: 2\nrefs: {}\n', /this build reads version 1/],
     ['an unknown top-level key', 'version: 1\nsecrets: {}\n', /unknown top-level key "secrets"/],
     ['a non-mapping refs section', 'version: 1\nrefs: nope\n', /"refs" .* must be a mapping/],
diff --git a/packages/credentials/credentials-local/tests/migration.spec.ts b/packages/credentials/credentials-local/tests/migration.spec.ts
new file mode 100644
index 0000000000..30fec951e3
--- /dev/null
+++ b/packages/credentials/credentials-local/tests/migration.spec.ts
@@ -0,0 +1,140 @@
+// One-shot boot upgrade of the pre-release flat layout: a key stored by an
+// earlier build must survive the versioned-document change without a hand
+// edit, byte for byte, while everything the recognizer cannot prove flat
+// keeps the loud rejection local.spec exercises.
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { withFileLock } from '@deepseek-ai/dsh-atomic-write'
+import { LocalCredentialProvider, renderFlatLayoutMigration } from '../src/index.ts'
+
+/** Credential documents are seeded owner-only, exactly as the provider creates them. */
+function writeCredentials(file: string, text: string): Promise<void> {
+  return writeFile(file, text, { mode: 0o600 })
+}
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-cred-migration-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof LocalCredentialProvider>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(LocalCredentialProvider, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+// Every spelling an earlier build accepted: plain, quoted, block-scalar, a
+// comment header, an interior blank line, and a key that happens to spell a
+// section name of the versioned layout.
+const FLAT = [
+  '# keys stored before the versioned layout',
+  'DSH_CRED_TEST: stored',
+  '',
+  '# annotates the quoted entry',
+  "DSH_CRED_OTHER: 'quoted value'",
+  'DSH_CRED_BLOCK: |',
+  '  first line',
+  '  second line',
+  'records: tricky',
+].join('\n') + '\n'
+
+const MIGRATED = [
+  'version: 1',
+  'refs:',
+  '  # keys stored before the versioned layout',
+  '  DSH_CRED_TEST: stored',
+  '',
+  '  # annotates the quoted entry',
+  "  DSH_CRED_OTHER: 'quoted value'",
+  '  DSH_CRED_BLOCK: |',
+  '    first line',
+  '    second line',
+  '  records: tricky',
+].join('\n') + '\n'
+
+describe('flat-layout boot migration', () => {
+  it('upgrades the flat document in place, byte for byte, and serves its keys', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeCredentials(path, FLAT)
+    const ctx = await boot({ path, watch: false })
+    expect(await readFile(path, 'utf8')).toBe(MIGRATED)
+    if (process.platform !== 'win32') expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_TEST'))).toEqual({ value: 'stored', source: 'file' })
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_OTHER')))
+      .toEqual({ value: 'quoted value', source: 'file' })
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_BLOCK')))
+      .toEqual({ value: 'first line\nsecond line\n', source: 'file' })
+    expect(await ctx.credentials.resolve(credentialRef('records'))).toEqual({ value: 'tricky', source: 'file' })
+  })
+
+  it('a second boot reads the migrated document without touching it', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeCredentials(path, FLAT)
+    await boot({ path, watch: false })
+    const ctx = await boot({ path, watch: false })
+    expect(await readFile(path, 'utf8')).toBe(MIGRATED)
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_TEST'))).toEqual({ value: 'stored', source: 'file' })
+  })
+
+  it('yields to a concurrent migrator under the writer lock', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeCredentials(path, FLAT)
+    const winner = 'version: 1\nrefs:\n  DSH_CRED_TEST: winner\n'
+    let release!: () => void
+    const held = new Promise<void>((resolve) => { release = resolve })
+    let acquired!: () => void
+    const holding = new Promise<void>((resolve) => { acquired = resolve })
+    const holder = withFileLock(path, async () => {
+      acquired()
+      await held
+    })
+    await holding
+    // The boot sees the flat text, then waits for the lock; the "other
+    // process" completes the migration in the meantime.
+    const booting = boot({ path, watch: false })
+    await writeCredentials(path, winner)
+    release()
+    await holder
+    const ctx = await booting
+    expect(await readFile(path, 'utf8')).toBe(winner)
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_TEST'))).toEqual({ value: 'winner', source: 'file' })
+  })
+
+  it('leaves an empty flow mapping alone', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeCredentials(path, '{}\n')
+    const ctx = await boot({ path, watch: false })
+    expect(await readFile(path, 'utf8')).toBe('{}\n')
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_TEST'))).toBeUndefined()
+  })
+
+  it('leaves a comment-only document alone', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeCredentials(path, '# nothing stored yet\n')
+    const ctx = await boot({ path, watch: false })
+    expect(await readFile(path, 'utf8')).toBe('# nothing stored yet\n')
+    expect(await ctx.credentials.resolve(credentialRef('DSH_CRED_TEST'))).toBeUndefined()
+  })
+
+  it('renders a final newline for a document that lacks one', () => {
+    expect(renderFlatLayoutMigration('DSH_CRED_TEST: bare')).toBe('version: 1\nrefs:\n  DSH_CRED_TEST: bare\n')
+  })
+})

From 564e4d1610d7ba4f878b09b5a529ee61bbcf843f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 20 Aug 2026 14:53:51 +0800
Subject: [PATCH 33/34] chore(sync): regenerate the module graph after the
 projection merges

---
 docs/module-graph.i18n.yaml |  4 +-
 docs/module-graph.md        | 88 +++++++++++++++++++++++++++----------
 docs/module-graph.zh.md     | 88 +++++++++++++++++++++++++++----------
 3 files changed, 132 insertions(+), 48 deletions(-)

diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index c76d6e283e..4dbba75888 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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 docs/module-graph.md
-module-graph.md: 32459504c815eede558d5f8f6b3aa3c041429341
-module-graph.zh.md: c0aeb8e0c277a76dbb0fc1d361f2d48fc8d46b64
+module-graph.md: f17c65854dbf349adba5ff99288676a4f7eb7402
+module-graph.zh.md: 31608370c550ae7e32e1395e9f6833abf3d096c8
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 32459504c8..f17c65854d 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -125,6 +125,7 @@ flowchart TD
     pkg_client_runtime["client-runtime"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_attachment["client-ui-attachment"]
+    pkg_client_ui_brand_official["client-ui-brand-official"]
     pkg_client_ui_commands["client-ui-commands"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_deliverables["client-ui-deliverables"]
@@ -139,6 +140,7 @@ flowchart TD
     pkg_client_ui_permission_presets["client-ui-permission-presets"]
     pkg_client_ui_plan["client-ui-plan"]
     pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_reference["client-ui-reference"]
     pkg_client_ui_renderer["client-ui-renderer"]
     pkg_client_ui_settings["client-ui-settings"]
     pkg_client_ui_settings_general["client-ui-settings-general"]
@@ -170,6 +172,8 @@ flowchart TD
   end
   subgraph group_context["packages/context"]
     pkg_agent_instructions["agent-instructions"]
+    pkg_file_reference["file-reference"]
+    pkg_file_reference_local["file-reference-local"]
     pkg_session_reference["session-reference"]
     pkg_time_context["time-context"]
     pkg_tmux_context["tmux-context"]
@@ -190,8 +194,8 @@ flowchart TD
     pkg_sdk_jsonrpc_demo["sdk-jsonrpc-demo"]
   end
   subgraph group_experimental["packages/experimental"]
-    pkg_team["team"]
-    pkg_tool_team["tool-team"]
+    pkg_experimental_agent_team["experimental-agent-team"]
+    pkg_experimental_tool_agent_team["experimental-tool-agent-team"]
   end
   subgraph group_extensions["packages/extensions"]
     pkg_client_ui_cordis["client-ui-cordis"]
@@ -290,6 +294,7 @@ flowchart TD
     pkg_tool_bash["tool-bash"]
     pkg_tool_bash_persistent["tool-bash-persistent"]
     pkg_tool_pwsh["tool-pwsh"]
+    pkg_tool_pwsh_persistent["tool-pwsh-persistent"]
   end
   subgraph group_storage["packages/storage"]
     pkg_storage["storage"]
@@ -408,6 +413,7 @@ flowchart TD
   pkg_settings_file --> pkg_invariants
   pkg_settings_file --> pkg_settings
   pkg_llm_deepseek --> pkg_anonymous_user_id
+  pkg_llm_deepseek --> pkg_attachment
   pkg_llm_deepseek --> pkg_credentials
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_launch_environment
@@ -514,6 +520,9 @@ flowchart TD
   pkg_web_search_deepseek --> pkg_web
   pkg_spill_local --> pkg_invariants
   pkg_spill_local --> pkg_spill
+  pkg_file_reference --> pkg_agent
+  pkg_file_reference --> pkg_invariants
+  pkg_file_reference --> pkg_typert_protocol
   pkg_time_context --> pkg_agent
   pkg_time_context --> pkg_invariants
   pkg_time_context --> pkg_session
@@ -567,6 +576,7 @@ flowchart TD
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
   pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_llm
   pkg_session_persistence_sqlite --> pkg_session
   pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
@@ -838,6 +848,11 @@ flowchart TD
   pkg_agent_instructions --> pkg_llm
   pkg_agent_instructions --> pkg_session
   pkg_agent_instructions --> pkg_tools
+  pkg_file_reference_local --> pkg_agent
+  pkg_file_reference_local --> pkg_file_reference
+  pkg_file_reference_local --> pkg_invariants
+  pkg_file_reference_local --> pkg_system_prompt
+  pkg_file_reference_local --> pkg_tools
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compaction
   pkg_session_reference --> pkg_invariants
@@ -845,6 +860,7 @@ flowchart TD
   pkg_session_reference --> pkg_output_retention
   pkg_session_reference --> pkg_session
   pkg_session_reference --> pkg_session_query
+  pkg_session_reference --> pkg_typert_protocol
   pkg_cordis_host_runner --> pkg_agent
   pkg_cordis_host_runner --> pkg_brand
   pkg_cordis_host_runner --> pkg_invariants
@@ -932,6 +948,11 @@ flowchart TD
   pkg_tool_bash_persistent --> pkg_terminal
   pkg_tool_bash_persistent --> pkg_timeout
   pkg_tool_bash_persistent --> pkg_tools
+  pkg_tool_pwsh_persistent --> pkg_agent
+  pkg_tool_pwsh_persistent --> pkg_invariants
+  pkg_tool_pwsh_persistent --> pkg_terminal
+  pkg_tool_pwsh_persistent --> pkg_timeout
+  pkg_tool_pwsh_persistent --> pkg_tools
   pkg_tool_terminal --> pkg_agent
   pkg_tool_terminal --> pkg_invariants
   pkg_tool_terminal --> pkg_jobs
@@ -1016,13 +1037,13 @@ flowchart TD
   pkg_compaction_tool_result_pruner --> pkg_llm
   pkg_compaction_tool_result_pruner --> pkg_session
   pkg_compaction_tool_result_pruner --> pkg_token_meter
-  pkg_team --> pkg_agent
-  pkg_team --> pkg_brand
-  pkg_team --> pkg_invariants
-  pkg_team --> pkg_llm
-  pkg_team --> pkg_session
-  pkg_team --> pkg_session_persistence
-  pkg_team --> pkg_subagent
+  pkg_experimental_agent_team --> pkg_agent
+  pkg_experimental_agent_team --> pkg_brand
+  pkg_experimental_agent_team --> pkg_invariants
+  pkg_experimental_agent_team --> pkg_llm
+  pkg_experimental_agent_team --> pkg_session
+  pkg_experimental_agent_team --> pkg_session_persistence
+  pkg_experimental_agent_team --> pkg_subagent
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
   pkg_tool_cordis --> pkg_invariants
@@ -1034,6 +1055,7 @@ flowchart TD
   pkg_host_apiproxy --> pkg_agent_presets
   pkg_host_apiproxy --> pkg_cordis_host_runner
   pkg_host_apiproxy --> pkg_invariants
+  pkg_host_apiproxy --> pkg_permission_presets
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1121,12 +1143,12 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_jobs
   pkg_agent_spine_demo --> pkg_tool_skill
   pkg_agent_spine_demo --> pkg_tools
-  pkg_tool_team --> pkg_agent
-  pkg_tool_team --> pkg_invariants
-  pkg_tool_team --> pkg_session
-  pkg_tool_team --> pkg_system_prompt
-  pkg_tool_team --> pkg_team
-  pkg_tool_team --> pkg_tools
+  pkg_experimental_tool_agent_team --> pkg_agent
+  pkg_experimental_tool_agent_team --> pkg_experimental_agent_team
+  pkg_experimental_tool_agent_team --> pkg_invariants
+  pkg_experimental_tool_agent_team --> pkg_session
+  pkg_experimental_tool_agent_team --> pkg_system_prompt
+  pkg_experimental_tool_agent_team --> pkg_tools
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1165,6 +1187,7 @@ flowchart TD
   pkg_api_remotes --> pkg_commands
   pkg_api_remotes --> pkg_cordis_host_runner
   pkg_api_remotes --> pkg_credentials
+  pkg_api_remotes --> pkg_file_reference
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_host_plugin_inventory
   pkg_api_remotes --> pkg_invariants
@@ -1172,6 +1195,7 @@ flowchart TD
   pkg_api_remotes --> pkg_message_feedback
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
+  pkg_api_remotes --> pkg_session_reference
   pkg_api_remotes --> pkg_settings
   pkg_api_remotes --> pkg_typert_registry
   pkg_client_runtime --> pkg_agent
@@ -1209,6 +1233,7 @@ flowchart TD
   pkg_client_test_runtime --> pkg_invariants
   pkg_client_ui_input_trigger --> pkg_client_locale
   pkg_client_ui_input_trigger --> pkg_client_runtime
+  pkg_client_ui_input_trigger --> pkg_file_reference
   pkg_client_ui_input_trigger --> pkg_invariants
   pkg_client_ui_settings_models --> pkg_api_remotes
   pkg_client_ui_settings_models --> pkg_client_connection
@@ -1238,6 +1263,14 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
+  pkg_client_ui_reference --> pkg_api_remotes
+  pkg_client_ui_reference --> pkg_client_locale
+  pkg_client_ui_reference --> pkg_client_runtime
+  pkg_client_ui_reference --> pkg_client_ui_input_trigger
+  pkg_client_ui_reference --> pkg_file_reference
+  pkg_client_ui_reference --> pkg_invariants
+  pkg_client_ui_reference --> pkg_session_reference
+  pkg_client_ui_reference --> pkg_typert_protocol
   pkg_cordis_client_runner --> pkg_api_remotes
   pkg_cordis_client_runner --> pkg_client_connection
   pkg_cordis_client_runner --> pkg_client_modules
@@ -1281,6 +1314,10 @@ flowchart TD
   pkg_client_ui_attachment --> pkg_client_runtime
   pkg_client_ui_attachment --> pkg_client_ui_conversation
   pkg_client_ui_attachment --> pkg_invariants
+  pkg_client_ui_brand_official --> pkg_client_runtime
+  pkg_client_ui_brand_official --> pkg_client_ui_conversation
+  pkg_client_ui_brand_official --> pkg_client_ui_sidebar
+  pkg_client_ui_brand_official --> pkg_invariants
   pkg_client_ui_commands --> pkg_api_remotes
   pkg_client_ui_commands --> pkg_client_locale
   pkg_client_ui_commands --> pkg_client_runtime
@@ -1470,7 +1507,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) |
 | [`settings-file`](../packages/settings/settings-file) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
@@ -1497,6 +1534,7 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) |
+| [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
@@ -1507,7 +1545,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
 | [`session-stats`](../packages/session/session-stats) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
@@ -1557,7 +1595,8 @@ flowchart TD
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
+| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
 | [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`tools`](../packages/core/tools) |
 | [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -1574,6 +1613,7 @@ flowchart TD
 | [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`invariants`](../packages/runtime-diagnostics/invariants), [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
 | [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
@@ -1588,9 +1628,9 @@ flowchart TD
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`team`](../packages/experimental/team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
+| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
 | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1601,29 +1641,31 @@ flowchart TD
 | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
-| [`tool-team`](../packages/experimental/tool-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`team`](../packages/experimental/team), [`tools`](../packages/core/tools) |
+| [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
 | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-title`](../packages/session/session-title), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`client-runtime`](../packages/client/runtime), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-slots`](../packages/client/ui-slots), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-settings`](../packages/client/ui-settings), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-layout`](../packages/client/ui-layout), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index c0aeb8e0c2..31608370c5 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -127,6 +127,7 @@ flowchart TD
     pkg_client_runtime["client-runtime"]
     pkg_client_ui_agent_preset["client-ui-agent-preset"]
     pkg_client_ui_attachment["client-ui-attachment"]
+    pkg_client_ui_brand_official["client-ui-brand-official"]
     pkg_client_ui_commands["client-ui-commands"]
     pkg_client_ui_conversation["client-ui-conversation"]
     pkg_client_ui_deliverables["client-ui-deliverables"]
@@ -141,6 +142,7 @@ flowchart TD
     pkg_client_ui_permission_presets["client-ui-permission-presets"]
     pkg_client_ui_plan["client-ui-plan"]
     pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_reference["client-ui-reference"]
     pkg_client_ui_renderer["client-ui-renderer"]
     pkg_client_ui_settings["client-ui-settings"]
     pkg_client_ui_settings_general["client-ui-settings-general"]
@@ -172,6 +174,8 @@ flowchart TD
   end
   subgraph group_context["packages/context"]
     pkg_agent_instructions["agent-instructions"]
+    pkg_file_reference["file-reference"]
+    pkg_file_reference_local["file-reference-local"]
     pkg_session_reference["session-reference"]
     pkg_time_context["time-context"]
     pkg_tmux_context["tmux-context"]
@@ -192,8 +196,8 @@ flowchart TD
     pkg_sdk_jsonrpc_demo["sdk-jsonrpc-demo"]
   end
   subgraph group_experimental["packages/experimental"]
-    pkg_team["team"]
-    pkg_tool_team["tool-team"]
+    pkg_experimental_agent_team["experimental-agent-team"]
+    pkg_experimental_tool_agent_team["experimental-tool-agent-team"]
   end
   subgraph group_extensions["packages/extensions"]
     pkg_client_ui_cordis["client-ui-cordis"]
@@ -292,6 +296,7 @@ flowchart TD
     pkg_tool_bash["tool-bash"]
     pkg_tool_bash_persistent["tool-bash-persistent"]
     pkg_tool_pwsh["tool-pwsh"]
+    pkg_tool_pwsh_persistent["tool-pwsh-persistent"]
   end
   subgraph group_storage["packages/storage"]
     pkg_storage["storage"]
@@ -410,6 +415,7 @@ flowchart TD
   pkg_settings_file --> pkg_invariants
   pkg_settings_file --> pkg_settings
   pkg_llm_deepseek --> pkg_anonymous_user_id
+  pkg_llm_deepseek --> pkg_attachment
   pkg_llm_deepseek --> pkg_credentials
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_launch_environment
@@ -516,6 +522,9 @@ flowchart TD
   pkg_web_search_deepseek --> pkg_web
   pkg_spill_local --> pkg_invariants
   pkg_spill_local --> pkg_spill
+  pkg_file_reference --> pkg_agent
+  pkg_file_reference --> pkg_invariants
+  pkg_file_reference --> pkg_typert_protocol
   pkg_time_context --> pkg_agent
   pkg_time_context --> pkg_invariants
   pkg_time_context --> pkg_session
@@ -569,6 +578,7 @@ flowchart TD
   pkg_session_persistence_jsonl --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session_persistence
   pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_llm
   pkg_session_persistence_sqlite --> pkg_session
   pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
@@ -840,6 +850,11 @@ flowchart TD
   pkg_agent_instructions --> pkg_llm
   pkg_agent_instructions --> pkg_session
   pkg_agent_instructions --> pkg_tools
+  pkg_file_reference_local --> pkg_agent
+  pkg_file_reference_local --> pkg_file_reference
+  pkg_file_reference_local --> pkg_invariants
+  pkg_file_reference_local --> pkg_system_prompt
+  pkg_file_reference_local --> pkg_tools
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compaction
   pkg_session_reference --> pkg_invariants
@@ -847,6 +862,7 @@ flowchart TD
   pkg_session_reference --> pkg_output_retention
   pkg_session_reference --> pkg_session
   pkg_session_reference --> pkg_session_query
+  pkg_session_reference --> pkg_typert_protocol
   pkg_cordis_host_runner --> pkg_agent
   pkg_cordis_host_runner --> pkg_brand
   pkg_cordis_host_runner --> pkg_invariants
@@ -934,6 +950,11 @@ flowchart TD
   pkg_tool_bash_persistent --> pkg_terminal
   pkg_tool_bash_persistent --> pkg_timeout
   pkg_tool_bash_persistent --> pkg_tools
+  pkg_tool_pwsh_persistent --> pkg_agent
+  pkg_tool_pwsh_persistent --> pkg_invariants
+  pkg_tool_pwsh_persistent --> pkg_terminal
+  pkg_tool_pwsh_persistent --> pkg_timeout
+  pkg_tool_pwsh_persistent --> pkg_tools
   pkg_tool_terminal --> pkg_agent
   pkg_tool_terminal --> pkg_invariants
   pkg_tool_terminal --> pkg_jobs
@@ -1018,13 +1039,13 @@ flowchart TD
   pkg_compaction_tool_result_pruner --> pkg_llm
   pkg_compaction_tool_result_pruner --> pkg_session
   pkg_compaction_tool_result_pruner --> pkg_token_meter
-  pkg_team --> pkg_agent
-  pkg_team --> pkg_brand
-  pkg_team --> pkg_invariants
-  pkg_team --> pkg_llm
-  pkg_team --> pkg_session
-  pkg_team --> pkg_session_persistence
-  pkg_team --> pkg_subagent
+  pkg_experimental_agent_team --> pkg_agent
+  pkg_experimental_agent_team --> pkg_brand
+  pkg_experimental_agent_team --> pkg_invariants
+  pkg_experimental_agent_team --> pkg_llm
+  pkg_experimental_agent_team --> pkg_session
+  pkg_experimental_agent_team --> pkg_session_persistence
+  pkg_experimental_agent_team --> pkg_subagent
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
   pkg_tool_cordis --> pkg_invariants
@@ -1036,6 +1057,7 @@ flowchart TD
   pkg_host_apiproxy --> pkg_agent_presets
   pkg_host_apiproxy --> pkg_cordis_host_runner
   pkg_host_apiproxy --> pkg_invariants
+  pkg_host_apiproxy --> pkg_permission_presets
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1123,12 +1145,12 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_jobs
   pkg_agent_spine_demo --> pkg_tool_skill
   pkg_agent_spine_demo --> pkg_tools
-  pkg_tool_team --> pkg_agent
-  pkg_tool_team --> pkg_invariants
-  pkg_tool_team --> pkg_session
-  pkg_tool_team --> pkg_system_prompt
-  pkg_tool_team --> pkg_team
-  pkg_tool_team --> pkg_tools
+  pkg_experimental_tool_agent_team --> pkg_agent
+  pkg_experimental_tool_agent_team --> pkg_experimental_agent_team
+  pkg_experimental_tool_agent_team --> pkg_invariants
+  pkg_experimental_tool_agent_team --> pkg_session
+  pkg_experimental_tool_agent_team --> pkg_system_prompt
+  pkg_experimental_tool_agent_team --> pkg_tools
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1167,6 +1189,7 @@ flowchart TD
   pkg_api_remotes --> pkg_commands
   pkg_api_remotes --> pkg_cordis_host_runner
   pkg_api_remotes --> pkg_credentials
+  pkg_api_remotes --> pkg_file_reference
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_host_plugin_inventory
   pkg_api_remotes --> pkg_invariants
@@ -1174,6 +1197,7 @@ flowchart TD
   pkg_api_remotes --> pkg_message_feedback
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
+  pkg_api_remotes --> pkg_session_reference
   pkg_api_remotes --> pkg_settings
   pkg_api_remotes --> pkg_typert_registry
   pkg_client_runtime --> pkg_agent
@@ -1211,6 +1235,7 @@ flowchart TD
   pkg_client_test_runtime --> pkg_invariants
   pkg_client_ui_input_trigger --> pkg_client_locale
   pkg_client_ui_input_trigger --> pkg_client_runtime
+  pkg_client_ui_input_trigger --> pkg_file_reference
   pkg_client_ui_input_trigger --> pkg_invariants
   pkg_client_ui_settings_models --> pkg_api_remotes
   pkg_client_ui_settings_models --> pkg_client_connection
@@ -1240,6 +1265,14 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
+  pkg_client_ui_reference --> pkg_api_remotes
+  pkg_client_ui_reference --> pkg_client_locale
+  pkg_client_ui_reference --> pkg_client_runtime
+  pkg_client_ui_reference --> pkg_client_ui_input_trigger
+  pkg_client_ui_reference --> pkg_file_reference
+  pkg_client_ui_reference --> pkg_invariants
+  pkg_client_ui_reference --> pkg_session_reference
+  pkg_client_ui_reference --> pkg_typert_protocol
   pkg_cordis_client_runner --> pkg_api_remotes
   pkg_cordis_client_runner --> pkg_client_connection
   pkg_cordis_client_runner --> pkg_client_modules
@@ -1283,6 +1316,10 @@ flowchart TD
   pkg_client_ui_attachment --> pkg_client_runtime
   pkg_client_ui_attachment --> pkg_client_ui_conversation
   pkg_client_ui_attachment --> pkg_invariants
+  pkg_client_ui_brand_official --> pkg_client_runtime
+  pkg_client_ui_brand_official --> pkg_client_ui_conversation
+  pkg_client_ui_brand_official --> pkg_client_ui_sidebar
+  pkg_client_ui_brand_official --> pkg_invariants
   pkg_client_ui_commands --> pkg_api_remotes
   pkg_client_ui_commands --> pkg_client_locale
   pkg_client_ui_commands --> pkg_client_runtime
@@ -1472,7 +1509,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) |
 | [`settings-file`](../packages/settings/settings-file) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`attachment`](../packages/attachment/attachment), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
@@ -1499,6 +1536,7 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) |
+| [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
 | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) |
 | [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
@@ -1509,7 +1547,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
 | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
 | [`session-stats`](../packages/session/session-stats) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) |
@@ -1559,7 +1597,8 @@ flowchart TD
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
+| [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) | `extensions` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol) |
 | [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`tools`](../packages/core/tools) |
 | [`tool-call-timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -1576,6 +1615,7 @@ flowchart TD
 | [`pwsh-sandbox`](../packages/shell/pwsh-sandbox) | `shell` | [`invariants`](../packages/runtime-diagnostics/invariants), [`pwsh-local`](../packages/shell/pwsh-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell) |
 | [`shell-env`](../packages/shell/shell-env) | `shell` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-persistence`](../packages/session/session-persistence), [`shell`](../packages/shell/shell), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/shell/tool-bash-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
@@ -1590,9 +1630,9 @@ flowchart TD
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`team`](../packages/experimental/team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
+| [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent) |
 | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1603,29 +1643,31 @@ flowchart TD
 | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
-| [`tool-team`](../packages/experimental/tool-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`team`](../packages/experimental/team), [`tools`](../packages/core/tools) |
+| [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) |
 | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`typert-registry`](../packages/typert/registry) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-title`](../packages/session/session-title), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`client-runtime`](../packages/client/runtime), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-slots`](../packages/client/ui-slots), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/runtime-diagnostics/invariants) |
-| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol) |
 | [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`client-runtime`](../packages/client/runtime), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-settings`](../packages/client/ui-settings), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-layout`](../packages/client/ui-layout), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants) |
+| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |

From 30289d632083d76eb6e4e0aa07563e1b0fb993d4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 20 Aug 2026 14:57:39 +0800
Subject: [PATCH 34/34] chore(release): carry dsh-authorization to the rc.8
 family version

---
 packages/credentials/authorization/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/credentials/authorization/package.json b/packages/credentials/authorization/package.json
index 9110e37c99..49527385e2 100644
--- a/packages/credentials/authorization/package.json
+++ b/packages/credentials/authorization/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-authorization",
   "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "publishConfig": {
     "access": "public"
   },