Merge pull request #1654 from deepseek-harness/codex/otel-feedback-levels

feat(telemetry): add feedback-gated OTEL modes
2026-08-07 16:07:27 +08:00
parent 53bd0a90a6 a5a135e269
commit 59533a3271
49 changed files with 942 additions and 253 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: a58598d8a956d47cb0cf6aa3e659f38314bc4b17
-2026-07-23-session-telemetry-otel-revival.zh.md: 0deb0b81ce262db4fa4ae26076cd59756d628d20
+2026-07-23-session-telemetry-otel-revival.md: f83128e8bf62e0718e59912c16c4e449855aaa1a
+2026-07-23-session-telemetry-otel-revival.zh.md: bef3bd9cbc22f363b92880864651dcaa782fc1de
@@ -12,9 +12,9 @@ Every deployment that wants harness sessions in an observability stack must hand

 `packages/telemetry/` revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:

- **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: adoption with cursor read-back, the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), the fixed first-chunk-per-(turn, step) projection, the `agent/error` relay, and dispose-time `shutdown` records.
+- **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: live adoption with cursor read-back and the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), buffer-free on-demand replay from the canonical log, the fixed first-chunk-per-(turn, step) projection, the live `agent/error` relay, and live dispose-time `shutdown` records.
 - **The `telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten.
- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. `exporter.url` is required and validated at load; unmounted or unconfigured, nothing leaves the process.
+- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. Its default `FULL` mode requires `exporter.url`; the later [feedback-gated telemetry decision](2026-08-05-feedback-gated-session-telemetry.md) adds `FEEDBACK_ONLY` and `DISABLED` delivery modes without moving the redaction or backend boundary, while [buffer-free feedback replay](../simplification/2026-08-06-buffer-free-feedback-telemetry.md) avoids a second in-memory copy of the session prefix.

 The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry, queueing, and loss policy are the reporting SDK's, configured through passthroughs — delivery is best-effort (at-most-once across a crash), which the READMEs state plainly.

@@ -34,4 +34,4 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry

 ## Consequences

-A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack; removing the entry is the opt-out, with no residual state. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
+A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack. `FULL` preserves that behavior by default, `FEEDBACK_ONLY` replays a canonical-log prefix when feedback is recorded, and `DISABLED` constructs no reporting pipeline; removing the entry remains a silent opt-out, while the disabled mode keeps the local feedback warning. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
@@ -12,9 +12,9 @@ Status: implemented

 `packages/telemetry/` 以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：

- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的接管、逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、固定的每个（轮次、步骤）组合的首分片投影、`agent/error` 转发、以及 dispose（资源释放）时的 `shutdown` 记录。
+- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
 - **`telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考后端：OTel JS SDK 日志流水线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。`exporter.url` 必填且加载时校验；未挂载或未配置时，任何数据都不会离开进程。
+- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考后端：OTel JS SDK 日志流水线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界，而[无缓冲反馈回放](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)避免在内存中创建会话前缀的第二份副本。

 边界公理保持不变：harness 的职责止于 `emit()`。批处理、重试、排队与丢失策略属于 reporting SDK，经 passthrough 配置——投递是尽力而为（崩溃时至多一次），两份 README 对此如实陈述。

@@ -34,4 +34,4 @@ Status: implemented

 ## 后果

-部署方在 `cordis.yml` 加一个带 OTLP endpoint 的 Cordis 配置项即可把会话流接入任何 OTel 兼容体系；删除该配置项即退出，无残留状态。未挂载规则的部署导出的记录与捕获时完全一致——包括文件内容与命令输出中内嵌的任何凭据——因此跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是真源。崩溃持久性在上述 outbox 决定重新审议前明确不在范围内。
+部署方在 `cordis.yml` 加一个带 OTLP endpoint 的 Cordis 配置项即可把会话流接入任何 OTel 兼容体系。`FULL` 默认保留该行为，`FEEDBACK_ONLY` 在记录反馈时回放权威日志前缀，`DISABLED` 则不构造上报流水线；删除该配置项仍是静默退出方式，而禁用模式会保留本地反馈警告。未挂载规则的部署导出的记录与捕获时完全一致，包括文件内容与命令输出中内嵌的任何凭据。因此，跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是真源。崩溃持久性在上述 outbox 决定重新审议前明确不在范围内。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: dad598a1830be445cdeb67d29acd8f6055bae139
-2026-07-28-feedback-command.zh.md: b9a6c62ef1c5ac134c09dd23e5628ed7b55d6ac2
+2026-07-28-feedback-command.md: 770c72954d66c9e26e03c47f99c261626e6ed09b
+2026-07-28-feedback-command.zh.md: c8bd57ddb5e94bfb826ec40b771547ca9625c8e3
@@ -18,7 +18,7 @@ The package declares the log-only `feedback/record { text }` session event and e

 `dsh-commands` still writes its `command/run` / `command/done` lifecycle pair around `/feedback`, but this command sets `recordInput: false`. Its `command/run` therefore carries the command identity and source without `args`; the feedback text exists only in `feedback/record`, while `command/done` carries the acknowledgement outcome. All three records are log-only and non-surface. Their appends start persistence's ordinary eager drain; nothing forces a flush, so acknowledgement reports that the feedback is in the log rather than already on disk.

-Capture is deliberately inert: nothing in this repository reads `feedback/record`.
+Capture remains inert for the running agent and model. The optional OTel telemetry package later adds one infrastructure consumer: it observes `feedback/record` as a release trigger in `FEEDBACK_ONLY` mode and as the local-only warning trigger in `DISABLED` mode, without changing the feedback event or command path. See [Feedback-gated session telemetry](2026-08-05-feedback-gated-session-telemetry.md).

 ### Why feedback owns an event

@@ -34,7 +34,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla

 ### A new group

-`packages/feedback/` is a new group because no existing one owns this. `goal/` is objective state, `session-title/` is titles, `core/` is the product spine. The group holds one package; a consumer would join it rather than forcing this one to grow.
+`packages/feedback/` is a new group because no existing one owns this. `goal/` is objective state, `session-title/` is titles, `core/` is the product spine. The group holds one producer package; cross-cutting consumers stay in their owning groups rather than forcing this one to grow.

 ## Alternatives considered

@@ -48,7 +48,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla

 **Register the command inside an existing package** such as `packages/ui/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.

-**Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer exists to use the structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
+**Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer needs that structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.

 **Add a model-facing tool instead of a slash command.** Rejected: feedback is a direct human observation. Routing it through the model spends a turn, lets the model paraphrase the user's words, and makes the record contingent on the model choosing to call the tool.

@@ -58,6 +58,6 @@ The shipped `dsh` base mounts the command unconditionally — no configuration,

 The package owns one independent append-only event with no cross-event or mutable-data relation for an invariant companion to check. The event follows the session log's existing replay, fork, persistence, and crash-tail behavior.

-Deferred: no consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail.
+Deferred: no product or model consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail. The optional telemetry consumer treats the event only as an export-policy trigger.

 No keyless transcript snapshot accompanies this change, at the requester's explicit direction. Package tests, a real Loader composition test over a `cordis.yml`, and the shipped Web composition test cover registration, capture, model exclusion, and product assembly.
@@ -18,7 +18,7 @@ Status: implemented

 `dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。

-采集刻意不产生后续动作：本仓库中没有任何代码读取 `feedback/record`。
+采集对正在运行的 agent 与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为本地警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。

 ### 为何反馈拥有自己的事件

@@ -34,7 +34,7 @@ Status: implemented

 ### 一个新的分组

-`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组目前只有一个包；未来的消费方应加入该分组，而不是迫使这个包不断膨胀。
+`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个包不断膨胀。

 ## 考虑过的替代方案

