dsh-trellis 0.1.14 → 0.1.16

package/README.md

@@ -27,10 +27,10 @@ dsh plugin --profile tui add dsh-trellis
 
 DSH `0.2.0-rc.2` 的 macOS / Windows 桌面端可在菜单栏“Manage dsh command”中安装或管理内置 `dsh` 命令，无需单独安装 Node 或 pnpm。先用 `dsh --version` 确认 PATH 中实际调用的版本；旧的全局 CLI 可能与桌面端不同。桌面端默认使用 `desktop` profile，其他 profile 仍需分别安装。
 
-新版本刚发布时，插件页预览的版本可能与安装器最终选择的版本不同。需要本版插件 `0.1.14` 时，在插件页输入 `dsh-trellis@0.1.14`，或显式安装到实际使用的 profile：
+新版本刚发布时，插件页预览的版本可能与安装器最终选择的版本不同。需要本版插件 `0.1.16` 时，在插件页输入 `dsh-trellis@0.1.16`，或显式安装到实际使用的 profile：
 
 ```powershell
-dsh plugin --profile desktop add dsh-trellis@0.1.14
+dsh plugin --profile desktop add dsh-trellis@0.1.16
 # Web / headless 用户将 desktop 替换为对应 profile 名称。
 ```
 
@@ -59,10 +59,20 @@ dsh plugin --profile headless add file:C:/path/to/dsh-trellis
 
 `file:` 插件会作为 profile 内的 pnpm 快照安装；拉取源码更新后，尤其是版本新增文件时，需要先 remove 再 add 刷新该 profile。外部 CLI 刷新快照后重启对应进程，不要假定源码目录变化会自动热更新。
 
-配套要求：项目的 Trellis 平台需包含 dsh（`trellis init --dsh`，见 Trellis-DeepSeekHarness 适配分支），且 `.trellis/scripts` 需包含读取原生 `DSH_SESSION_ID` 的适配（已含在同一分支）。现有 `engines.dsh` 和 Host peer 范围已接纳 `0.2.1-rc.3`，无需为每个预发布标签追加范围。`0.2.1-alpha.4` 起宿主优先检查显式 `engines.dsh`，仅未声明时才回退 DSH peer；其 `includePrerelease: true` 规则与 npm 默认匹配不同。通过准入不等于实际兼容，不应使用 `allow-version` 绕过缺失的 API。开发基线固定为 `0.2.0-rc.1`，隔离回归目标见开发章节的十三个明确宿主，不代表测试了范围内所有版本。Web 配置只在具备对应 client surface 的 profile 中加载。参见[官方版本声明迁移说明](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md)。
+配套要求：项目的 Trellis 平台需包含 dsh（`trellis init --dsh`，见 Trellis-DeepSeekHarness 适配分支），且 `.trellis/scripts` 需包含读取原生 `DSH_SESSION_ID` 的适配（已含在同一分支）。现有 `engines.dsh` 和 Host peer 范围已接纳 `0.2.1-rc.4`，无需为每个预发布标签追加范围。`0.2.1-alpha.4` 起宿主优先检查显式 `engines.dsh`，仅未声明时才回退 DSH peer；其 `includePrerelease: true` 规则与 npm 默认匹配不同。通过准入不等于实际兼容，不应使用 `allow-version` 绕过缺失的 API。开发基线固定为 `0.2.0-rc.1`，隔离回归目标见开发章节的十四个明确宿主，不代表测试了范围内所有版本。Web 配置只在具备对应 client surface 的 profile 中加载。参见[官方版本声明迁移说明](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md)。
 
 运行时需要 profile 提供 `sessionProjections` 服务；该依赖由插件的 `inject` 声明。自定义或精简 profile 若未组装此服务，需先加载 `@deepseek-ai/dsh-session-projection`，否则插件会等待依赖，不会退回直接扫描历史。
 
+### 0.1.16：OIDC 发布自动化
+
+- 增加指定标签的手动 OIDC 发布工作流，复用同一提交的 Windows/Linux 完整测试矩阵；不保存长期 npm 发布令牌。
+- 核对 main 历史、包名和版本后才构建发布，不改插件运行时代码、依赖或兼容范围。
+
+### 0.1.15：DSH 0.2.1-rc.4 兼容回归
+
+- 为 npm 发布的 RC.4 增加精确工具链映射、独立预期和 Windows/Linux CI 目标；保留生产代码、依赖基线及现有版本范围。未知 RC.5 仍拒绝执行。
+- 十四个宿主的本地跨平台结果及隔离 Web 验证范围见 [RC.4 验证记录](docs/validation-dsh-0.2.1-rc.4.md)；不将本地通过写作远端 CI 或新版已发布。
+
 ### 0.1.14：DSH 0.2.1-rc.3 兼容回归
 
 - 为 RC.3 增加精确工具链映射、独立预期和 Windows/Linux CI 目标；版本准入测试自动覆盖新增目标。保留开发基线、peer / engine 范围及生产代码，未知宿主仍拒绝执行。
@@ -177,16 +187,17 @@ pnpm run test:compat 0.2.0-rc.2  # 保留 0.2.0 RC.2 回归
 pnpm run test:compat 0.2.1-alpha.2 # 新工作目录与统一 activation 契约
 pnpm run test:compat 0.2.1-rc.2 # 保留 RC.2 隔离回归
 pnpm run test:compat 0.2.1-rc.3 # RC.3 隔离回归
