@iamlbccc/tdxd 1.1.0

package/README.md

@@ -0,0 +1,49 @@
+# tdxd
+
+TDX-Daemon — [Paperclip](https://paperclip.ing) TDX-Adapter 的远端守护进程：以「会话即进程」驱动 ACP Agent（opencode），提供会话续接、人在环权限审批、usage 计量回填；随包附带跨平台实例管理器 `tdxd-ctl`。
+
+## 安装
+
+```bash
+npm install -g @iamlbccc/tdxd        # Node.js >= 24
+```
+
+## 快速开始
+
+```bash
+# 1. 初始化一个 Agent 实例（交互式向导：config + token + workspace 骨架）
+tdxd-ctl init my-agent
+
+# 2. 启动并自检（health=200 即就绪）
+tdxd-ctl start my-agent
+tdxd-ctl status my-agent
+
+# 3. 在 Paperclip 平台 UI hire Agent（选 TDX-Adapter），粘贴 init 打印的 endpoint/token
+```
+
+实例布局（agent-first，每 Agent 一套内聚目录）：
+
+```
+$TDXD_HOME（默认 ~/.tdx）/agents/<name>/
+├── config.json     # 端口/workspace/权限白名单/模型价目
+├── secret.env      # 共享 token + 平台回调 key（600）
+├── log/tdxd.log
+└── run/pid
+```
+
+## 命令
+
+```
+tdxd-ctl init <name>        交互式脚手架（--yes 可脚本化）
+tdxd-ctl list               实例一览
+tdxd-ctl start|stop|restart|status  [name|all]
+```
+
+## 运行前提
+
+- Node.js >= 24；目标 Agent 的 ACP 运行时（如 [opencode](https://opencode.ai)）
+- 一台可达的 Paperclip 平台（TDX-Adapter 热装）
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,29 @@
+{
+  "name": "TDX-问答助手",
+  "note": "TDXD_NAME / TDXD_PORT / TDXD_TOKEN / TDXD_WORKSPACE / TDXD_COMMAND / TDXD_PAPERCLIP_URL / TDXD_PAPERCLIP_KEY 环境变量优先",
+  "port": 18200,
+  "bind": "127.0.0.1",
+  "token": "CHANGE_ME_long_random",
+  "workspace": "/home/iamlbccc/wsp/agentX/workspaces/tdx-assistant",
+  "command": "/home/iamlbccc/.opencode/bin/opencode",
+  "commandArgs": [],
+  "idleTtlMin": 10,
+  "maxSessions": 5,
+  "promptTimeoutMs": 360000,
+  "paperclip": {
+    "url": "http://127.0.0.1:3100",
+    "agentKey": "sk_pap_xxx（POST /api/agents/{id}/keys 铸造后填入）"
+  },
+  "permissions": {
+    "default": "deny",
+    "allow": [
+      {
+        "command": "^(cat|head|tail|ls|grep|jq|echo)\\b"
+      },
+      {
+        "command": "^curl +.*(\\\\$PAPERCLIP_API_URL|\\\\$PAPERCLIP_API_BASE|127\\\\.0\\\\.0\\\\.1:3100)"
+      }
+    ],
+    "_doc": "示例白名单：按段匹配（;|&&||||换行切分），全段命中才放行；deny 时向 issue 发审批评论（askComment:false 可关）"
+  }
+}

package/lib/acp.mjs

@@ -0,0 +1,230 @@
+// ACP 统一驱动：JSON-RPC(stdio) 传输层 + ACP 核心状态机 + 能力协商（resume/load 方言）
+// 设计依据：OpenCode 1.18.29 实测（docs/opencode-acp-probe-evidence.log）+ ACP 规范
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/** 桥内部凭据不得泄入 agent 子进程（BUG-06） */
+function sanitizedEnv(extra) {
+  const e = { ...process.env, ...extra };
+  for (const k of Object.keys(e)) if (k.startsWith("TDXD_")) delete e[k];
+  return e;
+}
+
+// envKey 必须覆盖整个 run env（authToken + RUN_ID + TASK_ID…）：
+// 只看 token 会导致进程跨 run 复用时 env 停留在首 run——模型读到旧 PAPERCLIP_RUN_ID，
+// checkout/PATCH 对平台而言是「别的 run」→ 409 → 收尾死循环（TDM-29~32 总根因）
+export const envKeyOf = (env) => env ? createHash("md5").update(JSON.stringify(env)).digest("hex").slice(0, 12) : null;
+
+export class AcpAgent {
+  /**
+   * @param {object} opts
+   * @param {string} opts.command   可执行文件（如 opencode）
+   * @param {string[]} [opts.args]  额外参数（默认 ["acp"]）
+   * @param {string} opts.workspace 会话工作区（--cwd）
+   * @param {object} [opts.env]     注入子进程的环境变量（如 PAPERCLIP_*，随 run 变化）
+   * @param {Array} [opts.mcpServers] 平台下发的 run 作用域 MCP servers（{name,url,token}，随 session 建立）
+   */
+  constructor(opts) {
+    this.command = opts.command;
+    this.args = opts.args ?? ["acp"];
+    this.workspace = opts.workspace;
+    this.env = opts.env ?? null;
+    this.mcpServers = opts.mcpServers ?? [];
+    this.proc = null;
+    this.capabilities = null;
+    this.agentInfo = null;
+    this.resumeMethod = null;      // 协商结果："session/resume" | "session/load" | null
+    this.model = null;            // 会话当前模型（取自 configOptions，随 done 事件上报供计费维度使用）
+    this.pending = new Map();
+    this.nextId = 0;
+    this.onUpdate = null;          // (update) => void  session/update 通知回调
+    this.permissionPolicy = opts.permissionPolicy ?? null;   // (command, params) => "allow" | "deny"
+    this.onPermissionEvent = null; // ({decision, reason, command, requestId}) => void 权限决策回调
+    this.buf = "";
+    this.dead = false;
+  }
+
+  get alive() { return !!this.proc && !this.dead && this.proc.exitCode === null; }
+
+  async start() {
+    if (this.alive) return;
+    this.dead = false;
+    this.proc = spawn(this.command, [...this.args, "--cwd", this.workspace], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: sanitizedEnv(this.env ?? undefined),
+    });
+    this.proc.stdout.setEncoding("utf8");
+    this.proc.stdout.on("data", (d) => this._onStdout(d));
+    this.proc.stderr.setEncoding("utf8");
+    this.proc.stderr.on("data", (d) => {
+      for (const line of String(d).split("\n")) {
+        if (line.trim()) console.error(`[acp:${this.workspace.split("/").pop()}] ${line.slice(0, 200)}`);
+      }
+    });
+    this.proc.on("exit", () => {
+      this.dead = true;
+      const err = new Error("ACP process exited");
+      for (const { rej } of this.pending.values()) rej(err);
+      this.pending.clear();
+    });
+    await this._request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: {} },
+    }, 30_000).then((r) => {
+      this.capabilities = r.agentCapabilities ?? {};
+      this.agentInfo = r.agentInfo ?? {};
+      // 方言协商：优先 sessionCapabilities.resume（OpenCode），次选规范 loadSession→session/load
+      const sc = this.capabilities.sessionCapabilities ?? {};
+      this.resumeMethod = "resume" in sc ? "session/resume"
+        : this.capabilities.loadSession ? "session/load" : null;
+    });
+  }
+
+  /** 平台 MCP server（{name,url,token}）→ ACP mcpServers 形状（OpenCode 方言：type 必填、headers 为 [{name,value}] 数组） */
+  toAcpMcp(list) {
+    return (list ?? this.mcpServers ?? [])
+      .filter((s) => s && s.url)
+      .map((s) => ({
+        name: s.name,
+        type: "http",
+        url: s.url,
+        headers: s.token ? [{ name: "Authorization", value: `Bearer ${s.token}` }] : [],
+      }));
+  }
+
+  async newSession() {
+    await this.start();
+    const r = await this._request("session/new", { cwd: this.workspace, mcpServers: this.toAcpMcp() });
+    this._captureModel(r);
+    return r.sessionId;
+  }
+
+  /** 从 ACP 结果的 configOptions 提取当前模型（如 kimi-for-coding/kimi-for-coding） */
+  _captureModel(result) {
+    try {
+      const opt = (result?.configOptions ?? []).find((o) => o?.id === "model");
+      if (opt?.currentValue) this.model = String(opt.currentValue);
+    } catch { /* 模型提取失败不影响会话 */ }
+  }
+
+  async resumeSession(sessionId) {
+    await this.start();
+    const method = this.resumeMethod ?? "session/resume";
+    const params = { cwd: this.workspace, mcpServers: this.toAcpMcp(), sessionId };
+    const r = await this._request(method, params);
+    this._captureModel(r);
+    return r.sessionId ?? sessionId;
+  }
+
+  /** 发送用户消息并等待终态；流式事件经 onUpdate 回调 */
+  async prompt(sessionId, text) {
+    return this._request("session/prompt", {
+      sessionId,
+      prompt: [{ type: "text", text }],
+    }, DEFAULT_TIMEOUT_MS * 3);
+  }
+
+  async cancel(sessionId) {
+    if (!this.alive) return;
+    this._notify("session/cancel", { sessionId }).catch(() => {});
+  }
+
+  /** 优雅终止：SIGTERM → 宽限 → SIGKILL（进程组语义，Windows 退出为 kill） */
+  stop() {
+    if (!this.proc || this.dead) return;
+    try { this.proc.kill("SIGTERM"); } catch { /* noop */ }
+    const p = this.proc;
+    setTimeout(() => { try { p.kill("SIGKILL"); } catch { /* noop */ } }, 3000).unref?.();
+    this.dead = true;
+  }
+
+  // ---- 内部：JSON-RPC/ndjson 传输 ----
+  _onStdout(d) {
+    this.buf += d;
+    let i;
+    while ((i = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, i).trim();
+      this.buf = this.buf.slice(i + 1);
+      if (!line || line.startsWith("Content-Type")) continue;
+      let msg; try { msg = JSON.parse(line); } catch { continue; }
+      if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+        const p = this.pending.get(msg.id);
+        if (p) {
+          this.pending.delete(msg.id);
+          clearTimeout(p.timer);
+          if (msg.error) p.rej(new Error(`ACP ${p.method}: ${msg.error.message}`));
+          else p.res(msg.result);
+        }
+      } else if (msg.method === "session/update") {
+        this.onUpdate?.(msg.params?.update);
+      } else if (msg.method !== undefined && msg.id !== undefined) {
+        // 服务端→客户端请求（如 session/request_permission）：必须应答，否则 opencode 永久等待（BUG-13）
+        this._onServerRequest(msg);
+      }
+    }
+  }
+
+  /** 服务端请求分发：权限请求按策略应答；未知请求回 -32601 防止对端悬挂 */
+  _onServerRequest(msg) {
+    if (msg.method === "session/request_permission") {
+      const decision = this._decidePermission(msg.params ?? {});
+      // ACP 响应形状（opencode 实测）：{outcome:{outcome:"selected",optionId}} | {outcome:{outcome:"cancelled"}}
+      const result = decision.optionId
+        ? { outcome: { outcome: "selected", optionId: decision.optionId } }
+        : { outcome: { outcome: "cancelled" } };
+      try {
+        this._write({ jsonrpc: "2.0", id: msg.id, result });
+      } catch (e) {
+        console.error(`[acp] permission 应答写入失败: ${e.message}`);
+      }
+      try { this.onPermissionEvent?.(decision.event); } catch { /* 监听器异常不得影响 agent */ }
+      return;
+    }
+    console.error(`[acp] 未处理的服务端请求 ${msg.method}(id=${msg.id}) → -32601`);
+    try {
+      this._write({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `tdxd: method not handled: ${msg.method}` } });
+    } catch { /* noop */ }
+  }
+
+  /** 依据 permissionPolicy 计算 allow/deny 与所选 optionId */
+  _decidePermission(params) {
+    const options = Array.isArray(params.options) ? params.options : [];
+    const allowOpt = options.find((o) => o?.optionId === "once" || /allow_once/i.test(String(o?.kind ?? "")));
+    const denyOpt = options.find((o) => /reject|deny|cancel/i.test(`${o?.optionId ?? ""} ${o?.kind ?? ""}`));
+    const command = String(params.toolCall?.rawInput?.command ?? params.toolCall?.title ?? "");
+    const verdict = this.permissionPolicy ? this.permissionPolicy(command, params) : "deny";
+    const meta = { command, requestId: params.toolCall?.toolCallId ?? null };
+    if (verdict === "allow" && allowOpt) {
+      return { optionId: allowOpt.optionId, event: { decision: "allow", reason: "policy", ...meta } };
+    }
+    return {
+      optionId: denyOpt?.optionId ?? null,
+      event: { decision: "deny", reason: verdict === "allow" ? "no-allow-option" : "policy", ...meta },
+    };
+  }
+
+  _write(obj) {
+    if (!this.alive) throw new Error("ACP process not running");
+    this.proc.stdin.write(JSON.stringify(obj) + "\n");
+  }
+
+  _notify(method, params) {
+    this._write({ jsonrpc: "2.0", method, params });
+    return Promise.resolve();
+  }
+
+  _request(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const id = this.nextId++;
+    return new Promise((res, rej) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        rej(new Error(`ACP ${method} timeout`));
+      }, timeoutMs);
+      this.pending.set(id, { res, rej, method, timer });
+      try { this._write({ jsonrpc: "2.0", id, method, params }); }
+      catch (e) { clearTimeout(timer); this.pending.delete(id); rej(e); }
+    });
+  }
+}