@@ -48,7 +48,7 @@ Status: implemented

 **在现有包中注册该命令**，例如 `packages/ui/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。

-**从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：目前没有消费方使用该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
+**从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：没有消费方需要该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。

 **改为提供面向模型的工具。** 已否决：反馈是人类的直接观察。经由模型会消耗一个轮次、让模型改写用户的原话，并使记录取决于模型是否选择调用该工具。

@@ -58,6 +58,6 @@ Status: implemented

 本包拥有一个独立的仅追加事件，不存在跨事件关系或可变数据关系可供不变式伴生插件检查。该事件遵循会话日志现有的回放、fork、持久化和崩溃尾部行为。

-延期事项：没有消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。
+延期事项：没有产品或模型消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。可选的遥测消费方只将该事件作为导出策略触发器。

 本次变更按请求者的明确指示不附带无密钥 transcript（文本记录）快照。包测试、基于真实 `cordis.yml` 的 Loader 组合测试，以及随附的 Web 组合测试覆盖注册、采集、模型排除和产品组装。
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
+2026-08-05-feedback-gated-session-telemetry.md: 7d923a7e4cf61e8d1119187564b87e4cbb2065b7
+2026-08-05-feedback-gated-session-telemetry.zh.md: 2862162c0c36e5194846c7e1c7bbc24230ce90aa
@@ -0,0 +1,35 @@
+# Agent Note: Feedback-gated session telemetry
+
+Status: implemented
+
+English | [中文](2026-08-05-feedback-gated-session-telemetry.zh.md)
+
+## Problem
+
+Session telemetry originally has one mounted behavior: every accepted record enters the reporting backend immediately. Deployments need two stricter policies without replacing the plugin: hold a session's telemetry unless its user records feedback, or disable reporting while still explaining what happens to feedback. The policy must preserve the existing full-export default and the telemetry seam's redaction-before-backend boundary.
+
+## Decision
+
+`@deepseek-ai/dsh-session-telemetry-otel` exposes the string-valued `TelemetryMode` enum to TypeScript callers and accepts the same three uppercase `mode` values in serialized configuration:
+
+- `FULL` is the default and preserves immediate delivery to the configured OTel pipeline.
+- `FEEDBACK_ONLY` reads the canonical session log when `feedback/record` is appended and hands over the unreleased prefix through that exact event. Records appended after that boundary remain local until another feedback event.
+- `DISABLED` constructs no exporter, processor, or logger provider. A `feedback/record` listener prints that nothing is shared and the feedback remains local.
+
+The generic telemetry coordinator owns `live` and `on-demand` capture. Live capture projects, clones, redacts, and hands each event to the backend on the session firehose. On-demand capture registers no continuous capture listeners; `captureSession(session, throughSeq)` reads the canonical log from the handoff cursor through an inclusive boundary, then projects, clones, redacts, and hands over that prefix. The cursor advances only for handed-over records. The [buffer-free replay decision](../simplification/2026-08-06-buffer-free-feedback-telemetry.md) owns why the on-demand path uses the canonical log instead of copied records.
+
+Mode resolution is a closed, fail-before-setup check: an unknown direct-construction value fails before transport configuration is read. Only `FULL` exposes the public service's `emit()` path to the SDK pipeline. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability; its listener passes an event to `captureSession()` only when the exact `feedback/record` object is already stored at `session.events[event.seq]`. `Session.append` commits that object before publishing `session/event`, so replay includes the feedback but cannot extend past its boundary. `DISABLED` creates neither the capability nor the SDK pipeline and does not inspect exporter configuration.
+
+## Alternatives considered
+
+**Open a session permanently after its first feedback.** Rejected because later work would be shared without another feedback act and the plugin would need additional open-session state. Releasing one pending prefix per feedback has the smaller state machine and the narrower sharing boundary.
+
+**Retain capture-time redacted records until feedback.** Rejected because it duplicates an unbounded session prefix even though the canonical log already owns the events. It preserves capture-time redaction policy and operational records, but those properties do not justify the memory cost for a mode defined as uploading the session log after feedback.
+
+**Temporarily allow public `emit()` calls during feedback replay.** Rejected because a redaction listener or another reentrant caller could enqueue an unrelated record while the flag was open. A private backend capability makes authorization structural and keeps the public service closed throughout replay.
+
+**Use an unmounted plugin as the disabled state.** That remains the silent opt-out, but it cannot warn when feedback is recorded. The explicit disabled mode lets a deployment keep one configuration shape and communicate that the local feedback did not leave the process.
+
+## Consequences
+
+`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` adds no telemetry-owned per-event buffer before feedback; direct service calls and non-canonical feedback events upload nothing, and a crash before feedback uploads nothing from that prefix. Replay applies the redaction policy mounted when feedback is recorded and excludes operational records that do not exist in the canonical log. Feedback-only streams therefore carry neither `agent-error` nor `shutdown` records, and shutdown absence is not a crash signal. Each later feedback captures the suffix accumulated since the previous boundary. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
@@ -0,0 +1,35 @@
+# Agent Note：反馈门控的会话遥测
+
+Status: implemented
+
+[English](2026-08-05-feedback-gated-session-telemetry.md) | 中文
+
+## 问题
+
+会话遥测原本只有一种已挂载行为：每条已接受记录都立即进入上报后端。部署方需要两种更严格的策略，且不替换插件：只有用户记录反馈时才释放该会话的遥测，或禁用上报并仍向用户说明反馈的去向。该策略必须保留现有的全量导出默认值，以及遥测 seam 在记录抵达后端之前脱敏的边界。
+
+## 决策
+
+`@deepseek-ai/dsh-session-telemetry-otel` 向 TypeScript 调用方公开以字符串为值的 `TelemetryMode` 枚举，并在序列化配置中接受相同的三个大写 `mode` 值：
+
+- `FULL` 是默认值，保留向已配置 OTel 流水线的即时投递。
+- `FEEDBACK_ONLY` 在追加 `feedback/record` 时读取权威会话日志，并交接截至该事件的未释放前缀。该边界后追加的记录会留在本地，直到另一个反馈事件。
+- `DISABLED` 不构造导出器、处理器或日志提供方。`feedback/record` 监听器会输出警告，说明什么都不会共享，且反馈仍留在本地。
+
+通用遥测协调器拥有 `live` 与 `on-demand` 捕获。实时捕获在会话 firehose 上投影、深拷贝、脱敏每个事件，并将其交给后端。按需捕获不注册持续捕获监听器；`captureSession(session, throughSeq)` 从 handoff 游标起读取权威日志，直至含边界的指定序列号，然后投影、深拷贝、脱敏并交接该前缀。游标只为已交接记录推进。[无缓冲回放决策](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)说明了按需路径为何使用权威日志而非记录副本。
+
+模式解析采用封闭式检查，并在设置前失败：通过直接构造传入未知值时，会在读取传输配置前失败。只有 `FULL` 向 SDK 流水线开放公共服务的 `emit()` 路径。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力；其监听器向 `captureSession()` 传递事件的唯一条件，是该事件与那个 `feedback/record` 对象身份完全相同，且该对象已存储于 `session.events[event.seq]`。`Session.append` 在发布 `session/event` 前已提交该对象，因此回放包含该反馈，但不会越过其边界。`DISABLED` 既不创建该能力，也不创建 SDK 流水线，并且不检查导出器配置。
+
+## 考虑过的替代方案
+
+**会话在首次反馈后永久开放。** 已否决，因为后续工作会在用户未再次提交反馈的情况下被共享，而且插件需要额外的会话开放状态。每次反馈只释放一个待处理前缀，状态机更小，共享边界也更窄。
+
+**反馈前保留捕获时已脱敏记录。** 已否决，因为权威日志已拥有这些事件，该方案仍会复制无上限的会话前缀。它能保留捕获时的脱敏策略与运维记录，但对于一个定义为「反馈后上传会话日志」的模式，这些性质不足以证明该内存成本合理。
+
+**在反馈回放期间临时允许公开 `emit()` 调用。** 已否决，因为在标志开启期间，脱敏监听器或另一个可重入调用方可能将无关记录入队。私有后端能力使授权成为结构性保证，并确保公共服务在整个回放过程中保持关闭。
+
+**以不挂载插件表示禁用状态。** 这仍然是静默退出方式，但无法在记录反馈时输出警告。显式禁用模式让部署方可以保持同一种配置形态，并说明本地反馈未离开进程。
+
+## 后果
+
+`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 在反馈前不增加遥测自有的逐事件缓冲；直接服务调用与非权威反馈事件均不上传任何内容，且反馈前发生崩溃时，该前缀也不上传任何内容。回放使用记录反馈时挂载的脱敏策略，并排除权威日志中不存在的运维记录。因此，仅反馈的流既不携带 `agent-error` 记录，也不携带 `shutdown` 记录，而缺少 shutdown 不是崩溃信号。每个后续反馈都会捕获从上一个边界起累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md
+2026-08-06-buffer-free-feedback-telemetry.md: 008bebdcb59f7ef4fe49f8e731aad77861368d5c
+2026-08-06-buffer-free-feedback-telemetry.zh.md: 7052e075921f4470864f5ea1c4aed5cf6201becf
@@ -0,0 +1,29 @@
+# Agent Note: Buffer-free feedback telemetry
+
+Status: implemented
+
+English | [中文](2026-08-06-buffer-free-feedback-telemetry.zh.md)
+
+## Problem
+
+Feedback-only telemetry must upload the session-log prefix only after recorded feedback. Retaining a deep-copied, redacted record for every projected event until that trigger duplicates the canonical session log and grows without a bound for a long-lived session that never records feedback.
+
+## Decision
+
+The telemetry coordinator provides `live` and `on-demand` capture. On-demand capture registers no session, flush, or operational-event listeners and retains no projected records. `captureSession(session, throughSeq?)` reads the canonical session log after the handoff cursor through an optional inclusive sequence boundary, applies the fixed projection, deep-copies each accepted event, runs the current `telemetry/record` waterfall, and hands the result to the backend.
+
+`FEEDBACK_ONLY` invokes that method with the `feedback/record` event's sequence. The append is already committed when `session/event` listeners run, so the replay contains the feedback event and cannot include a later suffix. The existing handoff cursor distinguishes later replays without another pending-record index.
+
+Because on-demand capture reads only the canonical log, it emits no `agent-error` or `shutdown` operational records. Redaction is evaluated at feedback time rather than append time. The [feedback mode decision](../feature/2026-08-05-feedback-gated-session-telemetry.md) owns the public sharing behavior; this note owns its buffer-free realization.
+
+## Alternatives considered
+
+**Retain capture-time redacted records.** This preserves the exact redaction policy and operational records observed when each event occurs, but duplicates the unbounded session prefix. The mode promises feedback-triggered session-log upload, not capture-time policy snapshots or pre-feedback operational telemetry.
+
+**Retain session event references or sequence numbers.** Rejected because the canonical log already supplies both order and identity. A second index saves payload copies but adds lifecycle state without enabling any required behavior.
+
+**Write a durable pre-feedback spool.** Deferred until a deployment requires crash recovery before feedback. It adds storage, cleanup, and confidentiality policy to a mode whose intended behavior is to upload nothing when the process exits before feedback.
+
+## Consequences
+
+A no-feedback session consumes no telemetry-owned memory proportional to its event count; the canonical session log remains the only pre-feedback copy. Feedback handling performs projection, cloning, and redaction synchronously before the backend's non-blocking enqueue, so its cost scales with the unreleased prefix. A redaction-policy change before feedback affects that replay, and a crash before feedback uploads nothing. Later feedback processes only events beyond the handoff cursor.
@@ -0,0 +1,29 @@
+# Agent Note: 无缓冲反馈遥测
+
+Status: implemented
+
+[English](2026-08-06-buffer-free-feedback-telemetry.md) | 中文
+
+## 问题
+
+仅反馈遥测必须只在记录反馈后上传会话日志前缀。若在触发前为每个已投影事件保留一份已深拷贝、已脱敏的记录，就会复制权威会话日志；对于长期运行但从不记录反馈的会话，这份副本会无限增长。
+
+## 决策
+
+遥测协调器提供 `live` 与 `on-demand` 捕获。按需捕获不注册会话、flush 或运维事件监听器，也不保留投影记录。`captureSession(session, throughSeq?)` 从 handoff 游标之后读取权威会话日志，直至可选的序列号边界（含边界），应用固定投影、深拷贝每个已接受事件、运行当前的 `telemetry/record` waterfall（瀑布式事件），并将结果交给后端。
+
+`FEEDBACK_ONLY` 以 `feedback/record` 事件的序列号调用该方法。`session/event` 监听器运行时，追加已经提交，因此回放包含该反馈事件，且无法包含后续后缀。现有 handoff 游标可区分后续回放，无需另一个待处理记录索引。
+
+按需捕获只读取权威日志，因此不会发出 `agent-error` 或 `shutdown` 运维记录。脱敏在反馈时而非追加时求值。[反馈模式决策](../feature/2026-08-05-feedback-gated-session-telemetry.md)规定公开的共享行为；本记录规定其无缓冲实现。
+
+## 考虑过的替代方案
+
+**保留捕获时的已脱敏记录。** 该方案会保留每个事件发生时观察到的确切脱敏策略与运维记录，但也会复制无上限的会话前缀。该模式承诺在反馈触发后上传会话日志，而非保留捕获时策略快照或反馈前运维遥测。
+
+**保留会话事件引用或序列号。** 已否决，因为权威日志已同时提供顺序与身份。第二个索引可以省去载荷副本，但会增加生命周期状态，且无法实现任何必需行为。
+
+**写入持久化的反馈前 spool。** 推迟到有部署要求反馈前的崩溃恢复时再实现。该方案会为一个预期在进程于反馈前退出时不上传任何内容的模式增加存储、清理与保密策略。
+
+## 后果
+
+没有反馈的会话不会消耗随事件数量增长的遥测自有内存；权威会话日志仍是反馈前的唯一副本。反馈处理会在后端非阻塞入队前同步执行投影、深拷贝与脱敏，因此其开销随未释放前缀增长。反馈前的脱敏策略变更会影响该次回放，而反馈前发生崩溃时什么都不上传。后续反馈只处理 handoff 游标之后的事件。
@@ -1350,11 +1350,13 @@ Requires: `sessions`

 ```ts config-catalog
 /**
- * Plugin configuration: two verbatim SDK option shapes plus one DSH-owned
- * shutdown bound. The package validates its endpoint and shutdown deadline
- * because both must fail at plugin load rather than at first export or exit.
+ * Plugin configuration: one sharing policy, two verbatim SDK option shapes,
+ * and one DSH-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
 */
 export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
  /**
   * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
   * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
@@ -1362,7 +1364,7 @@ export interface Config {
   * is the one field this package requires and validates itself.
   */
  exporter?: OTLPExporterNodeConfigBase & {
-    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required; validated at plugin load. */
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
    url?: string
  }
  /**
@@ -1373,11 +1375,18 @@ export interface Config {
  /** Maximum time spent awaiting the SDK provider's complete shutdown path. */
  shutdownTimeoutMillis?: number
 }
+
+/** Session-sharing policy selected by {@link Config.mode}. */
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
 ```

 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)

-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:41`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:80`](../packages/telemetry/session-telemetry-otel/src/index.ts)

 ## `@deepseek-ai/dsh-session-title`

@@ -798,7 +798,7 @@ Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/syst

 ### `telemetry/record` — waterfall

-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.

 ```ts cordis-catalog
 /**
@@ -812,8 +812,9 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 * `next()` replaces everything beneath. Dispatched synchronously on the
 * capture hot path inside the coordinator's containment: a throwing
 * listener withholds that one record (fail-closed) and never reaches the
- * agent loop. Redaction applies to the exported copy only; the canonical
- * session log is never rewritten.
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
 * @param record - the candidate record, already the coordinator's own deep
 *   copy; listeners return a (possibly new) record and must not mutate it.
 * @mode waterfall
@@ -821,7 +822,7 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```

