dsh-trellis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SajoLuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# 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`，只在原生 settlement notice 已排入父会话后返回，不用 shell sleep、轮询或 `job_output`。
+4. **`/trellis` 命令** — `/trellis-status`（活跃任务 + git 状态）、`/trellis-finish`（只读检查 + 安全收尾清单，不提前清 active-task 指针）。命令输出不进模型历史；真正的会话收尾走技能面 `/trellis-finish-work`，由技能先归档再写 journal。
+
+非 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
+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` 的适配（已含在同一分支）。插件目标版本为 DSH `0.1.0-rc.6`；升级 DSH 时应重跑本仓测试。
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里覆盖（整行替换）：
+
+```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 启动器，等待工具也会立即注销临时事件监听器。插件卸载时只注销自己的命令、工具和监听器。
+- **子代理并发**：workflow 只有在发现 `trellis_wait` 时才使用 DSH 原生 continuable 后台 `subagent`。主会话并行做独立工作；需要汇合时调用一次 `trellis_wait <subagent_id>` 等待原生结算事件。没有该工具时，首次派发直接设置 `run_in_background: false`，绝不留下无法事件汇合的后台子代理。
+
+## 开发
+
+```powershell
+pnpm install
+pnpm test    # node --test test/*.test.js
+```
+
+无构建步骤：纯 ESM JavaScript，`main` 直接指向 `lib/index.js`。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +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.
+- insert:
+    - id: dsh-trellis
+      name: dsh-trellis

package/lib/breadcrumb.js

@@ -0,0 +1,143 @@
+/**
+ * Per-turn workflow-state breadcrumb: composition, dedupe, and visibility.
+ *
+ * @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";
+
+export const SOURCE_KIND = "dsh-trellis";
+export const SOURCE_FORM = "breadcrumb";
+
+/**
+ * Truncate UTF-8 text to a byte budget without splitting a code point.
+ * @param {string} value
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+export function truncateUtf8(value, maxBytes) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length <= maxBytes) return value;
+  let end = Math.max(0, Math.trunc(maxBytes));
+  while (end > 0 && (bytes.readUInt8(end) & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString("utf8");
+}
+
+/**
+ * Compose the model-visible breadcrumb message for a resolved state.
+ * @param {{status: string, taskPath: string | null, body: string, digest: string}} state
+ * @param {number} maxBytes
+ * @returns {ReturnType<typeof createUserMessage>}
+ */
+export function breadcrumbMessage(state, maxBytes) {
+  const taskLine =
+    state.taskPath === null ? "" : `\nActive task: ${state.taskPath}`;
+  const text = truncateUtf8(
+    `<system-reminder>\nTrellis workflow state: ${state.status}${taskLine}\n\n${state.body}\n</system-reminder>`,
+    maxBytes,
+  );
+  return createUserMessage({
+    content: [{ type: "text", text }],
+    source: {
+      kind: SOURCE_KIND,
+      form: SOURCE_FORM,
+      status: state.status,
+      task: state.taskPath,
+      digest: state.digest,
+    },
+  });
+}
+
+/** Whether a user message carries our breadcrumb source. */
+export function isBreadcrumbMessage(message) {
+  const source = message?.source;
+  return (
+    typeof source === "object" &&
+    source !== null &&
+    source.kind === SOURCE_KIND &&
+    source.form === SOURCE_FORM
+  );
+}
+
+/** Whether the same breadcrumb payload is already visible in the session surface. */
+export function isBreadcrumbVisible(agent, digest) {
+  const visibleSeqs = new Set(agent.session.surface.nodes);
+  for (const [seq, event] of agent.session.events.entries()) {
+    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
+ * @param {string} keyword
+ */
+export function hasSkipKeyword(messages, keyword) {
+  if (!keyword) return false;
+  const pattern = new RegExp(
+    `\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`,
+    "i",
+  );
+  for (const message of messages) {
+    const content = message?.content;
+    const parts = Array.isArray(content)
+      ? content
+      : [{ type: "text", text: String(content ?? "") }];
+    for (const part of parts) {
+      if (typeof part?.text === "string" && pattern.test(part.text))
+        return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Build the plugin-owned pre-step composer.
+ * @param {object} resolved - normalized plugin config.
+ * @param {import("@deepseek-ai/cordis").Context} ctx
+ * @returns {{ compose(agent: any, messages: any[], signal: AbortSignal): Promise<any> }}
+ */
+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))
+      return undefined;
+    if (hasSkipKeyword(messages, resolved.skipKeyword)) return undefined;
+    const cwd = agent.session.header.cwd ?? process.cwd();
+    const sessionId = agent.session.header.id ?? "";
+    const contextKey =
+      sessionId === "" ? "dsh" : `dsh_${sanitizeContextKey(sessionId)}`;
+    signal?.throwIfAborted();
+    const state = await resolveTrellisState({
+      cwd,
+      markers: resolved.projectRootMarkers,
+      contextKey,
+      fs,
+      cache,
+    });
+    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);
+  };
+
+  return { compose };
+}

