dsh-herdr-bridge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-herdr-bridge contributors
+
+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

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# dsh-herdr-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）插件，把 DSH 的会话接进 [Herdr Core](https://github.com/herdrdev/herdr-core)（`hc`）：每个会话变成一个 hc 终端，Herdr 里的其他 Agent 可以像操控 Claude Code 一样读取和操控它。适用于 DSH Desktop 和 DSH Web（`dsh web`）。
+
+装好以后：
+
+- **在 Herdr 里看到 DSH 会话**：会话一开始运行，[Herdr App](https://github.com/herdrdev/herdr-app) 和 [Perch](https://github.com/Hariketsu/herdr-perch) 里就出现一行 `dsh-<短 id>`，状态在 `working / done / blocked / error` 之间跟着变。
+- **从 Herdr 操控 DSH**：Herdr Agent 用 `hc run / send / wait / read / interrupt` 新建会话、接管已有会话、发消息、取消回合。
+- **让 DSH 调度其他 Agent**：DSH 里的模型可以用 `hc` 启动 helper（比如 Claude Code），helper 的回报会送回这个 DSH 会话。
+- **审批两边都能答**：会话等待审批或提问时，在 DSH 界面或 hc 里回答都行，先答者生效，另一边的对话框会撤回。
+
+插件运行在 DSH 自己的进程里，不需要第二份 DSH，也不修改 DSH、Herdr 的任何源码。
+
+## 效果
+
+<!-- TODO: Perch / Herdr App 里显示 dsh-xxxx 行的截图 -->
+
+Herdr Agent 读取一个 DSH 会话时，看到的是和原生 TUI Agent 相同格式的文本（示例）：
+
+```text
+$ hc read fix
+❯ 修复 x.rs 里失败的测试
+⏺ 先跑一下测试看看失败在哪。
+⏺ bash 运行 x 的单元测试
+  ⎿ test parse_empty ... FAILED (+23 lines)
+⏺ 空输入时没有提前返回，已修复并重跑，全部通过。
+✻ done · 41s
+```
+
+## 要求
+
+| | 开发时使用的版本 | 说明 |
+|---|---|---|
+| DSH（Desktop 或 `dsh web`） | 0.2.2-rc.1 | 插件依赖的 DSH 接口仍在变化，升级 DSH 后可能需要更新插件。`dsh headless` 不支持，`dsh tui` 没有测试过 |
+| herdr-core（`hc`） | 0.1.18 | `hc` 需要在登录 shell 的 PATH 上，或在配置里指定 |
+| herdr-app | 0.1.13 | 可选 |
+| Perch | `40e4e2c` | 可选 |
+
+Desktop 和 `dsh web` 同一时间只能有一个接入 Herdr（见已知限制）。
+
+平台：只在 macOS 上验证过。Windows / Linux 的代码路径已写好，但没有测试过。暂无最低版本要求，只保证上表这一组合。
+
+## 安装
+
+1. 装进你使用的 DSH profile。Desktop 用 `desktop`，要先完全退出 Desktop（⌘Q）；Web 用 `web`，要先停掉 `dsh web`：
+   ```sh
+   dsh plugin --profile desktop add dsh-herdr-bridge --ignore-scripts --config.auto-install-peers=false   # 或 --profile web
+   ```
+2. 重新打开 Desktop 或启动 `dsh web`。插件加载时会生成命令 `~/.dsh/herdr-bridge/bin/dsh-hc`。
+3. 把它加进 PATH（下文的示例都假设已经加好），并安装 hc template，让 `hc run dsh "任务"` 可用：
+   ```sh
+   fish_add_path ~/.dsh/herdr-bridge/bin                # fish；zsh/bash 在 rc 文件里加 export PATH="$HOME/.dsh/herdr-bridge/bin:$PATH"
+   dsh-hc install-template                              # 写入 ~/.config/herdr-core/templates/dsh.md
+   ```
+
+**确认安装成功**：
+
+```sh
+dsh-hc ls          # 列出 DSH 里最近的会话（还没有会话时显示 no DSH sessions in that period）
+```
+
+然后在 DSH 里随便发一条消息，`hc ls` 里应该出现 `dsh-<短 id>` 终端。
+
+**卸载**：退出 Desktop 或停掉 `dsh web`，执行 `dsh plugin --profile <profile> remove dsh-herdr-bridge`；如果你在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里加过 `herdr-bridge` 配置，一并删掉。再删除 `~/.config/herdr-core/templates/dsh.md` 和 `~/.dsh/herdr-bridge/`。已经开着的 `dsh-*` 终端会在宽限期后自行退出。
+
+## 快速上手
+
+**1. 在 DSH 里正常使用。** 会话第一次运行时，插件为它开一个 `dsh-<短 id>` 终端，带标签 `dsh.session=<会话 id>` 和 `dsh.title=<会话标题>`（标题随改名同步）。还没运行过的会话，在 DSH 里对它输入 `/herdr`，它就会出现在 Herdr 里，命令会显示它的 hc 地址。会话关闭时，终端随之结束。
+
+**2. 从 Herdr 新建一个 DSH 会话。** 下面的 `/repo`、`fix` 都是示例：
+
+```sh
+hc run --bg --name fix --cwd /repo dsh "修复 x.rs 里失败的测试"
+hc wait fix               # 等这一回合结束
+hc read fix               # 读回复
+hc send --wait fix "继续，把边界情况也测了"
+```
+
+新会话的目录如果正好是 DSH 里已有的 Workspace，就加入它；是某个 Workspace 的子目录，就建成“未分组”会话；其他目录会自动添加为新的 Workspace。
+
+**3. 接管一个已有会话。**
+
+```sh
+dsh-hc ls --days 7                                  # 会话 id、标题、目录、是否已在 hc 里
+hc run --bg --name login dsh-hc attach 3b729fc9     # 用 id、id 前缀或标题片段
+hc read login                                       # 先看到之前的对话，再看到新的
+```
+
+如果这个会话已经有自动映射的 `dsh-<短 id>` 终端，那个终端会退出，由接管的终端代替。
+
+**4. 需要时取消。** `hc interrupt fix` 取消当前回合，相当于在 DSH 里点停止。
+
+## 审批、提问与信任边界
+
+会话等待审批或提问时，DSH 界面照常弹出对话框，hc 终端里也显示同一个问题，状态为 `blocked`。在 hc 侧回答必须加 `--force`：
+
+```sh
+hc send --force fix y      # 批准一次；n 为拒绝
+hc send --force fix 1,3    # 提问：选项序号（多选用逗号），也可以写自由文本，或 - 跳过
+```
+
+这和 hc 对待其他 Agent 的规则一致：hc 拒绝向 blocked 的程序普通 `send`，`--force` 是唯一的闸门。插件本身从不自动回答，什么时候可以用 `--force`，由驱动它的 Agent 的指令决定（见 `hc --skill`）。
+
+需要知道的边界：
+
+- **谁能操控会话**：能使用你的 hc 的进程，都能读取和操控已映射的 DSH 会话，和 hc 里的其他终端一样。插件的控制 socket 在 `~/.dsh/herdr-bridge/control.sock`，只在本机。
+- **权限不放大**：hc 发来的消息走 DSH 正常的 prompt 流程，会话原有的沙箱和审批规则照常生效。
+- **来自 hc 的输入会成为用户消息**：`hc send` 的文本，以及 helper 的回报和 hc 通知（完成、blocked、退出），都会作为下一条用户消息进入 DSH 会话并唤醒它。hc 发出的消息带有 `<hc …>` 标记，模型能看出来源，但它们和你亲手输入的消息处在同一个位置。
+
+## DSH 调度其他 Agent
+
+插件给已映射的会话注入 `DSH_HC_TERMINAL`（会话自己的 hc 地址），并注册一个 skill `herdr-bridge`，告诉模型这样启动 helper：
+
+```sh
+hc run --bg --parent "$DSH_HC_TERMINAL" --name helper --cwd /repo claude "…完成后用 hc send $DSH_HC_TERMINAL 汇报"
+```
+
+通用的 hc 用法来自 `~/.agents/skills/herdr-core`，DSH 会自动发现这个目录。
+
+## 配置
+
+写在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 的 `herdr-bridge` 条目下，全部可选：
+
+```yaml
+- id: herdr-bridge
+  config:
+    reconnectGraceSeconds: 30   # 插件断开后，终端等待重连的秒数，超时退出（默认 30）
+    herdrSpace: s3              # 给终端打 herdr.space 标签，在 Herdr App 的这个 space 里显示
+    hc: /path/to/hc             # hc 可执行文件，默认是 PATH 上的 hc
+```
+
+## 故障排查
+
+先看日志 `~/.dsh/herdr-bridge/bridge.log`。
+
+| 现象 | 检查 |
+|---|---|
+| DSH 里在用的会话，`hc ls` 里没有 | 日志里有没有插件加载和开终端失败的记录；DSH 进程能否找到 `hc`（Desktop 用登录 shell 的 PATH，`dsh web` 用启动它的 shell 的 PATH；找不到就在配置里设 `hc`）；是否同时开着 Desktop 和 `dsh web`（见已知限制） |
+| `dsh-hc: command not found` | PATH 没加好；直接用 `~/.dsh/herdr-bridge/bin/dsh-hc`。这个文件不存在说明插件没加载 |
+| `hc run dsh …` 提示找不到 template | 执行 `dsh-hc install-template` |
+| 终端显示“断开 → 重新连接” | 插件重载了（比如你在 DSH 里改了设置），正常现象，地址不变 |
+| `dsh-*` 终端突然退出 | DSH 退出或插件超过 `reconnectGraceSeconds` 没回来；重开 DSH 后，会话下次运行时会重新映射 |
+| 终端报协议版本不符 | 插件升级后旧终端还在跑旧代理；关掉终端重新 `attach` |
+| 升级 DSH 后插件不工作 | DSH 接口有变化，暂时降级 DSH 或等插件更新，并把日志附在 issue 里 |
+
+## 已知限制
+
+- **Desktop 和 `dsh web` 不能同时接入**：两者共用 `~/.dsh/herdr-bridge/`，只有先启动的那个能正常接入 Herdr。
+- **DSH 里看过的回合，Perch 仍显示“完成未看”**：Herdr 不知道 DSH 界面也是一个观看者。
+- **插件重载后，空闲会话从 `done` 变成 `idle`**：上一回合的结论丢失。Perch 的“完成未看”按回合数判断，不受影响。
+- **每个映射出去的会话有一个代理进程**，实际物理内存约 13–14 MB。
+- **插件升级后，已开着的终端仍运行旧代理**，直到重开。
+- **审批的“另一边撤回”依赖 DSH 的内部实现**：DSH 改动后可能失效，表现是 DSH 界面的对话框不消失，不会导致错误批准。
+
+计划和未验证的路径见 [TODO.md](TODO.md)。
+
+## 工作原理
+
+每个 hc 终端里跑一个很薄的代理 `dsh-hc`（用运行 DSH 的同一个 Node，Desktop 上就是它自带的那个），通过本机 socket 连到 DSH 进程里的插件。插件把 DSH 事件渲染成终端文本和 OSC 7501 状态，把终端输入转成 prompt、取消或审批回答。插件重载时代理会重连，hc 地址不变。
+
+架构、状态映射、竞争应答的实现、被否决的方案和测试覆盖，见 [docs/architecture.md](docs/architecture.md)。
+
+## 开发
+
+从源码安装、开发回路和隔离测试环境见 [docs/development.md](docs/development.md)，Agent 的工作约定见 [AGENTS.md](AGENTS.md)。简述：
+
+```sh
+scripts/dev.sh up          # 隔离环境：模拟 LLM + 隔离 hc core + 隔离 dsh web（Desktop 替身）
+scripts/dev.sh reload      # 热重载插件
+scripts/e2e.sh             # 32 项 hc 侧回归
+scripts/e2e-ui.sh          # 12 项 UI 侧回归（ego-browser）
+scripts/dev.sh down
+scripts/desktop.sh reload  # 把改动热重载进真实 Desktop（只改 cordis.patch.yml 里 herdr-bridge 这一项，首次会备份）
+```
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: herdr-bridge
+      name: dsh-herdr-bridge

package/index.js

@@ -0,0 +1,582 @@
+// dsh-herdr-bridge: DSH sessions as ordinary Herdr Core (hc) terminals.
+//
+// Each mirrored session has an hc terminal running `dsh-hc` (proxy.js), a thin pipe that connects
+// to this plugin's control socket. The plugin renders the conversation (render.js) and OSC 7501
+// status into that pipe, and turns keys coming back into prompts, cancellation, and answers.
+// See README.md for the design.
+import net from 'node:net'
+import { execFile } from 'node:child_process'
+import { appendFileSync, chmodSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, join, sep } from 'node:path'
+import { homedir } from 'node:os'
+import { createHash, randomUUID } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { Renderer, crlf, oneLine, osc, style } from './render.js'
+
+export const name = 'herdr-bridge'
+
+const PROTOCOL = 1
+const PASTE_START = '\x1b[200~'
+const PASTE_END = '\x1b[201~'
+const HC_REQUEST_PREFIX = 'hc-'
+const HISTORY_MESSAGES = 20
+
+/** Split terminal input into submitted text (Enter outside a paste) and cancel (lone Esc / Ctrl+C). */
+function inputParser({ submit, cancel, echo }) {
+  let text = ''
+  let pasting = false
+  let held = ''
+  return chunk => {
+    const s = held + chunk
+    held = ''
+    if (s === '\x1b') return cancel()
+    let i = 0
+    while (i < s.length) {
+      const rest = s.slice(i)
+      if (rest.startsWith(PASTE_START)) { pasting = true; i += PASTE_START.length; continue }
+      if (rest.startsWith(PASTE_END)) { pasting = false; i += PASTE_END.length; continue }
+      if (rest[0] === '\x1b') {
+        if (PASTE_START.startsWith(rest) || PASTE_END.startsWith(rest)) { held = rest; break }
+        const seq = /^\x1b(\[[0-9;?]*[ -/]*[@-~]|.)/.exec(rest)
+        i += seq ? seq[0].length : 1
+        continue
+      }
+      const c = rest[0]
+      i += 1
+      if (pasting) { text += c === '\r' ? '\n' : c; continue }
+      if (c === '\r') {
+        const done = text
+        text = ''
+        echo('\r\n')
+        if (done.trim()) submit(done)
+      } else if (c === '\x7f' || c === '\b') {
+        if (text) { text = text.slice(0, -1); echo('\b \b') }
+      } else if (c === '\x03') {
+        cancel()
+      } else if (c >= ' ' || c === '\t') {
+        text += c
+        echo(c)
+      }
+    }
+  }
+}
+
+/** Newline-delimited JSON on a socket. */
+function lines(socket, onMessage) {
+  let buffer = ''
+  socket.setEncoding('utf8')
+  socket.on('data', chunk => {
+    buffer += chunk
+    let end
+    while ((end = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, end)
+      buffer = buffer.slice(end + 1)
+      if (!line) continue
+      let message
+      try { message = JSON.parse(line) } catch { continue }
+      onMessage(message)
+    }
+  })
+}
+const send = (socket, message) => { if (!socket.destroyed) socket.write(`${JSON.stringify(message)}\n`) }
+
+const realpath = p => { try { return realpathSync(p) } catch { return p } }
+
+const SKILL = `# DSH session in Herdr (herdr-bridge)
+
+This DSH session is mirrored into Herdr Core (hc) as an ordinary terminal, so you can use \`hc\`
+(see the \`herdr-core\` skill or \`hc --skill\`) to run and coordinate other agents.
+
+- \`$DSH_HC_TERMINAL\` is this session's own hc address (empty until the session is mirrored,
+  which happens on its first run).
+- hc cannot tell which terminal your shell belongs to, so name yourself explicitly:
+  start helpers with \`hc run --bg --parent "$DSH_HC_TERMINAL" --name <name> --cwd <dir> <template|command> "<task>"\`
+  and tell them to report with \`hc send $DSH_HC_TERMINAL "<result>"\`.
+- Their reports, and hc's notes about them (finished, blocked, exited), arrive as your next user
+  message. After starting helpers, end your turn instead of waiting; you will be woken.
+- Your shell calls time out after about 60 s: if you must wait, use \`hc wait <t> --timeout 50\`
+  and repeat, never a bare \`hc wait\`.
+- Without \`$DSH_HC_TERMINAL\`, use \`hc run --bg --no-parent …\` and ask for reports to a file.
+`
+
+export function apply(ctx, config = {}) {
+  const hc = config.hc || 'hc'
+  const herdrSpace = config.herdrSpace || ''
+  const grace = Number(config.reconnectGraceSeconds ?? 30)
+  const home = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'herdr-bridge')
+  mkdirSync(home, { recursive: true })
+  const log = (...a) => appendFileSync(join(home, 'bridge.log'), `${new Date().toISOString()} ${a.join(' ')}\n`)
+  const socketPath = process.platform === 'win32'
+    ? `\\\\.\\pipe\\dsh-herdr-bridge-${createHash('sha1').update(home).digest('hex').slice(0, 12)}`
+    : join(home, 'control.sock')
+
+  // The launcher runs proxy.js with the Node that ships with DSH (this process's executable).
+  const launcher = (() => {
+    const proxy = fileURLToPath(new URL('./proxy.js', import.meta.url))
+    const bin = join(home, 'bin')
+    mkdirSync(bin, { recursive: true })
+    if (process.platform === 'win32') {
+      const file = join(bin, 'dsh-hc.cmd')
+      writeFileSync(file, `@echo off\r\nset ELECTRON_RUN_AS_NODE=1\r\nset "DSH_HERDR_SOCKET=${socketPath}"\r\nset "DSH_HERDR_LAUNCHER=${file}"\r\n"${process.execPath}" "${proxy}" %*\r\n`)
+      return file
+    }
+    const q = s => `'${s.replace(/'/g, `'\\''`)}'`
+    const file = join(bin, 'dsh-hc')
+    writeFileSync(file, `#!/bin/sh\nELECTRON_RUN_AS_NODE=1 DSH_HERDR_SOCKET=${q(socketPath)} DSH_HERDR_LAUNCHER=${q(file)} exec ${q(process.execPath)} ${q(proxy)} "$@"\n`)
+    chmodSync(file, 0o755)
+    return file
+  })()
+
+  const runHc = (args, done) => execFile(hc, args, (error, stdout, stderr) => {
+    if (error) log('hc', args[0], 'failed:', oneLine(stderr || error.message, 300))
+    done?.(error, stdout)
+  })
+
+  /** Host session services, present only in hosts that have them (Desktop, `dsh web`). */
+  let sessions = null
+  /** The Agent registry, to know whether a session is running when its bridge is (re)created. */
+  let agents = null
+  /** @type {Map<string, Bridge>} by session id */
+  const bridges = new Map()
+
+  class Bridge {
+    constructor(sessionId, cwd) {
+      this.sessionId = sessionId
+      this.cwd = cwd
+      this.title = basename(cwd || '') || 'dsh'
+      this.terminal = '' // hc address of the terminal mirroring it
+      this.status = { state: agents?.get(sessionId)?.status === 'running' ? 'working' : 'idle' }
+      this.lastEnd = null
+      this.waiter = null // a pending answer typed in hc
+      this.conns = new Map() // socket → { auto }
+      this.renderer = new Renderer()
+      this.launching = false
+      bridges.set(sessionId, this)
+      this.loadTitle()
+    }
+
+    get short() { return this.sessionId.replace(/^session-/, '').slice(0, 8) }
+    get mirrored() { return this.conns.size > 0 || this.launching }
+
+    out(s) { if (s) for (const socket of this.conns.keys()) send(socket, { t: 'out', d: s }) }
+    set(state, extra = {}) {
+      this.status = { state, ...extra }
+      this.out(osc(this.status, this.title))
+    }
+    retitle(title) {
+      title = oneLine(title, 80)
+      if (!title || title === this.title) return
+      this.title = title
+      this.out(osc(this.status, this.title))
+      if (this.terminal) runHc(['label', this.terminal, `dsh.title=${title}`])
+    }
+
+    async loadTitle() {
+      try {
+        const item = (await sessions?.sessionController.list({}, new AbortController().signal))
+          ?.items.find(i => i.sessionId === this.sessionId)
+        this.retitle(item?.projections?.values?.title)
+      } catch (error) {
+        log('title lookup failed', this.sessionId, error?.message ?? error)
+      }
+    }
+
+    /** Recent conversation, rendered like the live one, for a terminal that just joined. */
+    async history(socket) {
+      try {
+        const page = await sessions?.sessionController.page(
+          { address: { kind: 'session', sessionId: this.sessionId }, maxMessages: HISTORY_MESSAGES },
+          new AbortController().signal)
+        const replay = new Renderer()
+        replay.cols = this.renderer.cols
+        // History records wrap the session event: { type: 'event', event }.
+        const text = (page?.records ?? []).map(record => replay.event(record?.event ?? record)).join('')
+        if (text) send(socket, { t: 'out', d: text + crlf(`${style.dim('─── earlier conversation above ───')}\n`) })
+      } catch (error) {
+        log('history failed', this.sessionId, error?.message ?? error)
+      }
+    }
+
+    async attach(socket, hello, origin) {
+      this.launching = false
+      this.conns.set(socket, { auto: Boolean(hello.auto) })
+      if (hello.term) {
+        const changed = this.terminal !== hello.term
+        this.terminal = hello.term
+        if (changed) runHc(['label', this.terminal, `dsh.session=${this.sessionId}`, `dsh.title=${this.title}`])
+      }
+      if (hello.cols) this.renderer.cols = hello.cols
+      socket.on('close', () => this.conns.delete(socket))
+      send(socket, { t: 'welcome', v: PROTOCOL, session: this.sessionId, origin, grace })
+      send(socket, { t: 'out', d: osc(this.status, this.title) })
+      const feed = inputParser({
+        submit: text => this.submit(text),
+        cancel: () => this.cancel(),
+        echo: s => send(socket, { t: 'out', d: s }),
+      })
+      lines(socket, message => {
+        if (message.t === 'in' && typeof message.d === 'string') feed(message.d)
+        else if (message.t === 'size' && message.cols) this.renderer.cols = message.cols
+      })
+      if (!hello.resumed) {
+        send(socket, { t: 'out', d: crlf(`${style.bold(this.title)} ${style.dim(`· dsh ${this.short} · ${this.cwd ?? ''}`)}\n${style.dim('Enter sends · Esc cancels')}\n`) })
+        if (hello.mode === 'attach') await this.history(socket)
+      }
+    }
+
+    submit(text) {
+      if (this.waiter) {
+        const resolve = this.waiter
+        this.waiter = null
+        return resolve(text.trim())
+      }
+      return this.prompt(text)
+    }
+
+    /** Wait for the next line typed in hc; null when withdrawn. */
+    ask(signal) {
+      return new Promise(resolve => {
+        if (signal?.aborted) return resolve(null)
+        this.waiter = resolve
+        signal?.addEventListener('abort', () => {
+          if (this.waiter === resolve) { this.waiter = null; resolve(null) }
+        }, { once: true })
+      })
+    }
+
+    async prompt(text) {
+      const controller = sessions?.sessionController
+      if (!controller) return this.out(crlf('[bridge] this DSH host cannot take prompts\n'))
+      try {
+        await controller.prompt({
+          requestId: HC_REQUEST_PREFIX + randomUUID(),
+          sessionId: this.sessionId,
+          mode: 'queue',
+          content: [{ type: 'text', text }],
+        }, new AbortController().signal)
+      } catch (error) {
+        log('prompt failed', this.sessionId, error?.message ?? error)
+        this.out(crlf(`${style.red(`[bridge] prompt failed: ${error?.message ?? error}`)}\n`))
+      }
+    }
+
+    async cancel() {
+      try {
+        await sessions?.sessionController.cancel({ sessionId: this.sessionId })
+      } catch (error) {
+        log('cancel failed', this.sessionId, error?.message ?? error)
+      }
+    }
+
+    /** Mirror into hc: a terminal named dsh-<short id> running `dsh-hc attach`. */
+    launch() {
+      if (this.mirrored) return
+      this.launching = true
+      const args = ['run', '--bg', '--rm', '--no-parent', '--json', '--name', `dsh-${this.short}`,
+        '--label', `dsh.session=${this.sessionId}`, '--label', `dsh.title=${this.title}`]
+      if (herdrSpace) args.push('--label', `herdr.space=${herdrSpace}`)
+      if (this.cwd) args.push('--cwd', this.cwd)
+      args.push('--', launcher, 'attach', '--session', this.sessionId, '--auto')
+      // A failure is usually the name being taken: that terminal is still ours and reconnecting.
+      runHc(args, error => { if (error) this.launching = false })
+    }
+
+    /** Close every terminal mirroring this session; `except` keeps one. */
+    release(reason, except) {
+      for (const socket of this.conns.keys()) {
+        if (socket === except) continue
+        send(socket, { t: 'bye', reason })
+        socket.end()
+        this.conns.delete(socket)
+      }
+    }
+
+    dispose(reason) {
+      this.waiter?.(null)
+      this.release(reason)
+      bridges.delete(this.sessionId)
+    }
+  }
+
+  const sessionOf = agent => agent?.session
+  const isSubagent = agent => agent?.session.header?.origin === 'subagent'
+  const bridgeFor = (sessionId, cwd) => bridges.get(sessionId) ?? new Bridge(sessionId, cwd)
+  /** A top-level agent's bridge; a subagent speaks through its parent's. */
+  const bridgeOf = agent => {
+    const session = sessionOf(agent)
+    if (!session) return undefined
+    if (!isSubagent(agent)) return bridgeFor(session.id, session.header?.cwd)
+    return session.header?.parentSession ? bridges.get(session.header.parentSession) : undefined
+  }
+
+  ctx.on('agent/status', ({ agent, status }) => {
+    if (isSubagent(agent)) return
+    const bridge = bridgeOf(agent)
+    if (status === 'running') {
+      bridge.lastEnd = null
+      bridge.launch()
+      bridge.set('working')
+      return
+    }
+    const end = bridge.lastEnd
+    if (!end || end.kind === 'completed' || end.kind === 'max-tokens') bridge.set(end ? 'done' : 'idle')
+    else if (end.kind === 'aborted') bridge.set('idle')
+    else bridge.set('error', { msg: oneLine(end.error?.message ?? end.kind) })
+  })
+
+  ctx.on('session/event', (session, event) => {
+    if (session.header?.origin === 'subagent') return
+    const bridge = bridges.get(session.id)
+    if (!bridge) return
+    if (event.type === 'turn/end') bridge.lastEnd = event.data?.reason ?? { kind: 'completed' }
+    else if (event.type === 'session/title') bridge.retitle(event.data?.title)
+    bridge.out(bridge.renderer.event(event))
+  })
+
+  ctx.on('agent/assistant-stream', ({ agent, frame }) => {
+    if (isSubagent(agent)) return
+    const bridge = bridges.get(agent.session.id)
+    if (bridge) bridge.out(bridge.renderer.stream(frame))
+  })
+
+  ctx.on('agent/disposed', ({ agent }) => {
+    if (!isSubagent(agent)) bridges.get(agent.session.id)?.dispose('the DSH session closed')
+  })
+
+  // Blocked: Desktop and hc race to answer; the first answer wins and withdraws the other.
+  // DSH forwards an approval/question to Desktop's UI and withdraws that dialog when the request's
+  // signal aborts, so we hand the rest of the chain a signal we can abort. Prepended: the shipped
+  // answerer never calls next(), so a later listener would never run.
+  const WITHDRAWN = Symbol('withdrawn')
+  const race = (kind, describe, render, fromHc, settledByDesktop) => async (req, next) => {
+    const bridge = req?.agent && bridgeOf(req.agent)
+    if (!bridge || bridge.conns.size === 0) return next()
+    const ours = new AbortController()
+    const original = req.signal
+    try { req.signal = original ? AbortSignal.any([original, ours.signal]) : ours.signal } catch {}
+    bridge.set('blocked', { kind, msg: oneLine(describe(req)) })
+    bridge.out(render(req))
+    const desktop = Promise.resolve().then(next).then(
+      value => ({ from: 'desktop', value }),
+      error => ({ from: 'desktop', error }),
+    )
+    const answered = fromHc(bridge, req, ours.signal).then(value => ({ from: 'hc', value }))
+    try {
+      let first = await Promise.race([desktop, answered])
+      // No Desktop answerer (e.g. no window): keep waiting for hc.
+      if (first.from === 'desktop' && !settledByDesktop(first)) {
+        const later = await answered
+        if (later.value !== WITHDRAWN) first = later
+      }
+      // The request was withdrawn (the turn was cancelled): Desktop's side settles on its own.
+      if (first.from === 'hc' && first.value === WITHDRAWN) first = await desktop
+      if (first.from === 'hc') {
+        ours.abort(new Error('answered in hc'))
+        desktop.catch(() => {})
+        bridge.out(crlf(`  ${style.dim(`answered in hc: ${oneLine(JSON.stringify(first.value), 120)}`)}\n`))
+        return first.value
+      }
+      ours.abort(new Error('answered in DSH Desktop'))
+      bridge.out(crlf(`  ${style.dim('answered in DSH Desktop')}\n`))
+      if (first.error) throw first.error
+      return first.value
+    } finally {
+      try { req.signal = original } catch {}
+      if (bridge.status.state === 'blocked') bridge.set('working')
+    }
+  }
+
+  const approvalFromHc = async (bridge, req, signal) => {
+    for (;;) {
+      const answer = await bridge.ask(AbortSignal.any([signal, req.signal].filter(Boolean)))
+      if (answer === null) return WITHDRAWN
+      if (/^(y|yes|allow|1)$/i.test(answer)) return 'allowed-once'
+      if (/^(n|no|reject|deny|2)$/i.test(answer)) return 'rejected'
+      bridge.out(crlf(`  ${style.dim('y = allow once, n = reject')}\n`))
+    }
+  }
+
+  const questionsFromHc = async (bridge, req, signal) => {
+    const answers = []
+    const questions = req.questions ?? []
+    const stop = AbortSignal.any([signal, req.signal].filter(Boolean))
+    for (const [index, q] of questions.entries()) {
+      if (index > 0) bridge.out(bridge.renderer.question(q, index, questions.length))
+      const answer = await bridge.ask(stop)
+      if (answer === null) return WITHDRAWN
+      const options = q.options ?? []
+      const picks = /^\d+(\s*,\s*\d+)*$/.test(answer)
+        ? answer.split(',').map(n => options[Number(n) - 1]?.label).filter(Boolean)
+        : null
+      if (answer === '-') answers.push({ id: q.id, selected: [] })
+      else if (picks?.length) answers.push({ id: q.id, selected: q.multiSelect ? picks : picks.slice(0, 1) })
+      else answers.push({ id: q.id, selected: [], custom: answer })
+    }
+    return { answers }
+  }
+
+  ctx.on('approval/request', race('permission',
+    r => `${r.toolName}${r.reason ? `: ${r.reason}` : ''}`,
+    r => bridgeOf(r.agent).renderer.approval(r),
+    approvalFromHc,
+    first => !first.error && first.value !== 'unavailable',
+  ), { prepend: true })
+  ctx.on('user-questions/request', race('question',
+    r => (r.questions ?? []).map(q => q.question ?? q.header ?? '').join(' / ') || 'question',
+    r => (r.questions?.length ? bridgeOf(r.agent).renderer.question(r.questions[0], 0, r.questions.length) : ''),
+    questionsFromHc,
+    first => !first.error,
+  ), { prepend: true })
+
+  // The control socket: dsh-hc terminals (new / attach / reconnect) and `dsh-hc ls`.
+  // Only hosts that can create and prompt sessions serve it, and a live owner is never displaced.
+  ctx.inject(['sessionController', 'workspaceRegistry'], c => {
+    sessions = c
+
+    /** The folder's Workspace; a subfolder of one goes ungrouped; anything else gets its own. */
+    const placement = async cwd => {
+      const real = realpath(cwd)
+      const spaces = c.workspaceRegistry.list().map(w => ({ id: w.id, path: realpath(w.path) }))
+      const exact = spaces.find(w => w.path === real)
+      if (exact) return { workspaceId: exact.id }
+      if (spaces.some(w => real.startsWith(w.path + sep))) return { cwd: real }
+      return { workspaceId: (await c.workspaceRegistry.create(real)).id }
+    }
+
+    const recent = async days => {
+      const { items } = await c.sessionController.list({}, new AbortController().signal)
+      const since = Date.now() - days * 86_400_000
+      return items
+        .filter(i => !i.origin && !i.blank && i.updatedAt >= since)
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .map(i => ({
+          sessionId: i.sessionId,
+          title: i.projections?.values?.title ?? '',
+          cwd: i.cwd ?? '',
+          updatedAt: i.updatedAt,
+          running: i.running,
+          terminal: bridges.get(i.sessionId)?.terminal ?? '',
+        }))
+    }
+
+    const resolve = async (hello) => {
+      const items = await recent(36500)
+      if (hello.session) return items.find(i => i.sessionId === hello.session) ?? { sessionId: hello.session }
+      const query = String(hello.query ?? '').trim()
+      const hits = items.filter(i => i.sessionId === query || i.sessionId === `session-${query}`
+        || i.sessionId.replace(/^session-/, '').startsWith(query))
+      const matches = hits.length ? hits : items.filter(i => i.title.toLowerCase().includes(query.toLowerCase()))
+      if (matches.length === 1) return matches[0]
+      if (!matches.length) throw new Error(`no DSH session matches "${query}" (see dsh-hc ls)`)
+      throw new Error(`"${query}" matches ${matches.length} sessions: ${matches.slice(0, 5)
+        .map(m => `${m.sessionId.replace(/^session-/, '').slice(0, 8)} ${m.title}`).join('; ')}`)
+    }
+
+    const serve = socket => {
+      let greeted = false
+      socket.on('error', () => {})
+      lines(socket, async message => {
+        if (greeted || message.t !== 'hello') return
+        greeted = true
+        socket.removeAllListeners('data')
+        try {
+          if (message.v !== PROTOCOL) throw new Error(`dsh-hc speaks protocol ${message.v}; this plugin speaks ${PROTOCOL}`)
+          if (message.mode === 'ls') {
+            send(socket, { t: 'ls', items: await recent(Number(message.days) || 7) })
+            return socket.end()
+          }
+          if (message.mode === 'new') {
+            if (!message.cwd) throw new Error('missing folder')
+            const { sessionId } = await c.sessionController.create(await placement(message.cwd))
+            return bridgeFor(sessionId, realpath(message.cwd)).attach(socket, message, 'hc')
+          }
+          if (message.mode === 'attach') {
+            const found = await resolve(message)
+            const bridge = bridgeFor(found.sessionId, found.cwd)
+            if (!message.auto && !message.resumed) {
+              // A Herdr agent takes the session over: the automatic mirror makes way for it.
+              for (const [other, meta] of bridge.conns) {
+                if (meta.auto) { send(other, { t: 'bye', reason: `taken over by ${message.term || 'another hc terminal'}` }); other.end(); bridge.conns.delete(other) }
+              }
+            }
+            const origin = message.resumed ? (message.origin ?? 'desktop') : (message.auto ? 'desktop' : 'hc')
+            return bridge.attach(socket, message, origin)
+          }
+          throw new Error(`unknown mode ${message.mode}`)
+        } catch (error) {
+          log('control', message.mode, 'failed:', error?.message ?? error)
+          send(socket, { t: 'error', message: String(error?.message ?? error) })
+          socket.end()
+        }
+      })
+    }
+
+    const control = net.createServer(serve)
+    control.on('error', error => log('control socket error', error.message))
+    const probe = net.connect(socketPath)
+    probe.on('connect', () => { probe.destroy(); log('control socket owned by another host; not serving it') })
+    probe.on('error', () => {
+      if (process.platform !== 'win32') rmSync(socketPath, { force: true })
+      control.listen(socketPath)
+    })
+    c.effect(() => () => { control.close(); sessions = null }, 'herdr-bridge: close control socket')
+  })
+
+  // /herdr: mirror this session into Herdr now and show its hc address.
+  ctx.inject(['commands'], c => {
+    c.commands.register({
+      name: 'herdr',
+      description: 'Show this session in Herdr (hc) and print its hc address',
+      handler: async ({ agent }) => {
+        if (!agent || isSubagent(agent)) return { kind: 'error', text: 'Only a top-level session can be shown in Herdr.' }
+        const bridge = bridgeOf(agent)
+        bridge.launch()
+        for (let i = 0; i < 50 && !bridge.terminal; i++) await new Promise(r => setTimeout(r, 100))
+        if (!bridge.terminal) return { kind: 'error', text: 'Could not open an hc terminal; see ~/.dsh/herdr-bridge/bridge.log' }
+        return { kind: 'success', text: `In Herdr as ${bridge.terminal} (dsh-${bridge.short}). A Herdr agent can use: hc send ${bridge.terminal} "…" / hc read ${bridge.terminal}` }
+      },
+    })
+  })
+
+  // Reverse direction: each session's shell learns its own hc address; the model learns how to use it.
+  ctx.inject(['shellEnv'], c => {
+    c.shellEnv.register({
+      name: 'herdr-bridge',
+      variables: { DSH_HC_TERMINAL: { description: "This session's own Herdr Core (hc) terminal address." } },
+      resolve: execution => {
+        const bridge = execution.agent && bridgeOf(execution.agent)
+        return bridge?.terminal ? { DSH_HC_TERMINAL: bridge.terminal } : {}
+      },
+    })
+  })
+  ctx.inject(['skills'], c => {
+    c.skills.register({
+      name: 'herdr-bridge',
+      description: 'Use hc from this DSH session: your own hc address ($DSH_HC_TERMINAL), starting helper agents that report back to you, and waiting without blocking.',
+      whenToUse: 'Before using hc (Herdr Core) to start, message, or wait for other agents or terminals.',
+      source: 'runtime',
+      content: SKILL,
+    })
+  })
+
+  // After a reload, proxies reconnect on their own; mirror the running sessions that did not.
+  ctx.inject(['agents'], c => {
+    agents = c.agents
+    const timer = setTimeout(() => {
+      for (const agent of c.agents.list()) {
+        if (agent.status === 'running' && !isSubagent(agent)) bridgeOf(agent).launch()
+      }
+    }, 3000)
+    c.effect(() => () => { clearTimeout(timer); agents = null }, 'herdr-bridge: re-mirror running sessions')
+  })
+
+  ctx.effect(() => () => {
+    // Proxies keep their terminals and reconnect to the next instance within the grace period.
+    for (const bridge of bridges.values()) {
+      bridge.waiter?.(null)
+      for (const socket of bridge.conns.keys()) socket.destroy()
+    }
+    bridges.clear()
+  }, 'herdr-bridge: drop connections')
+  log('loaded')
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "dsh-herdr-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bridge DeepSeek Harness (DSH) sessions into Herdr Core as hc terminals",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "render.js",
+    "proxy.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.9"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hariketsu/dsh-herdr-bridge.git"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "herdr",
+    "herdr-core",
+    "hc",
+    "agent"
+  ]
+}