-Source: [`packages/telemetry/session-telemetry/src/index.ts:41`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/telemetry/session-telemetry/src/index.ts:43`](../../packages/telemetry/session-telemetry/src/index.ts)

 ## `tools/*`

@@ -2364,7 +2364,7 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```

-Source: [`packages/telemetry/session-telemetry/src/index.ts:135`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/telemetry/session-telemetry/src/index.ts:140`](../../packages/telemetry/session-telemetry/src/index.ts)

 ## `ctx.tokenMeter` — `TokenMeterService`

@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:73`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:95`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:95`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:104`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
@@ -43,7 +43,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:151`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:41`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
+| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
 | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) |
@@ -689,12 +689,6 @@ flowchart TD
  pkg_tasks_local --> pkg_invariants
  pkg_tasks_local --> pkg_tasks
  pkg_tasks_local --> pkg_timeout
-  pkg_session_telemetry_otel --> pkg_brand
-  pkg_session_telemetry_otel --> pkg_invariants
-  pkg_session_telemetry_otel --> pkg_llm
-  pkg_session_telemetry_otel --> pkg_paths
-  pkg_session_telemetry_otel --> pkg_session
-  pkg_session_telemetry_otel --> pkg_session_telemetry
  pkg_agent_loop --> pkg_agent
  pkg_agent_loop --> pkg_invariants
  pkg_agent_loop --> pkg_llm
@@ -908,6 +902,13 @@ flowchart TD
  pkg_tool_tasks --> pkg_system_prompt
  pkg_tool_tasks --> pkg_tasks
  pkg_tool_tasks --> pkg_tools
+  pkg_session_telemetry_otel --> pkg_brand
+  pkg_session_telemetry_otel --> pkg_command_feedback
+  pkg_session_telemetry_otel --> pkg_invariants
+  pkg_session_telemetry_otel --> pkg_llm
+  pkg_session_telemetry_otel --> pkg_paths
+  pkg_session_telemetry_otel --> pkg_session
+  pkg_session_telemetry_otel --> pkg_session_telemetry
  pkg_tool_workflow --> pkg_agent
  pkg_tool_workflow --> pkg_invariants
  pkg_tool_workflow --> pkg_llm
@@ -1244,7 +1245,6 @@ flowchart TD
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
-| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
@@ -1279,6 +1279,7 @@ flowchart TD
 | [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
@@ -11,6 +11,7 @@ import { createServer } from 'node:http'
 import { once } from 'node:events'
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'

 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('telemetry-otel driver requires a config path')
@@ -35,6 +36,15 @@ try {
  // The fixture credential rides the model-visible user message; the exported
  // copy must scrub it while the canonical log keeps the original bytes.
  await runOneShot(ctx, { task: 'prove telemetry with key sk-e2efixture1234567890' })
+  const mode = process.env.DSH_TELEMETRY_E2E_MODE ?? 'FULL'
+  if (mode !== 'FULL') {
+    const [agent] = ctx.get('agents')?.roots() ?? []
+    if (agent === undefined) throw new Error('telemetry-otel driver requires one root agent')
+    recordFeedback(agent.session, 'fixture feedback')
+    if (mode === 'FEEDBACK_ONLY') {
+      await runOneShot(ctx, { task: 'post-feedback private suffix' })
+    }
+  }
 } finally {
  await ctx.fiber.dispose()
 }
@@ -2,6 +2,14 @@
 # path, exporting to the mock OTLP collector the driver starts (url via env).
 # The redact-rule entry models a deployment mounting its own scrub rule on the
 # telemetry/record waterfall — the seam itself ships no rules.
+- id: logger-console
+  name: '@cordisjs/plugin-logger-console'
+  config:
+    colors: false
+    levels:
+      default: 3
+    showTime: ''
+
 - id: cli-mock-llm
  name: './cli-mock-llm.ts'

@@ -18,6 +26,7 @@
 - id: telemetry-otel
  name: '@deepseek-ai/dsh-session-telemetry-otel'
  config:
+    mode: !!js process.env.DSH_TELEMETRY_E2E_MODE || 'FULL'
    exporter:
      url: !!js process.env.DSH_TELEMETRY_E2E_URL

@@ -7,6 +7,7 @@
  "dependencies": {
    "@cordisjs/plugin-hmr": "workspace:*",
    "@cordisjs/plugin-include": "workspace:*",
+    "@cordisjs/plugin-logger-console": "workspace:*",
    "@cordisjs/plugin-timer": "workspace:*",
    "@deepseek-ai/dsh-acp-demo": "workspace:*",
    "@deepseek-ai/dsh-agent": "workspace:*",
@@ -19,6 +20,7 @@
    "@deepseek-ai/dsh-bash-sandbox": "workspace:*",
    "@deepseek-ai/dsh-cli-demo": "workspace:*",
    "@deepseek-ai/dsh-code-runtime-worker": "workspace:*",
+    "@deepseek-ai/dsh-command-feedback": "workspace:*",
    "@deepseek-ai/dsh-command-goal": "workspace:*",
    "@deepseek-ai/dsh-commands": "workspace:*",
    "@deepseek-ai/dsh-compact": "workspace:*",
@@ -65,6 +65,7 @@
        "**/*.ts"
      ],
      "ignoreDependencies": [
+        "@cordisjs/plugin-logger-console",
        "@deepseek-ai/.+"
      ]
    },
@@ -1486,7 +1486,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'telemetry/record',
    mode: 'waterfall',
    signature: '\'telemetry/record\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
-    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Redaction applies to the exported copy only; the canonical\n * session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
    summary: 'Transform one outbound record before it reaches the backend.',
  },
  {
@@ -160,6 +160,29 @@ export function apply(ctx: Context, config: Config): void {}
    expect(entries[0]?.refs).toEqual([{ alias: 'Remote', imported: 'Remote', specifier: '@fix/dep' }])
  })