package/lib/commands.js

@@ -0,0 +1,195 @@
+/**
+ * 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";
+
+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 withProject = async (invocation, fn) => {
+    const cwd = invocation.agent?.session?.header?.cwd ?? process.cwd();
+    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.",
+      handler: (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.",
+      handler: (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

@@ -0,0 +1,45 @@
+/**
+ * dsh-trellis plugin configuration (Schemastery).
+ *
+ * @module dsh-trellis/config
+ */
+import z from "@deepseek-ai/schemastery";
+
+export const Config = z.object({
+  /** Master switch: when false, the plugin injects nothing and registers nothing. */
+  enabled: z.boolean().default(true),
+  /** UTF-8 byte budget for the injected breadcrumb text. 0 disables injection. */
+  maxBytes: z.number().step(1).min(0).default(4096),
+  /** Directory markers that identify a project root (walked upward from the session cwd). */
+  projectRootMarkers: z.array(z.string()).default([".git"]),
+  /** Standalone word (case-insensitive) in the user prompt that skips breadcrumb injection for that turn. Empty disables. */
+  skipKeyword: z.string().default("no-trellis"),
+  /** Python executable used by /trellis commands. Empty selects a platform-aware fallback chain. */
+  pythonCmd: z.string().default(""),
+  /** Register the deterministic /trellis-status and read-only /trellis-finish commands. */
+  commandsEnabled: z.boolean().default(true),
+});
+
+/**
+ * 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) {
+  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

@@ -0,0 +1,146 @@
+/**
+ * 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 { Config, resolveConfig } from "./config.js";
+import { createBreadcrumbComposer, isBreadcrumbMessage } from "./breadcrumb.js";
+import { registerCommands } from "./commands.js";
+import { registerSessionEnv } from "./session-env.js";
+import { registerWaitTool } from "./wait-tool.js";
+
+export const name = "dsh-trellis";
+
+/** @type {string[]} */
+export const inject = ["commands", "shellEnv", "subagents", "tools"];
+
+export { Config };
+
+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 = {}) {
+  const resolved = resolveConfig(config);
+  if (!resolved.enabled) return;
+
+  // --- /trellis commands ---------------------------------------------------
+  let disposeCommands = () => {};
+  ctx.effect(() => {
+    if (resolved.commandsEnabled) {
+      disposeCommands = registerCommands(ctx, resolved);
+    }
+    return () => disposeCommands();
+  }, "dsh-trellis.commands");
+
+  // --- native continuable-subagent synchronization -----------------------
+  ctx.effect(
+    () => registerWaitTool(ctx),
+    "dsh-trellis.wait-tool",
+  );
+
+  // --- session-scoped shell identity --------------------------------------
+  ctx.effect(
+    () => registerSessionEnv(ctx),
+    "dsh-trellis.session-env",
+  );
+
+  // --- per-turn breadcrumb injection --------------------------------------
+  const { compose } = createBreadcrumbComposer(resolved, ctx);
+
+  const syncInbox = (agent, desired) => {
+    const pending = agent.inbox.nextStep.filter(isBreadcrumbMessage);
+    const alreadySupplied =
+      desired === undefined ||
+      agent.session.surface.nodes.some((seq) => {
+        const event = agent.session.events[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),
+    );
+    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);
+  };
+
+  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;
+    }
+    const lastClaimedIndex = decision.messages.findLastIndex((message) =>
+      messages.includes(message),
+    );
+    return {
+      kind: "enter",
+      messages: decision.messages.toSpliced(lastClaimedIndex + 1, 0, desired),
+    };
+  });
+}

package/lib/node-fs.js