package/proxy.js

@@ -0,0 +1,204 @@
+// dsh-hc: the program inside a DSH session's hc terminal, and a small CLI.
+// It is a thin pipe: raw keys and window size go to the dsh-herdr-bridge plugin; rendered text
+// (including OSC 7501 status) comes back and is written as is. When the plugin goes away (reload,
+// update, Desktop quitting) it keeps the terminal and reconnects within a grace period.
+//
+//   dsh-hc new                          a new DSH session in the current folder (hc template `dsh`)
+//   dsh-hc attach <session id | title>  take over an existing DSH session
+//   dsh-hc ls [--days N] [--json]       recent DSH sessions
+//   dsh-hc install-template             install the hc template `dsh`
+//
+// Started through the launcher the plugin writes ($DSH_HOME/herdr-bridge/bin/dsh-hc), which sets
+// DSH_HERDR_SOCKET and runs this file with the Node that ships with DSH Desktop.
+import net from 'node:net'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const PROTOCOL = 1
+const SOCKET = process.env.DSH_HERDR_SOCKET
+const LAUNCHER = process.env.DSH_HERDR_LAUNCHER
+const dim = s => `\x1b[2m${s}\x1b[22m`
+const b64 = s => Buffer.from(s).toString('base64')
+const errorStatus = msg => `\x1b]7501;state=error:app=dsh:msg=${b64(msg)}\x1b\\`
+
+function fail(message, code = 1) {
+  process.stderr.write(`dsh-hc: ${message}\n`)
+  process.exit(code)
+}
+
+/** Newline-delimited JSON on a socket. */
+function lines(socket, onMessage) {
+  let buffer = ''
+  socket.setEncoding('utf8')
+  socket.on('data', chunk => {
+    buffer += chunk
+    let end
+    while ((end = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, end)
+      buffer = buffer.slice(end + 1)
+      if (!line) continue
+      let message
+      try { message = JSON.parse(line) } catch { continue }
+      onMessage(message)
+    }
+  })
+}
+const send = (socket, message) => { if (socket && !socket.destroyed) socket.write(`${JSON.stringify(message)}\n`) }
+
+/** One request, one reply: `ls`. */
+function request(hello) {
+  return new Promise((resolve, reject) => {
+    if (!SOCKET) return reject(new Error('DSH_HERDR_SOCKET is not set; run dsh-hc through its launcher'))
+    const socket = net.connect(SOCKET)
+    socket.on('error', () => reject(new Error('DSH Desktop is not running, or dsh-herdr-bridge is not loaded')))
+    socket.on('connect', () => send(socket, { t: 'hello', v: PROTOCOL, ...hello }))
+    lines(socket, message => {
+      socket.end()
+      if (message.t === 'error') reject(new Error(message.message))
+      else resolve(message)
+    })
+  })
+}
+
+/** Interactive terminal mode: `new` and `attach`. */
+function terminal(first) {
+  const out = process.stdout
+  const size = () => ({ cols: out.columns || 100, rows: out.rows || 30 })
+  let socket = null
+  let welcome = null // { session, origin, grace } once the plugin accepted us
+  let live = false
+  let leaving = false
+  let deadline = 0
+
+  if (process.stdin.isTTY) process.stdin.setRawMode(true)
+  out.write('\x1b[?2004h') // bracketed paste: hc send arrives as one paste
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', d => {
+    if (live) send(socket, { t: 'in', d })
+    else out.write(dim('\r\n(not sent: reconnecting to DSH Desktop)\r\n'))
+  })
+  out.on('resize', () => send(socket, { t: 'size', ...size() }))
+
+  const leave = code => {
+    leaving = true
+    socket?.destroy()
+    process.exit(code)
+  }
+
+  const connect = hello => {
+    socket = net.connect(SOCKET)
+    socket.on('connect', () => send(socket, { t: 'hello', v: PROTOCOL, term: process.env.HC_TERMINAL_ID ?? '', ...size(), ...hello }))
+    lines(socket, message => {
+      if (message.t === 'welcome') {
+        const again = welcome !== null
+        welcome = { session: message.session, origin: message.origin, grace: message.grace ?? 30 }
+        live = true
+        deadline = 0
+        if (again) out.write(dim('⋯ reconnected\r\n'))
+      } else if (message.t === 'out') {
+        out.write(message.d)
+      } else if (message.t === 'bye') {
+        if (message.reason) out.write(dim(`\r\n⋯ ${message.reason}\r\n`))
+        leave(0)
+      } else if (message.t === 'error') {
+        out.write(`${errorStatus(message.message)}dsh-hc: ${message.message}\r\n`)
+        leave(1)
+      }
+    })
+    socket.on('error', () => {})
+    socket.on('close', () => {
+      live = false
+      if (leaving) return
+      if (!welcome) {
+        // Never got in: the plugin is not there (or refused). Report it so hc and its caller see why.
+        out.write(`${errorStatus('DSH Desktop is not running, or dsh-herdr-bridge is not loaded')}`
+          + 'dsh-hc: DSH Desktop is not running, or dsh-herdr-bridge is not loaded\r\n')
+        return setTimeout(() => leave(1), 200)
+      }
+      if (!deadline) {
+        deadline = Date.now() + welcome.grace * 1000
+        out.write(dim(`\r\n⋯ DSH Desktop disconnected; reconnecting for up to ${welcome.grace}s\r\n`))
+      }
+      if (Date.now() > deadline) {
+        out.write(dim('⋯ DSH Desktop did not come back\r\n'))
+        return leave(0)
+      }
+      setTimeout(() => {
+        connect({ mode: 'attach', session: welcome.session, origin: welcome.origin, resumed: true })
+      }, 1000)
+    })
+  }
+
+  if (!SOCKET) fail('DSH_HERDR_SOCKET is not set; run dsh-hc through its launcher')
+  connect(first)
+}
+
+function templateDir() {
+  if (process.platform === 'win32') return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'herdr-core', 'templates')
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'herdr-core', 'templates')
+}
+
+function installTemplate() {
+  if (!LAUNCHER) fail('DSH_HERDR_LAUNCHER is not set; run dsh-hc through its launcher')
+  const quoted = /\s/.test(LAUNCHER) ? `"${LAUNCHER}"` : LAUNCHER
+  const dir = templateDir()
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, 'dsh.md')
+  writeFileSync(file, `---
+name: dsh
+description: A DeepSeek Harness Desktop session in this folder (via dsh-herdr-bridge). Interactive; reports status. Find existing sessions with \`dsh-hc ls\` and take one over with \`hc run … ${quoted} attach <id|title>\`.
+command: ${quoted} new
+---
+`)
+  process.stdout.write(`${file}\n`)
+}
+
+// Terminal columns a string takes: East Asian wide and full-width characters take two.
+const WIDE = /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6\u{1F300}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u
+const width = s => [...s].reduce((w, ch) => w + (WIDE.test(ch) ? 2 : 1), 0)
+const pad = (s, n) => s + ' '.repeat(Math.max(0, n - width(s)))
+
+function table(items) {
+  if (!items.length) return 'no DSH sessions in that period\n'
+  const rows = items.map(i => [
+    i.sessionId.replace(/^session-/, '').slice(0, 8),
+    new Date(i.updatedAt).toISOString().slice(0, 16).replace('T', ' '),
+    i.running ? 'running' : '',
+    i.terminal || '',
+    i.title || '(untitled)',
+    i.cwd || '',
+  ])
+  const head = ['ID', 'UPDATED', 'STATE', 'HC', 'TITLE', 'FOLDER']
+  const widths = head.map((h, c) => Math.max(width(h), ...rows.map(r => width(r[c]))))
+  return [head, ...rows].map(r => r.map((v, c) => (c === r.length - 1 ? v : pad(v, widths[c]))).join('  ')).join('\n') + '\n'
+}
+
+const [command, ...args] = process.argv.slice(2)
+const flag = name => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined }
+
+switch (command) {
+  case 'new':
+    terminal({ mode: 'new', cwd: process.cwd() })
+    break
+  case 'attach': {
+    const session = flag('--session')
+    const query = session ?? args.filter(a => !a.startsWith('--')).join(' ')
+    if (!query) fail('usage: dsh-hc attach <session id | title>', 2)
+    terminal({ mode: 'attach', ...(session ? { session } : { query }), auto: args.includes('--auto') })
+    break
+  }
+  case 'ls': {
+    const days = Number(flag('--days') ?? 7)
+    request({ mode: 'ls', days }).then(
+      reply => process.stdout.write(args.includes('--json') ? `${JSON.stringify(reply.items, null, 2)}\n` : table(reply.items)),
+      error => fail(error.message),
+    )
+    break
+  }
+  case 'install-template':
+    installTemplate()
+    break
+  default:
+    fail('usage: dsh-hc new | attach <session id | title> | ls [--days N] [--json] | install-template', 2)
+}