-pnpm run test:compat # 默认跑全部十三个显式目标
+pnpm run test:compat 0.2.1-rc.4 # RC.4 隔离回归
+pnpm run test:compat # 默认跑全部十四个显式目标
 ```
 
-GitHub Actions 配置在 Windows / Linux 的 Node 24 环境执行锁定的 `0.2.0-rc.1` 安装、客户端构建、测试、其余十二个宿主的隔离回归及打包检查。测试覆盖真实 Session/projection 的恢复、分叉、压缩和 checkpoint，临时项目的精确绑定与任务错误恢复，以及新版真实 Loader 的 volatile 更新、子代理目录/查询/驻留状态；新版专属测试在旧宿主明确跳过。另有编译客户端 React 渲染、slot 生命周期、原子保存与拒绝写入测试。配置了 CI 目标不等于远端 CI 已运行，结果以对应提交为准。
+GitHub Actions 配置在 Windows / Linux 的 Node 24 环境执行锁定的 `0.2.0-rc.1` 安装、客户端构建、测试、其余十三个宿主的隔离回归及打包检查。测试覆盖真实 Session/projection 的恢复、分叉、压缩和 checkpoint，临时项目的精确绑定与任务错误恢复，以及新版真实 Loader 的 volatile 更新、子代理目录/查询/驻留状态；新版专属测试在旧宿主明确跳过。另有编译客户端 React 渲染、slot 生命周期、原子保存与拒绝写入测试。配置了 CI 目标不等于远端 CI 已运行，结果以对应提交为准。
 
 RC.2 集成用例运行真实 AgentLoop、Loader、ToolRuntime 和 Session，以本地脚本化模型响应验证三种 `toolUpdate` 能力：不支持、`addition-only`、`in-history`。覆盖插件启停的工具增删消息、Settings 重挂不重复注入、混合历史的恢复/分叉投影，以及 surface 替换后重建工具基线并重新注入面包屑。等待工具另覆盖目录损坏/不存在及卸载期间查询失败的错误保留与监听器清理。该验证不调用外部模型，也不替代 Web 浏览器或真实子代理派发验收；详情见 [2026-09-28 验证记录](https://github.com/SajoLuo/dsh-trellis/blob/main/docs/validation-dsh-0.1.7-rc.2.md)。
 
 0.2 集成用例另以真实 AgentLoop / ToolRuntime / Session 和实际 `trellis_wait` 验证失败工具历史的补齐顺序、错误分类、监听器清理及继续会话的消息配对。只注入 scheduler 故障和本地模型响应，不增加运行时补丁或自动重试；旧宿主按 `ToolCallRecovery` 能力明确跳过。还覆盖“目录查询期间收到成功结算、随后查询失败”的竞争，查询错误不能被伪装成成功。
 
-`test:compat` 不改当前 checkout 的依赖，临时副本保留在系统临时目录并打印路径供检查。十三个目标采用以下明确配对，不按“非最新版本”猜测；未知宿主必须先核对官方包并补齐测试。
+`test:compat` 不改当前 checkout 的依赖，临时副本保留在系统临时目录并打印路径供检查。十四个目标采用以下明确配对，不按“非最新版本”猜测；未知宿主必须先核对官方包并补齐测试。
 
 | DSH 目标 | Cordis | Schemastery | Include | Loader |
 |---|---|---|---|---|
@@ -194,12 +205,28 @@ RC.2 集成用例运行真实 AgentLoop、Loader、ToolRuntime 和 Session，以
 | 0.1.7-rc.1 / rc.2、0.2.0-rc.1 / rc.2 | 4.0.4 | 3.18.4 | 1.0.9 | 1.0.5 |
 | 0.2.1-alpha.2 | 4.0.5-alpha.1 | 3.18.5-alpha.1 | 1.0.10-alpha.1 | 1.0.6-alpha.1 |
 | 0.2.1-alpha.3 / alpha.4 / alpha.5 | 4.0.5-alpha.2 | 3.18.5-alpha.2 | 1.0.10-alpha.2 | 1.0.6-alpha.2 |
-| 0.2.1-rc.1 / rc.2 / rc.3 | 4.0.5 | 3.18.5 | 1.0.10 | 1.0.6 |
+| 0.2.1-rc.1 / rc.2 / rc.3 / rc.4 | 4.0.5 | 3.18.5 | 1.0.10 | 1.0.6 |
 
-发布前还应使用隔离 `DSH_HOME` 启动真实 Web profile，验证配置保存/读回、整包及组件开关、重新挂载和卸载；不复用个人凭据或会话。代码 HMR、外部 CLI 快照刷新和浏览器跨宿主 release 刷新是不同验收项，不能用一次开关测试代替。当前结果与未覆盖项见 [2026-10-25 RC.3 验证记录](docs/validation-dsh-0.2.1-rc.3.md)，[RC.2 记录](docs/validation-dsh-0.2.1-rc.2.md)保留为历史证据。
+发布前还应使用隔离 `DSH_HOME` 启动真实 Web profile，验证配置保存/读回、整包及组件开关、重新挂载和卸载；不复用个人凭据或会话。代码 HMR、外部 CLI 快照刷新和浏览器跨宿主 release 刷新是不同验收项，不能用一次开关测试代替。当前结果与未覆盖项见 [2026-10-27 RC.4 验证记录](docs/validation-dsh-0.2.1-rc.4.md)，[RC.3 记录](docs/validation-dsh-0.2.1-rc.3.md)与 [RC.2 记录](docs/validation-dsh-0.2.1-rc.2.md)保留为历史证据。
 
 Host half 是直接由 `main` 加载的 ESM JavaScript；Web half 通过 tsdown 生成 DSH lazy-CJS factory 到 `lib/client.js`。`pnpm pack` 会在 prepack 阶段自动重建客户端 bundle。
 
+## 自动发布
+
+`.github/workflows/publish.yml` 使用 npm [Trusted Publishing / OIDC](https://docs.npmjs.com/trusted-publishers/)，不保存长期 `NPM_TOKEN`。需先在 npm 的 `dsh-trellis` 包设置中绑定 GitHub 用户 `SajoLuo`、仓库 `dsh-trellis`、工作流文件名 `publish.yml`，并允许 `npm publish`；不需要单独的 dist-tag 管理权限。首次配置需要维护者交互确认。
+
+发布流程仅允许在本仓库的 `main` 手动触发，指定已有的稳定版标签。标签必须位于 main 历史中，且包名、标签版本、main 的包版本一致。工作流解析出不可变提交 SHA，让现有 Windows/Linux 完整测试矩阵和发布构建都使用同一个 SHA；测试失败或跳过整个测试任务时不发布。只有发布任务拥有 OIDC 权限，普通 push / PR 不会触发发布。
+
+启用后，由发布操作者执行，例如：
+
+```powershell
+gh workflow run publish.yml --repo SajoLuo/dsh-trellis --ref main -f tag=v0.1.16
+```
+
+GitHub-hosted runner 通过 OIDC 获取临时发布凭据并生成 provenance。这里的授权属于指定发布流程；本机直接运行 `npm publish` 仍按 npm 的交互认证规则执行。首次 OIDC 真发布前，不把配置或本地检查视为认证已经验证成功。
+
+新 Trusted Publisher 创建后，需在 48 小时内成功发布一次才能完成验证并免于过期。过期后须重新创建连接；不要把待验证状态当作已完成端到端验证。参见 [npm 可信发布连接的验证期限](https://github.blog/changelog/2026-10-02-unvalidated-npm-trusted-publishing-configurations-now-expire/)。
+
 ## License
 
 MIT

package/lib/commands.js

@@ -1,226 +1,226 @@
-/**
- * Human-facing /trellis commands: status and finish.
- *
- * Command names follow the dsh grammar (lowercase letters, digits, `_`, `-`;
- * no `:`), and deliberately avoid the skill names (`trellis-start`,
- * `trellis-continue`, `trellis-finish-work`): a command sharing a skill name
- * would shadow the skill's slash-pipeline injection. The Trellis session
- * rituals stay on the skill surface; these commands cover the deterministic,
- * zero-token side — pointer inspection and wrap-up.
- *
- * @module dsh-trellis/commands
- */
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { join } from "node:path";
-import { findProjectRoot } from "./workflow.js";
-import { nodeFs } from "./node-fs.js";
-import { dshContextKey } from "./session-env.js";
-import { resolveWorkingDirectory } from "./working-directory.js";
-
-const execFileAsync = promisify(execFile);
-
-/** Platform-aware Python launch candidates. An explicit config disables fallback. */
-export function pythonCandidates(config, platform = process.platform) {
-  if (config.pythonCmd) return [{ command: config.pythonCmd, prefixArgs: [] }];
-  if (platform === "win32") {
-    return [
-      { command: "py", prefixArgs: ["-3"] },
-      { command: "python", prefixArgs: [] },
-    ];
-  }
-  return [
-    { command: "python3", prefixArgs: [] },
-    { command: "python", prefixArgs: [] },
-  ];
-}
-
-/** Run a project Trellis script with bounded time and output. */
-export async function runTrellisScript(
-  config,
-  root,
-  sessionId,
-  scriptArgs,
-  dependencies = {},
-) {
-  const execute = dependencies.execFile ?? execFileAsync;
-  const platform = dependencies.platform ?? process.platform;
-  const signal = dependencies.signal;
-  const contextKey = dshContextKey(sessionId);
-  const env = {
-    ...process.env,
-    ...(contextKey
-      ? {
-          TRELLIS_CONTEXT_ID: contextKey,
-          DSH_TRELLIS_CONTEXT_ID: contextKey,
-          DSH_SHELL: "1",
-          DSH_SESSION_ID: sessionId,
-        }
-      : {}),
-  };
-  const script = join(root, ".trellis", "scripts", "task.py");
-  const candidates = pythonCandidates(config, platform);
-  for (const [index, candidate] of candidates.entries()) {
-    const args = [...candidate.prefixArgs, script, ...scriptArgs];
-    try {
-      const { stdout, stderr } = await execute(candidate.command, args, {
-        cwd: root,
-        env,
-        windowsHide: true,
-        timeout: 15_000,
-        maxBuffer: 256 * 1024,
-        ...(signal ? { signal } : {}),
-      });
-      const text = `${stdout}${stderr ? `\n${stderr}` : ""}`.trim();
-      return { kind: "success", text };
-    } catch (error) {
-      if (signal?.aborted || error?.name === "AbortError") {
-        return { kind: "error", text: "Trellis command cancelled." };
-      }
-      const missing = error?.code === "ENOENT";
-      if (missing && index < candidates.length - 1) continue;
-      const attempted = candidates
-        .slice(0, index + 1)
-        .map(({ command, prefixArgs }) => [command, ...prefixArgs].join(" "))
-        .join(", ");
-      const message = missing
-        ? `Python command not found (tried: ${attempted}). Set the plugin's pythonCmd config to a Python 3 executable.`
-        : `Trellis script failed via ${[candidate.command, ...candidate.prefixArgs].join(" ")}: ${error?.message ?? String(error)}`;
-      return { kind: "error", text: message };
-    }
-  }
-  return {
-    kind: "error",
-    text: "No Python command candidates are configured.",
-  };
-}
-
-/**
- * Register the /trellis command family.
- * @param {object} ctx - cordis context exposing `ctx.commands`.
- * @param {object} resolved - normalized plugin config.
- * @returns {() => void} disposer.
- */
-export function registerCommands(ctx, resolved, dependencies = {}) {
-  const fs = dependencies.fs ?? nodeFs;
-  const execute = dependencies.execFile ?? execFileAsync;
-  const platform = dependencies.platform ?? process.platform;
-  const disposers = [];
-
-  const withoutInput = (invocation, fn) => {
-    const rawInput = invocation.rawInput ?? "";
-    const attachments = invocation.attachments ?? [];
-    if (rawInput.trim() !== "" || attachments.length > 0) {
-      return {
-        kind: "error",
-        text: "This Trellis command does not accept arguments or image attachments.",
-      };
-    }
-    return fn();
-  };
-
-  const withProject = async (invocation, fn) => {
-    let cwd;
-    try {
-      cwd = await resolveWorkingDirectory(ctx, invocation.agent, invocation.signal);
-    } catch (error) {
-      return {
-        kind: "error",
-        text: invocation.signal?.aborted
-          ? "Trellis command cancelled."
-          : `Cannot resolve the current DSH working directory: ${error?.message ?? String(error)}`,
-      };
-    }
-    const root = await findProjectRoot(cwd, resolved.projectRootMarkers, fs);
-    if (root === null) {
-      return {
-        kind: "error",
-        text: "No project root found from the configured markers.",
-      };
-    }
-    const workflow = join(root, ".trellis", "workflow.md");
-    const taskScript = join(root, ".trellis", "scripts", "task.py");
-    if (!(await fs.exists(workflow)) || !(await fs.exists(taskScript))) {
-      return {
-        kind: "error",
-        text: "No Trellis project found (expected .trellis/workflow.md and .trellis/scripts/task.py).",
-      };
-    }
-    const sessionId = invocation.agent?.session?.header?.id ?? "";
-    return fn(root, sessionId, invocation.signal);
-  };
-
-  disposers.push(
-    ctx.commands.register({
-      name: "trellis-status",
-      description: "Show the Trellis active task and git status.",
-      // DSH rc.8 records command lifecycle events. These commands have no
-      // payload of their own, so omit empty/invalid input from the durable log.
-      recordInput: false,
-      handler: (invocation) =>
-        withoutInput(invocation, () =>
-          withProject(invocation, async (root, sessionId, signal) => {
-            const task = await runTrellisScript(
-              resolved,
-              root,
-              sessionId,
-              ["current", "--source"],
-              { execFile: execute, platform, signal },
-            );
-            if (signal?.aborted) return task;
-            let git = "";
-            try {
-              const { stdout } = await execute(
-                "git",
-                ["status", "--short", "--branch"],
-                {
-                  cwd: root,
-                  windowsHide: true,
-                  timeout: 10_000,
-                  maxBuffer: 128 * 1024,
-                  ...(signal ? { signal } : {}),
-                },
-              );
-              git = `\n\nGit status:\n${stdout.trim()}`;
-            } catch {
-              git = "";
-            }
-            const hint =
-              task.kind === "success"
-                ? `\n\nSession rituals: type /trellis-start (start), /trellis-continue (resume), /trellis-finish-work (skill wrap-up).`
-                : "";
-            return { kind: task.kind, text: `${task.text}${git}${hint}` };
-          }),
-        ),
-    }),
-  );
-
-  disposers.push(
-    ctx.commands.register({
-      name: "trellis-finish",
-      description:
-        "Inspect the active task and print the safe wrap-up checklist.",
-      recordInput: false,
-      handler: (invocation) =>
-        withoutInput(invocation, () =>
-          withProject(invocation, async (root, sessionId, signal) => {
-            const result = await runTrellisScript(
-              resolved,
-              root,
-              sessionId,
-              ["current", "--source"],
-              { execFile: execute, platform, signal },
-            );
-            if (signal?.aborted) return result;
-            const checklist =
-              'Wrap-up checklist (this command did not clear or archive anything):\n  1. Commit this task\'s changes (workflow.md Phase 3.4; do not push).\n  2. Type /trellis-finish-work so the skill can archive the task before the pointer is removed and then record the session journal.\n\nIf you must do it manually, archive first with the configured Python 3 runtime: .trellis/scripts/task.py archive <task-name>; then run .trellis/scripts/add_session.py --title "..." --commit <hash> --summary "...".';
-            return { kind: result.kind, text: `${result.text}\n\n${checklist}` };
-          }),
-        ),
-    }),
-  );
-
-  return () => {
-    for (const dispose of disposers) dispose();
-  };
-}
+/**
+ * Human-facing /trellis commands: status and finish.
+ *
+ * Command names follow the dsh grammar (lowercase letters, digits, `_`, `-`;
+ * no `:`), and deliberately avoid the skill names (`trellis-start`,
+ * `trellis-continue`, `trellis-finish-work`): a command sharing a skill name
+ * would shadow the skill's slash-pipeline injection. The Trellis session
+ * rituals stay on the skill surface; these commands cover the deterministic,
+ * zero-token side — pointer inspection and wrap-up.
+ *
+ * @module dsh-trellis/commands
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { findProjectRoot } from "./workflow.js";
+import { nodeFs } from "./node-fs.js";
+import { dshContextKey } from "./session-env.js";
+import { resolveWorkingDirectory } from "./working-directory.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Platform-aware Python launch candidates. An explicit config disables fallback. */
+export function pythonCandidates(config, platform = process.platform) {
+  if (config.pythonCmd) return [{ command: config.pythonCmd, prefixArgs: [] }];
+  if (platform === "win32") {
+    return [
+      { command: "py", prefixArgs: ["-3"] },
+      { command: "python", prefixArgs: [] },
+    ];
+  }
+  return [
+    { command: "python3", prefixArgs: [] },
+    { command: "python", prefixArgs: [] },
+  ];
+}
+
+/** Run a project Trellis script with bounded time and output. */
+export async function runTrellisScript(
+  config,
+  root,
+  sessionId,
+  scriptArgs,
+  dependencies = {},
+) {
+  const execute = dependencies.execFile ?? execFileAsync;
+  const platform = dependencies.platform ?? process.platform;
+  const signal = dependencies.signal;
+  const contextKey = dshContextKey(sessionId);
+  const env = {
+    ...process.env,
+    ...(contextKey
+      ? {
+          TRELLIS_CONTEXT_ID: contextKey,
+          DSH_TRELLIS_CONTEXT_ID: contextKey,
+          DSH_SHELL: "1",
+          DSH_SESSION_ID: sessionId,
+        }
+      : {}),
+  };
+  const script = join(root, ".trellis", "scripts", "task.py");
+  const candidates = pythonCandidates(config, platform);
+  for (const [index, candidate] of candidates.entries()) {
+    const args = [...candidate.prefixArgs, script, ...scriptArgs];
+    try {
+      const { stdout, stderr } = await execute(candidate.command, args, {
+        cwd: root,
+        env,
+        windowsHide: true,
+        timeout: 15_000,
+        maxBuffer: 256 * 1024,
+        ...(signal ? { signal } : {}),
+      });
+      const text = `${stdout}${stderr ? `\n${stderr}` : ""}`.trim();
+      return { kind: "success", text };
+    } catch (error) {
+      if (signal?.aborted || error?.name === "AbortError") {
+        return { kind: "error", text: "Trellis command cancelled." };
+      }
+      const missing = error?.code === "ENOENT";
+      if (missing && index < candidates.length - 1) continue;
+      const attempted = candidates
+        .slice(0, index + 1)
+        .map(({ command, prefixArgs }) => [command, ...prefixArgs].join(" "))
+        .join(", ");
+      const message = missing
+        ? `Python command not found (tried: ${attempted}). Set the plugin's pythonCmd config to a Python 3 executable.`
+        : `Trellis script failed via ${[candidate.command, ...candidate.prefixArgs].join(" ")}: ${error?.message ?? String(error)}`;
+      return { kind: "error", text: message };
+    }
+  }
+  return {
+    kind: "error",
+    text: "No Python command candidates are configured.",
+  };
+}
+
+/**
+ * Register the /trellis command family.
+ * @param {object} ctx - cordis context exposing `ctx.commands`.
+ * @param {object} resolved - normalized plugin config.
+ * @returns {() => void} disposer.
+ */
+export function registerCommands(ctx, resolved, dependencies = {}) {
+  const fs = dependencies.fs ?? nodeFs;
+  const execute = dependencies.execFile ?? execFileAsync;
+  const platform = dependencies.platform ?? process.platform;
+  const disposers = [];
+
+  const withoutInput = (invocation, fn) => {
+    const rawInput = invocation.rawInput ?? "";
+    const attachments = invocation.attachments ?? [];
+    if (rawInput.trim() !== "" || attachments.length > 0) {
+      return {
+        kind: "error",
+        text: "This Trellis command does not accept arguments or image attachments.",
+      };
+    }
+    return fn();
+  };
+
+  const withProject = async (invocation, fn) => {
+    let cwd;
+    try {
+      cwd = await resolveWorkingDirectory(ctx, invocation.agent, invocation.signal);
+    } catch (error) {
+      return {
+        kind: "error",
+        text: invocation.signal?.aborted
+          ? "Trellis command cancelled."
+          : `Cannot resolve the current DSH working directory: ${error?.message ?? String(error)}`,
+      };
+    }
+    const root = await findProjectRoot(cwd, resolved.projectRootMarkers, fs);
+    if (root === null) {
+      return {
+        kind: "error",
+        text: "No project root found from the configured markers.",
+      };
+    }
+    const workflow = join(root, ".trellis", "workflow.md");
+    const taskScript = join(root, ".trellis", "scripts", "task.py");
+    if (!(await fs.exists(workflow)) || !(await fs.exists(taskScript))) {
+      return {
+        kind: "error",
+        text: "No Trellis project found (expected .trellis/workflow.md and .trellis/scripts/task.py).",
+      };
+    }
+    const sessionId = invocation.agent?.session?.header?.id ?? "";
+    return fn(root, sessionId, invocation.signal);
+  };
+
+  disposers.push(
+    ctx.commands.register({
+      name: "trellis-status",
+      description: "Show the Trellis active task and git status.",
+      // DSH rc.8 records command lifecycle events. These commands have no
+      // payload of their own, so omit empty/invalid input from the durable log.
+      recordInput: false,
+      handler: (invocation) =>
+        withoutInput(invocation, () =>
+          withProject(invocation, async (root, sessionId, signal) => {
+            const task = await runTrellisScript(
+              resolved,
+              root,
+              sessionId,
+              ["current", "--source"],
+              { execFile: execute, platform, signal },
+            );
+            if (signal?.aborted) return task;
+            let git = "";
+            try {
+              const { stdout } = await execute(
+                "git",
+                ["status", "--short", "--branch"],
+                {
+                  cwd: root,
+                  windowsHide: true,
+                  timeout: 10_000,
+                  maxBuffer: 128 * 1024,
+                  ...(signal ? { signal } : {}),
+                },
+              );
+              git = `\n\nGit status:\n${stdout.trim()}`;
+            } catch {
+              git = "";
+            }
+            const hint =
+              task.kind === "success"
+                ? `\n\nSession rituals: type /trellis-start (start), /trellis-continue (resume), /trellis-finish-work (skill wrap-up).`
+                : "";
+            return { kind: task.kind, text: `${task.text}${git}${hint}` };
+          }),
+        ),
+    }),
+  );
+
+  disposers.push(
+    ctx.commands.register({
+      name: "trellis-finish",
+      description:
+        "Inspect the active task and print the safe wrap-up checklist.",
+      recordInput: false,
+      handler: (invocation) =>
+        withoutInput(invocation, () =>
+          withProject(invocation, async (root, sessionId, signal) => {
+            const result = await runTrellisScript(
+              resolved,
+              root,
+              sessionId,
+              ["current", "--source"],
+              { execFile: execute, platform, signal },
+            );
+            if (signal?.aborted) return result;
+            const checklist =
+              'Wrap-up checklist (this command did not clear or archive anything):\n  1. Commit this task\'s changes (workflow.md Phase 3.4; do not push).\n  2. Type /trellis-finish-work so the skill can archive the task before the pointer is removed and then record the session journal.\n\nIf you must do it manually, archive first with the configured Python 3 runtime: .trellis/scripts/task.py archive <task-name>; then run .trellis/scripts/add_session.py --title "..." --commit <hash> --summary "...".';
+            return { kind: result.kind, text: `${result.text}\n\n${checklist}` };
+          }),
+        ),
+    }),
+  );
+
+  return () => {
+    for (const dispose of disposers) dispose();
+  };
+}

