dsh-trellis 0.1.4 → 0.1.5

package/README.md

@@ -1,54 +1,58 @@
-# dsh-trellis
-
-DeepSeek Harness (dsh) host 插件：把 [Trellis](https://github.com/mindfold-ai/Trellis) 工作流带进 dsh，并尽量沿用 DSH 原生能力补齐 Codex / Claude Code 级体验：
-
-1. **每轮 workflow-state 面包屑注入** — 在每个 `agent/pre-step`，解析项目 `.trellis/workflow.md` 的 `[workflow-state:*]` 块 + 活跃任务状态（no_task / planning / in_progress），把对应面包屑注入会话（与 `dsh-agent-instructions` 的注入管道相同）。未变化不重复注入；被压缩后自动重注入；提示词里出现独立单词 `no-trellis` 可跳过当轮。
-2. **隔离的原生会话上下文身份** — 从当前 agent 的 DSH 原生 session header 生成受管的 `DSH_TRELLIS_CONTEXT_ID`，让 `task.py start/create/current` 解析到会话级 active-task 指针，并在子代理身份不同于 shell 自身 session 时优先使用被转发的身份；插件命令启动的子进程也显式使用同一个 DSH 身份。
-3. **原生子代理同步** — 安装插件后，Trellis 角色可用 DSH continuable 后台子代理；主会话先继续独立工作，耗尽后可调用事件驱动的 `trellis_wait`。它监听 DSH 的 `subagent/end`，利用 lifecycle 自带的 run/provider/output-block 元数据返回 `completed / failed / aborted / unknown` 的 fail-closed 结论。`error`、`max-tokens`、`refusal` 和未来未知失败原因都不会被误报成通过。rc.8 在父会话 idle 时也会用原生 settlement notice 唤醒，因此已经结束当前轮时无需额外调用 wait。
-4. **`/trellis` 命令** — `/trellis-status`（活跃任务 + git 状态）、`/trellis-finish`（只读检查 + 安全收尾清单，不提前清 active-task 指针）。命令输出不进模型历史；真正的会话收尾走技能面 `/trellis-finish-work`，由技能先归档再写 journal。rc.8 下两条零输入命令使用 `recordInput: false`，并显式拒绝参数和图片附件，避免静默忽略输入。
-5. **Web 配置菜单** — DSH rc.8 的“设置 → 插件 → 插件配置”会显示 Trellis 工作流卡片，可分阶段编辑全部六个配置项、恢复 profile 配置层并保存。写入经过 namespace revision fencing 和保存后读回确认；配置实时生效，禁用插件后卡片仍保留，可直接重新启用。
-
-非 Trellis 项目不注入面包屑；命令只有被用户显式调用时才会检查并返回“未初始化 Trellis”。
-
-这是 Trellis DSH 适配的**可选伴侣插件**，不是使用 `trellis init --dsh` 的前置条件。workflow 会按能力选择路径：存在 `trellis_wait` 时才使用 continuable 后台派发和事件汇合；未安装插件时，依赖结果的子代理从一开始就用 `run_in_background: false` 前台派发。两条路径都禁止 sleep 或轮询，Trellis CLI 也不会自动安装任何 DSH profile 插件。
-
-## 安装
-
-```powershell
-# 装进实际使用的 profile（均在该 profile 下次启动时生效）
-dsh plugin --profile web add dsh-trellis
-dsh plugin --profile headless add dsh-trellis
-
-# 如果你维护独立的 tui profile，也需要装进该 profile
-dsh plugin --profile tui add dsh-trellis
-```
-
-`dsh plugin` 会把插件安装到指定 profile；每个实际使用的 profile 都需要单独安装。升级到 npm 上的最新版本：
-
-```powershell
-dsh plugin --profile web update dsh-trellis
-dsh plugin --profile headless update dsh-trellis
-```
-
-对 `tui` profile 使用同样的 update，并在该 profile 下次启动时生效。
-
-如果要从源码开发或验证尚未发布的版本，可以改用本地 `file:` 安装：
-
-```powershell
-git clone https://github.com/SajoLuo/dsh-trellis.git
-cd dsh-trellis
-pnpm install --frozen-lockfile
-pnpm run build:client
-dsh plugin --profile headless add file:C:/path/to/dsh-trellis
-```
-
-`file:` 插件会作为 profile 内的 pnpm 快照安装；拉取源码更新后，尤其是版本新增文件时，需要先 remove 再 add 刷新该 profile。
-
-配套要求：项目的 Trellis 平台需包含 dsh（`trellis init --dsh`，见 Trellis-DeepSeekHarness 适配分支），且 `.trellis/scripts` 需包含读取原生 `DSH_SESSION_ID` 的适配（已含在同一分支）。Host peer 范围显式覆盖 DSH `0.1.0-rc.6+`、`0.1.1-rc.1+`、`0.1.2-alpha.1+`、`0.1.3-alpha.1+` 与 `0.1.5-alpha.1+` 五条已知预发布线，避免 npm 的 prerelease 语义把新版 Host 误判为不兼容；本仓开发与回归基线固定在 `0.1.5-alpha.2`。Host 侧 Settings 桥同时兼容旧版包级 helper 与当前 provider 方法，Web 配置卡片只在具备 settings/client surface 的 profile 中加载。
-
-### DSH 0.1.5-alpha.2 对齐说明
-
-- 已适配：Session V3 通过 `eventAt()` / `snapshotEvents()` 读取可见事件，并保留旧 session collection 回退；插件不直接读取磁盘会话日志，因此不需要自行迁移 V3 文件格式。
+# dsh-trellis
+
+DeepSeek Harness (dsh) host 插件：把 [Trellis](https://github.com/mindfold-ai/Trellis) 工作流带进 dsh，并尽量沿用 DSH 原生能力补齐 Codex / Claude Code 级体验：
+
+1. **每轮 workflow-state 面包屑注入** — 在每个 `agent/pre-step`，解析项目 `.trellis/workflow.md` 的 `[workflow-state:*]` 块 + 活跃任务状态（no_task / planning / in_progress），把对应面包屑注入会话（与 `dsh-agent-instructions` 的注入管道相同）。未变化不重复注入；被压缩后自动重注入；提示词里出现独立单词 `no-trellis` 可跳过当轮。
+2. **隔离的原生会话上下文身份** — 从当前 agent 的 DSH 原生 session header 生成受管的 `DSH_TRELLIS_CONTEXT_ID`，让 `task.py start/create/current` 解析到会话级 active-task 指针，并在子代理身份不同于 shell 自身 session 时优先使用被转发的身份；插件命令启动的子进程也显式使用同一个 DSH 身份。
+3. **原生子代理同步** — 安装插件后，Trellis 角色可用 DSH continuable 后台子代理；主会话先继续独立工作，耗尽后可调用事件驱动的 `trellis_wait`。它监听 DSH 的 `subagent/end`，利用 lifecycle 自带的 run/provider/output-block 元数据返回 `completed / failed / aborted / unknown` 的 fail-closed 结论。`error`、`max-tokens`、`refusal` 和未来未知失败原因都不会被误报成通过。rc.8 在父会话 idle 时也会用原生 settlement notice 唤醒，因此已经结束当前轮时无需额外调用 wait。
+4. **`/trellis` 命令** — `/trellis-status`（活跃任务 + git 状态）、`/trellis-finish`（只读检查 + 安全收尾清单，不提前清 active-task 指针）。命令输出不进模型历史；真正的会话收尾走技能面 `/trellis-finish-work`，由技能先归档再写 journal。rc.8 下两条零输入命令使用 `recordInput: false`，并显式拒绝参数和图片附件，避免静默忽略输入。
+5. **Web 配置菜单** — DSH rc.8 的“设置 → 插件 → 插件配置”会显示 Trellis 工作流卡片，可分阶段编辑全部六个配置项、恢复 profile 配置层并保存。写入经过 namespace revision fencing 和保存后读回确认；配置实时生效，禁用插件后卡片仍保留，可直接重新启用。
+
+非 Trellis 项目不注入面包屑；命令只有被用户显式调用时才会检查并返回“未初始化 Trellis”。
+
+这是 Trellis DSH 适配的**可选伴侣插件**，不是使用 `trellis init --dsh` 的前置条件。workflow 会按能力选择路径：存在 `trellis_wait` 时才使用 continuable 后台派发和事件汇合；未安装插件时，依赖结果的子代理从一开始就用 `run_in_background: false` 前台派发。两条路径都禁止 sleep 或轮询，Trellis CLI 也不会自动安装任何 DSH profile 插件。
+
+## 安装
+
+```powershell
+# 装进实际使用的 profile（均在该 profile 下次启动时生效）
+dsh plugin --profile web add dsh-trellis
+dsh plugin --profile headless add dsh-trellis
+
+# 如果你维护独立的 tui profile，也需要装进该 profile
+dsh plugin --profile tui add dsh-trellis
+```
+
+`dsh plugin` 会把插件安装到指定 profile；每个实际使用的 profile 都需要单独安装。升级到 npm 上的最新版本：
+
+```powershell
+dsh plugin --profile web update dsh-trellis
+dsh plugin --profile headless update dsh-trellis
+```
+
+对 `tui` profile 使用同样的 update，并在该 profile 下次启动时生效。
+
+如果要从源码开发或验证尚未发布的版本，可以改用本地 `file:` 安装：
+
+```powershell
+git clone https://github.com/SajoLuo/dsh-trellis.git
+cd dsh-trellis
+pnpm install --frozen-lockfile
+pnpm run build:client
+dsh plugin --profile headless add file:C:/path/to/dsh-trellis
+```
+
+`file:` 插件会作为 profile 内的 pnpm 快照安装；拉取源码更新后，尤其是版本新增文件时，需要先 remove 再 add 刷新该 profile。
+
+配套要求：项目的 Trellis 平台需包含 dsh（`trellis init --dsh`，见 Trellis-DeepSeekHarness 适配分支），且 `.trellis/scripts` 需包含读取原生 `DSH_SESSION_ID` 的适配（已含在同一分支）。Host peer 范围显式覆盖 DSH `0.1.0-rc.6+`、`0.1.1-rc.1+`、`0.1.2-alpha.1+`、`0.1.3-alpha.1+` 与 `0.1.5-alpha.1+` 五条已知预发布线，避免 npm 的 prerelease 语义把新版 Host 误判为不兼容；本仓开发与回归基线固定在 `0.1.5-rc.2`。Host 侧 Settings 桥同时兼容旧版包级 helper 与当前 provider 方法，Web 配置卡片只在具备 settings/client surface 的 profile 中加载。
+
+运行时需要 profile 提供 `sessionProjections` 服务；该依赖由插件的 `inject` 声明。自定义或精简 profile 若未组装此服务，需先加载 `@deepseek-ai/dsh-session-projection`，否则插件会等待依赖，不会退回直接扫描历史。
+
+### DSH 0.1.5-rc.2 对齐说明
+
+- 已迁移：面包屑使用 `sessionProjections` 的纯 fold，在恢复或分叉时重建状态、按已提交事件增量更新，不再调用 Session 的 `eventAt()` / `snapshotEvents()` / `ownEvents()` 或访问旧事件集合。当前 DSH 注册 Host-only projection；旧版 registry 通过 projection snapshot 兼容，仅包含序号和 payload 哈希，不传输工作流正文。
+- 已修复：恢复会话、插件或 Settings 重载后的首轮也会去重；以最后一条仍可见的面包屑判断，避免 A → B → A 状态切换被旧记录误抑制。压缩移除后会重新注入，字节预算变化导致的正文变化也会重新注入。
+- 前瞻适配：[上游同步历史读取弃用决策](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md) 已进入主线，但 RC.2 仍提供这些方法；本次提前解除依赖，不代表 RC.2 已删除接口。插件不负责迁移磁盘会话格式。
 - 已核对：插件不依赖 0.1.5 移除的 `ctx.agent` 或可构造 `Inbox`；pre-step 从事件载荷取得 agent，工具从 `exec.agent` 取得调用方，待处理消息只使用 `agent.inbox` 当前公开的 `nextStep`、`prepend`、`replace` 与 `remove`。
 - 已采用：command lifecycle 的 `recordInput`、command attachment envelope 的 fail-closed 输入检查、`subagent/end` 的 run/provider/final-output 元数据，以及 report-before-settlement 与 idle-parent 原生唤醒语义。
 - 已接入：Host `dsh-trellis` settings namespace 与 `dsh.client` 浏览器卡片。保存值写入 DSH 的 `settings.yaml` 用户层，并实时重挂插件 runtime；settings provider 单独重载时退回 loader 配置，插件自身卸载时则不会错误重挂 runtime。没有 settings 服务的 profile 继续使用原有 loader 配置。当前可选 Settings 生命周期由 `settings.installSection()` 承担；插件仍在运行时兼容旧版 helper。
@@ -59,37 +63,39 @@ dsh plugin --profile headless add file:C:/path/to/dsh-trellis
 ## 配置
 
 支持 Settings provider 的 DSH Web profile 可直接打开“设置 → 插件 → 插件配置 → Trellis 工作流”。保存内容进入该 DSH_HOME 的 `settings.yaml`，优先级高于 profile 组合层并立即生效。
-
-Headless、rc.6 或需要声明部署默认值时，仍可在 profile 的 `cordis.patch.yml` 里覆盖（整行替换）；Web 卡片的“恢复配置文件值”会清除用户层字段并重新继承这里的值：
-
-```yaml
-- id: dsh-trellis
-  config:
-    maxBytes: 4096          # 面包屑注入的字节预算（0 = 关闭注入）
-    skipKeyword: no-trellis # 提示词中的独立单词可跳过当轮注入（空 = 禁用）
-    pythonCmd: ""           # 空 = 自动选择：Windows 先 py -3 再 python；其他系统先 python3 再 python
-    commandsEnabled: true
-```
-
-## 工作原理
-
-- **状态解析**（`lib/workflow.js`）：向上找项目根 → 读 `.trellis/workflow.md` 解析状态块 → 先看当前会话指针 `.trellis/.runtime/sessions/dsh_<id>.json`。当前指针缺失时只允许 Trellis 官方的“唯一 session 文件”回退；存在 0 个或 2 个以上 session 文件就拒绝猜测，避免多个 DSH 窗口串任务。
-- **注入去重**：面包屑带 digest，与最近一次注入相同且仍在可见表面则不重复注入。
-- **会话身份**：DSH 原生提供 `DSH_SESSION_ID = agent.session.header.id`，并先丢弃环境中已有的 `DSH_*` 再重建受管命名空间。Trellis beta 因此会在同时看到 `DSH_SHELL=1` 与 `DSH_SESSION_ID` 时优先解析当前 DSH 身份，即使没有插件也不会被外层 host 继承的 `TRELLIS_CONTEXT_ID` 串任务。插件通过 `shellEnv` 为每次执行额外生成 `DSH_TRELLIS_CONTEXT_ID = dsh_<session-id>`，用于转发可能不同于 shell 自身 session 的子代理身份；主会话与子代理仍各自保留 DSH 身份，子代理通过派发 prompt 首行的 `Active task:` 和角色 prelude 取得父任务上下文。
-- **Headless 会话**：每次 `dsh --profile headless` 调用都是新的 DSH session。需要跨轮保留 active-task 指针时，应保持同一会话或显式 resume 返回的 session id，不能把多个独立 headless 调用当成同一 session。
-- **取消与生命周期**：命令和 `trellis_wait` 都继承 DSH invocation 的 `AbortSignal`；取消后命令不会继续尝试另一个 Python 启动器，等待工具也会立即注销临时事件监听器。`trellis_wait` 只在收到配对的结算事件时声明 `settlementNoticeQueued=true`；仅从 catalog 看到 inactive 时保持 `unknown`，不猜任务通过。插件卸载时只注销自己的命令、工具和监听器。
-- **子代理并发**：workflow 只有在发现 `trellis_wait` 时才使用 DSH 原生 continuable 后台 `subagent`。主会话并行做独立工作；需要汇合时调用一次 `trellis_wait <subagent_id>` 等待原生结算事件。没有该工具时，首次派发直接设置 `run_in_background: false`，绝不留下无法事件汇合的后台子代理。
-
-## 开发
-
-```powershell
-pnpm install
-pnpm run build:client
-pnpm test    # node --test test/*.test.js
-```
-
-Host half 是直接由 `main` 加载的 ESM JavaScript；Web half 通过 tsdown 生成 DSH lazy-CJS factory 到 `lib/client.js`。`pnpm pack` 会在 prepack 阶段自动重建客户端 bundle。
-
-## License
-
-MIT
+
+Headless、rc.6 或需要声明部署默认值时，仍可在 profile 的 `cordis.patch.yml` 里覆盖（整行替换）；Web 卡片的“恢复配置文件值”会清除用户层字段并重新继承这里的值：
+
+```yaml
+- id: dsh-trellis
+  config:
+    maxBytes: 4096          # 面包屑注入的字节预算（0 = 关闭注入）
+    skipKeyword: no-trellis # 提示词中的独立单词可跳过当轮注入（空 = 禁用）
+    pythonCmd: ""           # 空 = 自动选择：Windows 先 py -3 再 python；其他系统先 python3 再 python
+    commandsEnabled: true
+```
+
+## 工作原理
+
+- **状态解析**（`lib/workflow.js`）：向上找项目根 → 读 `.trellis/workflow.md` 解析状态块 → 先看当前会话指针 `.trellis/.runtime/sessions/dsh_<id>.json`。当前指针缺失时只允许 Trellis 官方的“唯一 session 文件”回退；存在 0 个或 2 个以上 session 文件就拒绝猜测，避免多个 DSH 窗口串任务。
+- **注入去重**（`lib/breadcrumb-projection.js`）：投影仅保存面包屑的事件序号和 source/content 指纹，与 DSH 已维护的 `session.surface.nodes` 一起确定最后可见面包屑。恢复、分叉和重载均从 projection 重建；不缓存“本进程最后注入”的临时判断，也不扫描完整事件历史。
+- **会话身份**：DSH 原生提供 `DSH_SESSION_ID = agent.session.header.id`，并先丢弃环境中已有的 `DSH_*` 再重建受管命名空间。Trellis beta 因此会在同时看到 `DSH_SHELL=1` 与 `DSH_SESSION_ID` 时优先解析当前 DSH 身份，即使没有插件也不会被外层 host 继承的 `TRELLIS_CONTEXT_ID` 串任务。插件通过 `shellEnv` 为每次执行额外生成 `DSH_TRELLIS_CONTEXT_ID = dsh_<session-id>`，用于转发可能不同于 shell 自身 session 的子代理身份；主会话与子代理仍各自保留 DSH 身份，子代理通过派发 prompt 首行的 `Active task:` 和角色 prelude 取得父任务上下文。
+- **Headless 会话**：每次 `dsh --profile headless` 调用都是新的 DSH session。需要跨轮保留 active-task 指针时，应保持同一会话或显式 resume 返回的 session id，不能把多个独立 headless 调用当成同一 session。
+- **取消与生命周期**：命令和 `trellis_wait` 都继承 DSH invocation 的 `AbortSignal`；取消后命令不会继续尝试另一个 Python 启动器，等待工具也会立即注销临时事件监听器。`trellis_wait` 只在收到配对的结算事件时声明 `settlementNoticeQueued=true`；仅从 catalog 看到 inactive 时保持 `unknown`，不猜任务通过。插件卸载时只注销自己的命令、工具和监听器。
+- **子代理并发**：workflow 只有在发现 `trellis_wait` 时才使用 DSH 原生 continuable 后台 `subagent`。主会话并行做独立工作；需要汇合时调用一次 `trellis_wait <subagent_id>` 等待原生结算事件。没有该工具时，首次派发直接设置 `run_in_background: false`，绝不留下无法事件汇合的后台子代理。
+
+## 开发
+
+```powershell
+pnpm install
+pnpm run build:client
+pnpm test    # node --test test/*.test.js
+```
+
+GitHub Actions 在 Windows / Linux 的 Node 24 环境执行锁定安装、客户端构建、测试和打包检查；其中包含真实 Session/projection 服务的增量驱动、恢复、分叉、压缩和 checkpoint 回归。
+
+Host half 是直接由 `main` 加载的 ESM JavaScript；Web half 通过 tsdown 生成 DSH lazy-CJS factory 到 `lib/client.js`。`pnpm pack` 会在 prepack 阶段自动重建客户端 bundle。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -1,5 +1,5 @@
 # dsh-trellis bundle patch: one insert over the composed profile tree.
-# Service injection (commands, tools, and subagents) is declared by the plugin module.
+# Service injection (including sessionProjections) is declared by the plugin module.
 - insert:
     - id: dsh-trellis
       name: dsh-trellis

package/lib/breadcrumb-projection.js

@@ -0,0 +1,78 @@
+/**
+ * Replayable breadcrumb identity, driven by DSH's projection registry.
+ * Only fingerprints are retained, never message bodies or a second event log.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isBreadcrumbMessage } from "./breadcrumb.js";
+
+export const BREADCRUMB_PROJECTION_KEY = "dsh-trellis.breadcrumbs";
+
+/** Stable JSON payload identity, excluding the per-injection message id. */
+export function breadcrumbFingerprint(message) {
+  const json = JSON.stringify(
+    { content: message.content, source: message.source },
+    (_key, value) =>
+      value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) =>
+            a < b ? -1 : a > b ? 1 : 0,
+          ))
+        : value,
+  );
+  return createHash("sha256").update(json).digest("hex");
+}
+
+export const breadcrumbProjection = {
+  key: BREADCRUMB_PROJECTION_KEY,
+  stateVersion: 1,
+  stateSchema: z.record(
+    z.string().regex(/^(0|[1-9]\d*)$/),
+    z.string().regex(/^[a-f0-9]{64}$/),
+  ),
+  init: () => ({}),
+  apply(state, event) {
+    if (event.type !== "user/message" || !isBreadcrumbMessage(event.data)) {
+      return state;
+    }
+    return { ...state, [event.seq]: breadcrumbFingerprint(event.data) };
+  },
+};
+
+/** Register/read on the owning runtime scope; unload removes our key only. */
+export function registerBreadcrumbProjection(ctx) {
+  const registry = ctx.sessionProjections;
+  if (typeof registry?.register !== "function") {
+    throw new Error("dsh-trellis requires the DSH sessionProjections service");
+  }
+  const hostOnly = typeof registry.stateOf === "function";
+  // rc.6 predates host-only units. Its projection snapshot contains only our
+  // seq -> hash index, not workflow text. This is NOT a Session log snapshot.
+  const definition = hostOnly ? breadcrumbProjection : {
+    ...breadcrumbProjection,
+    schema: breadcrumbProjection.stateSchema,
+    view: (state) => state,
+  };
+  const dispose = registry.register(definition);
+  return {
+    dispose,
+    isVisible(session, message) {
+      const state = hostOnly
+        ? registry.stateOf(session, BREADCRUMB_PROJECTION_KEY)
+        : registry.snapshot(session).values[BREADCRUMB_PROJECTION_KEY];
+      if (state === undefined) {
+        throw new Error("dsh-trellis breadcrumb projection is not registered");
+      }
+      // Surface order, not maximum event seq: replacements can reorder seqs.
+      // Only the LAST visible breadcrumb may suppress a new state (A -> B -> A).
+      // Provenance can cite still-visible nodes, so do not prune by sourceEventSeqs.
+      const nodes = session.surface.nodes;
+      for (let i = nodes.length - 1; i >= 0; i -= 1) {
+        const fingerprint = state[nodes[i]];
+        if (fingerprint !== undefined) {
+          return fingerprint === breadcrumbFingerprint(message);
+        }
+      }
+      return false;
+    },
+  };
+}