package/render.js

@@ -0,0 +1,150 @@
+// Turn DSH session events into terminal text, laid out the way TUI agents (Claude Code, pi) show
+// a conversation: the prompt, streamed assistant text, one line per tool call with its result, and
+// a closing line per turn. Pure functions plus a small per-session state object.
+
+const CSI = '\x1b['
+export const style = {
+  bold: s => `${CSI}1m${s}${CSI}22m`,
+  dim: s => `${CSI}2m${s}${CSI}22m`,
+  red: s => `${CSI}31m${s}${CSI}39m`,
+  green: s => `${CSI}32m${s}${CSI}39m`,
+  yellow: s => `${CSI}33m${s}${CSI}39m`,
+  cyan: s => `${CSI}36m${s}${CSI}39m`,
+}
+
+/** Raw-mode terminals need CR LF. */
+export const crlf = s => s.replace(/\r?\n/g, '\r\n')
+export const oneLine = (s, n = 120) => String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, n)
+const clip = (s, n) => (s.length > n ? `${s.slice(0, Math.max(1, n - 1))}…` : s)
+const indent = (s, pad) => s.replace(/\n/g, `\n${pad}`)
+const b64 = s => Buffer.from(s).toString('base64')
+
+/** OSC 7501 Program Status Protocol report. */
+export function osc({ state, msg, kind }, title) {
+  const parts = [`state=${state}`, 'app=dsh']
+  if (title) parts.push(`title=${b64(title)}`)
+  if (msg) parts.push(`msg=${b64(msg)}`)
+  if (kind) parts.push(`kind=${kind}`)
+  return `\x1b]7501;${parts.join(':')}\x1b\\`
+}
+
+const textOf = content => (Array.isArray(content) ? content : [])
+  .filter(p => p?.type === 'text' && typeof p.text === 'string')
+  .map(p => p.text)
+  .join('\n')
+
+/** The most telling argument of a tool call, for its one-line summary. */
+function toolSummary(args) {
+  if (typeof args === 'string') {
+    try { args = JSON.parse(args) } catch { return oneLine(args) }
+  }
+  if (!args || typeof args !== 'object') return ''
+  for (const key of ['description', 'command', 'file_path', 'path', 'pattern', 'query', 'url', 'name', 'prompt']) {
+    if (typeof args[key] === 'string' && args[key].trim()) return oneLine(args[key])
+  }
+  if (Array.isArray(args.questions)) return oneLine(args.questions.map(q => q?.question).join(' / '))
+  return ''
+}
+
+function seconds(ms) {
+  const s = Math.max(0, Math.round(ms / 1000))
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`
+}
+
+/** Per-session rendering state: which steps were streamed live, and when each turn started. */
+export class Renderer {
+  constructor() {
+    this.cols = 100
+    this.streamed = new Set()
+    this.turnStarted = new Map()
+    this.inText = false
+  }
+
+  /** A durable session event (live or replayed from history) to terminal text. */
+  event(event) {
+    const data = event?.data ?? {}
+    switch (event?.type) {
+      case 'turn/start':
+        this.turnStarted.set(data.turn, event.time ?? Date.now())
+        return ''
+      case 'user/message': {
+        if (data.source?.kind !== 'user') return ''
+        const text = textOf(data.content).trim()
+        return text ? crlf(`\n${style.bold('❯')} ${indent(text, '  ')}\n`) : ''
+      }
+      case 'assistant/message': {
+        // Streamed already, even if the stream began before this renderer existed (a reload).
+        if (this.inText) { this.inText = false; return '\r\n' }
+        if (this.streamed.has(`${data.turn}:${data.step}`)) return ''
+        const text = textOf(data.message?.content).trim()
+        return text ? crlf(`${style.cyan('⏺')} ${indent(text, '  ')}\n`) : ''
+      }
+      case 'tool/call': {
+        const summary = toolSummary(data.arguments)
+        const head = `${style.cyan('⏺')} ${style.bold(data.name ?? 'tool')}`
+        return crlf(`${head}${summary ? ` ${style.dim(clip(summary, this.cols - (data.name?.length ?? 4) - 4))}` : ''}\n`)
+      }
+      case 'tool/result': {
+        const message = data.message ?? {}
+        const lines = textOf(message.content).split('\n').map(l => l.trimEnd())
+          .filter(l => l.trim() && !/^\[(stdout|stderr)\]$/.test(l.trim()))
+        const failed = message.isError || data.error !== undefined
+        let first = lines[0] ?? (failed ? 'failed' : 'done')
+        first = clip(first.trim(), this.cols - 16)
+        const more = lines.length > 1 ? style.dim(` (+${lines.length - 1} lines)`) : ''
+        return crlf(`  ${style.dim('⎿')} ${failed ? style.red(first) : style.dim(first)}${more}\n`)
+      }
+      case 'turn/end': {
+        const reason = data.reason ?? { kind: 'completed' }
+        const started = this.turnStarted.get(data.turn)
+        this.turnStarted.delete(data.turn)
+        const took = started !== undefined ? ` · ${seconds((event.time ?? Date.now()) - started)}` : ''
+        if (reason.kind === 'completed' || reason.kind === 'max-tokens') return crlf(`${style.dim(`✻ done${took}`)}\n`)
+        if (reason.kind === 'aborted') return crlf(`${style.yellow('✻ cancelled')}${style.dim(took)}\n`)
+        if (reason.kind === 'interrupted') return ''
+        return crlf(`${style.red(`✻ error: ${oneLine(reason.error?.message ?? reason.kind, 200)}`)}\n`)
+      }
+      default:
+        return ''
+    }
+  }
+
+  /** A live assistant-stream frame to terminal text (text deltas only). */
+  stream(frame) {
+    if (frame?.type === 'start') {
+      this.step = `${frame.turn}:${frame.step}`
+      this.inText = false
+      return ''
+    }
+    if (frame?.type === 'chunk' && frame.chunk?.type === 'text-delta' && frame.chunk.text) {
+      const lead = this.inText ? '' : `${style.cyan('⏺')} `
+      this.inText = true
+      if (this.step) this.streamed.add(this.step)
+      return lead + crlf(frame.chunk.text.replace(/\n/g, '\n  '))
+    }
+    if (frame?.type === 'end') {
+      const close = this.inText ? '\r\n' : ''
+      this.inText = false
+      return close
+    }
+    return ''
+  }
+
+  /** The question an approval or ask_user_question puts to whoever answers first. */
+  approval(req) {
+    const what = `${req.toolName}${req.reason ? `: ${req.reason}` : ''}`
+    return crlf(`${style.yellow('⏸ permission')} ${oneLine(what, 400)}\n`
+      + `  ${style.dim('answer here (y = allow once, n = reject) or in DSH Desktop')}\n`)
+  }
+
+  question(q, index, total) {
+    const options = q.options ?? []
+    let s = `${style.yellow(`⏸ question ${index + 1}/${total}`)} ${q.header ? `${q.header}: ` : ''}${q.question}\n`
+    if (q.detail) s += `  ${q.detail}\n`
+    options.forEach((o, n) => { s += `  ${n + 1}. ${o.label}${o.description ? style.dim(` — ${o.description}`) : ''}\n` })
+    s += `  ${style.dim(options.length
+      ? `answer here (${q.multiSelect ? 'numbers like 1,3' : 'a number'}, your own text, or - to skip) or in DSH Desktop`
+      : 'answer here (your text, or - to skip) or in DSH Desktop')}\n`
+    return crlf(s)
+  }
+}