Merge remote-tracking branch 'origin/main' into pr888-nested-gate

fix: match the release archive directory literally, not as a regex
release_version was interpolated into an awk regex, where '.' matches any character. Version 1.0.1-beta.1 therefore also admitted .changes/released/1x0x1-betaX1/, letting the archive drift from the CHANGELOG version while every other seal assertion still passed and breaking the documented audit trail. Compare the archive prefix with index() and split the basename off with substr(), matching the literal-comparison idiom already used throughout check-changelog-pr.sh. Only the basename, whose character class is fixed, stays a pattern.
2026-08-12 13:53:37 +08:00 · 2026-08-12 13:52:25 +08:00 · 2026-08-12 12:18:58 +08:00 · 2026-08-12 12:07:07 +08:00 · 2026-08-12 12:01:38 +08:00 · 2026-08-12 12:00:42 +08:00
278 changed files with 47283 additions and 2615 deletions
@@ -0,0 +1,34 @@
+# Release fragments
+
+普通功能、修复和面向用户的行为变更不要再修改根目录 `CHANGELOG.md` 的
+`Unreleased` 区域。每个 PR 在本目录新增一个独立的 Markdown fragment，避免
+并行 PR 争用同一文件。
+
+文件名使用能唯一定位变更的短名，通常是 PR 号，例如
+`1234-chat-reply-mentions.md`。文件名必须匹配
+`^[a-z0-9][a-z0-9._-]*\.md$`，且必须是普通文件，不能是符号链接。本目录顶层
+只接受 `README.md`、`released/` 和符合该规则的 fragment：fragment 一律平铺在
+顶层，不接受任何其它子目录，本目录自身也不能被替换成文件或符号链接。其余条目
+会被 CI 直接拒绝而不是忽略，以免非法条目跳过校验后拖垮下一个 PR。文件格式
+严格如下：
+
+```markdown
+---
+category: Added
+---
+
+- **Chat reply mentions** (#1234) — supports mentioning selected members.
+```
+
+`category` 只能是 `Added`、`Changed`、`Deprecated`、`Removed`、`Fixed` 或
+`Security`。正文至少包含一个 Markdown 列表项，且不得包含 `TODO` 或 `TBD`。
+
+发布 beta 时，`scripts/release/prepare-changelog.sh` 会按分类和文件名稳定排序，
+将未归档 fragments 汇总为唯一的版本章节，并移动到
+`.changes/released/<version>/`。因此 release-seal PR 是唯一会修改
+`CHANGELOG.md` 的 PR；它同时归档已消费的 fragments，供审计追溯。
+归档只能在同一个 release-seal PR 中以原样移动完成；CI 会拒绝直接修改、
+删除或重写已归档文件。
+
+无需面向用户发布说明的改动不添加 fragment。评审者根据改动是否可见来判断该
+例外是否成立。
@@ -19,8 +19,10 @@ repeat the entire CI suite locally only to fill this checklist: CI expands the
 selected tier from documentation checks, through affected-package tests, to
 the complete high-risk suite.

- [ ] Exact in-place `CHANGELOG.md`-only check (otherwise `N/A`):
-  `./scripts/policy/check-changelog-pr.sh --fast-path "$(git merge-base HEAD origin/main)" HEAD`
+- [ ] Release fragment added for a user-visible behavior/interface change (otherwise `N/A`):
+  `.changes/<unique-name>.md`; ordinary PRs must not edit `CHANGELOG.md`.
+- [ ] Release-seal validation (otherwise `N/A`):
+  `./scripts/policy/check-changelog-pr.sh --content-only "$(git merge-base HEAD origin/main)" HEAD`
 - [ ] Targeted test/check commands and results:
 - [ ] Behavior evidence (test name, CLI output shape, or before/after result):
 - [ ] Documentation links/content/rendering checked (documentation-only, otherwise
@@ -1288,6 +1288,12 @@ jobs:
          ./scripts/policy/check-changelog-pr.sh \
            "$mode" "$PR_BASE_SHA" HEAD

+      - name: Validate release fragment lifecycle
+        if: github.event_name == 'pull_request'
+        env:
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: ./scripts/policy/check-release-fragments.sh "$PR_BASE_SHA" HEAD
+
      - name: Validate trusted main CHANGELOG-only push
        if: github.event_name == 'push' && needs.lint.outputs.changelog_only == 'true'
        env:
@@ -1,14 +1,17 @@
 name: PR Eval Dispatch

-# `/eval <products> [sha=<full-head-sha>] [cases=<ref>]` PR 评论 → 触发内网评测流水线，报告由内网 bot 回贴。
+# `/eval <products> [sha=<full-head-sha>] [cases=<ref>]` PR 评论 → 生成可验证的评测请求，报告由 bot 回贴。
 # 本 workflow 只在默认分支上下文运行，不 checkout、不执行 PR 代码。
 # 审核 SHA 规则：评测他人 PR 必须显式携带 sha=（审阅背书凭据，验证
 # 其恰为当前 open head）；评测自己创建的 PR 可省略，自动钉住派发时刻
-# 的当前 head（作者自背书，无第三方偷换窗口）；内网 CI 另以
+# 的当前 head（作者自背书，无第三方偷换窗口）；受控评测执行端另以
 # FETCH_HEAD 校验兜底派发后的变更。
 # 授权两级：仓库 write/maintain/admin 可派发任意 PR；默认分支
 # .github/eval-allowlist.txt 名单内的用户仅可派发自己创建的 PR。
-# 触发通道与凭证全部经 secrets 注入，文件内不出现任何内网信息。
+# 触发通道：workflow 先创建占位评论，再上传与本次 run/comment 绑定的
+# 不可变 manifest artifact，最后把 artifact 指针写回同一评论。评论仅是
+# 不可信通知；受控评测服务必须验证成功 run、artifact 与 manifest，并在
+# 触发评测前原子占用 manifest.idempotency_key，重复占用只能 no-op。

 on:
  issue_comment:
@@ -31,8 +34,8 @@ jobs:
    timeout-minutes: 5
    permissions:
      contents: read
-      issues: write
-      pull-requests: read
+      # 该 job 仅处理 PR；评论写入也限定在 PR Conversation 这一权限域。
+      pull-requests: write
    steps:
      - name: Check out default branch tooling
        uses: actions/checkout@v4
@@ -66,12 +69,10 @@ jobs:
          PARSE_ERROR: ${{ steps.parse.outputs.error }}
        run: |
          body="❌ /eval 命令解析失败：${PARSE_ERROR}"
-          jq -n --arg body "$body" '{body: $body}' | curl --fail --silent --show-error \
-            -X POST \
-            -H "Authorization: Bearer ${GH_TOKEN}" \
-            -H "Accept: application/vnd.github+json" \
-            --data @- \
-            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null
+          gh api --method POST \
+            "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+            --raw-field body="$body" \
+            > /dev/null
          exit 1

      - name: Verify reviewed PR head
@@ -91,49 +92,205 @@ jobs:
            | python3 scripts/ci/eval_dispatch_guard.py head \
            >> "$GITHUB_OUTPUT"

-      - name: Trigger internal evaluation pipeline
-        env:
-          EVAL_TRIGGER_TOKEN: ${{ secrets.EVAL_TRIGGER_TOKEN }}
-          EVAL_TRIGGER_URL: ${{ secrets.EVAL_TRIGGER_URL }}
-          PR_NUMBER: ${{ github.event.issue.number }}
-          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          PRODUCTS: ${{ steps.parse.outputs.products }}
-          CASES_REF: ${{ steps.parse.outputs.cases_ref }}
-        run: |
-          if [ -z "$EVAL_TRIGGER_TOKEN" ] || [ -z "$EVAL_TRIGGER_URL" ]; then
-            echo "EVAL_TRIGGER_URL / EVAL_TRIGGER_TOKEN not configured; cannot dispatch." >&2
-            exit 1
-          fi
-          jq -n \
-            --arg pr "$PR_NUMBER" \
-            --arg sha "$PR_HEAD_SHA" \
-            --arg products "$PRODUCTS" \
-            --arg cases "$CASES_REF" \
-            '{branch: "main", params: {pr_number: $pr, pr_head_sha: $sha, products: $products, cases_ref: $cases}}' \
-          | curl --fail --silent --show-error \
-            -X POST \
-            -H "private-token: ${EVAL_TRIGGER_TOKEN}" \
-            -H "Content-Type: application/json" \
-            --data @- \
-            "$EVAL_TRIGGER_URL"
-          echo "Internal evaluation dispatched."
-
-      - name: Acknowledge on PR
+      - name: Create dispatch placeholder
+        id: placeholder
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+          placeholder_body="🛰️ /eval 请求已通过权限与版本校验，正在生成可验证的评测请求。"
+          response="$(
+            gh api --method POST \
+              "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+              --raw-field body="$placeholder_body"
+          )"
+          comment_id="$(
+            printf '%s' "$response" \
+              | jq -er \
+                --arg issue_url "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}" \
+                'select(.issue_url == $issue_url) | .id | tostring | select(test("^[1-9][0-9]*$"))'
+          )"
+          printf 'comment_id=%s\n' "$comment_id" >> "$GITHUB_OUTPUT"
+
+      - name: Build dispatch request manifest
+        env:
+          REPOSITORY_ID: '1187709537'
+          REPOSITORY: ${{ github.repository }}
+          WORKFLOW_ID: '331725458'
+          WORKFLOW_PATH: .github/workflows/eval-dispatch.yml
+          RUN_ID: ${{ github.run_id }}
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+          SOURCE_COMMENT_ID: ${{ github.event.comment.id }}
+          DISPATCH_COMMENT_ID: ${{ steps.placeholder.outputs.comment_id }}
+          ACTOR_ID: ${{ github.event.comment.user.id }}
+          ACTOR_LOGIN: ${{ github.event.comment.user.login }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          PRODUCTS: ${{ steps.parse.outputs.products }}
+          CASES_REF: ${{ steps.parse.outputs.cases_ref }}
+          SOURCE_BODY: ${{ github.event.comment.body }}
+          MANIFEST_PATH: ${{ runner.temp }}/eval-dispatch-request.json
+        run: |
+          set -euo pipefail
+          if [ "$REPOSITORY" != "DingTalk-Real-AI/dingtalk-workspace-cli" ]; then
+            echo "unexpected repository: ${REPOSITORY}" >&2
+            exit 1
+          fi
+          for value in \
+            "$REPOSITORY_ID" \
+            "$WORKFLOW_ID" \
+            "$RUN_ID" \
+            "$RUN_ATTEMPT" \
+            "$SOURCE_COMMENT_ID" \
+            "$DISPATCH_COMMENT_ID" \
+            "$ACTOR_ID" \
+            "$PR_NUMBER"; do
+            if [[ ! "$value" =~ ^[1-9][0-9]*$ ]]; then
+              echo "dispatch manifest contains a non-canonical identifier" >&2
+              exit 1
+            fi
+          done
+          if [[ ! "$PR_HEAD_SHA" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "dispatch manifest contains an invalid PR head SHA" >&2
+            exit 1
+          fi
+
+          hash_output="$(printf '%s' "$SOURCE_BODY" | sha256sum)"
+          source_body_sha256="${hash_output%% *}"
+          if [[ ! "$source_body_sha256" =~ ^[0-9a-f]{64}$ ]]; then
+            echo "failed to hash source comment" >&2
+            exit 1
+          fi
+          idempotency_key="${REPOSITORY_ID}:${SOURCE_COMMENT_ID}"
+
+          umask 077
+          jq -n \
+            --arg repository_id "$REPOSITORY_ID" \
+            --arg repository "$REPOSITORY" \
+            --arg workflow_id "$WORKFLOW_ID" \
+            --arg workflow_path "$WORKFLOW_PATH" \
+            --arg run_id "$RUN_ID" \
+            --arg run_attempt "$RUN_ATTEMPT" \
+            --arg source_comment_id "$SOURCE_COMMENT_ID" \
+            --arg dispatch_comment_id "$DISPATCH_COMMENT_ID" \
+            --arg actor_id "$ACTOR_ID" \
+            --arg actor_login "$ACTOR_LOGIN" \
+            --arg pr_number "$PR_NUMBER" \
+            --arg pr_head_sha "$PR_HEAD_SHA" \
+            --arg products "$PRODUCTS" \
+            --arg cases_ref "$CASES_REF" \
+            --arg source_body_sha256 "$source_body_sha256" \
+            --arg idempotency_key "$idempotency_key" \
+            '{
+              schema_version: 1,
+              repository_id: $repository_id,
+              repository: $repository,
+              workflow_id: $workflow_id,
+              workflow_path: $workflow_path,
+              run_id: $run_id,
+              run_attempt: $run_attempt,
+              source_comment_id: $source_comment_id,
+              dispatch_comment_id: $dispatch_comment_id,
+              actor_id: $actor_id,
+              actor_login: $actor_login,
+              pr_number: $pr_number,
+              pr_head_sha: $pr_head_sha,
+              products: $products,
+              cases_ref: $cases_ref,
+              source_body_sha256: $source_body_sha256,
+              idempotency_key: $idempotency_key
+            }' > "$MANIFEST_PATH"
+
+      - name: Upload dispatch request manifest
+        id: artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-dispatch-request-${{ github.run_id }}-${{ github.run_attempt }}-${{ steps.placeholder.outputs.comment_id }}
+          path: ${{ runner.temp }}/eval-dispatch-request.json
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: false
+
+      - name: Finalize dispatch marker
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DISPATCH_COMMENT_ID: ${{ steps.placeholder.outputs.comment_id }}
+          REPOSITORY_ID: '1187709537'
+          WORKFLOW_ID: '331725458'
+          WORKFLOW_PATH: .github/workflows/eval-dispatch.yml
+          RUN_ID: ${{ github.run_id }}
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+          ARTIFACT_ID: ${{ steps.artifact.outputs.artifact-id }}
+          ARTIFACT_DIGEST: ${{ steps.artifact.outputs.artifact-digest }}
          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
          PRODUCTS: ${{ steps.parse.outputs.products }}
          CASES_REF: ${{ steps.parse.outputs.cases_ref }}
        run: |
+          set -euo pipefail
+          if [[ ! "$DISPATCH_COMMENT_ID" =~ ^[1-9][0-9]*$ ]] || \
+             [[ ! "$ARTIFACT_ID" =~ ^[1-9][0-9]*$ ]]; then
+            echo "artifact marker contains a non-canonical identifier" >&2
+            exit 1
+          fi
+
+          artifact_digest="${ARTIFACT_DIGEST,,}"
+          if [[ "$artifact_digest" != sha256:* ]]; then
+            artifact_digest="sha256:${artifact_digest}"
+          fi
+          if [[ ! "$artifact_digest" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+            echo "artifact marker contains an invalid digest" >&2
+            exit 1
+          fi
+
+          marker_json="$(
+            jq -nc \
+              --arg repository_id "$REPOSITORY_ID" \
+              --arg workflow_id "$WORKFLOW_ID" \
+              --arg workflow_path "$WORKFLOW_PATH" \
+              --arg run_id "$RUN_ID" \
+              --arg run_attempt "$RUN_ATTEMPT" \
+              --arg dispatch_comment_id "$DISPATCH_COMMENT_ID" \
+              --arg artifact_id "$ARTIFACT_ID" \
+              --arg artifact_digest "$artifact_digest" \
+              '{
+                schema_version: 1,
+                repository_id: $repository_id,
+                workflow_id: $workflow_id,
+                workflow_path: $workflow_path,
+                run_id: $run_id,
+                run_attempt: $run_attempt,
+                dispatch_comment_id: $dispatch_comment_id,
+                artifact_id: $artifact_id,
+                artifact_digest: $artifact_digest
+              }'
+          )"
          cases_note=""
          if [ -n "$CASES_REF" ]; then
            cases_note="，用例版本 \`${CASES_REF}\`"
          fi
-          body="🛰️ /eval 已受理：产品集 \`${PRODUCTS}\`${cases_note}，评测对象 \`${PR_HEAD_SHA}\`。内网评测流水线运行结束后将由 bot 回贴报告（首行为基线对比头条）。"
-          jq -n --arg body "$body" '{body: $body}' | curl --fail --silent --show-error \
-            -X POST \
-            -H "Authorization: Bearer ${GH_TOKEN}" \
-            -H "Accept: application/vnd.github+json" \
-            --data @- \
-            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null
+          body="<!-- eval-dispatch: ${marker_json} -->"$'\n'"🛰️ /eval 已受理：产品集 \`${PRODUCTS}\`${cases_note}，评测对象 \`${PR_HEAD_SHA}\`。"$'\n'"受控评测服务将在数分钟内处理，完成后由 bot 回贴报告。"
+          response="$(
+            gh api --method PATCH \
+              "repos/${GITHUB_REPOSITORY}/issues/comments/${DISPATCH_COMMENT_ID}" \
+              --raw-field body="$body"
+          )"
+          printf '%s' "$response" \
+            | jq -e \
+              --arg comment_id "$DISPATCH_COMMENT_ID" \
+              --arg body "$body" \
+              '((.id | tostring) == $comment_id) and (.body == $body)' \
+              > /dev/null
+
+      - name: Mark dispatch preparation failure
+        if: ${{ failure() && steps.placeholder.outputs.comment_id != '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DISPATCH_COMMENT_ID: ${{ steps.placeholder.outputs.comment_id }}
+        run: |
+          failure_body="❌ /eval 请求准备失败，未生成可消费的评测请求。请稍后重试。"
+          gh api --method PATCH \
+            "repos/${GITHUB_REPOSITORY}/issues/comments/${DISPATCH_COMMENT_ID}" \
+            --raw-field body="$failure_body" \
+            > /dev/null \
+            || true
@@ -2793,7 +2793,7 @@ jobs:
            fi
            if test "${{ needs.dispatch-contract.outputs.mode }}" = plan_release; then
              echo
-              echo "Plan only: no tag or package was created. Add the exact \`CHANGELOG.md\` section, merge it to main, then run publish."
+              echo "Plan only: no tag or package was created. Render pending \`.changes/*.md\` fragments into the exact \`CHANGELOG.md\` section, merge the release-seal PR to main, then run publish."
            fi
          } >> "$GITHUB_STEP_SUMMARY"

@@ -464,6 +464,134 @@ Keep CLI confirmation behavior and Schema metadata consistent, and add a
 semantic regression test through the final embedded loader/query delivery
 path; a generator unit test or JSON count alone is insufficient.

+## Unified result Schema and performance
+
+The unified runtime envelope and the per-command Schema result declaration are
+related but distinct contracts:
+
+- Runtime owns the outer machine envelope (`ok`, `outcome`, `data`, `error`,
+  `meta`) and derives it through `internal/output`. Business commands return a
+  `CommandResult`; they must not hand-author the outer JSON shape.
+- A leaf `Contract.Result` / `contract.ResultSpec` describes the reviewed
+  business value inside `data`. It may declare `outcomes`, `data_schema`, and
+  `sensitive_paths`. `Contract.Pagination` is a separate command capability
+  because pagination is emitted under envelope `meta`, not inside `data`.
+- `outcomes` is the set of results a command may produce; it is not the outcome
+  of the current invocation. `data_schema` is a JSON Schema object for business
+  data and must not duplicate the framework envelope.
+- Result declarations are delivered in the full leaf and in the reviewed
+  `--compact` Agent projection. Compact retains the normalized `result` object
+  verbatim but still omits provenance, interface bindings, and other audit-only
+  fields. Product/group summaries remain navigation views and need not repeat
+  every leaf Result. When an Agent needs return-shape facts, query the compact
+  leaf directly; do not load the whole full Catalog.
+- A missing `result` means “no reviewed return-value declaration is published
+  for this leaf.” It does **not** prove that the runtime is legacy, and it must
+  not be filled by inference from examples, MCP samples, or previous command
+  output. Runtime rollout remains an internal per-command fact.
+- The public contract has no `contract_version`, no `--output-contract`, and no
+  Agent-selectable protocol alias. Agents continue to request machine output
+  with `--format json`; migrated commands use the unified result directly and
+  unmigrated commands retain their current legacy output.
+- Existing `dev` / `devapp` pilot coverage is gradual. Active reviewed
+  `devapp` shortcuts are gated on a non-empty Result declaration, while `dev`
+  currently has representative Result coverage. Do not describe that as
+  repository-wide coverage. Any newly activated Agent-visible command should
+  add and test its Result declaration; the remaining pilot gaps should shrink,
+  not expand.
+
+The compact/full leaf `result` object has one stable shape:
+
+```json
+{
+  "result": {
+    "outcomes": ["success", "pending", "partial_failure", "failure"],
+    "data_schema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {"type": "string", "description": "Stable resource ID"},
+              "name": {"type": "string", "description": "Display name"}
+            }
+          }
+        }
+      }
+    },
+    "sensitive_paths": ["credential.secret"]
+  },
+  "pagination": {
+    "kind": "cursor",
+    "cursor_parameter": "cursor",
+    "meta_path": "meta.pagination",
+    "endpoint_exhausted_path": "meta.pagination.endpoint_exhausted",
+    "next_token_path": "meta.pagination.next_token"
+  }
+}
+```
+
+Field rules:
+
+| Field | Required | Contract |
+|---|---|---|
+| `outcomes` | yes | Non-empty unique subset of `success`, `pending`, `partial_failure`, `failure`; normalization publishes canonical order. |
+| `data_schema` | yes | One recursive JSON Schema **object** describing only the runtime envelope's `data` value. Every named `properties` child must have a non-empty `description`. It must not duplicate `ok`, `outcome`, `error`, or `meta`. |
+| `sensitive_paths` | no | Unique safe dot paths relative to `data`; renderers/redaction consumers must not treat them as shell/JQ expressions. |
+
+Optional members are omitted, never emitted as `null`. A leaf without a
+reviewed Result omits the entire `result` key. Compact must preserve the same
+normalized Result value as the full leaf; it must not summarize, infer, rename,
+or independently rebuild any Result field. Product/group summaries do not
+aggregate child Result objects.
+
+`pagination` is a sibling of `result`, not a child. It declares the canonical
+CLI cursor parameter and the fixed framework paths under `meta.pagination`.
+Product response fields used to derive that metadata remain mapper internals;
+they are not part of `result.data_schema`. Do not execute a second request to
+derive pagination metadata.
+
+Invalid result declarations fail closed during normalization: unknown or
+duplicate outcomes, a non-object/multiple `data_schema`, unsafe or duplicate
+sensitive paths, unsupported pagination kinds, attempts to override framework
+meta paths, and an invalid cursor parameter must be rejected rather than
+silently removed.
+Full-leaf wire round trips must
+preserve the normalized Result exactly. Do not commit generated Schema JSON as
+evidence; tests construct contracts in Go and runtime/CI assemble the Catalog
+from declarations.
+
+### Performance model and rules
+
+- Catalog construction is declaration-driven and cached through the existing
+  lazy `sync.Once` delivery path. Do not reassemble or reopen annotations per
+  command invocation, per leaf lookup, or per renderer.
+- Normalizing one Result declaration is linear in the size of that declaration.
+  Full `schema --all` is linear in tools + parameters + Result schema bytes and
+  is an audit/compatibility export, not the normal Agent discovery path.
+  Overview → compact product/group → compact leaf remains the normal route;
+  only the final leaf carries its Result declaration.
+- Constructing a `CommandResult` defensively clones result data and validates
+  invariants; rendering is buffer-first and then writes once. Both CPU cost and
+  transient memory are O(payload size), with roughly one additional in-memory
+  rendered copy. This buys immutability and prevents partial JSON leakage, but
+  it is not free.
+- Large list/search commands must use bounded pages and publish continuation
+  facts. The current emitter buffers one command result/page before publishing;
+  pagination is the memory bound. Continuous event streams are a separate,
+  command-specific protocol and are not described by `ResultSpec`.
+- A `dual_validate` command must execute the business request exactly once,
+  validate a shadow unified result, and preserve legacy bytes. Never obtain
+  validation by issuing a second network or write request.
+- Filters and alternate formats are render-time work over the same in-memory
+  result. They must not rerun the business operation or rebuild Schema.
+- Performance changes must preserve the one-result, buffer-first, fail-closed,
+  and atomic `--output` guarantees. Do not trade correctness for a microbenchmark
+  improvement. For a material hot-path change, benchmark representative small
+  and page-sized payloads and report allocations/bytes as well as latency.
+
 ## Current Schema boundaries

 - `schema list` remains a progressive overview. `schema --all` is the stable
@@ -479,8 +607,9 @@ path; a generator unit test or JSON count alone is insufficient.
  a complete compatibility baseline.
 - `dws <path> --help` defines whether Cobra exposes a path and which flags the
  executable accepts. A compact leaf defines Agent selection, CLI parameters,
-  constraints, and safety/confirmation semantics. Full leaf fields such as
-  `property`, `interface_ref`, and provenance are audit facts. A conflict is
-  contract drift, not permission to guess.
+  constraints, safety/confirmation semantics, and any reviewed `result`
+  contract. Full leaf fields such as `property`, `interface_ref`, and
+  provenance are audit facts. A conflict is contract drift, not permission to
+  guess.
 - Schema and Help describe commands; neither returns DingTalk business data.
  After discovery, execute the real read/search/list command to obtain data.
@@ -6,6 +6,53 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th

 ## [Unreleased]

+## [1.0.58-beta.4] - 2026-08-12
+
+### Added
+
+- **Multi-skill installation and upgrade** — fresh installs, `dws skill setup`,
+  and `dws upgrade` now use the multi-skill layout by default. Existing mono
+  installations migrate during upgrade; mono remains an explicit legacy option.
+- **Native streaming-card mentions** — `dws chat message send-card` now accepts
+  `--at-open-dingtalk-ids` and `--at-all` for group cards and forwards them to
+  `create_and_send_card`, matching the existing shortcut behavior without
+  changing single-chat card creation.
+- **Expanded Minutes workflows** — 27 public Minutes shortcuts now cover
+  upload, download, export, recording, analysis, sharing, and recovery flows;
+  every write command keeps an explicit confirmation requirement.
+- **Chat command discovery** — 30 existing typed Chat commands are now
+  available in the runtime Schema and Agent catalog, with sensitive writes
+  carrying their required confirmation metadata.
+
+### Changed
+
+- **Chat read results** — typed commands and shortcuts now expose a consistent
+  top-level `messages` list with stable `messageId` and `text` fields while
+  retaining existing response envelopes and fields.
+- **Wiki feed results** — Wiki feed list output now formats time fields and
+  trims excess fields. Its `--limit` default is 10 and maximum is 20.
+- **Developer command results** — the `dev` and selected `devapp` commands now
+  use the unified result envelope for consistent success, pending, partial,
+  and failure reporting.
+- **Evaluation dispatch hardening** — `/eval` now uses a verifiable polling
+  relay instead of direct access from the hosted runner, binding the workflow,
+  comment, PR head, parameters, and result provenance.
+
+### Fixed
+
+- **Streaming-card update acknowledgement** — accepts the pre-production
+  `success: true` response from `update_streaming_card` as affirmative write
+  evidence while preserving explicit negative, conflicting, and bizId-drift
+  failures, so Agents do not repeat an update that the service already applied.
+- **Text input bounds** — literal input, stdin, and `@file` inputs now all
+  enforce the same byte limit; file reads validate the opened descriptor and
+  cannot exceed the limit after a path replacement or file growth.
+- **Evaluation PR comments** — restores `/eval` PR conversation comments with
+  the least required pull-request write permission and actionable GitHub 403
+  diagnostics.
+
+## [1.0.58-beta.3] - 2026-08-11
+
 ### Added

 - **Aitable workflow execution and history** — adds `dws aitable workflow run` for confirmed asynchronous execution of scheduled or record-triggered workflows, plus `dws aitable workflow history` for status-, time-, and page-filtered execution records. The commands map directly to `aitable/run_workflow` and `aitable/get_flow_record_list`, validate trigger-specific arguments locally, and document the `executionId` / `instanceId` correlation.
@@ -13,6 +60,9 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
  `--at-open-dingtalk-ids` and `--at-all` for group cards, passing mention
  targets to the initial card-creation request and prepending its returned
  `atTag` to the automatic streaming update.
+- **Personal OA approval events** — personal event consumers now support task
+  creation, completion, redirection, instance start, termination, and
+  completion events, with typed output and matching usage documentation.

 ### Fixed

@@ -22,6 +72,18 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
  a successful local write. The result includes the saved path and byte size;
  document exports additionally report the node, requested format, job/task
  ID, and final status.
+- **IM search and card-write safety** — conversation-scoped search now fails
+  closed when the target cannot be verified, and streaming-card updates require
+  business evidence rather than a transport-only success response.
+- **Document shortcut reliability** — document write, readback verification,
+  pagination, template/version discovery, export, media, and local-file
+  workflows now preserve compatibility while rejecting ambiguous write results.
+- **Event runtime-token handoff** — personal `event consume`, `status`,
+  `stop`, and `+listen-im` honor the root `--token` without falling back to a
+  stale OAuth profile. Detached buses negotiate an owner-only, memory-only IPC
+  credential channel; tokens are never placed in child argv, environment,
+  profiles, logs, or run-state files.
+
 ### Changed

 - **Minutes `permission apply --policy` type** — `--policy` is now declared as
@@ -31,6 +93,15 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 - **Minutes skill references** — document `permission apply` in both Minutes
  skill references: list it in the command trees, describe its policy values and
  how it differs from `permission add`, and add its intent routing.
+- **Chat paging guidance** — typed chat message commands now document
+  `--page-all`, aggregate result shapes, and cursor behavior in CLI Help and
+  Agent selection examples.
+- **Calendar skill parity** — mono and multi Calendar references are aligned to
+  prevent documentation drift without changing CLI behavior.
+- **Release engineering** — CI now shards helper-package changes through the
+  full race suite, widens a flaky stdio idempotency test budget, governs exact
+  reviewed CLI/Schema type migrations, and lets authorized maintainers trigger
+  internal MCP evaluation with a reviewed `/eval` PR comment.

 ## [1.0.58-beta.2] - 2026-08-10

@@ -60,6 +131,10 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 - **CLI 接口兼容门禁支持 reviewed flag 类型豁免**（无用户可见变更）— `authoritative-interface-integrity` 与 `check-command-compatibility.sh` 此前一律拒绝历史命令的 flag 类型变更，即使新类型只是把同一套校验从 RunE 前移到解析期，也没有任何评审通道。现在两道门禁各带一张精确豁免表：命令路径 + flag 名 + 旧类型 → 新类型四元组全等才命中、方向敏感（`string`→`int` 与 `int`→`string` 是两个不同的键，只有被评审的方向可用），且仅当该 flag 的其他契约（shorthand / required / hidden / no-opt / scope）纹丝不动时才放行，因此豁免夹带不了别的破坏。首条也是目前唯一一条登记的是 `dws minutes permission apply --policy` 的 `string` → `int`（配合 #912）：旧实现在 RunE 里做 `strconv.ParseInt(v, 10, 64)` 再校验 `[2,4]`，新实现由 pflag 以 `strconv.ParseInt(s, 0, 64)` 解析后仍校验 `[2,4]`，**历史上能成功的调用集是新调用集的子集**（base 0 额外接受 `0x3` 这类写法，只放宽不收紧），非法值依然失败、只是报错文案与时机前移；flag 默认值由 `""` 变 `"0"` 是类型的必然结果，两道门禁都不比较默认值，且该 flag 必须显式给出、默认值不可达。两张表必须逐字一致并有守卫测试锚定漂移——重复是被迫的而非选择：`check-authoritative-interface-baselines.sh` 会把整个 `scripts/policy/interface-baseline` 目录复制进检出历史版本的 worktree 再编译，那份拷贝不能 import 本分支新增的包。
 - **Schema 兼容门禁支持 reviewed 参数类型豁免**（无用户可见变更）— 接上一条。`schema-compatibility` 是同一个 `Interface Integrity` job 里排在两道 CLI 接口门禁之后的第三道检查，此前也一律拒绝已发布参数的 `type` 变更。由于前两道先失败、`set -e` 让它从未在 CI 上暴露，上一条豁免只解决了三分之二。现在 `checkParameterCompatibility` 也带一张精确豁免表：`<product>/<tool id>` + 参数名 + 旧类型 + 新类型四元组全等才命中、方向敏感，且仅当该参数**除 `type` 外的全部已发布字段逐字段相等**时才放行。这里刻意用相等性比较而非「没有产生其他兼容性错误」：放宽 `required` / `cli_required`、清空 `required_when`、扩宽 `enum`、清空 `interface_type`、经 reviewed mapping exclusion 清空 `property`——这些变化单独看都是兼容的、根本不产生错误，若以错误列表代替相等性检查，它们就能搭着一次已评审的类型迁移一起蒙混过关。结构体整体比较还意味着将来给 `parameterSchema` 新增字段时会自动纳入守卫，而不是悄悄放宽每一条既有条目。唯一条目是 `minutes/minutes.apply_minutes_permission` 的 `policy` 由 `"string"` 迁移到 `"integer"`（配合 #912）：该 `type` 由 Cobra flag 类型投影而来（provenance `cobra_flag_type`），描述的是 CLI 如何接受取值；消费方据此拼装的是命令行，而 `--policy 4` 在两种声明下是同一个 argv，加引号的 `--policy "4"` 到 pflag 仍是 4，RunE 也仍校验 `[2,4]`——而且该参数映射的 property `policyId` 一直以数字上报，新声明比旧声明更贴近真实请求。表里的类型值必须是 `schemaType` 实际产出的带引号形态（`"string"` 而非裸 `string`），守卫测试用 `schemaType` 复算并校验类型名属于 JSON Schema 的封闭取值集合——`reviewedInterfaceRefRedirect` 曾因键的书写形态错误两次静默失效，这里不重犯。

+### Fixed
+
+- **Event runtime-token handoff** — personal `event consume`, `status`, `stop`, and `+listen-im` now honor the existing root `--token` instead of falling back to a stale local OAuth profile. Detached personal-event buses negotiate the credential only after an additive capability handshake, receive and rotate it through owner-only local IPC, and keep it in memory; the token is never forwarded through child argv, environment variables, profiles, logs, or run-state files. Existing OAuth and multi-profile behavior is unchanged when `--token` is absent. A new client refuses to send a runtime token to an older bus and leaves its existing consumers and subscriptions untouched; the recovery message asks users to inspect `event status --as user`, preview `event stop --as user --all --dry-run`, and explicitly confirm `event stop --as user --all --yes` before retrying.
+
 ## [1.0.58-beta.1] - 2026-08-07

 ### Added
@@ -83,7 +83,10 @@ coverage is additionally selected for platform-sensitive code.
   change.
 6. Run `./scripts/release/verify-package-managers.sh` when packaging or
   installer surfaces change (run `make package` first).
-7. Update docs and `CHANGELOG.md` for behavior/interface changes.
+7. Update docs and add one `.changes/<unique-name>.md` release fragment for
+   behavior/interface changes. Do not edit `CHANGELOG.md` in an ordinary PR;
+   the release-seal workflow renders and archives fragments into the versioned
+   changelog section.

 ## Submission Flow

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
  desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.58-beta.2"
+  version "1.0.58-beta.4"
  license "Apache-2.0"
  keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"

  on_macos do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-darwin-arm64.tar.gz"
-      sha256 "1b2b6953f7f1ae1ca6ecb0702424ac0e1a976a6a5ff91e8ffc3b5ae495d98c7c"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-darwin-arm64.tar.gz"
+      sha256 "5c2ac92e35b1f1dba80234af8b0c9505b2883f4a37c1e73892b8a1c3087b7702"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-darwin-amd64.tar.gz"
-      sha256 "a1c1b3c58b48e04c0ae520062f9d6ab0dc961eddb635497bdb9b4345316e45f6"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-darwin-amd64.tar.gz"
+      sha256 "93ef787770105fe1f0d27585adcac7b740aa6c37ff490275c4113814541ae095"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-linux-arm64.tar.gz"
-      sha256 "7f35e3c4734f17b125a8c32f3c95e05d1410f683cf6956be857ee9349f8e4d36"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-linux-arm64.tar.gz"
+      sha256 "011ce16a73d8fd24275e34c3122d3d0832c60cde2480f496018eb654059b5c05"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-linux-amd64.tar.gz"
-      sha256 "37beb9e39790563cf0584ac23376f713bf2eb2c50cff4222965e831ac9adbb0e"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-linux-amd64.tar.gz"
+      sha256 "847b17ff8a8d80dce38f0013eb35c77c102be16c9f98b955a632b983cd5ec104"
    end
  end

  resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.2/dws-skills.zip"
-    sha256 "7e10fead4192059c98d596c5b1886f77fd550526de5cd18c425cdad6fd64cd3a"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.58-beta.4/dws-skills.zip"
+    sha256 "f5e0c72cc92cb7e8886409319cf68bbbfc7740e969bd39a389b74af4befdbc66"
  end

  def install
@@ -70,15 +70,17 @@ The installer ships skills in one of two layouts. CLI commands (`dws aitable ...

 | Mode | What gets installed | Best for |
 |------|----------------------|----------|
-| **mono** (stable, default) | One `dws` skill covering all products | Cross-product workflows; single entry point |
-| **multi** | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
+| **multi** (default) | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
+| **mono** (legacy) | One `dws` skill covering all products | Cross-product workflows; single entry point |
+
+> Installs and upgrades default to `multi`. `mono` remains available via `DWS_SKILL_MODE=mono` or `dws skill setup --mode mono`. File issues if you hit problems.

 How to pick:

- **Quick install** (one-liner above): non-interactive, installs `mono`.
- **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) mono  2) multi` (default 1).
- **Override via env**: `DWS_SKILL_MODE=multi curl -fsSL ... | sh`.
- **Switch later**: `dws skill setup --mode multi` (or `--mode mono`) — re-run any time.
+- **Quick install** (one-liner above): non-interactive, installs `multi`.
+- **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) multi  2) mono` (default 1).
+- **Override via env**: `DWS_SKILL_MODE=mono curl -fsSL ... | sh`.
+- **Switch later**: `dws skill setup --mode mono` (or `--mode multi`) — review the listed paths and confirm interactively.

 </details>

@@ -391,19 +393,19 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

 The repo ships a complete Agent Skill system under `skills/`, organized into two layouts:

- `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), recommended default.
- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`.
+- `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), legacy.
+- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. Default layout.

 Leaf safety/parameters/selection prose for Schema generation come from ProductDecl / ContractFinal declarations in Go. The former `internal/cli/schema_hints/` HintFile tree is fully retired and must not reappear.

 After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:

 ```bash
-# Install skills into current project (defaults to mono)
+# Install skills into current project (defaults to multi; DWS_SKILL_MODE=mono switches back)
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```

-> `install.sh` installs to `$HOME/.agents/skills/dws` (global); `install-skills.sh` installs to `./.agents/skills/dws` (current project).
+> `install.sh` installs under `$HOME/.agents/skills/` (global; multi layout is per-product siblings, mono is the `dws/` subdirectory); `install-skills.sh` installs under `./.agents/skills/` (current project).
 >
 > China users: prefix `DWS_GITEE_REPO` to use the Gitee mirror — see [China mirror](#china-mirror).

@@ -413,13 +415,18 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 # Interactive: prompts for mode + target agents
 dws skill setup

-# Install mono skill to every detected agent home (claude / cursor / codex / opencode / qoder)
-dws skill setup --mode mono --target all --yes
+# Preview the exact directories that mono setup would back up and replace
+dws skill setup --mode mono --target all --dry-run

-# Install multi skills to a single agent home
-dws skill setup --mode multi --target cursor --yes
+# Run interactively and confirm the listed directories
+dws skill setup --mode mono --target all

-# Point at a local source tree (e.g. a fork or work-in-progress)
+# Preview, then install multi skills to a single agent home with interactive confirmation
+dws skill setup --mode multi --target cursor --dry-run
+dws skill setup --mode multi --target cursor
+
+# Point at a local source tree (e.g. a fork or work-in-progress), preview first
+DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi --dry-run
 DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 ```

@@ -428,7 +435,11 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 | `--mode` | `mono` \| `multi` | Skill layout; defaults to interactive prompt |
 | `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `opencode` \| `qoder` | Where to install; `all` covers every detected agent home |
 | `--source` | path | Local source directory (overrides bundled skills) |
-| `--yes` | — | Skip confirmation prompts |
+| `--yes` | — | Scripting-only: skip the confirmation prompt. Removals are still backed up to `~/.dws/skill-backups/` first |
+
+> The setup command can remove the opposite-mode layout (`dws/` for multi, DWS-managed multi Skills for mono) and stale managed Skills not in the bundle. DWS records ownership, installer version, source, and content digest centrally in `~/.dws/skills-state.json` (or `$DWS_CONFIG_DIR/skills-state.json`). Exact official names shipped before the centralized state remain a frozen migration list. A `dingtalk-*` prefix alone never authorizes cleanup, so other same-prefix market/user Skills are preserved. Every removal is previewed before confirmation and preserved under `~/.dws/skill-backups/<timestamp>/`; a directory that cannot be backed up is never removed. In a non-interactive shell, first run `--dry-run` and inspect its output; only then may the caller explicitly choose the scripting-only confirmation bypass.
+
+After a multi setup or upgrade, DWS stores the official bundle snapshot and centralized ownership metadata in `~/.dws/skills-state.json` (or `$DWS_CONFIG_DIR/skills-state.json`). Every upgrade installs and overwrites the complete bundled Skill set from that release. Deleting or excluding a bundled Skill is not sticky: the next upgrade restores it. `dws upgrade --force` additionally allows reinstalling the current CLI version when no newer version is available.

 Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.ps1`), `DWS_SKILL_SOURCE=<path>`.

@@ -726,7 +737,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step
 <summary>Coming soon</summary>

 - `conference` (video meetings)
- Multi-skill mode (experimental) — per-product skills under `skills/multi/`; opt in via `dws skill setup --mode multi`
+- Multi-skill mode (default) — per-product skills under `skills/multi/`; installs and upgrades default to it, `dws skill setup --mode mono` switches back after interactive confirmation

 </details>

@@ -70,15 +70,17 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma

 | 模式 | 安装内容 | 适合场景 |
 |------|----------|----------|
-| **mono**（稳定，默认） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
-| **multi** | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
+| **multi**（默认） | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
+| **mono**（legacy） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
+
+> 安装与升级默认均为 multi。mono 仍可通过 `DWS_SKILL_MODE=mono` 或 `dws skill setup --mode mono` 使用。问题请提 issue 反馈。

 怎么选：

- **快速安装**（上方一行 curl）：非交互，默认装 `mono`。
- **TTY 安装**（先下载再执行）：`curl -O .../install.sh && bash install.sh`，会弹出 `1) mono  2) multi` 选项（默认 1）。
- **环境变量覆盖**：`DWS_SKILL_MODE=multi curl -fsSL ... | sh`。
- **装完之后再切换**：`dws skill setup --mode multi`（或 `--mode mono`），随时重跑都行。
+- **快速安装**（上方一行 curl）：非交互，默认装 `multi`。
+- **TTY 安装**（先下载再执行）：`curl -O .../install.sh && bash install.sh`，会弹出 `1) multi  2) mono` 选项（默认 1）。
+- **环境变量覆盖**：`DWS_SKILL_MODE=mono curl -fsSL ... | sh`。
+- **装完之后再切换**：`dws skill setup --mode mono`（或 `--mode multi`），核对列出的路径后交互确认。

 </details>

@@ -385,19 +387,19 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

 仓库内置完整的 Agent Skill 体系（`skills/` 目录），分为两套布局：

- `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），默认推荐。
- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。
+- `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），legacy。
+- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。默认布局。

 Schema 生成的叶子 safety/参数/选型文案由 Go 中的 ProductDecl / ContractFinal 声明驱动。原 `internal/cli/schema_hints/` HintFile 目录已完全退役，不得重新引入。

 安装之后，Claude Code / Cursor 等 AI 工具就能通过自然语言直接操作钉钉：

 ```bash
-# 安装 skills 到当前项目（默认 mono）
+# 安装 skills 到当前项目（默认 multi；DWS_SKILL_MODE=mono 可切回）
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```

-> `install.sh` 安装到 `$HOME/.agents/skills/dws`（全局）；`install-skills.sh` 安装到 `./.agents/skills/dws`（当前项目）。
+> `install.sh` 安装到 `$HOME/.agents/skills/`（全局，multi 为按产品平铺，mono 为 `dws/` 子目录）；`install-skills.sh` 安装到 `./.agents/skills/`（当前项目）。
 >
 > 国内用户加 `DWS_GITEE_REPO` 走 Gitee 镜像，见 [国内加速安装](#国内加速安装)。

@@ -407,13 +409,18 @@ curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace
 # 交互式：提示选模式 + 目标 Agent
 dws skill setup

-# 把 mono skill 铺到所有检测到的 Agent home（claude / cursor / codex / opencode / qoder）
-dws skill setup --mode mono --target all --yes
+# 先预览 mono setup 将备份和替换的精确目录
+dws skill setup --mode mono --target all --dry-run

-# 只装到某一个 Agent home
-dws skill setup --mode multi --target cursor --yes
+# 交互执行并确认列出的目录
+dws skill setup --mode mono --target all

-# 指定本地源目录（比如 fork 或正在改的版本）
+# 先预览，再交互确认装到某一个 Agent home
+dws skill setup --mode multi --target cursor --dry-run
+dws skill setup --mode multi --target cursor
+
+# 指定本地源目录（比如 fork 或正在改的版本），先预览
+DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi --dry-run
 DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 ```

@@ -422,7 +429,11 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 | `--mode` | `mono` \| `multi` | skill 布局，不指定则交互式询问 |
 | `--target` | `all` \| `claude` \| `cursor` \| `codex` \| `opencode` \| `qoder` | 安装目标，`all` 表示铺到所有检测到的 Agent home |
 | `--source` | 路径 | 本地源目录（覆盖内置 skills） |
-| `--yes` | — | 跳过确认提示 |
+| `--yes` | — | 仅供脚本使用：跳过确认提示。删除操作仍会先备份到 `~/.dws/skill-backups/` |
+
+> setup 命令可能移除对面模式残留（装 multi 删 `dws/`，装 mono 清理统一状态中登记或属于状态上线前精确官方名称集合的 multi Skill）以及不在 bundle 内的过期受管 Skill。DWS 在 `~/.dws/skills-state.json`（或 `$DWS_CONFIG_DIR/skills-state.json`）集中记录所有权、安装版本、来源和内容摘要。仅有 `dingtalk-*` 前缀不能触发清理，因此其他同前缀市场/用户 Skill 会保留。所有删除都会先列入确认预览，并备份到 `~/.dws/skill-backups/<时间戳>/`；备份失败的目录会保留原样、绝不删除。非交互环境应先用 `--dry-run` 核对输出，再由调用方显式决定是否使用仅供脚本的确认跳过参数。
+
+multi setup 或 upgrade 后，DWS 会把官方 bundle 快照和统一所有权元数据写入 `~/.dws/skills-state.json`（或 `$DWS_CONFIG_DIR/skills-state.json`）。每次 upgrade 都会安装并覆盖该版本的全部预制 Skill；手工删除或通过 setup 排除预制 Skill 不会永久保留，下次 upgrade 会恢复。`dws upgrade --force` 还允许在没有新版本时重装当前 CLI 版本。

 环境变量：`DWS_SKILL_MODE=mono|multi`（`install.sh` / `install.ps1` 也认）、`DWS_SKILL_SOURCE=<路径>`。

@@ -715,7 +726,7 @@ dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <sec
 <summary>即将推出</summary>

 - `conference`（视频会议）
- 多 skill 模式（实验中）— 每产品一个独立 skill，位于 `skills/multi/`，通过 `dws skill setup --mode multi` 启用
+- 多 skill 模式（默认）— 每产品一个独立 skill，位于 `skills/multi/`，安装与升级默认启用；`dws skill setup --mode mono` 交互确认后可切回单 skill

 </details>

@@ -3,6 +3,7 @@
 "use strict";

 const fs = require("fs");
+const crypto = require("crypto");
 const os = require("os");
 const path = require("path");
 const childProcess = require("child_process");
@@ -45,6 +46,58 @@ function ensureCleanDir(dir) {
  fs.mkdirSync(dir, { recursive: true });
 }

+// backupStamp returns the UTC timestamp used for backup directory names,
+// matching the shell installers' `date -u +%Y%m%d-%H%M%S` layout.
+function backupStamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return (
+    `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
+    `-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}`
+  );
+}
+
+// backupAndRemoveSkillDir moves dir into <homeDir>/.dws/skill-backups/
+// <stamp>/<rel-or-basename> instead of destroying it (non-interactive
+// installs cannot confirm, so removals must stay reversible). Missing paths
+// are a no-op success. On any backup failure the directory is left in place
+// and false is returned so callers skip that target rather than silently
+// deleting data.
+function backupAndRemoveSkillDir(homeDir, dir, backups = null, renameFn = fs.renameSync) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return true;
+  }
+  const rel = path.relative(homeDir, dir);
+  const name =
+    rel && rel !== "." && !rel.startsWith("..") && !path.isAbsolute(rel)
+      ? rel.split(path.sep).join("-")
+      : path.basename(dir);
+  const stamp = backupStamp();
+  const backupRoot = path.join(homeDir, ".dws", "skill-backups");
+  let targetRoot = path.join(backupRoot, stamp);
+  let target = path.join(targetRoot, name);
+  for (let i = 1; fs.existsSync(target); i++) {
+    if (i > 1000) {
+      console.warn(`⚠️  备份目录冲突，保留原目录 ${dir}`);
+      return false;
+    }
+    targetRoot = path.join(backupRoot, `${stamp}-${i}`);
+    target = path.join(targetRoot, name);
+  }
+  try {
+    fs.mkdirSync(targetRoot, { recursive: true });
+    renameFn(dir, target);
+  } catch (err) {
+    console.warn(`⚠️  备份失败，保留原目录 ${dir}: ${err.message}`);
+    return false;
+  }
+  if (backups) {
+    backups.push({ original: dir, backup: target });
+  }
+  console.log(`  × 已备份并移除 ${dir} → ${target}`);
+  return true;
+}
+
 function findBinary(root) {
  const entries = fs.readdirSync(root, { withFileTypes: true });
  for (const entry of entries) {
@@ -117,9 +170,86 @@ function copyChildren(srcDir, destDir) {
  }
 }

+// publishCacheAtomically prepares a complete sibling tree before replacing a
+// cache. If copying or publishing fails, the previous cache stays available.
+// copyFn is injectable so the failure contract can be tested without relying
+// on platform-specific permission behavior.
+function publishCacheAtomically(sourceDir, cacheDir, copyFn = copyChildren) {
+  const cacheParent = path.dirname(cacheDir);
+  const cacheName = path.basename(cacheDir);
+  fs.mkdirSync(cacheParent, { recursive: true });
+
+  const stagedDir = fs.mkdtempSync(path.join(cacheParent, `.${cacheName}.tmp-`));
+  let rollbackDir = "";
+  let published = false;
+  try {
+    copyFn(sourceDir, stagedDir);
+
+    if (fs.existsSync(cacheDir)) {
+      rollbackDir = fs.mkdtempSync(path.join(cacheParent, `.${cacheName}.old-`));
+      fs.rmSync(rollbackDir, { recursive: true, force: true });
+      fs.renameSync(cacheDir, rollbackDir);
+    }
+
+    try {
+      fs.renameSync(stagedDir, cacheDir);
+      published = true;
+    } catch (publishErr) {
+      if (rollbackDir) {
+        try {
+          fs.renameSync(rollbackDir, cacheDir);
+          rollbackDir = "";
+        } catch (restoreErr) {
+          throw new Error(
+            `failed to publish cache ${cacheDir}: ${publishErr.message}; ` +
+              `failed to restore previous cache from ${rollbackDir}: ${restoreErr.message}`,
+          );
+        }
+      }
+      throw publishErr;
+    }
+
+    if (rollbackDir) {
+      try {
+        fs.rmSync(rollbackDir, { recursive: true, force: true });
+      } catch (cleanupErr) {
+        console.warn(
+          `⚠️  New cache is active, but old cache cleanup failed at ${rollbackDir}: ${cleanupErr.message}`,
+        );
+      }
+      rollbackDir = "";
+    }
+  } finally {
+    if (!published) {
+      fs.rmSync(stagedDir, { recursive: true, force: true });
+    }
+  }
+}
+
 function installSkillsToHomes(skillRoot) {
  const homeDir = os.homedir();
+  const managedNames = readManagedSkillNames(homeDir);
  let installed = 0;
+  let attempted = 0;
+  let failed = 0;
+
+  const installToBase = (baseDir) => {
+    const victims = [path.join(baseDir, "dws")];
+    if (fs.existsSync(baseDir)) {
+      for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && isManagedMultiSkillDir(path.join(baseDir, entry.name), managedNames)) {
+          victims.push(path.join(baseDir, entry.name));
+        }
+      }
+    }
+    try {
+      publishManagedMonoSkillSetAtomically(homeDir, skillRoot, baseDir, victims);
+    } catch (err) {
+      console.warn(`⚠️  跳过 ${baseDir}（mono 集合发布失败，已回滚）: ${err.message}`);
+      return false;
+    }
+    return true;
+  };

  AGENT_DIRS.forEach((agentDir, index) => {
    const baseDir = path.join(homeDir, agentDir);
@@ -127,37 +257,434 @@ function installSkillsToHomes(skillRoot) {
    if (index > 0 && !fs.existsSync(parentGate)) {
      return;
    }
-    const destDir = path.join(baseDir, "dws");
-    fs.rmSync(destDir, { recursive: true, force: true });
-    copyChildren(skillRoot, destDir);
-    installed += 1;
+    attempted += 1;
+    if (installToBase(baseDir)) {
+      installed += 1;
+    } else {
+      failed += 1;
+    }
  });

-  if (installed === 0) {
-    copyChildren(skillRoot, path.join(homeDir, ".agents", "skills", "dws"));
+  if (attempted === 0) {
+    if (installToBase(path.join(homeDir, ".agents", "skills"))) {
+      installed += 1;
+    } else {
+      failed += 1;
+    }
  }
+  if (installed === 0) {
+    throw new Error("未安装任何 mono Skill：所有检测到的 Agent 目标均失败");
+  }
+  if (failed > 0) {
+    throw new Error(`有 ${failed} 个 Agent 目标安装 mono Skill 失败`);
+  }
+  fs.rmSync(path.join(skillStateDir(homeDir), "skills-state.json"), { force: true });
+}
+
+// multiTreeHasSkills mirrors multi_tree_has_skills in scripts/install.sh and
+// Test-MultiTreeHasSkills in scripts/install.ps1: true only when the multi
+// bundle carries at least one product skill (a subdir with SKILL.md). An
+// empty or corrupt multi/ tree must never select the multi branch nor refresh
+// the multi cache — installing it would wipe existing skills and lay down
+// nothing.
+function multiTreeHasSkills(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return false;
+  }
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .some((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")));
+}
+
+const MANAGED_SKILL_DIGEST_SCOPE = "skill-directory-v1";
+// Frozen exact names shipped before centralized ownership metadata. Retired
+// names stay here so old installs can be migrated without treating every
+// dingtalk-* directory as DWS-owned.
+const LEGACY_OFFICIAL_MULTI_SKILLS = new Set([
+  "dingtalk-agoal", "dingtalk-aiapp", "dingtalk-aisearch", "dingtalk-aitable",
+  "dingtalk-attendance", "dingtalk-calendar", "dingtalk-chat", "dingtalk-contact",
+  "dingtalk-dev", "dingtalk-devapp", "dingtalk-devdoc", "dingtalk-ding",
+  "dingtalk-doc", "dingtalk-drive", "dingtalk-event", "dingtalk-hrbrain",
+  "dingtalk-live", "dingtalk-mail", "dingtalk-markdown", "dingtalk-minutes",
+  "dingtalk-misc", "dingtalk-oa", "dingtalk-pat", "dingtalk-profile",
+  "dingtalk-report", "dingtalk-shared", "dingtalk-sheet", "dingtalk-skill",
+  "dingtalk-todo", "dingtalk-wiki", "dws-shared",
+]);
+
+function skillStateDir(homeDir) {
+  return (process.env.DWS_CONFIG_DIR || "").trim() || path.join(homeDir, ".dws");
+}
+
+function readManagedSkillNames(homeDir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(path.join(skillStateDir(homeDir), "skills-state.json"), "utf8"));
+    return new Set((state.managed_skills || []).map((record) => record.name).filter(Boolean));
+  } catch (_) {
+    return new Set();
+  }
+}
+
+function isManagedMultiSkillDir(dir, managedNames) {
+  const name = path.basename(dir);
+  return LEGACY_OFFICIAL_MULTI_SKILLS.has(name) || managedNames.has(name);
+}
+
+function skillDirectoryDigest(dir) {
+  const files = [];
+  const visit = (current, prefix) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        visit(full, rel);
+      } else {
+        files.push({ rel, full });
+      }
+    }
+  };
+  visit(dir, "");
+  files.sort((a, b) => Buffer.from(a.rel).compare(Buffer.from(b.rel)));
+  const hash = crypto.createHash("sha256");
+  for (const file of files) {
+    hash.update(file.rel, "utf8");
+    hash.update(Buffer.from([0]));
+    hash.update(fs.readFileSync(file.full));
+    hash.update(Buffer.from([0]));
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+// Publish a complete multi-skill set as one transaction. The entire new set
+// is staged before any Agent-visible directory moves. If a later backup or
+// publish fails, every partial publication is removed and all old directories
+// are restored from their exact backup paths.
+function publishManagedMultiSkillSetAtomically(
+  homeDir,
+  multiRoot,
+  baseDir,
+  skills,
+  victims,
+  options = {},
+) {
+  const copyFn = options.copyFn || copyChildren;
+  const renameFn = options.renameFn || fs.renameSync;
+  const removeFn = options.removeFn || ((dir) => fs.rmSync(dir, { recursive: true, force: true }));
+  fs.mkdirSync(baseDir, { recursive: true });
+  const stageRoot = fs.mkdtempSync(path.join(baseDir, ".dws-multi-set.tmp-"));
+  const staged = [];
+  const backups = [];
+  const published = [];
+
+  const restore = () => {
+    const restoreErrors = [];
+    for (let i = published.length - 1; i >= 0; i -= 1) {
+      try {
+        removeFn(published[i]);
+      } catch (err) {
+        restoreErrors.push(`remove ${published[i]}: ${err.message}`);
+      }
+    }
+    for (let i = backups.length - 1; i >= 0; i -= 1) {
+      const item = backups[i];
+      try {
+        fs.mkdirSync(path.dirname(item.original), { recursive: true });
+        renameFn(item.backup, item.original);
+      } catch (err) {
+        restoreErrors.push(`restore ${item.original} from ${item.backup}: ${err.message}`);
+      }
+    }
+    if (restoreErrors.length > 0) {
+      throw new Error(restoreErrors.join("; "));
+    }
+  };
+
+  try {
+    for (const name of skills) {
+      const stagedDir = path.join(stageRoot, name);
+      copyFn(path.join(multiRoot, name), stagedDir);
+      staged.push({ staged: stagedDir, dest: path.join(baseDir, name) });
+    }
+
+    const seen = new Set();
+    for (const victim of victims) {
+      const normalized = path.resolve(victim);
+      if (seen.has(normalized)) {
+        continue;
+      }
+      seen.add(normalized);
+      if (!backupAndRemoveSkillDir(homeDir, victim, backups, renameFn)) {
+        throw new Error(`failed to back up Skill directory ${victim}`);
+      }
+    }
+
+    for (const item of staged) {
+      renameFn(item.staged, item.dest);
+      published.push(item.dest);
+    }
+  } catch (err) {
+    try {
+      restore();
+    } catch (restoreErr) {
+      throw new Error(`${err.message}; rollback failed: ${restoreErr.message}`);
+    }
+    throw err;
+  } finally {
+    removeFn(stageRoot);
+  }
+}
+
+// Publish mono plus every mutually-exclusive managed multi victim as one
+// transaction. The complete dws/ tree is staged before any live directory is
+// moved; a later backup or publish failure restores the exact previous set.
+function publishManagedMonoSkillSetAtomically(
+  homeDir,
+  monoRoot,
+  baseDir,
+  victims,
+  options = {},
+) {
+  const copyFn = options.copyFn || copyChildren;
+  const renameFn = options.renameFn || fs.renameSync;
+  const removeFn = options.removeFn || ((dir) => fs.rmSync(dir, { recursive: true, force: true }));
+  fs.mkdirSync(baseDir, { recursive: true });
+  const stageRoot = fs.mkdtempSync(path.join(baseDir, ".dws-mono-set.tmp-"));
+  const stagedDir = path.join(stageRoot, "dws");
+  const destDir = path.join(baseDir, "dws");
+  const backups = [];
+  const published = [];
+
+  const restore = () => {
+    const restoreErrors = [];
+    for (let i = published.length - 1; i >= 0; i -= 1) {
+      try {
+        removeFn(published[i]);
+      } catch (err) {
+        restoreErrors.push(`remove ${published[i]}: ${err.message}`);
+      }
+    }
+    for (let i = backups.length - 1; i >= 0; i -= 1) {
+      const item = backups[i];
+      try {
+        fs.mkdirSync(path.dirname(item.original), { recursive: true });
+        renameFn(item.backup, item.original);
+      } catch (err) {
+        restoreErrors.push(`restore ${item.original} from ${item.backup}: ${err.message}`);
+      }
+    }
+    if (restoreErrors.length > 0) {
+      throw new Error(restoreErrors.join("; "));
+    }
+  };
+
+  try {
+    copyFn(monoRoot, stagedDir);
+
+    const seen = new Set();
+    for (const victim of victims) {
+      const normalized = path.resolve(victim);
+      if (seen.has(normalized)) {
+        continue;
+      }
+      seen.add(normalized);
+      if (!backupAndRemoveSkillDir(homeDir, victim, backups, renameFn)) {
+        throw new Error(`failed to back up Skill directory ${victim}`);
+      }
+    }
+
+    published.push(destDir);
+    renameFn(stagedDir, destDir);
+  } catch (err) {
+    try {
+      restore();
+    } catch (restoreErr) {
+      throw new Error(`${err.message}; rollback failed: ${restoreErr.message}`);
+    }
+    throw err;
+  } finally {
+    removeFn(stageRoot);
+  }
+}
+
+function writeSkillsState(homeDir, multiRoot, skills) {
+  const version = process.env.npm_package_version || process.env.DWS_PACKAGE_VERSION || "unknown";
+  const managedSkills = [...skills].sort().map((name) => ({
+    name,
+    version,
+    source: "npm-postinstall",
+    digest: skillDirectoryDigest(path.join(multiRoot, name)),
+    digest_scope: MANAGED_SKILL_DIGEST_SCOPE,
+  }));
+  const state = {
+    version,
+    official_skills: [...skills].sort(),
+    updated_skills: [...skills].sort(),
+    managed_skills: managedSkills,
+    updated_at: new Date().toISOString(),
+  };
+  const stateDir = skillStateDir(homeDir);
+  fs.mkdirSync(stateDir, { recursive: true });
+  const stage = fs.mkdtempSync(path.join(stateDir, ".skills-state.tmp-"));
+  const stagedFile = path.join(stage, "skills-state.json");
+  const statePath = path.join(stateDir, "skills-state.json");
+  const rollbackPath = path.join(stage, "skills-state.previous.json");
+  let movedPrevious = false;
+  let preserveRecovery = false;
+  try {
+    fs.writeFileSync(stagedFile, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    if (fs.existsSync(statePath)) {
+      fs.renameSync(statePath, rollbackPath);
+      movedPrevious = true;
+    }
+    try {
+      fs.renameSync(stagedFile, statePath);
+    } catch (err) {
+      if (movedPrevious && !fs.existsSync(statePath)) {
+        try {
+          fs.renameSync(rollbackPath, statePath);
+          movedPrevious = false;
+        } catch (restoreErr) {
+          preserveRecovery = true;
+          throw new Error(
+            `publish skills state failed: ${err.message}; restore also failed: ${restoreErr.message}; previous state retained at ${rollbackPath}`,
+          );
+        }
+      }
+      throw err;
+    }
+  } finally {
+    if (!preserveRecovery) {
+      fs.rmSync(stage, { recursive: true, force: true });
+    }
+  }
+}
+
+// installMultiSkillsToHomes mirrors installSkillsToHomes for the multi bundle:
+// every product skill becomes a sibling directory of the agent home. Mutual
+// exclusion: the mono leftover (dws/) and stale, proven DWS-managed skills not
+// present in the new bundle are removed first.
+function installMultiSkillsToHomes(multiRoot) {
+  const homeDir = os.homedir();
+  const skills = fs
+    .readdirSync(multiRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(multiRoot, e.name, "SKILL.md")))
+    .map((e) => e.name);
+  if (skills.length === 0) {
+    throw new Error(`no product skills found under ${multiRoot}`);
+  }
+  const skillSet = new Set(skills);
+  const managedNames = readManagedSkillNames(homeDir);
+  let installed = 0;
+  let attempted = 0;
+  let failed = 0;
+
+  const installToBase = (baseDir) => {
+    fs.mkdirSync(baseDir, { recursive: true });
+    const victims = [path.join(baseDir, "dws")];
+    // Mutual exclusion: include the mono leftover and stale managed skills in
+    // the same transaction as every replaced bundled skill.
+    for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
+      if (
+        entry.isDirectory() &&
+        (LEGACY_OFFICIAL_MULTI_SKILLS.has(entry.name) || managedNames.has(entry.name)) &&
+        !skillSet.has(entry.name)
+      ) {
+        victims.push(path.join(baseDir, entry.name));
+      }
+    }
+    for (const name of skills) {
+      victims.push(path.join(baseDir, name));
+    }
+    try {
+      publishManagedMultiSkillSetAtomically(homeDir, multiRoot, baseDir, skills, victims);
+    } catch (err) {
+      console.warn(`⚠️  跳过 ${baseDir}（multi 集合发布失败，已回滚）: ${err.message}`);
+      return false;
+    }
+    return true;
+  };
+
+  AGENT_DIRS.forEach((agentDir, index) => {
+    const baseDir = path.join(homeDir, agentDir);
+    const parentGate = path.dirname(baseDir);
+    if (index > 0 && !fs.existsSync(parentGate)) {
+      return;
+    }
+    attempted += 1;
+    if (installToBase(baseDir)) {
+      installed += 1;
+    } else {
+      failed += 1;
+    }
+  });
+
+  if (attempted === 0) {
+    if (installToBase(path.join(homeDir, ".agents", "skills"))) {
+      installed += 1;
+    } else {
+      failed += 1;
+    }
+  }
+  if (installed === 0) {
+    throw new Error("未安装任何 multi Skill：所有检测到的 Agent 目标均失败");
+  }
+  if (failed > 0) {
+    throw new Error(`有 ${failed} 个 Agent 目标安装 multi Skill 失败`);
+  }
+  writeSkillsState(homeDir, multiRoot, skills);
+}
+
+// resolveSkillMode mirrors scripts/install.sh: DWS_SKILL_MODE (mono|multi)
+// wins; multi is the default. The --skill-mode flag accepts both the space
+// form (`--skill-mode mono`) and the equals form (`--skill-mode=mono`).
+function resolveSkillMode() {
+  const raw = (process.env.DWS_SKILL_MODE || "").trim().toLowerCase();
+  if (raw === "mono" || raw === "multi") {
+    return raw;
+  }
+  if (raw !== "") {
+    throw new Error(`invalid DWS_SKILL_MODE='${process.env.DWS_SKILL_MODE}'. Use 'mono' or 'multi'.`);
+  }
+  let fromFlag;
+  const flagIndex = process.argv.indexOf("--skill-mode");
+  if (flagIndex !== -1 && process.argv[flagIndex + 1]) {
+    fromFlag = process.argv[flagIndex + 1];
+  } else {
+    const equalsArg = process.argv.find((arg) => arg.startsWith("--skill-mode="));
+    if (equalsArg) {
+      fromFlag = equalsArg.slice("--skill-mode=".length);
+    }
+  }
+  if (fromFlag !== undefined) {
+    const mode = fromFlag.trim().toLowerCase();
+    if (mode === "mono" || mode === "multi") {
+      return mode;
+    }
+    throw new Error(`invalid --skill-mode '${fromFlag}'. Use 'mono' or 'multi'.`);
+  }
+  return "multi";
 }

 // cacheUserSkills copies the mono and multi trees out of the freshly extracted
 // dws-skills.zip into ~/.dws/skills/{mono,multi}/ so that `dws skill setup`
-// can fall back to a user-local cache when --source is not provided. mono is
-// already installed into agent homes by installSkillsToHomes; the cache is
-// purely a source-of-truth for the setup command.
+// can fall back to a user-local cache when --source is not provided. A cache
+// is only refreshed when the new bundle actually carries that tree — an
+// empty/corrupt multi/ (or a missing mono tree) must never wipe a previously
+// good cache.
 function cacheUserSkills(extractedSkillsRoot) {
  const cacheBase = path.join(os.homedir(), ".dws", "skills");

  const monoSource = fs.existsSync(path.join(extractedSkillsRoot, "mono", "SKILL.md"))
    ? path.join(extractedSkillsRoot, "mono")
    : extractedSkillsRoot;
-  const monoCache = path.join(cacheBase, "mono");
-  fs.rmSync(monoCache, { recursive: true, force: true });
-  copyChildren(monoSource, monoCache);
+  if (fs.existsSync(path.join(monoSource, "SKILL.md"))) {
+    const monoCache = path.join(cacheBase, "mono");
+    publishCacheAtomically(monoSource, monoCache);
+  }

  const multiSource = path.join(extractedSkillsRoot, "multi");
-  if (fs.existsSync(multiSource) && fs.statSync(multiSource).isDirectory()) {
+  if (multiTreeHasSkills(multiSource)) {
    const multiCache = path.join(cacheBase, "multi");
-    fs.rmSync(multiCache, { recursive: true, force: true });
-    copyChildren(multiSource, multiCache);
+    publishCacheAtomically(multiSource, multiCache);
  }
 }

@@ -191,8 +718,34 @@ function main() {
  const monoRoot = fs.existsSync(path.join(skillsStaging, "mono", "SKILL.md"))
    ? path.join(skillsStaging, "mono")
    : skillsStaging;
-  installSkillsToHomes(monoRoot);
+  // A mono install requires an actual SKILL.md at the root of monoRoot. On a
+  // multi-only zip monoRoot would degrade to the staging root and copy the
+  // whole bundle (multi/ included) into a dws/ directory — skip instead.
+  const monoHasSkill = fs.existsSync(path.join(monoRoot, "SKILL.md"));
+  const multiRoot = path.join(skillsStaging, "multi");
+  const skillMode = resolveSkillMode();
+  if (skillMode === "multi" && multiTreeHasSkills(multiRoot)) {
+    console.log(`Skill mode: multi — installing per-product skills`);
+    installMultiSkillsToHomes(multiRoot);
+  } else {
+    if (skillMode === "multi") {
+      console.log("multi skill tree not found or empty in bundle; falling back to mono.");
+    }
+    if (monoHasSkill) {
+      installSkillsToHomes(monoRoot);
+    } else {
+      console.log("mono skill tree not found in bundle; skipping skill install.");
+    }
+  }
  cacheUserSkills(skillsStaging);
 }

-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  publishCacheAtomically,
+  publishManagedMonoSkillSetAtomically,
+  publishManagedMultiSkillSetAtomically,
+};
@@ -48,8 +48,12 @@ It then runs:
  --fast-path "$PR_BASE_SHA" HEAD
 ```

-Because the verified PR diff contains only `CHANGELOG.md`, the validator and
-its policy dependencies in that merge tree are byte-for-byte the current base
+The exact fast path remains limited to historic one-file maintenance. A
+release-seal PR uses `--content-only`, which permits the generated
+`CHANGELOG.md` change together with archival moves from `.changes/` to
+`.changes/released/`; it receives the normal scoped admission instead of this
+fast path. Ordinary PRs must not modify `CHANGELOG.md`; they add a standalone
+release fragment instead. The validator and its policy dependencies in that merge tree are byte-for-byte the current base
 versions. Validation targets the synthetic merge tree, not the feature-branch
 tree, so a stale branch cannot supply an older validator or combine with newer
 base notes into an invalid final CHANGELOG.
@@ -79,10 +83,12 @@ to the complete main admission suite. A source change can therefore never
 inherit the CHANGELOG-only result.

 Any PR that touches `CHANGELOG.md` but also changes another file runs the same
-content contract in `Policy` with `--content-only`. That mode permits the
-second file but still rejects invalid dates or versions, missing bullets,
-placeholder `TODO`/`TBD`, unmanaged-section changes, and unsafe tree modes.
-Adding a second file therefore cannot bypass CHANGELOG validation.
+content contract in `Policy` with `--content-only`. That mode accepts only
+fragment archival moves (`.changes/<name>.md` to
+`.changes/released/<version>/<name>.md`) alongside the changelog; source and
+documentation changes are rejected. It still rejects invalid dates or
+versions, missing bullets, placeholder `TODO`/`TBD`, unmanaged-section
+changes, and unsafe tree modes.

 ## Risk tiers and downstream boundaries

@@ -184,11 +190,11 @@ Schema，并让 candidate 对两份历史 contract 独立执行检查；它只
 lifecycle 的 exact rename 规范化到当前历史副本，不会维护第二份 allowlist，也不会
 放宽其他 Schema 历史字段。

-For an exact CHANGELOG-only branch:
+For a release-seal branch that archives rendered fragments:

 ```sh
 base_ref=$(git merge-base HEAD origin/main)
-./scripts/policy/check-changelog-pr.sh --fast-path "$base_ref" HEAD
+./scripts/policy/check-changelog-pr.sh --content-only "$base_ref" HEAD
 ```

 `make coverage-gate` is an enforcement step, not a profile generator. For a
@@ -0,0 +1,312 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="DWS Drive Shortcut 与 lark-cli 的业务能力、真实数据 E2E 证据和平台边界分析。">
+  <title>Drive Shortcut 能力全景｜业务评审版</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --paper: #f4f6f2; --surface: #fffefa; --ink: #17251f; --muted: #66746d;
+      --line: #dce2dc; --forest: #154f3d; --green: #17765a; --mint: #dff4e8;
+      --blue: #265f86; --blue-soft: #e7f1f7; --amber: #8c5a09; --amber-soft: #fff2cf;
+      --red: #a43b32; --red-soft: #fde9e5; --shadow: 0 14px 40px rgba(28, 48, 38, .08);
+    }
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+    body { margin: 0; color: var(--ink); background: var(--paper); font: 15px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; }
+    a { color: inherit; text-decoration: none; }
+    code { padding: .12rem .38rem; border: 1px solid #d6e0da; border-radius: 6px; color: #174f3e; background: #f1f7f3; font: 600 .88em/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; white-space: nowrap; }
+    .wrap { width: min(1180px, calc(100% - 40px)); margin: auto; }
+    .hero { position: relative; overflow: hidden; padding: 64px 0 52px; color: #f7fff9; background: linear-gradient(125deg, #102b22 0%, #154c3c 57%, #1c6b54 100%); }
+    .hero::after { position: absolute; inset: -180px -100px auto auto; width: 540px; height: 540px; border: 1px solid rgba(255,255,255,.14); border-radius: 50%; box-shadow: 0 0 0 76px rgba(255,255,255,.035), 0 0 0 152px rgba(255,255,255,.025); content: ""; }
+    .hero-grid { position: relative; z-index: 1; display: grid; grid-template-columns: minmax(0, 1.35fr) minmax(300px, .65fr); gap: 32px; align-items: end; }
+    .eyebrow, .section-kicker { margin: 0 0 9px; color: #9fd6bd; font-size: 11px; font-weight: 900; letter-spacing: .16em; text-transform: uppercase; }
+    h1 { margin: 0; font-size: clamp(40px, 6vw, 68px); line-height: 1.03; letter-spacing: -.045em; }
+    .subtitle { max-width: 760px; margin: 19px 0 0; color: #d3e9de; font-size: 17px; }
+    .meta-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 21px; }
+    .meta-pill { padding: 6px 10px; border: 1px solid rgba(255,255,255,.18); border-radius: 999px; color: #d5e9df; background: rgba(255,255,255,.07); font-size: 11px; font-weight: 750; }
+    .meta-pill.good { color: #bff2d5; border-color: rgba(139,232,179,.38); }
+    .hero-stats { display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px; }
+    .hero-stat { padding: 17px 16px; border: 1px solid rgba(255,255,255,.17); border-radius: 15px; background: rgba(255,255,255,.075); backdrop-filter: blur(8px); }
+    .hero-stat strong { display: block; font-size: 30px; line-height: 1; }
+    .hero-stat span { display: block; margin-top: 7px; color: #cce2d7; font-size: 11px; }
+    .nav { position: sticky; top: 0; z-index: 20; border-bottom: 1px solid var(--line); background: rgba(255,254,250,.94); backdrop-filter: blur(12px); }
+    .nav .wrap { display: flex; overflow-x: auto; }
+    .nav a { flex: 0 0 auto; padding: 14px 15px; color: #5b6c64; font-size: 12px; font-weight: 800; }
+    .nav a:hover { color: var(--forest); background: #eaf3ee; }
+    main { padding: 38px 0 74px; }
+    section { margin-top: 50px; scroll-margin-top: 72px; }
+    section:first-child { margin-top: 0; }
+    .section-head { display: flex; justify-content: space-between; gap: 28px; align-items: end; margin-bottom: 19px; }
+    h2 { margin: 0; font-size: clamp(25px, 3.2vw, 36px); line-height: 1.16; letter-spacing: -.025em; }
+    h3 { margin: 0 0 7px; font-size: 18px; }
+    .section-desc { max-width: 660px; margin: 0; color: var(--muted); font-size: 13px; }
+    .callout { padding: 19px 21px; border: 1px solid #bdd8cb; border-left: 4px solid var(--green); border-radius: 13px; background: #ecf7f1; box-shadow: 0 6px 20px rgba(28,48,38,.04); }
+    .callout strong { color: #13513d; }
+    .callout.warn { border-color: #ead29a; border-left-color: #b67508; background: #fff8e7; }
+    .callout.warn strong { color: #784b00; }
+    .callout.danger { border-color: #e9b7b1; border-left-color: var(--red); background: var(--red-soft); }
+    .score-grid, .domain-grid, .evidence-grid, .review-grid { display: grid; gap: 13px; }
+    .score-grid { grid-template-columns: repeat(4, 1fr); margin-top: 16px; }
+    .score, .domain-card, .evidence-card, .review-card { border: 1px solid var(--line); border-radius: 15px; background: var(--surface); box-shadow: var(--shadow); }
+    .score { padding: 19px; }
+    .score strong { display: block; color: var(--forest); font-size: 29px; line-height: 1; }
+    .score span { display: block; margin-top: 8px; color: var(--muted); font-size: 12px; }
+    .domain-grid { grid-template-columns: repeat(4, 1fr); }
+    .domain-card { position: relative; padding: 21px; overflow: hidden; }
+    .domain-card .number { position: absolute; top: 12px; right: 17px; color: #d5e8de; font: 800 42px/1 ui-monospace, monospace; }
+    .domain-card p { min-height: 64px; margin: 8px 0 12px; color: var(--muted); font-size: 13px; }
+    .domain-card small { color: var(--green); font-weight: 800; }
+    .compare { overflow: hidden; border: 1px solid var(--line); border-radius: 16px; background: var(--surface); box-shadow: var(--shadow); }
+    .compare-top { display: grid; grid-template-columns: repeat(3, 1fr); }
+    .compare-column { padding: 21px; border-right: 1px solid var(--line); }
+    .compare-column:last-child { border-right: 0; }
+    .compare-column p, .compare-column li { color: var(--muted); font-size: 13px; }
+    .compare-column ul { margin: 9px 0 0; padding-left: 18px; }
+    .compare-column.covered { border-top: 5px solid var(--green); }
+    .compare-column.partial { border-top: 5px solid #c78b22; }
+    .compare-column.gap { border-top: 5px solid var(--red); }
+    .table-wrap { overflow-x: auto; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 12px 14px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }
+    th { color: #617069; background: #f7f8f5; font-size: 11px; font-weight: 900; letter-spacing: .03em; }
+    tr:last-child td { border-bottom: 0; }
+    tbody tr:hover { background: #f8fbf8; }
+    .verdict, .badge { display: inline-flex; align-items: center; padding: 3px 8px; border-radius: 999px; font-size: 10px; font-weight: 900; white-space: nowrap; }
+    .v-covered, .badge.read { color: #116045; background: var(--mint); }
+    .v-ahead, .badge.smart { color: #20577c; background: var(--blue-soft); }
+    .v-partial, .badge.write { color: #7b510a; background: var(--amber-soft); }
+    .v-gap, .badge.high { color: #8f3028; background: var(--red-soft); }
+    .truth-grid { display: grid; grid-template-columns: 1.1fr .9fr; gap: 14px; }
+    .truth-card { padding: 22px; border: 1px solid var(--line); border-radius: 15px; background: var(--surface); box-shadow: var(--shadow); }
+    .truth-step { display: grid; grid-template-columns: 30px 1fr; gap: 11px; margin-top: 13px; }
+    .truth-step b { display: grid; width: 28px; height: 28px; place-items: center; border-radius: 50%; color: #fff; background: var(--forest); font-size: 12px; }
+    .truth-step strong, .truth-step span { display: block; }
+    .truth-step span { color: var(--muted); font-size: 12px; }
+    .toolbar { display: grid; grid-template-columns: minmax(260px, 1fr) 180px 180px auto; gap: 10px; align-items: center; margin: 18px 0; padding: 13px; border: 1px solid var(--line); border-radius: 14px; background: var(--surface); }
+    input, select { width: 100%; min-height: 42px; padding: 9px 11px; border: 1px solid #ccd7d0; border-radius: 9px; color: var(--ink); background: #fff; font: inherit; }
+    input:focus, select:focus { outline: 3px solid rgba(23,118,90,.13); border-color: var(--green); }
+    .result-count { color: var(--muted); font-size: 12px; text-align: right; white-space: nowrap; }
+    .catalog { overflow: hidden; border: 1px solid var(--line); border-radius: 16px; background: var(--surface); box-shadow: var(--shadow); }
+    .shortcut-row { display: grid; grid-template-columns: 215px minmax(0, 1fr) 200px; gap: 16px; align-items: center; padding: 14px 17px; border-bottom: 1px solid var(--line); }
+    .shortcut-row:last-child { border-bottom: 0; }
+    .shortcut-row:hover { background: #f8fbf8; }
+    .command code { font-size: 12px; }
+    .row-main p { margin: 0; font-size: 13px; }
+    .row-main small { color: var(--muted); }
+    .badges { display: flex; justify-content: flex-end; flex-wrap: wrap; gap: 5px; }
+    .hidden-row { display: none; }
+    .evidence-grid { grid-template-columns: repeat(4, 1fr); }
+    .evidence-card { padding: 19px; }
+    .evidence-card strong { display: block; color: var(--forest); font-size: 23px; }
+    .evidence-card p { margin: 7px 0 0; color: var(--muted); font-size: 12px; }
+    .timeline { margin-top: 15px; border-left: 2px solid #bdd7ca; }
+    .event { position: relative; padding: 0 0 17px 22px; }
+    .event::before { position: absolute; left: -7px; top: 5px; width: 12px; height: 12px; border: 3px solid var(--paper); border-radius: 50%; background: var(--green); content: ""; }
+    .event b { display: block; }
+    .event span { color: var(--muted); font-size: 12px; }
+    .review-grid { grid-template-columns: repeat(3, 1fr); }
+    .review-card { position: relative; padding: 20px; }
+    .review-card .review-num { color: #b8d1c4; font: 800 12px/1 ui-monospace, monospace; letter-spacing: .1em; }
+    .review-card p { margin: 7px 0 0; color: var(--muted); font-size: 13px; }
+    footer { margin-top: 52px; padding: 23px 0; border-top: 1px solid var(--line); color: var(--muted); font-size: 11px; }
+    @media (max-width: 900px) { .hero-grid, .truth-grid { grid-template-columns: 1fr; } .score-grid, .domain-grid, .evidence-grid { grid-template-columns: repeat(2, 1fr); } .review-grid { grid-template-columns: 1fr 1fr; } .shortcut-row { grid-template-columns: 180px 1fr; } .badges { grid-column: 1 / -1; justify-content: flex-start; } }
+    @media (max-width: 620px) { .wrap { width: min(100% - 24px, 1180px); } .hero { padding: 44px 0 38px; } .hero-stats, .score-grid, .domain-grid, .evidence-grid, .review-grid, .compare-top { grid-template-columns: 1fr; } .compare-column { border-right: 0; border-bottom: 1px solid var(--line); } .toolbar { grid-template-columns: 1fr; } .result-count { text-align: left; } .shortcut-row { grid-template-columns: 1fr; } }
+    @media print { body { background: #fff; } .hero { color: var(--ink); background: #fff; border-bottom: 2px solid var(--ink); } .subtitle, .meta-pill, .hero-stat span { color: #425249; } .hero-stat { border-color: #aebbb3; } .nav, .toolbar { display: none; } .score, .domain-card, .compare, .truth-card, .catalog, .evidence-card, .review-card { box-shadow: none; break-inside: avoid; } }
+  </style>
+</head>
+<body>
+  <header class="hero">
+    <div class="wrap hero-grid">
+      <div>
+        <p class="eyebrow">Business Review · Drive</p>
+        <h1>Drive Shortcut<br>能力全景</h1>
+        <p class="subtitle">从 lark-cli 对齐出发，但不止于命令名：逐项审查输入、校验、多步编排、失败语义、真实字节和平台边界。</p>
+        <div class="meta-row">
+          <span class="meta-pill good">真实账号 E2E 已执行</span>
+          <span class="meta-pill">28 个公开入口</span>
+          <span class="meta-pill">统一 Result / Pagination</span>
+          <span class="meta-pill">报告已移除 PII / 凭证 / 业务正文</span>
+        </div>
+      </div>
+      <div class="hero-stats" aria-label="关键统计">
+        <div class="hero-stat"><strong>38</strong><span>lark-cli Drive 逐项审查</span></div>
+        <div class="hero-stat"><strong>26</strong><span>已覆盖或跨产品路由</span></div>
+        <div class="hero-stat"><strong>7</strong><span>部分对齐，边界已公开</span></div>
+        <div class="hero-stat"><strong>5</strong><span>客观不可对齐能力</span></div>
+      </div>
+    </div>
+  </header>
+
+  <nav class="nav"><div class="wrap"><a href="#overview">全景</a><a href="#compare">Lark 对齐</a><a href="#ahead">超越项</a><a href="#truth">真实语义</a><a href="#catalog">完整目录</a><a href="#e2e">E2E</a><a href="#review">评审</a></div></nav>
+
+  <main class="wrap">
+    <section id="overview">
+      <div class="section-head"><div><p class="section-kicker">Executive summary</p><h2>28 个公开入口，覆盖文件完整生命周期</h2></div><p class="section-desc">另有 <code>+publish-set</code> 已实现契约和读回逻辑，但真实普通文件与在线文档均被服务端拒绝，因此保持 unavailable，不进入 Agent 公开目录。</p></div>
+      <div class="callout"><strong>结论：</strong>Drive 已从 9 个偏原子入口扩展为 28 个可发现 Shortcut。它不仅补齐 Lark 的核心文件、版本和状态任务，还通过严格响应合同、真实落盘、写后读回、回收恢复和个人收藏形成更可审计的钉盘工作流。</div>
+      <div class="score-grid">
+        <article class="score"><strong>29</strong><span>已审查注册项（含 1 unavailable）</span></article>
+        <article class="score"><strong>25</strong><span>公开主能力 / 语义适配</span></article>
+        <article class="score"><strong>3</strong><span>公开兼容入口</span></article>
+        <article class="score"><strong>3</strong><span>高风险写入口，均需确认</span></article>
+      </div>
+    </section>
+
+    <section>
+      <div class="section-head"><div><p class="section-kicker">Capability map</p><h2>四个业务域</h2></div><p class="section-desc">目录按用户任务组织；兼容命令不重复计为新增能力。</p></div>
+      <div class="domain-grid">
+        <article class="domain-card"><span class="number">09</span><h3>发现与检查</h3><p>严格目录分页、搜索、最近访问，以及元数据、统计和封面聚合检查。</p><small>+list · +search · +recent · +inspect</small></article>
+        <article class="domain-card"><span class="number">09</span><h3>文件生命周期</h3><p>创建目录、上传下载、快捷方式、在线对象复制、移动重命名、删除与恢复。</p><small>+upload · +download · +rename · +recycle-restore</small></article>
+        <article class="domain-card"><span class="number">06</span><h3>个人与公开状态</h3><p>回收站清单、收藏闭环和互联网公开状态的独立安全域。</p><small>+star-list · +star-add · +publish-get</small></article>
+        <article class="domain-card"><span class="number">04</span><h3>历史版本</h3><p>版本列表、精确定位、真实字节下载与高风险回滚读回。</p><small>+version-history · +version-download · +version-revert</small></article>
+      </div>
+    </section>
+
+    <section id="compare">
+      <div class="section-head"><div><p class="section-kicker">Lark alignment</p><h2>对齐业务语义，不追求同名率</h2></div><p class="section-desc">38 项逐项核对。评论、导入导出和成员权限在 DWS 由更成熟的 Doc 或原子权限入口承接，不在 Drive 再复制一套。</p></div>
+      <div class="compare">
+        <div class="compare-top">
+          <article class="compare-column covered"><h3>26 · 已覆盖 / 路由</h3><p>上传下载、目录与快捷方式、版本、移动删除、状态、搜索、评论、导入导出和成员任务均有真实入口。</p></article>
+          <article class="compare-column partial"><h3>7 · 部分对齐</h3><p>预览、resolve/reaction、push/pull、权限申请与 setting 受对象模型或接口粒度约束，明确保留有限语义。</p></article>
+          <article class="compare-column gap"><h3>5 · 客观缺口</h3><p>删除评论恢复、普通文件版本删除、安全标签读写、可靠双向目录同步缺少必要下层接口。</p></article>
+        </div>
+        <div class="table-wrap"><table><thead><tr><th>Lark 任务组</th><th>DWS 主路径</th><th>结论</th><th>关键差异与交付决定</th></tr></thead><tbody>
+          <tr><td>upload / folder / shortcut / download</td><td><code>drive +upload</code> 等</td><td><span class="verdict v-ahead">增强</span></td><td>工作目录边界、OSS PUT、严格 commit、no-clobber、原子落盘、非零字节和读回验证。</td></tr>
+          <tr><td>preview / cover</td><td><code>drive +cover</code></td><td><span class="verdict v-partial">部分</span></td><td>封面/缩略图可读；没有等价的服务端多格式预览转换，不扩大宣称。</td></tr>
+          <tr><td>comments / replies</td><td><code>doc +comment-*</code> / <code>doc +review</code></td><td><span class="verdict v-covered">路由</span></td><td>评论归在线文档协作域；独立 resolve、reaction identity 与删除后恢复仍受接口限制。</td></tr>
+          <tr><td>export / import / task result</td><td><code>doc +export</code> / <code>doc +import</code></td><td><span class="verdict v-ahead">增强</span></td><td>提交、轮询、恢复、安全下载形成类型化闭环，不保留泛化下划线命令。</td></tr>
+          <tr><td>version history / get / revert</td><td><code>drive +version-*</code></td><td><span class="verdict v-ahead">增强</span></td><td>严格分页、精确版本、历史字节落盘、回滚前预检与终态读回；历史版本删除无接口。</td></tr>
+          <tr><td>status / inspect</td><td><code>drive +inspect</code></td><td><span class="verdict v-ahead">超越</span></td><td>元数据为必达结果，统计、公开状态和封面按需 fan-out；可选失败为 partial_success。</td></tr>
+          <tr><td>push / pull / sync</td><td><code>+upload</code> / <code>+download</code> 单文件</td><td><span class="verdict v-partial">部分</span></td><td>不在缺少稳定 hash、rename/delete journal 和冲突向量时制造危险目录同步。</td></tr>
+          <tr><td>member / permission</td><td><code>doc +access-*</code> / <code>drive permission</code></td><td><span class="verdict v-covered">路由</span></td><td>协作者权限与互联网公开是两个安全域；申请权限需真实上下文，未伪装为通用 Shortcut。</td></tr>
+          <tr><td>secure labels</td><td>无等价</td><td><span class="verdict v-gap">缺口</span></td><td>当前 DWS/钉钉下层没有 Drive 安全标签目录和写入接口，不能用普通权限代替。</td></tr>
+          <tr><td>search</td><td><code>drive +search</code> / <code>doc +search</code></td><td><span class="verdict v-ahead">增强</span></td><td>文件与在线文档按域路由；文件搜索严格验证数组、过滤和分页。</td></tr>
+        </tbody></table></div>
+      </div>
+      <div class="callout warn" style="margin-top:14px"><strong>普通文件 copy 边界：</strong>钉钉现有复制接口对普通文件产生 <code>.dlink</code>，不是字节独立副本。因此 <code>+copy</code> 只接受在线对象；普通文件快捷入口用 <code>+create-shortcut</code>，独立副本使用 <code>+download</code> 后 <code>+upload</code>。</div>
+    </section>
+
+    <section id="ahead">
+      <div class="section-head"><div><p class="section-kicker">Beyond parity</p><h2>DWS 可主推的八个差异化点</h2></div><p class="section-desc">价值来自正确性与完整闭环，而不是额外注册同义命令。</p></div>
+      <div class="domain-grid">
+        <article class="domain-card"><h3>严格目录语义</h3><p><code>+list</code> / <code>+recent</code> 只有服务端明确返回数组时才接受空集合。</p><small>缺字段 ≠ 空目录</small></article>
+        <article class="domain-card"><h3>聚合检查</h3><p><code>+inspect</code> 一次汇总身份、统计、公开状态和封面，并保留局部失败。</p><small>partial_success 可审计</small></article>
+        <article class="domain-card"><h3>真实文件传输</h3><p>上传执行完整事务；下载验证受控路径、覆盖策略、原子发布和字节。</p><small>不是只返回临时 URL</small></article>
+        <article class="domain-card"><h3>回收恢复闭环</h3><p>从 <code>recycleItemId</code> 恢复后读取真实节点，证明资源确实回到可访问状态。</p><small>恢复后读回</small></article>
+        <article class="domain-card"><h3>个人收藏闭环</h3><p>收藏、列表、取消收藏覆盖完整用户偏好过程，并保留分页。</p><small>add → list → remove</small></article>
+        <article class="domain-card"><h3>版本真实字节</h3><p>除元数据外可下载任意已知历史版本，并用本地字节核验回滚结果。</p><small>version-download</small></article>
+        <article class="domain-card"><h3>重命名终态</h3><p>处理服务端扩展名规则，再读取节点确认最终名称，避免重复扩展名。</p><small>write → read-back</small></article>
+        <article class="domain-card"><h3>公开域诚实降级</h3><p>查询和关闭可验证；开启在 eligible 节点闭环完成前保持 unavailable。</p><small>不把 notSupported 当成功</small></article>
+      </div>
+    </section>
+
+    <section id="truth">
+      <div class="section-head"><div><p class="section-kicker">Truthful execution</p><h2>空数组不再是“看起来成功”</h2></div><p class="section-desc">合法业务空集合可以成功，但必须先证明响应结构、元素类型和分页语义成立。内部错误、缺字段与坏投影必须失败。</p></div>
+      <div class="truth-grid">
+        <article class="truth-card"><h3>四层成功证据</h3>
+          <div class="truth-step"><b>1</b><div><strong>传输成功</strong><span>进程成功，MCP / HTTP 没有显式错误。</span></div></div>
+          <div class="truth-step"><b>2</b><div><strong>响应合同</strong><span>对象、数组、success 标志和元素类型与命令声明一致。</span></div></div>
+          <div class="truth-step"><b>3</b><div><strong>业务终态</strong><span>写命令必须获得新 ID、终态证据或后续元数据读回。</span></div></div>
+          <div class="truth-step"><b>4</b><div><strong>产物校验</strong><span>下载必须落盘、非零字节；关键链路比较大小和 SHA-256。</span></div></div>
+        </article>
+        <article class="truth-card"><h3>明确失败的情况</h3>
+          <ul><li>空响应、缺少预期集合字段或集合类型错误。</li><li>集合存在坏元素，不能投影时静默丢弃。</li><li><code>success=false</code>、写响应没有 ID 或读回不一致。</li><li>inspect 的可选分支失败却返回整体 success。</li><li>下载得到空文件、越界路径或覆盖既有文件。</li><li>普通文件 copy 返回快捷链接却声称独立副本。</li></ul>
+        </article>
+      </div>
+    </section>
+
+    <section id="catalog">
+      <div class="section-head"><div><p class="section-kicker">Full catalog</p><h2>28 个公开 Shortcut 完整目录</h2></div><p class="section-desc">16 个只读、9 个普通写、3 个高风险写；3 个历史入口保留兼容但不作为新 Agent 主路径。</p></div>
+      <div class="toolbar"><input id="q" type="search" placeholder="搜索命令或用途，例如 版本、回收、+inspect…" aria-label="搜索 Shortcut"><select id="domain"><option value="all">全部业务域</option><option value="discover">发现与检查</option><option value="lifecycle">文件生命周期</option><option value="personal">个人与公开</option><option value="version">历史版本</option></select><select id="risk"><option value="all">全部风险</option><option value="read">只读</option><option value="write">普通写</option><option value="high">高风险写</option></select><span id="result-count" class="result-count">显示 28 / 28</span></div>
+      <div class="catalog">
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +list</code></div><div class="row-main"><p>严格分页列出目录，保留游标，区分显式空目录和畸形响应。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +inspect</code></div><div class="row-main"><p>聚合元数据与可选统计、公开状态、封面；局部失败如实报告。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +info</code></div><div class="row-main"><p>历史元数据兼容入口；新场景优先使用 +inspect。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +search</code></div><div class="row-main"><p>按关键词、类型、扩展名、创建人、时间和分页搜索钉盘文件。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +find-file</code></div><div class="row-main"><p>历史文件搜索兼容入口；新场景优先使用 +search。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +search-docs</code></div><div class="row-main"><p>历史跨域搜索入口；新的在线文档搜索路由 doc +search。</p><small>兼容入口</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +recent</code></div><div class="row-main"><p>读取最近访问或编辑列表，支持创建人筛选并保留分页。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +stats</code></div><div class="row-main"><p>读取访问、编辑、评论、点赞、预览和下载统计。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="discover" data-risk="read"><div class="command"><code>dws drive +cover</code></div><div class="row-main"><p>读取封面或缩略图；不宣称服务端多格式预览。</p><small>发现与检查</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +upload</code></div><div class="row-main"><p>上传凭证、OSS PUT、严格提交和远端元数据读回的一体化事务。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="read"><div class="command"><code>dws drive +download</code></div><div class="row-main"><p>安全落盘、no-clobber、原子发布并验证非零字节。</p><small>文件生命周期</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +create-folder</code></div><div class="row-main"><p>创建文件夹后要求新 ID，并读回名称验证。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +create-shortcut</code></div><div class="row-main"><p>创建快捷方式并读回，明确区别于独立副本。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +copy</code></div><div class="row-main"><p>复制在线对象；普通文件预检拒绝，避免把 .dlink 当副本。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +move</code></div><div class="row-main"><p>移动到指定文件夹或知识库位置，语义与 copy/shortcut 消歧。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +rename</code></div><div class="row-main"><p>重命名后读取真实节点，验证最终名称和扩展名。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="high"><div class="command"><code>dws drive +delete</code></div><div class="row-main"><p>将确认过的节点移入回收站，要求 success=true 终态证据。</p><small>文件生命周期</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="lifecycle" data-risk="write"><div class="command"><code>dws drive +recycle-restore</code></div><div class="row-main"><p>按回收项 ID 恢复，并读回恢复后的节点。</p><small>文件生命周期</small></div><div class="badges"><span class="badge write">WRITE · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +recycle-list</code></div><div class="row-main"><p>严格分页列出回收项并稳定投影 recycleItemId。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +star-list</code></div><div class="row-main"><p>严格分页列出当前用户收藏并保留游标。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="write"><div class="command"><code>dws drive +star-add</code></div><div class="row-main"><p>以幂等用户偏好语义收藏指定节点。</p><small>个人与公开</small></div><div class="badges"><span class="badge write">WRITE</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="write"><div class="command"><code>dws drive +star-remove</code></div><div class="row-main"><p>以幂等用户偏好语义取消收藏指定节点。</p><small>个人与公开</small></div><div class="badges"><span class="badge write">WRITE</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="read"><div class="command"><code>dws drive +publish-get</code></div><div class="row-main"><p>只读查询互联网公开状态，不沿用错误的写风险标签。</p><small>个人与公开</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="personal" data-risk="high"><div class="command"><code>dws drive +publish-unset</code></div><div class="row-main"><p>关闭互联网公开并读回验证外链状态。</p><small>个人与公开</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-history</code></div><div class="row-main"><p>严格分页列出普通文件历史版本。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-get</code></div><div class="row-main"><p>按正整数版本号精确匹配，零命中显式失败。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="read"><div class="command"><code>dws drive +version-download</code></div><div class="row-main"><p>预检版本后安全下载历史字节，要求非零产物。</p><small>历史版本</small></div><div class="badges"><span class="badge read">READ</span><span class="badge smart">SMART</span></div></article>
+        <article class="shortcut-row" data-tool data-domain="version" data-risk="high"><div class="command"><code>dws drive +version-revert</code></div><div class="row-main"><p>验证版本存在后回滚，并读取当前节点终态。</p><small>历史版本</small></div><div class="badges"><span class="badge high">HIGH · CONFIRM</span><span class="badge smart">SMART</span></div></article>
+      </div>
+      <div class="callout warn" style="margin-top:14px"><strong>未公开入口：</strong><code>+publish-set</code> 的安全契约和 set→get 读回代码已存在，但真实后端返回 <code>operation.notSupported</code>。在找到 eligible 节点并完成 set→get→unset 闭环前，不进入公开 Agent catalog。</div>
+    </section>
+
+    <section id="e2e">
+      <div class="section-head"><div><p class="section-kicker">Real-data E2E</p><h2>真实数据验证，不用空结果证明成功</h2></div><p class="section-desc">测试在隔离目录创建临时资源，覆盖读取、写入、下载、版本、收藏、回收和清理。资源 ID、账号、URL、上传凭证、绝对路径和业务正文均未进入报告。</p></div>
+      <div class="evidence-grid">
+        <article class="evidence-card"><strong>39,838 B</strong><p>真实文件上传后下载字节数；与源文件 SHA-256 完全一致。</p></article>
+        <article class="evidence-card"><strong>2 versions</strong><p>覆盖写入生成两个版本；精确查询、历史下载和回滚全部读回。</p></article>
+        <article class="evidence-card"><strong>4 / 5</strong><p>隔离夹具中搜索命中 4 项、最近列表命中 5 项，证明非空投影链路。</p></article>
+        <article class="evidence-card"><strong>0 remain</strong><p>测试结束后隔离根目录无残留；临时资源进入回收站并完成本地清理。</p></article>
+      </div>
+      <div class="timeline">
+        <div class="event"><b>创建与发现</b><span>创建两个隔离目录并读回；+list 命中真实节点，由此发现并修复 dentryId 与 32 字符 fileId 混用。</span></div>
+        <div class="event"><b>上传与下载</b><span>真实 OSS 上传、远端元数据读回、下载、no-clobber 二次路径、大小与 SHA-256 一致性全部通过。</span></div>
+        <div class="event"><b>检查与个人状态</b><span>+inspect（含 stats / publish / cover）、+stats、+cover、收藏 add→list→remove 通过。</span></div>
+        <div class="event"><b>版本闭环</b><span>覆盖文件产生两个版本；history/get/download/revert 通过，回滚后最新字节与原始内容一致。</span></div>
+        <div class="event"><b>复制、移动与命名</b><span>在线文档 copy 通过；普通文件 .dlink 被修正为预检拒绝；move 往返、rename 扩展名规范化通过。</span></div>
+        <div class="event"><b>删除与恢复</b><span>delete→recycle-list→recycle-restore 通过，真实回收响应字段已按后端形态修正。</span></div>
+        <div class="event"><b>平台负向证据</b><span>publish-set 对普通文件和在线文档均明确返回不支持，因此保持 unavailable；没有把失败改写成空对象成功。</span></div>
+        <div class="event"><b>清理</b><span>隔离目录进入回收站，根目录残留计数为零；本地下载产物删除。</span></div>
+      </div>
+    </section>
+
+    <section id="review">
+      <div class="section-head"><div><p class="section-kicker">Review prompts</p><h2>建议业务评审重点确认</h2></div><p class="section-desc">这些是需要接受的产品边界，不是被空结果遮蔽的实现问题。</p></div>
+      <div class="review-grid">
+        <article class="review-card"><span class="review-num">01</span><h3>是否接受 26 / 7 / 5 结论？</h3><p>按用户任务计覆盖、部分与缺口，不用同名命令数量代替语义保真。</p></article>
+        <article class="review-card"><span class="review-num">02</span><h3>普通文件 copy 是否足够清晰？</h3><p>服务端无法提供原子独立副本；快捷方式与下载后上传两条替代路径已明确。</p></article>
+        <article class="review-card"><span class="review-num">03</span><h3>是否拒绝不可靠目录 sync？</h3><p>缺稳定 hash、删除/重命名日志和冲突向量时，不发布可能覆盖数据的双向同步。</p></article>
+        <article class="review-card"><span class="review-num">04</span><h3>跨产品路由是否合理？</h3><p>评论、导入导出和协作者权限优先复用 Doc 成熟入口，不在 Drive 制造同义表面。</p></article>
+        <article class="review-card"><span class="review-num">05</span><h3>publish-set 是否继续 unavailable？</h3><p>建议维持，直到真实 eligible 节点完成开启、查询、关闭的可恢复闭环。</p></article>
+        <article class="review-card"><span class="review-num">06</span><h3>下一批后端解锁优先级？</h3><p>建议依次评估普通文件原子 copy、同步所需版本信号、安全标签和评论恢复接口。</p></article>
+      </div>
+    </section>
+  </main>
+
+  <footer><div class="wrap">依据：DWS 最终 Shortcut catalog / Schema、Drive 实现与测试、真实账号 E2E、lark-cli Drive registrations 与实现。范围仅含 Drive Shortcut 及必要跨产品路由；不包含原子命令总表。所有业务标识、凭证、签名 URL、用户信息和正文均已脱敏。</div></footer>
+  <script>
+    const q = document.querySelector('#q');
+    const domain = document.querySelector('#domain');
+    const risk = document.querySelector('#risk');
+    const rows = [...document.querySelectorAll('[data-tool]')];
+    const count = document.querySelector('#result-count');
+    function filterTools() {
+      const needle = q.value.trim().toLocaleLowerCase('zh-CN');
+      let visible = 0;
+      rows.forEach((row) => {
+        const show = (!needle || row.textContent.toLocaleLowerCase('zh-CN').includes(needle)) && (domain.value === 'all' || row.dataset.domain === domain.value) && (risk.value === 'all' || row.dataset.risk === risk.value);
+        row.classList.toggle('hidden-row', !show);
+        if (show) visible += 1;
+      });
+      count.textContent = `显示 ${visible} / ${rows.length}`;
+    }
+    [q, domain, risk].forEach((control) => control.addEventListener('input', filterTools));
+  </script>
+</body>
+</html>
@@ -0,0 +1,82 @@
+# Drive Shortcut 对齐与超越 Lark CLI
+
+## 目标与判定口径
+
+本轮以 Lark CLI `drive` 的 38 个 shortcut 为对照，但不把“同名命令数量”当完成标准。对齐按用户任务判定：
+
+1. `drive +...` 有更稳定的 Agent 主入口时，提供 Shortcut，并发布 Selection、Safety、Result 与 Pagination。
+2. 钉钉已经在其他产品提供更成熟入口时，Skill 明确跨产品路由，不在 Drive 重复实现。
+3. 只有原子能力且 Shortcut 不增加校验、编排或投影价值时，保留 Runtime Schema leaf，不制造同义别名。
+4. 下层接口不存在或无法满足相同语义时，明确记录 gap；不得用空数组、空对象或只返回任务提交结果伪装完成。
+
+成功判定统一为：进程成功 + 统一结果 `ok=true/outcome=success` + 必要业务字段 + 真实数据读回或本地字节校验。服务端显式返回空数组可以是合法业务空结果；空响应、缺少数组、数组类型错误、坏元素、`success=false`、写入缺少终态证据都必须失败。
+
+## Lark 38 项映射
+
+| Lark Drive shortcut | DWS 路由 | 结论与原因 |
+|---|---|---|
+| `+upload` | `drive +upload` | 对齐并增强：工作目录边界、OSS PUT、严格 commit、元数据读回。 |
+| `+create-folder` | `drive +create-folder` | 对齐并增强：要求新 fileId 和名称读回。 |
+| `+create-shortcut` | `drive +create-shortcut` | 对齐并增强：明确 shortcut≠copy，创建后读回。 |
+| `+download` | `drive +download` | 对齐并增强：真实落盘、no-clobber、原子发布、非零字节。 |
+| `+preview` | `drive +cover`（有限） | 不完全对齐：钉钉当前只提供封面/缩略图读取，没有等价的服务端多格式预览转换接口。 |
+| `+cover` | `drive +cover` | 对齐：严格读取封面/缩略图对象。 |
+| `+add-comment` | `doc +comment-create` | 用户任务对齐；评论归在线文档协作域，Drive 不复制一套。 |
+| `+list-comments` | `doc +comment-list` | 用户任务对齐；Doc 已有类型、状态与分页。 |
+| `+batch-query-comments` | `doc +review` / `doc +comment-list` | 超越：可聚合未解决评论与确定性正文上下文；跨文档批量仍由调用方按节点编排。 |
+| `+resolve-comment` | `doc +comment-update`（有限） | 部分对齐：DWS 可更新评论，但当前下层未声明独立 resolve 状态接口。 |
+| `+restore-comment` | 无等价 | gap：钉钉当前下层未暴露恢复已删除评论的等价能力。 |
+| `+add-reply` | `doc +comment-reply` | 对齐。 |
+| `+list-replies` | `doc +comment-list` | 用户任务对齐：评论列表返回回复上下文；无独立 Drive reply 目录。 |
+| `+update-reply` | `doc +comment-update` | 对齐到评论/回复统一更新语义。 |
+| `+delete-reply` | `doc +comment-delete` | 对齐到评论/回复统一删除语义，高风险确认。 |
+| `+react-reply` | `doc +comment-reply`（有限） | 部分对齐：支持表情回复；不声称拥有 Lark 的独立 reaction identity。 |
+| `+export` | `doc +export` | 用户任务对齐并增强：提交、轮询、安全下载一体化。 |
+| `+export-download` | `doc +export` / `doc +export-get` | 超越：常规一体化，`+export-get` 仅作中断恢复。 |
+| `+import` | `doc +import` | 用户任务对齐并增强：转换白名单、上传 fallback、轮询终态。 |
+| `+version-history` | `drive +version-history` | 对齐并增强：严格空结果与分页。 |
+| `+version-get` | `drive +version-get` | 对齐并增强：精确版本号，零命中失败。 |
+| `+version-revert` | `drive +version-revert` | 对齐并增强：版本预检、高风险确认、节点读回。 |
+| `+version-delete` | 无等价 | gap：钉钉当前普通文件版本接口没有删除历史版本能力。 |
+| `+move` | `drive +move` | 对齐；与 copy/shortcut 明确消歧并发布确认。 |
+| `+delete` | `drive +delete` | 对齐；移入回收站、高风险确认、终态证据。 |
+| `+status` | `drive +inspect` | 超越：远端身份、统计、公开状态和封面按需聚合；不伪装成本地同步状态。 |
+| `+push` | `drive +upload`（单文件） | 部分对齐：单文件上传可靠；没有可靠的目录 diff、冲突和远端删除传播语义，因此不提供同名批量 push。 |
+| `+pull` | `drive +download`（单文件） | 部分对齐：单文件下载可靠；目录级增量拉取需稳定路径、hash 与冲突策略，当前接口不完整。 |
+| `+sync` | 无等价 | gap：在缺少稳定远端内容 hash、rename/delete journal 和冲突版本向量时，双向同步会有数据覆盖风险。 |
+| `+task_result` | `doc +export-get` / 导入任务恢复入口 | 用户任务对齐；DWS 按任务所属产品提供类型化恢复入口，不保留 Lark 的下划线泛化命令。 |
+| `+apply-permission` | `drive permission apply` raw leaf | 下层能力存在但未提升为 Shortcut：需要真实申请上下文和权限夹具，无法在通用 E2E 中安全创建。 |
+| `+member-add` | `doc +access-grant` | 用户任务对齐并增强：解析接收人、批量 ledger、首次写入前停止。 |
+| `+member-list` | `drive permission list` / `doc +inspect --include-permissions` | 对齐；常规 Agent 场景优先 Doc 聚合检查。 |
+| `+permission-get-setting` | `drive permission list` + `drive +publish-get` | 部分对齐：协作者与互联网公开是两个独立安全域，没有一个与 Lark setting 完全同构的钉钉接口。 |
+| `+secure-label-list` | 无等价 | gap：当前 DWS/钉钉下层没有可声明的 Drive 安全标签目录接口。 |
+| `+secure-label-update` | 无等价 | gap：没有安全标签写接口，不能用普通权限或公开状态替代。 |
+| `+search` | `drive +search` | 对齐并增强：过滤、严格数组和分页；在线文档搜索路由 `doc +search`。 |
+| `+inspect` | `drive +inspect` | 对齐并增强：必达元数据 + 可选聚合，部分失败不伪装成功。 |
+
+## DWS 超出 Lark Drive 的可挖掘能力
+
+- `+list`：严格目录分页，而不是把缺字段当空目录。
+- `+recent`：最近访问/编辑与创建人筛选。
+- `+stats`：阅读、编辑、评论、点赞、预览和下载统计。
+- `+recycle-list` / `+recycle-restore`：显式回收项身份与恢复后读回。
+- `+star-list` / `+star-add` / `+star-remove`：个人收藏完整闭环。
+- `+publish-get` / `+publish-unset`：互联网公开独立安全域与关闭后读回；`+publish-set` 保留为 unavailable 诊断入口。
+- `+version-download`：历史版本真实字节下载与本地 artifact 校验。
+- `+rename`：写后读回验证。
+
+普通钉盘文件的独立 `copy` 是额外确认出的部分 gap：钉钉当前 `doc/copy_document` 对该对象会生成 `.dlink`，不是字节独立副本。`drive +copy` 因此只接受在线对象；普通文件需要快捷入口时用 `+create-shortcut`，需要独立副本时用 `+download` 后 `+upload`。这不是完整的服务端原子 copy，对大文件也不能宣称完全等价。
+
+互联网公开开启也是账号/对象能力 gap：真实普通文件与在线文档夹具都由服务端返回 `operation.notSupported`。`+publish-get` 与关闭语义可验证，但 `+publish-set` 在找到 eligible 节点完成 set→get→unset 闭环前保持 `unavailable` 且不进入公开 Agent catalog。
+
+## 端到端门禁
+
+每个公开 Drive shortcut 必须至少覆盖：
+
+- Cobra 参数、静态确认、Shortcut Execute、MCP 调度和最终输出；
+- 明确业务空集合、空响应、缺字段、错误类型、坏元素、`success=false`；
+- 写入的 ID/终态证据与读回不一致；
+- 下载的本地路径边界、no-clobber、真实字节数；
+- 真实账号数据：读命令必须命中已知非空夹具或明确验证合法空集合；写命令必须创建隔离资源、读回、必要时下载比对字节并清理。
+
+发布前运行 `make build`、完整 Go 测试、Schema 生成/漂移/策略检查，并保存不含账号业务内容的结构化 E2E 汇总。
@@ -4,7 +4,7 @@ Defines the stable `dws event consume` subprocess contract so an
 orchestrator can determine when the consumer is ready, stop it cleanly,
 and machine-read why it exited.

-Scope of this branch: the five **contract** items below. Reconnect
+Scope of this branch: the six **contract** items below. Reconnect
 resilience (keeping the stream alive across a transient upstream drop) is
 tracked separately and intentionally out of scope here.

@@ -159,6 +159,46 @@ marker; reconnecting an established Stream remains a separate mechanism.
  `terminal_hold`, and identity-scoped cleanup; skill/docs tests pin the
  operational recovery instructions.

+### 6. Host runtime-token handoff
+
+When the root command carries an explicit host-supplied `--token`, personal
+event control requests and the foreground Stream use that token with higher
+priority than local OAuth. A detached bus receives it only through the
+owner-only local IPC transport:
+
+1. The child starts in runtime-token mode with non-sensitive identity and
+   ticket metadata only; neither its argv nor environment contains the token.
+2. The consumer sends `Hello` with `credential_mode=runtime_token`.
+3. The bus advertises the additive `runtime_token_v1` capability and its
+   in-memory credential generation in `HelloAck`.
+4. Only after that capability is confirmed does the consumer send a bounded
+   `credential_update` frame. The bus applies it with generation CAS, replies
+   with `credential_update_ack`, and registers the consumer only on success.
+
+The bus blocks ticket acquisition until the first runtime credential arrives.
+A later invocation may rotate Token A to Token B on a compatible existing bus;
+the current WebSocket remains connected and the next ticket request or natural
+reconnect uses B. If a 401 rejects the current runtime token, only an already
+installed newer generation is retried; the runtime path never refreshes or
+falls back to a local OAuth profile and never suggests `dws auth login`.
+
+Clients do not send a token to a bus that lacks the capability, do not stop
+other consumers automatically, and fail before printing the ready marker. With
+no explicit `--token`, the original OAuth, refresh, profile, and old-client to
+new-bus protocol behavior remains unchanged.
+
+**Verification**
+- T6a: a stale local Token A and root Token B produce control and ticket
+  requests authenticated only with B.
+- T6b: compatible bus reuse supports A-to-B rotation and generation conflicts;
+  401 retries only an already-installed newer runtime token.
+- T6c: an old bus receives no credential and remains running; the new consumer
+  exits before its ready marker.
+- T6d: a canary credential is absent from child argv/environment, dry-run,
+  stdout/stderr, `bus.meta`, `bus.log`, run state, and returned errors.
+- T6e: no-token OAuth, refresh, multi-profile, marker/cache, and bus-reuse tests
+  continue to pass.
+
 ## Out of scope (next branch)

 **Reconnect resilience** — today `personal source` retries only
@@ -0,0 +1,134 @@
+# 独立 `meta.pagination` Schema 方案
+
+## 1. 目标结构
+
+业务结果与分页控制信息分层：
+
+```json
+{
+  "ok": true,
+  "outcome": "success",
+  "data": {
+    "items": [{"id": "a"}]
+  },
+  "meta": {
+    "pagination": {
+      "endpoint_exhausted": false,
+      "next_token": "cursor-2"
+    }
+  }
+}
+```
+
+对应 compact/full leaf Schema：
+
+```json
+{
+  "result": {
+    "outcomes": ["success", "failure"],
+    "data_schema": {
+      "type": "object",
+      "properties": {
+        "items": {
+          "type": "array",
+          "description": "当前页业务记录",
+          "items": {"type": "object"}
+        }
+      }
+    }
+  },
+  "pagination": {
+    "kind": "cursor",
+    "cursor_parameter": "cursor",
+    "meta_path": "meta.pagination",
+    "endpoint_exhausted_path": "meta.pagination.endpoint_exhausted",
+    "next_token_path": "meta.pagination.next_token"
+  }
+}
+```
+
+`result` 只描述 `data`；`pagination` 是与 `result` 同级的命令能力声明。
+
+## 2. 分页状态
+
+| 状态 | `endpoint_exhausted` | `next_token` | Agent 行为 |
+|---|---:|---|---|
+| 可续跑 | `false` | 必须非空 | 将 token 传给 `--<cursor_parameter>` |
+| 已耗尽 | `true` | 必须省略 | 停止翻页 |
+
+`endpoint_exhausted:true` 只表示观察到 Endpoint 分页耗尽，不表示搜索索引
+健康、数据全量覆盖或业务对象不存在。
+
+## 3. 映射规则
+
+产品 mapper 可以读取服务端原始 `hasMore/nextCursor`、`has_more/page_token`
+等字段，但统一 CLI 输出只公布 `meta.pagination`：
+
+- 服务端表示还有下一页且 cursor 非空 → `endpoint_exhausted:false` + token。
+- 服务端表示没有下一页 → `endpoint_exhausted:true`，不带 token。
+- 表示还有下一页但 cursor 缺失、类型错误或证据冲突 → typed
+  `pagination_inconsistent`，禁止伪装终页。
+- mapper 使用同一份上游响应构造 `data` 与 `meta`，不得重新请求。
+
+原始分页控制字段不进入新的 `result.data_schema`。未迁移命令保持 legacy；
+已迁移命令按命令独立切换和回滚，不通过 Agent 参数选择协议。
+
+## 4. Schema 规则
+
+- `kind` 当前只允许 `cursor`。
+- `cursor_parameter` 是真实 canonical CLI flag 名，不带 `--`，并必须存在于
+  同一 leaf 的 `parameters`。
+- 三个 meta path 由框架固定生成，产品不能覆盖。
+- compact/full leaf 同时包含相同的 `result` 和 `pagination`。
+- product/group 导航摘要不复制分页对象；Agent 需要时查询具体 compact leaf。
+- 没有 `pagination` 表示该命令尚未发布经评审的分页能力，Agent 不得猜测。
+
+## 5. 渐进接入
+
+1. **legacy_only**：保持原输出，不公布分页声明。
+2. **dual_validate**：业务执行一次；影子构造并校验 `meta.pagination`，外部
+   legacy 字节不变。
+3. **unified_active**：输出独立 `meta.pagination`，Schema 公布同级
+   `pagination` 声明。
+4. **unified_stable**：Skill、示例和 Agent 审计均只读取 meta 分页。
+
+不增加 `contract_version`、`--output-contract` 或分页协议别名。
+
+## 6. 验收
+
+每个分页命令至少验证：
+
+1. 有下一页时 `endpoint_exhausted:false` 且 token 非空。
+2. 终页和空终页为 `endpoint_exhausted:true` 且无 token。
+3. 分页矛盾产生 typed failure，不 panic、不静默停止。
+4. `cursor_parameter` 在 Help/Schema 中真实存在。
+5. compact/full 的 `result`、`pagination` 分别 JSON 等价。
+6. `data_schema` 不包含分页控制字段。
+7. 运行时 `data` 不包含迁移后的分页控制字段。
+8. dual validate 与 active 都只消费一次上游响应。
+9. Agent 逐命令扫描结果进入评测台账；不提交生成 Schema JSON fixture。
+
+### DevApp 首批落地
+
+以下 8 个终结命令已发布独立 `pagination` Schema；运行时统一输出只在
+`meta.pagination` 返回分页控制信息：
+
+- `dev app list`
+- `dev app permission list`
+- `dev app event list`
+- `dev app version list`
+- `devapp +list`
+- `devapp +permission-list`
+- `devapp +event-list`
+- `devapp +version-list`
+
+两套既有命令前缀继续保留。原子命令的业务记录字段为 `data.items`；Shortcut
+保留既有业务投影（例如 `data.apps`、`data.permissions`、`data.events`、
+`data.versions` 以及 `data.count`），但两套入口都不再在业务数据中公布
+`hasMore/nextCursor`。
+
+## 7. 对齐依据
+
+GWS 用请求参数和 response schema 描述分页事实；Lark 在统一输出层维护分页
+元数据。DWS 采用更明确的分层：业务 `data` 保真承载记录，框架 `meta` 承载
+续跑状态，Schema 用独立能力把 token 与下一次 CLI 参数连接起来。
@@ -17,7 +17,8 @@

 1. 在上述 `Release` 页面选择 `Run workflow`，分支必须是默认分支 `main`。
 2. `release_operation=plan`，选择 `release_channel=beta|stable`；仅在开始新 beta 线时选择 `release_bump=patch|minor|major`。
-3. workflow summary 会给出唯一的下一版本。把对应的精确 `CHANGELOG.md` 章节通过 PR 合入 `main`。
+3. workflow summary 会给出唯一的下一版本。运行 `prepare-changelog.sh` 将已合入的
+   release fragments 汇总成对应的精确 `CHANGELOG.md` 章节，并通过唯一的 release-seal PR 合入 `main`。
 4. 再次运行，改为 `release_operation=publish`。beta 会直接进入自动化发布；stable 会在封 tag 前等待管理员签收。

 `plan` 是纯只读操作，不创建 tag、预留版本号或生成包。CHANGELOG 合入期间若另一个发布先占用了该版本，`publish` 会重新分配并因 CHANGELOG 章节不匹配而拒绝，需要重新 plan。`publish` 会先再次确认 dispatch SHA 仍是当前 `main`、Code Admission 和平台治理均通过，再由唯一的 write job 使用 GitHub API 原子创建 annotated tag；同一次 run 随即进入既有的跨平台构建、GitHub/npm、可选 OSS/Gitee 发布和 Homebrew 直交付 DAG。内置 `GITHUB_TOKEN` 创建的 tag 不依赖第二条 workflow 被再次触发。
@@ -94,7 +95,8 @@ main 上的候选代码 + beta CHANGELOG
 dws-release v1.2.3-beta.1
 ```

-如果 CHANGELOG 尚不存在，该命令只生成模板并停止。补全内容、删除所有 `TODO`，提交后通过 PR 合入 `main`；然后重新运行完全相同的命令，它会执行完整预检：
+如果 CHANGELOG 尚不存在，该命令会从 `.changes/*.md` 生成 beta 章节并归档已消费的
+fragments，然后停止。审阅生成内容并通过唯一的 release-seal PR 合入 `main`；然后重新运行完全相同的命令，它会执行完整预检：

 ```bash
 dws-release v1.2.3-beta.1
@@ -132,6 +134,15 @@ dws-release v1.2.3 --from-beta v1.2.3-beta.1

 正式版使用 `## [1.2.3] - YYYY-MM-DD`。该章节会直接成为 GitHub Release Notes。

+### Release fragments
+
+普通 PR 不修改 `CHANGELOG.md` 的 `Unreleased` 区域。需要面向用户发布说明的改动在
+`.changes/<unique-name>.md` 中增加一个独立 fragment；格式和允许的分类见
+[`.changes/README.md`](../.changes/README.md)。预发封板时
+`scripts/release/prepare-changelog.sh prerelease <version>` 会稳定排序并汇总所有未归档
+fragment，写入唯一版本章节后移动到 `.changes/released/<version>/`。因此并发 PR 不会争用
+`CHANGELOG.md`；唯一的 release-seal PR 同时提交生成的章节与归档移动，供审计复核。
+
 ## CI/CD 保证

 - 只接受 `vX.Y.Z-beta.N` 和 `vX.Y.Z`，且新版本必须高于上一正式版。这里的“上一正式版”必须同时具备公开非草稿 GitHub Release 和同 tag/commit 的成功 Release workflow；只有 tag、没有交付成功的孤儿版本会阻断后续发布，要求走机器核验恢复补齐。云端 tag 会固定 `Release-Run`、requester、commit 和版本分配指纹，交付验证按该精确 run/attempt 及完整 job graph 取证，不接受任意 `workflow_dispatch`。历史版本若曾通过专用 recovery workflow 完成交付，只能使用仓库内 `delivered-stable-recoveries.json` 中精确到 tag、commit、run、workflow SHA 与 attempt 的 reviewed 证据。
@@ -0,0 +1,216 @@
+# RFC：DWS 预制 Skill 安装、升级与模式迁移
+
+| 字段 | 内容 |
+|---|---|
+| 状态 | Accepted / as implemented |
+| 生效范围 | DWS CLI、升级器、npm 与平台安装脚本 |
+| 事实源 | 本 RFC 与当前代码；两者冲突时以代码和测试为准 |
+| 关联合同 | [Skill 内容框架](skill-content-framework.md)、[Mono↔Multi 内容质检](skill-mono-multi-qa.md) |
+
+## 1. 背景
+
+DWS 同时通过 CLI、升级器、npm、Shell 和 PowerShell 分发预制 Skill。multi
+成为默认布局后，所有入口必须对安装集合、模式互斥、失败退出、缓存发布和目录
+所有权保持一致。此前分散的调研、迁移计划、阶段性 roadmap 和 rollout 文档容易
+相互冲突；本 RFC 将最终行为收敛为一个长期合同。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+- 新装与升级默认使用 multi 布局，mono 在兼容期内保留显式 opt-in。
+- 每次升级使用当前版本的官方清单全量覆盖预制 Skill。
+- 删除或替换任何目录前先创建可恢复备份，备份失败不修改该 Agent 目标。
+- 只清理能够证明由 DWS 管理的目录，不通过名称前缀推断所有权。
+- 所有安装入口对部分失败返回非零状态，不误报整体成功。
+- 安装预览、确认和实际执行使用同一份计划。
+
+### 2.2 非目标
+
+- 不建设独立的 `dws skill mode status|set|rollback` 产品面。
+- 不持久化用户对预制 Skill 的本地删除或排除意图。
+- 不提供跨所有 Agent 目标的事务式回滚。
+- 不把市场 Skill 纳入预制 Skill 的升级和清理范围。
+
+## 3. 业内调研
+
+对主流 CLI 与 Agent Skill 分发方式的公开实现进行归纳后，可以得到以下共性：
+
+| 观察 | 对 DWS 的启示 |
+|---|---|
+| 多个产品能力通常以同级 Skill 目录安装，由 Agent 按目录发现 | multi 使用平铺的产品 Skill，并保留一个共享 Skill 承载公共协议 |
+| CLI 本体安装和 Agent Skill 安装是两个生命周期 | DWS 可以在 CLI 安装、setup 和 upgrade 中触发 Skill 同步，但二者的失败与状态必须分别报告 |
+| 生态安装器通常天然采用 multi，不提供 mono/multi 状态机 | DWS 的模式切换保持为重新执行 setup，不新增长期驻留的 mode lifecycle |
+| 市场 Skill 与 CLI 预制 Skill 可能落在同一 Agent 根目录 | 必须使用统一所有权元数据识别受管目录，名称前缀不能作为删除依据 |
+| 多 Skill 更新常以新清单刷新官方集合 | DWS 使用当前 bundle 官方清单全量覆盖，新增 Skill 自动加入，本地删除不视为持久化排除 |
+| 制品可能需要同时服务无运行时依赖、离线和多镜像环境 | DWS 保留 embed、zip 和平台安装脚本，不把单一生态包管理器设为唯一入口 |
+| 中断的复制和原地覆盖容易破坏最后一个可用版本 | 缓存与 Go upgrade 的 Agent 目标采用 staging publish；发布失败自动恢复该目标的完整旧集合 |
+| Agent 通常以 `SKILL.md` 为入口，其他文件按引用或工具规则按需读取 | 安装元数据使用不被内容引用的隐藏文件，并保证其内容不包含 Agent 指令 |
+
+本节只保留可复用的工程结论，不记录具体产品、仓库、版本或逐项能力对照，也不构成
+DWS 对任何外部实现的持续兼容义务。后续设计以 DWS 自身约束和本 RFC 的行为合同为准。
+
+## 4. 布局合同
+
+| 模式 | Agent 目录布局 | 选择方式 |
+|---|---|---|
+| multi（默认） | `<agent-home>/dingtalk-*/` 与必选 `dingtalk-shared/` | 默认；`dws skill setup --mode multi` |
+| mono（兼容） | `<agent-home>/dws/` | `dws skill setup --mode mono` 或安装器的 mono opt-in |
+
+模式切换通过重新执行 setup 完成。安装 multi 前备份并移除 mono 的 `dws/`；安装
+mono 前只备份并移除能够证明由 DWS 管理的 multi 目录。两个方向都不提供隐式、
+不可恢复的删除。
+
+## 5. 官方集合与升级策略
+
+当前版本 bundle 中的 multi 目录清单是升级集合的唯一权威来源。普通 upgrade 和
+`--force` 都安装并覆盖该版本的全部官方预制 Skill：
+
+- 本地删除的预制 Skill 会在下一次升级恢复；
+- setup 时通过 `--exclude` 暂时排除的 Skill 会在下一次升级恢复；
+- 新版本新增的官方 Skill 会自动安装；
+- 用户对预制 Skill 的本地修改会被官方版本覆盖；
+- `dingtalk-shared` 始终随官方集合安装。
+
+`~/.dws/skills-state.json`（设置 `DWS_CONFIG_DIR` 时位于该目录）不参与安装集合
+求解，也不保存排除策略。它既记录结果快照，也集中记录 multi Skill 的所有权和
+provenance，供安全清理、诊断与后续迁移使用。
+
+## 6. 目录所有权
+
+每次 multi setup 或 upgrade 全部成功后，DWS 在统一的
+`~/.dws/skills-state.json` 中写入：
+
+```json
+{
+  "version": "v0.2.14",
+  "official_skills": ["dingtalk-aitable"],
+  "updated_skills": ["dingtalk-aitable"],
+  "managed_skills": [
+    {
+      "name": "dingtalk-aitable",
+      "version": "v0.2.14",
+      "source": "dws-upgrade",
+      "digest": "sha256:<64 个十六进制字符>",
+      "digest_scope": "skill-directory-v1"
+    }
+  ],
+  "updated_at": "2026-08-11T12:34:56Z"
+}
+```
+
+每条 `managed_skills` 记录代表一个由 DWS 管理的官方 Skill。`version` 记录安装该
+副本的 DWS/发布包版本，`source` 记录安装入口，`digest` 是对 bundle 中 Skill 目录
+全部普通文件按相对路径排序后计算的内容摘要。摘要用于诊断和来源追踪，不作为后续
+升级的完整性门禁；用户修改 Skill 内容后，DWS 仍保有明确管理权并能在下一次升级时
+覆盖恢复。
+
+清理 stale Skill 或切换到 mono 时，只接受以下所有权证据：
+
+1. Skill 名称存在于统一状态的 `managed_skills` 中；
+2. 统一状态上线前曾发布过的官方 Skill 精确名称集合。
+
+历史集合是冻结的迁移清单，包含 `dws-shared` 以及已退役、折叠或仍在发布的旧官方
+目录名。仅有 `dingtalk-*` 前缀不构成所有权证据。因此，市场或用户创建的
+`dingtalk-custom` 等非官方精确名称目录不会被迁走。
+
+### 6.1 对 Agent 的影响
+
+Skill 目录内不再放置 DWS 所有权文件，也不增加非通用 frontmatter 字段。支持的
+Agent 仍只需以 `SKILL.md` 发现和加载 Skill；统一元数据位于 Agent Skill 目录之外，
+不会成为提示词上下文或影响 Agent 行为。
+
+## 7. Setup：Plan → Confirm → Execute
+
+`dws skill setup` 分为三个阶段：
+
+1. **Plan**：只读计算目标、安装集合以及所有待备份路径；
+2. **Confirm**：`--dry-run` 和交互确认渲染同一份计划；
+3. **Execute**：确认后严格执行计划中的备份和安装。
+
+安全要求：
+
+- 非交互环境未传 `--yes` 时拒绝执行；
+- 用户拒绝确认时必须零文件写入；
+- 备份失败时跳过整个 Agent 目标，不开始铺设相反布局；
+- 同一目标先完成所有必要备份，再复制新集合；
+- multi Skill 必须在同级 staging 中完成复制，再原子发布到正式目录；
+- 任意 `skipped > 0` 都返回非零退出码，并且不写入完整成功快照；
+- 一个 Agent 目标失败不阻止其他目标尝试，但最终结果仍为失败。
+
+## 8. Upgrade 与恢复语义
+
+升级器对每个 Agent 目标执行：
+
+1. 只读计算对面布局、过期受管 Skill 和同名官方 Skill；
+2. 在目标文件系统的 staging 中复制完整新集合；
+3. staging 全部成功后，才将旧集合移入备份目录；
+4. 逐项发布 staging；任一发布失败时删除已发布的新目录，并逆序恢复该目标的全部旧目录；
+5. 仅在没有目标失败且至少一个目标成功时更新状态快照。
+
+Go upgrade 当前提供 **单 Agent 目标级事务恢复**：复制失败发生在旧目录移动前；
+备份中途失败会恢复此前已移动的目录；发布中途失败会恢复该目标的完整旧集合。不同
+Agent 目标仍彼此独立，一个目标失败不会回滚此前已经成功升级的其他目标，这与
+“不提供跨所有 Agent 目标的事务式回滚”非目标保持一致。
+
+## 9. 备份合同
+
+- 路径：`~/.dws/skill-backups/<UTC 时间戳>/...`；
+- 主要操作：同一文件系统内使用 rename 移动；
+- 失败语义：备份失败时原目录保持不变，目标安装失败；
+- 可见性：计划和执行日志显示原路径与备份路径；
+- 保留策略：自动修剪，仅保留最近 5 批。
+
+备份是安装安全机制，不等于独立 rollback 产品。需要切回 mono 时重新运行
+`dws skill setup --mode mono`。
+
+## 10. 缓存与制品
+
+发布制品和二进制内嵌内容同时携带 mono 与 multi 源树。`~/.dws/skills/` 只是
+setup 在未显式指定 `--source` 时的本地回退缓存。
+
+缓存刷新必须采用同级 staging + publish：
+
+1. 在 staging 中完整复制并验证新树；
+2. 发布前保留旧缓存；
+3. 通过 rename 发布新缓存；
+4. 复制或发布失败时保留或恢复旧缓存；
+5. 空、缺失或损坏的 bundle 不能擦除有效缓存。
+
+## 11. 安装入口一致性
+
+以下入口都遵守本 RFC：
+
+| 入口 | 默认模式 | 失败合同 |
+|---|---|---|
+| `dws skill setup` | multi | 部分失败返回非零；不写完整成功状态 |
+| `dws upgrade` | bundle 含 multi 时安装 multi | 目标失败返回失败；下次全量重试 |
+| `scripts/install.sh` | multi | 任一检测到的目标失败则脚本非零 |
+| `scripts/install.ps1` | multi | 任一检测到的目标失败则脚本非零 |
+| `scripts/install-skills.sh` | multi | 任一检测到的目标失败则脚本非零 |
+| npm `install.js` | multi | 任一检测到的目标失败则 postinstall 失败 |
+
+Homebrew 不直接向 Agent home 铺设 Skill；安装 CLI 后由 setup 执行相同流程。
+
+## 12. 验收与回归门禁
+
+合入和后续修改至少覆盖：
+
+- mono → multi、multi → mono 互斥切换；
+- 状态上线前的官方 multi 目录切换 mono 时能够被精确迁移；
+- 未登记的同前缀市场/用户 Skill 在刷新和切换后仍存在；
+- 统一状态中登记的过期官方 Skill 被备份并移除；
+- 备份、复制、统一状态写入、缓存 publish 故障注入；
+- 非交互确认拒绝与显式 `--yes`；
+- 部分失败返回非零且不写错误状态快照；
+- 复制失败不留下 Agent 可见的残缺官方目录；
+- 普通 upgrade 恢复被删除的预制 Skill，并安装新增官方 Skill；
+- Windows、macOS、Linux 的路径和覆盖率门禁；
+- npm、Shell、PowerShell 与包管理器安装冒烟。
+
+## 13. 后续演进
+
+- 收敛各安装入口中的 Agent home 清单，减少跨语言复制；
+- 如确有运维需求，可单独设计备份查看和显式恢复命令；
+- mono 的物理删除必须作为独立变更，在 multi 内容、安装入口和迁移回归稳定后推进；
+- `managed_skills` 字段若演进，必须同步更新所有安装入口和跨平台回归。
@@ -1,188 +0,0 @@
-# lark-cli Shortcut 深度对齐矩阵
-
-> 12 个 agent 逐条深读 lark 每个 shortcut 的智能实现（Validate/DryRun/ID解析/投影/多步/分页），映射钉钉、标注保真度差距。
-
-## 2026-07-13 最新源码复核
-
-对比基线：
-
- DWS：`feature/shortcut@b7c14c1`（已合并 `origin/main@390b611`）
- lark-cli：`main@e96c4fa5`
- lark-cli 本轮更新范围：`f495cbb1..e96c4fa5`
-
-本轮 lark-cli **没有增加或删除生产 shortcut 命令**，变化集中在已有命令的实现保真度：统一 `--json` shorthand、文档分享锚点读取、whiteboard 本地文件安全内联、VC meeting events 的 identity/timeline/NDJSON 投影、Apps DB 环境自动选择、Drive push 错误分类，以及 Wiki token 解析兼容性。因此下方历史 gap 清单的命令面没有因本轮 pull 新增条目，但若要追平体验，以下实现差距需要上调优先级。
-
-### 当前命令面快照
-
-| 指标 | 数量 | 说明 |
-|---|---:|---|
-| DWS built-in shortcut | 366 | 16 个服务；运行时 registry 实测 |
-| lark-cli primary shortcut | 363 | 19 个服务；排除 `_test.go` 与 42 个 `sheets/backward` 隐藏兼容别名 |
-| 双方可映射服务内命令 | DWS 313 / lark 324 | 12 组产品映射，不含平台特有服务 |
-| 同服务同名命令 | 50 | 仅是名称交集，不等于语义等价或保真度一致 |
-| DWS 平台特有 shortcut | 53 | attendance / ding / oa / report 等 |
-| lark 平台特有 shortcut | 39 | okr / vc / slides / markdown / whiteboard / note / event |
-
-双方重叠服务的命令面如下；“同名”只用于定位，能力判断仍需看参数、验证、多步编排、输出投影和 dry-run：
-
-| 产品映射 | DWS | lark | 同名 |
-|---|---:|---:|---:|
-| aitable ↔ base | 82 | 87 | 31 |
-| calendar ↔ calendar | 23 | 10 | 3 |
-| chat ↔ im | 89 | 21 | 2 |
-| contact ↔ contact | 16 | 2 | 1 |
-| devapp ↔ apps | 30 | 63 | 3 |
-| doc ↔ doc | 19 | 14 | 1 |
-| drive ↔ drive | 9 | 26 | 3 |
-| mail ↔ mail | 10 | 21 | 0 |
-| minutes ↔ minutes | 13 | 9 | 1 |
-| sheet ↔ sheets | 2 | 42 | 0 |
-| todo ↔ task | 13 | 17 | 2 |
-| wiki ↔ wiki | 7 | 12 | 3 |
-
-### 最新优先差距
-
-1. **文档与白板资源保真度**：lark `doc +fetch/+update` 已支持分享链接 selection anchor、HTML5 block 资源引用，以及相对路径内的 SVG/Mermaid/PlantUML whiteboard 安全内联。DWS 具备文档读写和媒体原子能力，但缺少统一引用解析、路径门禁和资源回写编排。
-2. **Sheets typed workflow**：lark 的 typed table、批量样式、维度移动/冻结、range copy/fill/sort、workbook import/export 仍是最大可建设缺口。DWS 原生 helper 已有部分底层能力，但 shortcut 层只有 2 个精选命令，缺少跨 sheet 分块写、类型推断和 partial rollback。
-3. **Drive 本地同步体验**：lark `+push/+pull/+sync/+import/+export` 带批量计划、错误分类、路径保护和版本操作；DWS 目前偏原子上传/搜索，缺完整目录同步和可恢复批处理。
-4. **Mail 高保真写链路**：lark 对 send/reply/reply-all/forward 提供模板、签名、HTML lint、线程头、定时和附件编排；DWS 有底层发信/草稿工具，但 smart shortcut 尚未覆盖这些组合体验。
-5. **消息资源与统一搜索**：DWS 已有 `+search-msg/+chat-messages/+thread-replies/+at-me` 等拆分场景，lark `+messages-search` 仍在统一多维过滤、会话上下文富化、reaction/资源下载方面更完整。
-6. **会议事件输出**：lark `vc +meeting-events` 本轮新增当前身份、actor、会议状态推断、timeline 与 NDJSON 元数据。DWS 最新 main 已有更强的实时 event bus 和个人事件订阅，但尚未沉淀成同等级 shortcut 投影；这是“底层能力领先、shortcut UX 未收口”。
-
-### 不建议机械追平
-
- lark Apps DB、Spark 发布、Lark Drive/Wiki 特有对象模型属于平台差异，不应只为同名率复制。
- DWS 的 attendance、DING、OA、report、agoal 和最新 event bus 是钉钉侧差异化能力，应优先做场景化组合，而不是追求 363 vs 366 的数字对齐。
- DWS 已具备按姓名解析、跨产品智能编排、失败回滚和 usage→自定义 shortcut 沉淀闭环，这些能力无法由同名命令统计体现。
-
-> 注：下方“361 条”汇总是上一轮逐条人工分类的历史基线；当前 lark-cli primary shortcut 是 363 条，另有 42 个不应重复计为能力的 Sheets 隐藏兼容别名。历史条目的判断仍可复用，但总量数字不能直接代表本轮最新覆盖率，后续应把新增条目按 covered-1to1 / covered-smart / gap-buildable / no-dingtalk-tool 四类补录。
-
-## 汇总（361 条 lark shortcut）
-
-| dws_status | 数量 | 含义 |
-|---|:---:|---|
-| covered-1to1 | 144 | lark 组合在钉钉塌缩成 1:1，封装层已覆盖 |
-| no-dingtalk-tool | 127 | 钉钉无对应工具，客观不可对齐 |
-| **gap-buildable** | **41** | 钉钉有工具、值得补成智能 shortcut（**建设目标**）；已建 minutes `+detail`/`+replace-batch`、base `+record-share-links`/`+resolve-base`、im `+thread-replies`/`+chat-messages`/`+chat-list`、task `+related-tasks` |
-| covered-smart | 49 | 已建智能 shortcut / 部分覆盖 |
-
-## 🎯 gap-buildable 目标清单（原 49 条，已建 8 → 剩 41，按服务）
-
-> 已落地：minutes `+detail`（✅ smart `+detail`）、minutes `+word-replace`（✅ smart `+replace-batch`，批量+去重）、base `+record-share-link-create`（✅ smart `+record-share-links`，>20 去重+分片+合并）、im `+threads-messages-list`（✅ smart `chat +thread-replies`，list_topic_replies + 投影）、im `+chat-list`（✅ smart `chat +chat-list`）、task `+get-related-tasks`（✅ smart `todo +related-tasks`，三角色并集+去重+投影）。
-
-### im → chat（7）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+chat-list` ✅ | read | **已建 smart `chat +chat-list`**：`list_all_conversations` + 默认仅群聊 + `--types group/p2p` + `--exclude-muted` + page-size/page-token 别名 + `--page-all/--page-limit` 数字 cursor 自动翻页、跨页去重、合并后类型过滤和完整性 ledger。剩余未做：sort/sort-type、bot 身份 p2p 剥离（DWS 无对应身份模型） |
-| `+chat-messages-list` ✅ | read | **已建 smart `chat +chat-messages`**：群/单聊互斥解析、时间范围、asc/desc、时间边界全量翻页、reaction、资源下载与完整性 ledger |
-| `+chat-search` ✅ | read | **已建 smart `chat +chat-search`**：真实 `search_groups` 关键词搜索 + page-size/page-token 别名 + `--page-all/--page-limit` 不透明 cursor 自动翻页、跨页去重和完整性 ledger。Lark v2 的 member/type/mode/manager/sort 过滤没有可验证的钉钉对应参数，未伪造 |
-| `+flag-list` ✅ | read | **已建 smart `chat +flag-list`**：真实 `list_message_favorites` 的 `items + hasMore + 数字 nextCursor`，支持 page-size/page-token、`--page-all/--page-limit`、跨页去重和完整性 ledger；仅对齐 message favorite，不模拟 Lark Feed thread flag |
-| `+messages-resources-download` | write | dws download-media 走 get_resource_download_url 拿URL，缺分片Range下载/重试/扩展名推断/安全落盘路径校验 |
-| `+messages-search` ✅ | read | **已建 smart `chat +search-msg`**：统一多维过滤、精确时间范围、asc/desc、cursor 全量翻页、mget 富化、reaction、资源下载与完整性 ledger。剩余差异是 Lark chat 上下文和部分 sender/attachment 类型过滤 |
-| `+threads-messages-list` ✅ | read | **已建 smart `chat +thread-replies`**：支持主消息 ID 自动只读解析 conversation/thread，也支持显式 group + thread/topic ID；list_topic_replies + sender/text/time/reaction/resource 投影 + 下层毫秒级 nextCursor 有界自动翻页、跨页去重、完整性 ledger，以及全量结果 asc/desc。与 Lark 的剩余差异是钉钉底层没有服务端 asc 单页，因此 DWS 的 asc 明确要求 `--page-all`，避免伪全局排序 |
-
-### task → todo（3）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+reminder` | write | dws 有 add_todo_reminder/reset_todo_reminder 但无 lark 的先查现有再替换编排、相对时间(15m/1h)解析与互斥校验，值得补智能 shortcut |
-| `+get-related-tasks` ✅ | read | **已建 smart `todo +related-tasks`**：creator+executor+participant 三角色并集 + taskId 去重 + 投影。剩余未做：followed-by-me 成员比对、subtask_count/tasklists 富投影 |
-| `+upload-attachment` | write | dws add-attachment 走 init→PUT→commit 三步 MCP 上传(能力更重)，但无 50MB/regular 校验、applink 提取与 dry-run 计划展示；可对齐成更智能 shortcut |
-
-### calendar → calendar（1）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+room-find` | read | dws 有 room search(query_available_meeting_room 按单一时间段+过滤)和 busy search，但无多slot并发room_find聚合、无city/building/floor/capacity维度过滤、无按attendee推荐可用室，值得补成智能 shortcut 但未建 |
-
-### doc (docs) → doc（2）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+media-insert` | write | dws doc media insert 为3步(取凭证→PUT→insert_document_block)无回滚、无selection定位、无剪贴板、无宽高比补算、无wiki解析；可补成带回滚的智能shortcut |
-| `+media-download` | read | dws doc media download 走resourceId→downloadUrl两段,缺whiteboard导图分支、自动扩展名、路径安全、overwrite防护；media分支可对齐，whiteboard无工具 |
-
-### drive → drive（1）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+import` | write | dws drive upload 有 --workspace --convert 可转在线文档，但缺按目标类型(docx/sheet/bitable/slides)导入、缺 target-token 挂载与异步轮询 |
-
-### mail → mail（4）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+reply` | write | dws reply 走 create_reply_draft+send_draft 两步、附件仅上传会话，缺 EML 线程头构造、签名自动注入、模板合并、HTML lint、读回执、send-time 定时、跨字段校验 |
-| `+reply-all` | write | dws reply-all 两步且收件人由服务端决定，缺原文收件人抽取去重排己、线程头、签名/模板/lint/定时等编排保真 |
-| `+send` | write | dws send_email 单步(附件时先 create_draft 再传再 send)，缺签名/模板/lint/日历内嵌/定时发送/发件人profile解析/跨字段校验 |
-| `+forward` | write | dws forward 走 create_forward_draft+send_draft，缺 Fw:主题/引用块/原附件转载 EML 构建、签名/模板/lint/定时保真 |
-
-### wiki → wiki（1）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+node-get` | read | dws 无 get_node 对应 tool(proxy wiki doc read 读的是文档正文而非节点元数据/space解析)；缺 token/obj_token/URL→node 解析、obj_type推断、space交叉校验——是值得补的智能 shortcut 缺口 |
-
-### minutes → minutes（4）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+search` | read | dws list_by_keyword_and_time_range 只按 keyword+时间+归属(created/shared)过滤，缺 owner/participant 的 me 解析与筛选、缺 query 长度与跨字段互斥校验、缺输出投影与去头像 |
-| `+download` | read | dws 只有 query_minutes_audio_url 返回 OSS 地址(相当于 --url-only 单条)，缺真正落盘下载、批量 fanout+限速+去重、文件名推断、SSRF 防护与覆盖保护 |
-| `+word-replace` ✅ | write | **已建 smart `+replace-batch`**：多组 `原文=>替换` 批量替换 + 去重校验 + 逐组结果聚合（补齐 1:1 `+word-replace` 的单组限制）。剩余未做：@file/stdin 输入 |
-| `+detail` ✅ | read | **已建 smart `+detail`**：单命令按 `--artifacts` fanout basic/summary/keywords/transcript/todos + partial-failure 容错 + rt.Output 投影。剩余未做：wait-ready 轮询、transcript 落盘 |
-
-### base → aitable（10）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+title-resolve` ✅ | read | **已建 smart `aitable +resolve-base`**：search_bases 按名解析 baseId + 0/1/多候选消歧投影。剩余未做：Drive doc_wiki 全文搜索 |
-| `+field-create` | write | dws create_fields 支持批量,但缺 formula/lookup guide-ack 门禁与逐字段节流,可补智能 shortcut |
-| `+field-update` | write | dws update_field 缺 formula/lookup guide-ack 保护 |
-| `+record-share-link-create` ✅ | read | **已建 smart `+record-share-links`**：>20 条记录去重 + 分片(≤20/批) + 跨 aitable-helper server fanout + 合并 {recordId,shareUrl}，补齐单批 20 条上限 |
-| `+record-upload-attachment` | write | dws 只有 prepare_attachment_upload(拿上传凭证),缺 分片上传编排+append_attachments 回填单元格的完整链路 |
-| `+dashboard-block-list` | read | dws 仪表盘块是 chart(create/get/update/delete_chart),缺通用 block list,可对齐补 |
-| `+dashboard-block-get` | read | dws get_chart 覆盖 chart 类块,缺通用 block get |
-| `+dashboard-block-create` | write | dws create_chart 覆盖图表块,缺其他 block 类型的通用创建 |
-| `+dashboard-block-update` | write | dws update_chart 覆盖图表块更新 |
-| `+dashboard-block-delete` | high-risk-write | dws delete_chart 覆盖图表块删除 |
-
-### sheets → sheet（14）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+sheet-hide` | write | dws update_sheet可能含hidden属性但未见独立hide命令,需确认 |
-| `+sheet-unhide` | write | 同上,dws无独立unhide命令 |
-| `+sheet-set-tab-color` | write | dws update_sheet或可设tab色但无独立命令 |
-| `+sheet-show-gridline` | write | dws无网格线显隐命令 |
-| `+sheet-hide-gridline` | write | dws无网格线显隐命令 |
-| `+workbook-create` | write | dws有create_workspace_sheet但仅建空表,缺typed一步建表+填充+样式+partial回滚编排 |
-| `+dim-hide` | write | dws update-dimension或含hidden但无独立hide命令 |
-| `+dim-unhide` | write | 同上,dws无独立unhide命令 |
-| `+dim-freeze` | write | dws update-dimension可能含frozen但无独立freeze命令 |
-| `+cells-get` | read | dws range read存在但缺include样式/公式投影统一封装 |
-| `+table-get` | read | dws缺typed table读回+列类型推断+多sheet编排,只有裸csv/range读 |
-| `+table-put` | write | dws有append/set_cell_range但缺typed多sheet分块写+建缺失sheet+样式+partial回滚编排 |
-| `+rows-resize` | write | dws update-dimension可调尺寸但无独立rows-resize+size/type互斥校验 |
-| `+cols-resize` | write | dws update-dimension可调尺寸但无独立cols-resize+互斥校验 |
-
-### apps → devapp（3）
-
-| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
-|---|---|---|
-| `+release-create` | write | dws 有 create_dev_app_version(开放平台版本)可类比，但妙搭 release 是低代码应用发布、语义与产物不同 |
-| `+release-get` | read | dws 有 get_dev_app_version_detail 可类比但产品域(开放平台vs妙搭)不同 |
-| `+release-list` | read | dws 有 list_dev_app_versions 可类比但无 status 枚举过滤且产品域不同 |
-
-## 已建智能 shortcut（covered-smart，48）— 可继续升级保真度
-
- **im**: +chat-members-list +chat-list +messages-send +threads-messages-list
- **task**: +complete +assign +get-my-tasks +get-related-tasks
- **contact**: +search-user
- **calendar**: +agenda +create +update +freebusy +suggestion
- **doc (docs)**: +history-revert
- **drive**: +upload +search +inspect
- **mail**: +triage
- **minutes**: +upload +latest-minutes +action-items +transcript +minutes-search +detail +replace-batch
- **base**: +table-get +table-create +view-create +view-get-filter +view-set-filter +view-get-visible-fields +view-set-visible-fields +view-get-group +view-set-group +view-get-sort +view-set-sort +view-get-timebar +view-set-timebar +view-get-card +view-set-card +record-list +record-search +record-get +record-upsert +base-create +workflow-list +form-create +form-list +form-get +record-share-link-create
@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-08-06T21:08:26.697858",
-  "count": 357,
+  "generated_at": "2026-08-12T00:10:44.511794",
+  "count": 399,
  "results": [
    {
      "suite": "semantic",
@@ -2162,7 +2162,7 @@
      "risk": "read",
      "status": "reviewed_available",
      "disposition": "primary_smart",
-      "semantic_delta": "接受消息列表直接返回的 threadId（兼容 topicId），拉取回复并输出稳定身份、引用、reaction、resourceRefs、可读正文和时间边界分页；可选对回复资源去重后安全落盘并返回逐项失败 ledger。",
+      "semantic_delta": "接受话题主消息 ID 并通过只读消息详情自动解析 conversation/thread，也接受显式 group + threadId（兼容 topicId）；拉取回复并输出稳定身份、引用、reaction、resourceRefs、可读正文，使用下层毫秒级 nextCursor 安全分页以避免同秒回复漏读，并支持全量结果 asc/desc；可选对回复资源去重后安全落盘并返回逐项失败 ledger。",
      "availability": "available"
    },
    {
@@ -2650,8 +2650,8 @@
      "command": "+history-list",
      "risk": "read",
      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "统一历史版本分页参数并返回可用于回滚的版本列表。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史列表路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-list。",
      "availability": "available"
    },
    {
@@ -2660,8 +2660,8 @@
      "command": "+history-revert",
      "risk": "high-risk-write",
      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "先验证目标版本存在，再执行回滚并读回当前文档状态。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史回滚路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-revert。",
      "availability": "available"
    },
    {
@@ -2670,8 +2670,8 @@
      "command": "+history-save",
      "risk": "write",
      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "以文档历史语义命名手动版本快照，避免暴露底层 RPC 命名。",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留既有历史快照路径及稳定 Schema identity；新的 Agent 场景统一使用 +version-save。",
      "availability": "available"
    },
    {
@@ -2841,7 +2841,7 @@
      "risk": "read",
      "status": "reviewed_available",
      "disposition": "semantic_adapter",
-      "semantic_delta": "按名称检索模板并返回可继续创建的 templateId。",
+      "semantic_delta": "按名称或关键词检索模板并返回可消歧候选和 templateId。",
      "availability": "available"
    },
    {
@@ -2860,8 +2860,8 @@
      "command": "+version-list",
      "risk": "read",
      "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本列表命令及其稳定 Schema identity；新场景优先使用 +history-list。",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "版本浏览的 Agent 主入口；统一分页参数并返回可用于回滚的版本号。",
      "availability": "available"
    },
    {
@@ -2870,8 +2870,8 @@
      "command": "+version-revert",
      "risk": "high-risk-write",
      "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本回滚命令及其稳定 Schema identity；新场景优先使用 +history-revert。",
+      "disposition": "primary_smart",
+      "semantic_delta": "版本回滚的 Agent 主入口；先验证目标版本存在，再回滚并读回当前状态。",
      "availability": "available"
    },
    {
@@ -2880,58 +2880,289 @@
      "command": "+version-save",
      "risk": "write",
      "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留历史版本快照命令及其稳定 Schema identity；新场景优先使用 +history-save。",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "版本快照的 Agent 主入口；只保存当前快照，不隐式修改正文。",
      "availability": "available"
    },
    {
-      "suite": "write",
+      "suite": "semantic",
      "service": "drive",
      "command": "+copy",
      "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "复制前预检在线对象类型；普通钉盘文件因下层只会生成 .dlink 而显式拒绝，避免把快捷方式伪装成独立副本。",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+cover",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取节点封面或缩略图地址；明确不声称服务端多格式预览转换。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+create-folder",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建普通钉盘文件夹后要求 fileId，并读回名称验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+create-shortcut",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "明确 shortcut 与 copy 语义差异，创建后读取新节点验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "将已确认节点移入回收站，要求高风险确认和 success=true 终态证据。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+download",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "不再只返回临时链接；使用受控相对路径、no-clobber、原子发布并验证非零本地字节。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "drive",
      "command": "+find-file",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史文件定位入口；新的 Agent 文件搜索统一使用 +search。",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
      "service": "drive",
      "command": "+info",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史元数据入口；新的 Agent 场景统一使用可扩展的 +inspect。",
+      "availability": "available"
    },
    {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+inspect",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "以文件元数据为必达结果，按需聚合统计、公开状态和封面；可选读取失败显式报告 partial_success。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格区分显式空目录与缺失/畸形响应，稳定投影节点并完整保留分页游标。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "drive",
      "command": "+move",
      "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "移动后原位置不保留，统一 folder/workspace 目标语义并发布静态确认。",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+publish-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "只读查询互联网公开状态和权限，不沿用原子命令错误的写风险标签。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+publish-unset",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "高风险确认后关闭互联网公开，并读回状态验证外链已失效。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "drive",
      "command": "+recent",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格读取最近访问/编辑列表并保留 nextCursor/hasMore，防止嵌套响应被投影为空。",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+recycle-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出回收项并稳定投影 recycleItemId，显式空数组才是空回收站。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+recycle-restore",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "只要求列表可获得的 recycleItemId；恢复响应必须给出节点 ID，随后读回验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+rename",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "重命名后读取真实节点元数据验证最终名称。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "drive",
      "command": "+search",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一关键词、文件类型、扩展名、创建者、时间和分页过滤，并拒绝缺失结果数组。",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
      "service": "drive",
      "command": "+search-docs",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "alias_internal",
+      "semantic_delta": "保留历史跨域文档搜索入口；新的在线文档搜索统一使用 doc +search。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-add",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "以幂等用户偏好语义收藏指定节点。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出当前用户收藏并保留游标。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+star-remove",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "以幂等用户偏好语义取消收藏指定节点。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+stats",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取节点访问、编辑、评论、点赞、预览和下载统计的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+upload",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "组合工作目录边界校验、上传凭证、OSS PUT、严格提交响应和远端元数据读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-download",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "预检版本存在后安全下载历史字节，受控相对路径原子发布且要求非零产物。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按正整数版本号精确匹配元数据；零命中显式失败。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-history",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格分页列出普通文件版本，区分合法空历史与响应契约错误。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "drive",
+      "command": "+version-revert",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先验证目标版本存在，再经高风险确认回滚并读取当前节点状态。",
+      "availability": "available"
    },
    {
      "suite": "read",
@@ -3004,46 +3235,274 @@
      "status": "real-ok"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+action-items",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Resolves the latest task through strict itemList parsing and retrieves extracted Minutes actions without pretending to write Todo objects.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+apply-permission",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Maps view/download/edit intent to policy 4/3/2 and validates the permission-request response.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "minutes",
      "command": "+detail",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Fans out selected artifacts, fully paginates transcript data, validates artifact-specific shapes and returns non-zero on partial reads.",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+download",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Resolves real audio/video URLs, validates response shape and performs batch safe atomic local downloads with an explicit failure ledger.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+export-pack",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Validates selected artifacts, safely publishes a no-clobber local directory and emits a manifest without signed URLs or credentials.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+latest",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Validates the real itemList response and chooses latest only from an explicit comparable timestamp before reading details; +latest-minutes remains a compatibility alias.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "minutes",
      "command": "+list-all",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "Stable projection of all accessible Minutes with strict itemList response validation.",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
      "service": "minutes",
      "command": "+list-mine",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "Stable projection of current-user Minutes with strict itemList response validation.",
+      "availability": "available"
    },
    {
-      "suite": "read",
+      "suite": "semantic",
      "service": "minutes",
      "command": "+list-shared",
      "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "Stable projection of shared Minutes with strict itemList response validation.",
+      "availability": "available"
    },
    {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+mindmap",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Creates the asynchronous mind-graph task exactly once and polls the explicit 0/1/2 taskStatus to success, failure or timeout.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+prepare-asr",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Reads the real personal hot-word set, computes deterministic add/delete differences, defaults to additive changes and verifies final state.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+record-pause",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Friendly recording-pause facade with explicit task UUID validation and confirmation.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+record-resume",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Friendly recording-resume facade with explicit task UUID validation and confirmation.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "minutes",
      "command": "+record-start",
      "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Friendly recording-create facade with explicit confirmation and stable session parameter.",
+      "availability": "available"
    },
    {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+record-stop",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Friendly recording-stop facade with explicit task UUID validation and confirmation.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+record-wrap-up",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Stops recording once, then boundedly waits for selected validated artifacts and preserves taskUuid recovery on partial completion.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
      "service": "minutes",
      "command": "+replace-batch",
      "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Validates multi-rule input, supports JSON/file/stdin and reports partial writes with stop/continue policy and non-zero failure.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+search",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Validated itemList parsing, deterministic title filtering, bounded cursor pagination, de-duplication and completeness ledger; replaces the deprecated +minutes-search discovery route.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+share",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Grants semantic view/download/edit permissions per stable member UID with stop/continue partial-write ledgers and explicit acknowledgements.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+speaker-insights",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Requires a real async taskId, boundedly polls speaker summaries and returns task recovery handles when content is not ready.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+speaker-replace",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Fully paginates the transcript to preflight source speaker presence and verifies the nickname replacement after writing.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+summary",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Reads current summary, supports literal/file/stdin, preserves Markdown images, previews the change and verifies full read-back.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+transcript",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Resolves an explicit or latest task, follows every transcript cursor, de-duplicates paragraphs and publishes completeness.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+unshare",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Removes permission per stable member UID with stop/continue partial-write ledgers and explicit acknowledgements.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "Reads the current title, previews the diff, avoids no-op writes and verifies the final title by read-back.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+upload",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Owns local file validation, create-PUT-complete polling, pre-complete transfer cancellation compensation, unknown-completion recovery and final task read-back verification.",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "minutes",
+      "command": "+upload-and-analyze",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "Completes local upload with compensation, waits for validated artifacts, and optionally orchestrates mind map and speaker insights without re-upload recovery hazards.",
+      "availability": "available"
    },
    {
      "suite": "read",
@@ -2,7 +2,8 @@

 > 本分支权威合同：`skills/mono` / `skills/multi` 的**内容组织**与 zip 内容树形状。  
 > 不做安装/升级行为约定。质检见 [skill-mono-multi-qa.md](skill-mono-multi-qa.md)。  
-> 对齐调研：[skill-wukong-align-plan.md](skill-wukong-align-plan.md)。
+> 安装、升级与模式迁移见
+> [DWS 预制 Skill 安装、升级与模式迁移 RFC](rfc-skill-installation-and-upgrade.md)。

 ## 1. 两棵内容树

@@ -87,18 +88,7 @@ skills/mono/

 质检可断言源树形状；**不**断言安装器默认解压哪棵。

-## 6. 与悟空 `dingtalk-skills/` 对照（组织概念 only）
-
-| 维度 | DWS `skills/multi` | 悟空 `dingtalk-skills/`（develop） |
-|---|---|---|
-| 布局 | flat `dingtalk-*` + `dingtalk-shared` | 同构 flat |
-| 集合 | 产品 skill + shared（含 event/profile/…；dev/skill 等长尾落在 misc） | 更小产品集（如 attendance/report 独立目录） |
-| 质检权威 | **mono 单 skill 树** | 不作为 DWS 覆盖基准 |
-| 不移植 | `_install.sh` / bundle / dual / Qwen overlay | — |
-
-悟空独有命名（如 `dingtalk-attendance`）在 DWS 中由 `dingtalk-misc` 承接对应 mono `attendance*` / `report` / `oa` / `sheet` / `dev` 等面——见覆盖表。
-
-## 7. 变更流程
+## 6. 变更流程

 1. 改 / 增内容 → 更新 `skills/content-qa/mono-multi-coverage.yaml`（coverage 或 omit）  
 2. 跑 `make skill-mono-multi-content`（该独立门禁不包含在默认 `make policy` 中）
@@ -3,6 +3,8 @@
 > 对照基准：`skills/mono`（单 skill）。被测主体：`skills/multi`。  
 > 机读合同：`skills/content-qa/mono-multi-coverage.yaml`。  
 > 执行：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）。
+> 安装、升级与模式迁移见
+> [DWS 预制 Skill 安装、升级与模式迁移 RFC](rfc-skill-installation-and-upgrade.md)。

 ## 1. 质检矩阵

@@ -70,7 +72,3 @@ paired_files:
 | X6 | SAFETY_PREAMBLE_INJECT 无注入器 | **done** | 标记已移除 |

 产品面覆盖：见 YAML `coverage`——mono products 均有 multi 承接（misc 聚合 attendance/oa/sheet/…）。
-
-## 4. 与悟空
-
-借鉴 frontmatter / 断链 / requires 等**检查维度**；不运行悟空 bundle zip 校验脚本。覆盖权威始终是 DWS mono。
@@ -1,272 +0,0 @@
-# DWS multi-skill **内容框架**对齐方案（相对 dws-wukong develop）
-
-> 状态：**执行中** — Phase 1–3 已落地；M2/M3 已补；**M1 recovery 闭环已从 skill 删除（不做移植）**。  
-> 合同短文：[skill-content-framework.md](skill-content-framework.md)  
-> 质检规格：[skill-mono-multi-qa.md](skill-mono-multi-qa.md)  
-> 机读合同：`skills/content-qa/mono-multi-coverage.yaml`  
-> 门禁：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）
->
-> 撰写 / 收窄 / 质检增补 / 执行：2026-08-05  
-> 工作树：`/Users/john/GolandProjects/open-source/dws-multi-skill-align`  
-> 分支：`feat/multi-skill-framework-align`（自 `origin/main` @ `a37e6e68`）  
-> **本分支范围：只做 skill 内容的这个框架**（目录布局、文档契约、共享内容约定、zip 内容树合同、**相对 mono 的内容质检**）。  
-> **不做**安装/升级引擎、agent-home、脚本 skill-install 行为翻转。
->
-> 对照仓：
->
-> | 仓 | 路径 | 基线 |
-> |---|---|---|
-> | DWS OSS CLI（本工作树） | `dws-multi-skill-align` | `origin/main` |
-> | dws-wukong | `~/GolandProjects/open-source/dws-wukong` | `origin/develop` @ `ab76629a`（调研时） |
-> | 行为参考（**另一分支**） | `dws-skill-mode-migration` @ `402429ac`/`d5c8982c` | 安装默认 multi / upgrade 强制 multi —— **不在本分支排期** |
-> | 内容缺口留档（参考） | 同迁移分支 `docs/skill-capability-completion.md`（M1–M6 / X1 等） | **仅作质检目标线索**，非本分支权威 |
-
---
-
-## 0. TL;DR
-
-1. **本分支 = skill 内容框架 + 相对 mono 的内容质检**：固化 `skills/multi` 组织合同，并用 **mono 单 skill 布局作对照基准**做覆盖/结构/漂移门禁（文档 + CI 内容护栏）。
-2. **对齐悟空**：只取内容树组织概念；质检以 **DWS-native** 设计为主（已有 policy/测试可复用）。悟空 `validate-multiskill-bundle.py` 仅借鉴「frontmatter / 断链 / requires」类检查思路，**不**移植 bundle/安装校验。
-3. **安装/升级行为**与 `402429ac`/`d5c8982c` → **单独 follow-up 分支**，本方案只登记。
-4. 质检 **不改**默认安装哪棵树；只保证 multi 内容相对 mono **可解释、可覆盖、可回归**。
-
-### 0.1 IN SCOPE
-
-| 类别 | 包含 |
-|---|---|
-| 内容树结构 | `skills/mono/` 与 `skills/multi/<name>/` 目录合同 |
-| 单 skill 约定 | `SKILL.md` frontmatter / 契约块 / Golden Route；`references/`；可选 `scripts/` |
-| 共享内容 | `dingtalk-shared` 职责与被引用方式；与 mono 全局文映射（文档级） |
-| 命名与集合 | `dingtalk-*` + `dingtalk-shared`；相对悟空的共有/独有清单（文档） |
-| Zip **内容布局合同** | `mono/` / `multi/` / 根 mono 副本的内容含义与树形状；不改安装默认 |
-| **Mono↔multi 内容质检** | 覆盖、结构、漂移三类门禁；复用/扩展现有 policy 与测试；缺口修复属内容编辑（另批或同分支内容 Phase） |
-| 内容架构文档 | 本文件 + 可选短文（架构合同 + 质检矩阵） |
-
-### 0.2 OUT OF SCOPE
-
-| 类别 | 去向 |
-|---|---|
-| 安装默认 multi、upgrade always-multi | Follow-up 分支（`402429ac`/`d5c8982c`） |
-| `LocateSkillsRoot` / `skill_setup` / `paths.go` / `skillhome` / install 脚本行为 | 同上 |
-| 安装/运行时 manifest、state.json、mode 切换、telemetry header | 拒绝或行为分支 |
-| 悟空 `_install.sh` / dual / Qwen / RewindDesktop / pod | 拒绝 |
-| 非 skill 内容的 CLI 功能（schema/shortcut 代码等） | 拒绝 |
-| 把质检做成「改安装默认值」的后门 | 拒绝 |
-
---
-
-## 1. 内容现状盘点
-
-### 1.1 DWS `skills/mono`（质检对照基准 · 单 skill）
-
-```text
-skills/mono/
-├── SKILL.md
-├── references/
-│   ├── products/<area>.md|…/   # 产品能力面（质检「覆盖」主源）
-│   ├── error-codes.md、…  # 全局协议（无 recovery 闭环）
-│   └── best_practices/…
-└── scripts/
-```
-
-### 1.2 DWS `skills/multi`（内容主体）
-
-```text
-skills/multi/
-├── dingtalk-shared/     # 跨产品契约 / routing / 全局协议应落点
-└── dingtalk-*/     # 19 产品 + 各 references、scripts
-```
-
-仅 DWS 有（悟空无）：dev, event, hrbrain, markdown, pat, profile, skill。
-
-### 1.3 悟空 `dingtalk-skills/`（内容组织对照，非质检权威）
-
-Flat `dingtalk-*` + `dingtalk-shared`；单 skill 骨架同构。**不作为 mono 覆盖基准**（集合更小、不同源）。
-
-### 1.4 Zip 内容布局合同
-
-| Zip 路径 | 内容含义 |
-|---|---|
-| `<root>/` | mono 副本（兼容） |
-| `<root>/mono/` | 显式 mono 内容源 |
-| `<root>/multi/` | 与 `skills/multi/` 同构 |
-
-质检可断言「源树形状」；**不**断言安装面默认选哪棵。
-
-### 1.5 现有 DWS skill 内容质检资产（复用清单）
-
-| 资产 | 作用 | 与 mono↔multi 质检关系 |
-|---|---|---|
-| `scripts/policy/check-skill-commands.sh` + `skill-command-check/` | Skill 文内 `dws …` 命令路径存在性 | **复用**（命令真实性）；非覆盖映射 |
-| `scripts/policy/check-skill-context-budget.sh` | chat/event/mono/`dingtalk-shared` 上下文预算与冷启动约束 | **复用**（结构/预算）；可扩展 shared 引用规则 |
-| `scripts/policy/check-multi-im-skill-chain.sh` + `multi-im-skill-chain/` | IM 意图单默认路由、retired scripts、handoff | **复用**（chat/event 链）；面窄 |
-| `test/unit/skill_docs_policy_test.go` | 退役命令、event 扁平输出契约等 | **复用**；可加 mono↔multi 断言 |
-| `test/unit/whiteboard_skill_docs_test.go` | mono/multi whiteboard recipes **字节一致** | **样板**：产品面「同源文件」门禁范式 |
-| `test/skill_static`（`-tags skill_verify`） | 文内命令 vs Cobra；multi 查 flag | **复用**（opt-in 深度）；非 CI 默认全量时可保持 tags |
-| `test/skill_e2e` / `test/run_skill_tests.py` | 执行层 / 用例驱动 | **偏行为**；本分支质检默认不依赖 e2e |
-| `Makefile` → `policy` 含 context-budget、multi-im-skill-chain；`skill-command-integrity` 独立 | 已有 CI 钩子 | 新门禁优先挂同类 policy / `test/unit` |
-
-**缺口（尚无的门禁）**：系统的「mono `references/products/*` → multi 目录/文」覆盖表；frontmatter 全集完备性；orphan scripts。全局协议中 **确认门禁 / Schema 教学已补**；**recovery 闭环已从 skill 移除（不再作为缺口）**。
-
-### 1.6 悟空侧类比质检
-
-| 悟空 | 说明 | 本分支 |
-|---|---|---|
-| `scripts/validate-multiskill-bundle.py` | 校验 **已打好的 bundle zip**：frontmatter keys/category、`requires`、markdown 断链、scenario 编排 | **Adapt 思路** → DWS 源树（`skills/multi` + 对照 mono），不跑 zip 安装语义 |
-| `sync-monolith-to-multiskill.py` | mono→multi 派生 | **不**作默认质检手段；DWS 直接维护 multi |
-
-结论：**DWS-native mono↔multi 质检**；悟空仅参考检查维度。
-
---
-
-## 2. Diff（内容组织 + 质检视角）
-
-### 2.1 已同构
-
-Flat `dingtalk-*` + `dingtalk-shared`；`SKILL.md` + `references/`（+ 可选 `scripts/`）。
-
-### 2.2 分叉与已知内容风险（质检要盯的）
-
-| 风险 ID | 现象（线索） | 质检类型 |
-|---|---|---|
-| **C-cov** | mono `products/*` 能力面在 multi 无对应 skill/reference，或未登记「有意省略」 | 覆盖 |
-| **C-struct** | multi 缺 frontmatter 字段、`references/`、`DWS_RUNTIME_CONTRACT`、对 `dingtalk-shared` 引用不一致 | 结构 |
-| **C-drift-global** | 曾关注 recovery / 确认 / Schema；现确认与 Schema 已在 `dingtalk-shared`，**recovery skill 文档已删除** | 漂移（协议） |
-| **C-drift-orphan** | multi（或 mono）scripts/refs 无文档引用；或 routing 指向无索引产品（留档 X1/M6） | 漂移（孤儿） |
-| **C-pair** | 应对齐的成对文件（如 whiteboard recipes）内容不一致 | 漂移（成对） |
-
-### 2.3 Reject
-
-悟空安装包校验整文件照搬、内容集 19→12 砍产品、安装行为门禁冒充内容质检。
-
---
-
-## 3. Goals / Non-goals
-
-### 3.1 Goals
-
-1. 固化 multi **内容目录合同**与 mono↔multi **映射说明**。  
-2. 建立 **质检矩阵**（覆盖 / 结构 / 漂移）并以 mono 为对照基准；有意省略必须 reviewed 登记。  
-3. **复用** §1.5 资产；新增门禁走 `scripts/policy` 或 `test/unit`，内容-only。  
-4. （可选）纯内容元数据；**禁止**被安装引擎读取改行为。  
-5. 质检失败 → 修 **内容**或更新「有意省略」表，不改 setup/upgrade。
-
-### 3.2 Non-goals
-
-安装/升级翻转；cherry-pick 行为提交；取消产品；悟空客户端；非 skill CLI 功能；用质检驱动默认 multi 安装。
-
---
-
-## 4. 分期（内容框架 + 质检 · 均无安装引擎）
-
-> 批准前 **零编码**（含不实现新 gates）。**已执行**：Phase 1–3 见文首状态。
-
-### Phase 0 — 方案冻结（本文）
-
-| | |
-|---|---|
-| **范围** | 本文件；§7（含质检轨）勾选 |
-| **验收** | owner 重新批准 → ✅「现在开始执行」 |
-
-### Phase 1 — Multi 内容目录合同 + 架构短文 ✅
-
-| | |
-|---|---|
-| **范围** | `skills/multi` 目录合同；与悟空内容树对照表；zip `multi/` 同构合同 |
-| **触达** | `docs/skill-content-framework.md` |
-| **验收** | 可指导「如何新增 dingtalk-* 内容目录」 |
-
-### Phase 2 — Mono↔multi **内容质检规格**（矩阵 + 缺口基线） ✅
-
-| | |
-|---|---|
-| **范围** | 质检规格 + 覆盖/omit 机读表 + 缺口 disposition |
-| **触达** | `docs/skill-mono-multi-qa.md`、`skills/content-qa/mono-multi-coverage.yaml` |
-| **验收** | 矩阵可人工抽查；缺口均有 disposition |
-
-### Phase 3 — 质检落地：CI 内容护栏（复用 + 新 gate） ✅
-
-| | |
-|---|---|
-| **范围** | G1–G4 自动门禁 |
-| **触达** | `test/unit/mono_multi_skill_content_test.go`、`scripts/policy/check-mono-multi-skill-content.sh`、`Makefile` |
-| **验收** | `make skill-mono-multi-content` 绿；已知缺口走 reviewed omit |
-
-### Phase 4 — 可选：内容包元数据 + 缺口修复波次
-
-| | |
-|---|---|
-| **范围 A** | 纯内容 layout/skill 列表元数据（人不读安装器） |
-| **范围 B** | 按 Phase 2 disposition **修内容**：确认 / Schema 已补；**recovery skill 文档已删除（wontfix 移植）**；orphan 脚本仍走 allowlist（M4 等） |
-| **验收** | 元数据不驱动安装；修复项关闭对应质检失败或转入 omit |
-
-### 延期登记（非本分支）
-
-| 主题 | 载体 |
-|---|---|
-| 默认 multi + upgrade always-multi | 行为分支 ← `402429ac`/`d5c8982c` |
-| skillhome / 安装面 bootstrap | 行为分支 |
-
---
-
-## 5. Port / Adapt / Reject
-
-| 项 | 决策 | 说明 |
-|---|---|---|
-| flat + `dingtalk-shared` 内容模型 | **Port** | 已有；合同 + 质检加固 |
-| 悟空 bundle frontmatter/断链/requires 检查维度 | **Adapt** | 做成 DWS 源树门禁，不校验 bundle zip/安装 |
-| whiteboard 式 mono/multi 成对一致 | **Port（范式）** | 推广到 reviewed 文件对 |
-| `validate-multiskill-bundle.py` 整脚本 | **Reject** | 绑定悟空 zip/Qwen 语义 |
-| `_install.sh` / dual / overlay | **Reject** | 非内容 |
-| 行为 cherry-pick | **Defer** | 另分支 |
-
---
-
-## 6. 与 `402429ac` / `d5c8982c`
-
-| | |
-|---|---|
-| 本分支 cherry-pick？ | **否** |
-| 质检是否替代行为翻转？ | **否** |
-| 行为分支 | 另开；可与内容/质检并行 |
-
---
-
-## 7. 批准清单（请重新勾选）
-
-**范围**
-
- [x] 本分支 = skill **内容**框架 + **mono↔multi 内容质检**（§0.1）；无安装/升级引擎  
- [x] `402429ac`/`d5c8982c` 及 setup/paths/install 脚本行为 **不在本分支**  
- [x] 取消产品与悟空客户端链路仍拒绝  
-
-**内容框架 Phase**
-
- [x] **Phase 1**：multi 目录合同 + 悟空内容树对照短文  
-
-**质检轨 Phase**
-
- [x] **Phase 2**：质检矩阵 + mono↔multi 覆盖/缺口基线规格（先文档，可执行）  
- [x] **Phase 3**：CI 内容护栏（G1–G4）—— 本迭代做 / 拆 PR / 只要规格暂不落地  
- [x] 质检失败处置原则：修内容或 reviewed omit，**不**改安装默认  
-
-**可选**
-
- [ ] **Phase 4A** 纯内容元数据：做 / 不做 / 以后  
- [x] **Phase 4B** recovery skill 文档 **removed/wontfix**；确认/Schema 已补；剩余 orphan（M4 等）仍 defer / allowlist  
-
-**Follow-up 知悉**
-
- [ ] 安装默认 multi + upgrade always-multi → **另一分支**  
-
---
-
-## 8. 下一步
-
-**Phase 1–3 已落地**（合同短文 + 质检规格 + `skills/content-qa` + CI 门禁）。  
-Phase 4B：recovery 已删除（不做移植）；确认/Schema 已补。剩余 defer：orphan scripts（M4 等）、LICENSE/NOTICE（M5）、Phase 4A 元数据。  
-安装默认 multi 等行为仍走 **另一分支**。
-
---
-
-*锚点：`skills/mono`、`skills/multi`、§1.5 policy/测试、wukong `dingtalk-skills/`（组织对照 only）。*
@@ -0,0 +1,108 @@
+# DWS 统一命令框架设计概要
+
+> 状态：Framework core 已实现，dingtalk-dev/devapp 首批命令渐进接入中。本文定义框架能力、集成边界和首批 pilot 的发布纪律；其余产品命令迁移、Skill 更新和真实服务复验继续由后续 PR 独立完成。
+
+## 1. 产品裁决
+
+1. 不公开 `--output-contract`，也不增加任何等价别名。
+2. Agent 继续只使用既有 `--format json`。
+3. 每条 terminal command 在一个 release 中只有一个 active wire contract：已迁移命令直接使用统一结果，未迁移命令保持 legacy。
+4. contract 不由用户参数、环境变量、会话能力协商或 Agent 选择。
+5. 回滚是命令声明与发布行为，不改变消费者 argv。
+6. 本 PR 只迁移完成命令级兼容审计的 dingtalk-dev/devapp pilot；其他命令路径、参数和输出保持不变。
+
+## 2. 渐进迁移
+
+内部状态机：
+
+```text
+legacy_only -> dual_validate -> unified_active -> unified_stable -> unified_only
+```
+
+- `legacy_only`：只构造、输出 legacy。
+- `dual_validate`：业务只执行一次；外部仍逐字输出 legacy；同一内存结果 shadow-build 统一结果并严格校验。
+- `unified_active`：`--format json` 直接返回统一结果信封，可按发布声明回退。
+- `unified_stable`：完成真实 Agent 消费观察和兼容窗口。
+- `unified_only`：清理仅服务 legacy 的产品 renderer。
+
+状态是每条 terminal command 的内部发布元数据。Help、Skill、Agent Schema 不展示迁移状态，也不让消费者选择协议。
+
+## 3. 统一结果
+
+统一命令框架表达四类结果：
+
+```text
+success          请求完成且命令认为操作已完成
+pending          请求被受理，但异步操作尚未终结
+partial_failure  批量操作有成功项，也有失败或未知项
+failure          请求或操作失败
+```
+
+JSON 基本形态：
+
+```json
+{
+  "ok": true,
+  "outcome": "success",
+  "data": {}
+}
+```
+
+硬不变量：
+
+```text
+ok == (outcome in {success, pending})
+process rc == 0 <=> ok == true
+top-level error present <=> outcome == failure
+one invocation emits exactly one primary result
+```
+
+框架负责 L1 request outcome 和 L2 operation outcome 的统一表达；L3 verification 必须由产品命令基于业务事实实现，框架不得自动推断 `changed/verified`。
+
+## 4. 输出与错误纪律
+
+- 统一 JSON primary result 写 stdout；stderr 只写诊断。普通命令不把
+  NDJSON 作为通用结果契约；持续事件流若需要逐事件输出，由 event 命令
+  自己声明专用流协议。
+- 分页统一输出到信封 `meta.pagination`，并在命令 Schema 中作为与 `result`
+  同级的 `pagination` 能力声明；`result.data_schema` 只描述业务 data，不再
+  混入分页控制字段。
+- 日志不得污染 stdout。
+- `ok`、`retryable`、`dry_run` 等必须是 JSON boolean。
+- 失败由框架根据 typed error 映射退出码；产品代码不能自报任意 rc。
+- `partial_failure` 保留 `succeeded[]/failed[]/unknown[]`，使用非零 rc 7。
+- `pending` 必须提供 operation id、state 和可执行的 `next_command`。
+- `endpoint_exhausted` 只表示观察到当前 endpoint 分页耗尽；false 必须带 `next_token`，不得扩大成索引健康或业务数据完整。
+- dry-run 是已经完成的无副作用预览，表达为 `success + dry_run:true`，不是 `pending`。
+
+## 5. 重试与超时边界
+
+- 框架只统一表达 `retryable`、`retry_after_seconds` 和 `execution_started`，不自动决定业务操作能否安全重放。
+- 写调用的模糊失败、HTTP timeout 和异步等待预算属于 transport/产品集成范围，不在本 PR 改动。
+- 产品迁移必须证明其重试声明与幂等性、安全等级一致。
+
+## 6. 集成范围
+
+- 产品命令通过 `corecmd.ResultInvoke` 构造 `CommandResult`，由 root 单一出口渲染。
+- 首批 dingtalk-dev/devapp 命令用于验证原子命令与 shortcut 的接入缝；未进入 pilot 的 shortcut、长连接、批量写和异步任务各自需要独立集成 PR。框架 core 不替产品推断 success、pending、partial 或分页事实。
+- 每条 terminal command 独立 rollout；不能整域一次切换，也不能通过 Agent 参数选择协议。
+- 已有命令在进入 `unified_active` 前必须保留 legacy byte golden，并完成真实 Agent 语义扫描。
+
+## 7. 对齐原则
+
+- 对齐 Lark CLI：统一 envelope/emitter、typed error、partial、pending、分页窄语义和强类型结果。
+- 对齐 GWS：机器结果稳定结构化、日志与数据分流、消费者不协商协议版本。
+- DWS 保留差异：声明式 Agent Schema、安全门禁、静态命令与 shortcut 共存，以及四 outcome 模型。
+
+## 8. 发布门禁
+
+命令晋级 `unified_active` 前至少满足：
+
+1. success/failure/dry-run golden；批量或异步命令另有 partial/pending golden。
+2. 业务请求 exactly once；dual validation 不得二次调用服务端。
+3. legacy 命令 stdout/stderr/rc 字节级回归不变。
+4. Help、Schema 和全仓示例不存在协议选择参数。
+5. `--format json` 输出单个合法统一结果文档，stdout 无日志污染。
+6. typed error、进程 rc 与信封 `error.exit_code` 一致。
+7. 安全声明、确认门禁与 dry-run 运行时行为同源。
+8. Agent 语义扫描记录命令级迁移证据；发布回滚无需修改 Agent argv。
@@ -33,6 +33,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/safety"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	upgradepkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -2033,6 +2034,10 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dingtalk-shared", "SKILL.md")); err != nil {
 		t.Fatal(err)
 	}
+	state, readable, err := skillstate.Read(home)
+	if err != nil || !readable || len(state.OfficialSkills) != 3 || len(state.UpdatedSkills) != 2 {
+		t.Fatalf("setup state = %#v, readable=%v, err=%v", state, readable, err)
+	}
 	if output, _, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--dry-run", "--exclude", "b"); err != nil || !strings.Contains(output, "DRY-RUN") {
 		t.Fatalf("multi dry run = %q, %v", output, err)
 	}
@@ -2048,8 +2053,11 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 			t.Fatalf("invalid setup %#v succeeded", args)
 		}
 	}
-	if _, _, err := run("--source", mono, "--target", "agents", "--yes", "--dry-run"); err != nil {
-		t.Fatalf("default mono setup: %v", err)
+	if _, _, err := run("--mode", "mono", "--source", mono, "--target", "agents", "--yes", "--dry-run"); err != nil {
+		t.Fatalf("mono setup: %v", err)
+	}
+	if output, _, err := run("--source", multi, "--target", "agents", "--yes", "--dry-run"); err != nil || !strings.Contains(output, "mode=multi") {
+		t.Fatalf("default mode should be multi: %q, %v", output, err)
 	}
 }

@@ -2082,7 +2090,7 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 	if _, err := listMultiSkillNames(filepath.Join(t.TempDir(), "missing")); err == nil {
 		t.Fatal("missing multi source succeeded")
 	}
-	if mode, err := resolveSkillSetupMode("", true, io.Discard); err != nil || mode != skillSetupModeMono {
+	if mode, err := resolveSkillSetupMode("", true, io.Discard); err != nil || mode != skillSetupModeMulti {
 		t.Fatalf("default setup mode = %q, %v", mode, err)
 	}
 	if _, err := resolveSkillSetupMode("bad", true, io.Discard); err == nil {
@@ -2117,7 +2125,7 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 	for _, tc := range []struct{ path, mode string }{{"", skillSetupModeMono}, {mono, skillSetupModeMono}, {filepath.Dir(multi), skillSetupModeMulti}, {root, "bad"}} {
 		_ = isSkillSourceRoot(tc.path, tc.mode)
 	}
-	t.Setenv("HOME", t.TempDir())
+	setTestHome(t, t.TempDir())
 	for _, tc := range []struct{ target, mode string }{{"agents", skillSetupModeMono}, {"agents", skillSetupModeMulti}, {"all", skillSetupModeMono}, {"missing", skillSetupModeMono}} {
 		_, _ = resolveSkillSetupTargets(tc.target, tc.mode)
 	}
@@ -2125,8 +2133,8 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 	_ = agentHomeForMode("base", skillSetupModeMulti)
 	_ = detectExistingAgentHomes(t.TempDir(), skillSetupModeMono)
 	for _, mode := range []string{skillSetupModeMono, skillSetupModeMulti, "bad"} {
-		_, _ = confirmSkillSetup(io.Discard, mode, root, []string{root}, all)
-		_ = mutualExclusionVictims(root, mode)
+		_, _ = confirmSkillSetup(io.Discard, mode, root, []string{root}, all, false)
+		_, _ = mutualExclusionVictims(root, mode)
 	}
 	if isCharDevice(nil) || isInteractiveTerminal() {
 		t.Fatal("test process unexpectedly interactive")
@@ -2134,17 +2142,17 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {

 	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
 	_ = os.MkdirAll(filepath.Join(filepath.Dir(monoDest), "dingtalk-old"), 0o755)
-	_ = mutualExclusionVictims(monoDest, skillSetupModeMono)
+	_, _ = mutualExclusionVictims(monoDest, skillSetupModeMono)
 	multiDest := filepath.Join(t.TempDir(), "agent")
 	_ = os.MkdirAll(filepath.Join(multiDest, "dws"), 0o755)
-	_ = mutualExclusionVictims(multiDest, skillSetupModeMulti)
+	_, _ = mutualExclusionVictims(multiDest, skillSetupModeMulti)
 	cleanupMutualExclusion(monoDest, skillSetupModeMono, io.Discard, io.Discard)
 	cleanupMutualExclusion(multiDest, skillSetupModeMulti, io.Discard, io.Discard)

 	badParent := filepath.Join(t.TempDir(), "file")
 	_ = os.WriteFile(badParent, []byte("x"), 0o600)
 	_, _, _ = installSkillToHomes(root, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard)
-	_, _, _ = installMultiSkillToHomes(root, []string{"missing"}, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard)
+	_, _, _ = installMultiSkillToHomes(root, []string{"missing"}, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard, true)
 	if err := copyDir(filepath.Join(root, "missing"), t.TempDir()); err == nil {
 		t.Fatal("copy missing directory succeeded")
 	}
@@ -38,6 +38,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/registry"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
@@ -74,7 +75,7 @@ var (

 // newEventCommand returns the `event` parent command and all its subcommands.
 // Wired into root.go's utilityCommands list.
-func newEventCommand() *cobra.Command {
+func newEventCommand(globalFlags ...*GlobalFlags) *cobra.Command {
 	// Product-level Agent routing Decl (migrated from selection/event.json
 	// products.event). Catalog assembly stamps provenance contract_final.
 	contract.RegisterProductDecl(contract.ProductDecl{
@@ -99,12 +100,12 @@ func newEventCommand() *cobra.Command {
 		RunE:              func(c *cobra.Command, _ []string) error { return c.Help() },
 	}
 	cmd.AddCommand(
-		newEventListenIMCommand(),
-		newEventConsumeCommand(),
+		newEventListenIMCommand(globalFlags...),
+		newEventConsumeCommand(globalFlags...),
 		newEventListCommand(),
 		newEventSchemaCommand(),
-		newEventStatusCommand(),
-		newEventStopCommand(),
+		newEventStatusCommandWithFlags(globalFlags...),
+		newEventStopCommandWithFlags(globalFlags...),
 		newEventBusCommand(),
 	)
 	return cmd
@@ -114,7 +115,7 @@ func newEventCommand() *cobra.Command {
 //  event consume
 // ─────────────────────────────────────────────────────────────────────

-func newEventConsumeCommand() *cobra.Command {
+func newEventConsumeCommand(globalFlags ...*GlobalFlags) *cobra.Command {
 	var (
 		eventTypes   []string
 		filter       string
@@ -170,6 +171,8 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 				return err
 			}
 			if as == "user" {
+				personalOpts.ExplicitToken = eventExplicitToken(globalFlags)
+				personalOpts.ClientIDOverride = eventExplicitClientID(globalFlags)
 				personalOpts.EventKeys = dedupePersonalEventKeys(args)
 				personalOpts.EventKey = firstArg(personalOpts.EventKeys)
 				personalOpts.Flatten = flatten
@@ -563,6 +566,8 @@ func newEventBusCommand() *cobra.Command {
 		clientIDOverride string
 		idleTimeout      time.Duration
 		sourceKindRaw    string
+		runtimeTokenMode bool
+		identityHashFlag string
 		streamOpts       eventStreamTicketOptions
 	)
 	cmd := &cobra.Command{
@@ -599,23 +604,45 @@ func newEventBusCommand() *cobra.Command {
 				sourceKind = dwsevent.SourceKindAppStream
 			}
 			if sourceKind == dwsevent.SourceKindPersonalStream {
-				identity, err := eventResolvePersonal(ctx, configDir, streamOpts.SourceID)
-				if err != nil {
-					return failEarly(fmt.Errorf("event _bus: %w", err))
+				var (
+					identity     personal.Identity
+					identityHash string
+				)
+				if runtimeTokenMode {
+					identityHash = strings.TrimSpace(identityHashFlag)
+					if !validPersonalIdentityHash(identityHash) {
+						return failEarly(errors.New("event _bus: --identity-hash must be a 16-character hexadecimal identity hash in runtime token mode"))
+					}
+					if strings.TrimSpace(clientIDOverride) == "" {
+						return failEarly(errors.New("event _bus: --client-id is required in runtime token mode"))
+					}
+					identity = personal.Identity{
+						ClientID: strings.TrimSpace(clientIDOverride),
+						SourceID: personalEventStreamSourceID(streamOpts.SourceID),
+					}
+				} else {
+					var err error
+					identity, err = eventResolvePersonal(ctx, configDir, streamOpts.SourceID)
+					if err != nil {
+						return failEarly(fmt.Errorf("event _bus: %w", err))
+					}
+					if clientIDOverride != "" {
+						identity.ClientID = clientIDOverride
+					}
+					identityHash = dwsevent.IdentityHash(identity.Key())
 				}
-				if clientIDOverride != "" {
-					identity.ClientID = clientIDOverride
-				}
-				identityHash := dwsevent.IdentityHash(identity.Key())
 				editionName := editionNameOrDefault()
 				workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
 				endpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+				credentialBroker := newPersonalCredentialBroker(configDir, runtimeTokenMode, runtimeTokenMode)
 				src, err := eventNewPersonalSource(ctx, personalStreamSourceOptions{
 					ConfigDir:        configDir,
 					Identity:         identity,
 					TicketMode:       streamOpts.Mode,
 					TicketURL:        streamOpts.TicketURL,
 					ClientIDOverride: clientIDOverride,
+					CredentialBroker: credentialBroker,
+					RuntimeTokenMode: runtimeTokenMode,
 				})
 				if err != nil {
 					return failEarly(err)
@@ -628,17 +655,18 @@ func newEventBusCommand() *cobra.Command {
 					}
 				}
 				busCfg := bus.Config{
-					WorkDir:      workDir,
-					IPCEndpoint:  endpoint,
-					ClientID:     identity.ClientID,
-					Edition:      editionName,
-					SourceKind:   dwsevent.SourceKindPersonalStream,
-					IdentityHash: identityHash,
-					SourceID:     identity.SourceID,
-					Source:       src,
-					IdleTimeout:  idleTimeout,
-					ReadyPipe:    readyPipe,
-					Logger:       slog.Default(),
+					WorkDir:          workDir,
+					IPCEndpoint:      endpoint,
+					ClientID:         identity.ClientID,
+					Edition:          editionName,
+					SourceKind:       dwsevent.SourceKindPersonalStream,
+					IdentityHash:     identityHash,
+					SourceID:         identity.SourceID,
+					Source:           src,
+					IdleTimeout:      idleTimeout,
+					ReadyPipe:        readyPipe,
+					Logger:           slog.Default(),
+					CredentialBroker: credentialBroker,
 				}
 				bus.ApplyEnvTuning(&busCfg)
 				return eventBusRun(ctx, busCfg)
@@ -698,12 +726,18 @@ func newEventBusCommand() *cobra.Command {
 		"exit after this long with zero consumers (0 = disabled)")
 	cmd.Flags().StringVar(&sourceKindRaw, "source-kind", string(dwsevent.SourceKindAppStream),
 		"event source kind: app_stream|personal_stream")
+	cmd.Flags().BoolVar(&runtimeTokenMode, "runtime-token-mode", false,
+		"use an owner-injected in-memory runtime credential")
+	cmd.Flags().StringVar(&identityHashFlag, "identity-hash", "",
+		"pre-resolved non-sensitive personal identity hash")
 	cmd.Flags().StringVar(&streamOpts.Mode, "stream-ticket-mode", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_MODE")),
 		"用户 Stream 建联模式：空=SDK app credential；normal/custom=portal 取票")
 	cmd.Flags().StringVar(&streamOpts.SourceID, "stream-source-id", strings.TrimSpace(os.Getenv("DWS_STREAM_SOURCE_ID")),
 		"用户 Stream sourceId；personal_stream 开源版默认 open")
 	cmd.Flags().StringVar(&streamOpts.TicketURL, "stream-ticket-url", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_URL")),
 		"用户 Stream 取票 URL；personal_stream 默认由 MCP base URL 派生")
+	_ = cmd.Flags().MarkHidden("runtime-token-mode")
+	_ = cmd.Flags().MarkHidden("identity-hash")
 	return cmd
 }

@@ -822,6 +856,10 @@ func newEventListCommand() *cobra.Command {
 // ─────────────────────────────────────────────────────────────────────

 func newEventStatusCommand() *cobra.Command {
+	return newEventStatusCommandWithFlags()
+}
+
+func newEventStatusCommandWithFlags(globalFlags ...*GlobalFlags) *cobra.Command {
 	var (
 		all          bool
 		allEditions  bool
@@ -847,6 +885,8 @@ func newEventStatusCommand() *cobra.Command {
 					return fmt.Errorf("event status: %w", err)
 				}
 				personalOpts.Format = formatRaw
+				personalOpts.ExplicitToken = eventExplicitToken(globalFlags)
+				personalOpts.ClientIDOverride = eventExplicitClientID(globalFlags)
 				return eventRunPersonalStatus(c, personalOpts)
 			}
 			if err := rejectChangedFlags(c, "user", "event", "status", "subscribe-id", "personal-event-base-url", "stream-source-id"); err != nil {
@@ -1138,6 +1178,10 @@ func renderStatusBlock(w io.Writer, qs busctl.EntryStatus) {
 }

 func newEventStopCommand() *cobra.Command {
+	return newEventStopCommandWithFlags()
+}
+
+func newEventStopCommandWithFlags(globalFlags ...*GlobalFlags) *cobra.Command {
 	var asIdentity string
 	var opts personalStopOptions
 	cmd := &cobra.Command{
@@ -1158,6 +1202,8 @@ func newEventStopCommand() *cobra.Command {
 			}
 			if as == "user" {
 				opts.SubscribeID = firstArg(args)
+				opts.ExplicitToken = eventExplicitToken(globalFlags)
+				opts.ClientIDOverride = eventExplicitClientID(globalFlags)
 				if eventStopDryRun(c) {
 					return writeEventStopDryRun(c, as, opts)
 				}
@@ -1261,6 +1307,20 @@ func eventStopDryRun(cmd *cobra.Command) bool {
 	return value
 }

+func eventExplicitToken(globalFlags []*GlobalFlags) string {
+	if len(globalFlags) == 0 || globalFlags[0] == nil {
+		return ""
+	}
+	return strings.TrimSpace(globalFlags[0].Token)
+}
+
+func eventExplicitClientID(globalFlags []*GlobalFlags) string {
+	if len(globalFlags) == 0 || globalFlags[0] == nil {
+		return ""
+	}
+	return strings.TrimSpace(globalFlags[0].ClientID)
+}
+
 func writeEventStopDryRun(cmd *cobra.Command, identity string, opts personalStopOptions) error {
 	payload := map[string]any{
 		"dry_run":  true,
@@ -65,7 +65,7 @@ func (eventTargetReader) CallMCPData(product, tool string, params map[string]any

 var eventListenIMReader = func() targetresolver.Reader { return eventTargetReader{} }

-func newEventListenIMCommand() *cobra.Command {
+func newEventListenIMCommand(globalFlags ...*GlobalFlags) *cobra.Command {
 	var opts listenIMOptions
 	cmd := &cobra.Command{
 		Use:   "+listen-im",
@@ -91,6 +91,8 @@ func newEventListenIMCommand() *cobra.Command {
 				StreamTicketMode: opts.StreamTicketMode,
 				StreamTicketURL:  opts.StreamTicketURL,
 				StreamSourceID:   opts.StreamSourceID,
+				ExplicitToken:    eventExplicitToken(globalFlags),
+				ClientIDOverride: eventExplicitClientID(globalFlags),
 				Common: commonConsumeOptions{
 					FormatRaw: "ndjson",
 					MaxEvents: opts.MaxEvents,
@@ -28,6 +28,7 @@ import (

 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 )

@@ -184,6 +185,25 @@ func (r *personalSubscriptionAttemptReservation) completeSuccess() error {
 	return nil
 }

+// releaseRuntimeTokenFailure releases the in-flight claim without recording a
+// cross-invocation hold. A host may supply a fresh token on the very next
+// command, which must be allowed to retry immediately.
+func (r *personalSubscriptionAttemptReservation) releaseRuntimeTokenFailure() error {
+	if r == nil {
+		return runtimecred.ErrRuntimeTokenRejected
+	}
+	if r.store == nil || r.claim == nil {
+		return personalSubscriptionGuardError(errors.Join(
+			runtimecred.ErrRuntimeTokenRejected,
+			errors.New("personal event: subscription attempt reservation is incomplete"),
+		))
+	}
+	if err := r.store.Release(r.claim); err != nil {
+		return personalSubscriptionGuardError(errors.Join(runtimecred.ErrRuntimeTokenRejected, err))
+	}
+	return runtimecred.ErrRuntimeTokenRejected
+}
+
 func (r *personalSubscriptionAttemptReservation) completeFailure(
 	ctx context.Context,
 	failedIndex int,
@@ -14,6 +14,7 @@
 package app

 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
@@ -40,6 +41,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
@@ -82,6 +84,8 @@ type personalConsumeOptions struct {
 	StreamTicketMode string
 	StreamTicketURL  string
 	StreamSourceID   string
+	ExplicitToken    string
+	ClientIDOverride string
 }

 type personalListOptions struct {
@@ -92,19 +96,23 @@ type personalListOptions struct {
 }

 type personalStatusOptions struct {
-	EventKey       string
-	Status         string
-	SubscribeID    string
-	Format         string
-	ControlBaseURL string
-	StreamSourceID string
+	EventKey         string
+	Status           string
+	SubscribeID      string
+	Format           string
+	ControlBaseURL   string
+	StreamSourceID   string
+	ExplicitToken    string
+	ClientIDOverride string
 }

 type personalStopOptions struct {
-	SubscribeID    string
-	All            bool
-	ControlBaseURL string
-	StreamSourceID string
+	SubscribeID      string
+	All              bool
+	ControlBaseURL   string
+	StreamSourceID   string
+	ExplicitToken    string
+	ClientIDOverride string
 }

 type personalStreamSourceOptions struct {
@@ -113,6 +121,8 @@ type personalStreamSourceOptions struct {
 	TicketMode       string
 	TicketURL        string
 	ClientIDOverride string
+	CredentialBroker *runtimecred.Broker
+	RuntimeTokenMode bool
 }

 var (
@@ -142,10 +152,19 @@ var (
 	personalResolveAuxiliaryAccessToken = ResolveAuxiliaryAccessToken
 	personalForceRefreshRejectedToken   = forceRefreshRejectedAccessToken
 	personalLoadTokenData               = authpkg.LoadTokenData
+	personalLoadProfiles                = authpkg.LoadProfiles
 	personalClientID                    = authpkg.ClientID
+	personalRuntimeEventClientID        = runtimePersonalEventClientID
 	personalResolveAppCredentialsStrict = authpkg.ResolveAppCredentialsStrict
 )

+func runtimePersonalEventClientID() string {
+	if clientID := strings.TrimSpace(edition.Get().AuthClientID); clientID != "" {
+		return clientID
+	}
+	return strings.TrimSpace(os.Getenv("DWS_CLIENT_ID"))
+}
+
 func newEventSchemaCommand() *cobra.Command {
 	var asIdentity string
 	var formatRaw string
@@ -283,7 +302,7 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	projector := personalEventProjector(opts.DebugRawEvents, opts.Flatten)

 	configDir := defaultConfigDir()
-	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	identity, err := resolvePersonalEventIdentityForToken(ctx, configDir, opts.StreamSourceID, opts.ExplicitToken, opts.ClientIDOverride)
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
@@ -291,13 +310,24 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	editionName := editionNameOrDefault()
 	workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
 	ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
-	spawnProfileSelector := personalBusProfileSelector(configDir, identity)
+	spawnProfileSelector := ""
+	if strings.TrimSpace(opts.ExplicitToken) == "" {
+		spawnProfileSelector = personalBusProfileSelector(configDir, identity)
+	}
+	spawnArgs := personalBusSpawnArgsForToken(
+		identity,
+		identityHash,
+		opts.StreamTicketMode,
+		opts.StreamTicketURL,
+		spawnProfileSelector,
+		opts.ExplicitToken,
+	)

 	routes, err := consume.ParseRoutes(opts.Common.RoutesRaw)
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", personalSubscriptionValidationError(err))
 	}
-	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity, opts.ExplicitToken)
 	if opts.Common.DryRun {
 		if strings.TrimSpace(opts.SubscribeID) == "" {
 			if err := validatePersonalSubscriptionOptions(opts); err != nil {
@@ -314,7 +344,7 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 			WorkDir:        workDir,
 			IPCEndpoint:    ipcEndpoint,
 			ClientID:       identity.ClientID,
-			SpawnExtraArgs: personalBusSpawnArgs(identity, opts.StreamTicketMode, personalEventStreamTicketURL(opts.StreamTicketURL, configDir), spawnProfileSelector),
+			SpawnExtraArgs: personalBusSpawnArgsForToken(identity, identityHash, opts.StreamTicketMode, personalEventStreamTicketURL(opts.StreamTicketURL, configDir), spawnProfileSelector, opts.ExplicitToken),
 			Compact:        opts.Common.Compact,
 			MaxEvents:      opts.Common.MaxEvents,
 			Duration:       opts.Common.Duration,
@@ -341,7 +371,8 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 		WorkDir:        workDir,
 		IPCEndpoint:    ipcEndpoint,
 		ClientID:       identity.ClientID,
-		SpawnExtraArgs: personalBusSpawnArgs(identity, opts.StreamTicketMode, opts.StreamTicketURL, spawnProfileSelector),
+		SpawnExtraArgs: spawnArgs,
+		RuntimeToken:   strings.TrimSpace(opts.ExplicitToken),
 		Compact:        opts.Common.Compact,
 		MaxEvents:      opts.Common.MaxEvents,
 		Duration:       opts.Common.Duration,
@@ -370,13 +401,25 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 		}
 	}

-	var foregroundSource *source.PersonalSource
+	var (
+		foregroundSource *source.PersonalSource
+		foregroundBroker *runtimecred.Broker
+	)
 	if opts.Common.Foreground {
+		explicitToken := strings.TrimSpace(opts.ExplicitToken)
+		foregroundBroker = newPersonalCredentialBroker(configDir, explicitToken != "", false)
+		if explicitToken != "" {
+			if _, err := foregroundBroker.Update(0, explicitToken); err != nil {
+				return personalSubscriptionValidationError(err)
+			}
+		}
 		foregroundSource, err = personalNewStreamSource(ctx, personalStreamSourceOptions{
-			ConfigDir:  configDir,
-			Identity:   identity,
-			TicketMode: opts.StreamTicketMode,
-			TicketURL:  opts.StreamTicketURL,
+			ConfigDir:        configDir,
+			Identity:         identity,
+			TicketMode:       opts.StreamTicketMode,
+			TicketURL:        opts.StreamTicketURL,
+			CredentialBroker: foregroundBroker,
+			RuntimeTokenMode: explicitToken != "",
 		})
 		if err != nil {
 			return personalSubscriptionValidationError(err)
@@ -398,6 +441,10 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	}
 	sub, eventKey, ruleType, err := personalEnsureSubscription(ctx, client, identity, opts)
 	if err != nil {
+		if strings.TrimSpace(opts.ExplicitToken) != "" && personalRuntimeTokenControlRejection(err) {
+			err = attempt.releaseRuntimeTokenFailure()
+			return fmt.Errorf("event consume --as user: %w", err)
+		}
 		err = attempt.completeFailure(ctx, 0, 0, err, nil)
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
@@ -476,14 +523,15 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	}
 	if opts.Common.Foreground {
 		busCfg := bus.Config{
-			WorkDir:      workDir,
-			IPCEndpoint:  ipcEndpoint,
-			ClientID:     identity.ClientID,
-			Edition:      editionName,
-			SourceKind:   dwsevent.SourceKindPersonalStream,
-			IdentityHash: identityHash,
-			SourceID:     identity.SourceID,
-			Source:       foregroundSource,
+			WorkDir:          workDir,
+			IPCEndpoint:      ipcEndpoint,
+			ClientID:         identity.ClientID,
+			Edition:          editionName,
+			SourceKind:       dwsevent.SourceKindPersonalStream,
+			IdentityHash:     identityHash,
+			SourceID:         identity.SourceID,
+			Source:           foregroundSource,
+			CredentialBroker: foregroundBroker,
 		}
 		bus.ApplyEnvTuning(&busCfg)
 		return personalBusRun(ctx, busCfg)
@@ -517,7 +565,7 @@ func runPersonalEventConsumeMany(c *cobra.Command, opts personalConsumeOptions)

 	ctx := c.Context()
 	configDir := defaultConfigDir()
-	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	identity, err := resolvePersonalEventIdentityForToken(ctx, configDir, opts.StreamSourceID, opts.ExplicitToken, opts.ClientIDOverride)
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
@@ -525,7 +573,10 @@ func runPersonalEventConsumeMany(c *cobra.Command, opts personalConsumeOptions)
 	editionName := editionNameOrDefault()
 	workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
 	ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
-	spawnProfileSelector := personalBusProfileSelector(configDir, identity)
+	spawnProfileSelector := ""
+	if strings.TrimSpace(opts.ExplicitToken) == "" {
+		spawnProfileSelector = personalBusProfileSelector(configDir, identity)
+	}
 	routes, err := consume.ParseRoutes(opts.Common.RoutesRaw)
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", personalSubscriptionValidationError(err))
@@ -534,7 +585,7 @@ func runPersonalEventConsumeMany(c *cobra.Command, opts personalConsumeOptions)
 		WorkDir:        workDir,
 		IPCEndpoint:    ipcEndpoint,
 		ClientID:       identity.ClientID,
-		SpawnExtraArgs: personalBusSpawnArgs(identity, opts.StreamTicketMode, personalEventStreamTicketURL(opts.StreamTicketURL, configDir), spawnProfileSelector),
+		SpawnExtraArgs: personalBusSpawnArgsForToken(identity, identityHash, opts.StreamTicketMode, personalEventStreamTicketURL(opts.StreamTicketURL, configDir), spawnProfileSelector, opts.ExplicitToken),
 		Compact:        opts.Common.Compact,
 		MaxEvents:      opts.Common.MaxEvents,
 		Duration:       opts.Common.Duration,
@@ -560,8 +611,9 @@ func runPersonalEventConsumeMany(c *cobra.Command, opts personalConsumeOptions)
 		printPersonalMultiDryRun(c.ErrOrStderr(), baseCfg, plans)
 		return nil
 	}
+	baseCfg.RuntimeToken = strings.TrimSpace(opts.ExplicitToken)

-	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity, opts.ExplicitToken)
 	attempt, err := reservePersonalSubscriptionAttempts(
 		workDir,
 		client,
@@ -598,6 +650,10 @@ func runPersonalEventConsumeMany(c *cobra.Command, opts personalConsumeOptions)
 		if personalSubscriptionCanceled(ctx, cause) {
 			cleanupCtx = ctx
 		}
+		if strings.TrimSpace(opts.ExplicitToken) != "" && personalRuntimeTokenControlRejection(cause) {
+			cleanup(cleanupCtx)
+			return attempt.releaseRuntimeTokenFailure()
+		}
 		completed := attempt.completeFailure(ctx, failedIndex, succeededCount, cause, override)
 		// Persist the hold (or release a canceled claim) before any potentially
 		// slow remote rollback. Otherwise the attempt lease can expire while
@@ -985,7 +1041,7 @@ func runPersonalEventStatus(c *cobra.Command, opts personalStatusOptions) error
 		return err
 	}
 	configDir := defaultConfigDir()
-	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	identity, err := resolvePersonalEventIdentityForToken(ctx, configDir, opts.StreamSourceID, opts.ExplicitToken, opts.ClientIDOverride)
 	if err != nil {
 		return fmt.Errorf("event status --as user: %w", err)
 	}
@@ -1017,7 +1073,7 @@ func runPersonalEventStatus(c *cobra.Command, opts personalStatusOptions) error
 	if status == "" || status == "all" {
 		status = ""
 	}
-	subs, err := personalListSubscriptions(newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity), ctx, personal.ListOptions{
+	subs, err := personalListSubscriptions(newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity, opts.ExplicitToken), ctx, personal.ListOptions{
 		Status:      status,
 		EventKey:    opts.EventKey,
 		SubscribeID: opts.SubscribeID,
@@ -1038,6 +1094,15 @@ func runPersonalEventStatus(c *cobra.Command, opts personalStatusOptions) error
 	return nil
 }

+func personalRuntimeTokenControlRejection(err error) bool {
+	var apiErr *personal.APIError
+	if !errors.As(err, &apiErr) || apiErr == nil {
+		return false
+	}
+	return apiErr.HTTPStatus == http.StatusUnauthorized ||
+		strings.EqualFold(strings.TrimSpace(apiErr.Code), "RUNTIME_TOKEN_REJECTED")
+}
+
 func ensurePublicPersonalEvent(eventKey string) error {
 	eventKey = strings.TrimSpace(eventKey)
 	if eventKey == "" {
@@ -1120,7 +1185,7 @@ func runPersonalEventStop(c *cobra.Command, opts personalStopOptions) error {
 	}

 	configDir := defaultConfigDir()
-	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	identity, err := resolvePersonalEventIdentityForToken(ctx, configDir, opts.StreamSourceID, opts.ExplicitToken, opts.ClientIDOverride)
 	if err != nil {
 		return fmt.Errorf("event stop --as user: %w", err)
 	}
@@ -1132,7 +1197,7 @@ func runPersonalEventStop(c *cobra.Command, opts personalStopOptions) error {
 	if err != nil {
 		return fmt.Errorf("event stop --as user: %w", err)
 	}
-	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity, opts.ExplicitToken)
 	for _, id := range subscribeIDs {
 		if err := personalDeleteSubscription(client, ctx, id); err != nil {
 			return fmt.Errorf("event stop --as user: cancel subscription %s: %w", id, err)
@@ -1248,6 +1313,138 @@ func printPersonalStopResult(w io.Writer, subscribeIDs []string, single bool, bu
 	fmt.Fprintf(w, "cancelled %d personal subscription(s); %s\n", len(subscribeIDs), busState)
 }

+func resolvePersonalEventIdentityForToken(ctx context.Context, configDir, sourceIDOverride, explicitToken string, clientIDOverrides ...string) (personal.Identity, error) {
+	explicitToken = strings.TrimSpace(explicitToken)
+	if explicitToken == "" {
+		return personalResolveEventIdentity(ctx, configDir, sourceIDOverride)
+	}
+	clientIDOverride := ""
+	if len(clientIDOverrides) > 0 {
+		clientIDOverride = strings.TrimSpace(clientIDOverrides[0])
+	}
+	return resolvePersonalEventIdentityWithToken(ctx, configDir, sourceIDOverride, explicitToken, clientIDOverride)
+}
+
+// resolvePersonalEventIdentityWithToken resolves only non-sensitive identity
+// metadata around a caller-supplied bearer token. It intentionally does not
+// call LoadTokenData or any refresh-capable token resolver: an explicit root
+// --token must never be replaced with, persisted into, or used to refresh a
+// local OAuth profile.
+func resolvePersonalEventIdentityWithToken(ctx context.Context, configDir, sourceIDOverride, explicitToken string, clientIDOverrides ...string) (personal.Identity, error) {
+	explicitToken = strings.TrimSpace(explicitToken)
+	if explicitToken == "" {
+		return resolvePersonalEventIdentity(ctx, configDir, sourceIDOverride)
+	}
+	if strings.Contains(strings.TrimSpace(authpkg.RuntimeProfile()), ",") {
+		return personal.Identity{}, fmt.Errorf("personal events require exactly one --profile")
+	}
+
+	corpID := resolveRuntimeDefault(ctx, "$corpId")
+	userID := resolveRuntimeDefault(ctx, "$currentUserId")
+	clientID := ""
+	if len(clientIDOverrides) > 0 {
+		clientID = strings.TrimSpace(clientIDOverrides[0])
+	}
+	if clientID == "" {
+		// An edition hook or explicit environment value is runtime identity,
+		// not persisted app state. Resolve it before profiles.json so a complete
+		// host context never depends on local OAuth metadata health.
+		clientID = strings.TrimSpace(personalRuntimeEventClientID())
+	}
+	explicitProfile := strings.TrimSpace(authpkg.RuntimeProfile()) != ""
+	if explicitProfile || corpID == "" || userID == "" || clientID == "" {
+		profile, err := personalEventProfileMetadata(configDir)
+		if err != nil {
+			// A user-selected --profile remains a strict contract. Without an
+			// explicit selector, profiles.json is optional metadata for a
+			// host-managed bearer: malformed or stale persisted state must not
+			// override complete runtime defaults or prevent the later global
+			// client-id fallback.
+			if explicitProfile {
+				return personal.Identity{}, fmt.Errorf("load OAuth identity metadata: %w", err)
+			}
+			profile = nil
+		}
+		if profile != nil {
+			if corpID == "" {
+				corpID = strings.TrimSpace(profile.CorpID)
+			}
+			if userID == "" {
+				userID = strings.TrimSpace(profile.UserID)
+			}
+			if clientID == "" {
+				clientID = strings.TrimSpace(profile.ClientID)
+			}
+		}
+	}
+	if clientID == "" {
+		// Persisted/global app credentials are only a fallback after the
+		// selected profile, so an old app config cannot override profile.ClientID.
+		clientID = strings.TrimSpace(personalClientID())
+	}
+	if clientID == "" {
+		if id, _, _, _, resolveErr := personalResolveAppCredentialsStrict(configDir); resolveErr == nil {
+			clientID = strings.TrimSpace(id)
+		}
+	}
+	if clientID == "" {
+		return personal.Identity{}, fmt.Errorf("cannot resolve OAuth client_id for personal events")
+	}
+
+	sourceID := strings.TrimSpace(sourceIDOverride)
+	if sourceID == "" {
+		sourceID = personalEventStreamSourceID("")
+	}
+	localSubject := ""
+	if corpID == "" || userID == "" {
+		localSubject = personalTokenSubject("access", explicitToken)
+	}
+	return personal.Identity{
+		LocalSubject: localSubject,
+		CorpID:       corpID,
+		UserID:       userID,
+		ClientID:     clientID,
+		SourceID:     sourceID,
+	}, nil
+}
+
+func personalEventProfileMetadata(configDir string) (*authpkg.Profile, error) {
+	cfg, err := personalLoadProfiles(configDir)
+	if err != nil {
+		return nil, err
+	}
+	selector := strings.TrimSpace(authpkg.RuntimeProfile())
+	explicitSelector := selector != ""
+	if strings.Contains(selector, ",") {
+		return nil, fmt.Errorf("personal events require exactly one --profile")
+	}
+	if cfg == nil || len(cfg.Profiles) == 0 {
+		if explicitSelector {
+			return nil, fmt.Errorf("profile %q not found", selector)
+		}
+		return nil, nil
+	}
+	if selector == "" {
+		selector = strings.TrimSpace(cfg.CurrentProfile)
+	}
+	if selector == "" {
+		return nil, nil
+	}
+	profile, err := selectPersonalEventProfileMetadata(cfg, selector, make(map[string]struct{}))
+	if err != nil && !explicitSelector {
+		// A stale persisted CurrentProfile must not make a host-provided bearer
+		// unusable. Runtime defaults and the one-way local subject are sufficient
+		// to isolate the event bus without consulting local OAuth credentials.
+		return nil, nil
+	}
+	return profile, err
+}
+
+func selectPersonalEventProfileMetadata(cfg *authpkg.ProfilesConfig, selector string, visited map[string]struct{}) (*authpkg.Profile, error) {
+	_ = visited // retained for the focused compatibility seam used by app tests.
+	return authpkg.ResolveProfileMetadata(cfg, strings.TrimSpace(selector))
+}
+
 func resolvePersonalEventIdentity(ctx context.Context, configDir string, sourceIDOverride string) (personal.Identity, error) {
 	accessToken, err := personalResolveAuxiliaryAccessToken(ctx, configDir, "")
 	if err != nil {
@@ -1302,7 +1499,11 @@ func resolvePersonalEventIdentity(ctx context.Context, configDir string, sourceI
 	}, nil
 }

-func newPersonalEventControlClient(configDir, baseURL string, identity personal.Identity) *personal.Client {
+func newPersonalEventControlClient(configDir, baseURL string, identity personal.Identity, explicitTokens ...string) *personal.Client {
+	explicitToken := ""
+	if len(explicitTokens) > 0 {
+		explicitToken = strings.TrimSpace(explicitTokens[0])
+	}
 	identity.AccessToken = ""
 	client := personal.NewClient(baseURL, identity)
 	version := strings.TrimSpace(RawVersion())
@@ -1311,12 +1512,146 @@ func newPersonalEventControlClient(configDir, baseURL string, identity personal.
 	}
 	client.ClientVersion = version
 	client.UserAgent = "dws-cli/" + version
-	client.AccessTokenProvider = func(ctx context.Context) (string, error) {
-		return personalResolveAuxiliaryAccessToken(ctx, configDir, "")
+	if explicitToken != "" {
+		client.AccessTokenProvider = func(context.Context) (string, error) { return explicitToken, nil }
+		client.HTTPClient.Transport = runtimeTokenControlTransport{base: http.DefaultTransport, token: explicitToken}
+		client.HTTPClient.CheckRedirect = runtimeTokenRedirectPolicy
+	} else {
+		client.AccessTokenProvider = func(ctx context.Context) (string, error) {
+			return personalResolveAuxiliaryAccessToken(ctx, configDir, "")
+		}
 	}
 	return client
 }

+// runtimeTokenRedirectPolicy prevents Go's redirect machinery from copying
+// DWS's custom x-user-access-token header to another authority. Returning
+// ErrUseLastResponse keeps the 3xx response available to the caller without a
+// url.Error that could echo an attacker-controlled Location value.
+func runtimeTokenRedirectPolicy(req *http.Request, via []*http.Request) error {
+	if len(via) == 0 || req == nil || req.URL == nil || via[0] == nil || via[0].URL == nil {
+		return http.ErrUseLastResponse
+	}
+	origin := via[0].URL
+	if !strings.EqualFold(strings.TrimSpace(req.URL.Host), strings.TrimSpace(origin.Host)) {
+		return http.ErrUseLastResponse
+	}
+	if strings.EqualFold(origin.Scheme, "https") && !strings.EqualFold(req.URL.Scheme, "https") {
+		return http.ErrUseLastResponse
+	}
+	return nil
+}
+
+const runtimeTokenControlErrorBody = `{"code":"RUNTIME_TOKEN_REJECTED","message":"event runtime token was rejected; retry with a fresh host credential"}`
+
+// runtimeTokenControlTransport scrubs an explicit bearer from every response
+// body and diagnostic header before the control client decodes or logs it. A
+// 401 is replaced with a fixed rejection envelope so untrusted response text
+// can never escape through stderr or debug logs.
+type runtimeTokenControlTransport struct {
+	base  http.RoundTripper
+	token string
+}
+
+func (t runtimeTokenControlTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	base := t.base
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	resp, err := base.RoundTrip(req)
+	if err != nil {
+		if token := strings.TrimSpace(t.token); token != "" && strings.Contains(err.Error(), token) {
+			return nil, errors.New("personal event: runtime-token control request failed")
+		}
+		return nil, err
+	}
+	if resp == nil {
+		return resp, err
+	}
+	token := strings.TrimSpace(t.token)
+	for key, values := range resp.Header {
+		for i := range values {
+			if token != "" {
+				values[i] = strings.ReplaceAll(values[i], token, "<redacted-runtime-token>")
+			}
+		}
+		resp.Header[key] = values
+	}
+	var responseBody []byte
+	if resp.Body != nil {
+		responseBody, err = io.ReadAll(io.LimitReader(resp.Body, config.MaxResponseBodySize))
+		_ = resp.Body.Close()
+		if err != nil {
+			return nil, errors.New("personal event: read runtime-token control response")
+		}
+	}
+	if resp.StatusCode == http.StatusUnauthorized {
+		responseBody = []byte(runtimeTokenControlErrorBody)
+	} else if token != "" {
+		responseBody = redactRuntimeTokenResponseBody(responseBody, token)
+	}
+	resp.Body = io.NopCloser(bytes.NewReader(responseBody))
+	resp.ContentLength = int64(len(responseBody))
+	if resp.Header == nil {
+		resp.Header = make(http.Header)
+	}
+	resp.Header.Set("Content-Type", "application/json")
+	resp.Header.Set("Content-Length", fmt.Sprintf("%d", len(responseBody)))
+	return resp, nil
+}
+
+func redactRuntimeTokenResponseBody(data []byte, token string) []byte {
+	token = strings.TrimSpace(token)
+	if len(data) == 0 || token == "" {
+		return data
+	}
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.UseNumber()
+	var decoded any
+	if err := decoder.Decode(&decoded); err == nil {
+		var trailing any
+		if trailingErr := decoder.Decode(&trailing); errors.Is(trailingErr, io.EOF) {
+			if redacted, changed := redactRuntimeTokenJSONValue(decoded, token); changed {
+				if encoded, marshalErr := json.Marshal(redacted); marshalErr == nil {
+					return encoded
+				}
+			}
+		}
+	}
+	return bytes.ReplaceAll(data, []byte(token), []byte("<redacted-runtime-token>"))
+}
+
+func redactRuntimeTokenJSONValue(value any, token string) (any, bool) {
+	switch typed := value.(type) {
+	case string:
+		redacted := strings.ReplaceAll(typed, token, "<redacted-runtime-token>")
+		return redacted, redacted != typed
+	case []any:
+		changed := false
+		for i := range typed {
+			var itemChanged bool
+			typed[i], itemChanged = redactRuntimeTokenJSONValue(typed[i], token)
+			changed = changed || itemChanged
+		}
+		return typed, changed
+	case map[string]any:
+		changed := false
+		redactedMap := make(map[string]any, len(typed))
+		for key, item := range typed {
+			redactedKey := strings.ReplaceAll(key, token, "<redacted-runtime-token>")
+			redacted, itemChanged := redactRuntimeTokenJSONValue(item, token)
+			redactedMap[redactedKey] = redacted
+			changed = changed || itemChanged || redactedKey != key
+		}
+		if !changed {
+			return typed, false
+		}
+		return redactedMap, true
+	default:
+		return value, false
+	}
+}
+
 func personalTokenSubject(kind, token string) string {
 	token = strings.TrimSpace(token)
 	if token == "" {
@@ -1326,6 +1661,15 @@ func personalTokenSubject(kind, token string) string {
 	return strings.TrimSpace(kind) + ":" + hex.EncodeToString(sum[:])
 }

+func validPersonalIdentityHash(value string) bool {
+	value = strings.TrimSpace(value)
+	if len(value) != 16 {
+		return false
+	}
+	_, err := hex.DecodeString(value)
+	return err == nil
+}
+
 func resolveRuntimeDefault(ctx context.Context, key string) string {
 	if fnMap := edition.Get().RuntimeDefaults; fnMap != nil {
 		if fn := fnMap()[key]; fn != nil {
@@ -1363,20 +1707,42 @@ func newPersonalStreamSource(ctx context.Context, opts personalStreamSourceOptio
 		}
 		clientSecret = secret
 	}
+	credentialBroker := opts.CredentialBroker
+	if credentialBroker == nil {
+		credentialBroker = newPersonalCredentialBroker(opts.ConfigDir, false, false)
+	}
+	httpClient := &http.Client{Timeout: 30 * time.Second}
+	if opts.RuntimeTokenMode {
+		httpClient.CheckRedirect = runtimeTokenRedirectPolicy
+	}
 	_ = ctx
 	return source.NewPersonal(source.PersonalConfig{
 		AccessTokenProvider: func(ctx context.Context) (string, error) {
-			return personalResolveAuxiliaryAccessToken(ctx, opts.ConfigDir, "")
+			return credentialBroker.Resolve(ctx)
 		},
 		ForceRefreshToken: func(ctx context.Context, rejectedToken string) (string, error) {
-			return personalForceRefreshRejectedToken(ctx, opts.ConfigDir, rejectedToken)
+			return credentialBroker.RefreshRejected(ctx, rejectedToken)
+		},
+		ClassifyRetryReject: credentialBroker.ClassifyRejectedAfterRetry,
+		ClientID:            clientID,
+		ClientSecret:        clientSecret,
+		SourceID:            opts.Identity.SourceID,
+		TicketURL:           ticketURL,
+		TicketMode:          mode,
+		HTTPClient:          httpClient,
+	})
+}
+
+func newPersonalCredentialBroker(configDir string, requireSeed, requireActivation bool) *runtimecred.Broker {
+	return runtimecred.New(runtimecred.Config{
+		RequireSeed:       requireSeed,
+		RequireActivation: requireActivation,
+		LocalResolve: func(ctx context.Context) (string, error) {
+			return personalResolveAuxiliaryAccessToken(ctx, configDir, "")
+		},
+		LocalRefresh: func(ctx context.Context, rejectedToken string) (string, error) {
+			return personalForceRefreshRejectedToken(ctx, configDir, rejectedToken)
 		},
-		ClientID:     clientID,
-		ClientSecret: clientSecret,
-		SourceID:     opts.Identity.SourceID,
-		TicketURL:    ticketURL,
-		TicketMode:   mode,
-		HTTPClient:   &http.Client{Timeout: 30 * time.Second},
 	})
 }

@@ -1441,6 +1807,25 @@ func personalBusSpawnArgs(identity personal.Identity, ticketMode, ticketURL stri
 	return args
 }

+func personalBusSpawnArgsForToken(identity personal.Identity, identityHash, ticketMode, ticketURL, profileSelector, explicitToken string) []string {
+	if strings.TrimSpace(explicitToken) == "" {
+		return personalBusSpawnArgs(identity, ticketMode, ticketURL, profileSelector)
+	}
+	args := []string{
+		"--source-kind", string(dwsevent.SourceKindPersonalStream),
+		"--runtime-token-mode",
+		"--identity-hash", strings.TrimSpace(identityHash),
+		"--stream-source-id", strings.TrimSpace(identity.SourceID),
+	}
+	if strings.TrimSpace(ticketMode) != "" {
+		args = append(args, "--stream-ticket-mode", strings.TrimSpace(ticketMode))
+	}
+	if strings.TrimSpace(ticketURL) != "" {
+		args = append(args, "--stream-ticket-url", strings.TrimSpace(ticketURL))
+	}
+	return args
+}
+
 func personalEventTypes(eventKey string, explicit []string) []string {
 	if len(explicit) > 0 {
 		return explicit
@@ -0,0 +1,396 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+const (
+	runtimeTokenDetachedChildEnv     = "DWS_EVENT_RUNTIME_TOKEN_E2E_CHILD"
+	runtimeTokenDetachedWorkDirEnv   = "DWS_EVENT_RUNTIME_TOKEN_E2E_WORKDIR"
+	runtimeTokenDetachedEndpointEnv  = "DWS_EVENT_RUNTIME_TOKEN_E2E_ENDPOINT"
+	runtimeTokenDetachedEvidenceEnv  = "DWS_EVENT_RUNTIME_TOKEN_E2E_EVIDENCE"
+	runtimeTokenDetachedCanaryA      = "dws-runtime-e2e-A-9f34c8d10b7e"
+	runtimeTokenDetachedCanaryB      = "dws-runtime-e2e-B-2ad761e5c490"
+	runtimeTokenDetachedClientID     = "runtime-e2e-client"
+	runtimeTokenDetachedIdentityHash = "90abcdef12345678"
+	runtimeTokenDetachedSourceID     = "runtime-e2e-source"
+)
+
+// runRuntimeTokenDetachedE2EChild is called at the very start of TestMain.
+// busctl.Spawn executes this test binary with production-style `event _bus`
+// arguments; the env marker lets the child run a real bus daemon before the Go
+// test runner attempts to parse those CLI arguments.
+func runRuntimeTokenDetachedE2EChild() (int, bool) {
+	if os.Getenv(runtimeTokenDetachedChildEnv) != "1" {
+		return 0, false
+	}
+	workDir := strings.TrimSpace(os.Getenv(runtimeTokenDetachedWorkDirEnv))
+	endpoint := strings.TrimSpace(os.Getenv(runtimeTokenDetachedEndpointEnv))
+	evidence := strings.TrimSpace(os.Getenv(runtimeTokenDetachedEvidenceEnv))
+	if workDir == "" || endpoint == "" || evidence == "" {
+		return 91, true
+	}
+
+	argvClean := !runtimeTokenDetachedContainsCanary(strings.Join(os.Args, "\x00"))
+	envClean := !runtimeTokenDetachedContainsCanary(strings.Join(os.Environ(), "\x00"))
+	if err := appendRuntimeTokenDetachedEvidence(evidence,
+		fmt.Sprintf("child_start argv_clean=%t env_clean=%t", argvClean, envClean)); err != nil {
+		return 92, true
+	}
+	if !argvClean || !envClean {
+		return 93, true
+	}
+
+	logFile, err := os.OpenFile(filepath.Join(workDir, "bus.log"), os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return 94, true
+	}
+	defer logFile.Close()
+
+	broker := runtimecred.New(runtimecred.Config{RequireSeed: true, RequireActivation: true})
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+	err = bus.Run(ctx, bus.Config{
+		WorkDir:          workDir,
+		IPCEndpoint:      endpoint,
+		ClientID:         runtimeTokenDetachedClientID,
+		SourceKind:       dwsevent.SourceKindPersonalStream,
+		IdentityHash:     runtimeTokenDetachedIdentityHash,
+		SourceID:         runtimeTokenDetachedSourceID,
+		Edition:          "open",
+		SDKVersion:       "runtime-e2e",
+		Source:           &runtimeTokenDetachedSource{broker: broker, evidence: evidence},
+		CredentialBroker: broker,
+		ReadyPipe:        busctl.ReadyFDFromEnv(),
+		Logger:           slog.New(slog.NewTextHandler(logFile, nil)),
+	})
+	if err != nil && !errors.Is(err, context.Canceled) {
+		_ = appendRuntimeTokenDetachedEvidence(evidence, "bus_exit clean=false")
+		return 95, true
+	}
+	_ = appendRuntimeTokenDetachedEvidence(evidence, "bus_exit clean=true")
+	return 0, true
+}
+
+type runtimeTokenDetachedSource struct {
+	broker   *runtimecred.Broker
+	evidence string
+}
+
+// Start models the credential-sensitive part of a reconnecting Stream source
+// without network access. It resolves A for the first connection, waits until a
+// second consumer rotates the broker to B, then exercises the exact 401 path:
+// RefreshRejected(A) must return B and must not fall back to local OAuth.
+func (s *runtimeTokenDetachedSource) Start(ctx context.Context, _ dwsevent.EmitFn) error {
+	first, err := s.broker.Resolve(ctx)
+	if err != nil {
+		return errors.New("runtime e2e: initial credential unavailable")
+	}
+	if first != runtimeTokenDetachedCanaryA || s.broker.Generation() != 1 {
+		return errors.New("runtime e2e: initial credential mismatch")
+	}
+	if err := appendRuntimeTokenDetachedEvidence(s.evidence, "resolved_a=true generation=1"); err != nil {
+		return errors.New("runtime e2e: record initial connection")
+	}
+
+	ticker := time.NewTicker(5 * time.Millisecond)
+	defer ticker.Stop()
+	for s.broker.Generation() < 2 {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ticker.C:
+		}
+	}
+	rotated, err := s.broker.RefreshRejected(ctx, first)
+	if err != nil || rotated != runtimeTokenDetachedCanaryB {
+		return errors.New("runtime e2e: rotated credential unavailable")
+	}
+	if err := appendRuntimeTokenDetachedEvidence(s.evidence, "rejected_a=true resolved_b=true reconnect=true generation=2"); err != nil {
+		return errors.New("runtime e2e: record reconnect")
+	}
+	<-ctx.Done()
+	return ctx.Err()
+}
+
+func appendRuntimeTokenDetachedEvidence(path, line string) error {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	_, err = fmt.Fprintln(f, line)
+	return err
+}
+
+func runtimeTokenDetachedContainsCanary(value string) bool {
+	return strings.Contains(value, runtimeTokenDetachedCanaryA) ||
+		strings.Contains(value, runtimeTokenDetachedCanaryB)
+}
+
+func TestCrossPlatformCoverageUnixDetachedRuntimeTokenLifecycleAndCanaryLeakScan(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("real detached-process lifecycle is Unix-only; Windows named-pipe code is cross-compiled separately")
+	}
+
+	root, err := os.MkdirTemp("/tmp", "dws-runtime-token-e2e-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.RemoveAll(root) })
+	workDir := filepath.Join(root, "events", "open", string(dwsevent.SourceKindPersonalStream), runtimeTokenDetachedIdentityHash)
+	if err := os.MkdirAll(workDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	endpoint := dwsevent.IPCEndpoint(workDir, "open", dwsevent.SourceKindPersonalStream, runtimeTokenDetachedIdentityHash)
+	evidencePath := filepath.Join(workDir, "runtime-e2e.evidence")
+
+	identity := personal.Identity{
+		ClientID: runtimeTokenDetachedClientID,
+		SourceID: runtimeTokenDetachedSourceID,
+		CorpID:   "runtime-e2e-corp",
+		UserID:   "runtime-e2e-user",
+	}
+	spawnArgs := personalBusSpawnArgsForToken(identity, runtimeTokenDetachedIdentityHash, "", "", "corp:user", runtimeTokenDetachedCanaryA)
+	assertRuntimeTokenDetachedClean(t, "spawn argv", []byte(strings.Join(spawnArgs, "\x00")))
+
+	childEnv := append([]string{}, os.Environ()...)
+	childEnv = append(childEnv,
+		runtimeTokenDetachedChildEnv+"=1",
+		runtimeTokenDetachedWorkDirEnv+"="+workDir,
+		runtimeTokenDetachedEndpointEnv+"="+endpoint,
+		runtimeTokenDetachedEvidenceEnv+"="+evidencePath,
+	)
+	assertRuntimeTokenDetachedClean(t, "spawn environment", []byte(strings.Join(childEnv, "\x00")))
+
+	pid, err := busctl.Spawn(busctl.SpawnConfig{
+		ExecPath:  os.Args[0],
+		ClientID:  runtimeTokenDetachedClientID,
+		ExtraArgs: spawnArgs,
+		Env:       childEnv,
+	})
+	if err != nil {
+		failRuntimeTokenDetachedError(t, "spawn detached runtime bus", err)
+	}
+	stopped := false
+	t.Cleanup(func() {
+		if !stopped {
+			_ = busctl.Stop(busctl.StopConfig{WorkDir: workDir, Timeout: 2 * time.Second})
+			if proc, findErr := os.FindProcess(pid); findErr == nil {
+				_ = proc.Kill()
+			}
+		}
+	})
+
+	waitRuntimeTokenDetachedFile(t, evidencePath, "child_start argv_clean=true env_clean=true", 3*time.Second)
+
+	var stdoutA, stderrA bytes.Buffer
+	err = consume.Run(context.Background(), runtimeTokenDetachedConsumeConfig(
+		workDir, endpoint, "sub-runtime-a", runtimeTokenDetachedCanaryA, 500*time.Millisecond, &stdoutA, &stderrA,
+	))
+	if err != nil {
+		failRuntimeTokenDetachedError(t, "consume token A", err)
+	}
+	waitRuntimeTokenDetachedFile(t, evidencePath, "resolved_a=true generation=1", 3*time.Second)
+
+	if err := personal.UpsertRunState(workDir, personal.RunState{
+		SubscribeID:  "sub-runtime-b",
+		EventKey:     personal.EventMention,
+		ClientID:     runtimeTokenDetachedClientID,
+		SourceID:     runtimeTokenDetachedSourceID,
+		IdentityHash: runtimeTokenDetachedIdentityHash,
+	}); err != nil {
+		failRuntimeTokenDetachedError(t, "persist non-sensitive run state", err)
+	}
+
+	var stdoutB, stderrB bytes.Buffer
+	consumeDone := make(chan error, 1)
+	go func() {
+		consumeDone <- consume.Run(context.Background(), runtimeTokenDetachedConsumeConfig(
+			workDir, endpoint, "sub-runtime-b", runtimeTokenDetachedCanaryB, 5*time.Second, &stdoutB, &stderrB,
+		))
+	}()
+
+	status := waitRuntimeTokenDetachedStatus(t, endpoint, "sub-runtime-b", 3*time.Second)
+	if status.Bus.PID != pid || status.Bus.IdentityHash != runtimeTokenDetachedIdentityHash {
+		t.Fatalf("status bus identity = %#v, want pid=%d identity=%s", status.Bus, pid, runtimeTokenDetachedIdentityHash)
+	}
+	waitRuntimeTokenDetachedFile(t, evidencePath, "rejected_a=true resolved_b=true reconnect=true generation=2", 3*time.Second)
+
+	stopResp, err := busctl.StopConsumers(endpoint, []string{"sub-runtime-b"})
+	if err != nil {
+		failRuntimeTokenDetachedError(t, "targeted consumer stop", err)
+	}
+	if len(stopResp.Stopped) != 1 || stopResp.Stopped[0] != "sub-runtime-b" {
+		t.Fatalf("targeted stop response = %#v", stopResp)
+	}
+	select {
+	case err := <-consumeDone:
+		if err != nil {
+			failRuntimeTokenDetachedError(t, "consume token B after targeted stop", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("token B consumer did not exit after targeted stop")
+	}
+	status = waitRuntimeTokenDetachedStatus(t, endpoint, "", 3*time.Second)
+	if len(status.Consumers) != 0 {
+		t.Fatalf("status consumers after stop = %#v", status.Consumers)
+	}
+
+	if err := busctl.Stop(busctl.StopConfig{WorkDir: workDir, Timeout: 4 * time.Second}); err != nil {
+		failRuntimeTokenDetachedError(t, "stop detached bus", err)
+	}
+	stopped = true
+	waitRuntimeTokenDetachedFile(t, evidencePath, "bus_exit clean=true", 3*time.Second)
+
+	statusJSON, err := json.Marshal(status)
+	if err != nil {
+		t.Fatal(err)
+	}
+	stopJSON, err := json.Marshal(stopResp)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for name, artifact := range map[string][]byte{
+		"consume A stdout": stdoutA.Bytes(),
+		"consume A stderr": stderrA.Bytes(),
+		"consume B stdout": stdoutB.Bytes(),
+		"consume B stderr": stderrB.Bytes(),
+		"status response":  statusJSON,
+		"stop response":    stopJSON,
+	} {
+		assertRuntimeTokenDetachedClean(t, name, artifact)
+	}
+	assertRuntimeTokenDetachedTreeClean(t, root)
+
+	for _, required := range []string{
+		filepath.Join(workDir, bus.MetaFileName),
+		filepath.Join(workDir, "bus.log"),
+		filepath.Join(workDir, personal.StateFileName),
+		evidencePath,
+	} {
+		if info, statErr := os.Stat(required); statErr != nil || !info.Mode().IsRegular() {
+			t.Fatalf("expected runtime artifact %s: info=%v err=%v", required, info, statErr)
+		}
+	}
+}
+
+func runtimeTokenDetachedConsumeConfig(workDir, endpoint, subscribeID, token string, duration time.Duration, stdout, stderr *bytes.Buffer) consume.Config {
+	return consume.Config{
+		WorkDir:          workDir,
+		IPCEndpoint:      endpoint,
+		ClientID:         runtimeTokenDetachedClientID,
+		RuntimeToken:     token,
+		EventTypes:       []string{personal.EventMention},
+		EventKey:         personal.EventMention,
+		SubscribeID:      subscribeID,
+		ReadySubscribeID: subscribeID,
+		Duration:         duration,
+		Format:           consume.FormatNDJSON,
+		Stdout:           stdout,
+		Stderr:           stderr,
+	}
+}
+
+func waitRuntimeTokenDetachedFile(t *testing.T, path, want string, timeout time.Duration) string {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		data, err := os.ReadFile(path)
+		if err == nil && strings.Contains(string(data), want) {
+			return string(data)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	data, err := os.ReadFile(path)
+	if runtimeTokenDetachedContainsCanary(string(data)) {
+		t.Fatalf("runtime credential leaked into child evidence while waiting for %q", want)
+	}
+	t.Fatalf("evidence %s missing %q: data=%q err=%v", path, want, data, err)
+	return ""
+}
+
+func waitRuntimeTokenDetachedStatus(t *testing.T, endpoint, subscribeID string, timeout time.Duration) *transport.StatusResp {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	var lastErr error
+	for time.Now().Before(deadline) {
+		status, err := busctl.QueryStatus(endpoint)
+		if err == nil {
+			if subscribeID == "" && len(status.Consumers) == 0 {
+				return status
+			}
+			for _, consumer := range status.Consumers {
+				if consumer.SubscribeID == subscribeID {
+					return status
+				}
+			}
+		}
+		lastErr = err
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("status never reached subscribe_id=%q: %v", subscribeID, lastErr)
+	return nil
+}
+
+func assertRuntimeTokenDetachedTreeClean(t *testing.T, root string) {
+	t.Helper()
+	err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if entry.IsDir() || !entry.Type().IsRegular() {
+			return nil
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		assertRuntimeTokenDetachedClean(t, path, data)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("scan runtime artifacts: %v", err)
+	}
+}
+
+func assertRuntimeTokenDetachedClean(t *testing.T, name string, artifact []byte) {
+	t.Helper()
+	if runtimeTokenDetachedContainsCanary(string(artifact)) {
+		t.Fatalf("runtime credential leaked into %s", name)
+	}
+}
+
+func failRuntimeTokenDetachedError(t *testing.T, step string, err error) {
+	t.Helper()
+	if err != nil && runtimeTokenDetachedContainsCanary(err.Error()) {
+		t.Fatalf("%s failed and exposed a runtime credential", step)
+	}
+	t.Fatalf("%s: %v", step, err)
+}
@@ -0,0 +1,335 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+func TestCrossPlatformCoverageRuntimeTokenBusRejectsIncompleteIdentity(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	for _, tc := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "invalid identity hash",
+			args: []string{"--source-kind", "personal_stream", "--runtime-token-mode", "--identity-hash", "not-a-hash", "--client-id", "client"},
+			want: "16-character hexadecimal identity hash",
+		},
+		{
+			name: "missing client id",
+			args: []string{"--source-kind", "personal_stream", "--runtime-token-mode", "--identity-hash", "0123456789abcdef"},
+			want: "--client-id is required",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := newEventBusCommand()
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("Execute() error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
+type eventRuntimeTokenReleaseErrorStore struct {
+	err error
+}
+
+func (*eventRuntimeTokenReleaseErrorStore) Claim([]personal.AttemptSpec, time.Duration) (*personal.AttemptClaim, error) {
+	return nil, nil
+}
+
+func (*eventRuntimeTokenReleaseErrorStore) CompleteSuccess(*personal.AttemptClaim) error {
+	return nil
+}
+
+func (*eventRuntimeTokenReleaseErrorStore) CompleteFailure(*personal.AttemptClaim, []string, personal.AttemptFailure) (personal.AttemptHold, error) {
+	return personal.AttemptHold{}, nil
+}
+
+func (s *eventRuntimeTokenReleaseErrorStore) Release(*personal.AttemptClaim) error {
+	return s.err
+}
+
+func TestCrossPlatformCoverageRuntimeTokenAttemptReleaseGuardEdges(t *testing.T) {
+	var nilReservation *personalSubscriptionAttemptReservation
+	if err := nilReservation.releaseRuntimeTokenFailure(); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		t.Fatalf("nil reservation error = %v", err)
+	}
+
+	incomplete := &personalSubscriptionAttemptReservation{}
+	if err := incomplete.releaseRuntimeTokenFailure(); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) ||
+		!strings.Contains(err.Error(), "reservation is incomplete") {
+		t.Fatalf("incomplete reservation error = %v", err)
+	}
+
+	wantErr := errors.New("release failed")
+	reservation := &personalSubscriptionAttemptReservation{
+		store: &eventRuntimeTokenReleaseErrorStore{err: wantErr},
+		claim: &personal.AttemptClaim{AttemptID: "attempt"},
+	}
+	if err := reservation.releaseRuntimeTokenFailure(); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) ||
+		!errors.Is(err, wantErr) {
+		t.Fatalf("release failure error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenConsumeRejectionAndOversizeEdges(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldEdition := edition.Get()
+	oldProfile := authpkg.RuntimeProfile()
+	oldLoadProfiles := personalLoadProfiles
+	oldValidate := personalValidateConsumeConfig
+	oldConflict := personalValidateNoOutputConflict
+	oldAttemptStore := personalNewSubscriptionAttemptStore
+	oldEnsure := personalEnsureSubscription
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		authpkg.SetRuntimeProfile(oldProfile)
+		personalLoadProfiles = oldLoadProfiles
+		personalValidateConsumeConfig = oldValidate
+		personalValidateNoOutputConflict = oldConflict
+		personalNewSubscriptionAttemptStore = oldAttemptStore
+		personalEnsureSubscription = oldEnsure
+	})
+	edition.Override(&edition.Hooks{})
+	authpkg.SetRuntimeProfile("")
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, nil }
+	personalValidateConsumeConfig = func(consume.Config) error { return nil }
+	personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+
+	oversized := strings.Repeat("x", runtimecred.DefaultMaxTokenBytes+1)
+	err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+		EventKey:         personal.EventMention,
+		ExplicitToken:    oversized,
+		ClientIDOverride: "runtime-client",
+		Common:           commonConsumeOptions{Foreground: true},
+	})
+	if !errors.Is(err, runtimecred.ErrTokenTooLarge) {
+		t.Fatalf("oversized foreground token error = %v", err)
+	}
+
+	rejection := &personal.APIError{
+		Code:       "RUNTIME_TOKEN_REJECTED",
+		HTTPStatus: http.StatusUnauthorized,
+	}
+	if personalRuntimeTokenControlRejection(errors.New("ordinary failure")) {
+		t.Fatal("ordinary error classified as runtime-token rejection")
+	}
+
+	singleStore := &personalRecordingAttemptStore{}
+	personalNewSubscriptionAttemptStore = func(string) personalSubscriptionAttemptStore { return singleStore }
+	personalEnsureSubscription = func(context.Context, *personal.Client, personal.Identity, personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		return nil, "", "", rejection
+	}
+	err = runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+		EventKey:         personal.EventMention,
+		ExplicitToken:    "runtime-token-single",
+		ClientIDOverride: "runtime-client",
+		ControlBaseURL:   "https://control.example.test",
+	})
+	if !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) || singleStore.releaseCalls != 1 || singleStore.failureCalls != 0 {
+		t.Fatalf("single rejection = %v, release=%d failure=%d", err, singleStore.releaseCalls, singleStore.failureCalls)
+	}
+
+	manyStore := &personalRecordingAttemptStore{}
+	personalNewSubscriptionAttemptStore = func(string) personalSubscriptionAttemptStore { return manyStore }
+	err = runPersonalEventConsumeMany(newPersonalCoverageCommand(), personalConsumeOptions{
+		EventKeys:        []string{personal.EventMention, personal.EventAllSingleChat},
+		ExplicitToken:    "runtime-token-many",
+		ClientIDOverride: "runtime-client",
+		ControlBaseURL:   "https://control.example.test",
+	})
+	if !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) || manyStore.releaseCalls != 1 || manyStore.failureCalls != 0 {
+		t.Fatalf("multi rejection = %v, release=%d failure=%d", err, manyStore.releaseCalls, manyStore.failureCalls)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenIdentityFallbackEdges(t *testing.T) {
+	configDir := t.TempDir()
+	oldEdition := edition.Get()
+	oldProfile := authpkg.RuntimeProfile()
+	oldResolveIdentity := personalResolveEventIdentity
+	oldResolveAuxiliary := personalResolveAuxiliaryAccessToken
+	oldLoadTokenData := personalLoadTokenData
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	oldClientID := personalClientID
+	oldResolveCredentials := personalResolveAppCredentialsStrict
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		authpkg.SetRuntimeProfile(oldProfile)
+		personalResolveEventIdentity = oldResolveIdentity
+		personalResolveAuxiliaryAccessToken = oldResolveAuxiliary
+		personalLoadTokenData = oldLoadTokenData
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+		personalClientID = oldClientID
+		personalResolveAppCredentialsStrict = oldResolveCredentials
+	})
+
+	legacy := personal.Identity{ClientID: "legacy-client", SourceID: "legacy-source"}
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) { return legacy, nil }
+	identity, err := resolvePersonalEventIdentityForToken(context.Background(), configDir, "", "  ")
+	if err != nil || identity.ClientID != legacy.ClientID {
+		t.Fatalf("wrapper empty-token fallback = %#v, %v", identity, err)
+	}
+	personalResolveAuxiliaryAccessToken = func(context.Context, string, string) (string, error) {
+		return "legacy-access", nil
+	}
+	personalLoadTokenData = func(string) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{
+			CorpID: "legacy-corp", UserID: "legacy-user", ClientID: "direct-client",
+		}, nil
+	}
+	identity, err = resolvePersonalEventIdentityWithToken(context.Background(), configDir, "", "  ")
+	if err != nil || identity.ClientID != "direct-client" {
+		t.Fatalf("direct empty-token fallback = %#v, %v", identity, err)
+	}
+
+	edition.Override(&edition.Hooks{})
+	personalRuntimeEventClientID = func() string { return "" }
+	personalClientID = func() string { return "" }
+	wantMetadataErr := errors.New("profiles unreadable")
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, wantMetadataErr }
+	authpkg.SetRuntimeProfile("corp:user")
+	if _, err := resolvePersonalEventIdentityWithToken(context.Background(), configDir, "", "token", "runtime-client"); !errors.Is(err, wantMetadataErr) {
+		t.Fatalf("explicit profile metadata error = %v", err)
+	}
+
+	authpkg.SetRuntimeProfile("")
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, nil }
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "app-client", "", "", "", nil
+	}
+	identity, err = resolvePersonalEventIdentityWithToken(context.Background(), configDir, "", "runtime-token")
+	if err != nil || identity.ClientID != "app-client" || !strings.HasPrefix(identity.LocalSubject, "access:") {
+		t.Fatalf("app-credential fallback identity = %#v, %v", identity, err)
+	}
+
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "", "", "", "", errors.New("missing app credentials")
+	}
+	if _, err := resolvePersonalEventIdentityWithToken(context.Background(), configDir, "", "runtime-token"); err == nil || !strings.Contains(err.Error(), "cannot resolve OAuth client_id") {
+		t.Fatalf("missing client ID error = %v", err)
+	}
+
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{
+			CurrentProfile: "stale",
+			Profiles:       []authpkg.Profile{{Name: "other", CorpID: "corp", UserID: "user"}},
+		}, nil
+	}
+	profile, err := personalEventProfileMetadata(configDir)
+	if err != nil || profile != nil {
+		t.Fatalf("stale implicit current profile = %#v, %v", profile, err)
+	}
+
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{Profiles: []authpkg.Profile{{Name: "other"}}}, nil
+	}
+	profile, err = personalEventProfileMetadata(configDir)
+	if err != nil || profile != nil {
+		t.Fatalf("empty implicit selector = %#v, %v", profile, err)
+	}
+
+	authpkg.SetRuntimeProfile("corp-a:user-a,corp-b:user-b")
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, nil }
+	if _, err := personalEventProfileMetadata(configDir); err == nil || !strings.Contains(err.Error(), "exactly one --profile") {
+		t.Fatalf("multi-profile metadata error = %v", err)
+	}
+}
+
+type eventRuntimeTokenReadErrorBody struct{}
+
+func (eventRuntimeTokenReadErrorBody) Read([]byte) (int, error) {
+	return 0, errors.New("body read failed")
+}
+
+func (eventRuntimeTokenReadErrorBody) Close() error { return nil }
+
+func TestCrossPlatformCoverageRuntimeTokenControlTransportErrorEdges(t *testing.T) {
+	const token = "runtime-control-edge-canary"
+
+	unsupported, err := http.NewRequest(http.MethodGet, "unsupported://control.example.test/path", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := (runtimeTokenControlTransport{}).RoundTrip(unsupported); err == nil {
+		t.Fatal("nil base unexpectedly accepted an unsupported protocol")
+	}
+
+	wantTransportErr := errors.New("ordinary transport failure")
+	ordinary := runtimeTokenControlTransport{base: eventRuntimeRoundTripFunc(func(*http.Request) (*http.Response, error) {
+		return nil, wantTransportErr
+	})}
+	if _, err := ordinary.RoundTrip(unsupported); !errors.Is(err, wantTransportErr) {
+		t.Fatalf("ordinary transport error = %v", err)
+	}
+
+	leaking := runtimeTokenControlTransport{
+		token: token,
+		base: eventRuntimeRoundTripFunc(func(*http.Request) (*http.Response, error) {
+			return nil, errors.New("reflected " + token)
+		}),
+	}
+	if _, err := leaking.RoundTrip(unsupported); err == nil || strings.Contains(err.Error(), token) ||
+		err.Error() != "personal event: runtime-token control request failed" {
+		t.Fatalf("redacted transport error = %v", err)
+	}
+
+	nilResponse := runtimeTokenControlTransport{base: eventRuntimeRoundTripFunc(func(*http.Request) (*http.Response, error) {
+		return nil, nil
+	})}
+	if resp, err := nilResponse.RoundTrip(unsupported); resp != nil || err != nil {
+		t.Fatalf("nil response = %#v, %v", resp, err)
+	}
+
+	readFailure := runtimeTokenControlTransport{base: eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusInternalServerError,
+			Header:     make(http.Header),
+			Body:       eventRuntimeTokenReadErrorBody{},
+			Request:    req,
+		}, nil
+	})}
+	if _, err := readFailure.RoundTrip(unsupported); err == nil || !strings.Contains(err.Error(), "read runtime-token control response") {
+		t.Fatalf("body read error = %v", err)
+	}
+
+	nilHeader := runtimeTokenControlTransport{base: eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: http.StatusOK, Request: req}, nil
+	})}
+	resp, err := nilHeader.RoundTrip(unsupported)
+	if err != nil || resp == nil || resp.Header == nil || resp.Header.Get("Content-Type") != "application/json" {
+		t.Fatalf("nil-header response = %#v, %v", resp, err)
+	}
+
+	if got := redactRuntimeTokenResponseBody(nil, token); len(got) != 0 {
+		t.Fatalf("empty response redaction = %q", got)
+	}
+	value, changed := redactRuntimeTokenJSONValue([]any{"plain", "prefix-" + token}, token)
+	items, ok := value.([]any)
+	if !ok || !changed || len(items) != 2 || strings.Contains(items[1].(string), token) {
+		t.Fatalf("array redaction = %#v changed=%t", value, changed)
+	}
+}
@@ -0,0 +1,917 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageEventCommandsWireTrimmedRootRuntimeToken(t *testing.T) {
+	oldConsume := eventRunPersonalConsume
+	oldStatus := eventRunPersonalStatus
+	oldStop := eventRunPersonalStop
+	t.Cleanup(func() {
+		eventRunPersonalConsume = oldConsume
+		eventRunPersonalStatus = oldStatus
+		eventRunPersonalStop = oldStop
+	})
+
+	flags := &GlobalFlags{Token: "  runtime-canary  ", ClientID: " root-client "}
+	assertIdentity := func(token, clientID string) {
+		t.Helper()
+		if token != "runtime-canary" || clientID != "root-client" {
+			t.Fatalf("runtime identity = token %q client %q", token, clientID)
+		}
+	}
+
+	eventRunPersonalConsume = func(_ *cobra.Command, opts personalConsumeOptions) error {
+		assertIdentity(opts.ExplicitToken, opts.ClientIDOverride)
+		return nil
+	}
+	consumeCmd := newEventConsumeCommand(flags)
+	if err := consumeCmd.RunE(consumeCmd, []string{personal.EventMention}); err != nil {
+		t.Fatalf("consume RunE() error = %v", err)
+	}
+
+	eventRunPersonalStatus = func(_ *cobra.Command, opts personalStatusOptions) error {
+		assertIdentity(opts.ExplicitToken, opts.ClientIDOverride)
+		return nil
+	}
+	statusCmd := newEventStatusCommandWithFlags(flags)
+	if err := statusCmd.RunE(statusCmd, nil); err != nil {
+		t.Fatalf("status RunE() error = %v", err)
+	}
+
+	eventRunPersonalStop = func(_ *cobra.Command, opts personalStopOptions) error {
+		assertIdentity(opts.ExplicitToken, opts.ClientIDOverride)
+		return nil
+	}
+	stopCmd := newEventStopCommandWithFlags(flags)
+	stopRoot := &cobra.Command{Use: "dws"}
+	stopRoot.PersistentFlags().Bool("yes", true, "")
+	stopRoot.AddCommand(stopCmd)
+	if err := stopCmd.RunE(stopCmd, []string{"sub-runtime"}); err != nil {
+		t.Fatalf("stop RunE() error = %v", err)
+	}
+
+	listenCmd := newEventListenIMCommand(flags)
+	if err := listenCmd.RunE(listenCmd, nil); err != nil {
+		t.Fatalf("listen-im RunE() error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventConsumeParsesRootRuntimeTokenBeforeAndAfterSubcommand(t *testing.T) {
+	oldConsume := eventRunPersonalConsume
+	t.Cleanup(func() { eventRunPersonalConsume = oldConsume })
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{name: "before", args: []string{"--token", "runtime-before", "event", "consume", personal.EventMention}},
+		{name: "after", args: []string{"event", "consume", personal.EventMention, "--token", "runtime-after"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			flags := &GlobalFlags{}
+			root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+			bindPersistentFlags(root, flags)
+			root.AddCommand(newEventCommand(flags))
+			var got string
+			eventRunPersonalConsume = func(_ *cobra.Command, opts personalConsumeOptions) error {
+				got = opts.ExplicitToken
+				return nil
+			}
+			root.SetArgs(tc.args)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			want := "runtime-" + tc.name
+			if got != want {
+				t.Fatalf("ExplicitToken = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageResolvePersonalEventIdentityWithTokenUsesMetadataOnly(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldLoadToken := personalLoadTokenData
+	oldAux := personalResolveAuxiliaryAccessToken
+	oldClientID := personalClientID
+	oldCredentials := personalResolveAppCredentialsStrict
+	previousProfile := authpkg.RuntimeProfile()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalLoadTokenData = oldLoadToken
+		personalResolveAuxiliaryAccessToken = oldAux
+		personalClientID = oldClientID
+		personalResolveAppCredentialsStrict = oldCredentials
+		authpkg.SetRuntimeProfile(previousProfile)
+	})
+
+	personalLoadTokenData = func(string) (*authpkg.TokenData, error) {
+		t.Fatal("explicit token identity read sensitive TokenData")
+		return nil, nil
+	}
+	personalResolveAuxiliaryAccessToken = func(context.Context, string, string) (string, error) {
+		t.Fatal("explicit token identity resolved local OAuth")
+		return "", nil
+	}
+	personalClientID = func() string {
+		t.Fatal("explicit root client ID was not preferred")
+		return ""
+	}
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		t.Fatal("explicit root client ID unexpectedly fell back to app credentials")
+		return "", "", "", "", nil
+	}
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{
+			Version: 2,
+			Profiles: []authpkg.Profile{{
+				Name:     "Runtime profile",
+				CorpID:   "profile-corp",
+				CorpName: "Runtime Org",
+				UserID:   "profile-user",
+				UserName: "Runtime User",
+				ClientID: "profile-client",
+			}},
+		}, nil
+	}
+	authpkg.SetRuntimeProfile("Runtime Org:Runtime User")
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "", false },
+		}
+	}})
+
+	identity, err := resolvePersonalEventIdentityWithToken(
+		context.Background(), "unused", "runtime-source", " runtime-canary ", "root-client",
+	)
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+	if identity.CorpID != "runtime-corp" || identity.UserID != "profile-user" || identity.ClientID != "root-client" {
+		t.Fatalf("identity metadata = %#v", identity)
+	}
+	if identity.AccessToken != "" {
+		t.Fatalf("identity retained raw runtime token: %q", identity.AccessToken)
+	}
+	if identity.LocalSubject != "" {
+		t.Fatalf("complete identity LocalSubject = %q, want empty", identity.LocalSubject)
+	}
+}
+
+func TestCrossPlatformCoverageResolvePersonalEventIdentityWithCompleteRuntimeMetadataSkipsProfiles(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+	})
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		t.Fatal("complete host metadata unexpectedly read profiles.json")
+		return nil, nil
+	}
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+	personalRuntimeEventClientID = func() string { return "edition-client" }
+	identity, err := resolvePersonalEventIdentityWithToken(context.Background(), "unused", "source", "canary", "root-client")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+	if identity.CorpID != "runtime-corp" || identity.UserID != "runtime-user" || identity.ClientID != "root-client" {
+		t.Fatalf("identity = %#v", identity)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeEventClientIDPrefersEditionBeforeEnvironment(t *testing.T) {
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	t.Setenv("DWS_CLIENT_ID", "environment-client")
+
+	edition.Override(&edition.Hooks{AuthClientID: "edition-client"})
+	if got := runtimePersonalEventClientID(); got != "edition-client" {
+		t.Fatalf("runtime client ID = %q, want edition hook", got)
+	}
+	edition.Override(&edition.Hooks{})
+	if got := runtimePersonalEventClientID(); got != "environment-client" {
+		t.Fatalf("runtime client ID = %q, want environment fallback", got)
+	}
+}
+
+func TestCrossPlatformCoverageCompleteRuntimeIdentityUsesEditionClientBeforeProfiles(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+	})
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		t.Fatal("complete host metadata unexpectedly read profiles.json")
+		return nil, errors.New("unreachable")
+	}
+	personalRuntimeEventClientID = func() string { return "edition-client" }
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+	identity, err := resolvePersonalEventIdentityWithToken(context.Background(), "unused", "source", "canary")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+	if identity.CorpID != "runtime-corp" || identity.UserID != "runtime-user" || identity.ClientID != "edition-client" {
+		t.Fatalf("identity = %#v", identity)
+	}
+}
+
+func TestCrossPlatformCoverageSelectedProfileClientPrecedesPersistedGlobalClient(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	oldClientID := personalClientID
+	previousProfile := authpkg.RuntimeProfile()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+		personalClientID = oldClientID
+		authpkg.SetRuntimeProfile(previousProfile)
+	})
+	edition.Override(&edition.Hooks{})
+	personalRuntimeEventClientID = func() string { return "" }
+	personalClientID = func() string { return "stale-global-client" }
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{
+			Version:        3,
+			CurrentProfile: "corp:user",
+			Profiles: []authpkg.Profile{{
+				Name: "Selected", CorpID: "corp", UserID: "user", ClientID: "profile-client",
+			}},
+		}, nil
+	}
+	authpkg.SetRuntimeProfile("corp:user")
+	identity, err := resolvePersonalEventIdentityWithToken(context.Background(), "unused", "source", "canary")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+	if identity.ClientID != "profile-client" {
+		t.Fatalf("ClientID = %q, want selected profile client", identity.ClientID)
+	}
+}
+
+func TestCrossPlatformCoverageMalformedPersistedProfilesDoNotBlockRuntimeDefaultsAndGlobalClient(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	oldClientID := personalClientID
+	previousProfile := authpkg.RuntimeProfile()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+		personalClientID = oldClientID
+		authpkg.SetRuntimeProfile(previousProfile)
+	})
+	authpkg.SetRuntimeProfile("")
+	personalRuntimeEventClientID = func() string { return "" }
+	personalClientID = func() string { return "global-client" }
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return nil, errors.New("malformed persisted profiles")
+	}
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+
+	identity, err := resolvePersonalEventIdentityWithToken(context.Background(), "unused", "source", "canary")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+	if identity.CorpID != "runtime-corp" || identity.UserID != "runtime-user" || identity.ClientID != "global-client" {
+		t.Fatalf("identity = %#v", identity)
+	}
+}
+
+func TestCrossPlatformCoverageResolvePersonalEventIdentityWithTokenRejectsMultipleProfilesBeforeMetadata(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	previousProfile := authpkg.RuntimeProfile()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		authpkg.SetRuntimeProfile(previousProfile)
+	})
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		t.Fatal("multiple runtime profiles unexpectedly reached metadata loading")
+		return nil, nil
+	}
+	authpkg.SetRuntimeProfile("corp-a:user-a,corp-b:user-b")
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+	_, err := resolvePersonalEventIdentityWithToken(context.Background(), "unused", "source", "canary", "root-client")
+	if err == nil || !strings.Contains(err.Error(), "exactly one --profile") {
+		t.Fatalf("multiple-profile error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageExplicitProfileRequiresMetadataRegistry(t *testing.T) {
+	oldLoadProfiles := personalLoadProfiles
+	defer func() { personalLoadProfiles = oldLoadProfiles }()
+	oldProfile := authpkg.RuntimeProfile()
+	authpkg.SetRuntimeProfile("missing-profile")
+	defer authpkg.SetRuntimeProfile(oldProfile)
+
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{}, nil
+	}
+	_, err := personalEventProfileMetadata(t.TempDir())
+	if err == nil || !strings.Contains(err.Error(), `profile "missing-profile" not found`) {
+		t.Fatalf("personalEventProfileMetadata() error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageCompleteRuntimeIdentityStillValidatesExplicitProfile(t *testing.T) {
+	oldEdition := edition.Get()
+	oldLoadProfiles := personalLoadProfiles
+	oldRuntimeClientID := personalRuntimeEventClientID
+	oldProfile := authpkg.RuntimeProfile()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalLoadProfiles = oldLoadProfiles
+		personalRuntimeEventClientID = oldRuntimeClientID
+		authpkg.SetRuntimeProfile(oldProfile)
+	})
+
+	authpkg.SetRuntimeProfile("missing-profile")
+	personalLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{}, nil
+	}
+	personalRuntimeEventClientID = func() string { return "runtime-client" }
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+
+	_, err := resolvePersonalEventIdentityWithToken(context.Background(), t.TempDir(), "source", "canary")
+	if err == nil || !strings.Contains(err.Error(), `profile "missing-profile" not found`) {
+		t.Fatalf("resolvePersonalEventIdentityWithToken() error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoveragePersonalProfileMetadataOrganizationCurrentBeatsUnresolved(t *testing.T) {
+	cfg := &authpkg.ProfilesConfig{
+		Version: 3,
+		Profiles: []authpkg.Profile{
+			{Name: "Historical", CorpID: "corp-1"},
+			{Name: "Exact", CorpID: "corp-1", UserID: "user-1"},
+		},
+		OrgCurrentProfiles: map[string]string{"corp-1": "corp-1:user-1"},
+	}
+	profile, err := selectPersonalEventProfileMetadata(cfg, "corp-1", make(map[string]struct{}))
+	if err != nil {
+		t.Fatalf("selectPersonalEventProfileMetadata() error = %v", err)
+	}
+	if profile == nil || profile.UserID != "user-1" {
+		t.Fatalf("selected profile = %#v, want organization current account", profile)
+	}
+}
+
+func TestCrossPlatformCoverageExplicitTokenControlClientRedactsReflected401(t *testing.T) {
+	const token = "runtime-control-canary"
+	oldLogger := slog.Default()
+	var logs bytes.Buffer
+	slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(oldLogger) })
+
+	client := newPersonalEventControlClient("unused", "https://control.invalid", personal.Identity{
+		ClientID: "client", SourceID: "source",
+	}, token)
+	wrapped, ok := client.HTTPClient.Transport.(runtimeTokenControlTransport)
+	if !ok {
+		t.Fatalf("control transport = %T, want runtimeTokenControlTransport", client.HTTPClient.Transport)
+	}
+	var authorization string
+	wrapped.base = eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		authorization = req.Header.Get("Authorization")
+		body := `{"code":"UNAUTHORIZED","message":"rejected ` + token + `"}`
+		header := make(http.Header)
+		header.Set("X-Request-Id", "request-"+token)
+		header.Set("X-Trace-Id", "trace-"+token)
+		return &http.Response{
+			StatusCode: http.StatusUnauthorized,
+			Header:     header,
+			Body:       io.NopCloser(strings.NewReader(body)),
+			Request:    req,
+		}, nil
+	})
+	client.HTTPClient.Transport = wrapped
+
+	_, err := client.ListSubscriptions(context.Background(), personal.ListOptions{})
+	if err == nil {
+		t.Fatal("ListSubscriptions() unexpectedly succeeded")
+	}
+	if authorization != "Bearer "+token {
+		t.Fatalf("Authorization = %q", authorization)
+	}
+	if strings.Contains(err.Error(), token) || strings.Contains(logs.String(), token) {
+		t.Fatalf("runtime token leaked: error=%q logs=%q", err, logs.String())
+	}
+	if !strings.Contains(err.Error(), "RUNTIME_TOKEN_REJECTED") {
+		t.Fatalf("error = %q, want fixed runtime token rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenRedirectGuardDoesNotForwardCustomHeader(t *testing.T) {
+	const token = "runtime-redirect-canary"
+	var controlTargetHits, ticketTargetHits atomic.Int32
+	controlTarget := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		controlTargetHits.Add(1)
+		if r.Header.Get("x-user-access-token") == token {
+			t.Error("control redirect forwarded runtime token")
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer controlTarget.Close()
+	controlOrigin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("x-user-access-token") != token {
+			t.Error("control origin did not receive runtime token")
+		}
+		http.Redirect(w, r, controlTarget.URL, http.StatusFound)
+	}))
+	defer controlOrigin.Close()
+
+	client := newPersonalEventControlClient("unused", controlOrigin.URL, personal.Identity{
+		ClientID: "client", SourceID: "source",
+	}, token)
+	_, controlErr := client.ListSubscriptions(context.Background(), personal.ListOptions{})
+	if controlErr == nil {
+		t.Fatal("cross-host control redirect unexpectedly succeeded")
+	}
+	if controlTargetHits.Load() != 0 || strings.Contains(controlErr.Error(), token) {
+		t.Fatalf("control redirect hits=%d error=%q", controlTargetHits.Load(), controlErr)
+	}
+
+	ticketTarget := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ticketTargetHits.Add(1)
+		if r.Header.Get("x-user-access-token") == token {
+			t.Error("ticket redirect forwarded runtime token")
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer ticketTarget.Close()
+	ticketOrigin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("x-user-access-token") != token {
+			t.Error("ticket origin did not receive runtime token")
+		}
+		http.Redirect(w, r, ticketTarget.URL, http.StatusFound)
+	}))
+	defer ticketOrigin.Close()
+
+	broker := runtimecred.New(runtimecred.Config{RequireSeed: true})
+	if _, err := broker.Update(0, token); err != nil {
+		t.Fatal(err)
+	}
+	src, err := newPersonalStreamSource(context.Background(), personalStreamSourceOptions{
+		ConfigDir:        "unused",
+		Identity:         personal.Identity{ClientID: "client", SourceID: "source"},
+		TicketURL:        ticketOrigin.URL,
+		CredentialBroker: broker,
+		RuntimeTokenMode: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = src.Start(context.Background(), func(*dwsevent.RawEvent) {})
+	if err == nil {
+		t.Fatal("cross-host ticket redirect unexpectedly succeeded")
+	}
+	if ticketTargetHits.Load() != 0 || strings.Contains(err.Error(), token) {
+		t.Fatalf("ticket redirect hits=%d error=%q", ticketTargetHits.Load(), err)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenRedirectPolicyBranches(t *testing.T) {
+	origin, _ := http.NewRequest(http.MethodGet, "https://control.example/start", nil)
+	sameHost, _ := http.NewRequest(http.MethodGet, "https://control.example/next", nil)
+	if err := runtimeTokenRedirectPolicy(sameHost, []*http.Request{origin}); err != nil {
+		t.Fatalf("same-host HTTPS redirect rejected: %v", err)
+	}
+	for name, request := range map[string]*http.Request{
+		"cross-host": func() *http.Request {
+			r, _ := http.NewRequest(http.MethodGet, "https://other.example/next", nil)
+			return r
+		}(),
+		"downgrade": func() *http.Request {
+			r, _ := http.NewRequest(http.MethodGet, "http://control.example/next", nil)
+			return r
+		}(),
+	} {
+		if err := runtimeTokenRedirectPolicy(request, []*http.Request{origin}); !errors.Is(err, http.ErrUseLastResponse) {
+			t.Fatalf("%s redirect policy error = %v", name, err)
+		}
+	}
+	if err := runtimeTokenRedirectPolicy(nil, nil); !errors.Is(err, http.ErrUseLastResponse) {
+		t.Fatalf("empty redirect chain error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageExplicitTokenControlClientRedactsEveryErrorEnvelope(t *testing.T) {
+	const token = "runtime-control-all-status-canary"
+	tests := []struct {
+		name   string
+		status int
+		body   string
+	}{
+		{name: "bad-request", status: http.StatusBadRequest, body: `{"code":"BAD_REQUEST","message":"` + token + `"}`},
+		{name: "server-error", status: http.StatusInternalServerError, body: `{"code":"INTERNAL","message":"` + token + `"}`},
+		{name: "success-false", status: http.StatusOK, body: `{"success":false,"errorCode":"DENIED","errorMsg":"` + token + `"}`},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			oldLogger := slog.Default()
+			var logs bytes.Buffer
+			slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+			t.Cleanup(func() { slog.SetDefault(oldLogger) })
+
+			client := newPersonalEventControlClient("unused", "https://control.invalid", personal.Identity{
+				ClientID: "client", SourceID: "source",
+			}, token)
+			wrapped := client.HTTPClient.Transport.(runtimeTokenControlTransport)
+			wrapped.base = eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+				header := make(http.Header)
+				header.Set("X-Request-Id", "request-"+token)
+				header.Set("X-Trace-Id", "trace-"+token)
+				return &http.Response{
+					StatusCode: tc.status,
+					Header:     header,
+					Body:       io.NopCloser(strings.NewReader(tc.body)),
+					Request:    req,
+				}, nil
+			})
+			client.HTTPClient.Transport = wrapped
+
+			_, err := client.ListSubscriptions(context.Background(), personal.ListOptions{})
+			if err == nil {
+				t.Fatal("ListSubscriptions() unexpectedly succeeded")
+			}
+			if strings.Contains(err.Error(), token) || strings.Contains(logs.String(), token) {
+				t.Fatalf("runtime token leaked: error=%q logs=%q", err, logs.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageExplicitTokenControlTransportPreservesSuccessfulResponse(t *testing.T) {
+	client := newPersonalEventControlClient("unused", "https://control.invalid", personal.Identity{
+		ClientID: "client", SourceID: "source",
+	}, "runtime-success-canary")
+	wrapped := client.HTTPClient.Transport.(runtimeTokenControlTransport)
+	wrapped.base = eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader(`{"success":true,"result":{"items":[],"total":0}}`)),
+			Request:    req,
+		}, nil
+	})
+	client.HTTPClient.Transport = wrapped
+	if _, err := client.ListSubscriptions(context.Background(), personal.ListOptions{}); err != nil {
+		t.Fatalf("ListSubscriptions() successful response error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageExplicitTokenControlClientRedactsJSONEscapedToken(t *testing.T) {
+	const token = "runtime<escaped>&canary"
+	body, err := json.Marshal(map[string]any{"code": "BAD_REQUEST", "message": "rejected " + token})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if bytes.Contains(body, []byte(token)) {
+		t.Fatalf("fixture was not JSON-escaped: %s", body)
+	}
+	oldLogger := slog.Default()
+	var logs bytes.Buffer
+	slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(oldLogger) })
+
+	client := newPersonalEventControlClient("unused", "https://control.invalid", personal.Identity{
+		ClientID: "client", SourceID: "source",
+	}, token)
+	wrapped := client.HTTPClient.Transport.(runtimeTokenControlTransport)
+	wrapped.base = eventRuntimeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusBadRequest,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(bytes.NewReader(body)),
+			Request:    req,
+		}, nil
+	})
+	client.HTTPClient.Transport = wrapped
+	_, err = client.ListSubscriptions(context.Background(), personal.ListOptions{})
+	if err == nil {
+		t.Fatal("ListSubscriptions() unexpectedly succeeded")
+	}
+	if strings.Contains(err.Error(), token) || strings.Contains(logs.String(), token) {
+		t.Fatalf("escaped runtime token leaked: error=%q logs=%q", err, logs.String())
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenBusModeSkipsLocalOAuthIdentity(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldResolve := eventResolvePersonal
+	oldSource := eventNewPersonalSource
+	oldRun := eventBusRun
+	t.Cleanup(func() {
+		eventResolvePersonal = oldResolve
+		eventNewPersonalSource = oldSource
+		eventBusRun = oldRun
+	})
+
+	resolvedLocal := false
+	eventResolvePersonal = func(context.Context, string, string) (personal.Identity, error) {
+		resolvedLocal = true
+		return personal.Identity{}, nil
+	}
+	var sourceOpts personalStreamSourceOptions
+	eventNewPersonalSource = func(_ context.Context, opts personalStreamSourceOptions) (*source.PersonalSource, error) {
+		sourceOpts = opts
+		return nil, nil
+	}
+	var busCfg bus.Config
+	eventBusRun = func(_ context.Context, cfg bus.Config) error {
+		busCfg = cfg
+		return nil
+	}
+
+	cmd := newEventBusCommand()
+	cmd.SetArgs([]string{
+		"--source-kind", "personal_stream",
+		"--runtime-token-mode",
+		"--identity-hash", "0123456789abcdef",
+		"--client-id", "runtime-client",
+		"--stream-source-id", "runtime-source",
+		"--idle-timeout", "0",
+	})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("event _bus runtime mode error = %v", err)
+	}
+	if resolvedLocal {
+		t.Fatal("runtime token bus resolved local OAuth identity")
+	}
+	if sourceOpts.CredentialBroker == nil || busCfg.CredentialBroker != sourceOpts.CredentialBroker {
+		t.Fatal("personal source and bus did not share one credential broker")
+	}
+	if busCfg.IdentityHash != "0123456789abcdef" || busCfg.ClientID != "runtime-client" || busCfg.SourceID != "runtime-source" {
+		t.Fatalf("bus identity = %#v", busCfg)
+	}
+	generation, err := sourceOpts.CredentialBroker.Update(0, "detached-activation-canary")
+	if err != nil {
+		t.Fatalf("seed detached broker: %v", err)
+	}
+	waitCtx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	defer cancel()
+	if _, err := sourceOpts.CredentialBroker.Resolve(waitCtx); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("detached broker resolved before consumer activation: %v", err)
+	}
+	if _, err := sourceOpts.CredentialBroker.Activate(generation); err != nil {
+		t.Fatalf("activate detached broker: %v", err)
+	}
+	if resolved, err := sourceOpts.CredentialBroker.Resolve(context.Background()); err != nil || resolved == "" {
+		t.Fatalf("detached broker did not resolve after activation: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageForegroundRuntimeBrokerDoesNotRequireActivation(t *testing.T) {
+	broker := newPersonalCredentialBroker(t.TempDir(), true, false)
+	if _, err := broker.Update(0, "foreground-activation-canary"); err != nil {
+		t.Fatalf("seed foreground broker: %v", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if resolved, err := broker.Resolve(ctx); err != nil || resolved == "" {
+		t.Fatalf("foreground broker unexpectedly waited for activation: %v", err)
+	}
+}
+
+func TestCrossPlatformCoveragePersonalRuntimeBusSpawnArgsContainNoSecretOrProfile(t *testing.T) {
+	const token = "runtime-spawn-canary"
+	args := personalBusSpawnArgsForToken(personal.Identity{
+		ClientID: "client", SourceID: "source", CorpID: "corp", UserID: "user",
+	}, "identity-hash", "normal", "https://ticket.invalid", "corp:user", token)
+	joined := strings.Join(args, " ")
+	for _, forbidden := range []string{token, "--profile", "corp:user"} {
+		if strings.Contains(joined, forbidden) {
+			t.Fatalf("spawn args leaked %q: %q", forbidden, joined)
+		}
+	}
+	for _, required := range []string{"--runtime-token-mode", "--identity-hash", "identity-hash", "--stream-source-id", "source"} {
+		if !strings.Contains(joined, required) {
+			t.Fatalf("spawn args %q missing %q", joined, required)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageUnsupportedOldBusDoesNotDeleteReusedSubscription(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldEdition := edition.Get()
+	oldEnsure := personalEnsureSubscription
+	oldUpsert := personalUpsertRunState
+	oldDelete := personalDeleteSubscription
+	oldRemove := personalRemoveRunStates
+	oldConsume := personalConsumeRun
+	oldValidate := personalValidateConsumeConfig
+	oldConflict := personalValidateNoOutputConflict
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalEnsureSubscription = oldEnsure
+		personalUpsertRunState = oldUpsert
+		personalDeleteSubscription = oldDelete
+		personalRemoveRunStates = oldRemove
+		personalConsumeRun = oldConsume
+		personalValidateConsumeConfig = oldValidate
+		personalValidateNoOutputConflict = oldConflict
+	})
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+	personalEnsureSubscription = func(context.Context, *personal.Client, personal.Identity, personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		return &personal.Subscription{SubscribeID: "sub-existing"}, personal.EventMention, "at", nil
+	}
+	personalUpsertRunState = func(string, personal.RunState) error { return nil }
+	deleteCalls := 0
+	personalDeleteSubscription = func(*personal.Client, context.Context, string) error {
+		deleteCalls++
+		return nil
+	}
+	var removed []string
+	personalRemoveRunStates = func(_ string, ids []string) error {
+		removed = append(removed, ids...)
+		return nil
+	}
+	personalValidateConsumeConfig = func(consume.Config) error { return nil }
+	personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+	personalConsumeRun = func(_ context.Context, cfg consume.Config) error {
+		if strings.TrimSpace(cfg.RuntimeToken) == "" {
+			t.Fatal("runtime token was not wired to consume")
+		}
+		return &consume.RuntimeTokenUnsupportedError{BusPID: 72}
+	}
+
+	err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+		SubscribeID:      "sub-existing",
+		ExplicitToken:    "old-bus-cleanup-canary",
+		ClientIDOverride: "runtime-client",
+	})
+	if !errors.Is(err, consume.ErrRuntimeTokenUnsupported) {
+		t.Fatalf("consume error = %v", err)
+	}
+	if deleteCalls != 0 {
+		t.Fatalf("reused remote subscription was deleted %d time(s)", deleteCalls)
+	}
+	if len(removed) != 0 {
+		t.Fatalf("reused local run-state was removed: %#v", removed)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenReusedDryRunUsesExplicitControlCredential(t *testing.T) {
+	const token = "runtime-dry-run-control-canary"
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldEdition := edition.Get()
+	oldEnsure := personalEnsureSubscription
+	oldUpsert := personalUpsertRunState
+	oldConsume := personalConsumeRun
+	oldBusRun := personalBusRun
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		personalEnsureSubscription = oldEnsure
+		personalUpsertRunState = oldUpsert
+		personalConsumeRun = oldConsume
+		personalBusRun = oldBusRun
+	})
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return "runtime-corp", true },
+			"$currentUserId": func(context.Context) (string, bool) { return "runtime-user", true },
+		}
+	}})
+
+	personalEnsureSubscription = func(ctx context.Context, client *personal.Client, _ personal.Identity, _ personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		if _, ok := client.HTTPClient.Transport.(runtimeTokenControlTransport); !ok {
+			t.Fatalf("control transport = %T, want runtimeTokenControlTransport", client.HTTPClient.Transport)
+		}
+		got, err := client.AccessTokenProvider(ctx)
+		if err != nil || got != token {
+			t.Fatalf("control token = %q, %v", got, err)
+		}
+		return &personal.Subscription{SubscribeID: "sub-existing"}, personal.EventMention, "at", nil
+	}
+	personalUpsertRunState = func(string, personal.RunState) error {
+		t.Fatal("dry-run unexpectedly persisted run state")
+		return nil
+	}
+	consumeCalls := 0
+	personalConsumeRun = func(_ context.Context, cfg consume.Config) error {
+		consumeCalls++
+		if !cfg.DryRun {
+			t.Fatal("consume config is not dry-run")
+		}
+		if strings.Contains(strings.Join(cfg.SpawnExtraArgs, " "), token) {
+			t.Fatal("dry-run spawn args leaked runtime token")
+		}
+		return nil
+	}
+	personalBusRun = func(context.Context, bus.Config) error {
+		t.Fatal("dry-run unexpectedly started a bus")
+		return nil
+	}
+
+	err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+		SubscribeID:      "sub-existing",
+		ExplicitToken:    token,
+		ClientIDOverride: "runtime-client",
+		Common:           commonConsumeOptions{DryRun: true},
+	})
+	if err != nil {
+		t.Fatalf("dry-run consume error = %v", err)
+	}
+	if consumeCalls != 1 {
+		t.Fatalf("dry-run consume calls = %d, want 1", consumeCalls)
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenControlRejectionReleasesSubscriptionClaim(t *testing.T) {
+	store := &personalRecordingAttemptStore{}
+	reservation := &personalSubscriptionAttemptReservation{
+		store: store,
+		claim: &personal.AttemptClaim{AttemptID: "runtime-token-attempt"},
+		items: []personalSubscriptionAttemptItem{{eventKey: personal.EventMention, fingerprint: strings.Repeat("a", 64)}},
+	}
+	cause := &personal.APIError{
+		Code:       "RUNTIME_TOKEN_REJECTED",
+		Message:    "event runtime token was rejected; retry with a fresh host credential",
+		HTTPStatus: http.StatusUnauthorized,
+	}
+	if !personalRuntimeTokenControlRejection(cause) {
+		t.Fatal("runtime token control rejection was not classified")
+	}
+	err := reservation.releaseRuntimeTokenFailure()
+	if err == nil || !strings.Contains(err.Error(), "runtime token was rejected") {
+		t.Fatalf("releaseRuntimeTokenFailure() error = %v", err)
+	}
+	if store.releaseCalls != 1 || store.failureCalls != 0 {
+		t.Fatalf("attempt store release=%d failure=%d, want release only", store.releaseCalls, store.failureCalls)
+	}
+}
+
+type eventRuntimeRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f eventRuntimeRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
@@ -0,0 +1,525 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+func TestFrameworkErrorProjectionPreservesRecoveryMetadata(t *testing.T) {
+	next := time.Date(2026, 8, 10, 1, 2, 3, 0, time.FixedZone("test", 8*60*60))
+	retry := int64(4)
+	started := true
+	leaf := &helpers.CLIError{Code: "UPSTREAM_CODE", Suggestion: "retry with id", Operation: "create"}
+	call := &transport.CallError{Stage: transport.CallStage("decode"), HTTPStatus: 503, RPCCode: 91, TraceID: "call-trace", Cause: leaf}
+	typed := &apperrors.Error{
+		Category: apperrors.CategoryAPI, Message: "failed", Reason: "upstream_failed", Hint: "use status",
+		Actions: []string{"dws status"}, Retryable: true, RetryableSet: true, RetryAfterSeconds: &retry,
+		RPCCode: 92, RPCData: json.RawMessage(`{"task":"x"}`), Operation: "publish", ServerKey: "server",
+		Origin: "gateway", FailureStage: "response", ExecutionStarted: &started, NextRetryAt: &next,
+		AvailableFlags: []string{"--id"}, Snapshot: "/tmp/snapshot", Details: map[string]any{"id": "x"},
+		ServerDiag: apperrors.ServerDiagnostics{TraceID: "typed-trace", ServerErrorCode: "SERVER_CODE", TechnicalDetail: "detail", FriendlyHint: "friendly", ActionURL: "https://example.test"},
+		Cause:      call,
+	}
+	info := errorInfoFromExecutionError(typed)
+	if info.Type != "api" || info.Subtype != "upstream_failed" || info.HTTPStatus != 503 || info.RPCCode != 92 || info.RequestID != "call-trace" || info.TraceID != "typed-trace" {
+		t.Fatalf("projection=%+v", info)
+	}
+	if info.UpstreamCode != "SERVER_CODE" || info.Operation != "publish" || info.NextRetryAt == "" || info.Cause == "" || info.RPCData == nil || info.ExecutionStarted == nil || !*info.ExecutionStarted {
+		t.Fatalf("recovery metadata=%+v", info)
+	}
+
+	innerOperation := &helpers.CLIError{Operation: "create"}
+	outerWithoutOperation := &apperrors.Error{
+		Category: apperrors.CategoryAPI,
+		Message:  "failed",
+		Cause:    innerOperation,
+	}
+	preserved := errorInfoFromExecutionError(outerWithoutOperation)
+	if preserved.Operation != "create" {
+		t.Fatalf("operation=%q, want inner operation preserved", preserved.Operation)
+	}
+
+	requestCall := &transport.CallError{Stage: transport.CallStage("request"), HTTPStatus: 429, RequestID: "request-id"}
+	requestInfo := errorInfoFromExecutionError(requestCall)
+	if requestInfo.RequestID != "request-id" || requestInfo.HTTPStatus != 429 {
+		t.Fatalf("request projection=%+v", requestInfo)
+	}
+	partial := errorInfoFromExecutionError(&apperrors.Error{Category: apperrors.CategoryPartial, Message: "partial"})
+	if partial.Type != "internal" {
+		t.Fatalf("partial error type=%s", partial.Type)
+	}
+	for code, want := range map[int]string{1: "api", 2: "auth", 3: "validation", 4: "permission", 6: "discovery", 99: "internal"} {
+		if got := errorTypeForExitCode(code); got != want {
+			t.Fatalf("errorTypeForExitCode(%d)=%q", code, got)
+		}
+	}
+}
+
+func TestFrameworkExecutePreparseUnifiedErrorAndEmissionFallback(t *testing.T) {
+	for _, failWriter := range []bool{false, true} {
+		t.Run(map[bool]string{false: "unified", true: "fallback"}[failWriter], func(t *testing.T) {
+			testseam.Protect(t, &os.Args)
+			os.Args = []string{"dws", "leaf"}
+			testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+			testseam.Swap(t, &rootStopAllStdioClients, func() {})
+			testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return errors.New("bad preparse") })
+			var stdout bytes.Buffer
+			testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+				root := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+				root.SetContext(ctx)
+				leaf := &cobra.Command{Use: "leaf"}
+				output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+				if failWriter {
+					leaf.SetOut(frameworkFailWriter{})
+				} else {
+					leaf.SetOut(&stdout)
+				}
+				leaf.SetErr(&bytes.Buffer{})
+				root.AddCommand(leaf)
+				return root
+			})
+			if code := Execute(); code != 3 {
+				t.Fatalf("Execute code=%d", code)
+			}
+			if !failWriter && !strings.Contains(stdout.String(), `"outcome": "failure"`) {
+				t.Fatalf("stdout=%q", stdout.String())
+			}
+		})
+	}
+}
+
+func TestFrameworkPublicRootRequiresResultFromActiveCommand(t *testing.T) {
+	root := NewRootCommand(context.Background())
+	leaf := &cobra.Command{Use: "active-no-result", RunE: func(*cobra.Command, []string) error { return nil }}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+	root.SetArgs([]string{"active-no-result"})
+	if _, err := root.ExecuteC(); err == nil || !strings.Contains(err.Error(), "without a CommandResult") {
+		t.Fatalf("ExecuteC error=%v", err)
+	}
+}
+
+func TestFrameworkAbortOutputSinkRemoveFailure(t *testing.T) {
+	originalRemove := rootRemoveFile
+	t.Cleanup(func() { rootRemoveFile = originalRemove })
+	file, err := os.CreateTemp(t.TempDir(), "abort-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	rootRemoveFile = func(string) error { return errors.New("remove failed") }
+	cmd := &cobra.Command{Use: "abort"}
+	cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{file: file, tempPath: file.Name()}))
+	if err := abortOutputSink(cmd); err == nil || !strings.Contains(err.Error(), "remove temporary") {
+		t.Fatalf("abort error=%v", err)
+	}
+}
+
+func TestFrameworkOutputSinkHookWrappingAndCleanupEdges(t *testing.T) {
+	installOutputSinkRunBoundary(nil)
+	plain := &cobra.Command{Use: "plain"}
+	plain.SetContext(context.Background())
+	installOutputSinkRunBoundary(plain)
+
+	// newBoundaryChild builds a leaf whose --output lives on the root's
+	// persistent flag set, matching production wiring (a local --output flag
+	// belongs to the leaf's own business contract and skips the sink).
+	newBoundaryChild := func(outputPath string) *cobra.Command {
+		root := &cobra.Command{Use: "root"}
+		root.PersistentFlags().String("output", outputPath, "")
+		cmd := &cobra.Command{Use: "leaf"}
+		root.AddCommand(cmd)
+		cmd.SetContext(context.Background())
+		return cmd
+	}
+
+	var calls int
+	cmd := newBoundaryChild("")
+	cmd.RunE = func(*cobra.Command, []string) error { calls++; return nil }
+	cmd.PostRunE = func(*cobra.Command, []string) error { calls++; return nil }
+	installOutputSinkRunBoundary(cmd)
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.PostRunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	runOnly := newBoundaryChild("")
+	runOnly.Run = func(*cobra.Command, []string) { calls++ }
+	runOnly.PostRun = func(*cobra.Command, []string) { calls++ }
+	installOutputSinkRunBoundary(runOnly)
+	if runOnly.Run != nil || runOnly.RunE == nil {
+		t.Fatal("Run-only leaf must be converted to RunE so sink setup errors surface")
+	}
+	if err := runOnly.RunE(runOnly, nil); err != nil {
+		t.Fatal(err)
+	}
+	runOnly.PostRun(runOnly, nil)
+	if calls != 4 {
+		t.Fatalf("hook calls=%d", calls)
+	}
+
+	// A sink setup failure at Run entry returns before the business hook runs.
+	testseam.Swap(t, &rootCreateTemp, func(string, string) (*os.File, error) { return nil, errors.New("create failed") })
+	failCmd := newBoundaryChild(filepath.Join(t.TempDir(), "out.txt"))
+	businessRan := false
+	failCmd.RunE = func(*cobra.Command, []string) error { businessRan = true; return nil }
+	installOutputSinkRunBoundary(failCmd)
+	if err := failCmd.RunE(failCmd, nil); err == nil || !strings.Contains(err.Error(), "create failed") {
+		t.Fatalf("Run entry sink setup error=%v", err)
+	}
+	if businessRan {
+		t.Fatal("business hook ran after sink setup failure")
+	}
+	testseam.Swap(t, &rootCreateTemp, os.CreateTemp)
+
+	// A Run entry business error aborts the open sink: the temporary file is
+	// removed and the final target is never created.
+	abortTarget := filepath.Join(t.TempDir(), "result.txt")
+	abortCmd := newBoundaryChild(abortTarget)
+	abortCmd.RunE = func(*cobra.Command, []string) error { return errors.New("boom") }
+	installOutputSinkRunBoundary(abortCmd)
+	if err := abortCmd.RunE(abortCmd, nil); err == nil || !strings.Contains(err.Error(), "boom") {
+		t.Fatalf("Run entry business error=%v", err)
+	}
+	if _, err := os.Stat(abortTarget); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("target exists after aborted run: %v", err)
+	}
+	assertNoOutputTemps(t, abortTarget)
+
+	// A second configureOutputSink call on an already-open sink (a reused
+	// command tree stacks one Run wrapper per ExecuteC) must not replace the
+	// live sink with a second temporary file.
+	repeatTarget := filepath.Join(t.TempDir(), "result.txt")
+	repeatCmd := newBoundaryChild(repeatTarget)
+	if err := configureOutputSink(repeatCmd); err != nil {
+		t.Fatal(err)
+	}
+	first := outputSinkForCommand(repeatCmd)
+	if first == nil {
+		t.Fatal("first configureOutputSink did not open a sink")
+	}
+	if err := configureOutputSink(repeatCmd); err != nil {
+		t.Fatal(err)
+	}
+	if second := outputSinkForCommand(repeatCmd); second != first {
+		t.Fatal("configureOutputSink replaced an open sink")
+	}
+	if err := abortOutputSink(repeatCmd); err != nil {
+		t.Fatal(err)
+	}
+	assertNoOutputTemps(t, repeatTarget)
+
+	file2, err := os.CreateTemp(t.TempDir(), "sink-error-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	errorCmd := &cobra.Command{Use: "error"}
+	errorCmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{file: file2, tempPath: file2.Name(), target: "unused"}))
+	if err := runWithOutputSinkErrorCleanup(errorCmd, func() error { return errors.New("boom") }); err == nil {
+		t.Fatal("run error swallowed")
+	}
+
+	file3, err := os.CreateTemp(t.TempDir(), "sink-panic-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	panicCmd := &cobra.Command{Use: "panic"}
+	panicCmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{file: file3, tempPath: file3.Name(), target: "unused"}))
+	func() {
+		defer func() {
+			if recover() == nil {
+				t.Fatal("panic swallowed")
+			}
+		}()
+		_ = runWithOutputSinkErrorCleanup(panicCmd, func() error { panic("boom") })
+	}()
+
+	if closeOutputSink(nil) != nil || abortOutputSink(nil) != nil || outputSinkForCommand(nil) != nil {
+		t.Fatal("nil sink guards failed")
+	}
+	finished := &outputSinkState{finished: true, file: file3}
+	finishedCmd := &cobra.Command{Use: "finished"}
+	finishedCmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, finished))
+	if closeOutputSink(finishedCmd) != nil || abortOutputSink(finishedCmd) != nil {
+		t.Fatal("finished sink was processed twice")
+	}
+}
+
+type frameworkFailWriter struct{}
+
+func (frameworkFailWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") }
+
+func TestFrameworkExecutePanicBeforeEmissionUsesUnifiedFailure(t *testing.T) {
+	for _, failWriter := range []bool{false, true} {
+		t.Run(map[bool]string{false: "emits", true: "fallback"}[failWriter], func(t *testing.T) {
+			testseam.Protect(t, &os.Args)
+			os.Args = []string{"dws"}
+			testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+			testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+			testseam.Swap(t, &rootStopAllStdioClients, func() {})
+			var stdout bytes.Buffer
+			testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+				cmd := &cobra.Command{Use: "dws"}
+				cmd.SetContext(ctx)
+				output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+				if failWriter {
+					cmd.SetOut(frameworkFailWriter{})
+				} else {
+					cmd.SetOut(&stdout)
+				}
+				cmd.SetErr(&bytes.Buffer{})
+				return cmd
+			})
+			testseam.Swap(t, &rootExecuteCommand, func(*cobra.Command) (*cobra.Command, error) { panic("before emission") })
+			if code := Execute(); code != 5 {
+				t.Fatalf("Execute code=%d", code)
+			}
+			if !failWriter && !strings.Contains(stdout.String(), `"outcome": "failure"`) {
+				t.Fatalf("stdout=%q", stdout.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageFrameworkExecuteRareOutcomeBranches(t *testing.T) {
+	t.Run("preparse interrupted", func(t *testing.T) {
+		var stdout bytes.Buffer
+		installSignalExecuteSeams(t, true, &stdout, io.Discard)
+		testseam.Swap(t, &rootRunPreParse, func(cmd *cobra.Command, _ *pipeline.Engine) error {
+			signalSelf(t, syscall.SIGINT)
+			<-cmd.Context().Done()
+			return errors.New("preparse failed")
+		})
+		if code := Execute(); code != 130 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("nil executed after emission attempt", func(t *testing.T) {
+		installSignalExecuteSeams(t, true, io.Discard, io.Discard)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			cmd.SetOut(frameworkFailWriter{})
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			_, _, _ = output.EmitStoredResult(cmd)
+			signalSelf(t, syscall.SIGINT)
+			<-cmd.Context().Done()
+			return nil, cmd.Context().Err()
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("publication failure after emission", func(t *testing.T) {
+		var stdout bytes.Buffer
+		installSignalExecuteSeams(t, true, &stdout, io.Discard)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := output.EmitStoredResult(cmd); err != nil {
+				t.Fatal(err)
+			}
+			return cmd, newOutputPublicationError("publish", errors.New("rename failed"))
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("publication failure envelope writer also fails", func(t *testing.T) {
+		installSignalExecuteSeams(t, true, io.Discard, io.Discard)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := output.EmitStoredResult(cmd); err != nil {
+				t.Fatal(err)
+			}
+			file, err := os.CreateTemp(t.TempDir(), "finished-output-*")
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer file.Close()
+			state := &outputSinkState{file: file, original: frameworkFailWriter{}, finished: true}
+			cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, state))
+			return cmd, newOutputPublicationError("publish", errors.New("rename failed"))
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("failure envelope cannot be written", func(t *testing.T) {
+		installSignalExecuteSeams(t, true, io.Discard, io.Discard)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			cmd.SetOut(frameworkFailWriter{})
+			return cmd, errors.New("business failed")
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("late output publication warning", func(t *testing.T) {
+		installSignalExecuteSeams(t, false, io.Discard, io.Discard)
+		testseam.Swap(t, &rootRenameFile, func(string, string) error { return errors.New("rename failed") })
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			file, err := os.CreateTemp(t.TempDir(), "late-output-*")
+			if err != nil {
+				t.Fatal(err)
+			}
+			state := &outputSinkState{file: file, tempPath: file.Name(), target: filepath.Join(t.TempDir(), "result.json")}
+			cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, state))
+			return cmd, nil
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	for _, tc := range []struct {
+		name       string
+		unified    bool
+		original   io.Writer
+		wantOutput bool
+	}{
+		{name: "unified late publication failure", unified: true, original: &bytes.Buffer{}, wantOutput: true},
+		{name: "legacy late publication failure", original: io.Discard},
+		{name: "late publication failure writer fails", unified: true, original: frameworkFailWriter{}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			installSignalExecuteSeams(t, tc.unified, io.Discard, io.Discard)
+			testseam.Swap(t, &rootRenameFile, func(string, string) error { return errors.New("rename failed") })
+			var original io.Writer = tc.original
+			testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+				file, err := os.CreateTemp(t.TempDir(), "panic-output-*")
+				if err != nil {
+					t.Fatal(err)
+				}
+				cmd.SetOut(file)
+				cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, &outputSinkState{
+					file: file, original: original, tempPath: file.Name(), target: filepath.Join(t.TempDir(), "result.json"),
+				}))
+				panic("after sink open")
+			})
+			if code := Execute(); code != 5 {
+				t.Fatalf("Execute code=%d", code)
+			}
+			if tc.wantOutput && !strings.Contains(tc.original.(*bytes.Buffer).String(), `"outcome": "failure"`) {
+				t.Fatalf("stdout=%q", tc.original.(*bytes.Buffer).String())
+			}
+		})
+	}
+
+	t.Run("abort failure is diagnostic", func(t *testing.T) {
+		installSignalExecuteSeams(t, false, io.Discard, io.Discard)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			file, err := os.CreateTemp(t.TempDir(), "abort-output-*")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := file.Close(); err != nil {
+				t.Fatal(err)
+			}
+			cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, &outputSinkState{
+				file: file, original: io.Discard, tempPath: file.Name(), target: filepath.Join(t.TempDir(), "result.json"),
+			}))
+			return cmd, errors.New("business failed")
+		})
+		if code := Execute(); code != 5 {
+			t.Fatalf("Execute code=%d", code)
+		}
+	})
+
+	t.Run("publication helper requires observable finished transaction", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "unified"}
+		output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+		file, err := os.CreateTemp(t.TempDir(), "unfinished-output-*")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer file.Close()
+		cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{
+			file: file, finished: true,
+		}))
+		if _, handled, emitErr := emitOutputPublicationFailure(cmd, newOutputPublicationError("publish", errors.New("rename failed"))); handled || emitErr != nil {
+			t.Fatalf("handled=%v err=%v", handled, emitErr)
+		}
+	})
+}
+
+type frameworkPanicWriter struct{}
+
+func (frameworkPanicWriter) Write([]byte) (int, error) { panic("writer panic") }
+
+func TestCrossPlatformCoverageFrameworkRootHookErrors(t *testing.T) {
+	t.Run("flag group validation", func(t *testing.T) {
+		root := NewRootCommand(context.Background())
+		leaf := &cobra.Command{Use: "exclusive", RunE: func(*cobra.Command, []string) error { return nil }}
+		leaf.Flags().Bool("left", false, "")
+		leaf.Flags().Bool("right", false, "")
+		leaf.MarkFlagsMutuallyExclusive("left", "right")
+		root.AddCommand(leaf)
+		root.SetOut(io.Discard)
+		root.SetErr(io.Discard)
+		root.SetArgs([]string{"exclusive", "--left", "--right"})
+		if err := root.Execute(); err == nil {
+			t.Fatal("expected mutually-exclusive flag error")
+		}
+	})
+
+	t.Run("edition pre-run error", func(t *testing.T) {
+		old := edition.Get()
+		t.Cleanup(func() { edition.Override(old) })
+		edition.Override(&edition.Hooks{AfterPersistentPreRun: func(*cobra.Command, []string) error {
+			return errors.New("edition hook failed")
+		}})
+		root := NewRootCommand(context.Background())
+		root.SetOut(io.Discard)
+		root.SetErr(io.Discard)
+		root.SetArgs([]string{"version"})
+		if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "edition hook failed") {
+			t.Fatalf("Execute error=%v", err)
+		}
+	})
+
+	t.Run("post-run emission panic", func(t *testing.T) {
+		root := NewRootCommand(context.Background())
+		cmd := &cobra.Command{Use: "panic-output"}
+		output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+		ctx, _ := output.WithResultStore(context.Background())
+		cmd.SetContext(ctx)
+		cmd.SetOut(frameworkPanicWriter{})
+		if err := output.StoreResult(ctx, output.Success(map[string]any{"ok": true})); err != nil {
+			t.Fatal(err)
+		}
+		defer func() {
+			if recover() == nil {
+				t.Fatal("expected post-run panic")
+			}
+		}()
+		_ = root.PersistentPostRunE(cmd, nil)
+	})
+}
@@ -58,7 +58,7 @@ func TestP1SharedAlwaysIncludedWithSkillFilter(t *testing.T) {
 	// Actually install with the filtered+mandatory set and assert dingtalk-shared landed.
 	dest := t.TempDir()
 	var out, errOut bytes.Buffer
-	if _, _, err := installMultiSkillToHomes(src, final, []string{dest}, &out, &errOut); err != nil {
+	if _, _, err := installMultiSkillToHomes(src, final, []string{dest}, &out, &errOut, true); err != nil {
 		t.Fatalf("install: %v (%s)", err, errOut.String())
 	}
 	if _, err := os.Stat(filepath.Join(dest, "dingtalk-shared", "SKILL.md")); err != nil {
@@ -79,13 +79,15 @@ func TestCrossPlatformCoveragePATRetryRemainingPureAndWaitCoverage(t *testing.T)
 	if ok, err := WaitForPatAuthorization(context.Background(), "", &out); err != nil || ok {
 		t.Fatalf("timed out authorization = %v, %v", ok, err)
 	}
-	patAuthorizationTimeout = 5 * time.Millisecond
+	patAuthorizationTimeout = time.Second
 	patAuthorizationPollInterval = time.Millisecond
+	pollCtx, pollCancel := context.WithCancel(context.Background())
 	patResolveAccessToken = func(context.Context, string, string) (string, error) {
+		pollCancel()
 		return "", authpkg.ErrTokenDataNotFound
 	}
 	out.Reset()
-	if ok, err := WaitForPatAuthorization(context.Background(), "", &out); err != nil || ok || !strings.Contains(out.String(), "等待授权中") {
+	if ok, err := WaitForPatAuthorization(pollCtx, "", &out); ok || !errors.Is(err, context.Canceled) || !strings.Contains(out.String(), "等待授权中") {
 		t.Fatalf("invalid-token polling = %v, %v, output %q", ok, err, out.String())
 	}
 }
@@ -15,24 +15,24 @@ package app

 import (
 	"context"
+	"encoding/json"
 	stderrors "errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"net/url"
 	"os"
-	"os/signal"
 	"path/filepath"
 	"sort"
 	"strings"
 	"sync"
-	"syscall"
 	"time"

 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
@@ -40,6 +40,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline/handlers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/usage"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -58,8 +59,14 @@ var (
 	rootStopAllStdioClients         = StopAllStdioClients
 	rootLoadPlugins                 = loadPlugins
 	rootMkdirAll                    = os.MkdirAll
-	rootCreateFile                  = os.Create
+	rootCreateTemp                  = os.CreateTemp
+	rootSyncFile                    = (*os.File).Sync
 	rootCloseFile                   = (*os.File).Close
+	// os.Rename replaces an existing non-directory target on every supported
+	// Go host; the Windows implementation uses MOVEFILE_REPLACE_EXISTING. Keep
+	// the temporary file beside the target so publication stays on one volume.
+	rootRenameFile                  = os.Rename
+	rootRemoveFile                  = os.Remove
 	rootPluginInjectConfigEnv       = (*plugin.Loader).InjectPluginConfigEnv
 	rootPluginLoadUser              = (*plugin.Loader).LoadUser
 	rootPluginLoadDev               = (*plugin.Loader).LoadDev
@@ -76,10 +83,53 @@ var (

 // Execute runs the root command and returns the process exit code.
 func Execute() (exitCode int) {
+	var (
+		root        *cobra.Command
+		executed    *cobra.Command
+		resultStore *output.ResultStore
+	)
 	defer func() {
 		if r := recover(); r != nil {
-			fmt.Fprintf(os.Stderr, "Error: internal panic: %v\n", r)
-			exitCode = 5
+			target := executed
+			if target == nil && root != nil {
+				if found, _, err := root.Find(os.Args[1:]); err == nil {
+					target = found
+				}
+			}
+			if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted {
+				exitCode = code
+				if target != nil {
+					fmt.Fprintf(target.ErrOrStderr(), "Warning: command panicked after result emission attempt: %v\n", r)
+				}
+			} else if target != nil && output.UsesUnifiedResult(target) {
+				info := &output.ErrorInfo{Type: "internal", ExitCode: 5, Message: fmt.Sprintf("internal panic: %v", r)}
+				if code, err := output.EmitResult(target, output.Failure(info)); err == nil {
+					exitCode = code
+				} else {
+					fmt.Fprintf(os.Stderr, "Error: internal panic: %v\n", r)
+					exitCode = 5
+				}
+			} else {
+				fmt.Fprintf(os.Stderr, "Error: internal panic: %v\n", r)
+				exitCode = 5
+			}
+			if executed == nil {
+				executed = target
+			}
+		}
+		CloseFileLogger()
+		if executed != nil {
+			if err := closeOutputSink(executed); err != nil {
+				if code, handled, emitErr := emitOutputPublicationFailure(executed, err); handled && emitErr == nil {
+					exitCode = code
+				} else {
+					exitCode = apperrors.ExitCode(err)
+					fmt.Fprintf(os.Stderr, "Warning: close output sink: %v\n", err)
+					if emitErr != nil {
+						fmt.Fprintf(os.Stderr, "Warning: emit output publication failure: %v\n", emitErr)
+					}
+				}
+			}
 		}
 	}()

@@ -95,15 +145,17 @@ func Execute() (exitCode int) {
 		timing.WriteReportIfEnabled(RawVersion(), SanitizeCommand(os.Args))
 	}()

-	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer cancel()
-
 	// Attach timing collector to context for use by child components
-	ctx = WithTimingCollector(ctx, timing)
+	ctx := WithTimingCollector(context.Background(), timing)
+	ctx, resultStore = output.WithResultStore(ctx)
+	var signalState *processSignalState
+	var stopSignals func()
+	ctx, signalState, stopSignals = installProcessSignalContext(ctx, resultStore)
+	defer stopSignals()

 	initStart := time.Now()
 	engine := newPipelineEngine()
-	root := rootNewRootCommandWithEngine(ctx, engine)
+	root = rootNewRootCommandWithEngine(ctx, engine)
 	timing.Record("cmd_init", time.Since(initStart))

 	// Run PreParse handlers on raw argv before Cobra parses flags.
@@ -111,16 +163,89 @@ func Execute() (exitCode int) {
 	// and --limit100 → --limit 100.
 	if err := rootRunPreParse(root, engine); err != nil {
 		err = newPreParseValidationError(err)
+		if interrupted, _ := signalState.outcome(); interrupted != nil {
+			err = interrupted
+		}
+		if target, _, findErr := root.Find(os.Args[1:]); findErr == nil && target != nil && output.UsesUnifiedResult(target) {
+			result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err))
+			code, emitErr := output.EmitResult(target, result)
+			if emitErr == nil {
+				return code
+			}
+		}
 		_ = printExecutionError(root, os.Stdout, os.Stderr, err)
 		return apperrors.ExitCode(err)
 	}

-	executed, err := rootExecuteCommand(root)
+	var err error
+	executed, err = rootExecuteCommand(root)
+	// PersistentPostRunE normally commits or aborts the transactional output
+	// sink. Finalize once more at the process boundary so custom execution
+	// seams, embedding callers, or future hook changes cannot leave publication
+	// errors to a defer that runs after the process exit code is fixed.
+	if executed != nil {
+		if err == nil {
+			if closeErr := closeOutputSink(executed); closeErr != nil {
+				err = closeErr
+			}
+		} else if abortErr := abortOutputSink(executed); abortErr != nil {
+			fmt.Fprintf(executed.ErrOrStderr(), "Warning: abort output sink after command failure: %v\n", abortErr)
+		}
+	}
+	interrupted, primaryCompletedBeforeSignal := signalState.outcome()
+	if interrupted != nil && !primaryCompletedBeforeSignal {
+		if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted {
+			var publicationErr *outputPublicationError
+			if err != nil && stderrors.As(err, &publicationErr) {
+				// The successful result was written only to a transaction that did
+				// not publish. Let the error path replace it with one observable
+				// failure envelope on the restored original stream.
+			} else {
+				if executed == nil {
+					executed = root
+				}
+				fmt.Fprintf(executed.ErrOrStderr(), "Warning: process interrupted after result emission attempt: %v\n", interrupted)
+				// Once publication starts, its stored exit code is authoritative. A
+				// signal recorded just before or during publication must not turn a
+				// successfully emitted result into a contradictory 130/143 process
+				// status; likewise, a failed publication must retain its internal
+				// error code instead of being relabelled as cancellation.
+				return code
+			}
+		}
+		var publicationErr *outputPublicationError
+		if err == nil || !stderrors.As(err, &publicationErr) {
+			err = interrupted
+		}
+	}
 	if err != nil {
 		if executed == nil {
 			executed = root
 		}
+		if code, attempted, _, _ := output.StoredEmissionState(resultStore); attempted {
+			var publicationErr *outputPublicationError
+			if stderrors.As(err, &publicationErr) {
+				if failureCode, handled, emitErr := emitOutputPublicationFailure(executed, publicationErr); handled {
+					if emitErr == nil {
+						return failureCode
+					}
+					fmt.Fprintf(executed.ErrOrStderr(), "Warning: emit output publication failure: %v\n", emitErr)
+				}
+				return apperrors.ExitCode(publicationErr)
+			}
+			fmt.Fprintf(executed.ErrOrStderr(), "Warning: command hook failed after result emission: %v\n", err)
+			return code
+		}
 		err = rewordRequiredFlagError(err)
+		var raw apperrors.RawStderrError
+		if output.UsesUnifiedResult(executed) && !stderrors.As(err, &raw) {
+			result := output.FailureWithExitCode(errorInfoFromExecutionError(err), apperrors.ExitCode(err))
+			code, emitErr := output.EmitResult(executed, result)
+			if emitErr == nil {
+				return code
+			}
+			err = apperrors.NewInternal("emit failure result: "+emitErr.Error(), apperrors.WithCause(emitErr))
+		}
 		if isUnknownCommandError(err) {
 			executed.SetOut(os.Stderr)
 			_ = executed.Help()
@@ -129,9 +254,121 @@ func Execute() (exitCode int) {
 		_ = printExecutionError(executed, os.Stdout, os.Stderr, err)
 		return apperrors.ExitCode(err)
 	}
+	if code, emitted := output.StoredExitCode(resultStore); emitted {
+		return code
+	}
 	return 0
 }

+// errorInfoFromExecutionError projects the repository error model into the unified
+// failure body. Exit code and category are derived from the same error value,
+// preventing the wire and process status from drifting apart.
+func errorInfoFromExecutionError(err error) *output.ErrorInfo {
+	exitCode := apperrors.ExitCode(err)
+	info := &output.ErrorInfo{
+		Type:     errorTypeForExitCode(exitCode),
+		ExitCode: exitCode,
+		Message:  err.Error(),
+	}
+	var interrupted *processInterruption
+	if stderrors.As(err, &interrupted) && interrupted != nil {
+		info.Type = "internal"
+		info.Subtype = interrupted.Subtype()
+		return info
+	}
+	if stderrors.Is(err, context.DeadlineExceeded) {
+		info.Subtype = "deadline_exceeded"
+	}
+	var cliErr *helpers.CLIError
+	if stderrors.As(err, &cliErr) && cliErr != nil {
+		info.UpstreamCode = cliErr.Code
+		info.Hint = cliErr.Suggestion
+		info.Operation = cliErr.Operation
+	}
+	var callErr *transport.CallError
+	if stderrors.As(err, &callErr) && callErr != nil {
+		info.HTTPStatus = callErr.HTTPStatus
+		info.RPCCode = callErr.RPCCode
+		info.Stage = string(callErr.Stage)
+		if callErr.RequestID != "" {
+			info.RequestID = callErr.RequestID
+		} else if callErr.TraceID != "" {
+			info.RequestID = callErr.TraceID
+		}
+	}
+	var typed *apperrors.Error
+	if !stderrors.As(err, &typed) || typed == nil {
+		return info
+	}
+	if typed.Category == apperrors.CategoryPartial {
+		// An error lacks the item-level data required by partial_failure.
+		// Callers must use output.Partial; fail closed consistently otherwise.
+		info.Type = string(apperrors.CategoryInternal)
+	} else {
+		info.Type = string(typed.Category)
+	}
+	info.Subtype = typed.Reason
+	if typed.Hint != "" {
+		info.Hint = typed.Hint
+	}
+	info.Actions = append([]string(nil), typed.Actions...)
+	info.Retryable = typed.RetryableSet && typed.Retryable
+	info.RetryAfterSeconds = typed.RetryAfterSeconds
+	if typed.RPCCode != 0 {
+		info.RPCCode = typed.RPCCode
+	}
+	if typed.ServerDiag.TraceID != "" {
+		info.TraceID = typed.ServerDiag.TraceID
+	}
+	if typed.Operation != "" {
+		info.Operation = typed.Operation
+	}
+	info.ServerKey = typed.ServerKey
+	info.Origin = typed.Origin
+	if typed.FailureStage != "" {
+		info.Stage = typed.FailureStage
+	}
+	info.ExecutionStarted = typed.ExecutionStarted
+	if typed.NextRetryAt != nil {
+		info.NextRetryAt = typed.NextRetryAt.UTC().Format(time.RFC3339)
+	}
+	info.AvailableFlags = append([]string(nil), typed.AvailableFlags...)
+	info.SnapshotPath = typed.Snapshot
+	info.Details = typed.Details
+	if len(typed.RPCData) > 0 {
+		var rpcData any
+		if json.Unmarshal(typed.RPCData, &rpcData) == nil {
+			info.RPCData = rpcData
+		}
+	}
+	info.TechnicalDetail = typed.ServerDiag.TechnicalDetail
+	info.FriendlyHint, info.ActionURL = apperrors.ServerGuidance(typed.ServerDiag)
+	if typed.Cause != nil {
+		info.Cause = typed.Cause.Error()
+	}
+	if typed.ServerDiag.ServerErrorCode != "" {
+		info.UpstreamCode = typed.ServerDiag.ServerErrorCode
+	}
+	return info
+}
+
+func errorTypeForExitCode(code int) string {
+	switch code {
+	case 1:
+		return "api"
+	case 2:
+		return "auth"
+	case 3:
+		return "validation"
+	case 4:
+		return "permission"
+	case 6:
+		return "discovery"
+	default:
+		return "internal"
+	}
+}
+
 // newPreParseValidationError keeps pipeline handler identity in internal logs
 // while exposing only the underlying parameter-domain error to CLI users.
 func newPreParseValidationError(err error) error {
@@ -368,6 +605,7 @@ func NewRootCommand(ctx ...context.Context) *cobra.Command {
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
+	rootCtx, _ = output.WithResultStore(rootCtx)
 	return newRootCommandWithEngine(rootCtx, nil, true, false)
 }

@@ -390,6 +628,7 @@ func NewSchemaSourceRootCommand(ctx ...context.Context) *cobra.Command {
 // no pipeline processing is applied.
 func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine) *cobra.Command {
 	registerSchemaRuntimeDelivery()
+	rootCtx, _ = output.WithResultStore(rootCtx)
 	return newRootCommandWithEngine(rootCtx, engine, true, false)
 }

@@ -414,6 +653,25 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 			return cmd.Help()
 		},
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			// A public root may be reused by embedding callers through multiple
+			// ExecuteC invocations. Begin each invocation with an empty result
+			// lifecycle while retaining the store pointer observed by Execute's
+			// signal and exit-code handling. Declaration-only command trees do not
+			// install a store at construction time, so add one lazily when those
+			// trees are executed for compatibility and policy tests.
+			executionCtx, _ := output.WithResultStore(cmd.Context())
+			cmd.SetContext(executionCtx)
+			// WithResultStore above guarantees the reset precondition.
+			_ = output.ResetResultStore(executionCtx)
+			// Do not run Cobra's ValidateRequiredFlags/ValidateFlagGroups here:
+			// Cobra executes them between the leaf's PreRunE and RunE, and leaves
+			// rely on that order to normalize alias flags into required canonical
+			// flags (for example chat message download-media copies --msg-id into
+			// the required --message-id in PreRunE). Running them early fails the
+			// alias path before the leaf can normalize it. The transactional
+			// --output sink instead opens at Run entry (after Cobra's own
+			// validation), so validation failures still cannot strand a
+			// temporary file.
 			// Validate caller-provided identity labels before any edition hook
 			// or command network activity can run. Header-only library callers
 			// use the best-effort path in resolveIdentityHeaders instead.
@@ -436,19 +694,37 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 			// Configure global slog level based on --debug / --verbose flags.
 			configureLogLevel(flags)

-			if err := configureOutputSink(cmd); err != nil {
-				return err
-			}
+			installOutputSinkRunBoundary(cmd)
 			if fn := edition.Get().AfterPersistentPreRun; fn != nil {
-				return fn(cmd, args)
+				if err := fn(cmd, args); err != nil {
+					return err
+				}
 			}
 			return nil
 		},
-		PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
+		PersistentPostRunE: func(cmd *cobra.Command, args []string) (err error) {
+			defer func() {
+				if r := recover(); r != nil {
+					warnAbortOutputSink(cmd)
+					panic(r)
+				}
+				if err != nil {
+					warnAbortOutputSink(cmd)
+				}
+			}()
+			_, emitted, emitErr := output.EmitStoredResult(cmd)
 			StopAllStdioClients()
 			CloseAuditSink()
-			CloseFileLogger()
-			return closeOutputSink(cmd)
+			if emitErr != nil {
+				return apperrors.NewInternal("emit command result: "+emitErr.Error(), apperrors.WithCause(emitErr))
+			}
+			if output.UsesUnifiedResult(cmd) && !emitted {
+				return apperrors.NewInternal("framework 2.0 command returned without a CommandResult")
+			}
+			if closeErr := closeOutputSink(cmd); closeErr != nil {
+				return closeErr
+			}
+			return nil
 		},
 	}

@@ -472,7 +748,7 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 		newConfigCommand(),
 		newDoctorCommand(),
 		newRecoveryCommand(),
-		newEventCommand(),
+		newEventCommand(flags),
 		newAuditCommand(),
 		newCompletionCommand(root),
 		newUpgradeCommand(),
@@ -848,6 +1124,54 @@ func deduplicateCommands(root *cobra.Command) {
 	}
 }

+type outputSinkState struct {
+	mu       sync.Mutex
+	file     *os.File
+	original io.Writer
+	tempPath string
+	target   string
+	finished bool
+}
+
+type outputPublicationError struct {
+	cause error
+}
+
+func (e *outputPublicationError) Error() string { return e.cause.Error() }
+func (e *outputPublicationError) Unwrap() error { return e.cause }
+func (e *outputPublicationError) ExitCode() int { return 5 }
+
+func newOutputPublicationError(message string, cause error) error {
+	return &outputPublicationError{cause: fmt.Errorf("%s: %w", message, cause)}
+}
+
+// emitOutputPublicationFailure replaces a result that was rendered only into a
+// rolled-back transactional file with one observable failure envelope on the
+// original output stream. This is not a second public result: closeOutputSink
+// has removed the temporary file and restored cmd.OutOrStdout before returning
+// the publication error.
+func emitOutputPublicationFailure(cmd *cobra.Command, err error) (code int, handled bool, emitErr error) {
+	var publicationErr *outputPublicationError
+	if cmd == nil || !stderrors.As(err, &publicationErr) || !output.UsesUnifiedResult(cmd) {
+		return 0, false, nil
+	}
+	state := outputSinkForCommand(cmd)
+	if state == nil {
+		return 0, false, nil
+	}
+	state.mu.Lock()
+	original := state.original
+	finished := state.finished
+	state.mu.Unlock()
+	if original == nil || !finished {
+		return 0, false, nil
+	}
+	cmd.SetOut(original)
+	result := output.FailureWithExitCode(errorInfoFromExecutionError(publicationErr), apperrors.ExitCode(publicationErr))
+	code, emitErr = output.EmitResult(cmd, result)
+	return code, true, emitErr
+}
+
 func configureOutputSink(cmd *cobra.Command) error {
 	if local := cmd.LocalFlags().Lookup("output"); local != nil {
 		return nil
@@ -860,32 +1184,180 @@ func configureOutputSink(cmd *cobra.Command) error {
 	if outputPath == "" {
 		return nil
 	}
+	// A public root may be reused across ExecuteC calls, accumulating one Run
+	// wrapper per execution. When the sink for this invocation is already open,
+	// an inner wrapper must not replace it with a second temporary file.
+	if state := outputSinkForCommand(cmd); state != nil {
+		state.mu.Lock()
+		finished := state.finished
+		state.mu.Unlock()
+		if !finished {
+			return nil
+		}
+	}
 	if err := validateOptionalPath("--output", outputPath); err != nil {
 		return err
 	}
 	if err := rootMkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
 		return apperrors.NewInternal(fmt.Sprintf("failed to prepare output directory: %v", err))
 	}
-	file, err := rootCreateFile(outputPath)
+	tempPattern := "." + filepath.Base(outputPath) + ".tmp-*"
+	file, err := rootCreateTemp(filepath.Dir(outputPath), tempPattern)
 	if err != nil {
-		return apperrors.NewInternal(fmt.Sprintf("failed to create output file: %v", err))
+		return apperrors.NewInternal(fmt.Sprintf("failed to create temporary output file: %v", err))
 	}
+	originalOut := cmd.OutOrStdout()
 	cmd.SetOut(file)
-	cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, file))
+	cmd.SetContext(context.WithValue(cmd.Context(), outputFileContextKey{}, &outputSinkState{
+		file:     file,
+		original: originalOut,
+		tempPath: file.Name(),
+		target:   outputPath,
+	}))
 	return nil
 }

+// installOutputSinkRunBoundary defers opening the transactional --output sink
+// to the executed command's Run entry. Cobra runs ValidateRequiredFlags and
+// ValidateFlagGroups after the leaf's PreRunE and immediately before RunE, so
+// opening the sink there keeps two invariants at once: leaf PreRunE hooks can
+// still normalize alias flags into required canonical flags, and a validation
+// failure can never strand a temporary output file. Run-only leaves are
+// converted to RunE so a sink setup failure remains a returned error. Post-run
+// hooks keep the error cleanup wrapping so a post-run failure still aborts the
+// transaction; pre-run hooks need no wrapping because the sink cannot exist
+// before Run entry.
+func installOutputSinkRunBoundary(cmd *cobra.Command) {
+	if cmd == nil {
+		return
+	}
+	openSinkAndRun := func(run func(*cobra.Command, []string) error) func(*cobra.Command, []string) error {
+		return func(cmd *cobra.Command, args []string) error {
+			if err := configureOutputSink(cmd); err != nil {
+				return err
+			}
+			return runWithOutputSinkErrorCleanup(cmd, func() error { return run(cmd, args) })
+		}
+	}
+	if cmd.RunE != nil {
+		cmd.RunE = openSinkAndRun(cmd.RunE)
+	} else if cmd.Run != nil {
+		original := cmd.Run
+		cmd.Run = nil
+		cmd.RunE = openSinkAndRun(func(cmd *cobra.Command, args []string) error {
+			original(cmd, args)
+			return nil
+		})
+	}
+	if cmd.PostRunE != nil {
+		original := cmd.PostRunE
+		cmd.PostRunE = func(cmd *cobra.Command, args []string) error {
+			return runWithOutputSinkErrorCleanup(cmd, func() error { return original(cmd, args) })
+		}
+	}
+	if cmd.PostRun != nil {
+		original := cmd.PostRun
+		cmd.PostRun = func(cmd *cobra.Command, args []string) {
+			_ = runWithOutputSinkErrorCleanup(cmd, func() error {
+				original(cmd, args)
+				return nil
+			})
+		}
+	}
+}
+
+func runWithOutputSinkErrorCleanup(cmd *cobra.Command, run func() error) (err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			warnAbortOutputSink(cmd)
+			panic(r)
+		}
+		if err != nil {
+			warnAbortOutputSink(cmd)
+		}
+	}()
+	return run()
+}
+
+func warnAbortOutputSink(cmd *cobra.Command) {
+	if closeErr := abortOutputSink(cmd); closeErr != nil {
+		fmt.Fprintf(cmd.ErrOrStderr(), "Warning: close output sink: %v\n", closeErr)
+	}
+}
+
 func closeOutputSink(cmd *cobra.Command) error {
-	file, ok := cmd.Context().Value(outputFileContextKey{}).(*os.File)
-	if !ok || file == nil {
+	state := outputSinkForCommand(cmd)
+	if state == nil {
 		return nil
 	}
-	if err := rootCloseFile(file); err != nil {
-		return apperrors.NewInternal(fmt.Sprintf("failed to close output file: %v", err))
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	// A reusable Cobra tree must never retain the transactional file as its
+	// stdout after this execution. Restore the caller's writer on every terminal
+	// path, including sync/close/rename failures and repeated cleanup calls.
+	if state.original != nil {
+		cmd.SetOut(state.original)
+	}
+	if state.finished {
+		return nil
+	}
+	state.finished = true
+	if err := rootSyncFile(state.file); err != nil {
+		_ = rootCloseFile(state.file)
+		_ = rootRemoveFile(state.tempPath)
+		return newOutputPublicationError("failed to sync output file", err)
+	}
+	if err := rootCloseFile(state.file); err != nil {
+		_ = rootRemoveFile(state.tempPath)
+		return newOutputPublicationError("failed to close output file", err)
+	}
+	if err := rootRenameFile(state.tempPath, state.target); err != nil {
+		_ = rootRemoveFile(state.tempPath)
+		return newOutputPublicationError("failed to publish output file", err)
 	}
 	return nil
 }

+func abortOutputSink(cmd *cobra.Command) error {
+	state := outputSinkForCommand(cmd)
+	if state == nil {
+		return nil
+	}
+	state.mu.Lock()
+	defer state.mu.Unlock()
+	if state.finished {
+		return nil
+	}
+	state.finished = true
+	// A business error still needs the root execution boundary to publish one
+	// typed failure envelope. Restore the pre-transaction writer before closing
+	// and unlinking the temporary file so that failure emission cannot target a
+	// closed descriptor. The final --output target remains untouched.
+	if state.original != nil {
+		cmd.SetOut(state.original)
+	}
+	closeErr := rootCloseFile(state.file)
+	removeErr := rootRemoveFile(state.tempPath)
+	if closeErr != nil {
+		return apperrors.NewInternal(fmt.Sprintf("failed to close output file: %v", closeErr))
+	}
+	if removeErr != nil && !stderrors.Is(removeErr, os.ErrNotExist) {
+		return apperrors.NewInternal(fmt.Sprintf("failed to remove temporary output file: %v", removeErr))
+	}
+	return nil
+}
+
+func outputSinkForCommand(cmd *cobra.Command) *outputSinkState {
+	if cmd == nil || cmd.Context() == nil {
+		return nil
+	}
+	state, _ := cmd.Context().Value(outputFileContextKey{}).(*outputSinkState)
+	if state == nil || state.file == nil {
+		return nil
+	}
+	return state
+}
+
 func validateOptionalPath(flagName, path string) error {
 	path = strings.TrimSpace(path)
 	if path == "" {
@@ -157,11 +157,11 @@ func TestCrossPlatformCoverageRootFlagsPluginsAndOutputRemainingCoverage(t *test
 	})

 	oldMkdir := rootMkdirAll
-	oldCreate := rootCreateFile
+	oldCreate := rootCreateTemp
 	oldClose := rootCloseFile
 	t.Cleanup(func() {
 		rootMkdirAll = oldMkdir
-		rootCreateFile = oldCreate
+		rootCreateTemp = oldCreate
 		rootCloseFile = oldClose
 	})
 	wantErr := errors.New("filesystem")
@@ -193,17 +193,19 @@ func TestCrossPlatformCoverageRootFlagsPluginsAndOutputRemainingCoverage(t *test
 		t.Fatal("mkdir failure succeeded")
 	}
 	rootMkdirAll = func(string, os.FileMode) error { return nil }
-	rootCreateFile = func(string) (*os.File, error) { return nil, wantErr }
+	rootCreateTemp = func(string, string) (*os.File, error) { return nil, wantErr }
 	if err := configureOutputSink(newOutputCommand(filepath.Join("create-failure", "out"))); err == nil {
 		t.Fatal("create failure succeeded")
 	}
-	rootCreateFile = oldCreate
+	rootCreateTemp = oldCreate
 	file, err := os.CreateTemp(t.TempDir(), "close")
 	if err != nil {
 		t.Fatal(err)
 	}
 	cmd := &cobra.Command{Use: "close"}
-	cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, file))
+	cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{
+		file: file, tempPath: file.Name(), target: filepath.Join(filepath.Dir(file.Name()), "close-target"),
+	}))
 	rootCloseFile = func(*os.File) error { return wantErr }
 	if err := closeOutputSink(cmd); err == nil {
 		t.Fatal("close failure succeeded")
@@ -216,7 +218,9 @@ func TestCrossPlatformCoverageRootFlagsPluginsAndOutputRemainingCoverage(t *test
 	if err != nil {
 		t.Fatal(err)
 	}
-	cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, file))
+	cmd.SetContext(context.WithValue(context.Background(), outputFileContextKey{}, &outputSinkState{
+		file: file, tempPath: file.Name(), target: filepath.Join(filepath.Dir(file.Name()), "close-success-target"),
+	}))
 	if err := closeOutputSink(cmd); err != nil {
 		t.Fatalf("close success = %v", err)
 	}
@@ -0,0 +1,240 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/spf13/cobra"
+)
+
+func TestPublicRootDirectExecuteResetsUnifiedResultLifecycle(t *testing.T) {
+	root := NewRootCommand(context.Background())
+	var stdout bytes.Buffer
+	root.SetOut(&stdout)
+	root.SetErr(&bytes.Buffer{})
+	run := 0
+	leaf := &cobra.Command{
+		Use: "lifecycle-repeat",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			run++
+			return output.StoreResult(cmd.Context(), output.Success(map[string]any{"run": run}))
+		},
+	}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+
+	for want := 1; want <= 2; want++ {
+		stdout.Reset()
+		root.SetArgs([]string{"lifecycle-repeat", "--format", "json"})
+		executed, err := root.ExecuteC()
+		if err != nil {
+			t.Fatalf("ExecuteC run %d: %v", want, err)
+		}
+		if executed != leaf {
+			t.Fatalf("ExecuteC run %d executed %v, want lifecycle leaf", want, executed)
+		}
+		var envelope struct {
+			OK   bool `json:"ok"`
+			Data struct {
+				Run int `json:"run"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+			t.Fatalf("ExecuteC run %d output %q: %v", want, stdout.String(), err)
+		}
+		if !envelope.OK || envelope.Data.Run != want {
+			t.Fatalf("ExecuteC run %d envelope=%+v", want, envelope)
+		}
+	}
+
+	missing := &cobra.Command{Use: "lifecycle-missing", RunE: func(*cobra.Command, []string) error { return nil }}
+	output.SetCommandRollout(missing, output.RolloutUnifiedActive)
+	root.AddCommand(missing)
+	stdout.Reset()
+	root.SetArgs([]string{"lifecycle-missing", "--format", "json"})
+	if _, err := root.ExecuteC(); err == nil || !strings.Contains(err.Error(), "without a CommandResult") {
+		t.Fatalf("missing-result ExecuteC error=%v, want fresh lifecycle failure", err)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("missing-result ExecuteC replayed stale output %q", stdout.String())
+	}
+}
+
+func TestPublicRootRestoresStdoutAfterSuccessfulOutputPublication(t *testing.T) {
+	root := NewRootCommand(context.Background())
+	var stdout bytes.Buffer
+	root.SetOut(&stdout)
+	root.SetErr(&bytes.Buffer{})
+	run := 0
+	leaf := &cobra.Command{
+		Use: "lifecycle-output-repeat",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			run++
+			return output.StoreResult(cmd.Context(), output.Success(map[string]any{"run": run}))
+		},
+	}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+
+	target := filepath.Join(t.TempDir(), "result.json")
+	root.SetArgs([]string{"lifecycle-output-repeat", "--output", target, "--format", "json"})
+	if _, err := root.ExecuteC(); err != nil {
+		t.Fatalf("first ExecuteC: %v", err)
+	}
+	first, err := os.ReadFile(target)
+	if err != nil || !bytes.Contains(first, []byte(`"run": 1`)) {
+		t.Fatalf("published output=%q err=%v", first, err)
+	}
+
+	if err := root.PersistentFlags().Set("output", ""); err != nil {
+		t.Fatal(err)
+	}
+	stdout.Reset()
+	root.SetArgs([]string{"lifecycle-output-repeat", "--format", "json"})
+	if _, err := root.ExecuteC(); err != nil {
+		t.Fatalf("second ExecuteC: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"run": 2`) {
+		t.Fatalf("second stdout=%q", stdout.String())
+	}
+}
+
+func TestPublicRootDirectExecuteFailsWhenUnifiedSinkCannotPublish(t *testing.T) {
+	oldClose := rootCloseFile
+	t.Cleanup(func() { rootCloseFile = oldClose })
+	closeCalls := 0
+	rootCloseFile = func(file *os.File) error {
+		closeCalls++
+		if err := file.Close(); err != nil {
+			return err
+		}
+		return errors.New("late close diagnostic")
+	}
+
+	root := NewRootCommand(context.Background())
+	leaf := &cobra.Command{
+		Use: "lifecycle-unified",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return output.StoreResult(cmd.Context(), output.Success(map[string]any{"id": "ok"}))
+		},
+	}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+	root.SetArgs([]string{"lifecycle-unified", "--output", filepath.Join(t.TempDir(), "result.json")})
+
+	executed, err := root.ExecuteC()
+	if err == nil || apperrors.ExitCode(err) != 5 {
+		t.Fatalf("direct ExecuteC error=%v, want publication failure with exit 5", err)
+	}
+	if executed != leaf {
+		t.Fatalf("executed=%v, want lifecycle leaf", executed)
+	}
+	if closeCalls != 1 {
+		t.Fatalf("output sink close calls=%d, want 1", closeCalls)
+	}
+}
+
+func TestPublicRootDirectExecutePreservesLegacyCloseError(t *testing.T) {
+	oldClose := rootCloseFile
+	t.Cleanup(func() { rootCloseFile = oldClose })
+	rootCloseFile = func(file *os.File) error {
+		_ = file.Close()
+		return errors.New("legacy close failed")
+	}
+
+	root := NewRootCommandWithEngine(context.Background(), nil)
+	root.AddCommand(&cobra.Command{Use: "lifecycle-legacy", RunE: func(*cobra.Command, []string) error { return nil }})
+	root.SetArgs([]string{"lifecycle-legacy", "--output", filepath.Join(t.TempDir(), "result.txt")})
+	if _, err := root.ExecuteC(); err == nil || !strings.Contains(err.Error(), "legacy close failed") {
+		t.Fatalf("legacy direct ExecuteC error=%v, want close failure", err)
+	}
+}
+
+func TestPublicRootDirectExecuteClosesSinkOnHandlerError(t *testing.T) {
+	oldClose := rootCloseFile
+	t.Cleanup(func() { rootCloseFile = oldClose })
+	closeCalls := 0
+	rootCloseFile = func(file *os.File) error {
+		closeCalls++
+		return file.Close()
+	}
+
+	root := NewRootCommand(context.Background())
+	root.AddCommand(&cobra.Command{Use: "lifecycle-error", RunE: func(*cobra.Command, []string) error {
+		return errors.New("handler failed")
+	}})
+	root.SetArgs([]string{"lifecycle-error", "--output", filepath.Join(t.TempDir(), "result.txt")})
+	if _, err := root.ExecuteC(); err == nil || !strings.Contains(err.Error(), "handler failed") {
+		t.Fatalf("direct ExecuteC error=%v, want handler failure", err)
+	}
+	if closeCalls != 1 {
+		t.Fatalf("output sink close calls=%d, want 1", closeCalls)
+	}
+}
+
+func TestExecutePanicAfterEmissionPreservesSingleResultAndExitCode(t *testing.T) {
+	oldNormalize := rootNormalizeProcessProfileArgs
+	oldExecute := rootExecuteCommand
+	oldNewRoot := rootNewRootCommandWithEngine
+	oldPreParse := rootRunPreParse
+	oldStop := rootStopAllStdioClients
+	oldArgs := os.Args
+	t.Cleanup(func() {
+		rootNormalizeProcessProfileArgs = oldNormalize
+		rootExecuteCommand = oldExecute
+		rootNewRootCommandWithEngine = oldNewRoot
+		rootRunPreParse = oldPreParse
+		rootStopAllStdioClients = oldStop
+		os.Args = oldArgs
+	})
+	os.Args = []string{"dws"}
+	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
+	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
+	rootStopAllStdioClients = func() {}
+	var stdout, stderr bytes.Buffer
+	rootNewRootCommandWithEngine = func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+		cmd := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+		output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+		cmd.SetOut(&stdout)
+		cmd.SetErr(&stderr)
+		cmd.SetContext(ctx)
+		return cmd
+	}
+	rootExecuteCommand = func(cmd *cobra.Command) (*cobra.Command, error) {
+		result := output.Failure(&output.ErrorInfo{Type: "validation", Message: "bad input"})
+		if err := output.StoreResult(cmd.Context(), result); err != nil {
+			t.Fatal(err)
+		}
+		if _, _, err := output.EmitStoredResult(cmd); err != nil {
+			t.Fatal(err)
+		}
+		panic("after emission")
+	}
+
+	if code := Execute(); code != 3 {
+		t.Fatalf("Execute code=%d, want emitted validation code 3", code)
+	}
+	if got := strings.Count(stdout.String(), `"outcome": "failure"`); got != 1 {
+		t.Fatalf("stdout contains %d envelopes, want one: %s", got, stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "panicked after result emission attempt") {
+		t.Fatalf("panic diagnostic missing: %q", stderr.String())
+	}
+}
+
+func TestErrorInfoProjectionKeepsTraceIDDistinctFromRequestID(t *testing.T) {
+	err := apperrors.NewAPI("failed", apperrors.WithTraceID("trace-1"))
+	info := errorInfoFromExecutionError(err)
+	if info.TraceID != "trace-1" || info.RequestID != "" {
+		t.Fatalf("projection trace_id=%q request_id=%q", info.TraceID, info.RequestID)
+	}
+}
@@ -0,0 +1,377 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func TestOutputSinkAtomicallyReplacesExistingTargetWithMode0600(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.txt")
+	if err := os.WriteFile(target, []byte("original"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var tempMode os.FileMode
+	root := newAtomicOutputTestRoot(func(cmd *cobra.Command) error {
+		info, err := cmd.OutOrStdout().(*os.File).Stat()
+		if err != nil {
+			return err
+		}
+		tempMode = info.Mode().Perm()
+		_, err = fmt.Fprint(cmd.OutOrStdout(), "replacement")
+		return err
+	})
+	root.SetArgs([]string{"atomic-output", "--output", target})
+	if _, err := root.ExecuteC(); err != nil {
+		t.Fatalf("ExecuteC: %v", err)
+	}
+
+	assertOutputFile(t, target, "replacement", 0o600)
+	if tempMode != 0o600 {
+		t.Fatalf("temporary output mode=%#o, want 0600", tempMode)
+	}
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkHandlerFailurePreservesTarget(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.txt")
+	if err := os.WriteFile(target, []byte("original"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+
+	root := newAtomicOutputTestRoot(func(cmd *cobra.Command) error {
+		_, _ = fmt.Fprint(cmd.OutOrStdout(), "partial")
+		return errors.New("handler failed")
+	})
+	root.SetArgs([]string{"atomic-output", "--output", target})
+	if _, err := root.ExecuteC(); err == nil {
+		t.Fatal("ExecuteC succeeded")
+	}
+
+	assertOutputFile(t, target, "original", 0o640)
+	assertNoOutputTemps(t, target)
+}
+
+func TestExecuteUnifiedRunEFailureWithOutputRestoresStdoutAndPreservesTarget(t *testing.T) {
+	testseam.Protect(t, &os.Args)
+	os.Args = []string{"dws", "atomic-output-unified-failure", "--output", filepath.Join(t.TempDir(), "result.json"), "--format", "json"}
+	target := os.Args[3]
+	if err := os.WriteFile(target, []byte("original"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+	testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+	testseam.Swap(t, &rootStopAllStdioClients, func() {})
+	var stdout, stderr bytes.Buffer
+	testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, engine *pipeline.Engine) *cobra.Command {
+		root := NewRootCommandWithEngine(ctx, engine)
+		root.SetOut(&stdout)
+		root.SetErr(&stderr)
+		leaf := &cobra.Command{
+			Use: "atomic-output-unified-failure",
+			RunE: func(*cobra.Command, []string) error {
+				return apperrors.NewValidation("business validation failed")
+			},
+		}
+		output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+		root.AddCommand(leaf)
+		return root
+	})
+
+	if code := Execute(); code != 3 {
+		t.Fatalf("Execute exit code=%d, want validation code 3; stderr=%q", code, stderr.String())
+	}
+	var envelope struct {
+		OK      bool   `json:"ok"`
+		Outcome string `json:"outcome"`
+		Error   struct {
+			Type    string `json:"type"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("failure stdout=%q: %v; stderr=%q", stdout.String(), err, stderr.String())
+	}
+	if envelope.OK || envelope.Outcome != "failure" || envelope.Error.Type != "validation" || envelope.Error.Message != "business validation failed" {
+		t.Fatalf("failure envelope=%+v", envelope)
+	}
+	assertOutputFile(t, target, "original", 0o640)
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkPanicCleansTempAndPreservesTarget(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.txt")
+	if err := os.WriteFile(target, []byte("original"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	root := newAtomicOutputTestRoot(func(cmd *cobra.Command) error {
+		_, _ = fmt.Fprint(cmd.OutOrStdout(), "partial")
+		panic("boom")
+	})
+	root.SetArgs([]string{"atomic-output", "--output", target})
+	if recovered := executeAndRecover(root); recovered == nil {
+		t.Fatal("ExecuteC did not panic")
+	}
+
+	assertOutputFile(t, target, "original", 0o600)
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkRenameFailurePreservesTarget(t *testing.T) {
+	testseam.Swap(t, &rootRenameFile, func(string, string) error {
+		return errors.New("rename failed")
+	})
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.txt")
+	if err := os.WriteFile(target, []byte("original"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	root := newAtomicOutputTestRoot(func(cmd *cobra.Command) error {
+		_, err := fmt.Fprint(cmd.OutOrStdout(), "replacement")
+		return err
+	})
+	root.SetArgs([]string{"atomic-output", "--output", target})
+	if _, err := root.ExecuteC(); err == nil || err.Error() == "" {
+		t.Fatalf("ExecuteC error=%v, want publication failure", err)
+	}
+
+	assertOutputFile(t, target, "original", 0o600)
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkSyncAndCloseFailuresPreserveTarget(t *testing.T) {
+	tests := []struct {
+		name string
+		seam func(*testing.T)
+	}{
+		{
+			name: "sync",
+			seam: func(t *testing.T) {
+				testseam.Swap(t, &rootSyncFile, func(*os.File) error { return errors.New("sync failed") })
+			},
+		},
+		{
+			name: "close",
+			seam: func(t *testing.T) {
+				testseam.Swap(t, &rootCloseFile, func(file *os.File) error {
+					_ = file.Close()
+					return errors.New("close failed")
+				})
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tt.seam(t)
+			dir := t.TempDir()
+			target := filepath.Join(dir, "result.txt")
+			if err := os.WriteFile(target, []byte("original"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			root := newAtomicOutputTestRoot(func(cmd *cobra.Command) error {
+				_, err := fmt.Fprint(cmd.OutOrStdout(), "replacement")
+				return err
+			})
+			root.SetArgs([]string{"atomic-output", "--output", target})
+			if _, err := root.ExecuteC(); err == nil {
+				t.Fatal("ExecuteC succeeded")
+			}
+
+			assertOutputFile(t, target, "original", 0o600)
+			assertNoOutputTemps(t, target)
+		})
+	}
+}
+
+func TestOutputSinkUnifiedPublicationFailureFailsAndLeavesNoFinalFile(t *testing.T) {
+	testseam.Swap(t, &rootRenameFile, func(string, string) error {
+		return errors.New("rename failed")
+	})
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.json")
+
+	root := NewRootCommand()
+	leaf := &cobra.Command{
+		Use: "atomic-output-unified",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return output.StoreResult(cmd.Context(), output.Success(map[string]any{"id": "ok"}))
+		},
+	}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+	root.SetArgs([]string{"atomic-output-unified", "--output", target})
+	if _, err := root.ExecuteC(); err == nil {
+		t.Fatal("unified ExecuteC succeeded without publishing its output")
+	} else if code := apperrors.ExitCode(err); code != 5 {
+		t.Fatalf("publication exit code=%d, want 5: %v", code, err)
+	}
+	if _, err := os.Stat(target); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("final output exists after publication failure: %v", err)
+	}
+	assertNoOutputTemps(t, target)
+}
+
+func TestExecuteUnifiedPublicationFailureEmitsFailureOnOriginalStdout(t *testing.T) {
+	testseam.Protect(t, &os.Args)
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.json")
+	if err := os.WriteFile(target, []byte("original"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	os.Args = []string{"dws", "atomic-output-unified-publication", "--output", target, "--format", "json"}
+	testseam.Swap(t, &rootRenameFile, func(string, string) error { return errors.New("rename failed") })
+	testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+	testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+	testseam.Swap(t, &rootStopAllStdioClients, func() {})
+	var stdout, stderr bytes.Buffer
+	testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, engine *pipeline.Engine) *cobra.Command {
+		root := NewRootCommandWithEngine(ctx, engine)
+		root.SetOut(&stdout)
+		root.SetErr(&stderr)
+		leaf := &cobra.Command{
+			Use: "atomic-output-unified-publication",
+			RunE: func(cmd *cobra.Command, _ []string) error {
+				return output.StoreResult(cmd.Context(), output.Success(map[string]any{"id": "ok"}))
+			},
+		}
+		output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+		root.AddCommand(leaf)
+		return root
+	})
+
+	if code := Execute(); code != 5 {
+		t.Fatalf("Execute exit code=%d, want publication failure code 5; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	var envelope output.Envelope
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("publication failure stdout=%q: %v; stderr=%q", stdout.String(), err, stderr.String())
+	}
+	if envelope.OK || envelope.Outcome != output.OutcomeFailure || envelope.Error == nil || envelope.Error.Type != "internal" || envelope.Error.ExitCode != 5 {
+		t.Fatalf("publication failure envelope=%+v", envelope)
+	}
+	if !strings.Contains(envelope.Error.Message, "failed to publish output file") {
+		t.Fatalf("publication failure message=%q", envelope.Error.Message)
+	}
+	if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "failure"`)); got != 1 {
+		t.Fatalf("stdout contains %d failure envelopes, want one: %s", got, stdout.String())
+	}
+	if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "success"`)); got != 0 {
+		t.Fatalf("rolled-back success leaked to stdout: %s", stdout.String())
+	}
+	assertOutputFile(t, target, "original", 0o640)
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkEmissionFailurePreservesTarget(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.json")
+	if err := os.WriteFile(target, []byte("original"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	root := NewRootCommand()
+	leaf := &cobra.Command{
+		Use: "atomic-emission-failure",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"id": "ok"})); err != nil {
+				return err
+			}
+			return cmd.OutOrStdout().(*os.File).Close()
+		},
+	}
+	output.SetCommandRollout(leaf, output.RolloutUnifiedActive)
+	root.AddCommand(leaf)
+	root.SetArgs([]string{"atomic-emission-failure", "--output", target})
+	if _, err := root.ExecuteC(); err == nil {
+		t.Fatal("ExecuteC succeeded after emission failure")
+	}
+
+	assertOutputFile(t, target, "original", 0o600)
+	assertNoOutputTemps(t, target)
+}
+
+func TestOutputSinkValidationFailureDoesNotCreateTemp(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "result.txt")
+	if err := os.WriteFile(target, []byte("original"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	root := NewRootCommand()
+	leaf := &cobra.Command{Use: "atomic-validation", RunE: func(*cobra.Command, []string) error { return nil }}
+	leaf.Flags().String("required", "", "")
+	_ = leaf.MarkFlagRequired("required")
+	root.AddCommand(leaf)
+	root.SetArgs([]string{"atomic-validation", "--output", target})
+	if _, err := root.ExecuteC(); err == nil {
+		t.Fatal("ExecuteC succeeded without required flag")
+	}
+
+	assertOutputFile(t, target, "original", 0o600)
+	assertNoOutputTemps(t, target)
+}
+
+func newAtomicOutputTestRoot(run func(*cobra.Command) error) *cobra.Command {
+	root := NewRootCommand()
+	root.AddCommand(&cobra.Command{
+		Use: "atomic-output",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return run(cmd)
+		},
+	})
+	return root
+}
+
+func executeAndRecover(cmd *cobra.Command) (recovered any) {
+	defer func() { recovered = recover() }()
+	_, _ = cmd.ExecuteC()
+	return nil
+}
+
+func assertOutputFile(t *testing.T, path, want string, wantMode os.FileMode) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read output: %v", err)
+	}
+	if string(data) != want {
+		t.Fatalf("output=%q, want %q", data, want)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("stat output: %v", err)
+	}
+	if mode := info.Mode().Perm(); mode != wantMode {
+		t.Fatalf("output mode=%#o, want %#o", mode, wantMode)
+	}
+}
+
+func assertNoOutputTemps(t *testing.T, target string) {
+	t.Helper()
+	matches, err := filepath.Glob(filepath.Join(filepath.Dir(target), "."+filepath.Base(target)+".tmp-*"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(matches) != 0 {
+		t.Fatalf("temporary output files remain: %v", matches)
+	}
+}
@@ -0,0 +1,38 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"path/filepath"
+	"testing"
+)
+
+// TestChatDownloadMediaAliasPreRunNormalizesRequiredFlag is the root-level
+// regression for the alias normalization order: root's persistent pre-run must
+// not run Cobra's required-flag validation ahead of the leaf PreRunE.
+// chat message download-media copies --msg-id / --open-message-id into the
+// required --message-id flag in its PreRunE; validating early failed that
+// documented alias path with "missing required flag(s): --message-id".
+func TestChatDownloadMediaAliasPreRunNormalizesRequiredFlag(t *testing.T) {
+	for _, alias := range []string{"msg-id", "open-message-id"} {
+		t.Run(alias, func(t *testing.T) {
+			root := NewRootCommand(context.Background())
+			var stdout, stderr bytes.Buffer
+			root.SetOut(&stdout)
+			root.SetErr(&stderr)
+			target := filepath.Join(t.TempDir(), "download.bin")
+			root.SetArgs([]string{
+				"chat", "message", "download-media",
+				"--type", "mediaId",
+				"--resource-id", "media-1",
+				"--" + alias, "msg-1",
+				"--open-conversation-id", "cid-1",
+				"--output", target,
+				"--dry-run", "--format", "json",
+			})
+			if _, err := root.ExecuteC(); err != nil {
+				t.Fatalf("ExecuteC with alias --%s: %v\nstdout: %s\nstderr: %s", alias, err, stdout.String(), stderr.String())
+			}
+		})
+	}
+}
@@ -0,0 +1,229 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/spf13/cobra"
+)
+
+func TestExecuteEmitsStoredUnifiedResultAtSingleRootExit(t *testing.T) {
+	oldNormalize := rootNormalizeProcessProfileArgs
+	oldExecute := rootExecuteCommand
+	oldNewRoot := rootNewRootCommandWithEngine
+	oldPreParse := rootRunPreParse
+	oldStop := rootStopAllStdioClients
+	oldArgs := os.Args
+	t.Cleanup(func() {
+		rootNormalizeProcessProfileArgs = oldNormalize
+		rootExecuteCommand = oldExecute
+		rootNewRootCommandWithEngine = oldNewRoot
+		rootRunPreParse = oldPreParse
+		rootStopAllStdioClients = oldStop
+		os.Args = oldArgs
+	})
+	os.Args = []string{"dws"}
+	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
+	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
+	rootStopAllStdioClients = func() {}
+	rootNewRootCommandWithEngine = func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+		cmd := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+		cmd.SetContext(ctx)
+		return cmd
+	}
+
+	var stdout, stderr bytes.Buffer
+	executed := &cobra.Command{Use: "leaf"}
+	output.SetCommandRollout(executed, output.RolloutUnifiedActive)
+	executed.SetOut(&stdout)
+	executed.SetErr(&stderr)
+	rootExecuteCommand = func(root *cobra.Command) (*cobra.Command, error) {
+		executed.SetContext(root.Context())
+		if err := output.StoreResult(executed.Context(), output.Success(map[string]any{"id": "a"})); err != nil {
+			return executed, err
+		}
+		if _, _, err := output.EmitStoredResult(executed); err != nil {
+			return executed, err
+		}
+		return executed, nil
+	}
+	if code := Execute(); code != 0 {
+		t.Fatalf("Execute code=%d, want 0", code)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr=%q, want diagnostics only/empty", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"outcome": "success"`) || strings.Contains(stdout.String(), `"contract_version"`) {
+		t.Fatalf("stdout does not match the unified envelope: %s", stdout.String())
+	}
+}
+
+// TestRootExecutionErrorToStderrOnly 是 B184 的回归断言：失败信封（JSON 错误
+// 输出）恒走 stderr，stdout 严格为空（契约 §5.1：失败时 stdout 必须为空）。
+// printExecutionError 把 PrintJSON/PrintHuman 都写 stderr writer，stdout
+// writer 不得收到任何字节。
+func TestRootExecutionErrorToStderrOnly(t *testing.T) {
+	t.Parallel()
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().String("format", "json", "")
+	_ = root.PersistentFlags().Set("format", "json")
+
+	var stdout, stderr bytes.Buffer
+	if err := printExecutionError(root, &stdout, &stderr, apperrors.NewAuth("token expired")); err != nil {
+		t.Fatalf("printExecutionError() error = %v", err)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("failure must keep stdout empty, got %q", stdout.String())
+	}
+	want := "{\n  \"error\": {\n    \"category\": \"auth\",\n    \"code\": 2,\n    \"message\": \"token expired\"\n  }\n}\n"
+	if got := stderr.String(); got != want {
+		t.Fatalf("legacy root error wire changed\n got: %q\nwant: %q", got, want)
+	}
+}
+
+// TestRootHumanErrorToStderrOnly 是 B184 的人类可读分支断言：非 JSON 模式下，
+// 失败走 stderr（PrintHuman），stdout 为空。
+func TestRootHumanErrorToStderrOnly(t *testing.T) {
+	t.Parallel()
+
+	root := &cobra.Command{Use: "dws"}
+	root.PersistentFlags().String("format", "table", "")
+	_ = root.PersistentFlags().Set("format", "table")
+
+	var stdout, stderr bytes.Buffer
+	if err := printExecutionError(root, &stdout, &stderr, apperrors.NewInternal("boom")); err != nil {
+		t.Fatalf("printExecutionError() error = %v", err)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("failure must keep stdout empty, got %q", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "Error:") {
+		t.Fatalf("expected human error on stderr, got %q", stderr.String())
+	}
+}
+
+// TestRootExecuteOutcomeToExitCode 是 B185 的 Execute 出口断言：Execute 把
+// 命令返回的 error 类别映射为进程退出码（apperrors.ExitCode）。ok→0、
+// confirmation/validation→3、panic 与 unrepresentable partial error→5。
+func TestRootExecuteOutcomeToExitCode(t *testing.T) {
+	oldNormalize := rootNormalizeProcessProfileArgs
+	oldExecute := rootExecuteCommand
+	oldNewRoot := rootNewRootCommandWithEngine
+	oldPreParse := rootRunPreParse
+	oldStop := rootStopAllStdioClients
+	oldArgs := os.Args
+	t.Cleanup(func() {
+		rootNormalizeProcessProfileArgs = oldNormalize
+		rootExecuteCommand = oldExecute
+		rootNewRootCommandWithEngine = oldNewRoot
+		rootRunPreParse = oldPreParse
+		rootStopAllStdioClients = oldStop
+		os.Args = oldArgs
+	})
+	os.Args = []string{"dws"}
+	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
+	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
+	rootStopAllStdioClients = func() {}
+	rootNewRootCommandWithEngine = func(context.Context, *pipeline.Engine) *cobra.Command {
+		return &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+	}
+
+	// ok / pending（信封 success/pending 语义）→ 0
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) { return nil, nil }
+	if code := Execute(); code != 0 {
+		t.Fatalf("success Execute code = %d, want 0", code)
+	}
+
+	// An error cannot carry partial succeeded/failed data and fails closed.
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) {
+		return nil, &apperrors.Error{Category: apperrors.CategoryPartial, Message: "partial"}
+	}
+	if code := Execute(); code != 5 {
+		t.Fatalf("partial error Execute code = %d, want 5", code)
+	}
+
+	// confirmation_required（validation 子类）→ 3
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) {
+		return nil, apperrors.NewValidation("blocked", apperrors.WithReason("confirmation_required"))
+	}
+	if code := Execute(); code != 3 {
+		t.Fatalf("confirmation Execute code = %d, want 3", code)
+	}
+
+	// plain internal → 5
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) {
+		return nil, errors.New("plain")
+	}
+	if code := Execute(); code != 5 {
+		t.Fatalf("plain Execute code = %d, want 5", code)
+	}
+}
+
+// TestRootSilenceErrorsAndDeferTeardown 是 B186 的断言：根命令 SilenceErrors/
+// SilenceUsage 打开（Cobra 不自行打印），且 Execute 出口 defer 收尾路径
+// （StopAllStdioClients）在错误路径也被调用。
+func TestRootSilenceErrorsAndDeferTeardown(t *testing.T) {
+	oldNormalize := rootNormalizeProcessProfileArgs
+	oldExecute := rootExecuteCommand
+	oldNewRoot := rootNewRootCommandWithEngine
+	oldPreParse := rootRunPreParse
+	oldStop := rootStopAllStdioClients
+	oldArgs := os.Args
+	t.Cleanup(func() {
+		rootNormalizeProcessProfileArgs = oldNormalize
+		rootExecuteCommand = oldExecute
+		rootNewRootCommandWithEngine = oldNewRoot
+		rootRunPreParse = oldPreParse
+		rootStopAllStdioClients = oldStop
+		os.Args = oldArgs
+	})
+	os.Args = []string{"dws"}
+	rootNormalizeProcessProfileArgs = func() func() { return func() {} }
+	rootRunPreParse = func(*cobra.Command, *pipeline.Engine) error { return nil }
+	stopped := false
+	rootStopAllStdioClients = func() { stopped = true }
+	rootNewRootCommandWithEngine = func(context.Context, *pipeline.Engine) *cobra.Command {
+		return &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+	}
+
+	// 错误路径：Execute 返回非零，且 defer 收尾（StopAllStdioClients）被调用。
+	rootExecuteCommand = func(*cobra.Command) (*cobra.Command, error) {
+		return nil, apperrors.NewInternal("fail")
+	}
+	_ = Execute()
+	if !stopped {
+		t.Fatal("defer teardown (StopAllStdioClients) not called on error path")
+	}
+}
+
+// TestRootSilenceErrorsFlag 断言根命令的 SilenceErrors/SilenceUsage 为真，
+// 保证 Cobra 不自行在错误时打印 usage/错误（错误渲染统一走 printExecutionError）。
+func TestRootSilenceErrorsFlag(t *testing.T) {
+	t.Parallel()
+
+	root := NewRootCommand()
+	if !root.SilenceErrors || !root.SilenceUsage {
+		t.Fatalf("root must set SilenceErrors=%v SilenceUsage=%v", root.SilenceErrors, root.SilenceUsage)
+	}
+}
@@ -25,11 +25,32 @@ func TestRuntimeSchemaCompletenessCoversPublicCommandTree(t *testing.T) {
 	if !containsSchemaPath(report.Covered, "chat category create-smart") {
 		t.Fatal("chat category create-smart is not covered by runtime Schema")
 	}
+	for _, path := range missingChatCatalogCoveragePaths() {
+		if !containsSchemaPath(report.Covered, path) {
+			t.Fatalf("%s is not covered by runtime Schema", path)
+		}
+	}
 	if !containsSchemaPath(report.Excluded, "agoal strategy list") {
 		t.Fatal("agoal strategy list is not recorded as a reviewed exclusion")
 	}
 }

+func TestRuntimeSchemaCompletenessDoesNotExcludeMissingChatCatalogPaths(t *testing.T) {
+	exclusions, err := cli.ReviewedRuntimeSchemaExclusions()
+	if err != nil {
+		t.Fatal(err)
+	}
+	excluded := map[string]bool{}
+	for _, exclusion := range exclusions {
+		excluded[exclusion.CLIPath] = true
+	}
+	for _, path := range missingChatCatalogCoveragePaths() {
+		if excluded[path] {
+			t.Fatalf("%s must not remain in runtime Schema exclusions", path)
+		}
+	}
+}
+
 func containsSchemaPath(paths []string, want string) bool {
 	for _, path := range paths {
 		if path == want {
@@ -38,3 +59,38 @@ func containsSchemaPath(paths []string, want string) bool {
 	}
 	return false
 }
+
+func missingChatCatalogCoveragePaths() []string {
+	return []string{
+		"chat category add-conv",
+		"chat category create",
+		"chat category delete",
+		"chat category remove-conv",
+		"chat category rename",
+		"chat chmod",
+		"chat clear-all-red-point",
+		"chat clear-messages",
+		"chat clear-red-point",
+		"chat data-auth cross-org",
+		"chat group audit-join-validation",
+		"chat group list-all",
+		"chat group list-join-validations",
+		"chat group members list-by-ids",
+		"chat group notice create",
+		"chat group notice edit",
+		"chat group notice get",
+		"chat group notice list",
+		"chat group share-invite",
+		"chat group update-alias",
+		"chat hide",
+		"chat list-all-conversations",
+		"chat mark-read",
+		"chat mark-unread",
+		"chat message list-emotion-replies",
+		"chat message set-top-msg",
+		"chat message unset-top-msg",
+		"chat mute-at-all",
+		"chat mute-red-envelope",
+		"chat text translate",
+	}
+}
@@ -16,12 +16,12 @@ import (
 )

 const (
-	publicShortcutCount = 357
+	publicShortcutCount = 399
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
-	// including hidden leaves such as minutes.shortcut_minutes_search.
-	schemaPublishedShortcutCount = 358
+	// including the hidden historical minutes.shortcut_minutes_search contract.
+	schemaPublishedShortcutCount = 401
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 357
+	publiclyDeliveredShortcutCount = 399
 )

 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -114,12 +114,14 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)

 	product := executeShortcutSchemaQuery(t, "chat")
 	productPayload, _ := product["product"].(map[string]any)
-	if got, want := int(product["count"].(float64)), 187; got != want {
+	if got, want := int(product["count"].(float64)), 217; got != want {
 		t.Fatalf("schema chat count = %d, want %d", got, want)
 	}
 	summaries := schemaContractObjectSlice(productPayload["tools"])
 	shortcutCount := 0
+	summaryByCLIPath := make(map[string]map[string]any, len(summaries))
 	for _, summary := range summaries {
+		summaryByCLIPath[schemaContractString(summary["cli_path"])] = summary
 		if strings.HasPrefix(schemaContractString(summary["canonical_path"]), "chat.shortcut_") {
 			shortcutCount++
 		}
@@ -127,6 +129,135 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 	if shortcutCount != 98 {
 		t.Fatalf("schema chat shortcut summaries = %d, want 98", shortcutCount)
 	}
+	for _, cliPath := range missingChatCatalogCoveragePaths() {
+		if summaryByCLIPath[cliPath] == nil {
+			t.Fatalf("schema chat missing expected catalog tool %q", cliPath)
+		}
+	}
+	assertSchemaSummarySafety(t, summaryByCLIPath, "chat clear-messages", "destructive", "high", "user_required")
+	assertSchemaSummarySafety(t, summaryByCLIPath, "chat data-auth cross-org", "write", "high", "user_required")
+	assertSchemaSummarySafety(t, summaryByCLIPath, "chat group share-invite", "write", "medium", "user_required")
+	assertChatCatalogCompleteLeafContracts(t)
+}
+
+func assertSchemaSummarySafety(
+	t testing.TB,
+	summaries map[string]map[string]any,
+	cliPath string,
+	effect string,
+	risk string,
+	confirmation string,
+) {
+	t.Helper()
+	summary := summaries[cliPath]
+	if summary == nil {
+		t.Fatalf("schema chat missing expected catalog tool %q", cliPath)
+	}
+	if got := schemaContractString(summary["effect"]); got != effect {
+		t.Fatalf("%s effect = %q, want %q", cliPath, got, effect)
+	}
+	if got := schemaContractString(summary["risk"]); got != risk {
+		t.Fatalf("%s risk = %q, want %q", cliPath, got, risk)
+	}
+	if got := schemaContractString(summary["confirmation"]); got != confirmation {
+		t.Fatalf("%s confirmation = %q, want %q", cliPath, got, confirmation)
+	}
+}
+
+func assertChatCatalogCompleteLeafContracts(t testing.TB) {
+	t.Helper()
+	for _, cliPath := range []string{
+		"chat clear-messages",
+		"chat clear-red-point",
+		"chat hide",
+		"chat mark-read",
+		"chat mark-unread",
+		"chat mute-at-all",
+		"chat mute-red-envelope",
+	} {
+		leaf := executeShortcutSchemaQuery(t, "--cli-path", cliPath)
+		assertSchemaLeafParameterRequired(t, leaf, cliPath, "conversation-id", false)
+		assertSchemaLeafConstraints(t, leaf, cliPath, map[string]any{
+			"require_one_of":     [][]string{{"conversation-id", "id", "chat"}},
+			"mutually_exclusive": [][]string{{"conversation-id", "id", "chat"}},
+		})
+	}
+
+	markRead := executeShortcutSchemaQuery(t, "--cli-path", "chat mark-read")
+	assertSchemaLeafParameterRequired(t, markRead, "chat mark-read", "message-id", true)
+
+	chmod := executeShortcutSchemaQuery(t, "--cli-path", "chat chmod")
+	assertSchemaLeafConstraints(t, chmod, "chat chmod", map[string]any{
+		"require_one_of":     [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}},
+		"mutually_exclusive": [][]string{{"conversation-id", "open-dingtalk-id", "user"}},
+	})
+	assertChatGrantParameterFacts(t, chmod, "chat chmod")
+
+	crossOrg := executeShortcutSchemaQuery(t, "--cli-path", "chat data-auth cross-org")
+	assertSchemaLeafConstraints(t, crossOrg, "chat data-auth cross-org", map[string]any{
+		"require_one_of":     [][]string{{"target-org-id", "all"}},
+		"mutually_exclusive": [][]string{{"target-org-id", "all"}},
+	})
+	assertChatGrantParameterFacts(t, crossOrg, "chat data-auth cross-org")
+
+	shareInvite := executeShortcutSchemaQuery(t, "--cli-path", "chat group share-invite")
+	assertSchemaLeafConstraints(t, shareInvite, "chat group share-invite", map[string]any{
+		"require_one_of":     [][]string{{"target", "receiver"}},
+		"mutually_exclusive": [][]string{{"target", "receiver"}},
+	})
+
+	auditJoin := executeShortcutSchemaQuery(t, "--cli-path", "chat group audit-join-validation")
+	assertSchemaLeafParameterEnum(t, auditJoin, "chat group audit-join-validation", "status", []string{"AuditApprove", "AuditDelete"})
+}
+
+func assertSchemaLeafParameterRequired(t testing.TB, leaf map[string]any, cliPath, name string, want bool) {
+	t.Helper()
+	parameters := schemaContractMap(leaf["parameters"])
+	parameter := parameters[name]
+	if parameter == nil {
+		t.Fatalf("%s missing --%s parameter: %#v", cliPath, name, parameters)
+	}
+	if got, _ := parameter["required"].(bool); got != want {
+		t.Fatalf("%s --%s required = %#v, want %v", cliPath, name, parameter["required"], want)
+	}
+}
+
+func assertSchemaLeafParameterEnum(t testing.TB, leaf map[string]any, cliPath, name string, want []string) {
+	t.Helper()
+	parameters := schemaContractMap(leaf["parameters"])
+	parameter := parameters[name]
+	if parameter == nil {
+		t.Fatalf("%s missing --%s parameter: %#v", cliPath, name, parameters)
+	}
+	if got := schemaContractStringSlice(parameter["enum"]); !schemaContractJSONEqual(got, want) {
+		t.Fatalf("%s --%s enum = %#v, want %#v", cliPath, name, got, want)
+	}
+}
+
+func assertSchemaLeafConstraints(t testing.TB, leaf map[string]any, cliPath string, want map[string]any) {
+	t.Helper()
+	if got := leaf["constraints"]; !schemaContractJSONEqual(got, want) {
+		t.Fatalf("%s constraints = %#v, want %#v", cliPath, got, want)
+	}
+}
+
+func assertChatGrantParameterFacts(t testing.TB, leaf map[string]any, cliPath string) {
+	t.Helper()
+	parameters := schemaContractMap(leaf["parameters"])
+	grantType := parameters["grant-type"]
+	if grantType == nil {
+		t.Fatalf("%s missing --grant-type parameter: %#v", cliPath, parameters)
+	}
+	wantEnum := []string{"once", "session", "timed", "permanent"}
+	if got := schemaContractStringSlice(grantType["enum"]); !schemaContractJSONEqual(got, wantEnum) {
+		t.Fatalf("%s --grant-type enum = %#v, want %#v", cliPath, got, wantEnum)
+	}
+	if got := schemaContractString(parameters["session-id"]["required_when"]); got != "grant-type is session" {
+		t.Fatalf("%s --session-id required_when = %q, want grant-type is session", cliPath, got)
+	}
+	if got := schemaContractString(parameters["ttl"]["required_when"]); got != "grant-type is timed" {
+		t.Fatalf("%s --ttl required_when = %q, want grant-type is timed", cliPath, got)
+	}
 }

 func TestDeliveryDocUpdateShortcutPublishesCompleteConditionalContract(t *testing.T) {
@@ -0,0 +1,137 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"sync"
+	"syscall"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+)
+
+var rootEscalateSignal = func(sig os.Signal) {
+	signal.Reset(sig)
+	redeliverProcessSignal(sig)
+}
+
+var (
+	rootFindProcess = os.FindProcess
+	rootExitProcess = os.Exit
+)
+
+// redeliverProcessSignal asks the current process to handle the second signal
+// with the platform's default semantics. Platforms that cannot deliver the
+// requested signal through os.Process.Signal fall back to the conventional
+// CLI exit status instead of leaving the process running after escalation.
+func redeliverProcessSignal(sig os.Signal) {
+	process, err := rootFindProcess(os.Getpid())
+	if err == nil {
+		err = process.Signal(sig)
+	}
+	if err != nil {
+		rootExitProcess(interruptionExitCode(sig))
+	}
+}
+
+func interruptionExitCode(sig os.Signal) int {
+	if sig == syscall.SIGTERM {
+		return 143
+	}
+	return 130
+}
+
+type processInterruption struct {
+	signal os.Signal
+}
+
+func (e *processInterruption) Error() string {
+	return fmt.Sprintf("process interrupted by %s", e.signal)
+}
+
+func (e *processInterruption) Unwrap() error { return context.Canceled }
+
+func (e *processInterruption) ExitCode() int {
+	return interruptionExitCode(e.signal)
+}
+
+func (e *processInterruption) Subtype() string {
+	if e.signal == syscall.SIGTERM {
+		return "terminated"
+	}
+	return "cancelled_by_user"
+}
+
+type processSignalState struct {
+	mu                       sync.Mutex
+	interruption             *processInterruption
+	primaryCompletedAtSignal bool
+}
+
+func (s *processSignalState) record(sig os.Signal, store *output.ResultStore) (first bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.interruption != nil {
+		return false
+	}
+	_, _, s.primaryCompletedAtSignal, _ = output.StoredEmissionState(store)
+	s.interruption = &processInterruption{signal: sig}
+	return true
+}
+
+func (s *processSignalState) outcome() (*processInterruption, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.interruption, s.primaryCompletedAtSignal
+}
+
+func installProcessSignalContext(parent context.Context, store *output.ResultStore) (context.Context, *processSignalState, func()) {
+	signals := make(chan os.Signal, 2)
+	signal.Notify(signals, os.Interrupt, syscall.SIGTERM)
+	return manageProcessSignals(parent, store, signals, func() { signal.Stop(signals) }, rootEscalateSignal)
+}
+
+func manageProcessSignals(
+	parent context.Context,
+	store *output.ResultStore,
+	signals <-chan os.Signal,
+	stopNotify func(),
+	escalate func(os.Signal),
+) (context.Context, *processSignalState, func()) {
+	ctx, cancel := context.WithCancelCause(parent)
+	state := &processSignalState{}
+	done := make(chan struct{})
+	stopped := make(chan struct{})
+	var stopOnce sync.Once
+
+	go func() {
+		defer close(stopped)
+		for {
+			select {
+			case sig := <-signals:
+				if sig == nil {
+					continue
+				}
+				if state.record(sig, store) {
+					cancel(state.interruption)
+					continue
+				}
+				escalate(sig)
+				return
+			case <-done:
+				return
+			}
+		}
+	}()
+
+	stop := func() {
+		stopOnce.Do(func() {
+			stopNotify()
+			close(done)
+			<-stopped
+			cancel(context.Canceled)
+		})
+	}
+	return ctx, state, stop
+}
@@ -0,0 +1,336 @@
+package app
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func signalSelf(t *testing.T, sig syscall.Signal) {
+	t.Helper()
+	process, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatalf("find current process: %v", err)
+	}
+	if err := process.Signal(sig); err != nil {
+		t.Skipf("current platform does not support process signal delivery: %v", err)
+	}
+}
+
+func TestFrameworkSignalRedeliveryFallbackAndInterruptionMethods(t *testing.T) {
+	originalFind, originalExit := rootFindProcess, rootExitProcess
+	t.Cleanup(func() { rootFindProcess, rootExitProcess = originalFind, originalExit })
+	rootFindProcess = func(int) (*os.Process, error) { return nil, errors.New("find failed") }
+	exitCode := 0
+	rootExitProcess = func(code int) { exitCode = code }
+	rootEscalateSignal(syscall.SIGTERM)
+	if exitCode != 143 {
+		t.Fatalf("escalation exit=%d", exitCode)
+	}
+	exitCode = 0
+	redeliverProcessSignal(syscall.SIGTERM)
+	if exitCode != 143 {
+		t.Fatalf("fallback exit=%d", exitCode)
+	}
+	rootFindProcess = func(int) (*os.Process, error) { return os.FindProcess(99999999) }
+	exitCode = 0
+	redeliverProcessSignal(syscall.SIGINT)
+	if exitCode != 130 {
+		t.Fatalf("signal fallback exit=%d", exitCode)
+	}
+	interrupted := &processInterruption{signal: syscall.SIGINT}
+	if !errors.Is(interrupted, context.Canceled) || interrupted.ExitCode() != 130 || interrupted.Subtype() != "cancelled_by_user" || !strings.Contains(interrupted.Error(), "interrupt") {
+		t.Fatalf("interruption=%v", interrupted)
+	}
+	terminated := &processInterruption{signal: syscall.SIGTERM}
+	if terminated.ExitCode() != 143 || terminated.Subtype() != "terminated" {
+		t.Fatalf("termination=%v", terminated)
+	}
+	state := &processSignalState{}
+	if !state.record(syscall.SIGINT, nil) || state.record(syscall.SIGTERM, nil) {
+		t.Fatal("signal state did not reject a second interruption")
+	}
+}
+
+func TestFrameworkManageProcessSignalsNilAndEscalation(t *testing.T) {
+	signals := make(chan os.Signal, 3)
+	stopped, escalated := false, make(chan os.Signal, 1)
+	ctx, _, stop := manageProcessSignals(context.Background(), nil, signals, func() { stopped = true }, func(sig os.Signal) { escalated <- sig })
+	signals <- nil
+	signals <- syscall.SIGINT
+	<-ctx.Done()
+	signals <- syscall.SIGTERM
+	if got := <-escalated; got != syscall.SIGTERM {
+		t.Fatalf("escalated=%v", got)
+	}
+	stop()
+	stop()
+	if !stopped {
+		t.Fatal("signal notification was not stopped")
+	}
+}
+
+func installSignalExecuteSeams(t *testing.T, unified bool, stdout, stderr io.Writer) {
+	t.Helper()
+	testseam.Protect(t, &os.Args)
+	os.Args = []string{"dws"}
+	testseam.Swap(t, &rootNormalizeProcessProfileArgs, func() func() { return func() {} })
+	testseam.Swap(t, &rootRunPreParse, func(*cobra.Command, *pipeline.Engine) error { return nil })
+	testseam.Swap(t, &rootStopAllStdioClients, func() {})
+	testseam.Swap(t, &rootNewRootCommandWithEngine, func(ctx context.Context, _ *pipeline.Engine) *cobra.Command {
+		cmd := &cobra.Command{Use: "dws", SilenceErrors: true, SilenceUsage: true}
+		if unified {
+			output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
+		}
+		cmd.SetContext(ctx)
+		cmd.SetOut(stdout)
+		cmd.SetErr(stderr)
+		return cmd
+	})
+}
+
+func TestExecuteSignalEmitsOneTypedUnifiedFailure(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		signal  syscall.Signal
+		code    int
+		subtype string
+	}{
+		{name: "SIGINT", signal: syscall.SIGINT, code: 130, subtype: "cancelled_by_user"},
+		{name: "SIGTERM", signal: syscall.SIGTERM, code: 143, subtype: "terminated"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			installSignalExecuteSeams(t, true, &stdout, &stderr)
+			testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+				signalSelf(t, tc.signal)
+				<-cmd.Context().Done()
+				return cmd, cmd.Context().Err()
+			})
+
+			if code := Execute(); code != tc.code {
+				t.Fatalf("Execute code=%d, want %d", code, tc.code)
+			}
+			var env output.Envelope
+			if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+				t.Fatalf("decode envelope: %v; output=%q", err, stdout.String())
+			}
+			if env.Error == nil || env.Error.Type != "internal" || env.Error.Subtype != tc.subtype || env.Error.ExitCode != tc.code {
+				t.Fatalf("error=%+v, want internal/%s exit %d", env.Error, tc.subtype, tc.code)
+			}
+			if bytes.Count(stdout.Bytes(), []byte(`"outcome": "failure"`)) != 1 {
+				t.Fatalf("stdout must contain one failure envelope: %s", stdout.String())
+			}
+		})
+	}
+}
+
+func TestExecuteSignalLegacyExitCodes(t *testing.T) {
+	for _, tc := range []struct {
+		signal syscall.Signal
+		code   int
+	}{{syscall.SIGINT, 130}, {syscall.SIGTERM, 143}} {
+		t.Run(tc.signal.String(), func(t *testing.T) {
+			installSignalExecuteSeams(t, false, io.Discard, io.Discard)
+			testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+				signalSelf(t, tc.signal)
+				<-cmd.Context().Done()
+				return cmd, cmd.Context().Err()
+			})
+			if code := Execute(); code != tc.code {
+				t.Fatalf("Execute code=%d, want %d", code, tc.code)
+			}
+		})
+	}
+}
+
+func TestExecuteDeadlineIsNotSignalCancellation(t *testing.T) {
+	var stdout bytes.Buffer
+	installSignalExecuteSeams(t, true, &stdout, io.Discard)
+	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+		return cmd, context.DeadlineExceeded
+	})
+	if code := Execute(); code != 5 {
+		t.Fatalf("Execute code=%d, want internal deadline code 5", code)
+	}
+	var env output.Envelope
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatal(err)
+	}
+	if env.Error == nil || env.Error.Subtype != "deadline_exceeded" || env.Error.ExitCode == 130 || env.Error.ExitCode == 143 {
+		t.Fatalf("deadline error=%+v", env.Error)
+	}
+}
+
+func TestSignalAfterFailedEmissionAttemptPreservesPublicationExitCode(t *testing.T) {
+	var stdout bytes.Buffer
+	installSignalExecuteSeams(t, true, &stdout, io.Discard)
+	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+		cmd.SetOut(failingWriter{})
+		if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+			t.Fatal(err)
+		}
+		_, _, _ = output.EmitStoredResult(cmd)
+		signalSelf(t, syscall.SIGINT)
+		<-cmd.Context().Done()
+		return cmd, cmd.Context().Err()
+	})
+	if code := Execute(); code != 5 {
+		t.Fatalf("Execute code=%d, want publication failure code 5", code)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("second envelope emitted: %q", stdout.String())
+	}
+}
+
+func TestSignalBeforeEmissionAttemptPreservesPublishedOutcome(t *testing.T) {
+	var stdout bytes.Buffer
+	installSignalExecuteSeams(t, true, &stdout, io.Discard)
+	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+		// Record cancellation before publication begins, then simulate a command
+		// hook that has already committed its result and completes publication.
+		// The wire result must remain authoritative over the earlier signal.
+		signalSelf(t, syscall.SIGINT)
+		<-cmd.Context().Done()
+		if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+			t.Fatal(err)
+		}
+		if _, _, err := output.EmitStoredResult(cmd); err != nil {
+			t.Fatal(err)
+		}
+		return cmd, cmd.Context().Err()
+	})
+	if code := Execute(); code != 0 {
+		t.Fatalf("Execute code=%d, want published success code 0", code)
+	}
+	var env output.Envelope
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode envelope: %v; output=%q", err, stdout.String())
+	}
+	if !env.OK || env.Outcome != output.OutcomeSuccess {
+		t.Fatalf("published envelope=%+v, want successful outcome", env)
+	}
+	if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "success"`)); got != 1 {
+		t.Fatalf("stdout contains %d success envelopes, want one: %s", got, stdout.String())
+	}
+}
+
+func TestSignalAfterCompletedPrimaryPreservesEstablishedOutcome(t *testing.T) {
+	var stdout bytes.Buffer
+	installSignalExecuteSeams(t, true, &stdout, io.Discard)
+	testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+		if err := output.StoreResult(cmd.Context(), output.Success(map[string]any{"ok": true})); err != nil {
+			t.Fatal(err)
+		}
+		if _, _, err := output.EmitStoredResult(cmd); err != nil {
+			t.Fatal(err)
+		}
+		signalSelf(t, syscall.SIGINT)
+		<-cmd.Context().Done()
+		return cmd, cmd.Context().Err()
+	})
+	if code := Execute(); code != 0 {
+		t.Fatalf("Execute code=%d, want established success code 0", code)
+	}
+	if got := bytes.Count(stdout.Bytes(), []byte(`"outcome": "success"`)); got != 1 {
+		t.Fatalf("stdout contains %d success envelopes, want one: %s", got, stdout.String())
+	}
+}
+
+func TestExecuteSignalSubprocessExitStatus(t *testing.T) {
+	if os.Getenv("DWS_SIGNAL_HELPER") == "1" {
+		installSignalExecuteSeams(t, true, os.Stdout, os.Stderr)
+		testseam.Swap(t, &rootExecuteCommand, func(cmd *cobra.Command) (*cobra.Command, error) {
+			_, _ = fmt.Fprintln(os.Stderr, "READY")
+			<-cmd.Context().Done()
+			return cmd, cmd.Context().Err()
+		})
+		os.Exit(Execute())
+	}
+
+	for _, tc := range []struct {
+		name    string
+		signal  syscall.Signal
+		code    int
+		subtype string
+	}{
+		{name: "SIGINT", signal: syscall.SIGINT, code: 130, subtype: "cancelled_by_user"},
+		{name: "SIGTERM", signal: syscall.SIGTERM, code: 143, subtype: "terminated"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := exec.Command(os.Args[0], "-test.run=^TestExecuteSignalSubprocessExitStatus$")
+			cmd.Env = append(os.Environ(), "DWS_SIGNAL_HELPER=1")
+			stdout, err := cmd.StdoutPipe()
+			if err != nil {
+				t.Fatal(err)
+			}
+			stderr, err := cmd.StderrPipe()
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := cmd.Start(); err != nil {
+				t.Fatal(err)
+			}
+			if scanner := bufio.NewScanner(stderr); !scanner.Scan() || scanner.Text() != "READY" {
+				t.Fatalf("helper readiness failed: %q, err=%v", scanner.Text(), scanner.Err())
+			}
+			if err := cmd.Process.Signal(tc.signal); err != nil {
+				_ = cmd.Process.Kill()
+				_ = cmd.Wait()
+				t.Skipf("current platform does not support subprocess signal delivery: %v", err)
+			}
+			payload, readErr := io.ReadAll(stdout)
+			if readErr != nil {
+				t.Fatal(readErr)
+			}
+			waitErr := cmd.Wait()
+			var exitErr *exec.ExitError
+			if !errors.As(waitErr, &exitErr) || exitErr.ExitCode() != tc.code {
+				t.Fatalf("wait error=%v, want exit %d", waitErr, tc.code)
+			}
+			var env output.Envelope
+			if err := json.Unmarshal(payload, &env); err != nil {
+				t.Fatalf("decode helper output: %v; output=%q", err, payload)
+			}
+			if env.Error == nil || env.Error.Subtype != tc.subtype || env.Error.ExitCode != tc.code {
+				t.Fatalf("helper error=%+v", env.Error)
+			}
+		})
+	}
+}
+
+func TestSecondSignalUsesEscalationSeam(t *testing.T) {
+	signals := make(chan os.Signal, 2)
+	escalated := make(chan os.Signal, 1)
+	ctx, _, stop := manageProcessSignals(context.Background(), nil, signals, func() {}, func(sig os.Signal) {
+		escalated <- sig
+	})
+	signals <- syscall.SIGINT
+	<-ctx.Done()
+	if !errors.Is(context.Cause(ctx), context.Canceled) {
+		t.Fatalf("cause=%v, want cancellation", context.Cause(ctx))
+	}
+	signals <- syscall.SIGTERM
+	if got := <-escalated; got != syscall.SIGTERM {
+		t.Fatalf("escalated %v, want SIGTERM", got)
+	}
+	stop()
+}
+
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") }
@@ -0,0 +1,707 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillprovenance"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func useManagedSkillNames(t *testing.T, names ...string) {
+	t.Helper()
+	records := make([]skillprovenance.Record, 0, len(names))
+	for _, name := range names {
+		records = append(records, skillprovenance.Record{Name: name})
+	}
+	testseam.Swap(t, &skillSetupReadState, func(string) (*skillstate.State, bool, error) {
+		return &skillstate.State{ManagedSkills: records}, true, nil
+	})
+}
+
+// TestCrossPlatformCoverageSkillSetupConfirmPreviewsStaleSkills verifies the
+// confirmation prompt lists stale dingtalk-* / dws-shared directories that a
+// full (unfiltered) multi install will back up and remove, and that a
+// filtered install previews nothing extra.
+func TestCrossPlatformCoverageSkillSetupConfirmPreviewsStaleSkills(t *testing.T) {
+	testseam.Swap(t, &skillSetupInteractive, func() bool { return false })
+
+	dest := filepath.Join(t.TempDir(), ".claude", "skills")
+	stale := filepath.Join(dest, "dingtalk-old")
+	if err := os.MkdirAll(stale, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(stale, "SKILL.md"), []byte("stale"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	useManagedSkillNames(t, "dingtalk-old")
+
+	var out bytes.Buffer
+	ok, err := confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{dest}, []string{"dingtalk-chat"}, false)
+	if err == nil || ok || !strings.Contains(err.Error(), "--yes") {
+		t.Fatalf("confirmSkillSetup = (%v, %v), want non-interactive confirmation error", ok, err)
+	}
+	if !strings.Contains(out.String(), "将备份并移除过期 skill") {
+		t.Fatalf("full install preview must list stale skills, got %q", out.String())
+	}
+	if !strings.Contains(out.String(), filepath.Join(dest, "dingtalk-old")) {
+		t.Fatalf("preview must name the stale directory, got %q", out.String())
+	}
+
+	out.Reset()
+	ok, err = confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{dest}, []string{"dingtalk-chat"}, true)
+	if err == nil || ok {
+		t.Fatalf("filtered confirmSkillSetup = (%v, %v), want non-interactive confirmation error", ok, err)
+	}
+	if strings.Contains(out.String(), "将备份并移除过期 skill") {
+		t.Fatalf("filtered install must stay additive in the preview, got %q", out.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupUnifiedOwnership(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "dingtalk-custom")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if isManagedDWSMultiSkillDir(dir) {
+		t.Fatal("an unregistered dingtalk-* directory must not be treated as DWS-owned")
+	}
+	managed := map[string]bool{"dingtalk-custom": true}
+	if !isManagedDWSMultiSkillDir(dir, managed) {
+		t.Fatal("unified metadata must prove ownership")
+	}
+	legacy := filepath.Join(t.TempDir(), legacySharedSkill)
+	if !isManagedDWSMultiSkillDir(legacy) {
+		t.Fatal("the exact legacy dws-shared name must remain managed")
+	}
+
+}
+
+func TestCrossPlatformCoveragePublishManagedSkillFailurePaths(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{"dingtalk-a"})
+	skillSrc := filepath.Join(src, "dingtalk-a")
+	failure := errors.New("publish denied")
+
+	t.Run("mkdir", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupPublishTemp, func(string, string) (string, error) { return "", failure })
+		err := publishDWSManagedSkillDir(skillSrc, filepath.Join(t.TempDir(), "dingtalk-a"))
+		if !errors.Is(err, failure) || !strings.Contains(err.Error(), "staging") {
+			t.Fatalf("mkdir error = %v", err)
+		}
+	})
+
+	t.Run("copy", func(t *testing.T) {
+		parent := t.TempDir()
+		testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { return failure })
+		err := publishDWSManagedSkillDir(skillSrc, filepath.Join(parent, "dingtalk-a"))
+		if !errors.Is(err, failure) {
+			t.Fatalf("copy error = %v", err)
+		}
+		if entries, readErr := os.ReadDir(parent); readErr != nil || len(entries) != 0 {
+			t.Fatalf("copy failure retained staging: %v, err=%v", entries, readErr)
+		}
+	})
+
+	t.Run("rename", func(t *testing.T) {
+		parent := t.TempDir()
+		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return failure })
+		err := publishDWSManagedSkillDir(skillSrc, filepath.Join(parent, "dingtalk-a"))
+		if !errors.Is(err, failure) || !strings.Contains(err.Error(), "发布 Skill") {
+			t.Fatalf("rename error = %v", err)
+		}
+		if entries, readErr := os.ReadDir(parent); readErr != nil || len(entries) != 0 {
+			t.Fatalf("rename failure retained staging: %v, err=%v", entries, readErr)
+		}
+	})
+
+	t.Run("cleanup", func(t *testing.T) {
+		renameErr := errors.New("rename denied")
+		cleanupErr := errors.New("cleanup denied")
+		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return renameErr })
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupErr })
+		err := publishDWSManagedSkillDir(skillSrc, filepath.Join(t.TempDir(), "dingtalk-a"))
+		if !errors.Is(err, renameErr) || !errors.Is(err, cleanupErr) {
+			t.Fatalf("cleanup error = %v", err)
+		}
+	})
+}
+
+// TestCrossPlatformCoverageSkillSetupCleanupHomeFailure verifies that
+// cleanupMutualExclusion keeps every victim in place with a warning when
+// $HOME cannot be resolved, instead of destroying anything.
+func TestCrossPlatformCoverageSkillSetupCleanupHomeFailure(t *testing.T) {
+	dest := filepath.Join(t.TempDir(), ".agents", "skills")
+	victim := filepath.Join(dest, "dws")
+	if err := os.MkdirAll(victim, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(victim, "SKILL.md"), []byte("mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	homeErr := errors.New("home boom")
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", homeErr })
+
+	var out, errOut bytes.Buffer
+	cleanupMutualExclusion(dest, skillSetupModeMulti, &out, &errOut)
+	if !strings.Contains(errOut.String(), "无法解析 HOME，跳过删除") {
+		t.Fatalf("expected HOME warning on errOut, got %q", errOut.String())
+	}
+	if _, err := os.Stat(filepath.Join(victim, "SKILL.md")); err != nil {
+		t.Fatalf("victim must survive the HOME failure: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupBackupFailureSkipsWholeTarget(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	copyCalls := 0
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error {
+		copyCalls++
+		return nil
+	})
+	failure := errors.New("backup boom")
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, dir string) (string, error) {
+		if filepath.Base(dir) == "dws" {
+			return "", failure
+		}
+		return "", nil
+	})
+
+	dest := filepath.Join(home, ".agents", "skills")
+	if err := os.MkdirAll(filepath.Join(dest, "dws"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	src := writeMultiSkillSource(t, []string{"dingtalk-a", "dingtalk-shared"})
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installMultiSkillToHomes(src, []string{"dingtalk-a", "dingtalk-shared"}, []string{dest}, &out, &errOut, false)
+	if err != nil || installed != 0 || skipped != 2 {
+		t.Fatalf("install = (%d, %d, %v), want (0, 2, nil)", installed, skipped, err)
+	}
+	if copyCalls != 2 {
+		t.Fatalf("backup failure staged %d new Skills, want 2", copyCalls)
+	}
+	if !strings.Contains(errOut.String(), "跳过整个 Agent 目标") {
+		t.Fatalf("missing whole-target warning: %q", errOut.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupCleanupMutualExclusionBackupFailure(t *testing.T) {
+	home := t.TempDir()
+	dest := filepath.Join(home, ".agents", "skills")
+	victim := filepath.Join(dest, "dws")
+	if err := os.MkdirAll(victim, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	failure := errors.New("backup boom")
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, dir string) (string, error) {
+		if dir != victim {
+			t.Fatalf("backup victim = %q, want %q", dir, victim)
+		}
+		return "", failure
+	})
+
+	var out, errOut bytes.Buffer
+	err := cleanupMutualExclusion(dest, skillSetupModeMulti, &out, &errOut)
+	if !errors.Is(err, failure) {
+		t.Fatalf("cleanup error = %v, want %v", err, failure)
+	}
+	if out.Len() != 0 || !strings.Contains(errOut.String(), "互斥清理失败") {
+		t.Fatalf("cleanup output = %q / %q", out.String(), errOut.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupMonoCleanupFailureSkipsWholeTarget(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	copyCalls := 0
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error {
+		copyCalls++
+		return nil
+	})
+	failure := errors.New("multi backup boom")
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, dir string) (string, error) {
+		if filepath.Base(dir) == "dingtalk-a" {
+			return "", failure
+		}
+		return "", nil
+	})
+
+	base := filepath.Join(home, ".agents", "skills")
+	multi := filepath.Join(base, "dingtalk-a")
+	if err := os.MkdirAll(multi, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	useManagedSkillNames(t, filepath.Base(multi))
+	monoSrc := t.TempDir()
+	if err := os.WriteFile(filepath.Join(monoSrc, "SKILL.md"), []byte("mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installSkillToHomes(monoSrc, []string{filepath.Join(base, "dws")}, &out, &errOut)
+	if err != nil || installed != 0 || skipped != 1 {
+		t.Fatalf("install = (%d, %d, %v), want (0, 1, nil)", installed, skipped, err)
+	}
+	if copyCalls != 1 {
+		t.Fatalf("multi cleanup failure staged mono %d times, want 1", copyCalls)
+	}
+	if _, err := os.Stat(multi); err != nil {
+		t.Fatalf("multi leftover must survive backup failure: %v", err)
+	}
+	if !strings.Contains(errOut.String(), "Skill 备份失败，已执行回滚，跳过整个 Agent 目标") {
+		t.Fatalf("missing mono whole-target warning: %q", errOut.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupStaleBackupFailureSkipsWholeTarget(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	copyCalls := 0
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error {
+		copyCalls++
+		return nil
+	})
+	failure := errors.New("stale backup boom")
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, dir string) (string, error) {
+		if filepath.Base(dir) == "dingtalk-stale" {
+			return "", failure
+		}
+		return "", nil
+	})
+
+	dest := filepath.Join(home, ".agents", "skills")
+	stale := filepath.Join(dest, "dingtalk-stale")
+	if err := os.MkdirAll(stale, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	useManagedSkillNames(t, filepath.Base(stale))
+	src := writeMultiSkillSource(t, []string{"dingtalk-a", "dingtalk-shared"})
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installMultiSkillToHomes(src, []string{"dingtalk-a", "dingtalk-shared"}, []string{dest}, &out, &errOut, false)
+	if err != nil || installed != 0 || skipped != 2 {
+		t.Fatalf("install = (%d, %d, %v), want (0, 2, nil)", installed, skipped, err)
+	}
+	if copyCalls != 2 {
+		t.Fatalf("stale backup failure staged %d new Skills, want 2", copyCalls)
+	}
+	if !strings.Contains(errOut.String(), "Skill 备份失败，已执行回滚，跳过整个 Agent 目标") {
+		t.Fatalf("missing stale whole-target warning: %q", errOut.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupTransactionFailuresRestoreOldSet(t *testing.T) {
+	for _, failureKind := range []string{"later_backup", "later_publish"} {
+		failureKind := failureKind
+		t.Run(failureKind, func(t *testing.T) {
+			home := t.TempDir()
+			dest := filepath.Join(home, ".agents", "skills")
+			first := filepath.Join(dest, "dingtalk-first")
+			second := filepath.Join(dest, "dingtalk-second")
+			for path, body := range map[string]string{
+				filepath.Join(first, "SKILL.md"):  "old first\n",
+				filepath.Join(second, "SKILL.md"): "old second\n",
+			} {
+				if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			src := writeMultiSkillSource(t, []string{"dingtalk-first", "dingtalk-second"})
+			if err := os.WriteFile(filepath.Join(src, "dingtalk-first", "SKILL.md"), []byte("new first\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(filepath.Join(src, "dingtalk-second", "SKILL.md"), []byte("new second\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+
+			testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+			failure := errors.New("injected " + failureKind + " failure")
+			if failureKind == "later_backup" {
+				originalBackup := skillSetupBackupAndRemove
+				testseam.Swap(t, &skillSetupBackupAndRemove, func(homeDir, dir string) (string, error) {
+					if dir == second {
+						return "", failure
+					}
+					return originalBackup(homeDir, dir)
+				})
+			} else {
+				originalRename := skillSetupPublishRename
+				testseam.Swap(t, &skillSetupPublishRename, func(oldPath, newPath string) error {
+					if newPath == second && strings.HasPrefix(filepath.Base(filepath.Dir(oldPath)), ".dws-setup-set-") {
+						return failure
+					}
+					return originalRename(oldPath, newPath)
+				})
+			}
+
+			var out, errOut bytes.Buffer
+			installed, skipped, err := installMultiSkillToHomes(
+				src,
+				[]string{"dingtalk-first", "dingtalk-second"},
+				[]string{dest},
+				&out,
+				&errOut,
+				true,
+			)
+			if err != nil || installed != 0 || skipped != 2 {
+				t.Fatalf("transaction failure = (%d, %d, %v), stderr=%s", installed, skipped, err, errOut.String())
+			}
+			for path, want := range map[string]string{
+				filepath.Join(first, "SKILL.md"):  "old first\n",
+				filepath.Join(second, "SKILL.md"): "old second\n",
+			} {
+				got, readErr := os.ReadFile(path)
+				if readErr != nil || string(got) != want {
+					t.Fatalf("restored %s = %q, err=%v, want %q", path, got, readErr, want)
+				}
+			}
+			entries, readErr := os.ReadDir(dest)
+			if readErr != nil {
+				t.Fatal(readErr)
+			}
+			for _, entry := range entries {
+				if strings.HasPrefix(entry.Name(), ".dws-setup-set-") {
+					t.Fatalf("transaction left staging directory %s", entry.Name())
+				}
+			}
+			if !strings.Contains(errOut.String(), "已执行回滚") || !strings.Contains(errOut.String(), failure.Error()) {
+				t.Fatalf("transaction failure output = %q", errOut.String())
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
+	failure := errors.New("injected transaction failure")
+
+	t.Run("managed publish success", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{"dingtalk-a"})
+		dest := filepath.Join(t.TempDir(), "dingtalk-a")
+		if err := publishDWSManagedSkillDir(filepath.Join(src, "dingtalk-a"), dest); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := os.Stat(filepath.Join(dest, "SKILL.md")); err != nil {
+			t.Fatalf("published Skill missing: %v", err)
+		}
+	})
+
+	t.Run("staging cleanup failure", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{"dingtalk-a"})
+		dest := t.TempDir()
+		testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { return failure })
+		cleanupErr := errors.New("staging cleanup failure")
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupErr })
+		_, _, err := stageSkillSetupTarget(
+			&skillSetupPlan{Mode: skillSetupModeMulti, Source: src, MultiSkillNames: []string{"dingtalk-a"}},
+			skillSetupTargetPlan{Destination: dest},
+		)
+		if !errors.Is(err, failure) || !errors.Is(err, cleanupErr) {
+			t.Fatalf("staging cleanup error = %v", err)
+		}
+	})
+
+	t.Run("staging directory failure", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{"dingtalk-a"})
+		dest := t.TempDir()
+		originalMkdirAll := skillSetupMkdirAll
+		testseam.Swap(t, &skillSetupMkdirAll, func(path string, mode os.FileMode) error {
+			if filepath.Base(path) == "dingtalk-a" && strings.HasPrefix(filepath.Base(filepath.Dir(path)), ".dws-setup-set-") {
+				return failure
+			}
+			return originalMkdirAll(path, mode)
+		})
+		_, _, err := stageSkillSetupTarget(
+			&skillSetupPlan{Mode: skillSetupModeMulti, Source: src, MultiSkillNames: []string{"dingtalk-a"}},
+			skillSetupTargetPlan{Destination: dest},
+		)
+		if !errors.Is(err, failure) || !strings.Contains(err.Error(), "创建 Skill staging 目录失败") {
+			t.Fatalf("staging directory error = %v", err)
+		}
+	})
+
+	t.Run("restore failure aggregation", func(t *testing.T) {
+		t.Run("remove published", func(t *testing.T) {
+			testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return failure })
+			if err := restoreSkillSetupTarget([]string{"published"}, nil); !errors.Is(err, failure) {
+				t.Fatalf("remove published error = %v", err)
+			}
+		})
+		t.Run("original still exists", func(t *testing.T) {
+			original := t.TempDir()
+			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: original, backup: "backup"}})
+			if err == nil || !strings.Contains(err.Error(), "恢复目标仍存在") {
+				t.Fatalf("existing restore target error = %v", err)
+			}
+		})
+		t.Run("stat", func(t *testing.T) {
+			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, failure })
+			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
+			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "检查 Skill 恢复目标失败") {
+				t.Fatalf("restore stat error = %v", err)
+			}
+		})
+		t.Run("mkdir", func(t *testing.T) {
+			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+			testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return failure })
+			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
+			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "创建 Skill 恢复目录失败") {
+				t.Fatalf("restore mkdir error = %v", err)
+			}
+		})
+		t.Run("rename", func(t *testing.T) {
+			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+			testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
+			testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return failure })
+			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
+			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "恢复原 Skill 失败") {
+				t.Fatalf("restore rename error = %v", err)
+			}
+		})
+	})
+
+	t.Run("backup rollback failure", func(t *testing.T) {
+		calls := 0
+		testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) {
+			calls++
+			if calls == 1 {
+				return "backup", nil
+			}
+			return "", failure
+		})
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+		testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
+		restoreErr := errors.New("restore failure")
+		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return restoreErr })
+		_, err := backupSkillSetupTarget("home", []skillSetupBackup{{Path: "first"}, {Path: "second"}}, io.Discard)
+		if !errors.Is(err, failure) || !errors.Is(err, restoreErr) {
+			t.Fatalf("backup rollback error = %v", err)
+		}
+	})
+
+	t.Run("publish rollback failure", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return failure })
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+		testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
+		err := publishSkillSetupTarget(
+			[]skillSetupStagedDir{{staged: "staged", dest: "dest"}},
+			[]skillSetupBackedUpDir{{original: "dest", backup: "backup"}},
+		)
+		if !errors.Is(err, failure) || !strings.Contains(err.Error(), "回滚不完整") {
+			t.Fatalf("publish rollback error = %v", err)
+		}
+	})
+
+	t.Run("execute cleanup errors", func(t *testing.T) {
+		newPlan := func(t *testing.T) *skillSetupPlan {
+			t.Helper()
+			src := writeMultiSkillSource(t, []string{"dingtalk-a"})
+			return &skillSetupPlan{
+				Mode:            skillSetupModeMulti,
+				Source:          src,
+				MultiSkillNames: []string{"dingtalk-a"},
+				Targets:         []skillSetupTargetPlan{{Destination: t.TempDir()}},
+			}
+		}
+
+		t.Run("after backup failure", func(t *testing.T) {
+			plan := newPlan(t)
+			plan.Targets[0].Backups = []skillSetupBackup{{Path: filepath.Join(plan.Targets[0].Destination, "old")}}
+			testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return t.TempDir(), nil })
+			testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) { return "", failure })
+			cleanupErr := errors.New("cleanup after backup failure")
+			testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupErr })
+			var stderr bytes.Buffer
+			_, skipped, err := executeSkillSetupPlan(plan, io.Discard, &stderr)
+			if err != nil || skipped != 1 || !strings.Contains(stderr.String(), cleanupErr.Error()) {
+				t.Fatalf("backup cleanup = skipped %d, err %v, stderr %q", skipped, err, stderr.String())
+			}
+		})
+
+		t.Run("after publish failure", func(t *testing.T) {
+			plan := newPlan(t)
+			originalRename := skillSetupPublishRename
+			testseam.Swap(t, &skillSetupPublishRename, func(oldPath, newPath string) error {
+				if strings.HasPrefix(filepath.Base(filepath.Dir(oldPath)), ".dws-setup-set-") {
+					return failure
+				}
+				return originalRename(oldPath, newPath)
+			})
+			originalRemoveAll := skillSetupRemoveAll
+			cleanupErr := errors.New("cleanup after publish failure")
+			testseam.Swap(t, &skillSetupRemoveAll, func(path string) error {
+				if strings.HasPrefix(filepath.Base(path), ".dws-setup-set-") {
+					return cleanupErr
+				}
+				return originalRemoveAll(path)
+			})
+			var stderr bytes.Buffer
+			_, skipped, err := executeSkillSetupPlan(plan, io.Discard, &stderr)
+			if err != nil || skipped != 1 || !strings.Contains(stderr.String(), cleanupErr.Error()) {
+				t.Fatalf("publish cleanup = skipped %d, err %v, stderr %q", skipped, err, stderr.String())
+			}
+		})
+
+		t.Run("after success", func(t *testing.T) {
+			plan := newPlan(t)
+			originalRemoveAll := skillSetupRemoveAll
+			cleanupErr := errors.New("cleanup after success")
+			testseam.Swap(t, &skillSetupRemoveAll, func(path string) error {
+				if strings.HasPrefix(filepath.Base(path), ".dws-setup-set-") {
+					return cleanupErr
+				}
+				return originalRemoveAll(path)
+			})
+			var stderr bytes.Buffer
+			installed, skipped, err := executeSkillSetupPlan(plan, io.Discard, &stderr)
+			if err != nil || installed != 1 || skipped != 0 || !strings.Contains(stderr.String(), cleanupErr.Error()) {
+				t.Fatalf("success cleanup = installed %d, skipped %d, err %v, stderr %q", installed, skipped, err, stderr.String())
+			}
+		})
+	})
+}
+
+// TestCrossPlatformCoverageSkillSetupInstallHomeFailureSkips verifies both
+// install paths skip (never destroy) every target when $HOME cannot be
+// resolved for the pre-refresh backup.
+func TestCrossPlatformCoverageSkillSetupInstallHomeFailureSkips(t *testing.T) {
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", errors.New("home boom") })
+
+	monoSrc := t.TempDir()
+	if err := os.WriteFile(filepath.Join(monoSrc, "SKILL.md"), []byte("# mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
+	if err := os.MkdirAll(monoDest, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(monoDest, "SKILL.md"), []byte("# old"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installSkillToHomes(monoSrc, []string{monoDest}, &out, &errOut)
+	if err != nil || installed != 0 || skipped != 1 {
+		t.Fatalf("mono install = (%d, %d, %v), want (0, 1, nil)", installed, skipped, err)
+	}
+	if !strings.Contains(errOut.String(), "无法解析 HOME，跳过刷新") {
+		t.Fatalf("expected HOME skip warning, got %q", errOut.String())
+	}
+	if _, err := os.Stat(filepath.Join(monoDest, "SKILL.md")); err != nil {
+		t.Fatalf("existing mono dir must be preserved: %v", err)
+	}
+
+	multiSrc := writeMultiSkillSource(t, []string{"dingtalk-a"})
+	multiDest := filepath.Join(t.TempDir(), ".claude", "skills")
+	if err := os.MkdirAll(filepath.Join(multiDest, "dingtalk-a"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	out.Reset()
+	errOut.Reset()
+	installed, skipped, err = installMultiSkillToHomes(multiSrc, []string{"dingtalk-a"}, []string{multiDest}, &out, &errOut, true)
+	if err != nil || installed != 0 || skipped != 1 {
+		t.Fatalf("multi install = (%d, %d, %v), want (0, 1, nil)", installed, skipped, err)
+	}
+	if !strings.Contains(errOut.String(), "无法解析 HOME，跳过整个 Agent 目标") {
+		t.Fatalf("expected multi HOME skip warning, got %q", errOut.String())
+	}
+	if _, err := os.Stat(filepath.Join(multiDest, "dingtalk-a")); err != nil {
+		t.Fatalf("existing sub skill must be preserved: %v", err)
+	}
+}
+
+// TestCrossPlatformCoverageSkillSetupRemoveStaleMultiSkillsEdges covers
+// removeStaleMultiSkills and its preview companion staleMultiSkillVictims:
+// scan failures, the HOME failure, backup failures, and the success path.
+func TestCrossPlatformCoverageSkillSetupRemoveStaleMultiSkillsEdges(t *testing.T) {
+	dest := filepath.Join(t.TempDir(), ".cursor", "skills")
+	keep := []string{"dingtalk-chat"}
+	entries := map[string]bool{ // dir entries; README below is a plain file
+		"dingtalk-chat":  true, // kept (in bundle)
+		"dingtalk-stale": true, // stale product skill
+		"dws-shared":     true, // legacy shared name is stale too
+		"other-skill":    true, // non-DWS, must survive
+	}
+	for name := range entries {
+		if err := os.MkdirAll(filepath.Join(dest, name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useManagedSkillNames(t, "dingtalk-stale")
+	if err := os.WriteFile(filepath.Join(dest, "README"), []byte("file"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	var out, errOut bytes.Buffer
+
+	// Non-ENOENT scan failure warns; ENOENT is silent.
+	testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, errors.New("scan boom") })
+	removeStaleMultiSkills(dest, keep, &out, &errOut)
+	if !strings.Contains(errOut.String(), "过期 skill 扫描失败") {
+		t.Fatalf("expected scan warning, got %q", errOut.String())
+	}
+	errOut.Reset()
+	testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, os.ErrNotExist })
+	removeStaleMultiSkills(dest, keep, &out, &errOut)
+	if errOut.Len() != 0 {
+		t.Fatalf("ENOENT scan must be silent, got %q", errOut.String())
+	}
+	testseam.Swap(t, &skillSetupReadDir, os.ReadDir)
+
+	// The preview companion sees the same victims and skips files/kept/non-DWS.
+	victims := staleMultiSkillVictims(dest, keep)
+	wantVictims := []string{filepath.Join(dest, "dingtalk-stale"), filepath.Join(dest, "dws-shared")}
+	if len(victims) != len(wantVictims) {
+		t.Fatalf("staleMultiSkillVictims = %v, want %v", victims, wantVictims)
+	}
+
+	// HOME failure keeps every stale directory with a warning.
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", errors.New("home boom") })
+	errOut.Reset()
+	removeStaleMultiSkills(dest, keep, &out, &errOut)
+	if !strings.Contains(errOut.String(), "无法解析 HOME，跳过删除") {
+		t.Fatalf("expected HOME warning, got %q", errOut.String())
+	}
+	for name := range entries {
+		if _, err := os.Stat(filepath.Join(dest, name)); err != nil {
+			t.Fatalf("entry %s must survive the HOME failure: %v", name, err)
+		}
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return t.TempDir(), nil })
+
+	// Backup failure keeps the stale directory with a warning.
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) { return "", errors.New("backup boom") })
+	errOut.Reset()
+	removeStaleMultiSkills(dest, keep, &out, &errOut)
+	if !strings.Contains(errOut.String(), "过期 skill 清理失败（保留原目录") {
+		t.Fatalf("expected backup failure warning, got %q", errOut.String())
+	}
+	for _, stale := range wantVictims {
+		if _, err := os.Stat(stale); err != nil {
+			t.Fatalf("stale dir must survive the backup failure: %v", err)
+		}
+	}
+
+	// Success: both stale dirs are backed up and reported; the rest survives.
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_, dir string) (string, error) { return filepath.Join(t.TempDir(), "backup"), nil })
+	out.Reset()
+	removeStaleMultiSkills(dest, keep, &out, &errOut)
+	if count := strings.Count(out.String(), "已备份并清理过期 skill"); count != len(wantVictims) {
+		t.Fatalf("expected %d stale cleanup lines, got %d (out=%q)", len(wantVictims), count, out.String())
+	}
+	if _, err := os.Stat(filepath.Join(dest, "other-skill")); err != nil {
+		t.Fatalf("non-DWS dir must survive: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dest, "dingtalk-chat")); err != nil {
+		t.Fatalf("bundle skill must survive: %v", err)
+	}
+}
@@ -47,18 +47,16 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 	oldTargets := skillSetupResolveTargets
 	oldList := skillSetupListMulti
 	oldFilter := skillSetupFilterMulti
-	oldConfirm := skillSetupConfirm
-	oldMono := skillSetupInstallMono
-	oldMulti := skillSetupInstallMulti
+	oldConfirm := skillSetupConfirmPlan
+	oldExecute := skillSetupExecutePlan
 	t.Cleanup(func() {
 		skillSetupResolveMode = oldMode
 		skillSetupResolveSource = oldSource
 		skillSetupResolveTargets = oldTargets
 		skillSetupListMulti = oldList
 		skillSetupFilterMulti = oldFilter
-		skillSetupConfirm = oldConfirm
-		skillSetupInstallMono = oldMono
-		skillSetupInstallMulti = oldMulti
+		skillSetupConfirmPlan = oldConfirm
+		skillSetupExecutePlan = oldExecute
 	})
 	fail := errors.New("failure")
 	skillSetupResolveMode = func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil }
@@ -83,17 +81,17 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 	}
 	skillSetupFilterMulti = func(all, _, _ []string) ([]string, error) { return all, nil }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
-	_ = cmd.Root().PersistentFlags().Set("dry-run", "true")
+	cmd.Flags().Bool("dry-run", true, "")
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
 	}

-	skillSetupConfirm = func(io.Writer, string, string, []string, []string) (bool, error) { return false, fail }
+	skillSetupConfirmPlan = func(io.Writer, *skillSetupPlan) (bool, error) { return false, fail }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, false)
 	if err := cmd.RunE(cmd, nil); err == nil {
 		t.Fatal("confirmation failure should propagate")
 	}
-	skillSetupConfirm = func(io.Writer, string, string, []string, []string) (bool, error) { return false, nil }
+	skillSetupConfirmPlan = func(io.Writer, *skillSetupPlan) (bool, error) { return false, nil }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, false)
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
@@ -105,17 +103,17 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 		t.Fatal("unknown resolved mode should fail")
 	}
 	skillSetupResolveMode = func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil }
-	skillSetupInstallMono = func(string, []string, io.Writer, io.Writer) (int, int, error) { return 0, 0, fail }
+	skillSetupExecutePlan = func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) { return 0, 0, fail }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, true)
 	if err := cmd.RunE(cmd, nil); err == nil {
 		t.Fatal("mono install failure should propagate")
 	}
-	skillSetupInstallMono = func(string, []string, io.Writer, io.Writer) (int, int, error) { return 1, 0, nil }
+	skillSetupExecutePlan = func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) { return 1, 0, nil }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, true)
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
 	}
-	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) { return 0, 0, fail }
+	skillSetupExecutePlan = func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) { return 0, 0, fail }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
 	if err := cmd.RunE(cmd, nil); err == nil {
 		t.Fatal("multi install failure should propagate")
@@ -123,6 +121,7 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 }

 func TestCrossPlatformCoverageSkillSetupMigratesLegacySharedAfterReplacement(t *testing.T) {
+	setTestHome(t, t.TempDir())
 	src := writeMultiSkillSource(t, []string{multiSharedSkill, "dingtalk-chat"})
 	home := filepath.Join(t.TempDir(), "skills")
 	legacyPath := filepath.Join(home, legacyMultiSharedSkill)
@@ -143,6 +142,7 @@ func TestCrossPlatformCoverageSkillSetupMigratesLegacySharedAfterReplacement(t *
 		[]string{home},
 		&out,
 		&errOut,
+		true,
 	)
 	if err != nil || installed != 2 || skipped != 0 {
 		t.Fatalf("install = %d/%d, err=%v, stderr=%s", installed, skipped, err, errOut.String())
@@ -156,7 +156,7 @@ func TestCrossPlatformCoverageSkillSetupMigratesLegacySharedAfterReplacement(t *
 	if _, err := os.Stat(filepath.Join(customPath, "SKILL.md")); err != nil {
 		t.Fatalf("unrelated custom skill changed: %v", err)
 	}
-	if !strings.Contains(out.String(), "已清理已退役 Skill 残留") {
+	if !strings.Contains(out.String(), "已备份并清理过期 skill") {
 		t.Fatalf("legacy cleanup was not reported: %s", out.String())
 	}

@@ -178,12 +178,17 @@ func TestCrossPlatformCoverageSkillSetupMigratesLegacySharedAfterReplacement(t *
 			[]string{failureHome},
 			&failureOut,
 			&failureErr,
+			true,
 		)
 		if err != nil || installed != 0 || skipped != 1 {
 			t.Fatalf("failed replacement = %d/%d, err=%v", installed, skipped, err)
 		}
-		if _, err := os.Stat(filepath.Join(failureLegacy, "SKILL.md")); err != nil {
-			t.Fatalf("failed replacement removed legacy shared skill: %v", err)
+		got, readErr := os.ReadFile(filepath.Join(failureLegacy, "SKILL.md"))
+		if readErr != nil || string(got) != "legacy\n" {
+			t.Fatalf("failed replacement changed the live legacy copy: %q, err=%v", got, readErr)
+		}
+		if !strings.Contains(failureErr.String(), "Skill staging 失败，保留原集合") {
+			t.Fatalf("failed replacement did not report preserved live set: %s", failureErr.String())
 		}
 	})
 }
@@ -226,6 +231,7 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	oldReadDir, oldStat := skillSetupReadDir, skillSetupStat
 	oldExecutable, oldGetwd, oldHome := skillSetupExecutable, skillSetupGetwd, skillSetupUserHomeDir
 	oldRemove, oldMkdir := skillSetupRemoveAll, skillSetupMkdirAll
+	oldBackup := skillSetupBackupAndRemove
 	oldCopyDir, oldWalk, oldRel := skillSetupCopyDir, skillSetupWalk, skillSetupRel
 	oldMkdirTemp, oldRename := skillSetupMkdirTemp, skillSetupRename
 	oldReadlink, oldOpen, oldOpenFile, oldCopy := skillSetupReadlink, skillSetupOpen, skillSetupOpenFile, skillSetupCopy
@@ -234,6 +240,7 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 		skillSetupReadDir, skillSetupStat = oldReadDir, oldStat
 		skillSetupExecutable, skillSetupGetwd, skillSetupUserHomeDir = oldExecutable, oldGetwd, oldHome
 		skillSetupRemoveAll, skillSetupMkdirAll = oldRemove, oldMkdir
+		skillSetupBackupAndRemove = oldBackup
 		skillSetupCopyDir, skillSetupWalk, skillSetupRel = oldCopyDir, oldWalk, oldRel
 		skillSetupMkdirTemp, skillSetupRename = oldMkdirTemp, oldRename
 		skillSetupReadlink, skillSetupOpen, skillSetupOpenFile, skillSetupCopy = oldReadlink, oldOpen, oldOpenFile, oldCopy
@@ -246,7 +253,7 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 		t.Fatal("interactive mode failure should propagate")
 	}
 	skillSetupRunForm = func(*huh.Form) error { return nil }
-	if got, err := resolveSkillSetupMode("", false, io.Discard); err != nil || got != skillSetupModeMono {
+	if got, err := resolveSkillSetupMode("", false, io.Discard); err != nil || got != skillSetupModeMulti {
 		t.Fatalf("interactive default choice = %q, %v", got, err)
 	}

@@ -305,23 +312,24 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	skillSetupReadDir, skillSetupStat = oldReadDir, oldStat
 	var out, errOut bytes.Buffer
 	skillSetupRunForm = func(*huh.Form) error { return fail }
-	if _, err := confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{monoDest}, []string{"dingtalk-doc"}); err == nil {
+	if _, err := confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{monoDest}, []string{"dingtalk-doc"}, false); err == nil {
 		t.Fatal("confirmation form failure should propagate")
 	}
 	skillSetupRunForm = func(*huh.Form) error { return nil }
-	if ok, err := confirmSkillSetup(&out, skillSetupModeMono, "src", []string{monoDest}, nil); err != nil || ok {
+	if ok, err := confirmSkillSetup(&out, skillSetupModeMono, "src", []string{monoDest}, nil, false); err != nil || ok {
 		t.Fatalf("EOF confirmation = %v, %v", ok, err)
 	}
-	skillSetupRemoveAll = func(string) error { return fail }
+	skillSetupUserHomeDir = func() (string, error) { return t.TempDir(), nil }
+	skillSetupBackupAndRemove = func(string, string) (string, error) { return "", fail }
 	cleanupMutualExclusion(monoDest, skillSetupModeMono, &out, &errOut)

 	skillSetupCopyDir = func(string, string) error { return fail }
-	skillSetupRemoveAll = func(string) error { return fail }
+	skillSetupBackupAndRemove = func(string, string) (string, error) { return "", fail }
 	_, skipped, _ := installSkillToHomes("src", []string{"a"}, &out, &errOut)
 	if skipped != 1 {
-		t.Fatal("mono remove failure not skipped")
+		t.Fatal("mono backup failure not skipped")
 	}
-	skillSetupRemoveAll = func(string) error { return nil }
+	skillSetupBackupAndRemove = func(string, string) (string, error) { return "", nil }
 	skillSetupMkdirAll = func(string, os.FileMode) error { return fail }
 	_, skipped, _ = installSkillToHomes("src", []string{"b"}, &out, &errOut)
 	if skipped != 1 {
@@ -334,18 +342,18 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	}

 	skillSetupMkdirAll = func(string, os.FileMode) error { return fail }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one", "two"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one", "two"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
 	if skipped != 2 {
 		t.Fatal("multi mkdir failure count mismatch")
 	}
 	skillSetupMkdirAll = func(string, os.FileMode) error { return nil }
-	skillSetupRemoveAll = func(string) error { return fail }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
+	skillSetupBackupAndRemove = func(string, string) (string, error) { return "", fail }
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
 	if skipped != 1 {
-		t.Fatal("multi remove failure count mismatch")
+		t.Fatal("multi backup failure count mismatch")
 	}
-	skillSetupRemoveAll = func(string) error { return nil }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
+	skillSetupBackupAndRemove = func(string, string) (string, error) { return "", nil }
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
 	if skipped != 1 {
 		t.Fatal("multi copy failure count mismatch")
 	}
@@ -516,15 +524,15 @@ func TestCrossPlatformCoverageSkillSetupEventMigrationFailureBranches(t *testing
 	})

 	t.Run("ordinary and prerequisite install errors", func(t *testing.T) {
-		testseam.Swap(t, &skillSetupInstallMulti, func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+		testseam.Swap(t, &skillSetupInstallMulti, func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) {
 			return 0, 0, fail
 		})
 		migration := filepath.Join(t.TempDir(), "migration")
 		ordinary := filepath.Join(t.TempDir(), "ordinary")
-		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill}, []string{migration, ordinary}, []string{migration}, io.Discard, io.Discard); !errors.Is(err, fail) {
+		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill}, []string{migration, ordinary}, []string{migration}, true, io.Discard, io.Discard); !errors.Is(err, fail) {
 			t.Fatalf("ordinary install failure = %v", err)
 		}
-		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill, multiMiscSkill, multiSharedSkill}, []string{migration}, []string{migration}, io.Discard, io.Discard); !errors.Is(err, fail) {
+		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill, multiMiscSkill, multiSharedSkill}, []string{migration}, []string{migration}, true, io.Discard, io.Discard); !errors.Is(err, fail) {
 			t.Fatalf("prerequisite install failure = %v", err)
 		}
 	})
@@ -0,0 +1,345 @@
+package app
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/charmbracelet/huh"
+)
+
+func TestCrossPlatformCoverageSkillSetupPlanPreviewDeclineAndExecutionMatch(t *testing.T) {
+	home := t.TempDir()
+	dest := filepath.Join(home, ".claude", "skills")
+	source := writeMultiSkillSource(t, []string{"dingtalk-a", "dingtalk-shared"})
+	for _, name := range []string{"dws", "dingtalk-a", "dingtalk-stale"} {
+		if err := os.MkdirAll(filepath.Join(dest, name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useManagedSkillNames(t, "dingtalk-stale")
+
+	testseam.Swap(t, &skillSetupResolveMode, func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil })
+	testseam.Swap(t, &skillSetupResolveSource, func(string, string) (string, func(), error) { return source, func() {}, nil })
+	testseam.Swap(t, &skillSetupResolveTargets, func(string, string) ([]string, error) { return []string{dest}, nil })
+	testseam.Swap(t, &skillSetupListMulti, func(string) ([]string, error) {
+		return []string{"dingtalk-a", "dingtalk-shared"}, nil
+	})
+	testseam.Swap(t, &skillSetupFilterMulti, filterMultiSkillNames)
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupInteractive, func() bool { return true })
+	testseam.Swap(t, &skillSetupRunForm, func(*huh.Form) error { return nil })
+	testseam.Swap(t, &skillSetupWriteState, func(string, skillstate.State) error { return nil })
+
+	wantBackups := []string{
+		filepath.Join(dest, "dingtalk-a"),
+		filepath.Join(dest, "dingtalk-stale"),
+		filepath.Join(dest, "dws"),
+	}
+
+	// Dry-run must disclose every exact path and perform no backup or copy.
+	backupCalls, copyCalls := []string{}, 0
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, path string) (string, error) {
+		backupCalls = append(backupCalls, path)
+		return "backup", nil
+	})
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { copyCalls++; return nil })
+	testseam.Swap(t, &skillSetupWriteFile, func(string, []byte, os.FileMode) error { return nil })
+	testseam.Swap(t, &skillSetupPublishRename, func(src, dest string) error {
+		if err := os.RemoveAll(dest); err != nil {
+			return err
+		}
+		return os.Rename(src, dest)
+	})
+	dryRunCmd := skillSetupCoverageCommand(t, skillSetupModeMulti, false)
+	var dryRunOut bytes.Buffer
+	dryRunCmd.SetOut(&dryRunOut)
+	if err := dryRunCmd.Root().PersistentFlags().Set("dry-run", "true"); err != nil {
+		t.Fatal(err)
+	}
+	if err := dryRunCmd.RunE(dryRunCmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range wantBackups {
+		if strings.Count(dryRunOut.String(), path) != 1 {
+			t.Fatalf("dry-run path %s count != 1:\n%s", path, dryRunOut.String())
+		}
+	}
+	if len(backupCalls) != 0 || copyCalls != 0 {
+		t.Fatalf("dry-run mutated backup=%v copy=%d", backupCalls, copyCalls)
+	}
+
+	// The real confirmation renderer discloses the same paths. Its default
+	// negative answer must leave backup and copy at zero calls.
+	declineCmd := skillSetupCoverageCommand(t, skillSetupModeMulti, false)
+	var declineOut bytes.Buffer
+	declineCmd.SetOut(&declineOut)
+	if err := declineCmd.RunE(declineCmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range wantBackups {
+		if strings.Count(declineOut.String(), path) != 1 {
+			t.Fatalf("confirmation path %s count != 1:\n%s", path, declineOut.String())
+		}
+	}
+	if len(backupCalls) != 0 || copyCalls != 0 {
+		t.Fatalf("declined confirmation mutated backup=%v copy=%d", backupCalls, copyCalls)
+	}
+
+	// Explicit confirmation executes exactly the paths rendered from the plan.
+	var confirmedPlan *skillSetupPlan
+	testseam.Swap(t, &skillSetupConfirmPlan, func(out io.Writer, plan *skillSetupPlan) (bool, error) {
+		confirmedPlan = plan
+		renderSkillSetupPlan(out, plan)
+		return true, nil
+	})
+	confirmCmd := skillSetupCoverageCommand(t, skillSetupModeMulti, false)
+	if err := confirmCmd.RunE(confirmCmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	var planned []string
+	for _, target := range confirmedPlan.Targets {
+		for _, backup := range target.Backups {
+			planned = append(planned, backup.Path)
+		}
+	}
+	if !reflect.DeepEqual(planned, wantBackups) || !reflect.DeepEqual(backupCalls, wantBackups) {
+		t.Fatalf("planned=%v executed=%v want=%v", planned, backupCalls, wantBackups)
+	}
+	if copyCalls != 2 {
+		t.Fatalf("copy calls = %d, want 2", copyCalls)
+	}
+
+	// A filtered multi plan replaces only selected same-name skills and leaves
+	// unselected siblings out of the backup set.
+	filtered, err := buildSkillSetupPlan(skillSetupModeMulti, source, []string{dest}, []string{"dingtalk-a"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var filteredPaths []string
+	for _, backup := range filtered.Targets[0].Backups {
+		filteredPaths = append(filteredPaths, backup.Path)
+	}
+	if !reflect.DeepEqual(filteredPaths, []string{filepath.Join(dest, "dingtalk-a"), filepath.Join(dest, "dws")}) {
+		t.Fatalf("filtered backups = %v", filteredPaths)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupMonoPlanIncludesSameNameTarget(t *testing.T) {
+	dest := filepath.Join(t.TempDir(), ".agents", "skills", "dws")
+	if err := os.MkdirAll(dest, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	plan, err := buildSkillSetupPlan(skillSetupModeMono, "source", []string{dest}, nil, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Targets) != 1 || len(plan.Targets[0].Backups) != 1 || plan.Targets[0].Backups[0].Path != dest || plan.Targets[0].Backups[0].Reason != skillSetupBackupReplace {
+		t.Fatalf("mono plan = %#v", plan)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupPlanDeduplicatesAndFailsClosed(t *testing.T) {
+	dest := filepath.Join(t.TempDir(), "skills")
+	if err := os.MkdirAll(filepath.Join(dest, "dws"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// "dws" is synthetic but makes the mutual-exclusion target and selected
+	// same-name target overlap, pinning path deduplication in the plan itself.
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dws"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Targets[0].Backups) != 1 || plan.Targets[0].Backups[0].Path != filepath.Join(dest, "dws") {
+		t.Fatalf("deduplicated plan = %#v", plan)
+	}
+
+	failure := errors.New("scan denied")
+	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
+	if err := os.MkdirAll(filepath.Dir(monoDest), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, failure })
+	if _, err := buildSkillSetupPlan(skillSetupModeMono, "source", []string{monoDest}, nil, false); err == nil || !strings.Contains(err.Error(), "\u68c0\u67e5\u5c06\u88ab\u66ff\u6362") {
+		t.Fatalf("replacement stat error = %v", err)
+	}
+
+	testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+	testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, failure })
+	if _, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-a"}, false); err == nil || !strings.Contains(err.Error(), "\u626b\u63cf\u8fc7\u671f") {
+		t.Fatalf("stale scan error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupInstallWrappersFailOnPlanErrors(t *testing.T) {
+	t.Run("multi mono-leftover stat failure", func(t *testing.T) {
+		failure := errors.New("stat denied")
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) {
+			return nil, failure
+		})
+
+		installed, skipped, err := installMultiSkillToHomes(
+			"source",
+			[]string{"dingtalk-a"},
+			[]string{filepath.Join(t.TempDir(), "skills")},
+			io.Discard,
+			io.Discard,
+			true,
+		)
+		if installed != 0 || skipped != 1 || !errors.Is(err, failure) {
+			t.Fatalf("installMultiSkillToHomes = (%d, %d, %v), want (0, 1, %v)", installed, skipped, err, failure)
+		}
+	})
+
+	t.Run("mono multi-leftover scan failure", func(t *testing.T) {
+		failure := errors.New("scan denied")
+		testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) {
+			return nil, failure
+		})
+
+		installed, skipped, err := installSkillToHomes(
+			"source",
+			[]string{filepath.Join(t.TempDir(), "skills", "dws")},
+			io.Discard,
+			io.Discard,
+		)
+		if installed != 0 || skipped != 1 || !errors.Is(err, failure) {
+			t.Fatalf("installSkillToHomes = (%d, %d, %v), want (0, 1, %v)", installed, skipped, err, failure)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillSetupMergedEventPlanEdges(t *testing.T) {
+	t.Run("legacy shared stat failure", func(t *testing.T) {
+		dest := filepath.Join(t.TempDir(), "skills")
+		failure := errors.New("legacy stat denied")
+		testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+			if path == filepath.Join(dest, legacySharedSkill) {
+				return nil, failure
+			}
+			return nil, os.ErrNotExist
+		})
+
+		_, err := buildSkillSetupPlan(
+			skillSetupModeMulti,
+			"source",
+			[]string{dest},
+			[]string{multiSharedSkill},
+			true,
+		)
+		if !errors.Is(err, failure) {
+			t.Fatalf("legacy shared stat error = %v, want %v", err, failure)
+		}
+	})
+
+	t.Run("migration plan retains unrelated backups", func(t *testing.T) {
+		dest := filepath.Join(t.TempDir(), "skills")
+		unrelated := filepath.Join(dest, "dws")
+		plan := &skillSetupPlan{Targets: []skillSetupTargetPlan{
+			{
+				Destination: dest,
+				Backups: []skillSetupBackup{
+					{Path: filepath.Join(dest, multiEventSkill)},
+					{Path: filepath.Join(dest, multiMiscSkill)},
+					{Path: unrelated},
+				},
+			},
+		}}
+
+		configureEventMiscMigrationPlan(plan, []string{dest}, true)
+		if len(plan.Targets[0].Backups) != 1 || plan.Targets[0].Backups[0].Path != unrelated {
+			t.Fatalf("migration backups = %#v, want only %s", plan.Targets[0].Backups, unrelated)
+		}
+	})
+
+	t.Run("no migration targets delegates filtered install", func(t *testing.T) {
+		called := false
+		testseam.Swap(t, &skillSetupInstallMulti, func(_ string, _ []string, _ []string, _ io.Writer, _ io.Writer, filtered bool) (int, int, error) {
+			called = true
+			if !filtered {
+				t.Fatal("filtered flag was not forwarded")
+			}
+			return 1, 2, nil
+		})
+
+		installed, skipped, err := installMultiSkillsWithEventMigration(
+			"source", []string{"dingtalk-a"}, []string{"dest"}, nil, true, io.Discard, io.Discard,
+		)
+		if err != nil || installed != 1 || skipped != 2 || !called {
+			t.Fatalf("delegated install = (%d, %d, %v), called=%v", installed, skipped, err, called)
+		}
+	})
+
+	t.Run("migration cleanup scan failure", func(t *testing.T) {
+		failure := errors.New("cleanup stat denied")
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) {
+			return nil, failure
+		})
+		dest := filepath.Join(t.TempDir(), "skills")
+
+		installed, skipped, err := installMultiSkillsWithEventMigration(
+			"source",
+			[]string{multiEventSkill, multiSharedSkill},
+			[]string{dest},
+			[]string{dest},
+			true,
+			io.Discard,
+			io.Discard,
+		)
+		if installed != 0 || skipped != 2 || !errors.Is(err, failure) {
+			t.Fatalf("cleanup scan failure = (%d, %d, %v), want (0, 2, %v)", installed, skipped, err, failure)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillSetupEmptyCleanupPlansAreNoOps(t *testing.T) {
+	dest := t.TempDir()
+	var out, errOut bytes.Buffer
+	if err := cleanupMutualExclusion(dest, skillSetupModeMulti, &out, &errOut); err != nil {
+		t.Fatal(err)
+	}
+	if err := removeStaleMultiSkills(dest, []string{"dingtalk-a"}, &out, &errOut); err != nil {
+		t.Fatal(err)
+	}
+	if out.Len() != 0 || errOut.Len() != 0 {
+		t.Fatalf("empty cleanup output = %q / %q", out.String(), errOut.String())
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupSameNameBackupFailureSkipsTarget(t *testing.T) {
+	home := t.TempDir()
+	dest := filepath.Join(home, ".agents", "skills")
+	plan := &skillSetupPlan{
+		Mode:            skillSetupModeMulti,
+		Source:          "source",
+		MultiSkillNames: []string{"dingtalk-a"},
+		Targets: []skillSetupTargetPlan{{
+			Destination: dest,
+			Backups: []skillSetupBackup{{
+				Path:   filepath.Join(dest, "dingtalk-a"),
+				Reason: skillSetupBackupReplace,
+			}},
+		}},
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) {
+		return "", errors.New("backup denied")
+	})
+	copyCalls := 0
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { copyCalls++; return nil })
+	var out, errOut bytes.Buffer
+	installed, skipped, err := executeSkillSetupPlan(plan, &out, &errOut)
+	if err != nil || installed != 0 || skipped != 1 || copyCalls != 1 {
+		t.Fatalf("same-name failure = (%d, %d, %v), copy=%d", installed, skipped, err, copyCalls)
+	}
+	if !strings.Contains(errOut.String(), "Skill 备份失败，已执行回滚，跳过整个 Agent 目标") {
+		t.Fatalf("same-name warning = %q", errOut.String())
+	}
+}
@@ -0,0 +1,190 @@
+package app
+
+import (
+	"errors"
+	"io"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillprovenance"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageSkillSetupPersistsOfficialSnapshot(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupResolveMode, func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil })
+	testseam.Swap(t, &skillSetupResolveSource, func(string, string) (string, func(), error) { return "source", func() {}, nil })
+	testseam.Swap(t, &skillSetupResolveTargets, func(string, string) ([]string, error) { return []string{filepath.Join(home, "skills")}, nil })
+	testseam.Swap(t, &skillSetupListMulti, func(string) ([]string, error) {
+		return []string{"dingtalk-a", "dingtalk-b", "dingtalk-shared"}, nil
+	})
+	testseam.Swap(t, &skillSetupFilterMulti, filterMultiSkillNames)
+	testseam.Swap(t, &skillSetupBuildProvenance, func(name, _ string, version, source string) (skillprovenance.Record, error) {
+		return skillprovenance.Record{Name: name, Version: version, Source: source, Digest: "sha256:test", DigestScope: skillprovenance.DigestScope}, nil
+	})
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupReadState, func(string) (*skillstate.State, bool, error) {
+		return &skillstate.State{ManagedSkills: []skillprovenance.Record{{Name: "dingtalk-existing"}}}, true, nil
+	})
+	testseam.Swap(t, &skillSetupExecutePlan, func(plan *skillSetupPlan, _ io.Writer, _ io.Writer) (int, int, error) {
+		if plan.Mode == skillSetupModeMono {
+			return 1, 0, nil
+		}
+		return 2, 0, nil
+	})
+	testseam.Swap(t, &skillSetupNow, func() time.Time {
+		return time.Date(2026, 8, 10, 1, 2, 3, 0, time.UTC)
+	})
+
+	var saved skillstate.State
+	testseam.Swap(t, &skillSetupWriteState, func(_ string, state skillstate.State) error {
+		saved = state
+		return nil
+	})
+	cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	if err := cmd.Flags().Set("skill", "a"); err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(saved.OfficialSkills, []string{"dingtalk-a", "dingtalk-b", "dingtalk-shared"}) ||
+		!reflect.DeepEqual(saved.UpdatedSkills, []string{"dingtalk-shared", "dingtalk-a"}) ||
+		!reflect.DeepEqual(skillprovenance.Names(saved.ManagedSkills), map[string]bool{"dingtalk-a": true, "dingtalk-existing": true, "dingtalk-shared": true}) {
+		t.Fatalf("saved = %#v", saved)
+	}
+
+	testseam.Swap(t, &skillSetupWriteState, func(string, skillstate.State) error { return errors.New("denied") })
+	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	if err := cmd.RunE(cmd, nil); err == nil || !strings.Contains(err.Error(), "信息快照失败") {
+		t.Fatalf("write-state error = %v", err)
+	}
+
+	testseam.Swap(t, &skillSetupRemoveState, func(string) error { return errors.New("denied") })
+	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, true)
+	if err := cmd.RunE(cmd, nil); err == nil || !strings.Contains(err.Error(), "清理 multi") {
+		t.Fatalf("remove-state error = %v", err)
+	}
+
+	testseam.Swap(t, &skillSetupRemoveState, func(string) error { return nil })
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", errors.New("no home") })
+	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, true)
+	if err := cmd.RunE(cmd, nil); err == nil || !strings.Contains(err.Error(), "无法解析 HOME") {
+		t.Fatalf("home error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupFilteredUnreadableStateStopsBeforeInstall(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupResolveMode, func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil })
+	testseam.Swap(t, &skillSetupResolveSource, func(string, string) (string, func(), error) { return "source", func() {}, nil })
+	testseam.Swap(t, &skillSetupResolveTargets, func(string, string) ([]string, error) { return []string{filepath.Join(home, "skills")}, nil })
+	testseam.Swap(t, &skillSetupListMulti, func(string) ([]string, error) { return []string{"dingtalk-a", "dingtalk-shared"}, nil })
+	testseam.Swap(t, &skillSetupFilterMulti, filterMultiSkillNames)
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupBuildProvenance, func(name, _ string, version, source string) (skillprovenance.Record, error) {
+		return skillprovenance.Record{Name: name, Version: version, Source: source, Digest: "sha256:test", DigestScope: skillprovenance.DigestScope}, nil
+	})
+	stateErr := errors.New("state denied")
+	testseam.Swap(t, &skillSetupReadState, func(string) (*skillstate.State, bool, error) { return nil, false, stateErr })
+	executed := 0
+	testseam.Swap(t, &skillSetupExecutePlan, func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) {
+		executed++
+		return 1, 0, nil
+	})
+
+	cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	if err := cmd.Flags().Set("skill", "a"); err != nil {
+		t.Fatal(err)
+	}
+	err := cmd.RunE(cmd, nil)
+	if !errors.Is(err, stateErr) || executed != 0 {
+		t.Fatalf("filtered setup = err %v, executed %d", err, executed)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupProvenancePreflightFailures(t *testing.T) {
+	for _, tc := range []struct {
+		name       string
+		filtered   bool
+		buildError error
+		homeError  error
+	}{
+		{name: "digest", buildError: errors.New("digest denied")},
+		{name: "filtered home", filtered: true, homeError: errors.New("home denied")},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			testseam.Swap(t, &skillSetupResolveMode, func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil })
+			testseam.Swap(t, &skillSetupResolveSource, func(string, string) (string, func(), error) { return "source", func() {}, nil })
+			testseam.Swap(t, &skillSetupResolveTargets, func(string, string) ([]string, error) { return []string{filepath.Join(home, "skills")}, nil })
+			testseam.Swap(t, &skillSetupListMulti, func(string) ([]string, error) { return []string{"dingtalk-a", "dingtalk-shared"}, nil })
+			testseam.Swap(t, &skillSetupFilterMulti, filterMultiSkillNames)
+			testseam.Swap(t, &skillSetupBuildProvenance, func(name, _ string, version, source string) (skillprovenance.Record, error) {
+				if tc.buildError != nil {
+					return skillprovenance.Record{}, tc.buildError
+				}
+				return skillprovenance.Record{Name: name, Version: version, Source: source, Digest: "sha256:test", DigestScope: skillprovenance.DigestScope}, nil
+			})
+			testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) {
+				if tc.homeError != nil {
+					return "", tc.homeError
+				}
+				return home, nil
+			})
+			executed := 0
+			testseam.Swap(t, &skillSetupExecutePlan, func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) {
+				executed++
+				return 1, 0, nil
+			})
+
+			cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+			if tc.filtered {
+				if err := cmd.Flags().Set("skill", "a"); err != nil {
+					t.Fatal(err)
+				}
+			}
+			err := cmd.RunE(cmd, nil)
+			if err == nil || executed != 0 {
+				t.Fatalf("preflight = err %v, executed %d", err, executed)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupPartialInstallDoesNotWriteState(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupResolveMode, func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil })
+	testseam.Swap(t, &skillSetupResolveSource, func(string, string) (string, func(), error) { return "source", func() {}, nil })
+	testseam.Swap(t, &skillSetupResolveTargets, func(string, string) ([]string, error) {
+		return []string{filepath.Join(home, "skills")}, nil
+	})
+	testseam.Swap(t, &skillSetupListMulti, func(string) ([]string, error) {
+		return []string{"dingtalk-a", "dingtalk-b", "dingtalk-shared"}, nil
+	})
+	testseam.Swap(t, &skillSetupFilterMulti, filterMultiSkillNames)
+	testseam.Swap(t, &skillSetupBuildProvenance, func(name, _ string, version, source string) (skillprovenance.Record, error) {
+		return skillprovenance.Record{Name: name, Version: version, Source: source, Digest: "sha256:test", DigestScope: skillprovenance.DigestScope}, nil
+	})
+	testseam.Swap(t, &skillSetupExecutePlan, func(*skillSetupPlan, io.Writer, io.Writer) (int, int, error) {
+		return 2, 1, nil
+	})
+
+	writes := 0
+	testseam.Swap(t, &skillSetupWriteState, func(string, skillstate.State) error {
+		writes++
+		return nil
+	})
+	cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	err := cmd.RunE(cmd, nil)
+	if err == nil || !strings.Contains(err.Error(), "Skill 安装不完整") || !strings.Contains(err.Error(), "skipped=1") {
+		t.Fatalf("partial setup error = %v", err)
+	}
+	if writes != 0 {
+		t.Fatalf("partial setup wrote %d complete state snapshot(s)", writes)
+	}
+}
@@ -9,6 +9,10 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillprovenance"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 )

 func TestSkillSetupCommandRegistered(t *testing.T) {
@@ -25,6 +29,189 @@ func TestSkillSetupCommandRegistered(t *testing.T) {
 	}
 }

+// TestCrossPlatformCoverageSkillSetupExamplesDoNotBypassConfirmation guards
+// the P1 review finding: copyable examples must preview or enter the normal
+// confirmation path, never carry the scripting-only confirmation bypass.
+func TestCrossPlatformCoverageSkillSetupExamplesDoNotBypassConfirmation(t *testing.T) {
+	cmd := newSkillSetupCommand()
+	var examples []string
+	for _, line := range strings.Split(cmd.Example, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		examples = append(examples, line)
+		if strings.Contains(line, "--yes") {
+			t.Fatalf("skill setup example bypasses confirmation: %q", line)
+		}
+	}
+	if len(examples) != 2 || !strings.Contains(examples[0], "--dry-run") || strings.Contains(examples[1], "--dry-run") {
+		t.Fatalf("examples must show preview then interactive confirmation: %v", examples)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupHelpDescribesFullUpgradeRefresh(t *testing.T) {
+	help := newSkillSetupCommand().Long
+	for _, want := range []string{"每次 dws upgrade", "全量覆盖预制 skill", "本地删除", "会在升级时恢复"} {
+		if !strings.Contains(help, want) {
+			t.Fatalf("skill setup help missing full-refresh contract %q:\n%s", want, help)
+		}
+	}
+	for _, stale := range []string{"跳过本地已删除", "--force 恢复全量"} {
+		if strings.Contains(help, stale) {
+			t.Fatalf("skill setup help still advertises retired incremental behavior %q:\n%s", stale, help)
+		}
+	}
+}
+
+// TestCrossPlatformCoverageSkillSetupDeclinedConfirmationNeverRemoves verifies
+// the destructive half of the setup contract: when the user declines the
+// confirmation prompt, nothing is installed and nothing is removed (neither
+// the opposite-mode leftovers nor stale skills). Confirming must then run the
+// exact cleanup previewed earlier: leftovers are backed up to
+// ~/.dws/skill-backups/ before they disappear.
+func TestCrossPlatformCoverageSkillSetupDeclinedConfirmationNeverRemoves(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+
+	multiSrc := writeMultiSkillSource(t, []string{"dingtalk-aitable", "dingtalk-calendar"})
+	agentHome := filepath.Join(home, ".claude", "skills")
+
+	// Opposite-mode leftover (mono dws/) plus a stale multi skill the full
+	// install would clean; both must survive a declined confirmation.
+	for _, leftover := range []string{filepath.Join(agentHome, "dws"), filepath.Join(agentHome, "dingtalk-stale")} {
+		if err := os.MkdirAll(leftover, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(leftover, "SKILL.md"), []byte("keep-me"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useManagedSkillNames(t, "dingtalk-stale")
+
+	oldConfirm := skillSetupConfirmPlan
+	t.Cleanup(func() { skillSetupConfirmPlan = oldConfirm })
+
+	// Declined confirmation: nothing may change on disk.
+	skillSetupConfirmPlan = func(io.Writer, *skillSetupPlan) (bool, error) { return false, nil }
+	cmd := newSkillSetupCommand()
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{"--mode", "multi", "--target", "claude", "--source", multiSrc})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("declined setup should succeed as a no-op: %v (%s)", err, errOut.String())
+	}
+	if !strings.Contains(out.String(), "已取消") {
+		t.Fatalf("expected cancellation notice, got %q", out.String())
+	}
+	for _, survivor := range []string{filepath.Join(agentHome, "dws"), filepath.Join(agentHome, "dingtalk-stale")} {
+		if _, err := os.Stat(filepath.Join(survivor, "SKILL.md")); err != nil {
+			t.Fatalf("declined confirmation removed %s: %v", survivor, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(agentHome, "dingtalk-aitable")); !os.IsNotExist(err) {
+		t.Fatalf("declined confirmation must not install either: %v", err)
+	}
+
+	// Confirmed: the previewed victims are backed up + removed, bundle skills land.
+	skillSetupConfirmPlan = func(io.Writer, *skillSetupPlan) (bool, error) { return true, nil }
+	out.Reset()
+	errOut.Reset()
+	cmd = newSkillSetupCommand()
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetArgs([]string{"--mode", "multi", "--target", "claude", "--source", multiSrc})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("confirmed setup failed: %v (%s)", err, errOut.String())
+	}
+	for _, gone := range []string{filepath.Join(agentHome, "dws"), filepath.Join(agentHome, "dingtalk-stale")} {
+		if _, err := os.Stat(gone); !os.IsNotExist(err) {
+			t.Fatalf("confirmed setup should remove %s (stat err=%v)", gone, err)
+		}
+	}
+	for _, n := range []string{"dingtalk-aitable", "dingtalk-calendar"} {
+		if _, err := os.Stat(filepath.Join(agentHome, n, "SKILL.md")); err != nil {
+			t.Fatalf("confirmed setup missing %s: %v", n, err)
+		}
+	}
+	// Every removal went through the reversible backup path, not a hard delete.
+	backupRoot := filepath.Join(home, ".dws", "skill-backups")
+	entries, err := os.ReadDir(backupRoot)
+	if err != nil || len(entries) == 0 {
+		t.Fatalf("confirmed setup must preserve victims under %s (entries=%v, err=%v)", backupRoot, entries, err)
+	}
+	if !strings.Contains(out.String(), "已备份并清理对面模式残留") || !strings.Contains(out.String(), "已备份并清理过期 skill") {
+		t.Fatalf("expected backup-and-remove log lines, got %q", out.String())
+	}
+}
+
+// TestCrossPlatformCoverageSkillSetupNonInteractiveRequiresYes pins the real
+// non-TTY safety boundary: an explicit mode alone is not consent to move
+// directories. The same command with --yes performs the previewed backup and
+// installation.
+func TestCrossPlatformCoverageSkillSetupNonInteractiveRequiresYes(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+	oldInteractive := skillSetupInteractive
+	skillSetupInteractive = func() bool { return false }
+	t.Cleanup(func() { skillSetupInteractive = oldInteractive })
+
+	multiSrc := writeMultiSkillSource(t, []string{"dingtalk-aitable"})
+	agentHome := filepath.Join(home, ".claude", "skills")
+	mono := filepath.Join(agentHome, "dws")
+	if err := os.MkdirAll(mono, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mono, "SKILL.md"), []byte("keep-me"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	run := func(extra ...string) error {
+		cmd := newSkillSetupCommand()
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
+		args := []string{"--mode", "multi", "--target", "claude", "--source", multiSrc}
+		cmd.SetArgs(append(args, extra...))
+		return cmd.Execute()
+	}
+
+	if err := run(); err == nil || !strings.Contains(err.Error(), "--yes") {
+		t.Fatalf("non-interactive setup error = %v, want explicit --yes requirement", err)
+	}
+	if data, err := os.ReadFile(filepath.Join(mono, "SKILL.md")); err != nil || string(data) != "keep-me" {
+		t.Fatalf("unconfirmed setup changed mono (data=%q, err=%v)", string(data), err)
+	}
+	if _, err := os.Stat(filepath.Join(agentHome, "dingtalk-aitable")); !os.IsNotExist(err) {
+		t.Fatalf("unconfirmed setup installed multi, stat err=%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".dws", "skill-backups")); !os.IsNotExist(err) {
+		t.Fatalf("unconfirmed setup created backup state, stat err=%v", err)
+	}
+
+	if err := run("--yes"); err != nil {
+		t.Fatalf("explicitly confirmed setup failed: %v", err)
+	}
+	if _, err := os.Stat(mono); !os.IsNotExist(err) {
+		t.Fatalf("confirmed setup kept mono, stat err=%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(agentHome, "dingtalk-aitable", "SKILL.md")); err != nil {
+		t.Fatalf("confirmed setup did not install multi: %v", err)
+	}
+	backupFound := false
+	_ = filepath.Walk(filepath.Join(home, ".dws", "skill-backups"), func(path string, info os.FileInfo, walkErr error) error {
+		if walkErr == nil && info != nil && !info.IsDir() && info.Name() == "SKILL.md" {
+			if data, readErr := os.ReadFile(path); readErr == nil && string(data) == "keep-me" {
+				backupFound = true
+			}
+		}
+		return nil
+	})
+	if !backupFound {
+		t.Fatal("confirmed setup did not back up mono")
+	}
+}
+
 func TestResolveSkillSetupModeFlagDirect(t *testing.T) {
 	got, err := resolveSkillSetupMode("mono", true, &bytes.Buffer{})
 	if err != nil || got != skillSetupModeMono {
@@ -39,14 +226,14 @@ func TestResolveSkillSetupModeFlagDirect(t *testing.T) {
 	}
 }

-func TestResolveSkillSetupModeNonInteractiveDefaultsMono(t *testing.T) {
+func TestResolveSkillSetupModeNonInteractiveDefaultsMulti(t *testing.T) {
 	var buf bytes.Buffer
 	got, err := resolveSkillSetupMode("", true, &buf)
-	if err != nil || got != skillSetupModeMono {
-		t.Fatalf("non-interactive empty mode should default to mono, got %q err=%v", got, err)
+	if err != nil || got != skillSetupModeMulti {
+		t.Fatalf("non-interactive empty mode should default to multi, got %q err=%v", got, err)
 	}
-	if !strings.Contains(buf.String(), "mono") {
-		t.Fatalf("expected output to mention mono fallback, got %q", buf.String())
+	if !strings.Contains(buf.String(), "multi") {
+		t.Fatalf("expected output to mention multi fallback, got %q", buf.String())
 	}
 }

@@ -143,7 +330,7 @@ func TestResolveSkillSetupTargetsMultiOmitsDwsTail(t *testing.T) {
 	}
 }

-func TestInstallSkillToHomesEndToEnd(t *testing.T) {
+func TestCrossPlatformCoverageInstallSkillToHomesEndToEnd(t *testing.T) {
 	src := t.TempDir()
 	if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("# test"), 0o644); err != nil {
 		t.Fatal(err)
@@ -205,7 +392,7 @@ func writeMultiSkillSource(t *testing.T, names []string) string {
 	return root
 }

-func TestInstallMultiSkillToHomes(t *testing.T) {
+func TestCrossPlatformCoverageInstallMultiSkillToHomes(t *testing.T) {
 	names := []string{"dingtalk-aitable", "dingtalk-calendar", "dingtalk-doc"}
 	src := writeMultiSkillSource(t, names)

@@ -221,7 +408,7 @@ func TestInstallMultiSkillToHomes(t *testing.T) {
 	dst2 := filepath.Join(t.TempDir(), ".cursor", "skills")

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, got, []string{dst1, dst2}, &stdout, &stderr)
+	installed, skipped, err := installMultiSkillToHomes(src, got, []string{dst1, dst2}, &stdout, &stderr, false)
 	if err != nil {
 		t.Fatalf("installMultiSkillToHomes err: %v", err)
 	}
@@ -245,12 +432,14 @@ func TestInstallMultiSkillToHomes(t *testing.T) {
 	}
 }

-func TestSkillSetupMutualExclusion(t *testing.T) {
+func TestCrossPlatformCoverageSkillSetupMutualExclusion(t *testing.T) {
 	names := []string{"dingtalk-aitable", "dingtalk-calendar"}
 	src := writeMultiSkillSource(t, names)

 	// Simulate a pre-existing mono install under <agent-home>/dws/
-	agentHome := filepath.Join(t.TempDir(), ".claude", "skills")
+	homeRoot := t.TempDir()
+	setTestHome(t, homeRoot)
+	agentHome := filepath.Join(homeRoot, ".claude", "skills")
 	monoLeftover := filepath.Join(agentHome, "dws")
 	if err := os.MkdirAll(filepath.Join(monoLeftover, "references"), 0o755); err != nil {
 		t.Fatal(err)
@@ -265,13 +454,16 @@ func TestSkillSetupMutualExclusion(t *testing.T) {
 	}

 	// Confirm mutualExclusionVictims sees the leftover
-	victims := mutualExclusionVictims(agentHome, skillSetupModeMulti)
+	victims, vErr := mutualExclusionVictims(agentHome, skillSetupModeMulti)
+	if vErr != nil {
+		t.Fatalf("mutualExclusionVictims err: %v", vErr)
+	}
 	if len(victims) != 1 || victims[0] != monoLeftover {
 		t.Fatalf("expected victims=[%s], got %v", monoLeftover, victims)
 	}

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr)
+	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr, false)
 	if err != nil {
 		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
 	}
@@ -290,7 +482,7 @@ func TestSkillSetupMutualExclusion(t *testing.T) {
 		}
 	}
 	// the cleanup line should appear in stdout (best-effort observability)
-	if !strings.Contains(stdout.String(), "已清理对面模式残留") {
+	if !strings.Contains(stdout.String(), "已备份并清理对面模式残留") {
 		t.Fatalf("expected cleanup log line, got stdout=%q", stdout.String())
 	}

@@ -318,11 +510,48 @@ func TestSkillSetupMutualExclusion(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(monoDest, "SKILL.md")); err != nil {
 		t.Fatalf("mono SKILL.md missing: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "已清理对面模式残留") {
+	if !strings.Contains(stdout.String(), "已备份并清理对面模式残留") {
 		t.Fatalf("expected cleanup log line on mono install, got stdout=%q", stdout.String())
 	}
 }

+func TestCrossPlatformCoverageSkillSetupMonoPreservesUnregisteredDingtalkSkill(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+	base := filepath.Join(home, ".agents", "skills")
+	managed := filepath.Join(base, "dingtalk-managed-old")
+	legacyOfficial := filepath.Join(base, "dingtalk-aitable")
+	custom := filepath.Join(base, "dingtalk-custom")
+	for _, dir := range []string{managed, legacyOfficial, custom} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(filepath.Base(dir)), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useManagedSkillNames(t, filepath.Base(managed))
+
+	monoSrc := t.TempDir()
+	if err := os.WriteFile(filepath.Join(monoSrc, "SKILL.md"), []byte("mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installSkillToHomes(monoSrc, []string{filepath.Join(base, "dws")}, &out, &errOut)
+	if err != nil || installed != 1 || skipped != 0 {
+		t.Fatalf("mono install = (%d, %d, %v), stderr=%s", installed, skipped, err, errOut.String())
+	}
+	if _, err := os.Stat(managed); !os.IsNotExist(err) {
+		t.Fatalf("centrally managed DWS multi Skill must be removed during mono switch: %v", err)
+	}
+	if _, err := os.Stat(legacyOfficial); !os.IsNotExist(err) {
+		t.Fatalf("pre-state official multi Skill must be removed during mono switch: %v", err)
+	}
+	if got, err := os.ReadFile(filepath.Join(custom, "SKILL.md")); err != nil || string(got) != "dingtalk-custom" {
+		t.Fatalf("unregistered market/user dingtalk-* Skill changed: data=%q err=%v", got, err)
+	}
+}
+
 // TestSkillSourceCandidatesIncludesUserCache verifies that the user-level
 // cache populated by install.sh / install.ps1 / npm install.js is part of the
 // fallback candidate list, so `dws skill setup` can find a source on a fresh
@@ -464,10 +693,11 @@ func TestFilterMultiSkillNames(t *testing.T) {
 // TestSkillSetupMultiAdditivePreservesSiblings verifies the key UX promise of
 // `dws skill setup --mode multi -s aitable`: installing a subset must NOT
 // touch already-installed dingtalk-* siblings (additive semantics).
-func TestSkillSetupMultiAdditivePreservesSiblings(t *testing.T) {
+func TestCrossPlatformCoverageSkillSetupMultiAdditivePreservesSiblings(t *testing.T) {
 	src := writeMultiSkillSource(t, []string{
 		"dingtalk-aitable", "dingtalk-calendar", "dingtalk-doc",
 	})
+	setTestHome(t, t.TempDir())
 	agentHome := filepath.Join(t.TempDir(), ".claude", "skills")

 	// Pretend the user already installed two dingtalk-* skills earlier.
@@ -493,7 +723,7 @@ func TestSkillSetupMultiAdditivePreservesSiblings(t *testing.T) {
 	}

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, filtered, []string{agentHome}, &stdout, &stderr)
+	installed, skipped, err := installMultiSkillToHomes(src, filtered, []string{agentHome}, &stdout, &stderr, true)
 	if err != nil {
 		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
 	}
@@ -561,6 +791,135 @@ func TestResolveSkillSetupSourceMultiFinds(t *testing.T) {
 	}
 }

+// TestCrossPlatformCoverageSkillSetupMultiFullInstallCleansStale verifies that a full (unfiltered)
+// multi install removes stale dingtalk-* / dws-shared directories that are no
+// longer part of the bundle, matching install.sh / install.js / upgrade paths.
+// The additive counterpart (filtered install) is covered by
+// TestCrossPlatformCoverageSkillSetupMultiAdditivePreservesSiblings.
+func TestCrossPlatformCoverageSkillSetupMultiFullInstallCleansStale(t *testing.T) {
+	names := []string{"dingtalk-aitable"}
+	src := writeMultiSkillSource(t, names)
+
+	homeRoot := t.TempDir()
+	setTestHome(t, homeRoot)
+	agentHome := filepath.Join(homeRoot, ".claude", "skills")
+	// Stale multi skills absent from the bundle, plus a non-DWS dir that must survive.
+	for _, n := range []string{"dingtalk-stale", "dws-shared", "other-skill"} {
+		dir := filepath.Join(agentHome, n)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("OLD "+n), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	useManagedSkillNames(t, "dingtalk-stale")
+	custom := filepath.Join(agentHome, "dingtalk-custom")
+	if err := os.MkdirAll(custom, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(custom, "SKILL.md"), []byte("market skill"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr, false)
+	if err != nil {
+		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
+	}
+	if installed != 1 || skipped != 0 {
+		t.Fatalf("expected installed=1 skipped=0, got %d/%d", installed, skipped)
+	}
+
+	if _, err := os.Stat(filepath.Join(agentHome, "dingtalk-aitable", "SKILL.md")); err != nil {
+		t.Errorf("missing installed skill: %v", err)
+	}
+	for _, stale := range []string{"dingtalk-stale", "dws-shared"} {
+		if _, err := os.Stat(filepath.Join(agentHome, stale)); !os.IsNotExist(err) {
+			t.Errorf("stale %q should be removed by a full multi install (stat err=%v)", stale, err)
+		}
+	}
+	body, err := os.ReadFile(filepath.Join(agentHome, "other-skill", "SKILL.md"))
+	if err != nil || !strings.HasPrefix(string(body), "OLD ") {
+		t.Errorf("non-DWS dir must be preserved (body=%q, err=%v)", string(body), err)
+	}
+	if body, err := os.ReadFile(filepath.Join(custom, "SKILL.md")); err != nil || string(body) != "market skill" {
+		t.Errorf("unregistered market/user dingtalk-* dir must survive (body=%q, err=%v)", string(body), err)
+	}
+	if !strings.Contains(stdout.String(), "已备份并清理过期 skill") {
+		t.Errorf("expected stale cleanup log line, got stdout=%q", stdout.String())
+	}
+}
+
+// TestSkillSetupMutualExclusionScanWarning verifies that a victim-scan failure
+// surfaces as an errOut warning instead of silently skipping cleanup.
+func TestCrossPlatformCoverageSkillSetupMutualExclusionScanWarning(t *testing.T) {
+	oldReadDir := skillSetupReadDir
+	t.Cleanup(func() { skillSetupReadDir = oldReadDir })
+	scanFail := errors.New("scan boom")
+	skillSetupReadDir = func(string) ([]os.DirEntry, error) { return nil, scanFail }
+
+	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
+	if _, err := mutualExclusionVictims(monoDest, skillSetupModeMono); err == nil {
+		t.Fatal("scan failure should surface as an error")
+	}
+
+	var out, errOut bytes.Buffer
+	cleanupMutualExclusion(monoDest, skillSetupModeMono, &out, &errOut)
+	if !strings.Contains(errOut.String(), "互斥清理扫描失败") {
+		t.Fatalf("expected scan warning on errOut, got %q", errOut.String())
+	}
+}
+
+// TestRunSkillSetupThreadsFilteredFlag verifies runSkillSetup tells
+// installMultiSkillToHomes whether -s/--skill or -x/--exclude was used, so a
+// full install cleans stale siblings while a filtered install stays additive.
+func TestRunSkillSetupThreadsFilteredFlag(t *testing.T) {
+	oldMode, oldSource, oldTargets := skillSetupResolveMode, skillSetupResolveSource, skillSetupResolveTargets
+	oldList, oldFilter, oldExecute := skillSetupListMulti, skillSetupFilterMulti, skillSetupExecutePlan
+	t.Cleanup(func() {
+		skillSetupResolveMode, skillSetupResolveSource, skillSetupResolveTargets = oldMode, oldSource, oldTargets
+		skillSetupListMulti, skillSetupFilterMulti, skillSetupExecutePlan = oldList, oldFilter, oldExecute
+	})
+
+	skillSetupResolveMode = func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil }
+	skillSetupResolveSource = func(string, string) (string, func(), error) { return "source", func() {}, nil }
+	skillSetupResolveTargets = func(string, string) ([]string, error) {
+		return []string{filepath.Join(t.TempDir(), "dest")}, nil
+	}
+	skillSetupListMulti = func(string) ([]string, error) { return []string{"dingtalk-aitable", "dws-shared"}, nil }
+	skillSetupFilterMulti = filterMultiSkillNames
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupBuildProvenance, func(name, _ string, version, source string) (skillprovenance.Record, error) {
+		return skillprovenance.Record{Name: name, Version: version, Source: source, Digest: "sha256:test", DigestScope: skillprovenance.DigestScope}, nil
+	})
+	testseam.Swap(t, &skillSetupWriteState, func(string, skillstate.State) error { return nil })
+	var gotFiltered []bool
+	skillSetupExecutePlan = func(plan *skillSetupPlan, _, _ io.Writer) (int, int, error) {
+		gotFiltered = append(gotFiltered, plan.Filtered)
+		return 1, 0, nil
+	}
+
+	// Full install (no -s/-x): filtered must be false.
+	cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("full install run err: %v", err)
+	}
+
+	// Filtered install: filtered must be true.
+	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
+	if err := cmd.Flags().Set("skill", "aitable"); err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("filtered install run err: %v", err)
+	}
+
+	if len(gotFiltered) != 2 || gotFiltered[0] != false || gotFiltered[1] != true {
+		t.Fatalf("filtered flag threading = %v, want [false true]", gotFiltered)
+	}
+}
 func executeMultiSkillSetupTest(t *testing.T, src string, dests []string, args ...string) (string, string, error) {
 	t.Helper()
 	originalTargets := skillSetupResolveTargets
@@ -633,7 +992,7 @@ func assertNoEventMigrationStages(t *testing.T, agentHome string) {
 	}
 }

-func TestSkillSetupSelectiveEventMigratesOnlyFoldedTargets(t *testing.T) {
+func TestCrossPlatformCoverageSkillSetupSelectiveEventMigratesOnlyFoldedTargets(t *testing.T) {
 	src := writeMultiSkillSource(t, []string{
 		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
 	})
@@ -653,13 +1012,10 @@ func TestSkillSetupSelectiveEventMigratesOnlyFoldedTargets(t *testing.T) {
 		t.Fatal(err)
 	}

-	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{freshHome, foldedHome}, "--skill", "event")
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{freshHome, foldedHome}, "--skill", "event", "--yes")
 	if err != nil {
 		t.Fatalf("selective event setup failed: %v\nstderr=%s\nstdout=%s", err, stderr, stdout)
 	}
-	if !strings.Contains(stdout, "迁移伴侣") || !strings.Contains(stdout, foldedHome) {
-		t.Fatalf("confirmation output should expose folded misc migration: %s", stdout)
-	}
 	if !strings.Contains(stdout, "重新加载 Skills") {
 		t.Fatalf("completion should tell the user to reload skills: %s", stdout)
 	}
@@ -703,7 +1059,7 @@ func TestSkillSetupSelectiveEventMigratesOnlyFoldedTargets(t *testing.T) {
 	}
 }

-func TestSkillSetupEventMigrationDryRunAndExplicitExclude(t *testing.T) {
+func TestCrossPlatformCoverageSkillSetupEventMigrationDryRunAndExplicitExclude(t *testing.T) {
 	src := writeMultiSkillSource(t, []string{
 		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
 	})
@@ -854,7 +1210,7 @@ func TestSkillSetupSelectiveEventPreservesFoldedMiscAfterPrimarySkip(t *testing.
 	originalInstallMulti := skillSetupInstallMulti
 	t.Cleanup(func() { skillSetupInstallMulti = originalInstallMulti })
 	calls := 0
-	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) {
 		calls++
 		if calls > 1 {
 			t.Fatal("misc migration companion ran after a primary install skip")
@@ -891,7 +1247,7 @@ func TestSkillSetupFreshTargetFailureDoesNotTouchFoldedPair(t *testing.T) {
 	originalInstallMulti := skillSetupInstallMulti
 	t.Cleanup(func() { skillSetupInstallMulti = originalInstallMulti })
 	calls := 0
-	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) {
 		calls++
 		if calls > 1 {
 			t.Fatal("folded target prerequisites ran after fresh target failure")
@@ -44,6 +44,10 @@ import (
 // test binary never launches a page on the developer's machine; tests that
 // need to assert the URL can still replace openBrowserFunc locally.
 func TestMain(m *testing.M) {
+	if code, ok := runRuntimeTokenDetachedE2EChild(); ok {
+		os.Exit(code)
+	}
+
 	tmpDir, err := os.MkdirTemp("", "dws-app-test-keychain-")
 	if err != nil {
 		panic("create test keychain tempdir: " + err.Error())
@@ -57,9 +57,9 @@ var (
 	downloadUpgradeProgress = upgrade.DownloadWithProgress
 	extractUpgradeZip       = upgrade.ExtractZip
 	findExtractedBinary     = upgrade.FindBinaryInDir
-	locateUpgradeSkill      = upgrade.LocateSkillMD
+	locateUpgradeSkill      = upgrade.LocateSkillsRoot
 	replaceUpgradeSelf      = upgrade.ReplaceSelf
-	installUpgradeSkills    = upgrade.UpgradeSkillLocations
+	installUpgradeSkills    = upgrade.UpgradeSkillLocationsWithOptions
 	upgradeMkdirTemp        = os.MkdirTemp
 	upgradeRemoveAll        = os.RemoveAll
 	upgradeReadFile         = os.ReadFile
@@ -99,7 +99,8 @@ func newUpgradeCommand() *cobra.Command {
 		Long: `检查并升级 DWS CLI 到最新版本。

 自动下载匹配当前平台的二进制文件和技能包，通过 SHA256 校验后原子替换。
-升级前会自动备份当前版本，可通过 --rollback 回滚。`,
+升级前会自动备份当前版本，可通过 --rollback 回滚。
+每次升级都会按新版本官方清单全量覆盖预制 Skill；--force 仅额外允许重装当前版本。`,
 		Example: `  dws upgrade                    # 交互式升级到最新版本
  dws upgrade --check            # 仅检查是否有新版本
  dws upgrade --list             # 列出最近版本
@@ -107,6 +108,7 @@ func newUpgradeCommand() *cobra.Command {
  dws upgrade --beta             # 升级到最新 beta 预发布版本
  dws upgrade --version v1.0.7   # 升级到指定正式版本
  dws upgrade --version v1.0.8-beta.1  # 升级到指定 beta 版本
+  dws upgrade --force           # 即使已是最新版本也重装当前版本
  dws upgrade --rollback         # 回滚到上一版本
  dws upgrade --dry-run          # 仅预览升级步骤，不实际执行
  dws upgrade -y                 # 跳过确认直接升级`,
@@ -158,7 +160,7 @@ func newUpgradeCommand() *cobra.Command {
 	cmd.Flags().StringVar(&flagVersion, "version", "", "升级到指定版本")
 	cmd.Flags().BoolVar(&flagBeta, "beta", false, "使用最新 beta 预发布版本（默认使用正式 release）")
 	cmd.Flags().BoolVar(&flagRollback, "rollback", false, "回滚到上一版本")
-	cmd.Flags().BoolVar(&flagForce, "force", false, "强制重新安装当前版本")
+	cmd.Flags().BoolVar(&flagForce, "force", false, "即使已是最新版本也强制重新安装当前版本")
 	cmd.Flags().BoolVar(&flagSkipSkills, "skip-skills", false, "跳过技能包更新")

 	return cmd
@@ -596,7 +598,9 @@ func runUpgrade(ctx context.Context, opts upgradeOptions) error {
 	}

 	if hasSkills {
-		result, installErr := installUpgradeSkills(skillSrc)
+		result, installErr := installUpgradeSkills(skillSrc, upgrade.SkillUpgradeOptions{
+			Version: release.Version,
+		})
 		if installErr != nil {
 			fmt.Printf(" %s\n", ugRed("✗"))
 			return fmt.Errorf("技能包安装失败: %w", installErr)
@@ -285,7 +285,7 @@ func TestCrossPlatformCoverageRunUpgradeAllStagesCoverage(t *testing.T) {
 			}
 			return nil
 		}
-		installUpgradeSkills = func(string) (*upgradepkg.SkillUpgradeResult, error) {
+		installUpgradeSkills = func(string, upgradepkg.SkillUpgradeOptions) (*upgradepkg.SkillUpgradeResult, error) {
 			if stage == "install" {
 				return nil, fail
 			}
@@ -0,0 +1,156 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillprovenance"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
+)
+
+// TestCrossPlatformCoverageUpgradeSkillLocationsMonoSeedMigratesToMulti is the fake-HOME E2E for
+// the 2026-08-05 owner decision: upgrade is not disk-sticky. Seeding a mono
+// layout then calling UpgradeSkillLocations with a multi bundle must install
+// product skills, remove dws/, and leave non-DWS dirs alone.
+func TestCrossPlatformCoverageUpgradeSkillLocationsMonoSeedMigratesToMulti(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+	upgrade.SwapUserHomeDirForTest(t, func() (string, error) { return home, nil })
+
+	agentsBase := filepath.Join(home, ".agents", "skills")
+	if err := os.MkdirAll(filepath.Join(agentsBase, "dws"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(agentsBase, "dws", "SKILL.md"), []byte("old mono"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(agentsBase, "other-skill"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(agentsBase, "other-skill", "SKILL.md"), []byte("not dws"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	extract := t.TempDir()
+	multiRoot := filepath.Join(extract, "multi")
+	for _, name := range []string{"dingtalk-chat", "dws-shared"} {
+		dir := filepath.Join(multiRoot, name)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# "+name), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	result, err := upgrade.UpgradeSkillLocations(multiRoot)
+	if err != nil {
+		t.Fatalf("UpgradeSkillLocations() error = %v", err)
+	}
+	if failed := result.Failed(); len(failed) != 0 {
+		t.Fatalf("expected 0 failures, got %v", failed)
+	}
+	if _, err := os.Stat(filepath.Join(agentsBase, "dws")); !os.IsNotExist(err) {
+		t.Fatalf("mono leftover dws/ must be gone, stat err=%v", err)
+	}
+	for _, name := range []string{"dingtalk-chat", "dws-shared"} {
+		if _, err := os.Stat(filepath.Join(agentsBase, name, "SKILL.md")); err != nil {
+			t.Errorf("multi skill missing: %s: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(agentsBase, "other-skill", "SKILL.md")); err != nil {
+		t.Errorf("non-DWS dir should be preserved: %v", err)
+	}
+}
+
+// TestUpgradeSkillLocationsRealBundleMigratesMono runs the upgrade path against
+// the repository's actual multi bundle (skills/multi, post-#887 layout with
+// dingtalk-shared). Disk is seeded with a mono install plus the leftovers the
+// rename and stale releases leave behind: a pre-rename dws-shared directory
+// and a dingtalk-* skill no longer in the bundle. All three must be gone after
+// the upgrade, every bundle skill installed, non-DWS dirs untouched, and the
+// ~/.dws/skills/multi cache refreshed.
+func TestCrossPlatformCoverageUpgradeSkillLocationsRealBundleMigratesMono(t *testing.T) {
+	home := t.TempDir()
+	setTestHome(t, home)
+	upgrade.SwapUserHomeDirForTest(t, func() (string, error) { return home, nil })
+
+	bundle := filepath.Join("..", "..", "skills", "multi")
+	entries, err := os.ReadDir(bundle)
+	if err != nil {
+		t.Fatalf("real multi bundle missing: %v", err)
+	}
+	var bundleNames []string
+	for _, e := range entries {
+		if e.IsDir() {
+			bundleNames = append(bundleNames, e.Name())
+		}
+	}
+	if len(bundleNames) == 0 {
+		t.Fatal("real multi bundle is empty")
+	}
+
+	agentsBase := filepath.Join(home, ".agents", "skills")
+	// Mono install plus pre-rename shared and a stale product skill.
+	for _, name := range []string{"dws", "dws-shared", "dingtalk-stale", "other-skill"} {
+		dir := filepath.Join(agentsBase, name)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# "+name), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := skillstate.Write(home, skillstate.State{ManagedSkills: []skillprovenance.Record{{Name: "dingtalk-stale"}}}); err != nil {
+		t.Fatal(err)
+	}
+	custom := filepath.Join(agentsBase, "dingtalk-custom")
+	if err := os.MkdirAll(custom, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(custom, "SKILL.md"), []byte("market skill"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := upgrade.UpgradeSkillLocations(bundle)
+	if err != nil {
+		t.Fatalf("UpgradeSkillLocations() error = %v", err)
+	}
+	if failed := result.Failed(); len(failed) != 0 {
+		t.Fatalf("expected 0 failures, got %v", failed)
+	}
+
+	for _, stale := range []string{"dws", "dws-shared", "dingtalk-stale"} {
+		if _, err := os.Stat(filepath.Join(agentsBase, stale)); !os.IsNotExist(err) {
+			t.Errorf("leftover %q must be removed by the upgrade, stat err=%v", stale, err)
+		}
+	}
+	for _, name := range bundleNames {
+		if _, err := os.Stat(filepath.Join(agentsBase, name, "SKILL.md")); err != nil {
+			t.Errorf("bundle skill %q missing after upgrade: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(agentsBase, "other-skill", "SKILL.md")); err != nil {
+		t.Errorf("non-DWS dir should be preserved: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(custom, "SKILL.md")); err != nil {
+		t.Errorf("unregistered market/user dingtalk-* dir should be preserved: %v", err)
+	}
+	// Shared skill must come from the renamed bundle dir, never the legacy name.
+	if _, err := os.Stat(filepath.Join(agentsBase, "dingtalk-shared", "SKILL.md")); err != nil {
+		t.Errorf("dingtalk-shared missing: %v", err)
+	}
+	// Cache refresh so `dws skill setup` fallbacks stay on the upgraded version.
+	if _, err := os.Stat(filepath.Join(home, ".dws", "skills", "multi", "SKILL.md")); err != nil {
+		// multi cache mirrors the bundle root, which has no top-level SKILL.md;
+		// check a bundle skill inside the cache instead.
+		if _, err2 := os.Stat(filepath.Join(home, ".dws", "skills", "multi", bundleNames[0], "SKILL.md")); err2 != nil {
+			t.Errorf("multi cache not refreshed: %v / %v", err, err2)
+		}
+	}
+}
@@ -18,6 +18,27 @@ import (
 	"github.com/spf13/cobra"
 )

+func TestCrossPlatformCoverageUpgradeHelpDoesNotMakeFullSkillRefreshForceOnly(t *testing.T) {
+	cmd := newUpgradeCommand()
+	force := cmd.Flags().Lookup("force")
+	if force == nil {
+		t.Fatal("upgrade --force flag is missing")
+	}
+	for _, text := range []string{cmd.Example, force.Usage} {
+		if strings.Contains(text, "恢复全部官方 Skill") {
+			t.Fatalf("upgrade help still implies that only --force performs the full Skill refresh: %q", text)
+		}
+	}
+	if !strings.Contains(force.Usage, "已是最新版本") {
+		t.Fatalf("upgrade --force help must explain its remaining purpose, got %q", force.Usage)
+	}
+	for _, want := range []string{"每次升级", "全量覆盖预制 Skill", "--force 仅额外允许重装当前版本"} {
+		if !strings.Contains(cmd.Long, want) {
+			t.Fatalf("upgrade help missing full-refresh contract %q: %s", want, cmd.Long)
+		}
+	}
+}
+
 // --- ensureV ---

 func TestEnsureV(t *testing.T) {
@@ -0,0 +1,40 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package auth
+
+import "testing"
+
+func TestCrossPlatformCoverageResolveProfileMetadataUsesSelectorGrammarAndReturnsCopy(t *testing.T) {
+	cfg := &ProfilesConfig{
+		Version: 3,
+		Profiles: []Profile{
+			{Name: "Historical", CorpID: "corp-1", CorpName: "Example Org"},
+			{Name: "Exact", CorpID: "corp-1", CorpName: "Example Org", UserID: "user-1", UserName: "Example User", ClientID: "client-1"},
+		},
+		OrgCurrentProfiles: map[string]string{"corp-1": "corp-1:user-1"},
+	}
+
+	for _, selector := range []string{"corp-1", "Example Org", "corp-1:Example User", "Example Org:Example User"} {
+		profile, err := ResolveProfileMetadata(cfg, selector)
+		if err != nil {
+			t.Fatalf("ResolveProfileMetadata(%q) error = %v", selector, err)
+		}
+		if profile == nil || profile.UserID != "user-1" || profile.ClientID != "client-1" {
+			t.Fatalf("ResolveProfileMetadata(%q) = %#v", selector, profile)
+		}
+	}
+
+	profile, err := ResolveProfileMetadata(cfg, "corp-1:user-1")
+	if err != nil {
+		t.Fatalf("ResolveProfileMetadata(exact) error = %v", err)
+	}
+	profile.Name = "mutated copy"
+	if cfg.Profiles[1].Name != "Exact" {
+		t.Fatalf("ResolveProfileMetadata returned registry-owned pointer")
+	}
+	if _, err := ResolveProfileMetadata(cfg, "missing"); err == nil {
+		t.Fatal("ResolveProfileMetadata(missing) unexpectedly succeeded")
+	}
+}
@@ -738,6 +738,20 @@ func ResolveProfileWithScope(configDir, selector string) (*Profile, bool, error)
 	return result, exact, err
 }

+// ResolveProfileMetadata applies the public profile-selector grammar to an
+// already-loaded, non-sensitive profiles registry. It performs no migration,
+// keychain access, token loading, or persistence, making it suitable for
+// callers that carry an externally managed bearer credential and need only
+// corp/user/client identity metadata.
+func ResolveProfileMetadata(cfg *ProfilesConfig, selector string) (*Profile, error) {
+	profile, _, err := resolveProfileSelection("", cfg, selector)
+	if err != nil || profile == nil {
+		return nil, err
+	}
+	copy := *profile
+	return &copy, nil
+}
+
 func resolveProfileWithScopeLocked(configDir, selector string) (*Profile, bool, error) {
 	if err := profilesEnsureMigration(configDir); err != nil {
 		return nil, false, err
@@ -71,7 +71,7 @@ func NewSchemaCommand() *cobra.Command {
 		Short: "渐进查看命令 Schema (产品 / 分组 / 工具参数)",
 		Long: `查看当前可运行命令的 Schema 元数据。

-不带参数时列出产品和工具数量；传产品或分组路径逐层展开；传具体工具路径输出扁平参数 Schema（对齐 GWS：parameters 内联 required，键为 CLI flag）。普通 Agent 查询应使用 --compact：它按稳定字段白名单输出选参、约束和安全语义。省略 --compact 的 full leaf 保留参数映射、接口绑定和 provenance，仅用于定向审计；--all 输出全部工具的完整 leaf Schema，用于审计/CI。helper、MCP 与本地 Cobra 命令均须通过 ContractFinal.Identity 声明进入收集的身份集，并从同一声明装配的 ToolSpec 投影；查询不执行服务发现或临时合成第二份 Schema。`,
+不带参数时列出产品和工具数量；传产品或分组路径逐层展开；传具体工具路径输出扁平参数 Schema（对齐 GWS：parameters 内联 required，键为 CLI flag）。普通 Agent 查询应使用 --compact：它按稳定字段白名单输出选参、约束、安全语义和已评审的返回契约。省略 --compact 的 full leaf 保留参数映射、接口绑定和 provenance，仅用于定向审计；--all 输出全部工具的完整 leaf Schema，用于审计/CI。helper、MCP 与本地 Cobra 命令均须通过 ContractFinal.Identity 声明进入收集的身份集，并从同一声明装配的 ToolSpec 投影；查询不执行服务发现或临时合成第二份 Schema。`,
 		Args:              cobra.MaximumNArgs(1),
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -113,7 +113,7 @@ func NewSchemaCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().Bool("all", false, "输出全部工具的完整 leaf Schema（包括参数和约束，用于审计/CI）")
-	cmd.Flags().Bool("compact", false, "按稳定字段白名单输出 Agent 选参、约束和安全语义")
+	cmd.Flags().Bool("compact", false, "按稳定字段白名单输出 Agent 选参、约束、安全语义和返回契约")
 	cmd.Flags().String("cli-path", "", "按 CLI 命令路径查询")
 	return cmd
 }
@@ -14,6 +14,7 @@
 package cli

 import (
+	"encoding/json"
 	"errors"
 	"strings"
 	"testing"
@@ -21,11 +22,13 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/spf13/cobra"
 )

 func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *testing.T) {
 	cmd := &cobra.Command{Use: "create", Short: "s", Long: "l"}
+	output.SetCommandRollout(cmd, output.RolloutUnifiedActive)
 	t.Cleanup(func() { contractfinal.ClearRuntimeContractFinalForTest(cmd) })
 	cmd.Flags().String("mode", "", "usage")
 	runtimeannotate.AnnotateRuntimeFlag(cmd, "mode", "mode", "string", false)
@@ -35,6 +38,10 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 			Effect: "write", Confirmation: "user_required", Idempotency: "none",
 		},
 		DryRun: &contract.DryRunSpec{PreviewKind: contract.DryRunPreviewInvocation},
+		Result: &contract.ResultSpec{
+			Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+			DataSchema: json.RawMessage(`{"type":"object","properties":{"id":{"type":"string","description":"Created object ID"}}}`),
+		},
 		Selection: &contract.SelectionSpec{
 			AgentSummary: "from contract",
 			UseWhen:      []string{"create things"},
@@ -68,6 +75,9 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 	if spec.DryRun == nil || spec.DryRun.PreviewKind != contract.DryRunPreviewInvocation {
 		t.Fatalf("dry_run = %#v", spec.DryRun)
 	}
+	if spec.Result == nil || string(spec.Result.DataSchema) != `{"properties":{"id":{"type":"string","description":"Created object ID"}},"type":"object"}` {
+		t.Fatalf("result = %#v", spec.Result)
+	}
 	if spec.Selection.AgentSummary != "from contract" {
 		t.Fatalf("selection = %#v", spec.Selection)
 	}
@@ -79,6 +89,39 @@ func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalPassThrough(t *tes
 	}
 }

+func TestRuntimeToolSpecHidesUnifiedResultForInactiveRollout(t *testing.T) {
+	for _, state := range []output.RolloutState{output.RolloutLegacyOnly, output.RolloutDualValidate} {
+		t.Run(string(state), func(t *testing.T) {
+			cmd := &cobra.Command{Use: "list"}
+			output.SetCommandRollout(cmd, state)
+			cmd.Flags().String("cursor", "", "cursor")
+			runtimeannotate.AnnotateRuntimeFlag(cmd, "cursor", "cursor", "string", false)
+			final := contract.ContractFinalPayload{
+				Identity: &contract.ToolIdentitySpec{
+					ProductID: "dev", Name: "list_things", CanonicalPath: "dev.list_things",
+					CLIPath: "dev list", PrimaryCLIPath: "dev list",
+				},
+				Result: &contract.ResultSpec{
+					Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+					DataSchema: json.RawMessage(`{"type":"object"}`),
+				},
+				Pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
+			}
+			entry := runtimeSchemaEntry{
+				ProductID: "dev", ToolName: "list_things", CLIName: "list",
+				CLIPath: "dev list", PrimaryCLIPath: "dev list", ProductName: "Dev", Command: cmd,
+			}
+			spec, err := runtimeToolSpecFromContractFinal(entry, final, runtimeSchemaMetadataSources{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if spec.Result != nil || spec.Pagination != nil {
+				t.Fatalf("inactive rollout published result=%#v pagination=%#v", spec.Result, spec.Pagination)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageRuntimeToolSpecFromContractFinalIdentityMismatchFails(t *testing.T) {
 	entry := runtimeSchemaEntry{
 		ProductID:      "dev",
@@ -1059,6 +1059,7 @@ var schemaCompactPayloadKeys = map[string]bool{
 	"effect": true, "risk": true, "confirmation": true, "idempotency": true,
 	"interface_mode": true, "availability": true, "interface_reason": true,
 	"parameters": true, "constraints": true, "positionals": true, "dry_run": true,
+	"result": true, "pagination": true,
 	"examples": true, "use_when": true, "avoid_when": true,
 }

@@ -1074,8 +1075,8 @@ var schemaCompactParamKeys = map[string]bool{

 // stripSchemaPayloadCompact projects a full Schema payload onto the reviewed
 // Agent-view allowlist. Structural product/tool children are projected
-// recursively; constraint, positional and dry-run values are already typed
-// contract data and are retained verbatim.
+// recursively; result, constraint, positional and dry-run values are already
+// typed contract data and are retained verbatim.
 func stripSchemaPayloadCompact(payload map[string]any) map[string]any {
 	if payload == nil {
 		return nil
@@ -78,7 +78,9 @@ var schemaCatalogToolOptionalKeys = []string{
 	"interface_reason",
 	"interface_ref",
 	"metadata_source",
+	"pagination",
 	"positionals",
+	"result",
 }

 var schemaCatalogToolEnums = map[string][]string{
@@ -237,6 +239,37 @@ func validateCatalogToolEntry(toolID string, entry map[string]any, violations *[
 	}

 	validateCatalogInterface(toolID, entry, violations)
+	if result, exists := entry["result"]; exists {
+		if _, ok := result.(map[string]any); !ok {
+			report("field %q must be an object", "result")
+		}
+	}
+	if rawPagination, exists := entry["pagination"]; exists {
+		pagination, ok := rawPagination.(map[string]any)
+		if !ok {
+			report("field %q must be an object", "pagination")
+		} else {
+			want := map[string]string{
+				"kind":                    contract.PaginationKindCursor,
+				"meta_path":               contract.PaginationMetaPath,
+				"endpoint_exhausted_path": contract.PaginationExhaustedPath,
+				"next_token_path":         contract.PaginationNextTokenPath,
+			}
+			for field, expected := range want {
+				if value, _ := pagination[field].(string); value != expected {
+					report("field %q.%s = %q, want %q", "pagination", field, value, expected)
+				}
+			}
+			cursor, _ := pagination["cursor_parameter"].(string)
+			if strings.TrimSpace(cursor) == "" {
+				report("field %q.cursor_parameter must be a non-empty string", "pagination")
+			} else if paramsOK {
+				if _, exists := parameters[cursor]; !exists {
+					report("field %q.cursor_parameter references missing parameter %q", "pagination", cursor)
+				}
+			}
+		}
+	}
 	for paramName, raw := range parameters {
 		param, ok := raw.(map[string]any)
 		if !ok {
@@ -18,6 +18,8 @@ import (
 	"fmt"
 	"strings"
 	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )

 // TestDeliverySchemaCatalogStructure gates the delivered catalog: every tool
@@ -100,6 +102,90 @@ func TestValidateCatalogStructureAcceptsValidEntry(t *testing.T) {
 	}
 }

+func TestValidateCatalogStructureAcceptsOptionalResultObject(t *testing.T) {
+	entry := validCatalogToolEntry()
+	entry["result"] = map[string]any{
+		"outcomes":    []any{"success", "failure"},
+		"data_schema": map[string]any{"type": "object"},
+	}
+	if err := ValidateCatalogStructure(catalogPayload(t, entry)); err != nil {
+		t.Fatalf("ValidateCatalogStructure() error = %v", err)
+	}
+	entry["result"] = "invalid"
+	if err := ValidateCatalogStructure(catalogPayload(t, entry)); err == nil || !strings.Contains(err.Error(), `field "result" must be an object`) {
+		t.Fatalf("invalid result error = %v", err)
+	}
+}
+
+func TestValidateCatalogStructureAcceptsStandalonePagination(t *testing.T) {
+	entry := validCatalogToolEntry()
+	parameters := entry["parameters"].(map[string]any)
+	parameters["cursor"] = map[string]any{
+		"description":      "续页游标",
+		"field_provenance": map[string]any{},
+		"required":         false,
+		"type":             "string",
+	}
+	entry["parameter_count"] = float64(len(parameters))
+	entry["has_parameters"] = true
+	entry["pagination"] = map[string]any{
+		"kind":                    contract.PaginationKindCursor,
+		"cursor_parameter":        "cursor",
+		"meta_path":               contract.PaginationMetaPath,
+		"endpoint_exhausted_path": contract.PaginationExhaustedPath,
+		"next_token_path":         contract.PaginationNextTokenPath,
+	}
+	if err := ValidateCatalogStructure(catalogPayload(t, entry)); err != nil {
+		t.Fatalf("ValidateCatalogStructure() error = %v", err)
+	}
+
+	entry["pagination"].(map[string]any)["next_token_path"] = "data.nextCursor"
+	if err := ValidateCatalogStructure(catalogPayload(t, entry)); err == nil || !strings.Contains(err.Error(), "next_token_path") {
+		t.Fatalf("invalid pagination error = %v", err)
+	}
+}
+
+func TestValidateCatalogStructureRejectsMalformedStandalonePagination(t *testing.T) {
+	validPaginationEntry := func() map[string]any {
+		entry := validCatalogToolEntry()
+		parameters := entry["parameters"].(map[string]any)
+		parameters["cursor"] = map[string]any{
+			"description":      "续页游标",
+			"field_provenance": map[string]any{},
+			"required":         false,
+			"type":             "string",
+		}
+		entry["parameter_count"] = float64(len(parameters))
+		entry["pagination"] = map[string]any{
+			"kind":                    contract.PaginationKindCursor,
+			"cursor_parameter":        "cursor",
+			"meta_path":               contract.PaginationMetaPath,
+			"endpoint_exhausted_path": contract.PaginationExhaustedPath,
+			"next_token_path":         contract.PaginationNextTokenPath,
+		}
+		return entry
+	}
+
+	for _, tc := range []struct {
+		name   string
+		mutate func(map[string]any)
+		want   string
+	}{
+		{"not an object", func(entry map[string]any) { entry["pagination"] = "cursor" }, `field "pagination" must be an object`},
+		{"empty cursor", func(entry map[string]any) { entry["pagination"].(map[string]any)["cursor_parameter"] = " " }, "cursor_parameter must be a non-empty string"},
+		{"unknown cursor", func(entry map[string]any) { entry["pagination"].(map[string]any)["cursor_parameter"] = "page-token" }, "references missing parameter"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			entry := validPaginationEntry()
+			tc.mutate(entry)
+			err := ValidateCatalogStructure(catalogPayload(t, entry))
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("ValidateCatalogStructure() error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageValidateCatalogStructureRejectsViolations(t *testing.T) {
 	cases := []struct {
 		name   string
@@ -1356,6 +1356,8 @@ func TestDeliveryCatalogChatParamDeclsFrom87910880Reviewed(t *testing.T) {
 		{"chat message edit", "conversation-id", "openConversationId", true, ""},
 		{"chat message edit", "msg-id", "openMessageId", true, ""},
 		{"chat message edit", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"},
+		{"chat message send-card", "at-all", "atAll", false, ""},
+		{"chat message send-card", "at-open-dingtalk-ids", "atOpenDingTalkIds", false, "array"},
 		{"chat message update-text-emotion", "msg-id", "openMsgId", true, ""},
 		{"chat message update-text-emotion", "old-emotion-id", "oldEmotionId", true, ""},
 		{"chat category batch-info", "category-ids", "categoryIds", true, "array"},
@@ -33,8 +33,6 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{
 			"auth status",
 			"completion",
 			"config list",
-			"dev connect list",
-			"dev connect restart",
 			"doctor",
 			"plugin build",
 			"plugin config get",
@@ -93,40 +91,9 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{
 			"calendar acl add",
 			"calendar acl delete",
 			"calendar book update",
-			"chat category add-conv",
-			"chat category create",
-			"chat category delete",
-			"chat category remove-conv",
-			"chat category rename",
-			"chat chmod",
-			"chat clear-all-red-point",
-			"chat clear-messages",
-			"chat clear-red-point",
-			"chat data-auth cross-org",
-			"chat group audit-join-validation",
-			"chat group list-all",
-			"chat group list-join-validations",
-			"chat group members list-by-ids",
-			"chat group notice create",
-			"chat group notice edit",
-			"chat group notice get",
-			"chat group notice list",
-			"chat group share-invite",
-			"chat group update-alias",
-			"chat hide",
-			"chat list-all-conversations",
-			"chat mark-read",
-			"chat mark-unread",
-			"chat message list-emotion-replies",
-			"chat message set-top-msg",
-			"chat message unset-top-msg",
-			"chat mute-at-all",
-			"chat mute-red-envelope",
-			"chat text translate",
 			"contact label get",
 			"contact label list",
 			"contact label list-members",
-			"dev app version check-approval",
 			"ding message list",
 			"ding message recall-personal",
 			"ding message receiver-status",
@@ -38,20 +38,33 @@ func init() {
 	registerRequireTogether("calendar.update_calendar_event", "recurrence-type", "recurrence-interval", "recurrence-range-type")
 	registerExclusiveOneOf("chat.search_messages_by_sender", "sender-user-id", "sender-open-dingtalk-id")
 	registerExclusiveOneOf("chat.create_and_send_card", "group", "receiver")
+	RegisterRuntimeSchemaConstraints("chat.chat_permission_grant", RuntimeSchemaConstraints{
+		MutuallyExclusive: [][]string{{"conversation-id", "open-dingtalk-id", "user"}},
+		RequireOneOf:      [][]string{{"conversation-id", "open-dingtalk-id", "user", "permParam"}},
+	})
+	registerExclusiveOneOf("chat.chat_permission_grant_cross_org_data", "target-org-id", "all")
 	registerRequireOneOf("chat.add_emoji_reaction", "conversation-id", "group", "id", "chat")
 	registerRequireOneOf("chat.add_text_emotion", "conversation-id", "group", "id", "chat")
+	registerExclusiveOneOf("chat.clear_conversation_messages", "conversation-id", "id", "chat")
+	registerExclusiveOneOf("chat.clear_conversation_red_point", "conversation-id", "id", "chat")
 	registerRequireOneOf("chat.update_text_emotion", "conversation-id", "group", "id", "chat")
 	registerExclusiveOneOf("chat.get_conversation_info", "group", "user", "open-dingtalk-id")
+	registerExclusiveOneOf("chat.hide_conversation", "conversation-id", "id", "chat")
 	registerExclusiveOneOf("chat.list_conversation_message_v2", "group", "user", "open-dingtalk-id")
 	registerExclusiveOneOf("chat.list_individual_chat_message", "user", "open-dingtalk-id")
+	registerExclusiveOneOf("chat.mark_conversation_unread", "conversation-id", "id", "chat")
+	registerExclusiveOneOf("chat.mark_message_read", "conversation-id", "id", "chat")
 	registerRequireOneOf("chat.remove_emoji_reaction", "conversation-id", "group", "id", "chat")
 	registerRequireOneOf("chat.remove_text_emotion", "conversation-id", "group", "id", "chat")
 	registerRequireOneOf("chat.send_personal_message", "text", "content", "msg-type")
 	registerExclusiveOneOf("chat.send_robot_message", "group", "users")
 	registerRequireOneOf("chat.set_group_member_mute_list", "users", "user")
+	registerExclusiveOneOf("chat.share_group_invite_url", "target", "receiver")
 	registerExclusiveOneOf("chat.transfer_group_owner", "new-owner", "user")
 	registerRequireOneOf("chat.update_conv_member_roles", "users", "user")
+	registerExclusiveOneOf("chat.update_at_all_notification_off", "conversation-id", "id", "chat")
 	registerRequireOneOf("chat.update_notification_off", "conversation-id", "id", "chat")
+	registerExclusiveOneOf("chat.update_red_env_notification_off", "conversation-id", "id", "chat")
 	registerRequireTogether("contact.query_dismission_employee_list", "start", "end")
 	registerRequireOneOf("dev.connect_status", "robot-client-id", "unified-app-id")
 	registerRequireOneOf("dev.connect_stop", "robot-client-id", "unified-app-id")
@@ -60,6 +60,8 @@ type ToolSpec struct {
 	Constraints     RuntimeSchemaConstraints
 	Positionals     []contract.RuntimeSchemaPositional
 	DryRun          *contract.DryRunSpec
+	Result          *contract.ResultSpec
+	Pagination      *contract.PaginationSpec
 	Safety          contract.SafetySpec
 	Interface       contract.InterfaceSpec
 	Selection       contract.SelectionSpec
@@ -133,6 +135,8 @@ type RuntimeToolSpecInput struct {
 	Constraints     RuntimeSchemaConstraints
 	Positionals     []contract.RuntimeSchemaPositional
 	DryRun          *contract.DryRunSpec
+	Result          *contract.ResultSpec
+	Pagination      *contract.PaginationSpec
 	Safety          contract.SafetySpec
 	Interface       contract.InterfaceSpec
 	Selection       contract.SelectionSpec
@@ -538,6 +542,20 @@ func (t ToolSpec) Validate() error {
 			return err
 		}
 	}
+	if t.Result != nil {
+		if _, err := contract.NormalizeResultSpec(t.Result, id.CanonicalPath); err != nil {
+			return err
+		}
+	}
+	if t.Pagination != nil {
+		pagination, err := contract.NormalizePaginationSpec(t.Pagination, id.CanonicalPath)
+		if err != nil {
+			return err
+		}
+		if !seen[pagination.CursorParameter] {
+			return fmt.Errorf("tool %s pagination cursor_parameter %q is not a declared parameter", id.CanonicalPath, pagination.CursorParameter)
+		}
+	}
 	if t.Interface.Mode != "" || t.Interface.Availability != "" || t.Interface.Reason != "" || t.Interface.Ref != nil {
 		if err := t.Interface.Validate(id.CanonicalPath); err != nil {
 			return err
@@ -726,6 +744,18 @@ func (t ToolSpec) normalized() ToolSpec {
 		dryRun.PreviewKind = strings.TrimSpace(dryRun.PreviewKind)
 		out.DryRun = &dryRun
 	}
+	if t.Result != nil {
+		result, err := contract.NormalizeResultSpec(t.Result, id.CanonicalPath)
+		if err == nil {
+			out.Result = result
+		}
+	}
+	if t.Pagination != nil {
+		pagination, err := contract.NormalizePaginationSpec(t.Pagination, id.CanonicalPath)
+		if err == nil {
+			out.Pagination = pagination
+		}
+	}
 	out.Positionals = append([]contract.RuntimeSchemaPositional(nil), t.Positionals...)
 	sort.Slice(out.Positionals, func(i, j int) bool {
 		if out.Positionals[i].Index != out.Positionals[j].Index {
@@ -952,6 +982,14 @@ func (t ToolSpec) ToPayload() (map[string]any, error) {
 		value, _ := typedJSONValue(t.DryRun)
 		payload["dry_run"] = value
 	}
+	if t.Result != nil {
+		value, _ := typedJSONValue(t.Result)
+		payload["result"] = value
+	}
+	if t.Pagination != nil {
+		value, _ := typedJSONValue(t.Pagination)
+		payload["pagination"] = value
+	}
 	applySafetyPayload(payload, t.Safety)
 	applyInterfacePayload(payload, t.Interface)
 	applySelectionPayload(payload, t.Selection, true)
@@ -975,7 +1013,7 @@ func (t ToolSpec) ToSummaryPayload() (map[string]any, error) {
 	}
 	for _, key := range []string{
 		"parameters", "has_parameters", "parameter_count", "constraints",
-		"positionals", "examples", "effect_source", "agent_source_refs",
+		"positionals", "result", "examples", "effect_source", "agent_source_refs",
 		"field_provenance", "path", "source", "product_id", "display", "is_alias",
 	} {
 		delete(payload, key)
@@ -0,0 +1,152 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func TestResultContractModelWireRoundTripAndCompactPolicy(t *testing.T) {
+	result := &contract.ResultSpec{
+		Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeFailure, contract.ResultOutcomeSuccess},
+		DataSchema:     json.RawMessage(`{ "type":"object", "properties":{"items":{"type":"array","description":"Business result records","items":{"type":"object"}}} }`),
+		SensitivePaths: []string{"items.secret", "credential"},
+	}
+	spec, err := ToolSpecFromRuntime(RuntimeToolSpecInput{
+		Identity:   contract.ToolIdentitySpec{ProductID: "dev", Name: "list", CLIName: "list", CLIPath: "dev list"},
+		Parameters: []ParameterSpec{{Name: "cursor", Type: "string"}},
+		Result:     result,
+		Pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
+	})
+	if err != nil {
+		t.Fatalf("ToolSpecFromRuntime() error = %v", err)
+	}
+	if got, want := spec.Result.Outcomes, []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("outcomes = %#v, want %#v", got, want)
+	}
+	result.Outcomes[0] = contract.ResultOutcomePending
+	result.DataSchema[0] = '['
+	if spec.Result.Outcomes[0] != contract.ResultOutcomeSuccess || spec.Result.DataSchema[0] != '{' {
+		t.Fatal("ToolSpec result aliases runtime input")
+	}
+
+	payload, err := spec.ToPayload()
+	if err != nil {
+		t.Fatalf("ToPayload() error = %v", err)
+	}
+	resultPayload, ok := payload["result"].(map[string]any)
+	if !ok || schemaString(resultPayload["data_schema"].(map[string]any)["type"]) != "object" {
+		t.Fatalf("result payload = %#v", payload["result"])
+	}
+	if _, exists := specResultSummary(t, spec)["result"]; exists {
+		t.Fatal("result must remain full-leaf-only")
+	}
+	compactResult, exists := stripSchemaPayloadCompact(payload)["result"].(map[string]any)
+	if !exists {
+		t.Fatal("compact leaf must include the reviewed result contract")
+	}
+	if outcomes, ok := compactResult["outcomes"].([]any); !ok || len(outcomes) != 2 {
+		t.Fatalf("compact result outcomes = %#v", compactResult["outcomes"])
+	}
+	if dataSchema, ok := compactResult["data_schema"].(map[string]any); !ok || schemaString(dataSchema["type"]) != "object" {
+		t.Fatalf("compact result data_schema = %#v", compactResult["data_schema"])
+	}
+	if !reflect.DeepEqual(compactResult, resultPayload) {
+		t.Fatalf("compact result must equal full-leaf result\ncompact: %#v\nfull: %#v", compactResult, resultPayload)
+	}
+	compactPagination, exists := stripSchemaPayloadCompact(payload)["pagination"].(map[string]any)
+	if !exists || schemaString(compactPagination["meta_path"]) != contract.PaginationMetaPath || schemaString(compactPagination["cursor_parameter"]) != "cursor" {
+		t.Fatalf("compact pagination = %#v", compactPagination)
+	}
+
+	wire, err := schemaToolWireFromPayload(payload)
+	if err != nil {
+		t.Fatalf("schemaToolWireFromPayload() error = %v", err)
+	}
+	roundTrip, err := schemaToolSpecFromWire(wire)
+	if err != nil {
+		t.Fatalf("schemaToolSpecFromWire() error = %v", err)
+	}
+	roundTripPayload, err := roundTrip.ToPayload()
+	if err != nil {
+		t.Fatalf("round-trip ToPayload() error = %v", err)
+	}
+	if !schemaJSONEqual(payload, roundTripPayload) {
+		t.Fatalf("result changed across wire round-trip\nfirst: %#v\nround: %#v", payload["result"], roundTripPayload["result"])
+	}
+}
+
+func specResultSummary(t *testing.T, spec ToolSpec) map[string]any {
+	t.Helper()
+	payload, err := spec.ToSummaryPayload()
+	if err != nil {
+		t.Fatalf("ToSummaryPayload() error = %v", err)
+	}
+	return payload
+}
+
+func TestToolWithoutResultKeepsResultAbsent(t *testing.T) {
+	spec, err := ToolSpecFromRuntime(RuntimeToolSpecInput{
+		Identity: contract.ToolIdentitySpec{ProductID: "dev", Name: "legacy", CLIName: "legacy", CLIPath: "dev legacy"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	payload, err := spec.ToPayload()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, exists := payload["result"]; exists {
+		t.Fatal("tool without Result gained a result key")
+	}
+}
+
+func TestToolSpecRejectsInvalidResultInsteadOfDroppingIt(t *testing.T) {
+	_, err := ToolSpecFromRuntime(RuntimeToolSpecInput{
+		Identity: contract.ToolIdentitySpec{ProductID: "dev", Name: "invalid", CLIName: "invalid", CLIPath: "dev invalid"},
+		Result: &contract.ResultSpec{
+			Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+			DataSchema: json.RawMessage(`[]`),
+		},
+	})
+	if err == nil {
+		t.Fatal("invalid result schema was silently dropped")
+	}
+}
+
+func TestToolSpecRejectsInvalidOrUndeclaredPaginationCursor(t *testing.T) {
+	identity := contract.ToolIdentitySpec{ProductID: "dev", Name: "list", CLIName: "list", CLIPath: "dev list"}
+	for _, tc := range []struct {
+		name       string
+		parameters []ParameterSpec
+		pagination *contract.PaginationSpec
+		want       string
+	}{
+		{
+			name:       "invalid pagination declaration",
+			parameters: []ParameterSpec{{Name: "cursor", Type: "string"}},
+			pagination: &contract.PaginationSpec{Kind: "offset", CursorParameter: "cursor"},
+			want:       "unsupported kind",
+		},
+		{
+			name:       "cursor is not a parameter",
+			pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
+			want:       "is not a declared parameter",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := ToolSpecFromRuntime(RuntimeToolSpecInput{
+				Identity: identity, Parameters: tc.parameters, Pagination: tc.pagination,
+			})
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("ToolSpecFromRuntime() error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}
@@ -11,6 +11,7 @@ import (

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -334,6 +335,15 @@ func runtimeToolSpecFromContractFinal(entry runtimeSchemaEntry, final contract.C

 	provenance := contractFinalProvenance(identity, title, description, titleProv, descriptionProv, safety, interfaceSpec, selection, final.DryRun)

+	result, pagination := final.Result, final.Pagination
+	if !output.UsesUnifiedResult(entry.Command) {
+		// ResultSpec describes the unified envelope data value and PaginationSpec
+		// describes meta.pagination. Keep both declarations internal while a
+		// command still emits legacy bytes or only shadow-validates the new
+		// contract; publishing them early makes Schema disagree with runtime.
+		result, pagination = nil, nil
+	}
+
 	return ToolSpecFromRuntime(RuntimeToolSpecInput{
 		Identity:        identity,
 		Display:         entry.ProductName,
@@ -344,6 +354,8 @@ func runtimeToolSpecFromContractFinal(entry runtimeSchemaEntry, final contract.C
 		Constraints:     constraints,
 		Positionals:     positionals,
 		DryRun:          final.DryRun,
+		Result:          result,
+		Pagination:      pagination,
 		Safety:          safety,
 		Interface:       interfaceSpec,
 		Selection:       selection,
@@ -65,6 +65,8 @@ type schemaToolWire struct {
 	Constraints         RuntimeSchemaConstraints            `json:"constraints"`
 	Positionals         []contract.RuntimeSchemaPositional  `json:"positionals"`
 	DryRun              *contract.DryRunSpec                `json:"dry_run"`
+	Result              *contract.ResultSpec                `json:"result"`
+	Pagination          *contract.PaginationSpec            `json:"pagination"`
 	Effect              string                              `json:"effect"`
 	EffectSource        string                              `json:"effect_source"`
 	Risk                string                              `json:"risk"`
@@ -267,6 +269,8 @@ func schemaToolSpecFromWire(wire schemaToolWire) (ToolSpec, error) {
 		Constraints:    wire.Constraints,
 		Positionals:    wire.Positionals,
 		DryRun:         wire.DryRun,
+		Result:         wire.Result,
+		Pagination:     wire.Pagination,
 		Safety: contract.SafetySpec{
 			Effect:       wire.Effect,
 			EffectSource: wire.EffectSource,
@@ -30,6 +30,8 @@ type ContractFinalPayload struct {
 	Parameters  []ParamDecl
 	Safety      *SafetySpec
 	DryRun      *DryRunSpec
+	Result      *ResultSpec
+	Pagination  *PaginationSpec
 	Interface   *InterfaceSpec
 	Selection   *SelectionSpec
 	Identity    *ToolIdentitySpec
@@ -0,0 +1,91 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package contract
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestNormalizeResultSpecCanonicalizesAndCopies(t *testing.T) {
+	in := &ResultSpec{
+		Outcomes:       []ResultOutcome{ResultOutcomeFailure, ResultOutcomeSuccess},
+		DataSchema:     json.RawMessage(`{ "properties": {"items":{"type":"array","description":"Result records","items":{"type":"object"}}}, "type":"object" }`),
+		SensitivePaths: []string{"items.secret", "credential"},
+	}
+
+	got, err := NormalizeResultSpec(in, "dev.list")
+	if err != nil {
+		t.Fatalf("NormalizeResultSpec() error = %v", err)
+	}
+	if want := []ResultOutcome{ResultOutcomeSuccess, ResultOutcomeFailure}; !reflect.DeepEqual(got.Outcomes, want) {
+		t.Fatalf("outcomes = %#v, want %#v", got.Outcomes, want)
+	}
+	if string(got.DataSchema) != `{"properties":{"items":{"type":"array","description":"Result records","items":{"type":"object"}}},"type":"object"}` {
+		t.Fatalf("data_schema = %s", got.DataSchema)
+	}
+	if want := []string{"credential", "items.secret"}; !reflect.DeepEqual(got.SensitivePaths, want) {
+		t.Fatalf("sensitive_paths = %#v, want %#v", got.SensitivePaths, want)
+	}
+
+	in.Outcomes[0] = ResultOutcomePending
+	in.DataSchema[0] = '['
+	in.SensitivePaths[0] = "changed"
+	if got.Outcomes[0] != ResultOutcomeSuccess || got.DataSchema[0] != '{' || got.SensitivePaths[0] != "credential" {
+		t.Fatalf("normalized result aliases input: %#v", got)
+	}
+}
+
+func TestNormalizeResultSpecRejectsInvalidContractsDeterministically(t *testing.T) {
+	valid := func() *ResultSpec {
+		return &ResultSpec{Outcomes: []ResultOutcome{ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object"}`)}
+	}
+	tests := []struct {
+		name string
+		edit func(*ResultSpec)
+		want string
+	}{
+		{"no outcomes", func(r *ResultSpec) { r.Outcomes = nil }, "no outcomes"},
+		{"unknown outcome", func(r *ResultSpec) { r.Outcomes = []ResultOutcome{"ok"} }, "unknown outcome"},
+		{"duplicate outcome", func(r *ResultSpec) { r.Outcomes = []ResultOutcome{ResultOutcomeSuccess, ResultOutcomeSuccess} }, "duplicate outcome"},
+		{"schema array", func(r *ResultSpec) { r.DataSchema = json.RawMessage(`[]`) }, "data_schema: must be one JSON object"},
+		{"multiple schemas", func(r *ResultSpec) { r.DataSchema = json.RawMessage(`{} {}`) }, "data_schema: must be one JSON object"},
+		{"missing property description", func(r *ResultSpec) {
+			r.DataSchema = json.RawMessage(`{"type":"object","properties":{"id":{"type":"string"}}}`)
+		}, "properties.id requires description"},
+		{"unsafe path", func(r *ResultSpec) { r.SensitivePaths = []string{"$.token"} }, "unsafe segment"},
+		{"duplicate path", func(r *ResultSpec) { r.SensitivePaths = []string{"token", " token "} }, "duplicate sensitive path"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			spec := valid()
+			test.edit(spec)
+			_, err := NormalizeResultSpec(spec, "dev.test")
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestNormalizePaginationSpecUsesFrameworkMetaPaths(t *testing.T) {
+	got, err := NormalizePaginationSpec(&PaginationSpec{Kind: PaginationKindCursor, CursorParameter: "--cursor"}, "dev.list")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.CursorParameter != "cursor" || got.MetaPath != PaginationMetaPath || got.EndpointExhaustedPath != PaginationExhaustedPath || got.NextTokenPath != PaginationNextTokenPath {
+		t.Fatalf("pagination = %#v", got)
+	}
+	for _, spec := range []*PaginationSpec{
+		{Kind: "offset", CursorParameter: "cursor"},
+		{Kind: PaginationKindCursor},
+		{Kind: PaginationKindCursor, CursorParameter: "cursor", MetaPath: "data.pagination"},
+	} {
+		if _, err := NormalizePaginationSpec(spec, "dev.list"); err == nil {
+			t.Fatalf("invalid pagination accepted: %#v", spec)
+		}
+	}
+}
@@ -14,7 +14,10 @@
 package contract

 import (
+	"bytes"
+	"encoding/json"
 	"fmt"
+	"io"
 	"sort"
 	"strings"
 )
@@ -59,6 +62,242 @@ type DryRunSpec struct {
 	RemoteReads bool   `json:"remote_reads,omitempty"`
 }

+// ResultOutcome is one closed unified-output envelope outcome.
+type ResultOutcome string
+
+const (
+	ResultOutcomeSuccess        ResultOutcome = "success"
+	ResultOutcomePending        ResultOutcome = "pending"
+	ResultOutcomePartialFailure ResultOutcome = "partial_failure"
+	ResultOutcomeFailure        ResultOutcome = "failure"
+)
+
+var canonicalResultOutcomes = [...]ResultOutcome{
+	ResultOutcomeSuccess,
+	ResultOutcomePending,
+	ResultOutcomePartialFailure,
+	ResultOutcomeFailure,
+}
+
+const (
+	PaginationKindCursor    = "cursor"
+	PaginationMetaPath      = "meta.pagination"
+	PaginationExhaustedPath = "meta.pagination.endpoint_exhausted"
+	PaginationNextTokenPath = "meta.pagination.next_token"
+)
+
+// PaginationSpec is a command-level declaration for framework pagination
+// metadata. It is deliberately separate from ResultSpec because pagination is
+// emitted under envelope meta, not inside the business response data.
+type PaginationSpec struct {
+	Kind                  string `json:"kind"`
+	CursorParameter       string `json:"cursor_parameter"`
+	MetaPath              string `json:"meta_path"`
+	EndpointExhaustedPath string `json:"endpoint_exhausted_path"`
+	NextTokenPath         string `json:"next_token_path"`
+}
+
+// ResultSpec is the reviewed return-value contract for one command and is
+// projected unchanged into both full-leaf and compact-leaf Schema. Outcomes
+// and DataSchema are required; Pagination and SensitivePaths are omitted when
+// absent. DataSchema is a canonical recursive JSON Schema object; every path
+// is relative to the unified-output envelope data value.
+type ResultSpec struct {
+	Outcomes       []ResultOutcome `json:"outcomes"`
+	DataSchema     json.RawMessage `json:"data_schema"`
+	SensitivePaths []string        `json:"sensitive_paths,omitempty"`
+}
+
+// NormalizeResultSpec returns a validated, canonical, defensively copied
+// result contract. It is shared by declaration, ToolSpec, and snapshot paths.
+func NormalizeResultSpec(in *ResultSpec, canonical string) (*ResultSpec, error) {
+	if in == nil {
+		return nil, nil
+	}
+	canonical = defaultString(strings.TrimSpace(canonical), "<unknown>")
+	out := &ResultSpec{}
+	seenOutcomes := make(map[ResultOutcome]bool, len(in.Outcomes))
+	for _, outcome := range in.Outcomes {
+		outcome = ResultOutcome(strings.TrimSpace(string(outcome)))
+		valid := false
+		for _, allowed := range canonicalResultOutcomes {
+			if outcome == allowed {
+				valid = true
+				break
+			}
+		}
+		if !valid {
+			return nil, fmt.Errorf("schema tool %s result has unknown outcome %q", canonical, outcome)
+		}
+		if seenOutcomes[outcome] {
+			return nil, fmt.Errorf("schema tool %s result has duplicate outcome %q", canonical, outcome)
+		}
+		seenOutcomes[outcome] = true
+	}
+	if len(seenOutcomes) == 0 {
+		return nil, fmt.Errorf("schema tool %s result has no outcomes", canonical)
+	}
+	for _, outcome := range canonicalResultOutcomes {
+		if seenOutcomes[outcome] {
+			out.Outcomes = append(out.Outcomes, outcome)
+		}
+	}
+	var err error
+	out.DataSchema, err = canonicalJSONObject(in.DataSchema)
+	if err != nil {
+		return nil, fmt.Errorf("schema tool %s result data_schema: %w", canonical, err)
+	}
+	if err := validateResultSchemaDescriptions(out.DataSchema, "data_schema"); err != nil {
+		return nil, fmt.Errorf("schema tool %s result %w", canonical, err)
+	}
+	seenPaths := make(map[string]bool, len(in.SensitivePaths))
+	for _, path := range in.SensitivePaths {
+		path = strings.TrimSpace(path)
+		if err := validateResultPath(path); err != nil {
+			return nil, fmt.Errorf("schema tool %s result sensitive path: %w", canonical, err)
+		}
+		if seenPaths[path] {
+			return nil, fmt.Errorf("schema tool %s result has duplicate sensitive path %q", canonical, path)
+		}
+		seenPaths[path] = true
+		out.SensitivePaths = append(out.SensitivePaths, path)
+	}
+	sort.Strings(out.SensitivePaths)
+	if len(out.SensitivePaths) == 0 {
+		out.SensitivePaths = nil
+	}
+	return out, nil
+}
+
+// NormalizePaginationSpec validates the command-specific input parameter and
+// fills the framework-owned public meta paths.
+func NormalizePaginationSpec(in *PaginationSpec, canonical string) (*PaginationSpec, error) {
+	if in == nil {
+		return nil, nil
+	}
+	canonical = defaultString(strings.TrimSpace(canonical), "<unknown>")
+	kind := strings.TrimSpace(in.Kind)
+	if kind != PaginationKindCursor {
+		return nil, fmt.Errorf("schema tool %s pagination has unsupported kind %q", canonical, kind)
+	}
+	cursorParameter := strings.TrimSpace(strings.TrimPrefix(in.CursorParameter, "--"))
+	if cursorParameter == "" || strings.Contains(cursorParameter, ".") {
+		return nil, fmt.Errorf("schema tool %s pagination cursor_parameter must name one CLI flag", canonical)
+	}
+	provided := []struct{ name, got, want string }{
+		{"meta_path", strings.TrimSpace(in.MetaPath), PaginationMetaPath},
+		{"endpoint_exhausted_path", strings.TrimSpace(in.EndpointExhaustedPath), PaginationExhaustedPath},
+		{"next_token_path", strings.TrimSpace(in.NextTokenPath), PaginationNextTokenPath},
+	}
+	for _, field := range provided {
+		if field.got != "" && field.got != field.want {
+			return nil, fmt.Errorf("schema tool %s pagination %s is framework-owned and must be %q", canonical, field.name, field.want)
+		}
+	}
+	return &PaginationSpec{
+		Kind:                  kind,
+		CursorParameter:       cursorParameter,
+		MetaPath:              PaginationMetaPath,
+		EndpointExhaustedPath: PaginationExhaustedPath,
+		NextTokenPath:         PaginationNextTokenPath,
+	}, nil
+}
+
+func canonicalJSONObject(raw json.RawMessage) (json.RawMessage, error) {
+	if len(raw) == 0 {
+		return nil, fmt.Errorf("must be one JSON object")
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.UseNumber()
+	var object map[string]json.RawMessage
+	if err := decoder.Decode(&object); err != nil || object == nil {
+		return nil, fmt.Errorf("must be one JSON object")
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		return nil, fmt.Errorf("must be one JSON object")
+	}
+	canonical, _ := json.Marshal(object) // decoded RawMessages are always marshalable
+	return json.RawMessage(canonical), nil
+}
+
+// validateResultSchemaDescriptions keeps the Agent-facing return contract
+// self-explanatory. Every named property needs a description; nested object
+// properties and array items are checked recursively. The root schema and
+// anonymous composition branches do not need descriptions because they are
+// not field names an Agent must interpret.
+func validateResultSchemaDescriptions(raw json.RawMessage, location string) error {
+	var schema map[string]any
+	if err := json.Unmarshal(raw, &schema); err != nil {
+		return fmt.Errorf("%s must be one JSON Schema object", location)
+	}
+	return validateResultSchemaNode(schema, location)
+}
+
+func validateResultSchemaNode(schema map[string]any, location string) error {
+	if rawProperties, exists := schema["properties"]; exists {
+		properties, ok := rawProperties.(map[string]any)
+		if !ok {
+			return fmt.Errorf("%s.properties must be an object", location)
+		}
+		for name, rawProperty := range properties {
+			property, ok := rawProperty.(map[string]any)
+			if !ok {
+				return fmt.Errorf("%s.properties.%s must be a JSON Schema object", location, name)
+			}
+			description, _ := property["description"].(string)
+			if strings.TrimSpace(description) == "" {
+				return fmt.Errorf("%s.properties.%s requires description", location, name)
+			}
+			if err := validateResultSchemaNode(property, location+".properties."+name); err != nil {
+				return err
+			}
+		}
+	}
+	if rawItems, exists := schema["items"]; exists {
+		items, ok := rawItems.(map[string]any)
+		if !ok {
+			return fmt.Errorf("%s.items must be a JSON Schema object", location)
+		}
+		if err := validateResultSchemaNode(items, location+".items"); err != nil {
+			return err
+		}
+	}
+	for _, keyword := range []string{"allOf", "anyOf", "oneOf"} {
+		rawBranches, exists := schema[keyword]
+		if !exists {
+			continue
+		}
+		branches, ok := rawBranches.([]any)
+		if !ok {
+			return fmt.Errorf("%s.%s must be an array", location, keyword)
+		}
+		for index, rawBranch := range branches {
+			branch, ok := rawBranch.(map[string]any)
+			if !ok {
+				return fmt.Errorf("%s.%s[%d] must be a JSON Schema object", location, keyword, index)
+			}
+			if err := validateResultSchemaNode(branch, fmt.Sprintf("%s.%s[%d]", location, keyword, index)); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func validateResultPath(path string) error {
+	if path == "" || strings.HasPrefix(path, ".") || strings.HasSuffix(path, ".") || strings.Contains(path, "..") {
+		return fmt.Errorf("path %q is not a relative data path", path)
+	}
+	for _, segment := range strings.Split(path, ".") {
+		for i, r := range segment {
+			if !((r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || r == '_' || (i > 0 && (r == '-' || (r >= '0' && r <= '9')))) {
+				return fmt.Errorf("path %q contains unsafe segment %q", path, segment)
+			}
+		}
+	}
+	return nil
+}
+
 const (
 	DryRunPreviewInvocation = "invocation"
 	DryRunPreviewRequest    = "request"
@@ -4,10 +4,75 @@
 package contract

 import (
+	"encoding/json"
 	"strings"
 	"testing"
 )

+func TestFrameworkResultSpecValidationEdges(t *testing.T) {
+	if got, err := NormalizeResultSpec(nil, ""); err != nil || got != nil {
+		t.Fatalf("NormalizeResultSpec(nil)=(%v,%v)", got, err)
+	}
+	base := func() *ResultSpec {
+		return &ResultSpec{Outcomes: []ResultOutcome{ResultOutcomeSuccess}, DataSchema: json.RawMessage(`{"type":"object"}`)}
+	}
+	if got, err := NormalizeResultSpec(base(), ""); err != nil || got == nil || got.SensitivePaths != nil {
+		t.Fatalf("valid default spec=(%#v,%v)", got, err)
+	}
+	cases := []struct {
+		name string
+		edit func(*ResultSpec)
+	}{
+		{"sensitive invalid", func(s *ResultSpec) { s.SensitivePaths = []string{"bad..path"} }},
+		{"empty schema", func(s *ResultSpec) { s.DataSchema = nil }},
+		{"multiple schema", func(s *ResultSpec) { s.DataSchema = json.RawMessage(`{} {}`) }},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			spec := base()
+			tc.edit(spec)
+			if _, err := NormalizeResultSpec(spec, "sample"); err == nil {
+				t.Fatalf("invalid spec accepted: %#v", spec)
+			}
+		})
+	}
+	if err := validateResultPath("a.$"); err == nil {
+		t.Fatal("unsafe segment accepted")
+	}
+}
+
+func TestFrameworkResultSchemaDescriptionValidationEdges(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{"invalid json", `{`, "must be one JSON Schema object"},
+		{"properties is not object", `{"properties":[]}`, "properties must be an object"},
+		{"property is not schema", `{"properties":{"id":"string"}}`, "properties.id must be a JSON Schema object"},
+		{"property description missing", `{"properties":{"id":{"type":"string"}}}`, "properties.id requires description"},
+		{"nested property invalid", `{"properties":{"item":{"description":"item","properties":[]}}}`, "properties.item.properties must be an object"},
+		{"items is not schema", `{"items":[]}`, "items must be a JSON Schema object"},
+		{"nested items invalid", `{"items":{"properties":[]}}`, "items.properties must be an object"},
+		{"composition is not array", `{"oneOf":{}}`, "oneOf must be an array"},
+		{"composition branch is not schema", `{"anyOf":["string"]}`, "anyOf[0] must be a JSON Schema object"},
+		{"nested composition invalid", `{"allOf":[{"properties":[]}]}`, "allOf[0].properties must be an object"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateResultSchemaDescriptions(json.RawMessage(tc.raw), "data_schema")
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("validation error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestNormalizePaginationSpecNilIsAbsent(t *testing.T) {
+	if got, err := NormalizePaginationSpec(nil, ""); err != nil || got != nil {
+		t.Fatalf("NormalizePaginationSpec(nil) = (%#v, %v)", got, err)
+	}
+}
+
 func TestCrossPlatformCoverageDryRunSpecValidate(t *testing.T) {
 	for _, kind := range []string{DryRunPreviewInvocation, DryRunPreviewRequest, DryRunPreviewPlan, DryRunPreviewDiff} {
 		if err := (DryRunSpec{PreviewKind: kind}).Validate("sample.run"); err != nil {
@@ -42,6 +42,8 @@ type ContractDecl struct {
 	Positionals []contract.RuntimeSchemaPositional
 	Parameters  []contract.ParamDecl
 	DryRun      *contract.DryRunSpec
+	Result      *contract.ResultSpec
+	Pagination  *contract.PaginationSpec
 	Interface   *contract.InterfaceSpec
 	Selection   contract.SelectionSpec
 	Identity    contract.ToolIdentitySpec
@@ -144,6 +146,12 @@ func (s ContractDecl) empty() bool {
 	if s.DryRun != nil && strings.TrimSpace(s.DryRun.PreviewKind) != "" {
 		return false
 	}
+	if s.Result != nil {
+		return false
+	}
+	if s.Pagination != nil {
+		return false
+	}
 	if s.Interface != nil {
 		iface := s.Interface
 		if strings.TrimSpace(iface.Mode) != "" || strings.TrimSpace(iface.Availability) != "" ||
@@ -42,6 +42,11 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 			Description: "Create Desc",
 			Positionals: []contract.RuntimeSchemaPositional{{Name: "id", Required: true, Index: 0}},
 			DryRun:      &contract.DryRunSpec{PreviewKind: "invocation", RemoteReads: true},
+			Result: &contract.ResultSpec{
+				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+				DataSchema: []byte(`{"type":"object"}`),
+			},
+			Pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
 			Interface: &contract.InterfaceSpec{
 				Mode:         "mcp",
 				Availability: "available",
@@ -79,6 +84,12 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 	if final.DryRun == nil || final.DryRun.PreviewKind != "invocation" || !final.DryRun.RemoteReads {
 		t.Fatalf("dry_run = %#v", final.DryRun)
 	}
+	if final.Result == nil || len(final.Result.Outcomes) != 1 {
+		t.Fatalf("result = %#v", final.Result)
+	}
+	if final.Pagination == nil || final.Pagination.CursorParameter != "cursor" || final.Pagination.MetaPath != contract.PaginationMetaPath {
+		t.Fatalf("pagination = %#v", final.Pagination)
+	}
 	if final.Interface == nil || final.Interface.Mode != "mcp" || final.Interface.Ref == nil || final.Interface.Ref.RPCName != "create_thing" {
 		t.Fatalf("interface = %#v", final.Interface)
 	}
@@ -110,6 +121,54 @@ func TestCrossPlatformCoverageNewCommandEmbedsFullContractDeclAsFinalSource(t *t
 	}
 }

+func TestFrameworkContractDeclResultMarksNonEmptyAndRejectsInvalidSchema(t *testing.T) {
+	if (ContractDecl{Result: &contract.ResultSpec{}}).Empty() {
+		t.Fatal("Result declaration was treated as empty")
+	}
+	defer func() {
+		if recovered := recover(); recovered == nil || !strings.Contains(recovered.(string), "invalid Contract.Result") {
+			t.Fatalf("panic=%v", recovered)
+		}
+	}()
+	New(Spec{
+		Use:    "bad-result",
+		Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+		Contract: ContractDecl{
+			Title: "Bad", Description: "bad result",
+			Result:    &contract.ResultSpec{Outcomes: []contract.ResultOutcome{contract.ResultOutcomeSuccess}},
+			Interface: &contract.InterfaceSpec{Mode: "local", Availability: "available"},
+			Selection: contract.SelectionSpec{AgentSummary: "bad", UseWhen: []string{"bad"}, AvoidWhen: []string{"good"}, Examples: []string{"dws bad-result"}},
+			Identity:  contract.ToolIdentitySpec{ProductID: "sample", Name: "bad", CanonicalPath: "sample.bad", CLIPath: "bad-result", PrimaryCLIPath: "bad-result"},
+		},
+		Invoke: func(*Ctx, map[string]any) error { return nil },
+	})
+}
+
+func TestFrameworkContractDeclPaginationMarksNonEmptyAndRejectsInvalidSpec(t *testing.T) {
+	if (ContractDecl{Pagination: &contract.PaginationSpec{}}).Empty() {
+		t.Fatal("Pagination declaration was treated as empty")
+	}
+	defer func() {
+		recovered := recover()
+		if recovered == nil || !strings.Contains(recovered.(string), "invalid Contract.Pagination") {
+			t.Fatalf("panic=%v", recovered)
+		}
+	}()
+	New(Spec{
+		Use:    "bad-pagination",
+		Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"},
+		Contract: ContractDecl{
+			Title:       "Bad pagination",
+			Description: "bad pagination",
+			Pagination:  &contract.PaginationSpec{Kind: "offset", CursorParameter: "cursor"},
+			Interface:   &contract.InterfaceSpec{Mode: "local", Availability: "available"},
+			Selection:   contract.SelectionSpec{AgentSummary: "bad", UseWhen: []string{"bad"}, AvoidWhen: []string{"good"}, Examples: []string{"dws bad-pagination"}},
+			Identity:    contract.ToolIdentitySpec{ProductID: "sample", Name: "bad_pagination", CanonicalPath: "sample.bad_pagination", CLIPath: "bad-pagination", PrimaryCLIPath: "bad-pagination"},
+		},
+		Invoke: func(*Ctx, map[string]any) error { return nil },
+	})
+}
+
 func TestNewCommandFallsBackToDeclaredDescriptionWithoutLong(t *testing.T) {
 	// Long wins when authored; without one the mandatory declaration supplies it.
 	cmd := New(Spec{
@@ -24,6 +24,11 @@ import (
 func TestContractFinalTypedRegistryNoJSON(t *testing.T) {
 	cmd := &cobra.Command{Use: "x"}
 	t.Cleanup(func() { ClearRuntimeContractFinalForTest(cmd) })
+	result := &contract.ResultSpec{
+		Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+		DataSchema:     []byte(`{"type":"object"}`),
+		SensitivePaths: []string{"token"},
+	}

 	RegisterRuntimeContractFinal(cmd, contract.ContractFinalPayload{
 		Title: "T",
@@ -32,7 +37,11 @@ func TestContractFinalTypedRegistryNoJSON(t *testing.T) {
 		},
 		Selection: &contract.SelectionSpec{AgentSummary: "sum", UseWhen: []string{"u"}},
 		Identity:  &contract.ToolIdentitySpec{ProductID: "p", Name: "n"},
+		Result:    result,
 	})
+	result.Outcomes[0] = contract.ResultOutcomeFailure
+	result.DataSchema[0] = '['
+	result.SensitivePaths[0] = "changed"
 	if cmd.Annotations != nil {
 		if _, ok := cmd.Annotations["dws.schema.final"]; ok {
 			t.Fatal("must not write JSON annotation dws.schema.final")
@@ -45,6 +54,14 @@ func TestContractFinalTypedRegistryNoJSON(t *testing.T) {
 	if got.Selection == nil || got.Selection.Reviewed != nil {
 		t.Fatalf("selection must not carry reviewed fields: %#v", got.Selection)
 	}
+	if got.Result == nil || got.Result.Outcomes[0] != contract.ResultOutcomeSuccess || got.Result.DataSchema[0] != '{' || got.Result.SensitivePaths[0] != "token" {
+		t.Fatalf("stored result aliases registration input: %#v", got.Result)
+	}
+	got.Result.Outcomes[0] = contract.ResultOutcomeFailure
+	again, _ := RuntimeContractFinal(cmd)
+	if again.Result.Outcomes[0] != contract.ResultOutcomeSuccess {
+		t.Fatal("RuntimeContractFinal result aliases stored payload")
+	}
 }

 func TestCrossPlatformCoverageContractFinalNilCommandGuards(t *testing.T) {
@@ -137,3 +154,96 @@ func TestCrossPlatformCoverageRuntimeContractFinalRejectsForeignStoredValue(t *t
 		t.Fatal("typed nil payload must not decode as contract.ContractFinalPayload")
 	}
 }
+
+func TestResolveRuntimeSafetyUsesCanonicalOrCLIIdentityAndRejectsUnavailable(t *testing.T) {
+	read := &cobra.Command{Use: "read"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(read) })
+	RegisterRuntimeContractFinal(read, contract.ContractFinalPayload{
+		Identity: &contract.ToolIdentitySpec{CanonicalPath: "sample.read", PrimaryCLIPath: "sample get"},
+		Safety:   &contract.SafetySpec{Effect: " read ", Idempotency: " idempotent "},
+	})
+
+	for _, lookup := range []struct {
+		canonical string
+		cli       string
+	}{
+		{canonical: "sample.read"},
+		{canonical: "different.rpc", cli: "dws sample get"},
+	} {
+		safety, declared, ok := ResolveRuntimeSafety(lookup.canonical, lookup.cli)
+		if !declared || !ok || safety.Effect != "read" || safety.Idempotency != "idempotent" {
+			t.Fatalf("ResolveRuntimeSafety(%q, %q) = %#v, %v, %v", lookup.canonical, lookup.cli, safety, declared, ok)
+		}
+	}
+
+	missingSafety := &cobra.Command{Use: "write"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(missingSafety) })
+	RegisterRuntimeContractFinal(missingSafety, contract.ContractFinalPayload{
+		Identity: &contract.ToolIdentitySpec{CanonicalPath: "sample.write"},
+	})
+	if _, declared, ok := ResolveRuntimeSafety("sample.write", ""); !declared || ok {
+		t.Fatalf("missing safety = declared %v ok %v, want true false", declared, ok)
+	}
+	if _, declared, ok := ResolveRuntimeSafety("legacy.call", "legacy call"); declared || ok {
+		t.Fatalf("legacy lookup = declared %v ok %v, want false false", declared, ok)
+	}
+}
+
+func boolPointer(value bool) *bool { return &value }
+func intPointer(value int) *int    { return &value }
+
+func TestFrameworkContractFinalDeepCopyAndSafetyConflicts(t *testing.T) {
+	cmd := &cobra.Command{Use: "all"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(cmd) })
+	payload := contract.ContractFinalPayload{
+		Positionals: []contract.RuntimeSchemaPositional{{Name: "id"}},
+		Parameters:  []contract.ParamDecl{{Name: "mode", Enum: []string{"a"}, Required: boolPointer(true)}},
+		Safety:      &contract.SafetySpec{Effect: " read ", EffectSource: " source ", Risk: " low ", Confirmation: " not_required ", Idempotency: " idempotent "},
+		DryRun:      &contract.DryRunSpec{PreviewKind: "plan"},
+		Result: &contract.ResultSpec{
+			Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess},
+			DataSchema: []byte(`{"type":"object"}`), SensitivePaths: []string{"token"},
+		},
+		Pagination: &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"},
+		Interface:  &contract.InterfaceSpec{Ref: &contract.InterfaceRefSpec{}},
+		Selection: &contract.SelectionSpec{
+			UseWhen: []string{"use"}, AvoidWhen: []string{"avoid"}, Prerequisites: []string{"pre"}, Tips: []string{"tip"},
+			WorkflowRefs: []string{"flow"}, Examples: []string{"example"}, SourceRefs: []string{"source"},
+			ExampleDispositions: []contract.ExampleDisposition{{Index: intPointer(1)}}, Reviewed: boolPointer(true),
+		},
+		Identity: &contract.ToolIdentitySpec{CanonicalPath: "sample.all", Aliases: []string{"alias"}},
+	}
+	RegisterRuntimeContractFinal(cmd, payload)
+	got, ok := RuntimeContractFinal(cmd)
+	if !ok || got.Result == payload.Result || got.Pagination == payload.Pagination || got.Interface == payload.Interface || got.Selection == payload.Selection || got.Identity == payload.Identity {
+		t.Fatalf("payload not deeply cloned: %#v", got)
+	}
+	payload.Parameters[0].Enum[0] = "changed"
+	*payload.Parameters[0].Required = false
+	*payload.Selection.ExampleDispositions[0].Index = 9
+	*payload.Selection.Reviewed = false
+	again, _ := RuntimeContractFinal(cmd)
+	if again.Parameters[0].Enum[0] != "a" || !*again.Parameters[0].Required || *again.Selection.ExampleDispositions[0].Index != 1 || !*again.Selection.Reviewed {
+		t.Fatalf("stored payload aliased input: %#v", again)
+	}
+
+	matching := &cobra.Command{Use: "matching"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(matching) })
+	RegisterRuntimeContractFinal(matching, contract.ContractFinalPayload{Identity: &contract.ToolIdentitySpec{Path: "sample.all", CLIPath: "sample all"}, Safety: &contract.SafetySpec{Effect: "read", EffectSource: "source", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"}})
+	if _, declared, valid := ResolveRuntimeSafety("sample.all", ""); !declared || !valid {
+		t.Fatalf("equivalent duplicate=(declared=%v valid=%v)", declared, valid)
+	}
+
+	conflict := &cobra.Command{Use: "conflict"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(conflict) })
+	RegisterRuntimeContractFinal(conflict, contract.ContractFinalPayload{Identity: &contract.ToolIdentitySpec{CanonicalPath: "sample.all"}, Safety: &contract.SafetySpec{Effect: "write"}})
+	if _, declared, valid := ResolveRuntimeSafety("sample.all", ""); !declared || valid {
+		t.Fatalf("conflict=(declared=%v valid=%v)", declared, valid)
+	}
+	if runtimeIdentityMatches(contract.ToolIdentitySpec{}, "", "") {
+		t.Fatal("empty identity matched")
+	}
+	if got := cloneSlice[string](nil); got != nil {
+		t.Fatalf("cloneSlice(nil)=%v", got)
+	}
+}
@@ -14,6 +14,7 @@
 package contractfinal

 import (
+	"strings"
 	"sync"

 	"github.com/spf13/cobra"
@@ -34,7 +35,7 @@ func RegisterRuntimeContractFinal(cmd *cobra.Command, payload contract.ContractF
 		return
 	}
 	runtimeannotate.AnnotateRuntimeContract(cmd)
-	p := payload
+	p := cloneContractFinalPayload(payload)
 	contractFinalByCommand.Store(cmd, &p)
 }

@@ -51,7 +52,84 @@ func RuntimeContractFinal(cmd *cobra.Command) (contract.ContractFinalPayload, bo
 	if !ok || p == nil {
 		return contract.ContractFinalPayload{}, false
 	}
-	return *p, true
+	return cloneContractFinalPayload(*p), true
+}
+
+func cloneContractFinalPayload(in contract.ContractFinalPayload) contract.ContractFinalPayload {
+	out := in
+	out.Positionals = cloneSlice(in.Positionals)
+	out.Parameters = cloneSlice(in.Parameters)
+	for i := range out.Parameters {
+		out.Parameters[i].Enum = cloneSlice(in.Parameters[i].Enum)
+		if in.Parameters[i].Required != nil {
+			required := *in.Parameters[i].Required
+			out.Parameters[i].Required = &required
+		}
+	}
+	if in.Safety != nil {
+		value := *in.Safety
+		out.Safety = &value
+	}
+	if in.DryRun != nil {
+		value := *in.DryRun
+		out.DryRun = &value
+	}
+	if in.Result != nil {
+		value := *in.Result
+		value.Outcomes = cloneSlice(in.Result.Outcomes)
+		value.DataSchema = cloneSlice(in.Result.DataSchema)
+		value.SensitivePaths = cloneSlice(in.Result.SensitivePaths)
+		out.Result = &value
+	}
+	if in.Pagination != nil {
+		value := *in.Pagination
+		out.Pagination = &value
+	}
+	if in.Interface != nil {
+		value := *in.Interface
+		if in.Interface.Ref != nil {
+			ref := *in.Interface.Ref
+			value.Ref = &ref
+		}
+		out.Interface = &value
+	}
+	if in.Selection != nil {
+		value := *in.Selection
+		value.UseWhen = cloneSlice(in.Selection.UseWhen)
+		value.AvoidWhen = cloneSlice(in.Selection.AvoidWhen)
+		value.Prerequisites = cloneSlice(in.Selection.Prerequisites)
+		value.Tips = cloneSlice(in.Selection.Tips)
+		value.WorkflowRefs = cloneSlice(in.Selection.WorkflowRefs)
+		value.Examples = cloneSlice(in.Selection.Examples)
+		value.SourceRefs = cloneSlice(in.Selection.SourceRefs)
+		value.ExampleDispositions = cloneSlice(in.Selection.ExampleDispositions)
+		for i := range value.ExampleDispositions {
+			if in.Selection.ExampleDispositions[i].Index != nil {
+				index := *in.Selection.ExampleDispositions[i].Index
+				value.ExampleDispositions[i].Index = &index
+			}
+		}
+		if in.Selection.Reviewed != nil {
+			reviewed := *in.Selection.Reviewed
+			value.Reviewed = &reviewed
+		}
+		out.Selection = &value
+	}
+	if in.Identity != nil {
+		value := *in.Identity
+		value.Aliases = cloneSlice(in.Identity.Aliases)
+		out.Identity = &value
+	}
+	return out
+}
+
+func cloneSlice[T any](in []T) []T {
+	if in == nil {
+		return nil
+	}
+	out := make([]T, len(in))
+	copy(out, in)
+	return out
 }

 // HasRuntimeContractFinal reports whether the leaf has a registered final overlay.
@@ -62,3 +140,67 @@ func HasRuntimeContractFinal(cmd *cobra.Command) bool {
 	_, ok := contractFinalByCommand.Load(cmd)
 	return ok
 }
+
+// ResolveRuntimeSafety finds the live ContractFinal safety declaration for an
+// invocation identity. declared distinguishes a matched declaration whose
+// safety is unavailable or conflicting from a legacy invocation with no unified
+// declaration context. Repeated equivalent command-tree registrations are
+// accepted; conflicting matches fail closed with ok=false.
+func ResolveRuntimeSafety(canonicalPath, cliPath string) (safety contract.SafetySpec, declared, ok bool) {
+	canonicalPath = strings.TrimSpace(canonicalPath)
+	cliPath = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(cliPath), "dws "))
+
+	var resolved contract.SafetySpec
+	contractFinalByCommand.Range(func(_, raw any) bool {
+		payload, valid := raw.(*contract.ContractFinalPayload)
+		if !valid || payload == nil || payload.Identity == nil ||
+			!runtimeIdentityMatches(*payload.Identity, canonicalPath, cliPath) {
+			return true
+		}
+		declared = true
+		if payload.Safety == nil {
+			ok = false
+			return false
+		}
+		candidate := normalizedRuntimeSafety(*payload.Safety)
+		if !ok {
+			resolved = candidate
+			ok = true
+			return true
+		}
+		if resolved != candidate {
+			ok = false
+			return false
+		}
+		return true
+	})
+	return resolved, declared, ok
+}
+
+func runtimeIdentityMatches(identity contract.ToolIdentitySpec, canonicalPath, cliPath string) bool {
+	if canonicalPath != "" {
+		for _, value := range []string{identity.CanonicalPath, identity.Path} {
+			if strings.TrimSpace(value) == canonicalPath {
+				return true
+			}
+		}
+	}
+	if cliPath == "" {
+		return false
+	}
+	for _, value := range []string{identity.PrimaryCLIPath, identity.CLIPath} {
+		if strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(value), "dws ")) == cliPath {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizedRuntimeSafety(safety contract.SafetySpec) contract.SafetySpec {
+	safety.Effect = strings.TrimSpace(safety.Effect)
+	safety.EffectSource = strings.TrimSpace(safety.EffectSource)
+	safety.Risk = strings.TrimSpace(safety.Risk)
+	safety.Confirmation = strings.TrimSpace(safety.Confirmation)
+	safety.Idempotency = strings.TrimSpace(safety.Idempotency)
+	return safety
+}
@@ -63,6 +63,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 )

@@ -224,11 +225,12 @@ const (
 // construction time. corecmd stays dispatch-agnostic and never calls a backend:
 // the adapters (FromLeafSpec / FromShortcut) supply the body.
 type Spec struct {
-	Use     string
-	Short   string
-	Long    string
-	Example string
-	Hidden  bool
+	Use           string
+	Short         string
+	Long          string
+	Example       string
+	Hidden        bool
+	OutputRollout output.RolloutState

 	Flags       []FlagSpec
 	Constraints []Constraint
@@ -266,6 +268,8 @@ type Spec struct {
 	RunE func(cmd *cobra.Command, args []string) error
 	// Invoke executes a single-step command with the assembled toolArgs.
 	Invoke func(c *Ctx, toolArgs map[string]any) error
+	// ResultInvoke executes once and returns an immutable framework 2.0 result.
+	ResultInvoke func(c *Ctx, toolArgs map[string]any) (output.CommandResult, error)
 	// Orchestrate executes a multi-step command; it assembles whatever payloads
 	// it needs from the Ctx.
 	Orchestrate func(c *Ctx) error
@@ -385,6 +389,9 @@ func New(spec Spec) *cobra.Command {
 	if spec.PostMount != nil {
 		spec.PostMount(cmd)
 	}
+	if spec.OutputRollout != "" {
+		output.SetCommandRollout(cmd, spec.OutputRollout)
+	}
 	if spec.ConfirmFirst {
 		if cmd.Annotations == nil {
 			cmd.Annotations = map[string]string{}
@@ -430,6 +437,16 @@ func New(spec Spec) *cobra.Command {
 				return err
 			}
 		}
+		if spec.ResultInvoke != nil {
+			if !output.UsesUnifiedResult(cmd) {
+				return fmt.Errorf("command %q uses ResultInvoke without an active unified-result rollout", cmd.CommandPath())
+			}
+			result, err := spec.ResultInvoke(ctx, toolArgs)
+			if err != nil {
+				return err
+			}
+			return output.StoreResult(cmd.Context(), result)
+		}
 		return spec.Invoke(ctx, toolArgs)
 	}
 	return cmd
@@ -486,12 +503,15 @@ func validateDispatchDecl(spec Spec) {
 	if spec.Invoke != nil {
 		declared++
 	}
+	if spec.ResultInvoke != nil {
+		declared++
+	}
 	if spec.Orchestrate != nil {
 		declared++
 	}
 	if declared != 1 {
 		panic(fmt.Sprintf(
-			"command %q must declare exactly one of RunE/Invoke/Orchestrate, got %d",
+			"command %q must declare exactly one of RunE/Invoke/Orchestrate, got %d (ResultInvoke is also a dispatcher)",
 			spec.Use, declared))
 	}
 	// ConfirmFirst only changes the ordering of a declared confirmation gate.
@@ -681,7 +701,7 @@ func ValidateRequired(cmd *cobra.Command, flags []FlagSpec) error {
 			if hint == "" {
 				hint = fmt.Sprintf("flag --%s is required", flag.Name)
 			}
-			return fmt.Errorf("%s", hint)
+			return apperrors.NewValidation(hint)
 		}
 	}
 	return nil
@@ -1360,6 +1380,20 @@ func AttachContract(cmd *cobra.Command, safety contract.SafetySpec, decl Contrac
 		d.PreviewKind = strings.TrimSpace(d.PreviewKind)
 		payload.DryRun = &d
 	}
+	if decl.Result != nil {
+		result, err := contract.NormalizeResultSpec(decl.Result, decl.Identity.CanonicalPath)
+		if err != nil {
+			panic(fmt.Sprintf("command %q has invalid Contract.Result: %v", cmd.Name(), err))
+		}
+		payload.Result = result
+	}
+	if decl.Pagination != nil {
+		pagination, err := contract.NormalizePaginationSpec(decl.Pagination, decl.Identity.CanonicalPath)
+		if err != nil {
+			panic(fmt.Sprintf("command %q has invalid Contract.Pagination: %v", cmd.Name(), err))
+		}
+		payload.Pagination = pagination
+	}
 	if decl.Interface != nil {
 		iface := &contract.InterfaceSpec{
 			Mode:         strings.TrimSpace(decl.Interface.Mode),
@@ -0,0 +1,99 @@
+package corecmd
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+func TestResultInvokeCarriesOneFrameworkResult(t *testing.T) {
+	calls := 0
+	ctx, store := output.WithResultStore(context.Background())
+	cmd := New(Spec{
+		Use:           "result",
+		OutputRollout: output.RolloutUnifiedActive,
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		ResultInvoke: func(*Ctx, map[string]any) (output.CommandResult, error) {
+			calls++
+			return output.Success(map[string]any{"id": "a"}), nil
+		},
+	})
+	cmd.SetContext(ctx)
+	cmd.PersistentFlags().String("format", "json", "")
+	var stdout bytes.Buffer
+	cmd.SetOut(&stdout)
+	cmd.PersistentPostRunE = func(executed *cobra.Command, _ []string) error {
+		_, _, err := output.EmitStoredResult(executed)
+		return err
+	}
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("calls=%d, want 1", calls)
+	}
+	if code, emitted := output.StoredExitCode(store); !emitted || code != 0 {
+		t.Fatalf("stored code/emitted=%d/%v", code, emitted)
+	}
+	if !strings.Contains(stdout.String(), `"outcome": "success"`) || strings.Contains(stdout.String(), `"contract_version"`) {
+		t.Fatalf("stdout=%s", stdout.String())
+	}
+	if output.CommandRollout(cmd) != output.RolloutUnifiedActive {
+		t.Fatalf("rollout=%s", output.CommandRollout(cmd))
+	}
+}
+
+func TestFrameworkResultInvokeErrorLegacyAndStoreEdges(t *testing.T) {
+	wantErr := errors.New("invoke failed")
+	cases := []struct {
+		name    string
+		rollout output.RolloutState
+		invoke  func(*Ctx, map[string]any) (output.CommandResult, error)
+		want    string
+	}{
+		{"invoke error", output.RolloutUnifiedActive, func(*Ctx, map[string]any) (output.CommandResult, error) { return nil, wantErr }, "invoke failed"},
+		{"legacy guard", output.RolloutLegacyOnly, func(*Ctx, map[string]any) (output.CommandResult, error) { return output.Success(nil), nil }, "without an active unified-result rollout"},
+		{"missing store", output.RolloutUnifiedActive, func(*Ctx, map[string]any) (output.CommandResult, error) { return output.Success(nil), nil }, "no result store"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := New(Spec{Use: "result", OutputRollout: tc.rollout, Safety: contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"}, ResultInvoke: tc.invoke})
+			cmd.SetArgs(nil)
+			err := cmd.Execute()
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("Execute error=%v, want %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestLegacyResultInvokeIsRejectedBeforeBusinessDispatch(t *testing.T) {
+	calls := 0
+	cmd := New(Spec{
+		Use:           "result",
+		OutputRollout: output.RolloutLegacyOnly,
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "high", Confirmation: "not_required", Idempotency: "unknown",
+		},
+		ResultInvoke: func(*Ctx, map[string]any) (output.CommandResult, error) {
+			calls++
+			return output.Success(map[string]any{"changed": true}), nil
+		},
+	})
+	cmd.SetArgs(nil)
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "without an active unified-result rollout") {
+		t.Fatalf("Execute error=%v", err)
+	}
+	if calls != 0 {
+		t.Fatalf("business dispatcher ran %d time(s), want 0", calls)
+	}
+}
@@ -54,7 +54,11 @@ func TestCrossPlatformCoverageDiagnosticsAndErrorRenderingEdges(t *testing.T) {
 	t.Cleanup(func() { marshalErrorJSON = oldMarshal })
 	marshalErrorJSON = func(any, string, string) ([]byte, error) { return nil, stderrors.New("encode") }
 	out.Reset()
-	if err := PrintJSON(&out, err); err != nil || !strings.Contains(out.String(), "failed to encode") {
+	if err := PrintJSON(&out, err); err != nil ||
+		!strings.Contains(out.String(), `"code":5`) ||
+		!strings.Contains(out.String(), `"category":"internal"`) ||
+		strings.Contains(out.String(), `"outcome"`) ||
+		strings.Contains(out.String(), `"type"`) {
 		t.Fatalf("PrintJSON fallback = %q, %v", out.String(), err)
 	}

@@ -39,6 +39,41 @@ const (
 	CategoryValidation Category = "validation"
 	CategoryDiscovery  Category = "discovery"
 	CategoryInternal   Category = "internal"
+
+	// CategoryPartial is retained for source compatibility, but an error cannot
+	// reconstruct the per-item data required by a partial result. It therefore
+	// fails closed as internal; callers must use output.Partial for exit code 7.
+	CategoryPartial Category = "partial_failure"
+)
+
+// 退出码表（规划 v1.2 OQ-1 定案；契约规范 §4；轮10裁决⑬——保留现行码表，
+// 仅新增 partial_failure 专用码，不做 wire 破坏性重排）：
+//
+//	0  success / pending（异步受理不是失败）
+//	1  api            （CategoryAPI）
+//	2  auth           （CategoryAuth）
+//	3  validation     （CategoryValidation；confirmation_required 子类共享此码，
+//	                   以 reason/subtype 区分，AC-13）
+//	4  PAT            （PATError 专属，见 pat.go ExitCodePermission；Category 不占用）
+//	5  internal       （CategoryInternal 与兜底：非结构化错误、panic 收敛均归 5）
+//	6  discovery      （CategoryDiscovery）
+//	7  partial_failure（部分成功专用码，见 ExitCodePartial）
+//
+// ExitCodePartial is the partial-result exit code shared with internal/output.
+// It is not returned for CategoryPartial errors because they lack the typed
+// succeeded/failed/unknown payload required for an honest partial result.
+const ExitCodePartial = 7
+
+// 类别专属退出码常量（B171/B172，权威 = 规划 v1.2 OQ-1 定案，契约规范 §4）。
+// ExitCode() 的 switch 用内联字面量，本组常量由 exitcodes.go 的
+// exitCodeByCategory 映射表引用，值与内联字面量一一对应（同源不双轨）。
+// 修改任一值必须先同步 ExitCode() 的 switch 分支与 internal/output 侧码表。
+const (
+	ExitCodeAPI        = 1
+	ExitCodeAuth       = 2
+	ExitCodeValidation = 3
+	ExitCodeDiscovery  = 6
+	ExitCodeInternal   = 5
 )

 // Error is the structured repository-local error model for the Go rewrite.
@@ -83,6 +118,13 @@ type Option func(*Error)
 // ExitCodePermission and the exit-code table in docs/reference.md);
 // Discovery therefore uses 6 so hosts can tell "catalog lookup broke"
 // apart from "PAT permission insufficient".
+//
+// confirmation_required 是 validation 的子类而非独立类别（B171，AC-13，
+// 规划 v1.2 OQ-1 定案）：门禁拦截错误挂 CategoryValidation 并以
+// reason=confirmation_required 区分，与 validation 共享 rc=3。信封侧
+// internal/output exitCodeForErrorInfo 的「subtype 优先于 type、
+// confirmation_required 恒 3」规则与本表同源（轮10裁决⑬；远期独立码
+// 保留于规划 OQ-9，落地前不得双轨）。
 func (e *Error) ExitCode() int {
 	switch e.Category {
 	case CategoryAPI:
@@ -93,6 +135,10 @@ func (e *Error) ExitCode() int {
 		return 3
 	case CategoryDiscovery:
 		return 6
+	case CategoryPartial:
+		// An error has no per-item succeeded/failed/unknown data and therefore
+		// cannot truthfully represent partial_failure. Fail closed as internal.
+		return ExitCodeInternal
 	default:
 		return 5
 	}
@@ -149,6 +195,11 @@ func WithRetryable(retryable bool) Option {
 // WithRetryAfterSeconds records the server-recommended delay before a retry.
 // A zero delay is meaningful and is therefore preserved; negative values are
 // ignored as invalid server guidance.
+//
+// 本通道只存原值、不钳制（B195/B199，AC-24）：服务端给多少存多少，wire 上
+// retry_after_seconds 原样透传。transport 侧的 RetryMaxDelay 钳制只作用于
+// 重试延迟选择（retryDelayForAttempt），不得回写或截断本字段（B196 草案：
+// 钳制上限可配置化后仍须保持「钳制延迟、不钳制透传」双通道分离）。
 func WithRetryAfterSeconds(seconds int64) Option {
 	return func(err *Error) {
 		if seconds < 0 {
@@ -322,14 +373,17 @@ func ExitCode(err error) int {
 	return 5
 }

-// PrintJSON writes a machine-readable JSON error object.
+// PrintJSON writes the legacy machine-readable JSON error object.
+//
+// This wire predates the unified result framework and is intentionally kept
+// byte-compatible for commands whose rollout is legacy_only or dual_validate.
+// Unified commands publish outcome/type/subtype through internal/output only.
 func PrintJSON(w io.Writer, err error) error {
 	errorPayload := map[string]any{
 		"code":     ExitCode(err),
 		"category": category(err),
 		"message":  err.Error(),
 	}
-
 	var typed *Error
 	if stderrors.As(err, &typed) {
 		if typed.Reason != "" {
@@ -409,7 +463,7 @@ func PrintJSON(w io.Writer, err error) error {

 	data, marshalErr := marshalErrorJSON(payload, "", "  ")
 	if marshalErr != nil {
-		_, writeErr := fmt.Fprintf(w, "{\"error\":{\"code\":5,\"category\":\"internal\",\"message\":\"failed to encode error output\"}}\n")
+		_, writeErr := fmt.Fprintln(w, `{"error":{"code":5,"category":"internal","message":"failed to encode error output"}}`)
 		return writeErr
 	}

@@ -556,6 +610,12 @@ func serverGuidance(diag ServerDiagnostics) (string, string) {
 	return friendlyHint, actionURL
 }

+// ServerGuidance exposes the same recovery projection to repository-local
+// adapters so legacy JSON and unified-result errors stay semantically aligned.
+func ServerGuidance(diag ServerDiagnostics) (string, string) {
+	return serverGuidance(diag)
+}
+
 func safeServerActionURL(raw string) string {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
@@ -572,6 +632,9 @@ func safeServerActionURL(raw string) string {
 func category(err error) string {
 	var typed *Error
 	if stderrors.As(err, &typed) {
+		if typed.Category == CategoryPartial {
+			return string(CategoryInternal)
+		}
 		return string(typed.Category)
 	}
 	return string(CategoryInternal)
@@ -0,0 +1,60 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package errors
+
+import "testing"
+
+// TestErrorsExitCodeMapConsistentWithExitCode 是 B209 的 errors 侧同源锁定：
+// exitcodes.go 的 exitCodeByCategory 映射表必须与 ExitCode() 的 switch 分支
+// 逐类别一致（同源不双轨，契约 §4）。任一单边修改即失败，防止未来漂移。
+// output 侧同源锁定由 internal/output emitter_phase_c_test.go
+// TestExitCodeForEnvelopeSameSourceAsErrorsExitCode 交叉断言（B209）。
+func TestErrorsExitCodeMapConsistentWithExitCode(t *testing.T) {
+	t.Parallel()
+
+	cats := []Category{
+		CategoryAPI,
+		CategoryAuth,
+		CategoryValidation,
+		CategoryDiscovery,
+		CategoryInternal,
+		CategoryPartial,
+	}
+	for _, cat := range cats {
+		table := exitCodeByCategory[cat]
+		viaSwitch := (&Error{Category: cat, Message: "x"}).ExitCode()
+		if table != viaSwitch {
+			t.Fatalf("exitCodeByCategory[%q]=%d disagrees with ExitCode()=%d", cat, table, viaSwitch)
+		}
+	}
+}
+
+// TestErrorsExitCodeConstantsEqualMap 锁定类别专属常量与映射表值一致。
+func TestErrorsExitCodeConstantsEqualMap(t *testing.T) {
+	t.Parallel()
+
+	want := map[Category]int{
+		CategoryAPI:        ExitCodeAPI,
+		CategoryAuth:       ExitCodeAuth,
+		CategoryValidation: ExitCodeValidation,
+		CategoryDiscovery:  ExitCodeDiscovery,
+		CategoryInternal:   ExitCodeInternal,
+		CategoryPartial:    ExitCodeInternal,
+	}
+	for cat, wantCode := range want {
+		if got := exitCodeByCategory[cat]; got != wantCode {
+			t.Fatalf("exitCodeByCategory[%q]=%d, want %d", cat, got, wantCode)
+		}
+	}
+}
@@ -0,0 +1,442 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package errors
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestErrorsPrintJSONFieldInventory protects the published legacy error wire.
+// Unified type/subtype/outcome fields belong to internal/output and must not
+// leak into commands that have not migrated.
+func TestErrorsPrintJSONFieldInventory(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewAPI(
+		"too many requests",
+		WithReason("rate_limit"),
+		WithHint("wait and retry"),
+		WithRetryable(true),
+		WithRetryAfterSeconds(30),
+	)); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	got := b.String()
+
+	for _, want := range []string{
+		`"category": "api"`,
+		`"reason": "rate_limit"`,
+		`"code": 1`,
+		`"retryable": true`,
+		`"retry_after_seconds": 30`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing wire-stable field %s in %s", want, got)
+		}
+	}
+	// informational 组
+	for _, want := range []string{
+		`"message": "too many requests"`,
+		`"hint": "wait and retry"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing informational field %s in %s", want, got)
+		}
+	}
+	for _, forbidden := range []string{`"outcome"`, `"type"`, `"subtype"`} {
+		if strings.Contains(got, forbidden) {
+			t.Errorf("unified field %s leaked into legacy wire: %s", forbidden, got)
+		}
+	}
+}
+
+func TestErrorsPrintJSONLegacyWireGolden(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewValidation("missing", WithReason("missing_required_flags"))); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	want := "{\n  \"error\": {\n    \"category\": \"validation\",\n    \"code\": 3,\n    \"message\": \"missing\",\n    \"reason\": \"missing_required_flags\"\n  }\n}\n"
+	if got := b.String(); got != want {
+		t.Fatalf("legacy error wire changed\n got: %q\nwant: %q", got, want)
+	}
+}
+
+func TestErrorsPrintJSONReasonProjectionStaysLegacy(t *testing.T) {
+	t.Parallel()
+
+	t.Run("confirmation_required", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewValidation(
+			"confirmation required",
+			WithReason("confirmation_required"),
+		)); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		got := b.String()
+		if !strings.Contains(got, `"reason": "confirmation_required"`) {
+			t.Fatalf("expected confirmation_required reason, got %q", got)
+		}
+		if strings.Contains(got, `"subtype"`) || strings.Contains(got, `"type"`) {
+			t.Fatalf("unified fields leaked into legacy wire: %q", got)
+		}
+	})
+
+	t.Run("no reason omits reason", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("plain")); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if strings.Contains(b.String(), `"reason"`) {
+			t.Fatalf("reason must be omitted when Reason is empty, got %q", b.String())
+		}
+	})
+}
+
+// TestErrorsConfirmationSharesValidationExitCode 是 B171 的契约断言：
+// confirmation_required 是 validation 的子类，共享 rc=3（AC-13，规划 v1.2
+// OQ-1 定案），靠 error.subtype 区分，而非独立退出码。
+func TestErrorsConfirmationSharesValidationExitCode(t *testing.T) {
+	t.Parallel()
+
+	confirmation := NewValidation("blocked", WithReason("confirmation_required"))
+	validation := NewValidation("bad param")
+
+	if got := ExitCode(confirmation); got != 3 {
+		t.Fatalf("confirmation ExitCode = %d, want 3 (shared with validation)", got)
+	}
+	if got := ExitCode(validation); got != 3 {
+		t.Fatalf("validation ExitCode = %d, want 3", got)
+	}
+	// Legacy reason distinguishes the confirmation subtype.
+	var b strings.Builder
+	if err := PrintJSON(&b, confirmation); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	if !strings.Contains(b.String(), `"reason": "confirmation_required"`) {
+		t.Fatalf("confirmation must carry reason, got %q", b.String())
+	}
+}
+
+func TestErrorsPartialCategoryFailsClosedAsInternal(t *testing.T) {
+	t.Parallel()
+
+	err := &Error{Category: CategoryPartial, Message: "partial"}
+	if got := ExitCode(err); got != ExitCodeInternal {
+		t.Fatalf("ExitCode(partial error) = %d, want internal %d", got, ExitCodeInternal)
+	}
+	if ExitCodePartial != 7 {
+		t.Fatalf("ExitCodePartial = %d, want 7", ExitCodePartial)
+	}
+	var b strings.Builder
+	if err := PrintJSON(&b, err); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	if !strings.Contains(b.String(), `"code": 5`) || !strings.Contains(b.String(), `"category": "internal"`) {
+		t.Fatalf("partial error must not masquerade as a partial result: %q", b.String())
+	}
+}
+
+func TestErrorsPrintJSONKeepsLegacyCategories(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		err  error
+		want string
+	}{
+		{"api", NewAPI("x"), "api"},
+		{"auth", NewAuth("x"), "auth"},
+		{"validation", NewValidation("x"), "validation"},
+		{"discovery", NewDiscovery("x"), "discovery"},
+		{"internal", NewInternal("x"), "internal"},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			var b strings.Builder
+			if err := PrintJSON(&b, tc.err); err != nil {
+				t.Fatalf("PrintJSON() error = %v", err)
+			}
+			got := b.String()
+			if !strings.Contains(got, `"category": "`+tc.want+`"`) {
+				t.Fatalf("expected legacy category %q in %s", tc.want, got)
+			}
+			if strings.Contains(got, `"type"`) {
+				t.Fatalf("unified type leaked into legacy JSON: %s", got)
+			}
+		})
+	}
+}
+
+// TestErrorsWireStableFieldsSubset protects the legacy recovery fields that
+// remain useful without changing the top-level envelope.
+func TestErrorsWireStableFieldsSubset(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewAPI(
+		"rpc failed",
+		WithReason("rate_limit"),
+		WithHint("h"),
+		WithRetryable(true),
+		WithRetryAfterSeconds(5),
+		WithActions("retry"),
+		WithServerDiag(ServerDiagnostics{TraceID: "t-1"}),
+		WithRPCCode(-32602),
+		WithRPCData([]byte(`{"field":"x"}`)),
+	)); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	got := b.String()
+	for _, want := range []string{
+		`"category"`, `"reason"`, `"code"`, `"retryable"`, `"retry_after_seconds"`,
+		`"message"`, `"hint"`, `"actions"`, `"trace_id"`, `"rpc_code"`, `"rpc_data"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("wire-stable field %s missing from %s", want, got)
+		}
+	}
+}
+
+// TestErrorsRetryableOmitEmpty 是 B175 的断言：retryable 仅 true 时出现在 wire
+// （与 output 侧 ErrorInfo.Retryable omitempty 一致）；未知三态（RetryableSet
+// 未置）时 retryable 缺席。
+func TestErrorsRetryableOmitEmpty(t *testing.T) {
+	t.Parallel()
+
+	t.Run("true present", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("x", WithRetryable(true))); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if !strings.Contains(b.String(), `"retryable": true`) {
+			t.Fatalf("expected retryable:true, got %q", b.String())
+		}
+	})
+	t.Run("unset omitted", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("x")); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if strings.Contains(b.String(), `"retryable"`) {
+			t.Fatalf("unknown retryability must be omitted, got %q", b.String())
+		}
+	})
+}
+
+// TestErrorsCategorySnapshots 是 B176/B177 的类别错误信封快照测试：api/auth/
+// validation（B176）与 discovery/internal/plain（B177）各自产出 stable 的
+// type/code 组合，plain 错误归 internal（rc=5）。
+func TestErrorsCategorySnapshots(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name     string
+		err      error
+		category string
+		code     string
+	}{
+		{"api", NewAPI("x"), "api", `"code": 1`},
+		{"auth", NewAuth("x"), "auth", `"code": 2`},
+		{"validation", NewValidation("x"), "validation", `"code": 3`},
+		{"discovery", NewDiscovery("x"), "discovery", `"code": 6`},
+		{"internal", NewInternal("x"), "internal", `"code": 5`},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			var b strings.Builder
+			if err := PrintJSON(&b, tc.err); err != nil {
+				t.Fatalf("PrintJSON() error = %v", err)
+			}
+			got := b.String()
+			if !strings.Contains(got, `"category": "`+tc.category+`"`) || !strings.Contains(got, tc.code) {
+				t.Fatalf("snapshot mismatch for %s: %s", tc.name, got)
+			}
+		})
+	}
+}
+
+// TestErrorsActionsArrayPassthrough 是 B178 的 actions 数组透传断言：Actions
+// （含 --yes 版本补救命令）原样进 wire，空串条目被过滤。
+func TestErrorsActionsArrayPassthrough(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewValidation(
+		"confirm required",
+		WithReason("confirmation_required"),
+		WithActions("dws chat send --yes", "", "dws chat cancel"),
+	)); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	got := b.String()
+	for _, want := range []string{
+		`"actions"`,
+		`"dws chat send --yes"`,
+		`"dws chat cancel"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("expected %s in actions, got %q", want, got)
+		}
+	}
+	// 空串条目被过滤：不应出现空引号动作。
+	if strings.Contains(got, `""`) {
+		t.Fatalf("empty action must be filtered, got %q", got)
+	}
+}
+
+// TestErrorsTraceRPCAndServerDiagPassthrough 是 B179 的透传保留断言：
+// trace_id/rpc_code/rpc_data 原样保留在 wire（informational，不进分支字段），
+// 与 output 侧 ErrorInfo 的 ServerDiag/RPC 字段对齐。
+func TestErrorsTraceRPCAndServerDiagPassthrough(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewAPI(
+		"rpc failed",
+		WithServerDiag(ServerDiagnostics{TraceID: "trace-abc"}),
+		WithRPCCode(-32602),
+		WithRPCData([]byte(`{"field":"base_id"}`)),
+	)); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	got := b.String()
+	for _, want := range []string{
+		`"trace_id": "trace-abc"`,
+		`"rpc_code": -32602`,
+		`"field"`,
+		`"base_id"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("expected %s in %s", want, got)
+		}
+	}
+}
+
+func TestErrorsLegacyPrintJSONOmitsUnifiedOutcome(t *testing.T) {
+	t.Parallel()
+
+	var b strings.Builder
+	if err := PrintJSON(&b, NewInternal("x")); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	if strings.Contains(b.String(), `"outcome"`) {
+		t.Fatalf("legacy error JSON must not carry unified outcome, got %q", b.String())
+	}
+}
+
+// TestWithRetryAfterSecondsPassthrough 是 B195 的透传断言：WithRetryAfterSeconds
+// 把服务端给出的秒数原样存入 RetryAfterSeconds，不做任何钳制（钳制只作用于
+// transport 重试延迟选择，B196 双通道分离）。
+func TestWithRetryAfterSecondsPassthrough(t *testing.T) {
+	t.Parallel()
+
+	err := NewAPI("limit", WithRetryAfterSeconds(900)).(*Error)
+	if err.RetryAfterSeconds == nil || *err.RetryAfterSeconds != 900 {
+		t.Fatalf("RetryAfterSeconds = %v, want 900 (unclamped)", err.RetryAfterSeconds)
+	}
+}
+
+// TestRetryAfterZeroValuePreserved 是 B198 的零值语义断言：0 秒是有意义的
+// 服务端建议（立即重试），必须保留；负值被视为非法服务端指引而被拒绝
+// （WithRetryAfterSeconds 忽略负值）。
+func TestRetryAfterZeroValuePreserved(t *testing.T) {
+	t.Parallel()
+
+	zero := NewAPI("x", WithRetryAfterSeconds(0)).(*Error)
+	if zero.RetryAfterSeconds == nil || *zero.RetryAfterSeconds != 0 {
+		t.Fatalf("zero RetryAfterSeconds must be preserved, got %v", zero.RetryAfterSeconds)
+	}
+
+	negative := NewAPI("x", WithRetryAfterSeconds(-1)).(*Error)
+	if negative.RetryAfterSeconds != nil {
+		t.Fatalf("negative RetryAfterSeconds must be rejected, got %v", *negative.RetryAfterSeconds)
+	}
+}
+
+// TestRetryAfterSecondsWirePassthrough 是 B199 的 wire 透传断言：retry_after_seconds
+// 在 PrintJSON 错误 JSON 中原样出现，值未被 transport 钳制改写（0 秒也透传）。
+func TestRetryAfterSecondsWirePassthrough(t *testing.T) {
+	t.Parallel()
+
+	t.Run("nonzero", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("x", WithRetryAfterSeconds(60))); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if !strings.Contains(b.String(), `"retry_after_seconds": 60`) {
+			t.Fatalf("expected retry_after_seconds:60 in wire, got %q", b.String())
+		}
+	})
+	t.Run("zero preserved", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("x", WithRetryAfterSeconds(0))); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if !strings.Contains(b.String(), `"retry_after_seconds": 0`) {
+			t.Fatalf("expected retry_after_seconds:0 preserved in wire, got %q", b.String())
+		}
+	})
+	t.Run("unset omitted", func(t *testing.T) {
+		var b strings.Builder
+		if err := PrintJSON(&b, NewAPI("x")); err != nil {
+			t.Fatalf("PrintJSON() error = %v", err)
+		}
+		if strings.Contains(b.String(), `"retry_after_seconds"`) {
+			t.Fatalf("retry_after_seconds must be omitted when unset, got %q", b.String())
+		}
+	})
+}
+
+// TestRetryAfterSecondsAndNextRetryAtConsistency 是 B200 的一致性断言：
+// RetryAfterSeconds 与 NextRetryAt 两字段同源（都描述"何时可重试"）且可共存
+// 不互斥；Promise 使用 UTC 归一化（NextRetryAt 转 UTC）。
+func TestRetryAfterSecondsAndNextRetryAtConsistency(t *testing.T) {
+	t.Parallel()
+
+	tz := time.FixedZone("CST", 8*60*60)
+	next := time.Date(2026, time.August, 7, 22, 0, 0, 0, tz)
+	err := NewAPI("x", WithRetryAfterSeconds(30), WithNextRetryAt(next)).(*Error)
+	if err.RetryAfterSeconds == nil || *err.RetryAfterSeconds != 30 {
+		t.Fatalf("RetryAfterSeconds = %v, want 30", err.RetryAfterSeconds)
+	}
+	if err.NextRetryAt == nil {
+		t.Fatal("NextRetryAt must be set")
+	}
+	// 两字段同源并存（B200），NextRetryAt 归一化为 UTC。
+	if got := err.NextRetryAt.UTC().Format(time.RFC3339); got != "2026-08-07T14:00:00Z" {
+		t.Fatalf("NextRetryAt UTC = %s, want 2026-08-07T14:00:00Z", got)
+	}
+
+	// wire 上两字段同现且互不覆盖。
+	var b strings.Builder
+	if err := PrintJSON(&b, err); err != nil {
+		t.Fatalf("PrintJSON() error = %v", err)
+	}
+	got := b.String()
+	if !strings.Contains(got, `"retry_after_seconds": 30`) {
+		t.Fatalf("missing retry_after_seconds:30 in %s", got)
+	}
+	if !strings.Contains(got, `"next_retry_at": "2026-08-07T14:00:00Z"`) {
+		t.Fatalf("missing next_retry_at in %s", got)
+	}
+}
@@ -341,6 +341,18 @@ func TestCrossPlatformCoveragePrintHumanIncludesServerGuidance(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageServerGuidanceAdapter(t *testing.T) {
+	t.Parallel()
+
+	hint, action := ServerGuidance(ServerDiagnostics{
+		FriendlyHint: "follow the recovery action",
+		ActionURL:    "https://example.test/recover",
+	})
+	if hint != "follow the recovery action" || action != "https://example.test/recover" {
+		t.Fatalf("ServerGuidance() = (%q, %q)", hint, action)
+	}
+}
+
 func TestCrossPlatformCoverageServerGuidanceSuppressesUnsafeActionURL(t *testing.T) {
 	t.Parallel()
 	for _, actionURL := range []string{
@@ -0,0 +1,18 @@
+package errors
+
+// 统一退出码表（B171/B172；轮 10 裁决⑬，权威 = 规划 v1.2 OQ-1 定案）：
+// 类别与退出码一一对应，`confirmation_required` 是 `validation` 下的子类
+// 共享 3，不新增独立退出码。
+//
+// 跨包同源锁定：internal/output.ExitCodeForEnvelope 对同一信封必须给出
+// 本表完全一致的码（api=1/auth=2/validation=3/discovery=6/internal=5）。
+// Typed output.Partial remains the only path to partial_failure exit 7.
+// 修改本表 = 契约变更，必须双侧同步并更新两侧同源测试。
+var exitCodeByCategory = map[Category]int{
+	CategoryAPI:        ExitCodeAPI,
+	CategoryAuth:       ExitCodeAuth,
+	CategoryValidation: ExitCodeValidation,
+	CategoryDiscovery:  ExitCodeDiscovery,
+	CategoryInternal:   ExitCodeInternal,
+	CategoryPartial:    ExitCodeInternal,
+}
@@ -0,0 +1,41 @@
+package errors
+
+// 错误信封 wire-stable 字段集（契约规范 §2.4；B174）。
+//
+// Agent 可编程分流的字段集合：type/subtype/code/retryable/
+// retry_after_seconds/message/hint/actions/trace_id/rpc_code/rpc_data/
+// outcome。wireErrors 的每个字段都必须落在此集合内；新增字段 = 契约
+// 扩展，需评审。wireErrors 未声明 JSON tag 的字段（如 Cause）是内部
+// 字段，序列化缺席，不属于 wire。
+
+// WireStableFields 是错误信封 wire-stable 字段名全集（含 outcome）。
+var WireStableFields = []string{
+	"type",
+	"subtype",
+	"code",
+	"retryable",
+	"retry_after_seconds",
+	"message",
+	"hint",
+	"actions",
+	"trace_id",
+	"rpc_code",
+	"rpc_data",
+	"outcome",
+}
+
+// WireStableErrorBodyFields 是 error 对象体（不含顶层 outcome）的
+// wire-stable 字段名子集。
+var WireStableErrorBodyFields = []string{
+	"type",
+	"subtype",
+	"code",
+	"retryable",
+	"retry_after_seconds",
+	"message",
+	"hint",
+	"actions",
+	"trace_id",
+	"rpc_code",
+	"rpc_data",
+}
@@ -17,6 +17,7 @@ import (

 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	eventlock "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/lock"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )

@@ -324,6 +325,21 @@ func TestCrossPlatformCoverageRunStartupAndSourceEdges(t *testing.T) {
 	if err := Run(context.Background(), base); !errors.Is(err, errBusInjected) {
 		t.Fatalf("source error = %v", err)
 	}
+
+	runtimeWorkDir := shortTempDir(t)
+	base.WorkDir = runtimeWorkDir
+	base.IPCEndpoint = dwsevent.IPCEndpoint(
+		runtimeWorkDir,
+		"open",
+		dwsevent.SourceKindPersonalStream,
+		dwsevent.IdentityHash(runtimeWorkDir),
+	)
+	base.Source = edgeSource{start: func(context.Context, dwsevent.EmitFn) error {
+		return runtimecred.ErrRuntimeTokenRejected
+	}}
+	if err := Run(context.Background(), base); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		t.Fatalf("runtime source error = %v", err)
+	}
 }

 type scriptedListener struct {
@@ -0,0 +1,275 @@
+package bus
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"net"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+func eventCoreDaemon(broker *runtimecred.Broker) *daemon {
+	return &daemon{
+		cfg:      Config{CredentialBroker: broker, IdleTimeout: time.Second},
+		log:      slog.New(slog.NewTextHandler(io.Discard, nil)),
+		hub:      NewHub(4),
+		started:  time.Now(),
+		idleStop: make(chan struct{}),
+	}
+}
+
+func eventCoreConnection(d *daemon, wrap func(net.Conn) net.Conn) (net.Conn, *transport.Writer, *transport.Reader, <-chan struct{}) {
+	server, client := net.Pipe()
+	if wrap != nil {
+		server = wrap(server)
+	}
+	done := make(chan struct{})
+	go func() {
+		d.handleConnection(context.Background(), server)
+		close(done)
+	}()
+	return client, transport.NewWriter(client), transport.NewReader(client), done
+}
+
+func eventCoreWaitDone(t *testing.T, done <-chan struct{}) {
+	t.Helper()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("connection handler did not stop")
+	}
+}
+
+type eventCoreWriteHookConn struct {
+	net.Conn
+	writes int
+	hook   func(int)
+}
+
+func (c *eventCoreWriteHookConn) Write(p []byte) (int, error) {
+	n, err := c.Conn.Write(p)
+	c.writes++
+	if err == nil && c.hook != nil {
+		c.hook(c.writes)
+	}
+	return n, err
+}
+
+func TestCrossPlatformCoverageEventCoreDaemonHandshakeEdges(t *testing.T) {
+	t.Run("incompatible ack write failure", func(t *testing.T) {
+		d := eventCoreDaemon(nil)
+		client, w, _, done := eventCoreConnection(d, nil)
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: "unsupported"}); err != nil {
+			t.Fatal(err)
+		}
+		_ = client.Close()
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("runtime ack write failure", func(t *testing.T) {
+		d := eventCoreDaemon(runtimecred.New(runtimecred.Config{}))
+		client, w, _, done := eventCoreConnection(d, nil)
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		_ = client.Close()
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("terminal runtime hello", func(t *testing.T) {
+		d := eventCoreDaemon(runtimecred.New(runtimecred.Config{}))
+		d.setTerminalReason(transport.ByeReasonRuntimeTokenRejected)
+		client, w, r, done := eventCoreConnection(d, nil)
+		defer client.Close()
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil || ack.TerminalReason != transport.ByeReasonRuntimeTokenRejected {
+			t.Fatalf("terminal ack = %#v, %v", ack, err)
+		}
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("malformed credential update", func(t *testing.T) {
+		d := eventCoreDaemon(runtimecred.New(runtimecred.Config{}))
+		client, w, r, done := eventCoreConnection(d, nil)
+		defer client.Close()
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := client.Write([]byte("{\n")); err != nil {
+			t.Fatal(err)
+		}
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("unexpected credential update", func(t *testing.T) {
+		d := eventCoreDaemon(runtimecred.New(runtimecred.Config{}))
+		client, w, r, done := eventCoreConnection(d, nil)
+		defer client.Close()
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil {
+			t.Fatal(err)
+		}
+		if err := w.WriteJSON(transport.Heartbeat{Type: transport.FrameTypeHeartbeat}); err != nil {
+			t.Fatal(err)
+		}
+		var updateAck transport.CredentialUpdateAck
+		if err := r.ReadJSON(&updateAck); err != nil || updateAck.ErrorCode != transport.CredentialErrorInvalid {
+			t.Fatalf("unexpected-frame ack = %#v, %v", updateAck, err)
+		}
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("credential ack write failure", func(t *testing.T) {
+		d := eventCoreDaemon(runtimecred.New(runtimecred.Config{}))
+		client, w, r, done := eventCoreConnection(d, nil)
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil {
+			t.Fatal(err)
+		}
+		if err := w.WriteJSON(transport.CredentialUpdate{
+			Type: transport.FrameTypeCredentialUpdate, ExpectedGeneration: ack.CredentialGeneration, Token: "token",
+		}); err != nil {
+			t.Fatal(err)
+		}
+		_ = client.Close()
+		eventCoreWaitDone(t, done)
+	})
+
+	t.Run("activation conflict", func(t *testing.T) {
+		broker := runtimecred.New(runtimecred.Config{RequireSeed: true, RequireActivation: true})
+		d := eventCoreDaemon(broker)
+		client, w, r, done := eventCoreConnection(d, func(conn net.Conn) net.Conn {
+			return &eventCoreWriteHookConn{Conn: conn, hook: func(write int) {
+				if write == 2 {
+					_, _ = broker.Update(1, "newer-token")
+				}
+			}}
+		})
+		defer client.Close()
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, CredentialMode: transport.CredentialModeRuntimeToken}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil {
+			t.Fatal(err)
+		}
+		if err := w.WriteJSON(transport.CredentialUpdate{Type: transport.FrameTypeCredentialUpdate, Token: "first-token"}); err != nil {
+			t.Fatal(err)
+		}
+		var updateAck transport.CredentialUpdateAck
+		if err := r.ReadJSON(&updateAck); err != nil || !updateAck.Accepted {
+			t.Fatalf("credential ack = %#v, %v", updateAck, err)
+		}
+		var bye transport.Bye
+		if err := r.ReadJSON(&bye); err != nil || bye.Reason != "runtime_credential_activation_failed" {
+			t.Fatalf("activation failure bye = %#v, %v", bye, err)
+		}
+		eventCoreWaitDone(t, done)
+	})
+}
+
+func TestCrossPlatformCoverageEventCoreDaemonWriterStopEdges(t *testing.T) {
+	originalProcs := runtime.GOMAXPROCS(1)
+	t.Cleanup(func() { runtime.GOMAXPROCS(originalProcs) })
+
+	run := func(t *testing.T, queueEvent bool) {
+		t.Helper()
+		d := eventCoreDaemon(nil)
+		client, w, r, done := eventCoreConnection(d, nil)
+		defer client.Close()
+		if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, SubscribeID: "writer-stop"}); err != nil {
+			t.Fatal(err)
+		}
+		var ack transport.HelloAck
+		if err := r.ReadJSON(&ack); err != nil {
+			t.Fatal(err)
+		}
+		deadline := time.Now().Add(time.Second)
+		for d.hub.Len() != 1 && time.Now().Before(deadline) {
+			time.Sleep(time.Millisecond)
+		}
+		time.Sleep(5 * time.Millisecond)
+		d.hub.mu.RLock()
+		var consumer *Consumer
+		for _, candidate := range d.hub.consumers {
+			consumer = candidate
+		}
+		d.hub.mu.RUnlock()
+		if consumer == nil {
+			t.Fatal("consumer not registered")
+		}
+		if queueEvent {
+			consumer.SendCh <- transport.Heartbeat{Type: transport.FrameTypeHeartbeat}
+		}
+		consumer.StopCh <- "writer-stop"
+		var bye transport.Bye
+		if err := r.ReadJSON(&bye); err != nil || bye.Reason != "writer-stop" {
+			t.Fatalf("writer stop bye = %#v, %v", bye, err)
+		}
+		eventCoreWaitDone(t, done)
+	}
+
+	t.Run("recheck after event", func(t *testing.T) { run(t, true) })
+	t.Run("blocked stop select", func(t *testing.T) { run(t, false) })
+}
+
+func TestCrossPlatformCoverageEventCoreDaemonHelpersAndStopAll(t *testing.T) {
+	var nilDaemon *daemon
+	nilDaemon.setTerminalReason("ignored")
+	if nilDaemon.getTerminalReason() != "" {
+		t.Fatal("nil daemon returned terminal reason")
+	}
+	d := eventCoreDaemon(nil)
+	d.setTerminalReason("ignored")
+	if d.getTerminalReason() != "" {
+		t.Fatal("invalid terminal reason was stored")
+	}
+	d.setTerminalReason(transport.ByeReasonRuntimeTokenRejected)
+	if d.getTerminalReason() != transport.ByeReasonRuntimeTokenRejected {
+		t.Fatal("terminal reason was not stored")
+	}
+
+	if code, _ := classifyCredentialUpdateError(runtimecred.ErrEmptyToken); code != transport.CredentialErrorInvalid {
+		t.Fatalf("empty-token classification = %q", code)
+	}
+	if code, message := classifyCredentialUpdateError(errors.New("internal detail")); code != transport.CredentialErrorInternal || message != "runtime credential update failed" {
+		t.Fatalf("internal classification = %q, %q", code, message)
+	}
+
+	hub := NewHub(1)
+	consumer, err := hub.Register(transport.Hello{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stopped := hub.StopAll("   "); stopped != 1 {
+		t.Fatalf("StopAll = %d", stopped)
+	}
+	select {
+	case reason := <-consumer.StopCh:
+		if reason != "shutdown" {
+			t.Fatalf("default stop reason = %q", reason)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("default stop reason not delivered")
+	}
+	hub.Unregister(consumer.ID)
+}
@@ -30,6 +30,7 @@ import (

 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/dedup"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 )
@@ -78,6 +79,11 @@ type Config struct {
 	// Source is the cloud adapter. Required.
 	Source SourceAdapter

+	// CredentialBroker enables additive runtime-token handoff over the
+	// owner-only local IPC transport. Nil preserves the original protocol and
+	// does not advertise runtime-token support.
+	CredentialBroker *runtimecred.Broker
+
 	// IdleTimeout: bus self-exits after this long with zero consumers.
 	// Zero disables (bus runs until SIGTERM).
 	IdleTimeout time.Duration
@@ -106,11 +112,13 @@ type Config struct {
 }

 var (
-	daemonMkdirAll        = os.MkdirAll
-	daemonAcquire         = Acquire
-	daemonWriteMeta       = WriteMeta
-	daemonListen          = transport.Listen
-	daemonShutdownTimeout = 2 * time.Second
+	daemonMkdirAll                   = os.MkdirAll
+	daemonAcquire                    = Acquire
+	daemonWriteMeta                  = WriteMeta
+	daemonListen                     = transport.Listen
+	daemonShutdownTimeout            = 2 * time.Second
+	daemonByeDrainTimeout            = 100 * time.Millisecond
+	daemonCredentialHandshakeTimeout = 10 * time.Second
 )

 // Run starts the bus daemon. Lifecycle (plan §4 invariant #6):
@@ -237,12 +245,22 @@ func Run(ctx context.Context, cfg Config) error {

 	// 6. Wait for shutdown trigger.
 	var exitErr error
+	shutdownReason := "shutdown"
 	select {
 	case <-ctx.Done():
 		log.Info("bus: shutdown requested by ctx", "reason", ctx.Err())
 	case err := <-srcErr:
 		log.Error("bus: source exited", "err", err)
 		exitErr = err
+		shutdownReason = sourceShutdownReason(err)
+		if shutdownReason == transport.ByeReasonRuntimeTokenRejected {
+			// A runtime token can fail immediately after Broker.Update. Serialize
+			// terminal publication with that handshake so the initiating consumer
+			// is registered (or receives a terminal HelloAck) before shutdown.
+			d.credentialHandoffMu.Lock()
+			d.setTerminalReason(shutdownReason)
+			d.credentialHandoffMu.Unlock()
+		}
 	case <-d.idleStop:
 		log.Info("bus: idle timeout reached, shutting down")
 	}
@@ -252,7 +270,7 @@ func Run(ctx context.Context, cfg Config) error {
 	// consumers. The accept-loop barrier is required before WaitGroup.Wait:
 	// sync.WaitGroup forbids a positive Add racing with Wait.
 	cancelRun()
-	d.shutdown(acceptDone)
+	d.shutdown(acceptDone, shutdownReason)
 	<-idleDone
 	<-dropWarnDone

@@ -274,6 +292,10 @@ type daemon struct {
 	shutdownMu   sync.Mutex
 	shuttingDown atomic.Bool
 	idleStop     chan struct{}
+
+	credentialHandoffMu sync.Mutex
+	terminalMu          sync.RWMutex
+	terminalReason      string
 }

 // closeOnceConn makes every connection close path idempotent. A live consumer
@@ -330,7 +352,8 @@ func (d *daemon) acceptLoop(ctx context.Context) {
 }

 // handleConnection processes one IPC connection's full lifecycle: read
-// Hello → register with Hub → spawn writer goroutine → read until EOF/Bye.
+// Hello → optional runtime credential negotiation → register with Hub → spawn
+// writer goroutine → read until EOF/Bye.
 // Always Unregisters and Closes on exit (plan invariant #5).
 func (d *daemon) handleConnection(ctx context.Context, conn net.Conn) {
 	conn = ensureCloseOnce(conn)
@@ -372,29 +395,141 @@ func (d *daemon) handleConnection(ctx context.Context, conn net.Conn) {
 		return
 	}

-	// Regular consumer registration
+	// HelloAck — credentials_source fields are filled in by the daemon
+	// runner (which knows from the strict resolver) and exposed via the
+	// adapter for forward-compat. v1 leaves them empty here; daemon.Run
+	// passes them through future config if the caller wishes.
+	ack := d.helloAck()
+	handoffLocked := false
+	runtimeGeneration := uint64(0)
+	defer func() {
+		if handoffLocked {
+			d.credentialHandoffMu.Unlock()
+		}
+	}()
+
+	// Runtime credentials use a two-phase additive handshake. The first ack
+	// proves capability before the client sends any secret. Only a successful
+	// CAS and credential ack permit Hub registration.
+	if hello.CredentialMode != "" {
+		if hello.CredentialMode != transport.CredentialModeRuntimeToken || d.cfg.CredentialBroker == nil {
+			ack.Capabilities = nil
+			ack.CredentialGeneration = 0
+			if err := w.WriteJSON(ack); err != nil {
+				d.log.Warn("bus: incompatible helloack write failed", "err", err)
+			}
+			return
+		}
+		d.credentialHandoffMu.Lock()
+		handoffLocked = true
+		// Terminal state may have been published while this Hello waited for a
+		// concurrent credential handoff. Rebuild the ack while holding the gate.
+		ack = d.helloAck()
+		if err := w.WriteJSON(ack); err != nil {
+			d.log.Warn("bus: runtime helloack write failed", "err", err)
+			return
+		}
+		if ack.TerminalReason == transport.ByeReasonRuntimeTokenRejected {
+			return
+		}
+
+		var update transport.CredentialUpdate
+		_ = conn.SetReadDeadline(time.Now().Add(daemonCredentialHandshakeTimeout))
+		if err := r.ReadJSON(&update); err != nil {
+			// Do not include the decoder error: malformed JSON may contain
+			// fragments of the credential.
+			d.log.Warn("bus: malformed runtime credential update")
+			return
+		}
+		_ = conn.SetReadDeadline(time.Time{})
+		if update.Type != transport.FrameTypeCredentialUpdate {
+			_ = w.WriteJSON(transport.CredentialUpdateAck{
+				Type:                 transport.FrameTypeCredentialUpdateAck,
+				Accepted:             false,
+				CredentialGeneration: d.cfg.CredentialBroker.Generation(),
+				ErrorCode:            transport.CredentialErrorInvalid,
+				Error:                "unexpected credential update frame",
+			})
+			return
+		}
+		// Validate registration before applying the credential or sending an
+		// accepted ack. Hub.Register performs the same deterministic compile
+		// before mutating the Hub; this preflight keeps invalid filters from
+		// producing a ready marker after credential negotiation.
+		if _, err := compileMatcher(hello.EventTypes, hello.Filter, hello.SubscribeID); err != nil {
+			update.Token = ""
+			_ = w.WriteJSON(transport.CredentialUpdateAck{
+				Type:                 transport.FrameTypeCredentialUpdateAck,
+				Accepted:             false,
+				CredentialGeneration: d.cfg.CredentialBroker.Generation(),
+				ErrorCode:            transport.CredentialErrorRegistration,
+				Error:                "consumer registration validation failed",
+			})
+			d.log.Warn("bus: runtime consumer registration validation failed")
+			return
+		}
+
+		generation, updateErr := d.cfg.CredentialBroker.Update(update.ExpectedGeneration, update.Token)
+		runtimeGeneration = generation
+		update.Token = ""
+		credentialAck := transport.CredentialUpdateAck{
+			Type:                 transport.FrameTypeCredentialUpdateAck,
+			Accepted:             updateErr == nil,
+			CredentialGeneration: generation,
+		}
+		if updateErr != nil {
+			credentialAck.ErrorCode, credentialAck.Error = classifyCredentialUpdateError(updateErr)
+		}
+		if err := w.WriteJSON(credentialAck); err != nil {
+			d.log.Warn("bus: credential update ack write failed", "err", err)
+			return
+		}
+		if updateErr != nil {
+			d.log.Warn("bus: runtime credential update rejected", "error_code", credentialAck.ErrorCode)
+			return
+		}
+	}
+
+	// Regular consumer registration. Local clients retain the original
+	// register-before-HelloAck ordering; runtime clients were already acked by
+	// the additive handshake above.
 	c, err := d.hub.Register(hello)
 	if err != nil {
 		d.log.Warn("bus: register failed", "err", err, "pid", hello.ConsumerPID)
 		_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "register_failed: " + err.Error()})
 		return
 	}
-
-	// HelloAck — credentials_source fields are filled in by the daemon
-	// runner (which knows from the strict resolver) and exposed via the
-	// adapter for forward-compat. v1 leaves them empty here; daemon.Run
-	// passes them through future config if the caller wishes.
-	idleSecs := int(d.cfg.IdleTimeout / time.Second)
-	if err := w.WriteJSON(transport.HelloAck{
-		Type:            transport.FrameTypeHelloAck,
-		BusPID:          os.Getpid(),
-		SourceState:     "connected", // best-effort; full state machine pushed via SourceState frames
-		StateSource:     "inferred",
-		IdleTimeoutSecs: idleSecs,
-	}); err != nil {
-		d.log.Warn("bus: helloack write failed", "err", err)
+	if handoffLocked {
+		// The runtime broker deliberately keeps the seed pending until the
+		// initiating consumer is registered. This prevents ticket acquisition
+		// (and an immediate 401) from racing ahead of the only connection that
+		// can observe the typed terminal reason.
+		if _, activateErr := d.cfg.CredentialBroker.Activate(runtimeGeneration); activateErr != nil {
+			d.log.Error("bus: runtime credential activation failed")
+			_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "runtime_credential_activation_failed"})
+			d.hub.Unregister(c.ID)
+			return
+		}
+	}
+	// A local/legacy consumer can arrive after terminal publication but after
+	// StopAll took its snapshot. Refuse it synchronously so it cannot observe a
+	// clean EOF for a runtime-token rejection.
+	if terminalReason := d.getTerminalReason(); terminalReason != "" {
+		_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: terminalReason})
+		d.hub.Unregister(c.ID)
 		return
 	}
+	if handoffLocked {
+		d.credentialHandoffMu.Unlock()
+		handoffLocked = false
+	}
+	if hello.CredentialMode == "" {
+		if err := w.WriteJSON(ack); err != nil {
+			d.log.Warn("bus: helloack write failed", "err", err)
+			d.hub.Unregister(c.ID)
+			return
+		}
+	}

 	// Writer goroutine pulls from SendCh and writes to the wire.
 	writerDone := make(chan struct{})
@@ -416,6 +551,16 @@ func (d *daemon) handleConnection(ctx context.Context, conn net.Conn) {
 				if !ok {
 					return
 				}
+				// A stop may have arrived while both channels were ready and the
+				// scheduler selected the buffered event. Re-check before starting a
+				// potentially blocking event write so terminal reasons stay prompt.
+				select {
+				case reason := <-c.StopCh:
+					_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: reason})
+					_ = conn.Close()
+					return
+				default:
+				}
 				if err := w.WriteJSON(frame); err != nil {
 					return
 				}
@@ -454,6 +599,51 @@ func (d *daemon) handleConnection(ctx context.Context, conn net.Conn) {
 	_ = ctx // for future use (writer ctx-cancel propagation)
 }

+func (d *daemon) helloAck() transport.HelloAck {
+	ack := transport.HelloAck{
+		Type:            transport.FrameTypeHelloAck,
+		BusPID:          os.Getpid(),
+		SourceState:     "connected", // best-effort; full state machine pushed via SourceState frames
+		StateSource:     "inferred",
+		IdleTimeoutSecs: int(d.cfg.IdleTimeout / time.Second),
+	}
+	if d.cfg.CredentialBroker != nil {
+		ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+		ack.CredentialGeneration = d.cfg.CredentialBroker.Generation()
+	}
+	ack.TerminalReason = d.getTerminalReason()
+	return ack
+}
+
+func (d *daemon) setTerminalReason(reason string) {
+	if d == nil || reason != transport.ByeReasonRuntimeTokenRejected {
+		return
+	}
+	d.terminalMu.Lock()
+	d.terminalReason = reason
+	d.terminalMu.Unlock()
+}
+
+func (d *daemon) getTerminalReason() string {
+	if d == nil {
+		return ""
+	}
+	d.terminalMu.RLock()
+	defer d.terminalMu.RUnlock()
+	return d.terminalReason
+}
+
+func classifyCredentialUpdateError(err error) (string, string) {
+	var conflict *runtimecred.GenerationConflictError
+	if errors.As(err, &conflict) {
+		return transport.CredentialErrorGenerationConflict, conflict.Error()
+	}
+	if errors.Is(err, runtimecred.ErrEmptyToken) || errors.Is(err, runtimecred.ErrTokenTooLarge) {
+		return transport.CredentialErrorInvalid, err.Error()
+	}
+	return transport.CredentialErrorInternal, "runtime credential update failed"
+}
+
 func (d *daemon) handleConsumerStopRPC(w *transport.Writer, r *transport.Reader) {
 	var req transport.ConsumerStopReq
 	if err := r.ReadJSON(&req); err != nil {
@@ -577,38 +767,64 @@ func (d *daemon) triggerShutdown(reason string) {
 //  4. wait for acceptLoop to return so no future consumerWG.Add can occur
 //  5. close all accepted connections and wait for handlers to drain
 //  6. lock + meta cleanup via Run's defers
-func (d *daemon) shutdown(acceptDone <-chan struct{}) {
+func (d *daemon) shutdown(acceptDone <-chan struct{}, reasons ...string) {
 	d.shutdownMu.Lock()
 	defer d.shutdownMu.Unlock()
 	if !d.shuttingDown.CompareAndSwap(false, true) {
 		return
 	}
-	d.hub.Broadcast(transport.Bye{Type: transport.FrameTypeBye, Reason: "shutdown"})
+	reason := normalizedShutdownReason(reasons...)
+	if reason == transport.ByeReasonRuntimeTokenRejected {
+		d.hub.StopAll(reason)
+	} else {
+		d.hub.Broadcast(transport.Bye{Type: transport.FrameTypeBye, Reason: reason})
+	}
 	_ = d.listener.Close()
 	<-acceptDone
-	// Force-close all open IPC connections so any reader goroutine blocked
-	// on Read() returns with a network error and exits cleanly. Without
-	// this the consumerWG never drains and Run hangs forever.
-	d.conns.Range(func(k, _ any) bool {
-		if c, ok := k.(net.Conn); ok {
-			_ = c.Close()
-		}
-		return true
-	})
-	// Give consumers a brief moment to drain final frames before we tear
-	// down their channels.
+	// Let local consumers drain the final Bye before force-closing their
+	// connections. This short grace period is what makes typed shutdown
+	// reasons (notably runtime_token_rejected) observable instead of racing
+	// with EOF. Consumers close their side immediately after reading Bye.
 	doneCh := make(chan struct{})
 	go func() {
 		d.consumerWG.Wait()
 		close(doneCh)
 	}()
 	select {
+	case <-doneCh:
+		return
+	case <-time.After(daemonByeDrainTimeout):
+	}
+
+	// A wedged/old consumer may not close after Bye. Force-close remaining
+	// connections so the daemon still has a bounded shutdown.
+	d.conns.Range(func(k, _ any) bool {
+		if c, ok := k.(net.Conn); ok {
+			_ = c.Close()
+		}
+		return true
+	})
+	select {
 	case <-doneCh:
 	case <-time.After(daemonShutdownTimeout):
 		d.log.Warn("bus: shutdown: consumer goroutines did not drain within 2s")
 	}
 }

+func sourceShutdownReason(err error) string {
+	if errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		return transport.ByeReasonRuntimeTokenRejected
+	}
+	return "shutdown"
+}
+
+func normalizedShutdownReason(reasons ...string) string {
+	if len(reasons) > 0 && reasons[0] == transport.ByeReasonRuntimeTokenRejected {
+		return transport.ByeReasonRuntimeTokenRejected
+	}
+	return "shutdown"
+}
+
 // signalReady writes a single 'R' byte to the ready pipe (if provided) and
 // closes it. The parent process (busctl/spawn) reads one byte and proceeds.
 func signalReady(p *os.File) {
@@ -246,6 +246,31 @@ func (h *Hub) StopConsumers(subscribeIDs []string, reason string) []string {
 	return out
 }

+// StopAll requests a high-priority graceful close for every live consumer.
+// Unlike Broadcast(Bye), this uses the writer's priority StopCh and therefore
+// cannot sit behind a full event buffer during a terminal source failure.
+func (h *Hub) StopAll(reason string) int {
+	reason = strings.TrimSpace(reason)
+	if reason == "" {
+		reason = "shutdown"
+	}
+	h.mu.RLock()
+	consumers := make([]*Consumer, 0, len(h.consumers))
+	for _, consumer := range h.consumers {
+		consumers = append(consumers, consumer)
+	}
+	h.mu.RUnlock()
+	stopped := 0
+	for _, consumer := range consumers {
+		select {
+		case consumer.StopCh <- reason:
+			stopped++
+		default:
+		}
+	}
+	return stopped
+}
+
 // Unregister removes a consumer by ID and closes its sendCh. Idempotent —
 // calling twice or on an unknown ID is a no-op. closeSend shares the same
 // per-consumer lock as Deliver/Broadcast, so a stale Hub snapshot cannot send
@@ -346,6 +346,27 @@ func TestHub_StopConsumersCoalescesQueuedStop(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageHubStopAllBypassesFullEventBuffer(t *testing.T) {
+	hub := NewHub(1)
+	consumer, err := hub.Register(transport.Hello{Type: transport.FrameTypeHello})
+	if err != nil {
+		t.Fatal(err)
+	}
+	consumer.SendCh <- transport.Event{Type: transport.FrameTypeEvent}
+
+	if stopped := hub.StopAll(transport.ByeReasonRuntimeTokenRejected); stopped != 1 {
+		t.Fatalf("StopAll() = %d, want 1", stopped)
+	}
+	select {
+	case reason := <-consumer.StopCh:
+		if reason != transport.ByeReasonRuntimeTokenRejected {
+			t.Fatalf("StopCh reason = %q", reason)
+		}
+	default:
+		t.Fatal("terminal stop was blocked behind the full event buffer")
+	}
+}
+
 func TestHub_ConcurrentStopConsumersRegisterUnregister(t *testing.T) {
 	h := NewHub(4)
 	const workers = 32
@@ -0,0 +1,407 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package bus
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"net"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+type runtimeCredentialRejectSource struct {
+	broker *runtimecred.Broker
+}
+
+func (s *runtimeCredentialRejectSource) Start(ctx context.Context, _ dwsevent.EmitFn) error {
+	if _, err := s.broker.Resolve(ctx); err != nil {
+		return err
+	}
+	return runtimecred.ErrRuntimeTokenRejected
+}
+
+func runtimeCredentialDaemon(broker *runtimecred.Broker, logOutput io.Writer) *daemon {
+	if logOutput == nil {
+		logOutput = io.Discard
+	}
+	return &daemon{
+		cfg:      Config{CredentialBroker: broker},
+		log:      slog.New(slog.NewTextHandler(logOutput, nil)),
+		hub:      NewHub(2),
+		started:  time.Now(),
+		idleStop: make(chan struct{}),
+	}
+}
+
+func runRuntimeCredentialConnection(t *testing.T, d *daemon) (net.Conn, *transport.Writer, *transport.Reader, <-chan struct{}) {
+	t.Helper()
+	server, client := net.Pipe()
+	done := make(chan struct{})
+	go func() {
+		d.handleConnection(context.Background(), server)
+		close(done)
+	}()
+	return client, transport.NewWriter(client), transport.NewReader(client), done
+}
+
+func TestCrossPlatformCoverageDaemonRuntimeCredentialHandshakeBeforeRegister(t *testing.T) {
+	broker := runtimecred.New(runtimecred.Config{RequireSeed: true, RequireActivation: true})
+	d := runtimeCredentialDaemon(broker, nil)
+	client, w, r, done := runRuntimeCredentialConnection(t, d)
+	defer client.Close()
+
+	if err := w.WriteJSON(transport.Hello{
+		Type:           transport.FrameTypeHello,
+		ConsumerPID:    42,
+		CredentialMode: transport.CredentialModeRuntimeToken,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var helloAck transport.HelloAck
+	if err := r.ReadJSON(&helloAck); err != nil {
+		t.Fatal(err)
+	}
+	if !hasTransportCapability(helloAck.Capabilities, transport.CapabilityRuntimeTokenV1) || helloAck.CredentialGeneration != 0 {
+		t.Fatalf("hello ack = %#v", helloAck)
+	}
+	if d.hub.Len() != 0 {
+		t.Fatalf("consumer registered before credential update: %d", d.hub.Len())
+	}
+
+	const canary = "ipc-canary-runtime-token"
+	if err := w.WriteJSON(transport.CredentialUpdate{
+		Type:               transport.FrameTypeCredentialUpdate,
+		ExpectedGeneration: helloAck.CredentialGeneration,
+		Token:              canary,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var updateAck transport.CredentialUpdateAck
+	if err := r.ReadJSON(&updateAck); err != nil {
+		t.Fatal(err)
+	}
+	if !updateAck.Accepted || updateAck.CredentialGeneration != 1 {
+		t.Fatalf("credential ack = %#v", updateAck)
+	}
+	deadline := time.Now().Add(time.Second)
+	for d.hub.Len() != 1 && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	if d.hub.Len() != 1 {
+		t.Fatal("consumer was not registered after credential ack")
+	}
+	if token, err := broker.Resolve(context.Background()); err != nil || token != canary {
+		t.Fatalf("broker did not resolve installed runtime token: %v", err)
+	}
+
+	if err := w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "done"}); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("connection did not close")
+	}
+}
+
+func TestCrossPlatformCoverageDaemonCompatibleBusRotatesRuntimeCredentialAcrossConnections(t *testing.T) {
+	broker := runtimecred.New(runtimecred.Config{RequireSeed: true, RequireActivation: true})
+	d := runtimeCredentialDaemon(broker, nil)
+
+	handshake := func(token string, wantHelloGeneration, wantAckGeneration uint64) {
+		t.Helper()
+		client, w, r, done := runRuntimeCredentialConnection(t, d)
+		if err := w.WriteJSON(transport.Hello{
+			Type:           transport.FrameTypeHello,
+			CredentialMode: transport.CredentialModeRuntimeToken,
+		}); err != nil {
+			t.Fatal(err)
+		}
+		var helloAck transport.HelloAck
+		if err := r.ReadJSON(&helloAck); err != nil {
+			t.Fatal(err)
+		}
+		if helloAck.CredentialGeneration != wantHelloGeneration {
+			t.Fatalf("hello generation = %d, want %d", helloAck.CredentialGeneration, wantHelloGeneration)
+		}
+		if err := w.WriteJSON(transport.CredentialUpdate{
+			Type:               transport.FrameTypeCredentialUpdate,
+			ExpectedGeneration: helloAck.CredentialGeneration,
+			Token:              token,
+		}); err != nil {
+			t.Fatal(err)
+		}
+		var updateAck transport.CredentialUpdateAck
+		if err := r.ReadJSON(&updateAck); err != nil {
+			t.Fatal(err)
+		}
+		if !updateAck.Accepted || updateAck.CredentialGeneration != wantAckGeneration {
+			t.Fatalf("credential ack accepted=%v generation=%d, want true/%d", updateAck.Accepted, updateAck.CredentialGeneration, wantAckGeneration)
+		}
+		if err := w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "done"}); err != nil {
+			t.Fatal(err)
+		}
+		_ = client.Close()
+		select {
+		case <-done:
+		case <-time.After(time.Second):
+			t.Fatal("connection did not close")
+		}
+	}
+
+	handshake("runtime-token-a", 0, 1)
+	if token, err := broker.Resolve(context.Background()); err != nil || token != "runtime-token-a" {
+		t.Fatalf("broker did not retain first token: %v", err)
+	}
+	handshake("runtime-token-b", 1, 2)
+	if token, err := broker.Resolve(context.Background()); err != nil || token != "runtime-token-b" {
+		t.Fatalf("broker did not rotate to second token: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDaemonRuntimeCredentialMissingCapabilityDoesNotRegister(t *testing.T) {
+	d := runtimeCredentialDaemon(nil, nil)
+	client, w, r, done := runRuntimeCredentialConnection(t, d)
+	defer client.Close()
+	if err := w.WriteJSON(transport.Hello{
+		Type:           transport.FrameTypeHello,
+		CredentialMode: transport.CredentialModeRuntimeToken,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var ack transport.HelloAck
+	if err := r.ReadJSON(&ack); err != nil {
+		t.Fatal(err)
+	}
+	if hasTransportCapability(ack.Capabilities, transport.CapabilityRuntimeTokenV1) {
+		t.Fatalf("unsupported daemon advertised capability: %#v", ack)
+	}
+	if d.hub.Len() != 0 {
+		t.Fatalf("unsupported daemon registered consumer: %d", d.hub.Len())
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("unsupported connection did not close")
+	}
+}
+
+func TestCrossPlatformCoverageDaemonTerminalStateRejectsLateLegacyConsumer(t *testing.T) {
+	d := runtimeCredentialDaemon(nil, nil)
+	d.setTerminalReason(transport.ByeReasonRuntimeTokenRejected)
+	client, w, r, done := runRuntimeCredentialConnection(t, d)
+	defer client.Close()
+
+	if err := w.WriteJSON(transport.Hello{Type: transport.FrameTypeHello, ConsumerPID: 7}); err != nil {
+		t.Fatal(err)
+	}
+	var bye transport.Bye
+	if err := r.ReadJSON(&bye); err != nil {
+		t.Fatal(err)
+	}
+	if bye.Type != transport.FrameTypeBye || bye.Reason != transport.ByeReasonRuntimeTokenRejected {
+		t.Fatalf("late consumer frame = %#v", bye)
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("late consumer connection did not close")
+	}
+	if d.hub.Len() != 0 {
+		t.Fatalf("late terminal consumer remained registered: %d", d.hub.Len())
+	}
+}
+
+func TestCrossPlatformCoverageDaemonRuntimeCredentialConflictDoesNotLeakOrRegister(t *testing.T) {
+	broker := runtimecred.New(runtimecred.Config{})
+	if _, err := broker.Update(0, "installed-secret"); err != nil {
+		t.Fatal(err)
+	}
+	var logs bytes.Buffer
+	d := runtimeCredentialDaemon(broker, &logs)
+	client, w, r, done := runRuntimeCredentialConnection(t, d)
+	defer client.Close()
+	if err := w.WriteJSON(transport.Hello{
+		Type:           transport.FrameTypeHello,
+		CredentialMode: transport.CredentialModeRuntimeToken,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var helloAck transport.HelloAck
+	if err := r.ReadJSON(&helloAck); err != nil {
+		t.Fatal(err)
+	}
+	const canary = "rejected-canary-secret"
+	if err := w.WriteJSON(transport.CredentialUpdate{
+		Type:               transport.FrameTypeCredentialUpdate,
+		ExpectedGeneration: 0,
+		Token:              canary,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var updateAck transport.CredentialUpdateAck
+	if err := r.ReadJSON(&updateAck); err != nil {
+		t.Fatal(err)
+	}
+	if updateAck.Accepted || updateAck.ErrorCode != transport.CredentialErrorGenerationConflict || updateAck.CredentialGeneration != 1 {
+		t.Fatalf("conflict ack = %#v", updateAck)
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("rejected connection did not close")
+	}
+	if strings.Contains(updateAck.Error, canary) || strings.Contains(logs.String(), canary) {
+		t.Fatal("credential appeared in acknowledgement or logs")
+	}
+	if d.hub.Len() != 0 {
+		t.Fatalf("rejected consumer registered: %d", d.hub.Len())
+	}
+}
+
+func TestCrossPlatformCoverageDaemonRuntimeCredentialInvalidFilterRejectedBeforeUpdate(t *testing.T) {
+	broker := runtimecred.New(runtimecred.Config{})
+	d := runtimeCredentialDaemon(broker, nil)
+	client, w, r, done := runRuntimeCredentialConnection(t, d)
+	defer client.Close()
+	if err := w.WriteJSON(transport.Hello{
+		Type:           transport.FrameTypeHello,
+		CredentialMode: transport.CredentialModeRuntimeToken,
+		Filter:         "[",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var helloAck transport.HelloAck
+	if err := r.ReadJSON(&helloAck); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.WriteJSON(transport.CredentialUpdate{
+		Type:               transport.FrameTypeCredentialUpdate,
+		ExpectedGeneration: helloAck.CredentialGeneration,
+		Token:              "filter-canary-secret",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var updateAck transport.CredentialUpdateAck
+	if err := r.ReadJSON(&updateAck); err != nil {
+		t.Fatal(err)
+	}
+	if updateAck.Accepted || updateAck.ErrorCode != transport.CredentialErrorRegistration {
+		t.Fatalf("invalid filter ack = %#v", updateAck)
+	}
+	if broker.Generation() != 0 || d.hub.Len() != 0 {
+		t.Fatalf("invalid filter mutated state: generation=%d consumers=%d", broker.Generation(), d.hub.Len())
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("invalid filter connection did not close")
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeCredentialShutdownReason(t *testing.T) {
+	if got := sourceShutdownReason(runtimecred.ErrRuntimeTokenRejected); got != transport.ByeReasonRuntimeTokenRejected {
+		t.Fatalf("runtime source shutdown reason = %q", got)
+	}
+	if got := sourceShutdownReason(errors.New("local source failed")); got != "shutdown" {
+		t.Fatalf("local source shutdown reason = %q", got)
+	}
+	if got := normalizedShutdownReason(transport.ByeReasonRuntimeTokenRejected); got != transport.ByeReasonRuntimeTokenRejected {
+		t.Fatalf("normalized runtime shutdown reason = %q", got)
+	}
+	for _, reasons := range [][]string{nil, {"peer-controlled"}} {
+		if got := normalizedShutdownReason(reasons...); got != "shutdown" {
+			t.Fatalf("normalized untrusted shutdown reason = %q", got)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDaemonRuntimeCredentialSourceRejectionBroadcastsTypedBye(t *testing.T) {
+	skipOnWindows(t, "uses Unix socket dial")
+	workDir := shortTempDir(t)
+	sockPath := filepath.Join(workDir, "bus.sock")
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	broker := runtimecred.New(runtimecred.Config{RequireSeed: true, RequireActivation: true})
+	runDone := make(chan error, 1)
+	go func() {
+		runDone <- Run(ctx, Config{
+			WorkDir:          workDir,
+			IPCEndpoint:      sockPath,
+			ClientID:         "runtime-client",
+			Edition:          "open",
+			SourceKind:       dwsevent.SourceKindPersonalStream,
+			IdentityHash:     "0123456789abcdef",
+			SourceID:         "open",
+			Source:           &runtimeCredentialRejectSource{broker: broker},
+			CredentialBroker: broker,
+		})
+	}()
+	waitForFile(t, sockPath, 2*time.Second)
+
+	conn, err := transport.Dial(sockPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	r, w := transport.NewReader(conn), transport.NewWriter(conn)
+	if err := w.WriteJSON(transport.Hello{
+		Type:           transport.FrameTypeHello,
+		CredentialMode: transport.CredentialModeRuntimeToken,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var helloAck transport.HelloAck
+	if err := r.ReadJSON(&helloAck); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.WriteJSON(transport.CredentialUpdate{
+		Type:               transport.FrameTypeCredentialUpdate,
+		ExpectedGeneration: helloAck.CredentialGeneration,
+		Token:              "runtime-rejected-canary",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	var updateAck transport.CredentialUpdateAck
+	if err := r.ReadJSON(&updateAck); err != nil || !updateAck.Accepted {
+		t.Fatalf("credential update ack = %#v, %v", updateAck, err)
+	}
+
+	var bye transport.Bye
+	if err := r.ReadJSON(&bye); err != nil {
+		t.Fatalf("read typed shutdown: %v", err)
+	}
+	if bye.Type != transport.FrameTypeBye || bye.Reason != transport.ByeReasonRuntimeTokenRejected {
+		t.Fatalf("shutdown frame = %#v", bye)
+	}
+	_ = conn.Close()
+	select {
+	case err := <-runDone:
+		if !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+			t.Fatalf("Run() error = %v", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("runtime credential bus did not stop")
+	}
+}
+
+func hasTransportCapability(capabilities []string, want string) bool {
+	for _, capability := range capabilities {
+		if capability == want {
+			return true
+		}
+	}
+	return false
+}
@@ -0,0 +1,101 @@
+package consume
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+func eventCoreCredentialReader(t *testing.T, frame any) *transport.Reader {
+	t.Helper()
+	var buffer bytes.Buffer
+	if err := transport.NewWriter(&buffer).WriteJSON(frame); err != nil {
+		t.Fatal(err)
+	}
+	return transport.NewReader(&buffer)
+}
+
+func TestCrossPlatformCoverageEventCoreRuntimeNegotiationEdges(t *testing.T) {
+	capable := transport.HelloAck{Capabilities: []string{transport.CapabilityRuntimeTokenV1}}
+	if err := negotiateRuntimeToken(
+		transport.NewWriter(io.Discard),
+		transport.NewReader(strings.NewReader("")),
+		transport.HelloAck{TerminalReason: transport.ByeReasonRuntimeTokenRejected},
+		"token",
+	); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		t.Fatalf("terminal hello error = %v", err)
+	}
+
+	wantWriteErr := errors.New("write failed")
+	if err := negotiateRuntimeToken(
+		transport.NewWriter(errorWriter{err: wantWriteErr}),
+		transport.NewReader(strings.NewReader("")),
+		capable,
+		"token",
+	); !errors.Is(err, wantWriteErr) {
+		t.Fatalf("credential write error = %v", err)
+	}
+
+	if err := negotiateRuntimeToken(
+		transport.NewWriter(io.Discard),
+		transport.NewReader(strings.NewReader("")),
+		capable,
+		"token",
+	); !errors.Is(err, io.EOF) {
+		t.Fatalf("credential ack read error = %v", err)
+	}
+
+	if err := negotiateRuntimeToken(
+		transport.NewWriter(io.Discard),
+		eventCoreCredentialReader(t, transport.Heartbeat{Type: transport.FrameTypeHeartbeat}),
+		capable,
+		"token",
+	); err == nil || !strings.Contains(err.Error(), "unexpected runtime credential response") {
+		t.Fatalf("unexpected credential frame error = %v", err)
+	}
+
+	if err := negotiateRuntimeToken(
+		transport.NewWriter(io.Discard),
+		eventCoreCredentialReader(t, transport.CredentialUpdateAck{
+			Type:      transport.FrameTypeCredentialUpdateAck,
+			Accepted:  false,
+			ErrorCode: transport.CredentialErrorRuntimeRejected,
+		}),
+		capable,
+		"token",
+	); !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		t.Fatalf("runtime rejected ack error = %v", err)
+	}
+
+	for _, code := range []string{
+		transport.CredentialErrorGenerationConflict,
+		transport.CredentialErrorInvalid,
+		transport.CredentialErrorRegistration,
+		transport.CredentialErrorRuntimeRejected,
+		transport.CredentialErrorInternal,
+	} {
+		if got := safeCredentialErrorCode(code); got != code {
+			t.Fatalf("safeCredentialErrorCode(%q) = %q", code, got)
+		}
+	}
+	if got := safeCredentialErrorCode("peer-controlled"); got != transport.CredentialErrorInternal {
+		t.Fatalf("unknown credential error code = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageEventCoreRunManyHandshakeFailure(t *testing.T) {
+	bus := newManyFakeBus(901, nil)
+	installManyDiscover(t, bus)
+	cfg := manyTestConfig(io.Discard, io.Discard)
+	cfg.RuntimeToken = "runtime-token"
+	err := RunMany(context.Background(), cfg, manyTestSpecs())
+	if !errors.Is(err, ErrRuntimeTokenUnsupported) || !strings.Contains(err.Error(), "runtime credential handshake") {
+		t.Fatalf("RunMany handshake error = %v", err)
+	}
+}
@@ -21,9 +21,11 @@ import (
 	"io"
 	"net"
 	"os"
+	"strings"
 	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )

@@ -45,6 +47,11 @@ type Config struct {
 	// personal_stream.
 	SpawnExtraArgs []string

+	// RuntimeToken is a host-supplied credential handed to a compatible bus
+	// only after capability negotiation over owner-only local IPC. It is never
+	// included in dry-run output, child argv, environment, or persisted state.
+	RuntimeToken string `json:"-" yaml:"-"`
+
 	// EventTypes / Filter / Compact are forwarded to the bus via Hello
 	// for server-side pushdown filtering.
 	EventTypes  []string
@@ -132,6 +139,36 @@ type Config struct {

 var discoverBus = busctl.Discover

+var (
+	ErrRuntimeTokenUnsupported = errors.New("consume: event bus does not support secure runtime-token handoff")
+	ErrRuntimeTokenUpdate      = errors.New("consume: event bus rejected runtime-token update")
+)
+
+// RuntimeTokenUnsupportedError is returned before the token is sent when the
+// connected bus lacks the runtime_token_v1 capability.
+type RuntimeTokenUnsupportedError struct {
+	BusPID int
+}
+
+func (e *RuntimeTokenUnsupportedError) Error() string {
+	return fmt.Sprintf("consume: running event bus (pid %d) does not support secure runtime-token handoff; let existing consumers exit, inspect with `dws event status --as user --format json`, preview cleanup with `dws event stop --as user --all --dry-run`, then confirm with `dws event stop --as user --all --yes` and retry", e.BusPID)
+}
+
+func (e *RuntimeTokenUnsupportedError) Unwrap() error { return ErrRuntimeTokenUnsupported }
+
+// RuntimeTokenUpdateError reports a rejected credential CAS without carrying
+// either the credential or peer-provided free-form error text.
+type RuntimeTokenUpdateError struct {
+	Code       string
+	Generation uint64
+}
+
+func (e *RuntimeTokenUpdateError) Error() string {
+	return fmt.Sprintf("consume: event bus rejected runtime-token update (code=%s, generation=%d)", e.Code, e.Generation)
+}
+
+func (e *RuntimeTokenUpdateError) Unwrap() error { return ErrRuntimeTokenUpdate }
+
 // Run dials the bus (forking one if necessary), sends Hello, and writes
 // each received Event frame as one NDJSON line to stdout. Blocks until
 // ctx is cancelled, MaxEvents is reached, the bus sends Bye, or the
@@ -144,6 +181,7 @@ func Run(ctx context.Context, cfg Config) error {
 	if cfg.WorkDir == "" || cfg.IPCEndpoint == "" || cfg.ClientID == "" {
 		return errors.New("consume: WorkDir, IPCEndpoint, and ClientID are required")
 	}
+	cfg.RuntimeToken = strings.TrimSpace(cfg.RuntimeToken)
 	if cfg.Stdout == nil {
 		cfg.Stdout = os.Stdout
 	}
@@ -225,6 +263,9 @@ func Run(ctx context.Context, cfg Config) error {
 		SubscribeID: cfg.SubscribeID,
 		Compact:     cfg.Compact,
 	}
+	if cfg.RuntimeToken != "" {
+		hello.CredentialMode = transport.CredentialModeRuntimeToken
+	}
 	if err := w.WriteJSON(hello); err != nil {
 		return fmt.Errorf("consume: write hello: %w", err)
 	}
@@ -236,6 +277,9 @@ func Run(ctx context.Context, cfg Config) error {
 	if ack.Type != transport.FrameTypeHelloAck {
 		return fmt.Errorf("consume: unexpected first frame type %q", ack.Type)
 	}
+	if err := negotiateRuntimeToken(w, r, ack, cfg.RuntimeToken); err != nil {
+		return err
+	}
 	if !cfg.Quiet {
 		// Contract: a fixed ready line on stderr BEFORE any stdout event.
 		// Parents block on stderr until this appears, then read stdout.
@@ -331,6 +375,9 @@ func Run(ctx context.Context, cfg Config) error {
 		case transport.FrameTypeBye:
 			var bye transport.Bye
 			_ = json.Unmarshal(raw, &bye)
+			if bye.Reason == transport.ByeReasonRuntimeTokenRejected {
+				return fmt.Errorf("consume: %w", runtimecred.ErrRuntimeTokenRejected)
+			}
 			if !cfg.Quiet {
 				fmt.Fprintf(cfg.Stderr, "[event] bus closing: %s\n", bye.Reason)
 			}
@@ -350,6 +397,62 @@ func Run(ctx context.Context, cfg Config) error {
 	}
 }

+func negotiateRuntimeToken(w *transport.Writer, r *transport.Reader, ack transport.HelloAck, token string) error {
+	if token == "" {
+		return nil
+	}
+	if ack.TerminalReason == transport.ByeReasonRuntimeTokenRejected {
+		return fmt.Errorf("consume: %w", runtimecred.ErrRuntimeTokenRejected)
+	}
+	if !hasCapability(ack.Capabilities, transport.CapabilityRuntimeTokenV1) {
+		return &RuntimeTokenUnsupportedError{BusPID: ack.BusPID}
+	}
+	if err := w.WriteJSON(transport.CredentialUpdate{
+		Type:               transport.FrameTypeCredentialUpdate,
+		ExpectedGeneration: ack.CredentialGeneration,
+		Token:              token,
+	}); err != nil {
+		return fmt.Errorf("consume: write runtime credential update: %w", err)
+	}
+	var updateAck transport.CredentialUpdateAck
+	if err := r.ReadJSON(&updateAck); err != nil {
+		return fmt.Errorf("consume: read runtime credential update ack: %w", err)
+	}
+	if updateAck.Type != transport.FrameTypeCredentialUpdateAck {
+		return errors.New("consume: unexpected runtime credential response frame")
+	}
+	if !updateAck.Accepted {
+		code := safeCredentialErrorCode(updateAck.ErrorCode)
+		if code == transport.CredentialErrorRuntimeRejected {
+			return fmt.Errorf("consume: %w", runtimecred.ErrRuntimeTokenRejected)
+		}
+		return &RuntimeTokenUpdateError{Code: code, Generation: updateAck.CredentialGeneration}
+	}
+	return nil
+}
+
+func safeCredentialErrorCode(code string) string {
+	switch code {
+	case transport.CredentialErrorGenerationConflict,
+		transport.CredentialErrorInvalid,
+		transport.CredentialErrorRegistration,
+		transport.CredentialErrorRuntimeRejected,
+		transport.CredentialErrorInternal:
+		return code
+	default:
+		return transport.CredentialErrorInternal
+	}
+}
+
+func hasCapability(capabilities []string, want string) bool {
+	for _, capability := range capabilities {
+		if capability == want {
+			return true
+		}
+	}
+	return false
+}
+
 // closeOnContext spawns a goroutine that closes conn when ctx is done.
 // This unblocks any pending Read on conn so the main loop can return.
 func closeOnContext(ctx context.Context, conn net.Conn) {
@@ -16,6 +16,7 @@ import (
 	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )

@@ -53,6 +54,7 @@ func RunMany(ctx context.Context, cfg Config, specs []ConsumerSpec) error {
 	if cfg.WorkDir == "" || cfg.IPCEndpoint == "" || cfg.ClientID == "" {
 		return errors.New("consume: WorkDir, IPCEndpoint, and ClientID are required")
 	}
+	cfg.RuntimeToken = strings.TrimSpace(cfg.RuntimeToken)
 	if len(specs) < 2 {
 		return errors.New("consume: RunMany requires at least two consumers")
 	}
@@ -127,14 +129,18 @@ func RunMany(ctx context.Context, cfg Config, specs []ConsumerSpec) error {
 		}
 		sessions = append(sessions, session)
 		closeOnContext(ctx, session.conn)
-		if err := session.w.WriteJSON(transport.Hello{
+		hello := transport.Hello{
 			Type:        transport.FrameTypeHello,
 			ConsumerPID: os.Getpid(),
 			EventTypes:  spec.EventTypes,
 			Filter:      spec.Filter,
 			SubscribeID: spec.SubscribeID,
 			Compact:     cfg.Compact,
-		}); err != nil {
+		}
+		if cfg.RuntimeToken != "" {
+			hello.CredentialMode = transport.CredentialModeRuntimeToken
+		}
+		if err := session.w.WriteJSON(hello); err != nil {
 			return fmt.Errorf("consume: write hello for %s: %w", spec.EventKey, err)
 		}
 		if err := session.r.ReadJSON(&session.ack); err != nil {
@@ -143,9 +149,16 @@ func RunMany(ctx context.Context, cfg Config, specs []ConsumerSpec) error {
 		if session.ack.Type != transport.FrameTypeHelloAck {
 			return fmt.Errorf("consume: unexpected first frame type %q for %s", session.ack.Type, spec.EventKey)
 		}
+		// Verify that every connection reached the same bus before handing a
+		// runtime credential to it. Discovery is expected to converge on one
+		// daemon, but a stale endpoint/race must not propagate the host token to
+		// an unrelated process merely so we can report the PID mismatch later.
 		if len(sessions) > 1 && session.ack.BusPID != sessions[0].ack.BusPID {
 			return fmt.Errorf("consume: consumers connected to different bus processes (%d and %d)", sessions[0].ack.BusPID, session.ack.BusPID)
 		}
+		if err := negotiateRuntimeToken(session.w, session.r, session.ack, cfg.RuntimeToken); err != nil {
+			return fmt.Errorf("consume: runtime credential handshake for %s: %w", spec.EventKey, err)
+		}
 	}

 	if !cfg.Quiet {
@@ -225,6 +238,9 @@ func RunMany(ctx context.Context, cfg Config, specs []ConsumerSpec) error {
 			case transport.FrameTypeBye:
 				var bye transport.Bye
 				_ = json.Unmarshal(frame.raw, &bye)
+				if bye.Reason == transport.ByeReasonRuntimeTokenRejected {
+					return fmt.Errorf("consume: %w", runtimecred.ErrRuntimeTokenRejected)
+				}
 				if bye.Reason == transport.ByeReasonSubscriptionStopped {
 					delete(active, frame.index)
 					_ = sessions[frame.index].conn.Close()
@@ -16,6 +16,7 @@ import (
 	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
 )

@@ -37,23 +38,25 @@ func (b *synchronizedBuffer) String() string {
 }

 type manyFakeBus struct {
-	client  net.Conn
-	server  net.Conn
-	hello   chan transport.Hello
-	acked   chan struct{}
-	ackGate <-chan struct{}
-	ack     transport.HelloAck
-	send    chan any
+	client           net.Conn
+	server           net.Conn
+	hello            chan transport.Hello
+	credentialUpdate chan transport.CredentialUpdate
+	acked            chan struct{}
+	ackGate          <-chan struct{}
+	ack              transport.HelloAck
+	send             chan any
 }

 func newManyFakeBus(busPID int, ackGate <-chan struct{}) *manyFakeBus {
 	client, server := net.Pipe()
 	f := &manyFakeBus{
-		client:  client,
-		server:  server,
-		hello:   make(chan transport.Hello, 1),
-		acked:   make(chan struct{}),
-		ackGate: ackGate,
+		client:           client,
+		server:           server,
+		hello:            make(chan transport.Hello, 1),
+		credentialUpdate: make(chan transport.CredentialUpdate, 1),
+		acked:            make(chan struct{}),
+		ackGate:          ackGate,
 		ack: transport.HelloAck{
 			Type:            transport.FrameTypeHelloAck,
 			BusPID:          busPID,
@@ -85,6 +88,23 @@ func (f *manyFakeBus) serve() {
 	if err := w.WriteJSON(f.ack); err != nil {
 		return
 	}
+	if hello.CredentialMode == transport.CredentialModeRuntimeToken {
+		if !hasCapability(f.ack.Capabilities, transport.CapabilityRuntimeTokenV1) {
+			return
+		}
+		var update transport.CredentialUpdate
+		if err := r.ReadJSON(&update); err != nil {
+			return
+		}
+		f.credentialUpdate <- update
+		if err := w.WriteJSON(transport.CredentialUpdateAck{
+			Type:                 transport.FrameTypeCredentialUpdateAck,
+			Accepted:             true,
+			CredentialGeneration: f.ack.CredentialGeneration + 1,
+		}); err != nil {
+			return
+		}
+	}
 	close(f.acked)
 	go func() {
 		for {
@@ -221,6 +241,91 @@ func TestRunManyWaitsForAllConsumersAndStopsOneAtATime(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageRunManyRuntimeTokenUsesEachConnectionGeneration(t *testing.T) {
+	const canary = "many-runtime-canary"
+	busA := newManyFakeBus(111, nil)
+	busB := newManyFakeBus(111, nil)
+	busA.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	busB.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	busA.ack.CredentialGeneration = 2
+	busB.ack.CredentialGeneration = 8
+	installManyDiscover(t, busA, busB)
+
+	cfg := manyTestConfig(io.Discard, io.Discard)
+	cfg.RuntimeToken = canary
+	done := make(chan error, 1)
+	go func() { done <- RunMany(context.Background(), cfg, manyTestSpecs()) }()
+
+	updateA := <-busA.credentialUpdate
+	updateB := <-busB.credentialUpdate
+	if updateA.Token != canary || updateA.ExpectedGeneration != 2 {
+		t.Fatal("first connection used the wrong credential or generation")
+	}
+	if updateB.Token != canary || updateB.ExpectedGeneration != 8 {
+		t.Fatal("second connection used the wrong credential or generation")
+	}
+	busA.send <- transport.Bye{Type: transport.FrameTypeBye, Reason: "shutdown"}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("RunMany did not stop")
+	}
+}
+
+func TestCrossPlatformCoverageRunManyRuntimeTokenRejectsDifferentBusBeforeSecondCredential(t *testing.T) {
+	const canary = "many-mismatched-bus-canary"
+	busA := newManyFakeBus(111, nil)
+	busB := newManyFakeBus(222, nil)
+	busA.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	busB.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	installManyDiscover(t, busA, busB)
+
+	cfg := manyTestConfig(io.Discard, io.Discard)
+	cfg.RuntimeToken = canary
+	err := RunMany(context.Background(), cfg, manyTestSpecs())
+	if err == nil || !strings.Contains(err.Error(), "different bus processes") {
+		t.Fatalf("RunMany() error = %v", err)
+	}
+	if update := <-busA.credentialUpdate; update.Token != canary {
+		t.Fatal("first bus did not receive the negotiated credential")
+	}
+	select {
+	case update := <-busB.credentialUpdate:
+		t.Fatalf("mismatched second bus received credential: generation=%d", update.ExpectedGeneration)
+	default:
+	}
+}
+
+func TestCrossPlatformCoverageRunManyRuntimeTokenRejectedByeReturnsTypedError(t *testing.T) {
+	busA := newManyFakeBus(333, nil)
+	busB := newManyFakeBus(333, nil)
+	busA.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	busB.ack.Capabilities = []string{transport.CapabilityRuntimeTokenV1}
+	installManyDiscover(t, busA, busB)
+
+	cfg := manyTestConfig(io.Discard, io.Discard)
+	cfg.RuntimeToken = "many-runtime-rejected-canary"
+	done := make(chan error, 1)
+	go func() { done <- RunMany(context.Background(), cfg, manyTestSpecs()) }()
+	<-busA.credentialUpdate
+	<-busB.credentialUpdate
+	busA.send <- transport.Bye{
+		Type:   transport.FrameTypeBye,
+		Reason: transport.ByeReasonRuntimeTokenRejected,
+	}
+	select {
+	case err := <-done:
+		if !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+			t.Fatalf("RunMany() error = %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("RunMany did not return runtime credential rejection")
+	}
+}
+
 func TestRunManyMaxEventsIsSharedAcrossConsumers(t *testing.T) {
 	busA := newManyFakeBus(202, nil)
 	busB := newManyFakeBus(202, nil)
@@ -0,0 +1,242 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package consume
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/runtimecred"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+func installRuntimeCredentialDiscover(t *testing.T, serve func(net.Conn)) {
+	t.Helper()
+	oldDiscover := discoverBus
+	done := make(chan struct{})
+	discoverBus = func(busctl.DiscoverConfig) (net.Conn, error) {
+		client, server := net.Pipe()
+		go func() {
+			defer close(done)
+			defer server.Close()
+			serve(server)
+		}()
+		return client, nil
+	}
+	t.Cleanup(func() {
+		discoverBus = oldDiscover
+		select {
+		case <-done:
+		case <-time.After(time.Second):
+			t.Error("fake runtime credential bus did not stop")
+		}
+	})
+}
+
+func TestCrossPlatformCoverageRunRuntimeTokenNegotiatesBeforeReady(t *testing.T) {
+	const canary = "consume-runtime-canary"
+	helloSeen := make(chan transport.Hello, 1)
+	updateSeen := make(chan transport.CredentialUpdate, 1)
+	installRuntimeCredentialDiscover(t, func(conn net.Conn) {
+		r, w := transport.NewReader(conn), transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			return
+		}
+		helloSeen <- hello
+		_ = w.WriteJSON(transport.HelloAck{
+			Type:                 transport.FrameTypeHelloAck,
+			BusPID:               71,
+			Capabilities:         []string{transport.CapabilityRuntimeTokenV1},
+			CredentialGeneration: 3,
+		})
+		var update transport.CredentialUpdate
+		if err := r.ReadJSON(&update); err != nil {
+			return
+		}
+		updateSeen <- update
+		_ = w.WriteJSON(transport.CredentialUpdateAck{
+			Type:                 transport.FrameTypeCredentialUpdateAck,
+			Accepted:             true,
+			CredentialGeneration: 4,
+		})
+		_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "done"})
+	})
+
+	var stderr bytes.Buffer
+	cfg := validRunConfig()
+	cfg.RuntimeToken = "  " + canary + "  "
+	cfg.Stderr = &stderr
+	if err := Run(context.Background(), cfg); err != nil {
+		t.Fatal(err)
+	}
+	hello := <-helloSeen
+	if hello.CredentialMode != transport.CredentialModeRuntimeToken {
+		t.Fatalf("credential mode = %q", hello.CredentialMode)
+	}
+	update := <-updateSeen
+	if update.ExpectedGeneration != 3 || update.Token != canary {
+		t.Fatal("credential update used the wrong token or generation")
+	}
+	if !strings.Contains(stderr.String(), "[event] ready bus_pid=71") {
+		t.Fatalf("ready marker missing: %s", stderr.String())
+	}
+}
+
+func TestCrossPlatformCoverageRunRuntimeTokenMissingCapabilityFailsBeforeSendingSecretOrReady(t *testing.T) {
+	const canary = "unsupported-canary-secret"
+	peerBytes := make(chan string, 1)
+	installRuntimeCredentialDiscover(t, func(conn net.Conn) {
+		r, w := transport.NewReader(conn), transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			return
+		}
+		_ = w.WriteJSON(transport.HelloAck{Type: transport.FrameTypeHelloAck, BusPID: 72})
+		raw, _ := io.ReadAll(conn)
+		peerBytes <- string(raw)
+	})
+
+	var stderr bytes.Buffer
+	cfg := validRunConfig()
+	cfg.RuntimeToken = canary
+	cfg.Stderr = &stderr
+	err := Run(context.Background(), cfg)
+	if !errors.Is(err, ErrRuntimeTokenUnsupported) {
+		t.Fatalf("Run error = %v", err)
+	}
+	if strings.Contains(err.Error(), canary) {
+		t.Fatal("unsupported-bus error contained runtime token")
+	}
+	for _, recoveryStep := range []string{
+		"dws event status --as user --format json",
+		"dws event stop --as user --all --dry-run",
+		"dws event stop --as user --all --yes",
+	} {
+		if !strings.Contains(err.Error(), recoveryStep) {
+			t.Fatalf("unsupported-bus error missing recovery step %q: %v", recoveryStep, err)
+		}
+	}
+	if strings.Contains(stderr.String(), "[event] ready") {
+		t.Fatal("ready marker was written before capability negotiation succeeded")
+	}
+	if got := <-peerBytes; strings.Contains(got, canary) || got != "" {
+		t.Fatal("client sent data after unsupported capability acknowledgement")
+	}
+}
+
+func TestCrossPlatformCoverageRunRuntimeTokenRejectedDoesNotSurfacePeerText(t *testing.T) {
+	const canary = "rejected-canary-secret"
+	installRuntimeCredentialDiscover(t, func(conn net.Conn) {
+		r, w := transport.NewReader(conn), transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			return
+		}
+		_ = w.WriteJSON(transport.HelloAck{
+			Type:         transport.FrameTypeHelloAck,
+			Capabilities: []string{transport.CapabilityRuntimeTokenV1},
+		})
+		var update transport.CredentialUpdate
+		if err := r.ReadJSON(&update); err != nil {
+			return
+		}
+		_ = w.WriteJSON(transport.CredentialUpdateAck{
+			Type:      transport.FrameTypeCredentialUpdateAck,
+			Accepted:  false,
+			ErrorCode: "malicious-code-" + update.Token,
+			Error:     "malicious echo " + update.Token,
+		})
+	})
+
+	cfg := validRunConfig()
+	cfg.RuntimeToken = canary
+	err := Run(context.Background(), cfg)
+	if !errors.Is(err, ErrRuntimeTokenUpdate) {
+		t.Fatalf("Run error = %v", err)
+	}
+	if strings.Contains(err.Error(), canary) {
+		t.Fatal("credential update error contained peer-provided token text")
+	}
+}
+
+func TestCrossPlatformCoverageRuntimeTokenNeverAppearsInDryRun(t *testing.T) {
+	const canary = "dry-run-canary-secret"
+	var output bytes.Buffer
+	cfg := validRunConfig()
+	cfg.RuntimeToken = canary
+	PrintDryRun(&output, cfg)
+	if strings.Contains(output.String(), canary) || strings.Contains(output.String(), "RuntimeToken") {
+		t.Fatal("dry-run output contained runtime-token data")
+	}
+}
+
+func TestCrossPlatformCoverageRunWhitespaceRuntimeTokenUsesLegacyHandshake(t *testing.T) {
+	helloSeen := make(chan transport.Hello, 1)
+	installRuntimeCredentialDiscover(t, func(conn net.Conn) {
+		r, w := transport.NewReader(conn), transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			return
+		}
+		helloSeen <- hello
+		_ = w.WriteJSON(transport.HelloAck{Type: transport.FrameTypeHelloAck})
+		_ = w.WriteJSON(transport.Bye{Type: transport.FrameTypeBye, Reason: "done"})
+	})
+	cfg := validRunConfig()
+	cfg.RuntimeToken = "   "
+	if err := Run(context.Background(), cfg); err != nil {
+		t.Fatal(err)
+	}
+	if hello := <-helloSeen; hello.CredentialMode != "" {
+		t.Fatalf("whitespace token enabled mode %q", hello.CredentialMode)
+	}
+}
+
+func TestCrossPlatformCoverageRunRuntimeTokenRejectedByeReturnsTypedError(t *testing.T) {
+	installRuntimeCredentialDiscover(t, func(conn net.Conn) {
+		r, w := transport.NewReader(conn), transport.NewWriter(conn)
+		var hello transport.Hello
+		if err := r.ReadJSON(&hello); err != nil {
+			return
+		}
+		_ = w.WriteJSON(transport.HelloAck{
+			Type:         transport.FrameTypeHelloAck,
+			BusPID:       73,
+			Capabilities: []string{transport.CapabilityRuntimeTokenV1},
+		})
+		var update transport.CredentialUpdate
+		if err := r.ReadJSON(&update); err != nil {
+			return
+		}
+		_ = w.WriteJSON(transport.CredentialUpdateAck{
+			Type:                 transport.FrameTypeCredentialUpdateAck,
+			Accepted:             true,
+			CredentialGeneration: 1,
+		})
+		_ = w.WriteJSON(transport.Bye{
+			Type:   transport.FrameTypeBye,
+			Reason: transport.ByeReasonRuntimeTokenRejected,
+		})
+	})
+
+	var stderr bytes.Buffer
+	cfg := validRunConfig()
+	cfg.RuntimeToken = "runtime-rejected-canary"
+	cfg.Stderr = &stderr
+	err := Run(context.Background(), cfg)
+	if !errors.Is(err, runtimecred.ErrRuntimeTokenRejected) {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if strings.Contains(stderr.String(), "reason: bus_shutdown") {
+		t.Fatalf("runtime rejection was reported as a successful exit: %s", stderr.String())
+	}
+}
@@ -113,8 +113,9 @@ func IsValidationError(err error) bool {
 // human-readable block. Called by Run when cfg.DryRun is true. Format
 // avoids JSON so users can `dws event consume --dry-run | head` cleanly.
 //
-// Secret-bearing fields are never present in Config (credentials never
-// reach this layer), so no redaction is required here.
+// RuntimeToken is the only secret-bearing Config field and is deliberately
+// not read or rendered here. Keep this function allowlist-based: never switch
+// it to generic struct serialization.
 func PrintDryRun(w io.Writer, cfg Config) {
 	if w == nil {
 		return
--- a/Show More
+++ b/Show More