package/lib/breadcrumb.js

@@ -4,7 +4,6 @@
  * @module dsh-trellis/breadcrumb
  */
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { join } from "node:path";
 import { resolveTrellisState, sanitizeContextKey } from "./workflow.js";
 import { nodeFs } from "./node-fs.js";
 
@@ -61,39 +60,6 @@ export function isBreadcrumbMessage(message) {
   );
 }
 
-/** Read one session event across the current and legacy DSH session APIs. */
-export function sessionEventAt(session, seq) {
-  if (typeof session.eventAt === "function") return session.eventAt(seq);
-  if (typeof session.events?.get === "function") return session.events.get(seq);
-  return session.events?.[seq];
-}
-
-/** Whether the same breadcrumb payload is already visible in the session surface. */
-export function isBreadcrumbVisible(agent, digest) {
-  const { session } = agent;
-  const visibleSeqs = new Set(session.surface.nodes);
-  // Current DSH sessions, including Session V3, expose an immutable on-demand
-  // snapshot. Keep the legacy collection fallback for older versions covered
-  // by our peer range.
-  const events =
-    typeof session.snapshotEvents === "function"
-      ? session.snapshotEvents()
-      : session.events;
-  for (const [fallbackSeq, event] of events.entries()) {
-    const seq = event?.seq ?? fallbackSeq;
-    if (!visibleSeqs.has(seq) || event.type !== "user/message") continue;
-    const source = event.data?.source;
-    if (
-      source?.kind === SOURCE_KIND &&
-      source?.form === SOURCE_FORM &&
-      source.digest === digest
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
 /**
  * Does the claimed prompt batch contain the skip keyword as a standalone word?
  * @param {Array<{content?: unknown}>} messages
@@ -127,7 +93,6 @@ export function hasSkipKeyword(messages, keyword) {
 export function createBreadcrumbComposer(resolved, ctx, dependencies = {}) {
   const fs = dependencies.fs ?? nodeFs;
   const cache = new Map();
-  const lastInjected = new WeakMap();
 
   const compose = async (agent, messages, signal) => {
     if (resolved.maxBytes <= 0 || !Number.isFinite(resolved.maxBytes))
@@ -147,11 +112,6 @@ export function createBreadcrumbComposer(resolved, ctx, dependencies = {}) {
     });
     signal?.throwIfAborted();
     if (state === null) return undefined;
-    const previous = lastInjected.get(agent.session);
-    if (previous !== undefined && previous.digest === state.digest) {
-      if (isBreadcrumbVisible(agent, state.digest)) return undefined;
-    }
-    lastInjected.set(agent.session, { digest: state.digest });
     return breadcrumbMessage(state, resolved.maxBytes);
   };
 

package/lib/index.js

@@ -25,8 +25,8 @@ import { Config, resolveConfig } from "./config.js";
 import {
   createBreadcrumbComposer,
   isBreadcrumbMessage,
-  sessionEventAt,
 } from "./breadcrumb.js";
+import { registerBreadcrumbProjection } from "./breadcrumb-projection.js";
 import { registerCommands } from "./commands.js";
 import { registerSessionEnv } from "./session-env.js";
 import { installSettingsSectionCompat } from "./settings-compat.js";
@@ -36,7 +36,7 @@ export const name = "dsh-trellis";
 export const SETTINGS_NAMESPACE = "dsh-trellis";
 
 /** @type {string[]} */
-export const inject = ["commands", "shellEnv", "subagents", "tools"];
+export const inject = ["commands", "shellEnv", "subagents", "tools", "sessionProjections"];
 
 export { Config };
 
@@ -131,26 +131,12 @@ export function insertBreadcrumbDecision(decision, claimedMessages, desired) {
   };
 }
 
-function registerBreadcrumb(ctx, resolved) {
-  const { compose } = createBreadcrumbComposer(resolved, ctx);
+function registerBreadcrumb(ctx, resolved) {
+  const { compose } = createBreadcrumbComposer(resolved, ctx);
+  const projection = registerBreadcrumbProjection(ctx);
 
   const syncInbox = (agent, desired) => {
     const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
-    const alreadySupplied =
-      desired === undefined ||
-      agent.session.surface.nodes.some((seq) => {
-        const event = sessionEventAt(agent.session, seq);
-        return (
-          event?.type === "user/message" &&
-          event.data !== undefined &&
-          isBreadcrumbMessage(event.data) &&
-          sameBreadcrumbPayload(event.data, desired)
-        );
-      });
-    if (alreadySupplied) {
-      for (const message of pending) agent.inbox.remove(message.id);
-      return;
-    }
     const reusable = pending.find((message) =>
       sameBreadcrumbPayload(message, desired),
     );
@@ -165,41 +151,54 @@ function registerBreadcrumb(ctx, resolved) {
     for (const message of pending.slice(1)) agent.inbox.remove(message.id);
   };
 
-  return ctx.on("agent/pre-step", async ({ agent, messages, step, signal }, next) => {
-    const decision = await next();
-    let desired;
-    try {
-      desired = await compose(agent, messages, signal);
-    } catch (error) {
-      if (signal !== undefined && signal.aborted) throw error;
-      ctx.logger?.warn?.(
-        "dsh-trellis breadcrumb composition failed: %o",
-        error,
-      );
-      return decision;
-    }
-    signal?.throwIfAborted();
-    if (desired === undefined) {
-      const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
-      for (const message of pending) agent.inbox.remove(message.id);
-      return decision;
-    }
-    if (
-      decision.kind === "reject" ||
-      (step === 1 && decision.messages.length === 0)
-    ) {
-      syncInbox(agent, desired);
-      return decision;
-    }
-    const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
-    for (const message of pending) agent.inbox.remove(message.id);
-    if (
-      decision.messages.some((message) =>
-        sameBreadcrumbPayload(message, desired),
-      )
-    ) {
-      return decision;
-    }
-    return insertBreadcrumbDecision(decision, messages, desired);
-  });
+  let disposeStep;
+  try {
+    disposeStep = ctx.on("agent/pre-step", async ({ agent, messages, step, signal }, next) => {
+      const decision = await next();
+      let desired;
+      try {
+        desired = await compose(agent, messages, signal);
+        if (desired !== undefined && projection.isVisible(agent.session, desired)) {
+          desired = undefined;
+        }
+      } catch (error) {
+        if (signal !== undefined && signal.aborted) throw error;
+        ctx.logger?.warn?.(
+          "dsh-trellis breadcrumb composition failed: %o",
+          error,
+        );
+        return decision;
+      }
+      signal?.throwIfAborted();
+      if (desired === undefined) {
+        const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
+        for (const message of pending) agent.inbox.remove(message.id);
+        return decision;
+      }
+      if (
+        decision.kind === "reject" ||
+        (step === 1 && decision.messages.length === 0)
+      ) {
+        syncInbox(agent, desired);
+        return decision;
+      }
+      const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
+      for (const message of pending) agent.inbox.remove(message.id);
+      if (
+        decision.messages.some((message) =>
+          sameBreadcrumbPayload(message, desired),
+        )
+      ) {
+        return decision;
+      }
+      return insertBreadcrumbDecision(decision, messages, desired);
+    });
+  } catch (error) {
+    projection.dispose();
+    throw error;
+  }
+  return () => {
+    disposeStep();
+    projection.dispose();
+  };
 }

package/package.json

@@ -1,121 +1,128 @@
-{
-  "name": "dsh-trellis",
-  "version": "0.1.4",
-  "description": "Trellis workflow integration for DeepSeek Harness: per-turn workflow-state breadcrumbs, utility commands, and native session identity.",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./lib/client.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml"
-  ],
-  "author": "SajoLuo",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SajoLuo/dsh-trellis.git"
-  },
-  "homepage": "https://github.com/SajoLuo/dsh-trellis#readme",
-  "bugs": {
-    "url": "https://github.com/SajoLuo/dsh-trellis/issues"
-  },
-  "keywords": [
-    "deepseek-harness",
-    "dsh",
-    "trellis",
-    "workflow",
-    "ai-agent"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "packageManager": "pnpm@10.33.0",
-  "dsh": {
-    "bundle": {
-      "patch": "cordis.patch.yml"
-    },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
-      ],
-      "platform": "web"
-    }
-  },
-  "scripts": {
-    "build:client": "tsdown",
-    "test": "node --test \"test/*.test.js\"",
-    "prepack": "pnpm run build:client"
-  },
-  "peerDependencies": {
+{
+  "name": "dsh-trellis",
+  "version": "0.1.5",
+  "description": "Trellis workflow integration for DeepSeek Harness: per-turn workflow-state breadcrumbs, utility commands, and native session identity.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "author": "SajoLuo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SajoLuo/dsh-trellis.git"
+  },
+  "homepage": "https://github.com/SajoLuo/dsh-trellis#readme",
+  "bugs": {
+    "url": "https://github.com/SajoLuo/dsh-trellis/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "trellis",
+    "workflow",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "dsh": {
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build:client": "tsdown",
+    "test": "node --test \"test/*.test.js\"",
+    "prepack": "pnpm run build:client"
+  },
+  "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.3-alpha.1 || ^0.1.5-alpha.1",
     "@deepseek-ai/schemastery": "^3.18.2"
-  },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/cordis": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-commands": {
-      "optional": true
-    },
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
+    "@deepseek-ai/dsh-session-projection": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-settings": {
       "optional": true
     },
-    "@deepseek-ai/dsh-shell-env": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-subagent": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    },
+    "@deepseek-ai/dsh-shell-env": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-subagent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
     "@deepseek-ai/schemastery": {
       "optional": true
     }
-  },
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-attachment": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-code-runtime": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-commands": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-home-paths": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-invariants": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-shell": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-shell-env": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.1.5-alpha.2",
-    "@deepseek-ai/dsh-util-time": "0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-code-runtime": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-commands": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-shell": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-shell-env": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-util-time": "0.1.5-rc.2",
     "@deepseek-ai/schemastery": "^3.18.2",
     "react": "19.2.8",
-    "tsdown": "^0.22.2"
-  }
-}
+    "tsdown": "^0.22.2"
+  }
+}