package/lib/config.js

@@ -1,56 +1,56 @@
-/**
- * dsh-trellis plugin configuration (Schemastery).
- *
- * @module dsh-trellis/config
- */
+/**
+ * dsh-trellis plugin configuration (Schemastery).
+ *
+ * @module dsh-trellis/config
+ */
 import z from "@deepseek-ai/schemastery";
 import * as settingsModule from "@deepseek-ai/dsh-settings";
 
 const fields = {
   /** Runtime master switch; the settings namespace remains available for re-enabling. */
-  enabled: z
-    .boolean()
-    .default(true)
-    .description(
-      "Enable Trellis breadcrumbs, commands, session facts, and the wait tool for this profile.",
-    ),
-  /** UTF-8 byte budget for the injected breadcrumb text. 0 disables injection. */
-  maxBytes: z
-    .number()
-    .step(1)
-    .min(0)
-    .default(4096)
-    .description(
-      "Maximum UTF-8 bytes in a workflow-state breadcrumb; 0 disables breadcrumbs.",
-    ),
-  /** Directory markers that identify a project root (walked upward from the session cwd). */
-  projectRootMarkers: z
-    .array(z.string())
-    .default([".git"])
-    .description(
-      "Directory entries used while walking upward to find the project root.",
-    ),
-  /** Standalone word (case-insensitive) in the user prompt that skips breadcrumb injection for that turn. Empty disables. */
-  skipKeyword: z
-    .string()
-    .default("no-trellis")
-    .description(
-      "Standalone prompt keyword that skips one breadcrumb injection; empty disables the escape hatch.",
-    ),
-  /** Python executable used by /trellis commands. Empty selects a platform-aware fallback chain. */
-  pythonCmd: z
-    .string()
-    .default("")
-    .description(
-      "Python 3 executable for Trellis scripts; empty selects a platform-aware launcher chain.",
-    ),
-  /** Register the deterministic /trellis-status and read-only /trellis-finish commands. */
-  commandsEnabled: z
-    .boolean()
-    .default(true)
-    .description(
-      "Register /trellis-status and the read-only /trellis-finish helper.",
-    ),
+  enabled: z
+    .boolean()
+    .default(true)
+    .description(
+      "Enable Trellis breadcrumbs, commands, session facts, and the wait tool for this profile.",
+    ),
+  /** UTF-8 byte budget for the injected breadcrumb text. 0 disables injection. */
+  maxBytes: z
+    .number()
+    .step(1)
+    .min(0)
+    .default(4096)
+    .description(
+      "Maximum UTF-8 bytes in a workflow-state breadcrumb; 0 disables breadcrumbs.",
+    ),
+  /** Directory markers that identify a project root (walked upward from the session cwd). */
+  projectRootMarkers: z
+    .array(z.string())
+    .default([".git"])
+    .description(
+      "Directory entries used while walking upward to find the project root.",
+    ),
+  /** Standalone word (case-insensitive) in the user prompt that skips breadcrumb injection for that turn. Empty disables. */
+  skipKeyword: z
+    .string()
+    .default("no-trellis")
+    .description(
+      "Standalone prompt keyword that skips one breadcrumb injection; empty disables the escape hatch.",
+    ),
+  /** Python executable used by /trellis commands. Empty selects a platform-aware fallback chain. */
+  pythonCmd: z
+    .string()
+    .default("")
+    .description(
+      "Python 3 executable for Trellis scripts; empty selects a platform-aware launcher chain.",
+    ),
+  /** Register the deterministic /trellis-status and read-only /trellis-finish commands. */
+  commandsEnabled: z
+    .boolean()
+    .default(true)
+    .description(
+      "Register /trellis-status and the read-only /trellis-finish helper.",
+    ),
 };
 
 // Legacy Settings validates plain values; profile-backed Settings exposes only