@@ -0,0 +1,40 @@
+/**
+ * Node filesystem shim implementing the narrow surface workflow.js needs.
+ *
+ * @module dsh-trellis/node-fs
+ */
+import { stat as nodeStat, readFile as nodeReadFile, readdir as nodeReaddir } from "node:fs/promises";
+
+/** @type {import("./workflow.js").FsShim} */
+export const nodeFs = {
+  async exists(path) {
+    try {
+      await nodeStat(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async stat(path) {
+    try {
+      const info = await nodeStat(path);
+      return { mtimeMs: info.mtimeMs };
+    } catch {
+      return null;
+    }
+  },
+  async readFile(path) {
+    try {
+      return await nodeReadFile(path, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  async listDir(path) {
+    try {
+      return await nodeReaddir(path);
+    } catch {
+      return [];
+    }
+  },
+};

package/lib/session-env.js

@@ -0,0 +1,43 @@
+/**
+ * Session-scoped context identity for Trellis's Python scripts.
+ *
+ * DSH rebuilds the managed `DSH_*` namespace for every model shell execution,
+ * discarding ambient `DSH_*` values first. This contributor therefore carries
+ * the current DSH session identity without inheriting an outer host's Trellis
+ * context. The beta Trellis adapter resolves it before the generic
+ * `TRELLIS_CONTEXT_ID` subprocess override.
+ *
+ * @module dsh-trellis/session-env
+ */
+import { sanitizeContextKey } from "./workflow.js";
+
+export const SESSION_ENV_CONTRIBUTOR = "dsh-trellis-session";
+
+/** Return the Trellis context key for a native DSH session id. */
+export function dshContextKey(sessionId) {
+  const sanitized = sanitizeContextKey(sessionId ?? "");
+  return sanitized === "" ? "" : `dsh_${sanitized}`;
+}
+
+/**
+ * Register the trusted, per-execution shell identity contribution.
+ * @param {object} ctx - Cordis context exposing `ctx.shellEnv`.
+ * @returns {() => void} disposer.
+ */
+export function registerSessionEnv(ctx) {
+  return ctx.shellEnv.register({
+    name: SESSION_ENV_CONTRIBUTOR,
+    variables: {
+      DSH_TRELLIS_CONTEXT_ID: {
+        description:
+          "Current DSH session's Trellis context key; overrides an inherited outer TRELLIS_CONTEXT_ID.",
+      },
+    },
+    resolve(execution) {
+      const contextKey = dshContextKey(
+        execution.agent?.session?.header?.id ?? "",
+      );
+      return contextKey === "" ? {} : { DSH_TRELLIS_CONTEXT_ID: contextKey };
+    },
+  });
+}

package/lib/wait-tool.js

@@ -0,0 +1,149 @@
+/**
+ * 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 DSH emits only after the child's settlement notice has been queued for
+ * the parent. 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;
+
+  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;
+  });
+
+  disposeListener =
+    parentCtx.on("subagent/end", (info) => {
+      if (settled || info.id !== subagentId) return;
+      settled = true;
+      cleanup();
+      resolvePromise(info.stopReason);
+    }) ?? (() => {});
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+
+  return {
+    promise,
+    cancel() {
+      if (settled) return;
+      settled = true;
+      cleanup();
+    },
+  };
+}
+
+/** Register the Trellis-only, event-driven subagent wait tool. */
+export function registerWaitTool(ctx) {
+  return ctx.tools.register(
+    defineTool({
+      name: "trellis_wait",
+      description:
+        "Wait efficiently for one direct background Trellis subagent after independent work is exhausted. This is event-driven: it returns only after DeepSeek Harness has queued the child's native settlement notice. Use the subagent id returned by `subagent`; never replace this with shell sleep, polling, or job_output.",
+      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 },
+            stopReason: { type: "string", required: true },
+          },
+        },
+        render(_args, value) {
+          if (value.state === "already-inactive") {
+            return [
+              {
+                type: "text",
+                text: `subagent ${value.subagentId} is already inactive; consume its queued settlement notice or inspect its transcript`,
+              },
+            ];
+          }
+          return [
+            {
+              type: "text",
+              text: `subagent ${value.subagentId} settled (${value.stopReason}); its native settlement notice is queued`,
+            },
+          ];
+        },
+      },
+      async execute(args, exec) {
+        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,
+          exec.signal,
+        );
+        try {
+          const entries = await ctx.subagents.listChildren(
+            parent.id,
+            exec.signal,
+          );
+          const child = entries.find(
+            (entry) =>
+              entry.kind === "child" &&
+              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}`,
+            );
+          }
+          if (child.activity === "inactive") {
+            waiter.cancel();
+            return {
+              subagentId: args.subagent_id,
+              state: "already-inactive",
+              stopReason: "unknown",
+            };
+          }
+
+          const stopReason = await waiter.promise;
+          return {
+            subagentId: args.subagent_id,
+            state: "settled",
+            stopReason,
+          };
+        } catch (error) {
+          waiter.cancel();
+          throw error;
+        }
+      },
+    }),
+  );
+}

package/lib/workflow.js

@@ -0,0 +1,215 @@
+/**
+ * Trellis project state resolution: project root, workflow-state blocks,
+ * active task pointer, and status mapping.
+ *
+ * Pure logic with an injectable filesystem shim so unit tests run without
+ * touching a real Trellis project.
+ *
+ * @module dsh-trellis/workflow
+ */
+import { join, dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+/** Workflow-state block charset, mirrored from Trellis's workflow.md contract. */
+const STATUS_RE =
+  /\[workflow-state:([A-Za-z0-9_-]+)\]([\s\S]*?)\[\/workflow-state:\1\]/g;
+
+/** Same sanitization Trellis task.py applies to context keys. */
+export function sanitizeContextKey(value) {
+  return String(value)
+    .replace(/[^A-Za-z0-9._-]+/g, "_")
+    .replace(/^[._-]+|[._-]+$/g, "");
+}
+
+/** The degrading fallback when workflow.md lacks a block for the resolved status. */
+export const FALLBACK_BREADCRUMB =
+  "Refer to `.trellis/workflow.md` for the current workflow step (no matching [workflow-state] block found).";
+
+/**
+ * Parse every `[workflow-state:STATUS] ... [/workflow-state:STATUS]` block.
+ * @param {string} content - workflow.md content.
+ * @returns {Map<string, string>} status → trimmed body.
+ */
+export function parseWorkflowStateBlocks(content) {
+  const blocks = new Map();
+  for (const match of content.matchAll(STATUS_RE)) {
+    blocks.set(match[1], match[2].trim());
+  }
+  return blocks;
+}
+
+/**
+ * Walk upward from cwd to the first directory containing one of the markers.
+ * @param {string} cwd - absolute starting directory.
+ * @param {string[]} markers - child names that identify a project root.
+ * @param {{exists(path: string): Promise<boolean>}} fs - filesystem shim.
+ * @returns {Promise<string | null>}
+ */
+export async function findProjectRoot(cwd, markers, fs) {
+  let current = resolve(cwd);
+  for (;;) {
+    for (const marker of markers) {
+      if (await fs.exists(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Read a file, returning null when absent. Cache by (path, mtimeMs) so the
+ * per-turn hot path does not re-read workflow.md on every step.
+ * @param {string} path
+ * @param {{readFile(path: string): Promise<string | null>, stat(path: string): Promise<{mtimeMs: number} | null>}} fs
+ * @param {Map<string, {mtimeMs: number, content: string | null}>} cache
+ * @returns {Promise<string | null>}
+ */
+export async function readCached(path, fs, cache) {
+  try {
+    const info = await fs.stat(path);
+    if (info === null) return null;
+    const hit = cache.get(path);
+    if (hit !== undefined && hit.mtimeMs === info.mtimeMs) return hit.content;
+    const content = await fs.readFile(path);
+    cache.set(path, { mtimeMs: info.mtimeMs, content });
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the active task for a dsh session.
+ *
+ * Canonical Trellis semantics are session-pointer-driven. If this session has
+ * no usable pointer, mirror `active_task.py`'s conservative class-2 fallback:
+ * infer a task only when the runtime contains exactly one session JSON file.
+ * Two or more files means multiple windows may be active, so the resolver
+ * refuses to guess even when one task happens to be newer.
+ *
+ * @param {string} root - project root.
+ * @param {string} contextKey - sanitized `dsh_<session-id>` key for this agent.
+ * @param {{listDir(path: string): Promise<string[]>, readFile(path: string): Promise<string | null>, stat(path: string): Promise<{mtimeMs: number} | null>}} fs
+ * @returns {Promise<{path: string, status: string} | null>} task dir-relative path + status.
+ */
+export async function resolveActiveTask(root, contextKey, fs) {
+  // 1. Session-scoped pointer (task.py start / create).
+  const sessionsDir = join(root, ".trellis", ".runtime", "sessions");
+  let names = [];
+  try {
+    names = await fs.listDir(sessionsDir);
+  } catch {
+    names = [];
+  }
+  for (const name of names) {
+    if (name !== `${contextKey}.json`) continue;
+    let data = null;
+    try {
+      data = JSON.parse((await fs.readFile(join(sessionsDir, name))) ?? "null");
+    } catch {
+      continue;
+    }
+    if (
+      data === null ||
+      typeof data !== "object" ||
+      typeof data.current_task !== "string"
+    )
+      continue;
+    const status = await readTaskStatus(root, data.current_task, fs);
+    if (status !== null) return { path: data.current_task, status };
+  }
+
+  // 2. Official single-session fallback. Count files before parsing so one
+  // malformed pointer cannot make a multi-window runtime look unambiguous.
+  const sessionFiles = names.filter((name) => name.endsWith(".json"));
+  if (sessionFiles.length !== 1) return null;
+
+  let fallback = null;
+  try {
+    fallback = JSON.parse(
+      (await fs.readFile(join(sessionsDir, sessionFiles[0]))) ?? "null",
+    );
+  } catch {
+    return null;
+  }
+  if (
+    fallback === null ||
+    typeof fallback !== "object" ||
+    typeof fallback.current_task !== "string" ||
+    fallback.current_task === ""
+  ) {
+    return null;
+  }
+  const status = await readTaskStatus(root, fallback.current_task, fs);
+  return status === null ? null : { path: fallback.current_task, status };
+}
+
+/**
+ * Read one task.json status, or null when missing/unparseable.
+ * @param {string} root
+ * @param {string} taskPath - repo-root relative task dir (e.g. `.trellis/tasks/04-17-foo`).
+ * @param {{readFile(path: string): Promise<string | null>}} fs
+ * @returns {Promise<string | null>}
+ */
+export async function readTaskStatus(root, taskPath, fs) {
+  try {
+    const data = JSON.parse(
+      (await fs.readFile(join(root, taskPath, "task.json"))) ?? "null",
+    );
+    if (
+      data !== null &&
+      typeof data === "object" &&
+      typeof data.status === "string"
+    ) {
+      return data.status;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Map a task.json status to a workflow-state breadcrumb status.
+ * @param {string | null} status
+ * @returns {"planning" | "in_progress" | "no_task"}
+ */
+export function mapStatus(status) {
+  if (status === "planning") return "planning";
+  if (status === "in_progress") return "in_progress";
+  return "no_task";
+}
+
+/**
+ * Resolve the full Trellis state for one session step.
+ * @param {object} options
+ * @param {string} options.cwd
+ * @param {string[]} options.markers
+ * @param {string} options.contextKey - sanitized session context key.
+ * @param {object} options.fs - filesystem shim ({exists, listDir, readFile, stat}).
+ * @param {Map<string, {mtimeMs: number, content: string | null}>} options.cache
+ * @returns {Promise<{root: string, status: string, taskPath: string | null, body: string, digest: string} | null>}
+ */
+export async function resolveTrellisState({
+  cwd,
+  markers,
+  contextKey,
+  fs,
+  cache,
+}) {
+  const root = await findProjectRoot(cwd, markers, fs);
+  if (root === null) return null;
+  const workflowPath = join(root, ".trellis", "workflow.md");
+  const content = await readCached(workflowPath, fs, cache);
+  if (content === null || content === undefined) return null;
+  const blocks = parseWorkflowStateBlocks(content);
+  if (blocks.size === 0) return null;
+  const task = await resolveActiveTask(root, contextKey, fs);
+  const status = mapStatus(task?.status ?? null);
+  const body = blocks.get(status) ?? FALLBACK_BREADCRUMB;
+  const digest = createHash("sha1")
+    .update(`${status}\n${task?.path ?? ""}\n${body}`)
+    .digest("hex");
+  return { root, status, taskPath: task?.path ?? null, body, digest };
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "dsh-trellis",
+  "version": "0.1.0",
+  "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"
+  },
+  "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"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-shell-env": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}