+  it('pastes an enum referenced by the config type', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture mode. */
+export enum Mode {
+  A = 'a',
+  B = 'b',
+}
+/** Fixture config. */
+export interface Config {
+  /** The mode. */
+  mode?: Mode
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries[0]?.pastes?.map(p => p.text)).toEqual([
+      '/** Fixture config. */\nexport interface Config {\n  /** The mode. */\n  mode?: Mode\n}',
+      "/** Fixture mode. */\nexport enum Mode {\n  A = 'a',\n  B = 'b',\n}",
+    ])
+  })
+
  it('hard-errors on a referenced type name that resolves nowhere', () => {
    expect(() => collectConfigCatalog(make({
      'src/index.ts': `import type { Context } from 'cordis'
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/README.md
-README.md: 7962a16ee9bc7d8a969a466591d761829cd55d7f
-README.zh.md: aad8f4d797ff16a5ef9be4c968fb28d708bad13e
+README.md: d2a4a5a27e1c661d2f62b328578fd890a0c622ee
+README.zh.md: 2fa42e3bb5f05dfc425356f302f44e497b100f24
@@ -8,4 +8,4 @@ The feedback family lets a human record a remark about the session without actin
 |---|---|---|
 | `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |

-A recorded remark is log-only: it never enters the model surface or derived history, and no shipped plugin consumes it. A future consumer reads `feedback/record` events from the session log rather than changing how they are captured.
+A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
@@ -8,4 +8,4 @@ feedback 家族让人类记录对会话的评价，但不据此采取任何动
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |

-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史，随附插件也不会消费它。未来的消费方从会话日志中读取 `feedback/record` 事件，而不是改变它们的采集方式。
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/command-feedback/README.md
-README.md: fb7e851774e4d3008cb28f2e70aa4fbe7d26a38a
-README.zh.md: 5d6750040cba065412b51ad6a49d6bd79502e98e
+README.md: 1923267eb3a25a4be564fa4f4535f7a3459ca481
+README.zh.md: 674665167030aa6214e9acaa7e6f5314a78c5b14
@@ -15,7 +15,7 @@ Surrounding whitespace is discarded, but feedback is otherwise unparsed: no trun

 ## What this plugin does and does not do

-`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer, starts no model work, and no plugin in this repository reads the event.
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) consumer observes the event without changing its capture contract.

 The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../ui/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.

@@ -52,7 +52,7 @@ Independent of the model request path. Recording appends to the session log only

 ## Known Limitations and Deferred Work

- **Nothing consumes the recorded feedback** — capture is deliberately inert. There is no retrieval, aggregation, export, or reporting surface, and no model-facing tool reads `feedback/record`; a consumer is a separate package.
+- **No feedback retrieval or management surface** — the optional OTel plugin uses the event only as a sharing trigger. There is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`.
 - **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
 - **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
 - **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. Feedback is not worth forcing a synchronous disk write for; a consumer that needs one awaits `ctx.sessions.flush(session)`.
@@ -15,7 +15,7 @@

 ## 本插件做什么、不做什么

-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，不启动任何模型工作；本仓库中也没有任何插件读取该事件。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) 消费方会观察该事件，但不改变它的采集契约。

 反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../ui/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。

@@ -52,7 +52,7 @@

 ## 已知限制与暂缓工作

- **没有任何消费方读取被记录的反馈**：采集刻意不产生任何后续动作。这里没有检索、聚合、导出或报告 surface，也没有面向模型的工具读取 `feedback/record`；消费方是另一个独立包。
+- **没有反馈检索或管理 surface**：可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
 - **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
 - **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
 - **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/telemetry/README.md
-README.md: c390493d4053f9f532c30c3c2291d833554d6a99
-README.zh.md: 846a3e276aeaeda7e3456f4e4d4bea577d224a89
+README.md: d1910323176738d1ecab8fe8e6c07a2811f0f5cd
+README.zh.md: 229cd3acc5ce3dc49a9c862efa824f4ee6a1fa7b
@@ -2,11 +2,9 @@

 English | [中文](README.zh.md)

-This family projects session activity into outbound telemetry and delegates delivery to a configured reporting backend.
+This family projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary; the [mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md) records immediate, feedback-gated, and disabled delivery.

 | Package | Role |
 |---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and backend delivery |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs |
-
-The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary.
+| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
@@ -2,11 +2,9 @@

 [English](README.md) | 中文

-本家族将会话活动投影为外发遥测，并将投递委派给配置的上报后端。
+本家族将会话活动投影为外发遥测，并将投递委派给配置的上报后端。[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录上报边界；[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)记录即时、反馈门控与禁用投递。

 | 包 | 职责 |
 |---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影和后端投递 |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志投递遥测 |
-
-[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录了上报边界。
+| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/telemetry/session-telemetry-otel/README.md
-README.md: 3a5d2b3a4b2adfb591cd4e18908f72ed5492fca4
-README.zh.md: 50ef72c92800943266ca6ecdb4483dc65ed58d79
+README.md: 585995ce409255df9608bc33b76625374bc67669
+README.zh.md: 6d2cfa4d492cee7f90d557c83f5c1ab3c730c6e5
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. It composes the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and maps each record the seam hands over onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity (`service.name`/`service.version`) comes from `dsh-llm`'s `APP_IDENTITY`, the same source the attribution headers use, plus `user.id` — the harness home's anonymous user id this package owns (`src/user-id.ts`: `$DSH_HOME/.userid`, a random UUID minted on first use; deleting the file resets the identity), carried once per export batch on the Resource rather than per record.
+The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam follows session events live, replays the canonical log only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity contains `service.name`/`service.version` from `dsh-llm`'s `APP_IDENTITY` plus this package's anonymous `user.id` (`$DSH_HOME/.userid`, a random UUID created on first use and reset by deleting the file), carried once per export batch rather than per record.

 ## Config

@@ -10,6 +10,7 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
 - id: telemetry-otel
  name: '@deepseek-ai/dsh-session-telemetry-otel'
  config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
    shutdownTimeoutMillis: 3000 # optional; defaults to 3000
    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
      url: https://collector.example.com/v1/logs
@@ -18,15 +19,25 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
 ```

-`exporter.url` is required, has no default, and must parse as `http(s)`; `shutdownTimeoutMillis` is a positive finite DSH-owned outer deadline and defaults to 3000 ms; a non-positive-integer `processor.maxExportBatchSize` also fails at plugin load because the SDK accepts it but then hangs on shutdown. Both SDK blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are SDK behavior tuned through `processor`. The backend implements no `flush()`: the batch processor owns ordinary flushing. During shutdown, however, OTel awaits `exporter.forceFlush()` before the processor's `exportTimeoutMillis`-bounded completion promise; if that transport promise never settles, this package abandons the wait at `shutdownTimeoutMillis`, logs the contained shutdown failure through the coordinator, and lets application teardown continue. The deadline cannot cancel the SDK transport, so records still pending then may be lost at process exit. Removing this block from `cordis.yml` is the opt-out: no residual state, no `enabled` flag.
+| `mode` | Behavior |
+|---|---|
+| `FULL` | Default. Each projected record, including lifecycle ops records, is handed to the OTel SDK immediately. |
+| `FEEDBACK_ONLY` | Each `feedback/record` replays, projects, and redacts the canonical session-log suffix through that event. Later records wait for another feedback event and remain local if none arrives. |
+| `DISABLED` | No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session telemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
+
+Programmatic TypeScript configuration uses the exported `TelemetryMode` enum (`TelemetryMode.FULL`, `TelemetryMode.FEEDBACK_ONLY`, or `TelemetryMode.DISABLED`); raw string literals are not assignable. Serialized Cordis configuration continues to use the string values shown above.
+
+Upload authorization is positive and fail-closed. An unknown direct-construction mode fails before transport configuration is read. Only `FULL` accepts direct `ctx.telemetry.emit()` calls. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability and treats only the exact `feedback/record` object already stored at `session.events[event.seq]` as consent; an independently emitted bus value is ignored. `DISABLED` never constructs the SDK pipeline, even when exporter options are present.
+
+`exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. In uploading modes, `shutdownTimeoutMillis` is a positive finite DSH-owned outer deadline that defaults to 3000 ms, and a non-positive-integer `processor.maxExportBatchSize` also fails at plugin load because the SDK accepts it but then hangs on shutdown. Both SDK blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are SDK behavior tuned through `processor`. The backend implements no `flush()`: the batch processor owns ordinary flushing. During shutdown, OTel awaits `exporter.forceFlush()` before the processor's `exportTimeoutMillis`-bounded completion promise; if that transport promise never settles, this package abandons the wait at `shutdownTimeoutMillis`, logs the contained shutdown failure through the coordinator, and lets application teardown continue. The deadline cannot cancel the SDK transport, so records still pending then may be lost at process exit.

 ## What leaves the machine

-Records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry.
+In uploading modes, records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). `FULL` runs redaction at append time; `FEEDBACK_ONLY` retains no telemetry copy and runs the currently mounted rules when feedback triggers canonical-log replay. Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.

 ## Field mapping

-Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)`, alert on severity, and detect crashes by `shutdown`-record absence (a session with activity, no `shutdown` ops record, gone stale ended uncleanly). The marker means telemetry stopped observing the session cleanly — emitted at the session's own disposal, or at application teardown for sessions still running then; a marker followed by more of that session's events is a telemetry reload, not a session restart. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. One consequence of continuing rather than replaying: a turn left open mid-stream and never closed marks the previous process dying inside it. The local log is repaired with synthetic closers at resume, but those repairs are never exported — the wire stream stays faithful to what the crashed process actually shipped, and a later clean `shutdown` marker attests only to the resumed process's own exit.
+Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)` and alert on severity. In `FULL`, they may also detect crashes by `shutdown`-record absence: the marker is emitted at the session's own disposal or application teardown, and a marker followed by more events is a telemetry reload. In `FEEDBACK_ONLY`, a released prefix normally has no later `shutdown` marker, so its absence is not a crash signal. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. A resumed local log may contain synthetic closers that were never exported; the wire stream stays faithful to records actually handed to the SDK.

 ## Model Experience

@@ -40,3 +51,4 @@ None; this package neither assembles nor sends a provider request.

 - **Upstream experimental tree** — `@opentelemetry/sdk-logs` is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
 - **Live-collector behavior belongs to the SDK exporter** — authentication, TLS, throttling, and other real OTLP deployment behavior follow the upstream SDK rather than a package-owned compatibility layer.
+- **Feedback-time snapshot** — `FEEDBACK_ONLY` retains no telemetry-owned copy before feedback. It reads and redacts the current canonical log when feedback is recorded; a crash before feedback uploads nothing, and policy changes before feedback affect what that replay exports.
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。它原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把 seam 交接过来的每条记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份（`service.name`/`service.version`）来自 `dsh-llm` 的 `APP_IDENTITY`，与归因标头同源；另有 `user.id`——本包自有的 harness home 匿名用户 id（`src/user-id.ts`：`$DSH_HOME/.userid`，首用生成随机 UUID；删除该文件即重置身份），随 Resource 每批导出携带一次而非逐条携带。
+[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。其 `mode` 决定 seam 是实时跟随会话事件、仅在记录反馈时回放权威日志，还是将遥测留在本地。上传模式会原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把每条已交接记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份包含 `service.name`/`service.version`（来自 `dsh-llm` 的 `APP_IDENTITY`），以及本包的匿名 `user.id`（`$DSH_HOME/.userid`；首次使用时创建的随机 UUID，删除该文件可重置）；这些身份随每个导出批次携带一次，而非逐条记录携带。

 ## 配置

@@ -10,6 +10,7 @@
 - id: telemetry-otel
  name: '@deepseek-ai/dsh-session-telemetry-otel'
  config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
    shutdownTimeoutMillis: 3000 # optional; defaults to 3000
    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
      url: https://collector.example.com/v1/logs
@@ -18,15 +19,25 @@
    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
 ```

-`exporter.url` 是必填项、没有默认值，并且必须能解析为 `http(s)`；`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。但在关闭期间，OTel 会先等待 `exporter.forceFlush()`，再进入受 `exportTimeoutMillis` 限制的处理器完成 promise；如果该传输 promise 始终不结算，本包（package）会在 `shutdownTimeoutMillis` 到期时放弃等待，沿协调器现有的失败隔离路径记录关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。从 `cordis.yml` 中删除该配置块即为退出方式：无残留状态，也没有 `enabled` 开关。
+| `mode` | 行为 |
+|---|---|
+| `FULL` | 默认值。每条已投影记录都立即交给 OTel SDK，包括生命周期运维记录。 |
+| `FEEDBACK_ONLY` | 每个 `feedback/record` 都会回放权威会话日志中截至该事件的后缀，并进行投影与脱敏。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
+| `DISABLED` | 不构造协调器、提供方、处理器或导出器。没有遥测记录会离开进程。`feedback/record` 会记录 `session telemetry is DISABLED; nothing will be shared and this feedback remains local`；该事件留在本地会话日志中。 |
+
+程序化 TypeScript 配置使用导出的 `TelemetryMode` 枚举（`TelemetryMode.FULL`、`TelemetryMode.FEEDBACK_ONLY` 或 `TelemetryMode.DISABLED`）；原始字符串字面量不可赋值。序列化后的 Cordis 配置继续使用上表所示的字符串值。
+
+上传授权采用显式许可，且为 fail-closed。通过直接构造传入未知模式时，会在读取传输配置前失败。只有 `FULL` 接受对 `ctx.telemetry.emit()` 的直接调用。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力，并且仅在 `feedback/record` 对象已经存储于 `session.events[event.seq]` 且对象身份完全相同时，才将其视为同意；独立发出的总线值会被忽略。即使存在导出器选项，`DISABLED` 也绝不会构造 SDK 流水线。
+
+`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再进入受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。

 ## 哪些数据会离开本机

-记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。
+在上传模式中，记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`、反馈文本，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。`FULL` 在追加时运行脱敏；`FEEDBACK_ONLY` 不保留遥测副本，而是在反馈触发权威日志回放时运行当时挂载的规则。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。`DISABLED` 不会构造 SDK 流水线，也不会将任何捕获内容交给后端。

 ## 字段映射

-seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；`severity` → `severityNumber`/`severityText`（INFO 9 / WARN 13 / ERROR 17）；`body` → 结构化日志 body；`attributes` 原样照搬。接收端基于 `(session.id, event.seq)` 去重、按严重级别告警，并通过 `shutdown` 记录的缺失检测崩溃（一个曾有活动、没有 `shutdown` 运维记录、且已然陈旧的会话，就是未干净结束的会话）。该标记的含义是遥测干净地停止了对该会话的观察：它在会话自身 dispose（资源释放）时发出，对于届时仍在运行的会话，则在应用关闭时发出；标记之后又出现该会话的更多事件，说明发生的是遥测重载，而不是会话重启。跨谱系（lineage）的流并不自足：恢复的会话在其自身 id 的流上从上一个进程停止之处继续；fork 出的会话，其流从继承边界开始，前缀位于父会话的流中，由接收端基于 `session.parent_id` + `session.seed_length` 拼接。继续而非回放的一个后果：流中一个开启后再未关闭的轮次，标志着上一个进程死在了该轮次之内。恢复时本地日志会以合成的关闭事件修复，但这些修复绝不导出：导出的流忠实于崩溃进程实际发出的内容，其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。
+seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；`severity` → `severityNumber`/`severityText`（INFO 9 / WARN 13 / ERROR 17）；`body` → 结构化日志 body；`attributes` 原样照搬。接收端基于 `(session.id, event.seq)` 去重，并按严重级别告警。在 `FULL` 中，接收端还可通过缺少 `shutdown` 记录检测崩溃：该标记在会话自身 dispose（资源释放）或应用关闭时发出；标记之后出现更多事件，说明遥测发生了重载。在 `FEEDBACK_ONLY` 中，已释放的前缀通常不包含随后的 `shutdown` 标记，因此缺少该标记不是崩溃信号。跨谱系（lineage）的流并不自足：恢复的会话在其自身 id 的流上从上一个进程停止之处继续；fork 出的会话的流从继承边界开始，其前缀位于父会话的流中，由接收端基于 `session.parent_id` + `session.seed_length` 拼接。恢复后的本地日志可能包含从未导出的合成关闭事件；协议流忠实于实际交给 SDK 的记录。

 ## 模型体验

@@ -40,3 +51,4 @@ seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；

 - **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 契约不动。
 - **真实 collector 行为属于 SDK 导出器**：身份验证、TLS、限流及其他真实 OTLP 部署行为遵循上游 SDK，不由本包自有兼容层处理。
+- **反馈时快照**：`FEEDBACK_ONLY` 在反馈前不保留遥测自有副本。记录反馈时，它读取并脱敏当前的权威日志；反馈前发生崩溃时什么都不上传，而反馈前的策略变更会影响该次回放的导出内容。
@@ -34,6 +34,7 @@
    "schemastery": "^3.18.0"
  },
  "peerDependencies": {
+    "@deepseek-ai/dsh-command-feedback": "^0.0.1",
    "@deepseek-ai/dsh-brand": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
@@ -44,6 +45,7 @@
  },
  "devDependencies": {
    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-command-feedback": "workspace:^",
    "@deepseek-ai/dsh-brand": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
@@ -6,9 +6,9 @@
 * record handed over by the seam onto `logger.emit()`. Per the seam's
 * boundary axiom, everything downstream of that call (batching, retry,
 * queueing, loss policy) is the SDK's documented behavior, configured
- * verbatim through the `exporter`/`processor` passthroughs. The one
- * backend-owned policy is an outer shutdown deadline: the SDK's export
- * timeout does not bound its preceding `forceFlush()` wait.
+ * verbatim through the `exporter`/`processor` passthroughs. This package owns
+ * capture mode and an outer shutdown deadline: the SDK's export timeout does
+ * not bound its preceding `forceFlush()` wait.
 *
 * @module @deepseek-ai/dsh-session-telemetry-otel
 */
@@ -16,7 +16,14 @@
 import { createRequire } from 'node:module'
 import z from 'schemastery'
 import type { Context } from 'cordis'
-import { Telemetry, TelemetryCoordinator, type TelemetryRecord, type TelemetrySeverity } from '@deepseek-ai/dsh-session-telemetry'
+import type {} from '@deepseek-ai/dsh-command-feedback'
+import {
+  Telemetry,
+  TelemetryCoordinator,
+  type TelemetryBackend,
+  type TelemetryRecord,
+  type TelemetrySeverity,
+} from '@deepseek-ai/dsh-session-telemetry'
 import { APP_IDENTITY } from '@deepseek-ai/dsh-llm'
 import { getOrCreateAnonymousUserId } from './user-id.ts'
 import {
@@ -33,12 +40,46 @@ import { resourceFromAttributes } from '@opentelemetry/resources'
 // version (same pattern as dsh-llm's attribution identity).
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string }

+/** Session-sharing policy selected by {@link Config.mode}. */
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
+
+/** Default session-sharing policy for schema and direct construction. */
+export const DEFAULT_TELEMETRY_MODE = TelemetryMode.FULL
+
+const DISABLED_FEEDBACK_WARNING = 'session telemetry is DISABLED; nothing will be shared and this feedback remains local'
+const NON_CANONICAL_FEEDBACK_WARNING = 'session telemetry ignored a feedback event absent from the canonical session log'
+const DROP_RECORD: TelemetryBackend['emit'] = () => {}
+
+/** Resolve the default and reject unknown runtime values before transport setup. */
+function resolveMode(mode: TelemetryMode | undefined): TelemetryMode {
+  const resolved = mode ?? DEFAULT_TELEMETRY_MODE
+  switch (resolved) {
+    case TelemetryMode.FULL:
+    case TelemetryMode.FEEDBACK_ONLY:
+    case TelemetryMode.DISABLED:
+      return resolved
+    default:
+      return assertNever(resolved)
+  }
+}
+
+/** Fail closed when direct construction bypasses the runtime config schema. */
+function assertNever(value: never): never {
+  throw new Error(`session-telemetry-otel: unsupported mode ${JSON.stringify(value)}`)
+}
+
 /**
- * Plugin configuration: two verbatim SDK option shapes plus one DSH-owned
- * shutdown bound. The package validates its endpoint and shutdown deadline
- * because both must fail at plugin load rather than at first export or exit.
+ * Plugin configuration: one sharing policy, two verbatim SDK option shapes,
+ * and one DSH-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
 */
 export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
  /**
   * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
   * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
@@ -46,7 +87,7 @@ export interface Config {
   * is the one field this package requires and validates itself.
   */
  exporter?: OTLPExporterNodeConfigBase & {
-    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required; validated at plugin load. */
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
    url?: string
  }
  /**
@@ -67,6 +108,7 @@ export interface Config {
 * (and silently drop every field not re-declared).
 */
 export const Config: z<Config> = z.object({
+  mode: z.union(Object.values(TelemetryMode)).default(DEFAULT_TELEMETRY_MODE),
  exporter: z.any(),
  processor: z.any(),
  shutdownTimeoutMillis: z.number(),
@@ -87,23 +129,32 @@ const SEVERITY: Record<TelemetrySeverity, { severityNumber: SeverityNumber; seve
 }

 /**
- * The backend plugin — the only entry a deployment loads. Constructing it
- * wires the SDK pipeline, registers the `telemetry` service (duplicate load
- * throws, cordis' standard duplicate-service behavior), and composes the
- * seam's {@link TelemetryCoordinator}, which installs the capture side onto
- * this fiber.
+ * The backend plugin — the only entry a deployment loads. It always registers
+ * the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+ * pipeline and compose {@link TelemetryCoordinator}; `DISABLED` constructs no
+ * SDK state and listens only to warn when recorded feedback stays local.
 */
 export class TelemetryOtel extends Telemetry {
  static inject = ['sessions']
  static Config = Config

-  private readonly provider: LoggerProvider
-  private readonly ledger: Logger
-  private readonly ops: Logger
+  private readonly directEmit: TelemetryBackend['emit']
+  private readonly provider: LoggerProvider | undefined
  private readonly shutdownTimeoutMillis: number

  constructor(ctx: Context, config: Config) {
+    const mode = resolveMode(config.mode)
    super(ctx)
+    if (mode === TelemetryMode.DISABLED) {
+      this.directEmit = DROP_RECORD
+      this.provider = undefined
+      this.shutdownTimeoutMillis = DEFAULT_SHUTDOWN_TIMEOUT_MILLIS
+      ctx.on('session/event', (_session, event) => {
+        if (event.type === 'feedback/record') ctx.logger.warn(DISABLED_FEEDBACK_WARNING)
+      })
+      return
+    }
+
    const url = config.exporter?.url
    if (url === undefined || url.length === 0) {
      throw new Error('session-telemetry-otel: exporter.url is required (the full OTLP logs endpoint)')
@@ -153,27 +204,50 @@ export class TelemetryOtel extends Telemetry {
        }),
      ],
    })
-    this.ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
-    this.ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
-    new TelemetryCoordinator(ctx, this)
+    const ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
+    const ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
+    const enqueue: TelemetryBackend['emit'] = (record) => {
+      const logger: Logger = record.channel === 'ops' ? ops : ledger
+      logger.emit({
+        timestamp: record.time,
+        observedTimestamp: record.time,
+        ...SEVERITY[record.severity],
+        // JSON-serializable by the seam's contract (validated at Session.append),
+        // which is exactly the AnyValue subset.
+        body: record.body as AnyValue,
+        attributes: record.attributes,
+      })
+    }
+    const backend: TelemetryBackend = {
+      emit: enqueue,
+      shutdown: () => this.shutdown(),
+    }
+    if (mode === TelemetryMode.FULL) {
+      this.directEmit = enqueue
+      new TelemetryCoordinator(ctx, backend, 'live')
+      return
+    }
+    this.directEmit = DROP_RECORD
+    const coordinator = new TelemetryCoordinator(ctx, backend, 'on-demand')
+    ctx.on('session/event', (session, event) => {
+      if (event.type !== 'feedback/record') return
+      // Consent is the committed record, not an independently emitted bus value.
+      if (session.events[event.seq] !== event) {
+        ctx.logger.warn(NON_CANONICAL_FEEDBACK_WARNING)
+        return
+      }
+      coordinator.captureSession(session, event.seq)
+    })
  }

  /**
-   * Map one seam record onto the SDK logger for its channel — a synchronous
-   * enqueue into the batch processor's queue.
-   * @param record - the logical record handed over by the coordinator.
+   * Hand a direct service record to the SDK only in `FULL`. Direct calls are
+   * no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+   * backend capability created only for the canonical feedback listener.
+   * @param record - the logical record offered directly to the service.
   */
  emit(record: TelemetryRecord): void {
-    const logger = record.channel === 'ops' ? this.ops : this.ledger
-    logger.emit({
-      timestamp: record.time,
-      observedTimestamp: record.time,
-      ...SEVERITY[record.severity],
-      // JSON-serializable by the seam's contract (validated at Session.append),
-      // which is exactly the AnyValue subset.
-      body: record.body as AnyValue,
-      attributes: record.attributes,
-    })
+    this.directEmit(record)
  }

  // The seam's optional flush() hint is deliberately NOT implemented. The
@@ -191,9 +265,11 @@ export class TelemetryOtel extends Telemetry {
   * shutdown awaits `exporter.forceFlush()` first, which can remain pending
   * when the transport never obtains a socket. The provider promise remains
   * observed after the deadline so a later rejection cannot become unhandled.
-   * @returns resolves when the SDK pipeline quiesces, or rejects at the configured deadline.
+   * `DISABLED` has no provider and resolves immediately.
+   * @returns resolves when the SDK pipeline quiesces or is disabled, or rejects at the configured deadline.
   */
  async shutdown(): Promise<void> {
+    if (this.provider === undefined) return
    const providerShutdown = this.provider.shutdown()
    let timer: ReturnType<typeof setTimeout> | undefined
    const deadline = new Promise<never>((_resolve, reject) => {
@@ -15,10 +15,9 @@ export const name = 'session-telemetry-otel-invariant'
 export const inject = ['invariants']

 /**
- * No runtime invariant: the backend forwards seam records into the OTel SDK's
- * in-process pipeline and appends nothing to any session; its only observable
- * effects (batching, export) happen inside the SDK past the seam's boundary
- * axiom, out of reach of an independent companion.
+ * No runtime invariant: mode selection changes capture handoff, SDK setup, and
+ * local diagnostics without mutating session or service state an independent
+ * companion can compare. Export remains inside the SDK past the seam boundary.
 */
 const install: InvariantInstaller = () => {}

@@ -40,6 +40,11 @@ interface OtlpCapture {
  }[]
 }

+interface FixtureOutput {
+  captures: OtlpCapture[]
+  logContent: string
+}
+
 async function jsonlFiles(dir: string): Promise<string[]> {
  const entries = await readdir(dir, { withFileTypes: true })
  const paths = await Promise.all(entries.map(async (entry) => {
@@ -50,10 +55,29 @@ async function jsonlFiles(dir: string): Promise<string[]> {
  return paths.flat()
 }

+async function readFixtureOutput(cwd: string): Promise<FixtureOutput> {
+  const captures = JSON.parse(await readFile(join(cwd, 'otlp-captures.json'), 'utf8')) as OtlpCapture[]
+  const logs = await jsonlFiles(join(cwd, '.sessions'))
+  expect(logs).toHaveLength(1)
+  return { captures, logContent: await readFile(logs[0] as string, 'utf8') }
+}
+
+function allRecords(captures: OtlpCapture[]) {
+  return captures.flatMap(capture => capture.resourceLogs.flatMap(resource =>
+    resource.scopeLogs.flatMap(scoped => scoped.logRecords.map(record => ({ scope: scoped.scope.name, record })))))
+}
+
+function eventTypes(captures: OtlpCapture[]): string[] {
+  return allRecords(captures).flatMap(({ record }) =>
+    record.attributes?.flatMap(attribute =>
+      attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
+        ? [attribute.value['stringValue']]
+        : []) ?? [])
+}
+
 describe('session-telemetry-otel through a real headless cordis.yml', () => {
  it('exports redacted ledger records to the collector while the canonical log keeps the secret', async () => {
-    let captures: OtlpCapture[] = []
-    let logContent = ''
+    let output!: FixtureOutput
    const { stderr } = await runLoaderSmoke({
      label: 'session-telemetry-otel loader smoke',
      tempDirPrefix: 'telemetry-otel-e2e-',
@@ -61,39 +85,70 @@ describe('session-telemetry-otel through a real headless cordis.yml', () => {
      libBinScript: driver,
      configPath,
      tsconfigPath: repoTsconfig,
-      inspect: async (cwd) => {
-        captures = JSON.parse(await readFile(join(cwd, 'otlp-captures.json'), 'utf8')) as OtlpCapture[]
-        const logs = await jsonlFiles(join(cwd, '.sessions'))
-        expect(logs).toHaveLength(1)
-        logContent = await readFile(logs[0] as string, 'utf8')
-      },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
    })
    expect(stderr).not.toContain('UNHANDLED')

-    const records = captures.flatMap(capture => capture.resourceLogs.flatMap(resource =>
-      resource.scopeLogs.flatMap(scoped => scoped.logRecords.map(record => ({ scope: scoped.scope.name, record })))))
+    const records = allRecords(output.captures)
    expect(records.length).toBeGreaterThan(0)

-    const eventTypes = records.flatMap(({ record }) =>
-      record.attributes?.flatMap(attribute =>
-        attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
-          ? [attribute.value['stringValue']]
-          : []) ?? [])
+    const types = eventTypes(output.captures)
    for (const expected of ['turn/start', 'user/message', 'tool/call', 'tool/result', 'assistant/message', 'turn/end']) {
-      expect(eventTypes, expected).toContain(expected)
+      expect(types, expected).toContain(expected)
    }
    expect(records.some(({ scope }) => scope.endsWith('/ops'))).toBe(true)

    // The deployment-mounted rule on the wire: the fixture credential never
    // leaves the process, its surrounding prose does, and the placeholder
    // marks the spot — the seam itself ships no rules.
-    const wire = JSON.stringify(captures)
+    const wire = JSON.stringify(output.captures)
    expect(wire).not.toContain(FIXTURE_SECRET)
    expect(wire).toContain(FIXTURE_PLACEHOLDER)
    expect(wire).toContain('prove telemetry with key')

    // The canonical session log is never rewritten.
-    expect(logContent).toContain(FIXTURE_SECRET)
-    expect(logContent).not.toContain(FIXTURE_PLACEHOLDER)
+    expect(output.logContent).toContain(FIXTURE_SECRET)
+    expect(output.logContent).not.toContain(FIXTURE_PLACEHOLDER)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('exports only prefixes ending in feedback under feedback-only mode', async () => {
+    let output!: FixtureOutput
+    const { stderr } = await runLoaderSmoke({
+      label: 'session-telemetry-otel feedback-only loader smoke',
+      tempDirPrefix: 'telemetry-otel-feedback-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: { DSH_TELEMETRY_E2E_MODE: 'FEEDBACK_ONLY' },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
+    })
+    expect(stderr).not.toContain('UNHANDLED')
+
+    const wire = JSON.stringify(output.captures)
+    expect(eventTypes(output.captures)).toContain('feedback/record')
+    expect(wire).toContain('fixture feedback')
+    expect(wire).toContain('prove telemetry with key')
+    expect(wire).not.toContain('post-feedback private suffix')
+    expect(output.logContent).toContain('post-feedback private suffix')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('keeps disabled feedback local and prints the stable warning', async () => {
+    let output!: FixtureOutput
+    const { stdout } = await runLoaderSmoke({
+      label: 'session-telemetry-otel disabled loader smoke',
+      tempDirPrefix: 'telemetry-otel-disabled-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: { DSH_TELEMETRY_E2E_MODE: 'DISABLED' },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
+    })
+
+    expect(output.captures).toEqual([])
+    expect(output.logContent).toContain('fixture feedback')
+    expect(stdout.match(/session telemetry is DISABLED; nothing will be shared and this feedback remains local/)?.[0])
+      .toMatchInlineSnapshot('"session telemetry is DISABLED; nothing will be shared and this feedback remains local"')
  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
@@ -5,7 +5,7 @@
 * for the default-exported Service class.
 */

-import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { afterAll, afterEach, beforeAll, describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { createServer, type Server } from 'node:http'
 import { once } from 'node:events'
 import { mkdtempSync, rmSync } from 'node:fs'
@@ -15,8 +15,9 @@ import { gunzipSync } from 'node:zlib'
 import { Context } from 'cordis'
 import { getOrCreateAnonymousUserId } from '../src/user-id.ts'
 import Loader from '@cordisjs/plugin-loader'
+import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import TelemetryOtel, { Config } from '../src/index.ts'
+import TelemetryOtel, { Config, DEFAULT_TELEMETRY_MODE, TelemetryMode } from '../src/index.ts'

 interface Capture {
  headers: import('node:http').IncomingHttpHeaders
@@ -34,6 +35,7 @@ interface OtlpLogsRequest {
        severityNumber: number
        severityText: string
        attributes?: { key: string; value: Record<string, unknown> }[]
+        body?: unknown
      }[]
    }[]
  }[]
@@ -107,6 +109,14 @@ function allRecords(captures: Capture[]) {
    s.logRecords.map(record => ({ scope: s.scope.name, record })))))
 }

+function eventTypes(captures: Capture[]): string[] {
+  return allRecords(captures).flatMap(({ record }) =>
+    record.attributes?.flatMap(attribute =>
+      attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
+        ? [attribute.value['stringValue']]
+        : []) ?? [])
+}
+
 describe('TelemetryOtel wire', () => {
  it('ships session records and the ops shutdown marker through the real SDK pipeline', async () => {
    const { url, captures } = await mockCollector()
@@ -114,6 +124,13 @@ describe('TelemetryOtel wire', () => {
    const session = ctx.sessions.create(SessionId('wire'), { meta: { cwd: '/tmp/w' } })
    session.append('turn/start', { turn: 1 })
    session.append('turn/end', { turn: 1, reason: { kind: 'error', error: { message: 'boom', code: 'UNKNOWN' } } })
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: Date.now(),
+      severity: 'info',
+      attributes: { 'session.id': 'wire', 'event.type': 'manual', 'event.seq': 99 },
+      body: { direct: true },
+    })
    await fiber.dispose()

    expect(captures.length).toBeGreaterThan(0)
@@ -138,6 +155,7 @@ describe('TelemetryOtel wire', () => {
    const end = ledger.find(r => r.record.attributes?.some(a => a.key === 'event.type' && a.value.stringValue === 'turn/end'))
    expect(end?.record.severityNumber).toBe(17)
    expect(end?.record.severityText).toBe('ERROR')
+    expect(eventTypes(captures)).toContain('manual')

    expect(ops).toHaveLength(1)
    expect(ops[0]!.record.attributes).toContainEqual({ key: 'telemetry.op', value: { stringValue: 'shutdown' } })
@@ -247,14 +265,134 @@ describe('TelemetryOtel wire', () => {
      r.record.attributes?.some(a => a.key === 'event.type' && a.value.stringValue === 'turn/start'))
    expect(start?.record.severityNumber).toBe(13)
  })
+
+  it('replays each session suffix only at the next feedback event', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: TelemetryMode.FEEDBACK_ONLY,
+      exporter: { url },
+    })
+    ctx.on('telemetry/record', (_record, next) => {
+      ctx.telemetry.emit({
+        channel: 'ledger',
+        time: Date.now(),
+        severity: 'info',
+        attributes: { 'session.id': 'feedback-only', 'event.type': 'direct-bypass', 'event.seq': 99 },
+        body: { mustStayLocal: true },
+      })
+      return next()
+    })
+    const session = ctx.sessions.create(SessionId('feedback-only'), { meta: {} })
+    session.append('turn/start', { turn: 1 })
+    recordFeedback(session, 'first report')
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    recordFeedback(session, 'second report')
+    session.append('turn/start', { turn: 2 })
+    await fiber.dispose()
+
+    const types = allRecords(captures).flatMap(({ record }) =>
+      record.attributes?.flatMap(attribute =>
+        attribute.key === 'event.type' ? [attribute.value.stringValue] : []) ?? [])
+    expect(types).toEqual(['turn/start', 'feedback/record', 'turn/end', 'feedback/record'])
+    expect(JSON.stringify(captures)).toContain('first report')
+    expect(JSON.stringify(captures)).toContain('second report')
+    expect(allRecords(captures).some(({ scope }) => scope.endsWith('/ops'))).toBe(false)
+  })
+
+  it('ignores direct emits and non-canonical feedback in feedback-only mode', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: TelemetryMode.FEEDBACK_ONLY,
+      exporter: { url },
+    })
+    const session = ctx.sessions.create(SessionId('no-feedback'), { meta: {} })
+    session.append('turn/start', { turn: 1 })
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: Date.now(),
+      severity: 'info',
+      attributes: { 'session.id': 'no-feedback', 'event.type': 'direct', 'event.seq': 99 },
+      body: { mustStayLocal: true },
+    })
+    ctx.emit('session/event', session, {
+      type: 'feedback/record',
+      seq: session.events.length,
+      time: Date.now(),
+      data: { text: 'not committed' },
+    })
+    await fiber.dispose()
+
+    expect(warn).toHaveBeenCalledWith(
+      'session telemetry ignored a feedback event absent from the canonical session log',
+    )
+    expect(captures).toEqual([])
+  })
+
+  it('constructs no disabled transport even when exporter options are present', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: TelemetryMode.DISABLED,
+      exporter: { url },
+      processor: { maxExportBatchSize: 0 },
+    })
+    const session = ctx.sessions.create(SessionId('disabled'), { meta: {} })
+    session.append('turn/start', { turn: 1 })
+    recordFeedback(session, 'local report')
+
+    expect(warn).toHaveBeenCalledWith(
+      'session telemetry is DISABLED; nothing will be shared and this feedback remains local',
+    )
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: 0,
+      severity: 'info',
+      attributes: {},
+      body: null,
+    })
+    await ctx.telemetry.shutdown()
+    await fiber.dispose()
+    recordFeedback(session, 'after disposal')
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(captures).toEqual([])
+  })
+
+  it('defaults direct construction to full delivery', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    new TelemetryOtel(ctx, { exporter: { url } })
+    const session = ctx.sessions.create(SessionId('direct-default'), { meta: {} })
+    session.append('turn/start', { turn: 1 })
+    await ctx.fiber.dispose()
+
+    expect(eventTypes(captures)).toContain('turn/start')
+  })
 })

 describe('TelemetryOtel config fails loud', () => {
+  it('exposes modes through the nominal enum', () => {
+    expectTypeOf<Config['mode']>().toEqualTypeOf<TelemetryMode | undefined>()
+    expectTypeOf<'FULL'>().not.toExtend<TelemetryMode>()
+    expectTypeOf<TelemetryMode.FULL>().toExtend<TelemetryMode>()
+    expect(DEFAULT_TELEMETRY_MODE).toBe(TelemetryMode.FULL)
+    expect(Config({}).mode).toBe(DEFAULT_TELEMETRY_MODE)
+  })
+
  it.each([
    [{}, /exporter\.url is required/],
    [{ exporter: { url: '' } }, /exporter\.url is required/],
    [{ exporter: { url: 'not a url' } }, /not a valid URL/],
    [{ exporter: { url: 'ftp://collector' } }, /must be http\(s\)/],
+    [{ mode: TelemetryMode.FEEDBACK_ONLY }, /exporter\.url is required/],
+    [{ mode: 'INVALID' }, /INVALID/],
    // The SDK accepts a non-positive batch size but its shutdown drain then
    // splices empty batches forever — dispose would hang, so reject at load.
    [{ exporter: { url: 'http://c/v1/logs' }, processor: { maxExportBatchSize: 0 } }, /maxExportBatchSize/],
@@ -266,6 +404,46 @@ describe('TelemetryOtel config fails loud', () => {
    await ctx.plugin(SessionStore)
    await expect(ctx.plugin(TelemetryOtel, config as Config)).rejects.toThrow(message)
  })
+
+  it('rejects an unknown direct mode before reading transport config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    let exporterRead = false
+    const config = {
+      mode: 'INVALID',
+      get exporter() {
+        exporterRead = true
+        throw new Error('transport config was read')
+      },
+    } as unknown as Config
+
+    expect(() => new TelemetryOtel(ctx, config)).toThrow(/unsupported mode "INVALID"/)
+    expect(exporterRead).toBe(false)
+  })
+
+  it('does not read any transport setting in disabled mode', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const transportRead = vi.fn(() => {
+      throw new Error('transport config was read')
+    })
+    const config = {
+      mode: TelemetryMode.DISABLED,
+      get exporter() {
+        return transportRead()
+      },
+      get processor() {
+        return transportRead()
+      },
+      get shutdownTimeoutMillis() {
+        return transportRead()
+      },
+    } as unknown as Config
+
+    new TelemetryOtel(ctx, config)
+    expect(transportRead).not.toHaveBeenCalled()
+    await ctx.fiber.dispose()
+  })
 })

 describe('dsh-session-telemetry-otel real-load-path guard', () => {
@@ -20,6 +20,9 @@
    {
      "path": "../../core/session"
    },
+    {
+      "path": "../../feedback/command-feedback"
+    },
    {
      "path": "../../llm/llm"
    },
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/telemetry/session-telemetry/README.md
-README.md: 272c9abe78849be3d2bba2c54cd7e25bcbe2d4c2
-README.zh.md: 6a72389135b3f4009625f7448f2774f239b804b5
+README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
+README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
@@ -2,23 +2,23 @@

 English | [中文](README.zh.md)

-The telemetry seam: the CAPTURE side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
+The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).

 ## The backend contract

-`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` in its constructor.
+`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path or during an explicit canonical-log replay), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` with `live` capture or `on-demand` capture and calls `captureSession(session, throughSeq?)` at its owning trigger.

 ## Capture points

-The coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, hand off; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (emit the session's `shutdown` operational record at its own termination edge — where receivers key crash detection — then retire it, so a long-lived backend neither retains closed sessions nor re-marks them at unload), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (mark each session still alive at teardown, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`).
+In `live` mode the coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, then hand off; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (capture the session's `shutdown` operational record at its termination edge, then retire it), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (capture shutdown for each still-live session, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`). In `on-demand` mode it registers only the dispose effect: `captureSession()` reads the canonical log through an optional inclusive sequence boundary, while flush hints and operational events remain local.

 ## The redact waterfall

-Every record passes the `telemetry/record` waterfall between projection and `emit()` — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.

 ## The handoff cursor

-A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session, advanced at emit time. It survives reloads that do not re-evaluate this module — config re-applies and backend source reloads, which is where iteration happens; that asymmetry is why the cursor lives in the seam. On re-adoption the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
+A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session. Live capture advances it at append time; on-demand capture advances it only while `captureSession()` hands a requested prefix to the backend. An uncaptured prefix remains solely in the canonical log, so a coordinator reload adds no telemetry-owned recovery state. On replay the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.

 ## The fixed chunk projection

@@ -40,3 +40,4 @@ None; this package neither assembles nor sends a provider request.

 - **Best-effort delivery** — the cursor marks handed-off, not delivered; a session torn down inside a reload window cannot be re-adopted; whatever sits in a backend queue at crash time is lost. A durable outbox (spool, per-sink cursors, at-least-once) is deferred until a deployment states a crash-loss requirement — see [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
 - **No built-in redaction rules** — with no `telemetry/record` listener mounted, records leave the process exactly as captured, including any credentials embedded in file contents or command output; a deployment exporting to a shared collector owns its rule set.
+- **On-demand redaction uses current state** — uncaptured events exist only in the canonical session log. A later `captureSession()` deep-copies and redacts their current values with the policy mounted at that time; there is no capture-time telemetry snapshot or durable pre-capture spool.
@@ -2,23 +2,23 @@

 [English](README.md) | 中文

-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
+遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。

 ## 后端契约

-`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径上同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端在其构造函数中组合 `TelemetryCoordinator`。
+`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径或显式权威日志回放期间同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `captureSession(session, throughSeq?)`。

 ## 捕获点

-协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏、交接；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘发出该会话的 `shutdown` 运维记录，接收端正是在这个边缘锚定崩溃检测；随后将该会话退役，因此长生命周期的后端既不会保留已关闭的会话，也不会在卸载时再次标记它们）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（拆卸时先标记每个仍存活的会话，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。
+在 `live` 模式中，协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏，再交接；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘捕获该会话的 `shutdown` 运维记录，然后将其退役）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（捕获每个仍存活会话的 shutdown，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。在 `on-demand` 模式中，协调器只注册 dispose effect：`captureSession()` 读取权威日志，直至可选的序列号边界（含边界）；flush 提示与运维事件留在本地。

 ## 脱敏 waterfall（瀑布式事件）

-每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。

 ## handoff 游标

-一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq，在 emit 时推进。游标在不重新求值本模块的重载（配置重新应用、后端源码重载）中存活，而迭代恰恰发生在这类重载中；这种不对称正是游标放在 seam 一侧的原因。重新收养时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
+一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq。实时捕获在追加时推进游标；按需捕获只有在 `captureSession()` 将请求的前缀交给后端时才推进游标。未捕获的前缀只留在权威日志中，因此协调器重载不会增加遥测自有的恢复状态。回放时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。

 ## 固定分片投影

@@ -40,3 +40,4 @@

 - **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
 - **不内置脱敏规则**：未挂载 `telemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
+- **按需脱敏使用当前状态**：未捕获的事件只存在于权威会话日志中。后续的 `captureSession()` 会使用当时挂载的策略，深拷贝并脱敏其当前值；不存在捕获时的遥测快照或持久化的捕获前 spool。
@@ -1,12 +1,15 @@
 /**
- * Capture coordinator: the seam's upstream half. Subscribes to the session
- * firehose plus the one live-bus relay (`agent/error`), applies the fixed
- * chunk projection, builds logical records, runs each through the
+ * Capture coordinator: the seam's upstream half. Live capture subscribes to
+ * the session firehose plus the one live-bus relay (`agent/error`). Both
+ * capture paths apply the fixed chunk projection, build logical records, and
+ * run each through the
 * `telemetry/record` waterfall (deployment-mounted redaction rules;
- * pass-through when none), and hands the result to the backend — synchronously, with every
- * handler self-contained so a failing backend can never starve other
- * subscribers (cordis `emit` is stop-on-throw) or touch the agent loop.
- * Composed by a backend in its constructor.
+ * pass-through when none), then hands the result to the backend. Live capture
+ * follows the session firehose; on-demand capture replays the canonical log
+ * only when requested. Every synchronous handler is self-contained so a
+ * failing backend can never starve other subscribers (cordis `emit` is
+ * stop-on-throw) or touch the agent loop. Composed by a backend in its
+ * constructor.
 *
 * @module @deepseek-ai/dsh-session-telemetry/coordinator
 */
@@ -16,6 +19,16 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { TelemetryBackend, TelemetryRecord, TelemetrySeverity } from './index.ts'

+/** Whether capture follows live events or reads the canonical log only when requested. */
+export type TelemetryCapture = 'live' | 'on-demand'
+
+/** One projected record ready for backend handoff. */
+interface ProjectedRecord {
+  readonly record: TelemetryRecord
+  /** Ledger cursor advanced only after the backend accepts this record. */
+  readonly seq?: number
+}
+
 /**
 * The handoff cursor: per session, the highest `seq` handed to a backend.
 * Deliberately MODULE-scope ambient state — a narrow, documented exception
@@ -32,17 +45,17 @@ const handoffCursor = new WeakMap<Session, number>()
 /**
 * Install the telemetry capture side onto a context for one backend.
 *
- * Registers the persistence-coordinator listener set plus the `agent/error`
- * relay, all through `ctx.effect()`/`ctx.on()` on the composing fiber, and
- * sweeps already-live sessions (a hot reload does not replay
- * `session/created`). A `session/disposed` emits the session's `shutdown`
- * operational record — the marker rides the session's own termination edge,
- * where receivers key crash detection — and retires it from the adopted set,
- * so a long-lived backend neither retains closed sessions (and their frozen
- * event logs) nor re-marks them at unload. Disposal marks the sessions still
- * alive at teardown (their own edge would fire unobserved) and then awaits
- * the backend's `shutdown()`; a failure there warns instead of throwing —
- * best-effort reporting must not fail application teardown.
+ * Live capture registers the persistence-coordinator listener set plus the
+ * `agent/error` relay, all through `ctx.effect()`/`ctx.on()` on the composing
+ * fiber, and sweeps already-live sessions (a hot reload does not replay
+ * `session/created`). A `session/disposed` captures the session's `shutdown`
+ * operational record at its own termination edge and retires it from the
+ * adopted set. On-demand capture registers none of those continuous listeners;
+ * {@link captureSession} reads the canonical log explicitly and never creates
+ * operational records. Disposal captures shutdown markers for live-adopted
+ * sessions, then awaits the backend's `shutdown()`; a failure there warns
+ * instead of throwing — best-effort reporting must not fail application
+ * teardown.
 */
 export class TelemetryCoordinator {
  /**
@@ -53,55 +66,55 @@ export class TelemetryCoordinator {
  private readonly adopted = new Set<Session>()
  /** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
  private readonly chunkSeen = new WeakMap<Session, Set<string>>()
-
  /**
   * @param ctx - the composing backend's context; listeners bind to its fiber.
   * @param backend - the backend receiving records; owned elsewhere, never disposed here beyond `shutdown()` forwarding.
+   * @param capture - follow live events, or wait for explicit canonical-log capture.
   */
  constructor(
    private readonly ctx: Context,
    private readonly backend: TelemetryBackend,
+    capture: TelemetryCapture = 'live',
  ) {
-    ctx.on('session/created', (session) => {
-      this.adopt(session)
-    })
-    // The session's own termination edge: emit the shutdown marker HERE —
-    // receivers classify a session with activity and no marker as crashed,
-    // so a normally closed session in a long-running host must get its
-    // marker at disposal, not never. Then retire: the projection/cursor
-    // WeakMaps die with the Session object; only the strong adopted set
-    // needs the explicit release.
-    ctx.on('session/disposed', (session) => {
-      this.contain(() => {
-        if (!this.adopted.delete(session)) return
-        this.handOff(shutdownRecord(session))
+    if (capture === 'live') {
+      ctx.on('session/created', (session) => {
+        this.adopt(session)
      })
-    })
-    ctx.on('session/event', (session, event) => {
-      this.contain(() => {
-        this.capture(session, event)
+      // Capture the shutdown marker at the session's own termination edge,
+      // then retire the only strong reference owned by this coordinator.
+      ctx.on('session/disposed', (session) => {
+        this.contain(() => {
+          if (!this.adopted.delete(session)) return
+          this.deliver(session, { record: this.redact(shutdownRecord(session)) })
+        })
      })
-    })
-    // Parallel listeners are awaited by the loop at turn end; returning void
-    // (not the SDK's flush promise) is the turn-latency contract.
-    ctx.on('session/flush', (session) => {
-      this.contain(() => {
-        this.hintFlush(session)
+      ctx.on('session/event', (session, event) => {
+        this.contain(() => {
+          this.captureEvent(session, event)
+        })
      })
-    })
-    ctx.on('agent/error', ({ agent, turn, step, error }) => {
-      this.contain(() => {
-        this.relayAgentError(agent, turn, step, error)
+      // Parallel listeners are awaited by the loop at turn end; returning void
+      // (not the SDK's flush promise) is the turn-latency contract.
+      ctx.on('session/flush', (session) => {
+        this.contain(() => {
+          this.hintFlush(session)
+        })
      })
-    })
+      ctx.on('agent/error', ({ agent, turn, step, error }) => {
+        this.contain(() => {
+          this.relayAgentError(agent, turn, step, error)
+        })
+      })
+      for (const session of ctx.sessions.list()) {
+        this.adopt(session)
+      }
+    }
    ctx.effect(() => async () => {
-      // Sessions still adopted here are alive through a whole-application
-      // teardown (their own disposal edge will fire after telemetry is gone,
-      // unobserved) — mark them now so the receiver sees a clean stop of
-      // observation rather than a crash-shaped silence.
+      // Sessions still adopted here are alive through whole-application
+      // teardown, so capture the marker before the backend quiesces.
      for (const session of this.adopted) {
        this.contain(() => {
-          this.handOff(shutdownRecord(session))
+          this.deliver(session, { record: this.redact(shutdownRecord(session)) })
        })
      }
      try {
@@ -110,8 +123,28 @@ export class TelemetryCoordinator {
        this.ctx.logger.warn(`telemetry: backend shutdown failed: ${String(error)}`)
      }
    }, 'telemetry capture')
-    for (const session of ctx.sessions.list()) {
-      this.adopt(session)
+  }
+
+  /**
+   * Project and hand over the canonical session-log suffix after the handoff
+   * cursor, optionally stopping at an inclusive sequence boundary. Redaction
+   * runs during this call, so an on-demand caller retains no copied records
+   * before requesting capture and uses the policy mounted at that time.
+   * Backend and policy failures remain contained per event and do not starve
+   * later events in the same replay.
+   * @param session - session whose current canonical-log prefix may be handed over.
+   * @param throughSeq - optional last sequence included in this capture.
+   */
+  captureSession(session: Session, throughSeq?: number): void {
+    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
+    // Containment is PER EVENT: one rejected record is withheld fail-closed
+    // while the rest of the historical replay proceeds.
+    for (const event of session.events) {
+      if (throughSeq !== undefined && event.seq > throughSeq) break
+      this.contain(() => {
+        if (event.seq <= cursor) this.track(session, event)
+        else this.captureEvent(session, event)
+      })
    }
  }

@@ -133,17 +166,7 @@ export class TelemetryCoordinator {
  private adopt(session: Session): void {
    if (this.adopted.has(session)) return
    this.adopted.add(session)
-    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
-    // Containment is PER EVENT, matching the firehose: one rejected record
-    // is withheld fail-closed while the rest of the historical replay
-    // proceeds — wrapping the whole loop would let a single failure silently
-    // skip the remainder of the log on an already-adopted session.
-    for (const event of session.events) {
-      this.contain(() => {
-        if (event.seq <= cursor) this.track(session, event)
-        else this.capture(session, event)
-      })
-    }
+    this.captureSession(session)
  }

  /** Feed the chunk projection without handing off — the ≤cursor half of re-adoption. */
@@ -153,8 +176,8 @@ export class TelemetryCoordinator {
    }
  }

-  /** Project one event and hand it to the backend, advancing the cursor on handoff. */
-  private capture(session: Session, event: SessionEvent): void {
+  /** Project, redact, and hand one event to the backend. */
+  private captureEvent(session: Session, event: SessionEvent): void {
    if (event.type === 'assistant/chunk') {
      const key = `${event.data.turn}:${event.data.step}`
      const seen = this.seen(session)
@@ -165,27 +188,36 @@ export class TelemetryCoordinator {
      if (seen.has(key)) return
      seen.add(key)
    }
-    this.handOff({
-      channel: 'ledger',
-      time: event.time,
-      severity: severityOf(event),
-      attributes: identityOf(session, event),
-      // The live event object is mutable and the backend serializes later;
-      // append-time validation guarantees this clone cannot throw.
-      body: structuredClone(event.data),
+    this.deliver(session, {
+      record: this.redact({
+        channel: 'ledger',
+        time: event.time,
+        severity: severityOf(event),
+        attributes: identityOf(session, event),
+        // The canonical event object is mutable and the backend serializes
+        // later; append-time validation guarantees this clone cannot throw.
+        body: structuredClone(event.data),
+      }),
+      seq: event.seq,
    })
-    handoffCursor.set(session, event.seq)
  }

  /**
-   * Run the `telemetry/record` waterfall over one record and hand the result
-   * to the backend. The innermost `next` passes the record through unchanged
-   * — the seam ships no rules; exported data is as clean as the listeners a
-   * deployment mounts. Callers run inside {@link contain}, so a throwing
-   * rule withholds the record instead of reaching the loop (fail-closed).
+   * Run the `telemetry/record` waterfall at capture time. The innermost `next`
+   * passes the record through unchanged — the seam ships no rules; exported
+   * data is as clean as the listeners a deployment mounts. Callers run inside
+   * {@link contain}, so a throwing rule withholds the record instead of
+   * reaching the loop (fail-closed). On-demand capture invokes this waterfall
+   * while reading the canonical session log, not when the event was appended.
   */
-  private handOff(record: TelemetryRecord): void {
-    this.backend.emit(this.ctx.waterfall('telemetry/record', record, () => record))
+  private redact(record: TelemetryRecord): TelemetryRecord {
+    return this.ctx.waterfall('telemetry/record', record, () => record)
+  }
+
+  /** Hand one redacted record to the backend, then advance its ledger cursor. */
+  private deliver(session: Session, pending: ProjectedRecord): void {
+    this.backend.emit(pending.record)
+    if (pending.seq !== undefined) handoffCursor.set(session, pending.seq)
  }

  /** Forward the turn-end boundary to the backend's optional flush hint. */
@@ -196,19 +228,21 @@ export class TelemetryCoordinator {
  /** Relay one `agent/error` bus emission as an `agent-error` operational record. */
  private relayAgentError(agent: Agent, turn: number, step: number, error: unknown): void {
    const detail = errorDetail(error)
-    this.handOff({
-      channel: 'ops',
-      time: Date.now(),
-      severity: 'error',
-      attributes: {
-        'telemetry.op': 'agent-error',
-        'session.id': String(agent.session.id),
-        'agent.id': agent.id,
-        'error.name': detail.name,
-        turn,
-        step,
-      },
-      body: detail,
+    this.deliver(agent.session, {
+      record: this.redact({
+        channel: 'ops',
+        time: Date.now(),
+        severity: 'error',
+        attributes: {
+          'telemetry.op': 'agent-error',
+          'session.id': String(agent.session.id),
+          'agent.id': agent.id,
+          'error.name': detail.name,
+          turn,
+          step,
+        },
+        body: detail,
+      }),
    })
  }

@@ -3,9 +3,10 @@
 *
 * The seam owns the CAPTURE side of session-event reporting — which records
 * exist (the chunk projection), what they carry (the logical record), when
- * they are handed over (adoption, the per-append firehose, lifecycle
- * forwarding), and the HMR handoff cursor. Everything downstream of
- * {@link Telemetry.emit} — batching, retry, queueing, loss policy — is the
+ * they are captured (adoption, the per-append firehose, lifecycle
+ * forwarding), live versus on-demand canonical-log capture, and the HMR
+ * cursor. Everything downstream of
+ * {@link Telemetry.emit} — batching, retry, queueing, and loss policy — is the
 * reporting SDK's territory and is deliberately not modelled here. The
 * design and its trade-offs are pinned in
 * .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
@@ -32,8 +33,9 @@ declare module 'cordis' {
     * `next()` replaces everything beneath. Dispatched synchronously on the
     * capture hot path inside the coordinator's containment: a throwing
     * listener withholds that one record (fail-closed) and never reaches the
-     * agent loop. Redaction applies to the exported copy only; the canonical
-     * session log is never rewritten.
+     * agent loop. Live capture dispatches at append time; on-demand capture
+     * dispatches while reading the canonical log. Redaction applies to the
+     * exported copy only; the canonical session log is never rewritten.
     * @param record - the candidate record, already the coordinator's own deep
     *   copy; listeners return a (possibly new) record and must not mutate it.
     * @mode waterfall
@@ -94,9 +96,10 @@ export interface TelemetryBackend {
  /**
   * Hand one record to the backend's pipeline. MUST be a non-blocking
   * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
   * @param record - the logical record to report; owned by the backend after the call.
   */
  emit(record: TelemetryRecord): void
@@ -121,6 +124,8 @@ export interface TelemetryBackend {
   * coordinator emits its dispose-time `shutdown` markers immediately before
   * calling this). Awaited by the coordinator's dispose; a rejection is
   * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
   * @returns resolves when the backend's pipeline has quiesced.
   */
  shutdown(): Promise<void>
@@ -153,4 +158,4 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
  abstract shutdown(): Promise<void>
 }

-export { TelemetryCoordinator } from './coordinator.ts'
+export { TelemetryCoordinator, type TelemetryCapture } from './coordinator.ts'
@@ -10,7 +10,12 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore, { SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { TelemetryCoordinator, type TelemetryBackend, type TelemetryRecord } from '../src/index.ts'
+import {
+  TelemetryCoordinator,
+  type TelemetryBackend,
+  type TelemetryCapture,
+  type TelemetryRecord,
+} from '../src/index.ts'

 declare module '@deepseek-ai/dsh-session' {
  interface SessionEventMap {
@@ -54,15 +59,21 @@ class FakeBackend implements TelemetryBackend {
  }
 }

-async function setup(backend: FakeBackend = new FakeBackend()) {
+async function setup(
+  backend: FakeBackend = new FakeBackend(),
+  capture: TelemetryCapture = 'live',
+) {
  const ctx = new Context()
  await ctx.plugin(SessionStore)
+  let coordinator!: TelemetryCoordinator
  const fiber = await ctx.plugin({
    name: 'fake-telemetry',
    inject: ['sessions'],
-    apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
+    apply: (inner: Context) => {
+      coordinator = new TelemetryCoordinator(inner, backend, capture)
+    },
  })
-  return { ctx, backend, fiber }
+  return { ctx, backend, coordinator, fiber }
 }

 function liveSession(ctx: Context, id = `s-${Math.random().toString(36).slice(2)}`): Session {
@@ -167,6 +178,104 @@ describe('TelemetryCoordinator capture', () => {
  })
 })

+describe('TelemetryCoordinator on-demand capture', () => {
+  it('captures one canonical-log prefix at a time without following later events', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
+    const session = liveSession(ctx, 'on-demand-prefix')
+    appendTurn(session)
+    const firstBoundary = session.events[1]!.seq
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(backend.records).toEqual([])
+
+    coordinator.captureSession(session, firstBoundary)
+    expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
+      'turn/start',
+      'user/message',
+    ])
+
+    expect(backend.ledger()).toHaveLength(2)
+    coordinator.captureSession(session)
+    coordinator.captureSession(session)
+    expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
+      'turn/start',
+      'user/message',
+      'turn/end',
+    ])
+  })
+
+  it('runs the currently mounted redaction policy during canonical-log capture', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
+    const session = liveSession(ctx, 'on-demand-redacted')
+    session.append('turn/start', { turn: 1 })
+    const disposeRule = ctx.on('telemetry/record', (_record, next) => ({
+      ...next(),
+      body: { scrubbed: true },
+    }))
+
+    coordinator.captureSession(session)
+    expect(backend.ledger()[0]!.body).toEqual({ scrubbed: true })
+    disposeRule()
+
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    coordinator.captureSession(session)
+    expect(backend.ledger()[1]!.body).toEqual({ turn: 1, reason: { kind: 'completed' } })
+  })
+
+  it('contains each backend failure independently while replaying a prefix', async () => {
+    const backend = new FakeBackend()
+    backend.rejectSeq = 1
+    const { ctx, coordinator } = await setup(backend, 'on-demand')
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const session = liveSession(ctx, 'on-demand-failure')
+    appendTurn(session)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+    coordinator.captureSession(session)
+    expect(backend.ledger().map(record => record.attributes['event.seq'])).toEqual([0, 2])
+    expect(warn).toHaveBeenCalled()
+  })
+
+  it('captures a pending prefix after coordinator reload without retained records', async () => {
+    const first = new FakeBackend()
+    const { ctx, fiber } = await setup(first, 'on-demand')
+    const session = liveSession(ctx, 'on-demand-reload')
+    session.append('turn/start', { turn: 1 })
+    await fiber.dispose()
+    expect(first.records).toEqual([])
+
+    const second = new FakeBackend()
+    let coordinator!: TelemetryCoordinator
+    await ctx.plugin({
+      name: 'fake-telemetry-after-on-demand-reload',
+      inject: ['sessions'],
+      apply: (inner: Context) => {
+        coordinator = new TelemetryCoordinator(inner, second, 'on-demand')
+      },
+    })
+    coordinator.captureSession(session)
+    expect(second.ledger().map(record => record.attributes['event.seq'])).toEqual([0])
+  })
+
+  it('registers no continuous capture, flush, or ops listeners', async () => {
+    const { ctx, backend, coordinator, fiber } = await setup(new FakeBackend(), 'on-demand')
+    const redact = vi.fn((_record: TelemetryRecord, next: () => TelemetryRecord) => next())
+    ctx.on('telemetry/record', redact)
+    const session = liveSession(ctx, 'on-demand-ledger-only')
+    session.append('turn/start', { turn: 1 })
+    await ctx.parallel('session/flush', session)
+    const agent = { id: 'agent-1', session } as Agent
+    ctx.emit('agent/error', { agent, turn: 1, step: 1, error: new Error('local only') })
+    expect(backend.flush).not.toHaveBeenCalled()
+    expect(backend.records).toEqual([])
+    expect(redact).not.toHaveBeenCalled()
+
+    coordinator.captureSession(session)
+    expect(redact).toHaveBeenCalledTimes(1)
+    await fiber.dispose()
+    expect(backend.records.map(record => record.channel)).toEqual(['ledger'])
+  })
+})
+
 describe('TelemetryCoordinator adoption', () => {
  it('exports an unpublished suffix without re-exporting constructor history', async () => {
    const backend = new FakeBackend()
@@ -277,6 +277,9 @@ importers:
      '@cordisjs/plugin-include':
        specifier: workspace:*
        version: link:../vendor/include
+      '@cordisjs/plugin-logger-console':
+        specifier: workspace:*
+        version: link:../vendor/logger-console
      '@cordisjs/plugin-timer':
        specifier: workspace:*
        version: link:../vendor/timer
@@ -313,6 +316,9 @@ importers:
      '@deepseek-ai/dsh-code-runtime-worker':
        specifier: workspace:*
        version: link:../packages/code-runtime/code-runtime-worker
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:*
+        version: link:../packages/feedback/command-feedback
      '@deepseek-ai/dsh-command-goal':
        specifier: workspace:*
        version: link:../packages/goal/command-goal
@@ -5962,6 +5968,9 @@ importers:
      '@deepseek-ai/dsh-brand':
        specifier: workspace:^
        version: link:../../util/brand
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:^
+        version: link:../../feedback/command-feedback
      '@deepseek-ai/dsh-invariants':
        specifier: workspace:^
        version: link:../../support/invariants
@@ -126,12 +126,13 @@ function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCt
 }

 /** A type declaration a paste can contain. */
-type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration
+type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.EnumDeclaration

-/** Find an interface/type-alias declaration by name in a file, or null. */
+/** Find a pasteable type declaration by name in a file, or null. */
 function findTypeDecl(ctx: FileCtx, name: string): TypeDecl | null {
  for (const stmt of ctx.sf.statements) {
-    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)) && stmt.name.text === name) return stmt
+    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt))
+      && stmt.name.text === name) return stmt
  }
  return null
 }
@@ -207,7 +208,7 @@ function checkMemberDocs(ctx: FileCtx, decl: TypeDecl, violations: string[]): vo
    else ts.forEachChild(type, (n) => { walkNested(n, path) })
  }
  if (ts.isInterfaceDeclaration(decl)) walkMembers(decl.members, decl.name.text)
-  else walkNested(decl.type, decl.name.text)
+  else if (ts.isTypeAliasDeclaration(decl)) walkNested(decl.type, decl.name.text)
 }

 /** Cross-file resolution context for the schema-path check. */