@@ -67,31 +67,31 @@ export function hasLiveConfig(config) {
     Symbol.for("cosmokit.volatile.write") in value,
   );
 }
-
-/**
- * Normalized runtime configuration.
- * @param {Partial<Record<string, unknown>>} config
- * @returns {{
- *   enabled: boolean,
- *   maxBytes: number,
- *   projectRootMarkers: string[],
- *   skipKeyword: string,
- *   pythonCmd: string,
- *   commandsEnabled: boolean,
- * }}
- */
+
+/**
+ * Normalized runtime configuration.
+ * @param {Partial<Record<string, unknown>>} config
+ * @returns {{
+ *   enabled: boolean,
+ *   maxBytes: number,
+ *   projectRootMarkers: string[],
+ *   skipKeyword: string,
+ *   pythonCmd: string,
+ *   commandsEnabled: boolean,
+ * }}
+ */
 export function resolveConfig(config) {
   config = Object.fromEntries(Object.entries(config).map(([key, value]) => [key,
     value !== null && typeof value === "object" &&
     Symbol.for("cosmokit.volatile.write") in value ? value.get() : value,
   ]));
-  return {
-    enabled: config.enabled !== false,
-    maxBytes: config.maxBytes ?? 4096,
-    projectRootMarkers: config.projectRootMarkers ?? [".git"],
-    skipKeyword: config.skipKeyword ?? "no-trellis",
-    pythonCmd:
-      typeof config.pythonCmd === "string" ? config.pythonCmd.trim() : "",
-    commandsEnabled: config.commandsEnabled !== false,
-  };
-}
+  return {
+    enabled: config.enabled !== false,
+    maxBytes: config.maxBytes ?? 4096,
+    projectRootMarkers: config.projectRootMarkers ?? [".git"],
+    skipKeyword: config.skipKeyword ?? "no-trellis",
+    pythonCmd:
+      typeof config.pythonCmd === "string" ? config.pythonCmd.trim() : "",
+    commandsEnabled: config.commandsEnabled !== false,
+  };
+}