package/lib/perm.mjs

@@ -0,0 +1,132 @@
+// 权限策略引擎（纯函数，供 tdxd 与测试复用）：
+// - 切分器：引号内/heredoc 正文内不切分；; && || | 换行 为段边界
+// - 命令替换（$(...) 与反引号）内容递归过同套规则（深度上限 2）
+// - 授权按「核心命令」（剥环境变量前缀/重定向符号后的 首命令+首路径型操作数）匹配，
+//   使 模型变体重试（加 flag、加 ; echo 等无害段）可命中同一授权
+import { createHash } from "node:crypto";
+
+export function stripEnvPrefix(seg) {
+  return seg.replace(/^[A-Za-z_][A-Za-z0-9_]*=(("[^"]*")|('[^']*')|(\S+))\s+/g, "");
+}
+
+/** 把 shell 命令切成顶层段，并抽取命令替换内容（引号/heredoc 感知） */
+export function parseShell(cmd, depth = 0) {
+  const s = String(cmd);
+  const segments = [];
+  const subs = [];
+  let cur = "";
+  let i = 0;
+  let heredocDelim = null;
+  let quoteCh = null;
+  const flushSeg = () => { const t = cur.trim(); if (t) segments.push(t); cur = ""; };
+  while (i < s.length) {
+    const c = s[i];
+    if (heredocDelim !== null) {
+      cur += c;
+      if (c === "\n") {
+        const lineStart = i + 1;
+        const nl = s.indexOf("\n", lineStart);
+        const line = s.slice(lineStart, nl === -1 ? s.length : nl).trim();
+        if (line === heredocDelim) { heredocDelim = null; i = nl === -1 ? s.length : nl; continue; }
+      }
+      i++;
+      continue;
+    }
+    if (quoteCh) {
+      if (c === "\\" && quoteCh === '"') { cur += c + (s[i + 1] ?? ""); i += 2; continue; }
+      if (c === quoteCh) quoteCh = null;
+      cur += c; i++; continue;
+    }
+    if (c === "'" || c === '"') { quoteCh = c; cur += c; i++; continue; }
+    if (c === "\\") { cur += c + (s[i + 1] ?? ""); i += 2; continue; }
+    if (c === "<" && s[i + 1] === "<") {
+      const m = /^<<-?\s*(?:'([A-Za-z0-9_]+)'|"([A-Za-z0-9_]+)"|([A-Za-z0-9_]+))/.exec(s.slice(i));
+      if (m) {
+        heredocDelim = m[1] ?? m[2] ?? m[3];
+        cur += m[0]; i += m[0].length; continue;
+      }
+    }
+    if (c === "$" && s[i + 1] === "(") {
+      let d = 1, j = i + 2;
+      while (j < s.length && d > 0) { if (s[j] === "(") d++; else if (s[j] === ")") d--; j++; }
+      const inner = s.slice(i + 2, j - 1);
+      if (depth < 2 && inner.trim()) subs.push(inner);
+      cur += s.slice(i, j); i = j; continue;
+    }
+    if (c === "`") {
+      const j = s.indexOf("`", i + 1);
+      const inner = j === -1 ? "" : s.slice(i + 1, j);
+      if (depth < 2 && inner.trim()) subs.push(inner);
+      const consumed = j === -1 ? s.length : j + 1;
+      cur += s.slice(i, consumed); i = consumed; continue;
+    }
+    if (c === ";" || c === "\n" || c === "|" || c === "\r") {
+      const two = s.slice(i, i + 2);
+      if (two === "&&" || two === "||" || two === "|&") { flushSeg(); i += 2; continue; }
+      flushSeg(); i += c === "\r" && s[i + 1] === "\n" ? 2 : 1; continue;
+    }
+    cur += c; i++;
+  }
+  flushSeg();
+  return { segments, subs };
+}
+
+/** 段核心：剥环境变量前缀与重定向符号，取 首命令+首个非 flag 操作数 */
+export function coreOfSegment(segRaw) {
+  const seg = stripEnvPrefix(segRaw);
+  const toks = seg.match(/(?:[^\s"']|"[^"]*"|'[^']*')+/g) ?? [];
+  const first = (toks[0] ?? "").replace(/^['"]|['"]$/g, "");
+  let operand = "";
+  for (let k = 1; k < toks.length; k++) {
+    const t = toks[k].replace(/^['"]|['"]$/g, "");
+    if (/^(>>|>|<|2>|&>)$/.test(t) || t === "2>&1") continue;
+    if (t.startsWith("-")) continue;
+    operand = t; break;
+  }
+  return operand ? `${first} ${operand}` : first;
+}
+
+export const permKeyOf = (core) => createHash("sha1").update(String(core).trim()).digest("hex").slice(0, 8);
+
+/** 生成命令评估器：每段须命中白名单（剥 env 前缀后匹配）或已授权核心；命令替换递归 */
+export function makeEvaluator(allowRes, defaultMode) {
+  const segAllowed = (seg) => {
+    if (defaultMode === "allow") return true;
+    const stripped = stripEnvPrefix(seg);
+    return allowRes.some((re) => re.test(stripped));
+  };
+  return function evalCommand(cmd, isCoreGranted, depth = 0) {
+    const { segments, subs } = parseShell(cmd, depth);
+    if (!segments.length && !subs.length) return "deny";
+    for (const seg of segments) {
+      if (assignmentOnly(seg)) continue; // 纯赋值段：可执行内容在 $()/反引号内，已递归校验
+      if (isCoreGranted && isCoreGranted(permKeyOf(coreOfSegment(seg)))) continue;
+      if (!segAllowed(seg)) return "deny";
+    }
+    for (const inner of subs) {
+      if (evalCommand(inner, isCoreGranted, depth + 1) === "deny") return "deny";
+    }
+    return "allow";
+  };
+}
+
+/** 移除 $(...)（括号配平）与反引号跨度 */
+function removeSubSpans(s) {
+  let out = "", i = 0;
+  while (i < s.length) {
+    if (s[i] === "$" && s[i + 1] === "(") {
+      let d = 1, j = i + 2;
+      while (j < s.length && d > 0) { if (s[j] === "(") d++; else if (s[j] === ")") d--; j++; }
+      out += " "; i = j; continue;
+    }
+    if (s[i] === "`") { const j = s.indexOf("`", i + 1); out += " "; i = j === -1 ? s.length : j + 1; continue; }
+    out += s[i++];
+  }
+  return out;
+}
+
+/** 纯赋值段判定：去掉替换跨度后只剩 NAME=value 序列（如 BODY=$(cat <<'MD'…)） */
+function assignmentOnly(seg) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*=/.test(seg)) return false;
+  return removeSubSpans(seg).replace(/^[A-Za-z_][A-Za-z0-9_]*=\S*\s+/g, "").replace(/^[A-Za-z_][A-Za-z0-9_]*=\S*$/, "").trim() === "";
+}

package/lib/router.mjs

@@ -0,0 +1,162 @@
+// SessionRouter（D13 会话即进程）：
+// conversationKey → { AcpAgent 进程, sessionId, lastActive, envKey }
+// · 新对话 → spawn + session/new
+// · 续接（进程在）→ 复用；进程亡但有 nativeSessionId → respawn + resume
+// · run 凭据变化（envKey 不同）→ 等锁后 respawn + resume（保证子进程 env 新鲜，不打断在途 run）
+// · **同会话互斥（BUG-03）**：conversation 级独占锁——acquire 即持锁，release（run 结束）才解锁；
+//   后到 run 排队等待，超时（busyWaitTimeoutMs，默认 8min > prompt 超时 6min）失败返回。
+//   锁挂在 conversation 而非会话条目上：会话未建立时同样互斥（并发首建竞态）。
+// · 空闲 TTL → 进程回收（sessionId 交由平台 sessionParams 留档）
+// · 并发上限闸（超过即排队等待；创建失败即回收，不占闸——BUG-04）
+import { AcpAgent, envKeyOf } from "./acp.mjs";
+
+export class SessionRouter {
+  constructor(opts) {
+    this.command = opts.command;
+    this.args = opts.args;
+    this.workspace = opts.workspace;
+    this.idleTtlMs = opts.idleTtlMs ?? 10 * 60_000;   // 默认 10 分钟
+    this.maxSessions = opts.maxSessions ?? 5;
+    this.busyWaitTimeoutMs = opts.busyWaitTimeoutMs ?? 8 * 60_000; // 同会话忙等上限
+    this.permissionPolicy = opts.permissionPolicy ?? null;  // 透传给 AcpAgent（tdxd 提供）
+    this.sessions = new Map();     // key → { agent, sessionId, lastActive, envKey }
+    this.waiters = [];             // maxSessions 全局闸等待
+    this.locks = new Set();        // 持有 conversation 锁的 key（acquire→release）
+    this.lockWaiters = new Map();  // key → [wake,...] 锁等待队列
+    this._reaper = setInterval(() => this._reap(), 60_000);
+    this._reaper.unref?.();
+  }
+
+  /** 取得（或建立）一个可用的 {agent, sessionId}；返回即持有该 conversation 的锁，run 结束须调 release() */
+  async acquire(conversationKey, nativeSessionId, onUpdate, env = null, mcpServers = []) {
+    const key = envKeyOf(env);
+    await this._lock(conversationKey); // 同会话互斥：先于一切（含凭据检查——不打断在途 run）
+    try {
+      let entry = this.sessions.get(conversationKey);
+      if (entry && entry.agent.alive && entry.envKey === key) {
+        await this._waitSlot();
+        // BUG-12：重派 acquire 不再刷新 lastActive（防 idleTTL 无限滑动喂僵尸）；
+        // 仅真实流事件（_touchWrap）与 release（run 真实结束）刷新
+        entry.agent.onUpdate = this._touchWrap(entry, onUpdate);
+        return { entry, sessionId: entry.sessionId, resumed: false };
+      }
+
+      // 凭据变化或进程亡 → 回收旧进程，重建（resume 续接）
+      if (entry) { entry.agent.stop(); this.sessions.delete(conversationKey); }
+
+      await this._waitSlot();
+      let agent = new AcpAgent({ command: this.command, args: this.args, workspace: this.workspace, env, mcpServers, permissionPolicy: this.permissionPolicy });
+      agent.onUpdate = onUpdate;
+      let sessionId;
+      let resumed = false;
+      if (nativeSessionId) {
+        try {
+          sessionId = await agent.resumeSession(nativeSessionId);
+          resumed = true;
+        } catch (e) {
+          // resume 失败（会话不存在/方言不匹配）→ 退化为新会话
+          agent.stop();
+          const fresh = new AcpAgent({ command: this.command, args: this.args, workspace: this.workspace, env, mcpServers, permissionPolicy: this.permissionPolicy });
+          fresh.onUpdate = onUpdate;
+          let sid;
+          try {
+            sid = await fresh.newSession();
+          } catch (e2) {
+            fresh.stop(); // BUG-04：创建失败即回收，不留僵尸条目
+            throw e2;
+          }
+          const freshEntry = { agent: fresh, sessionId: sid, lastActive: Date.now(), envKey: key };
+          freshEntry.agent.onUpdate = this._touchWrap(freshEntry, onUpdate);
+          this.sessions.set(conversationKey, freshEntry);
+          return { entry: freshEntry, sessionId: sid, resumed: false, note: `resume 失败已重建: ${e.message}` };
+        }
+      } else {
+        try {
+          sessionId = await agent.newSession();
+        } catch (e) {
+          agent.stop(); // BUG-04：创建失败即回收
+          throw e;
+        }
+      }
+      const newEntry = { agent, sessionId, lastActive: Date.now(), envKey: key };
+      newEntry.agent.onUpdate = this._touchWrap(newEntry, onUpdate);
+      this.sessions.set(conversationKey, newEntry);
+      return { entry: newEntry, sessionId, resumed };
+    } catch (e) {
+      this._unlock(conversationKey); // 失败路径必须放锁并唤醒下一个
+      throw e;
+    }
+  }
+
+  /** BUG-12：lastActive 仅由真实流事件刷新——包装 onUpdate，事件到达即 touch */
+  _touchWrap(entry, onUpdate) {
+    return (u) => { entry.lastActive = Date.now(); onUpdate?.(u); };
+  }
+
+  /** run 结束：解锁 conversation 并唤醒等待者 */
+  release(conversationKey) {
+    const entry = this.sessions.get(conversationKey);
+    if (entry) entry.lastActive = Date.now();
+    this._unlock(conversationKey);
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+
+  /** 丢弃会话条目（BUG-11）：prompt 超时/异常后调用——stop 进程 + 删条目，
+   *  下轮重派走 respawn+resume 而非复用僵尸；nativeSessionId 由平台留档，续接不受影响。 */
+  discard(conversationKey) {
+    const entry = this.sessions.get(conversationKey);
+    if (entry) { entry.agent.stop(); this.sessions.delete(conversationKey); }
+    this.lockWaiters.delete(conversationKey);
+    this._unlock(conversationKey);
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+
+  _waitSlot() {
+    if (this.sessions.size < this.maxSessions) return Promise.resolve();
+    return new Promise((res) => this.waiters.push(res));
+  }
+
+  /** conversation 锁：忙则入队，release 唤醒一个（唤醒即同步转交锁，防闯入）；超时拒绝 */
+  async _lock(conversationKey) {
+    if (!this.locks.has(conversationKey)) { this.locks.add(conversationKey); return; }
+    await new Promise((resolve, reject) => {
+      let queue = this.lockWaiters.get(conversationKey);
+      if (!queue) { queue = []; this.lockWaiters.set(conversationKey, queue); }
+      const timer = setTimeout(() => {
+        const idx = queue.indexOf(wake);
+        if (idx >= 0) queue.splice(idx, 1);
+        reject(new Error(`tdxd: 同会话忙等超时（${Math.round(this.busyWaitTimeoutMs / 1000)}s），在途 run 未释放: ${conversationKey}`));
+      }, this.busyWaitTimeoutMs);
+      const wake = () => { clearTimeout(timer); this.locks.add(conversationKey); resolve(); };
+      queue.push(wake);
+    });
+  }
+
+  _unlock(conversationKey) {
+    this.locks.delete(conversationKey);
+    const q = this.lockWaiters.get(conversationKey);
+    const wake = q?.shift();
+    if (wake) wake(); // wake 内部同步重新加锁（转交）
+  }
+
+  _reap() {
+    const now = Date.now();
+    for (const [key, entry] of this.sessions) {
+      if (now - entry.lastActive > this.idleTtlMs) {
+        entry.agent.stop();
+        this.sessions.delete(key);
+        this.lockWaiters.delete(key);
+      }
+    }
+  }
+
+  stopAll() {
+    clearInterval(this._reaper);
+    for (const entry of this.sessions.values()) entry.agent.stop();
+    this.sessions.clear();
+    this.lockWaiters.clear();
+    this.locks.clear();
+  }
+}

package/lib/tpl.mjs

@@ -0,0 +1,77 @@
+// init 脚手架模板：实例 config / workspace 骨架（AGENTS.md 角色模板 + opencode.json）
+
+export function configTpl({ name, displayName, port, workspace, model, url }) {
+  return `${JSON.stringify({
+    name: displayName,
+    port,
+    bind: "0.0.0.0",
+    workspace,
+    command: "opencode",
+    commandArgs: [],
+    idleTtlMin: 10,
+    maxSessions: 5,
+    promptTimeoutMs: 360000,
+    paperclip: { url },
+    permissions: {
+      default: "deny",
+      allow: [
+        { command: "^(cat|head|tail|ls|stat|file|wc|grep|rg|find|du|df|free|uname|whoami|id|date|nproc|which|env|printenv|pwd|ps)\\b" },
+        { command: "^(node|npm|pnpm|npx|python3?|pip3?|java|javac|mvn|go|rustc|cargo|gcc|g\\+\\+|make|cmake|git)( +--version| +version| +-v)$" },
+        { command: "^git +(status|diff|log|show|branch)\\b" },
+        { command: "^curl +.*(\\\\$PAPERCLIP_API_URL|\\\\$PAPERCLIP_API_BASE|127\\\\.0\\\\.0\\\\.1:3100|localhost:3100)" },
+        { command: "^(jq|echo|cd|sleep|mkdir +-p +/tmp/opencode)\\b" },
+      ],
+    },
+    pricing: {
+      models: {
+        [model]: {
+          inputPerMillion: 0.6,
+          cachedReadPerMillion: 0.15,
+          outputPerMillion: 2.5,
+          _doc: "占位价（USD/百万token）：请按模型官方定价校准",
+        },
+      },
+    },
+  }, null, 2)}\n`;
+}
+
+export function opencodeJsonTpl(model) {
+  return `${JSON.stringify({ $schema: "https://opencode.ai/config.json", model }, null, 2)}\n`;
+}
+
+const PERSONAS = {
+  manager: `# {NAME}
+
+你是团队负责人（Manager）。收到任务时：
+
+- 先判断：亲自做、拆分给合适成员、还是需要澄清——不确定就到任务里提问，不要猜
+- 拆分时建子任务（子任务写清背景/验收标准/依赖），设置好阻塞关系再分派
+- 跟踪进度：关注子任务状态，全部完成后汇总收尾、更新父任务
+- 输出简洁：状态行 + 要点列表，明确"已完成/待办/谁负责"
+`,
+  coder: `# {NAME}
+
+你是开发工程师。收到任务时：
+
+- 先读相关代码再动手；改动遵循仓库现有风格与约定
+- 改完必须验证（跑最窄的相关测试/编译），验证不了要明说
+- 提交信息简洁；在任务评论里留下：改了什么、为什么、如何验证
+- 发现超出本任务的问题：记录，不擅自扩大改动面
+`,
+  qa: `# {NAME}
+
+你是测试工程师。收到任务时：
+
+- 明确被测对象与验收标准；先设计用例覆盖正常/边界/异常路径
+- 如实报告：通过/失败逐条列出，失败附复现步骤与期望结果
+- 不掩盖问题，不为了"通过"放宽标准
+`,
+  blank: `# {NAME}
+
+（在此描述该 Agent 的角色职责与工作规范。）
+`,
+};
+
+export function agentsMdTpl(persona, name) {
+  return (PERSONAS[persona] ?? PERSONAS.blank).replaceAll("{NAME}", name);
+}