package/lib/index.js

@@ -1,24 +1,24 @@
-/**
- * dsh-trellis: Trellis workflow integration for DeepSeek Harness.
- *
- * - Per-turn workflow-state breadcrumb: at every eligible `agent/pre-step`,
- *   resolves the project's Trellis state (.trellis/workflow.md blocks +
- *   active task) and injects the matching [workflow-state:*] body into the
- *   session, exactly where the workspace-instruction baseline lands.
- * - `/trellis-status` and read-only `/trellis-finish` utility commands.
- *   Session rituals remain skills (`/trellis-start`, `/trellis-continue`,
- *   `/trellis-finish-work`) so command registration cannot shadow them.
- * - `trellis_wait`, an event-driven synchronization tool for a continuable
- *   role agent after the main session has exhausted independent work.
- * - A managed DSH_TRELLIS_CONTEXT_ID derived per shell execution from the
- *   native DSH session, so an outer host's inherited TRELLIS_CONTEXT_ID cannot
- *   silently claim the inner session. Utility commands set the same identity.
- *
- * In directories without a Trellis project it injects no breadcrumb; utility
- * commands validate the project only when a user explicitly invokes them.
- *
- * @module dsh-trellis
- */
+/**
+ * dsh-trellis: Trellis workflow integration for DeepSeek Harness.
+ *
+ * - Per-turn workflow-state breadcrumb: at every eligible `agent/pre-step`,
+ *   resolves the project's Trellis state (.trellis/workflow.md blocks +
+ *   active task) and injects the matching [workflow-state:*] body into the
+ *   session, exactly where the workspace-instruction baseline lands.
+ * - `/trellis-status` and read-only `/trellis-finish` utility commands.
+ *   Session rituals remain skills (`/trellis-start`, `/trellis-continue`,
+ *   `/trellis-finish-work`) so command registration cannot shadow them.
+ * - `trellis_wait`, an event-driven synchronization tool for a continuable
+ *   role agent after the main session has exhausted independent work.
+ * - A managed DSH_TRELLIS_CONTEXT_ID derived per shell execution from the
+ *   native DSH session, so an outer host's inherited TRELLIS_CONTEXT_ID cannot
+ *   silently claim the inner session. Utility commands set the same identity.
+ *
+ * In directories without a Trellis project it injects no breadcrumb; utility
+ * commands validate the project only when a user explicitly invokes them.
+ *
+ * @module dsh-trellis
+ */
 import { isDeepStrictEqual } from "node:util";
 import * as settingsModule from "@deepseek-ai/dsh-settings";
 import { Config, hasLiveConfig, resolveConfig } from "./config.js";
@@ -34,55 +34,55 @@ import { registerWaitTool } from "./wait-tool.js";
 
 export const name = "dsh-trellis";
 export const SETTINGS_NAMESPACE = "dsh-trellis";
-
-/** @type {string[]} */
+
+/** @type {string[]} */
 export const inject = ["commands", "shellEnv", "subagents", "tools", "sessionProjections"];
-
-export { Config };
-
-function stopAll(disposers) {
-  for (const dispose of disposers.toReversed()) dispose();
-}
-
-function sameBreadcrumbPayload(left, right) {
-  return (
-    isDeepStrictEqual(left.content, right.content) &&
-    isDeepStrictEqual(left.source, right.source)
-  );
-}
-
-/** @param {import("@deepseek-ai/cordis").Context} ctx */
+
+export { Config };
+
+function stopAll(disposers) {
+  for (const dispose of disposers.toReversed()) dispose();
+}
+
+function sameBreadcrumbPayload(left, right) {
+  return (
+    isDeepStrictEqual(left.content, right.content) &&
+    isDeepStrictEqual(left.source, right.source)
+  );
+}
+
+/** @param {import("@deepseek-ai/cordis").Context} ctx */
 export function apply(ctx, config = {}) {
   let stopped = false;
   let disposeRuntime = () => {};
   let currentConfig = () => config;
   let mountedConfig;
-
-  const mountRuntime = (nextConfig) => {
-    if (stopped) return;
-    disposeRuntime();
+
+  const mountRuntime = (nextConfig) => {
+    if (stopped) return;
+    disposeRuntime();
     const resolved = resolveConfig(nextConfig);
     mountedConfig = resolved;
-    if (!resolved.enabled) {
-      disposeRuntime = () => {};
-      return;
-    }
-
-    const disposers = [];
-    try {
-      if (resolved.commandsEnabled) {
-        disposers.push(registerCommands(ctx, resolved));
-      }
-      disposers.push(registerWaitTool(ctx));
-      disposers.push(registerSessionEnv(ctx));
-      disposers.push(registerBreadcrumb(ctx, resolved));
-    } catch (error) {
-      stopAll(disposers);
-      throw error;
-    }
-    disposeRuntime = () => stopAll(disposers);
-  };
-
+    if (!resolved.enabled) {
+      disposeRuntime = () => {};
+      return;
+    }
+
+    const disposers = [];
+    try {
+      if (resolved.commandsEnabled) {
+        disposers.push(registerCommands(ctx, resolved));
+      }
+      disposers.push(registerWaitTool(ctx));
+      disposers.push(registerSessionEnv(ctx));
+      disposers.push(registerBreadcrumb(ctx, resolved));
+    } catch (error) {
+      stopAll(disposers);
+      throw error;
+    }
+    disposeRuntime = () => stopAll(disposers);
+  };
+
   // Keep the composition entry working when no settings provider is mounted.
   // Once the service appears, its resolved section becomes the live source and
   // a saved Web card edit remounts only this plugin's runtime.
@@ -91,7 +91,7 @@ export function apply(ctx, config = {}) {
     return () => {
       stopped = true;
       disposeRuntime();
-    };
+    };
   }, "dsh-trellis.runtime");
 
   if (hasLiveConfig(config)) {
@@ -101,7 +101,7 @@ export function apply(ctx, config = {}) {
       if (!isDeepStrictEqual(resolveConfig(config), mountedConfig)) mountRuntime(config);
     });
   }
-
+
   // Optional by design: profiles without a settings service retain the
   // loader-config behavior. The canonical bridge also distinguishes a settings
   // provider reload (fall back to config) from this plugin's own teardown
@@ -140,7 +140,7 @@ export function insertBreadcrumbDecision(decision, claimedMessages, desired) {
     messages: decision.messages.toSpliced(lastClaimedIndex + 1, 0, desired),
   };
 }
-
+
 function registerBreadcrumb(ctx, resolved) {
   const { compose } = createBreadcrumbComposer(resolved, ctx);
   const projection = registerBreadcrumbProjection(ctx);
@@ -153,21 +153,21 @@ function registerBreadcrumb(ctx, resolved) {
 
   const syncInbox = (agent, desired) => {
     pendingInboxes.add(agent.inbox);
-    const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
-    const reusable = pending.find((message) =>
-      sameBreadcrumbPayload(message, desired),
-    );
-    if (reusable !== undefined) {
-      for (const message of pending)
-        if (message !== reusable) agent.inbox.remove(message.id);
-      return;
-    }
-    const replaced = pending[0];
-    if (replaced === undefined) agent.inbox.prepend("next-step", desired);
-    else agent.inbox.replace(replaced.id, desired);
-    for (const message of pending.slice(1)) agent.inbox.remove(message.id);
-  };
-
+    const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
+    const reusable = pending.find((message) =>
+      sameBreadcrumbPayload(message, desired),
+    );
+    if (reusable !== undefined) {
+      for (const message of pending)
+        if (message !== reusable) agent.inbox.remove(message.id);
+      return;
+    }
+    const replaced = pending[0];
+    if (replaced === undefined) agent.inbox.prepend("next-step", desired);
+    else agent.inbox.replace(replaced.id, desired);
+    for (const message of pending.slice(1)) agent.inbox.remove(message.id);
+  };
+
   let disposeStep;
   try {
     disposeStep = ctx.on("agent/pre-step", async ({ agent, messages, step, signal }, next) => {

package/lib/wait-tool.js

@@ -1,103 +1,103 @@
-/**
- * Event-driven waiting for DeepSeek Harness continuable subagents.
- *
- * Trellis dispatches role agents in DSH's default background mode so the main
- * agent can keep doing independent work. When that work is exhausted, this
- * tool provides a native synchronization point: it waits for `subagent/end`,
- * which proves execution settlement, not delivery of a parent notice (alpha.2
- * delivery is best effort and caller-owned activations may omit it entirely).
- * It deliberately replaces shell sleeps and polling loops.
- *
- * @module dsh-trellis/wait-tool
- */
-import { defineTool } from "@deepseek-ai/dsh-tools";
-
-function createSettlementWaiter(parentCtx, subagentId, signal) {
-  let disposeListener = () => {};
-  let settled = false;
-  let resolvePromise;
+/**
+ * Event-driven waiting for DeepSeek Harness continuable subagents.
+ *
+ * Trellis dispatches role agents in DSH's default background mode so the main
+ * agent can keep doing independent work. When that work is exhausted, this
+ * tool provides a native synchronization point: it waits for `subagent/end`,
+ * which proves execution settlement, not delivery of a parent notice (alpha.2
+ * delivery is best effort and caller-owned activations may omit it entirely).
+ * It deliberately replaces shell sleeps and polling loops.
+ *
+ * @module dsh-trellis/wait-tool
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+function createSettlementWaiter(parentCtx, subagentId, signal) {
+  let disposeListener = () => {};
+  let settled = false;
+  let resolvePromise;
   let rejectPromise;
   let terminal;
-
-  const cleanup = () => {
-    disposeListener?.();
-    signal?.removeEventListener("abort", onAbort);
-  };
-  const onAbort = () => {
-    if (settled) return;
-    settled = true;
-    cleanup();
-    rejectPromise(signal.reason ?? new Error("Trellis subagent wait cancelled."));
-  };
+
+  const cleanup = () => {
+    disposeListener?.();
+    signal?.removeEventListener("abort", onAbort);
+  };
+  const onAbort = () => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    rejectPromise(signal.reason ?? new Error("Trellis subagent wait cancelled."));
+  };
   const promise = new Promise((resolve, reject) => {
-    resolvePromise = resolve;
-    rejectPromise = reject;
+    resolvePromise = resolve;
+    rejectPromise = reject;
   });
   // Cancellation can precede completion of the catalog lookup below. Observe
   // the rejection immediately; the execute path still awaits the original.
   void promise.catch(() => {});
-
-  disposeListener =
-    parentCtx.on("subagent/end", (info) => {
-      if (settled || info.id !== subagentId) return;
-      settled = true;
-      cleanup();
+
+  disposeListener =
+    parentCtx.on("subagent/end", (info) => {
+      if (settled || info.id !== subagentId) return;
+      settled = true;
+      cleanup();
       resolvePromise(info);
       terminal = info;
-    }) ?? (() => {});
-  signal?.addEventListener("abort", onAbort, { once: true });
-  if (signal?.aborted) onAbort();
-
-  return {
+    }) ?? (() => {});
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+
+  return {
     promise,
     result: () => terminal,
-    cancel() {
-      if (settled) return;
-      settled = true;
-      cleanup();
-    },
-  };
-}
-
-/** Map a DSH stop reason to a gate-safe Trellis outcome. */
-export function settlementOutcome(stopReason) {
-  if (stopReason === "completed") return "completed";
-  if (stopReason === "aborted") return "aborted";
-  if (stopReason === "unknown") return "unknown";
-  return "failed";
-}
-
-function settledResult(subagentId, info) {
-  const stopReason =
-    typeof info?.stopReason === "string" ? info.stopReason : "unknown";
-  return {
-    subagentId,
-    state: "settled",
-    outcome: settlementOutcome(stopReason),
-    stopReason,
-    runId: typeof info?.runId === "string" ? info.runId : "",
-    provider: typeof info?.provider === "string" ? info.provider : "",
-    assistantOutputBlocks: Array.isArray(info?.lastAssistantMessage)
-      ? info.lastAssistantMessage.length
-      : 0,
-    // Compatibility field: false means unverified, not proven non-delivery.
-    settlementNoticeQueued: false,
-  };
-}
-
-function inactiveResult(subagentId) {
-  return {
-    subagentId,
-    state: "already-inactive",
-    outcome: "unknown",
-    stopReason: "unknown",
-    runId: "",
-    provider: "",
-    assistantOutputBlocks: 0,
-    settlementNoticeQueued: false,
-  };
-}
-
+    cancel() {
+      if (settled) return;
+      settled = true;
+      cleanup();
+    },
+  };
+}
+
+/** Map a DSH stop reason to a gate-safe Trellis outcome. */
+export function settlementOutcome(stopReason) {
+  if (stopReason === "completed") return "completed";
+  if (stopReason === "aborted") return "aborted";
+  if (stopReason === "unknown") return "unknown";
+  return "failed";
+}
+
+function settledResult(subagentId, info) {
+  const stopReason =
+    typeof info?.stopReason === "string" ? info.stopReason : "unknown";
+  return {
+    subagentId,
+    state: "settled",
+    outcome: settlementOutcome(stopReason),
+    stopReason,
+    runId: typeof info?.runId === "string" ? info.runId : "",
+    provider: typeof info?.provider === "string" ? info.provider : "",
+    assistantOutputBlocks: Array.isArray(info?.lastAssistantMessage)
+      ? info.lastAssistantMessage.length
+      : 0,
+    // Compatibility field: false means unverified, not proven non-delivery.
+    settlementNoticeQueued: false,
+  };
+}
+
+function inactiveResult(subagentId) {
+  return {
+    subagentId,
+    state: "already-inactive",
+    outcome: "unknown",
+    stopReason: "unknown",
+    runId: "",
+    provider: "",
+    assistantOutputBlocks: 0,
+    settlementNoticeQueued: false,
+  };
+}
+
 /** Catalogs prove ownership, not residency or successful completion. */
 function childActivity(ctx, parent, child) {
   if (child.kind === "child") {
@@ -122,111 +122,111 @@ function childActivity(ctx, parent, child) {
 export function registerWaitTool(ctx) {
   const lifetime = new AbortController();
   const unregister = ctx.tools.register(
-    defineTool({
-      name: "trellis_wait",
-      description:
-        "Wait efficiently for one direct background Trellis subagent after independent work is exhausted. This is an event-driven synchronization barrier over DSH's native settlement lifecycle. Use the subagent id returned by `subagent`; never replace this with shell sleep, polling, or job_output. On DSH rc.8+, an idle parent can instead yield and be woken by the native settlement notice.",
-      parameters: {
-        subagent_id: {
-          type: "string",
-          required: true,
-          description:
-            "Direct continuable subagent id returned by the `subagent` tool.",
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            subagentId: { type: "string", required: true },
-            state: { type: "string", required: true },
-            outcome: { type: "string", required: true },
-            stopReason: { type: "string", required: true },
-            runId: { type: "string", required: true },
-            provider: { type: "string", required: true },
-            assistantOutputBlocks: { type: "number", required: true },
-            settlementNoticeQueued: {
-              type: "boolean", required: true,
-              description: "Compatibility field: false means notice delivery is unverified, not proven absent.",
-            },
-          },
-        },
-        render(_args, value) {
-          if (value.state === "already-inactive") {
-            return [
-              {
-                type: "text",
-                text: `subagent ${value.subagentId} is already inactive; no stop reason can be proven from the catalog snapshot, so inspect its transcript or an already-visible settlement notice before passing a gate`,
-              },
-            ];
-          }
-          if (value.outcome !== "completed") {
-            return [
-              {
-                type: "text",
-                text: `subagent ${value.subagentId} settled with ${value.outcome} (${value.stopReason}); do not treat this gate as passed; settlement notice delivery is unverified`,
-              },
-            ];
-          }
-          return [
-            {
-              type: "text",
-              text: `subagent ${value.subagentId} completed; settlement notice delivery is unverified; inspect its report or transcript before passing a dependent gate`,
-            },
-          ];
-        },
-      },
+    defineTool({
+      name: "trellis_wait",
+      description:
+        "Wait efficiently for one direct background Trellis subagent after independent work is exhausted. This is an event-driven synchronization barrier over DSH's native settlement lifecycle. Use the subagent id returned by `subagent`; never replace this with shell sleep, polling, or job_output. On DSH rc.8+, an idle parent can instead yield and be woken by the native settlement notice.",
+      parameters: {
+        subagent_id: {
+          type: "string",
+          required: true,
+          description:
+            "Direct continuable subagent id returned by the `subagent` tool.",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            subagentId: { type: "string", required: true },
+            state: { type: "string", required: true },
+            outcome: { type: "string", required: true },
+            stopReason: { type: "string", required: true },
+            runId: { type: "string", required: true },
+            provider: { type: "string", required: true },
+            assistantOutputBlocks: { type: "number", required: true },
+            settlementNoticeQueued: {
+              type: "boolean", required: true,
+              description: "Compatibility field: false means notice delivery is unverified, not proven absent.",
+            },
+          },
+        },
+        render(_args, value) {
+          if (value.state === "already-inactive") {
+            return [
+              {
+                type: "text",
+                text: `subagent ${value.subagentId} is already inactive; no stop reason can be proven from the catalog snapshot, so inspect its transcript or an already-visible settlement notice before passing a gate`,
+              },
+            ];
+          }
+          if (value.outcome !== "completed") {
+            return [
+              {
+                type: "text",
+                text: `subagent ${value.subagentId} settled with ${value.outcome} (${value.stopReason}); do not treat this gate as passed; settlement notice delivery is unverified`,
+              },
+            ];
+          }
+          return [
+            {
+              type: "text",
+              text: `subagent ${value.subagentId} completed; settlement notice delivery is unverified; inspect its report or transcript before passing a dependent gate`,
+            },
+          ];
+        },
+      },
       async execute(args, exec) {
         const signal = exec.signal
           ? AbortSignal.any([exec.signal, lifetime.signal])
           : lifetime.signal;
         signal.throwIfAborted();
         const parent = exec.agent;
-        if (!parent)
-          throw new Error(
-            "trellis_wait requires a calling agent (exec.agent was undefined)",
-          );
-
-        // Install the listener before reading the durable catalog so settlement
-        // cannot slip through the validation/read-to-wait window.
-        const waiter = createSettlementWaiter(
-          parent.ctx,
-          args.subagent_id,
+        if (!parent)
+          throw new Error(
+            "trellis_wait requires a calling agent (exec.agent was undefined)",
+          );
+
+        // Install the listener before reading the durable catalog so settlement
+        // cannot slip through the validation/read-to-wait window.
+        const waiter = createSettlementWaiter(
+          parent.ctx,
+          args.subagent_id,
           signal,
-        );
-        try {
-          const entries = await ctx.subagents.listChildren(
-            parent.id,
+        );
+        try {
+          const entries = await ctx.subagents.listChildren(
+            parent.id,
             signal,
           );
           signal.throwIfAborted();
-          const child = entries.find(
-            (entry) =>
+          const child = entries.find(
+            (entry) =>
               (entry.kind === "child" || entry.kind === undefined) &&
-              entry.mode === "continuable" &&
-              entry.id === args.subagent_id,
-          );
-          if (child === undefined) {
-            throw new Error(
-              `trellis_wait can only wait for a direct continuable subagent of this session: ${args.subagent_id}`,
-            );
-          }
+              entry.mode === "continuable" &&
+              entry.id === args.subagent_id,
+          );
+          if (child === undefined) {
+            throw new Error(
+              `trellis_wait can only wait for a direct continuable subagent of this session: ${args.subagent_id}`,
+            );
+          }
           // Preserve a proven event captured during the asynchronous lookup.
           if (waiter.result()) return settledResult(args.subagent_id, waiter.result());
           if (childActivity(ctx, parent, child) === "inactive") {
-            waiter.cancel();
-            return inactiveResult(args.subagent_id);
-          }
-
-          const info = await waiter.promise;
-          return settledResult(args.subagent_id, info);
-        } catch (error) {
-          waiter.cancel();
-          throw error;
-        }
-      },
-    }),
+            waiter.cancel();
+            return inactiveResult(args.subagent_id);
+          }
+
+          const info = await waiter.promise;
+          return settledResult(args.subagent_id, info);
+        } catch (error) {
+          waiter.cancel();
+          throw error;
+        }
+      },
+    }),
   );
   return () => {
     if (lifetime.signal.aborted) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-trellis",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Trellis workflow integration for DeepSeek Harness: per-turn workflow-state breadcrumbs, utility commands, and native session identity.",
   "type": "module",
   "main": "lib/index.js",