@mingmaple/dsh-handover 0.9.22 → 1.0.0

package/src/tools/ho_workspace.mjs

@@ -1,15 +1,18 @@
-/** ho_workspace —— 工作区生命周期：list / create / delete / init（首次建体系）＋ 全局根目录迁移。 */
+/** ho_workspace —— 工作区生命周期：list / create / delete / init / scaffold / migrate（旧体系迁移）＋ 全局根目录迁移。 */
 import fs from 'node:fs';
 import { nameOf } from '../lib/names.mjs';
 import path from 'node:path';
+import { pathKey } from '../lib/pathkey.mjs';
 import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
 import { workspaceRows } from '../lib/registry.mjs';
 import { createGlobalWorkspace, ensureScaffold } from '../lib/scaffold.mjs';
+import { legacyInfo, migrateLegacyDocmaps } from '../lib/legacy.mjs';
+import { syncGlobalRefs } from '../lib/system.mjs';
 import { probeMove, startMove, moveStatus, cleanupOld, stageSwitch, repairLink, stageRetarget } from '../lib/mover.mjs';
 import { currentRoot } from '../lib/api.mjs';
 
-const BAD = '不能删除「全局」工作区（那是管理会话的家）。';
+const BAD = '不能删除「全局」工作区：该工作区为管理会话所在工作区。';
 
 function gb(n) {
   const v = Number(n) || 0;
@@ -29,7 +32,7 @@ function renderProbe(p) {
   if (p.freeBytes !== null && p.freeBytes !== undefined) out.push('  目标盘可用  ' + gb(p.freeBytes));
   for (const w of p.warnings || []) out.push('  注意：' + w);
   for (const x of p.problems || []) out.push('  未通过：' + x);
-  if (p.ok) out.push('提示：复制完会生成切换脚本；切换那一步需要**完全退出 DSH** 再跑（源目录被占用）。');
+  if (p.ok) out.push('提示：复制完成后生成切换脚本；切换步骤须完全退出 DSH 后再执行（源目录被占用）。');
   return out.join(NL);
 }
 
@@ -37,7 +40,7 @@ export function pmWorkspaceTool(env) {
   return {
     name: nameOf('workspace'),
     description:
-      '工作区：init 首次建全局体系、scaffold 补齐缺失目录与说明、list、create、delete、move-* 搬整个全局根目录。删除只删注册。',
+      '工作区：init 首次建立全局体系、scaffold 补齐缺失目录与说明、migrate 旧体系迁移、list、create、delete、move-* 迁移整个全局根目录。删除只删注册。',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -45,18 +48,18 @@ export function pmWorkspaceTool(env) {
       properties: {
         action: {
           type: 'string',
-          enum: ['init', 'scaffold', 'list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
-          description: 'init / scaffold / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
+          enum: ['init', 'scaffold', 'migrate', 'list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
+          description: 'init / scaffold / migrate / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
         },
-        parent: { type: 'string', description: 'init 用：目标父目录绝对路径（不存在会创建）；全局根建在它里面' },
-        name: { type: 'string', description: 'init 用：全局根目录名，默认 _Workspace' },
-        register: { type: 'boolean', description: 'init 用：建好后顺带注册为工作区（默认 false）' },
-        path: { type: 'string', description: 'create 用：目录绝对路径；默认要求已存在，ensure=true 时自动创建' },
-        title: { type: 'string', description: 'create、init 用：工作区显示标题（init 默认「全局」）' },
-        ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（默认 false，不替你建目录）' },
-        workspace: { type: 'string', description: 'delete 用：工作区 id、标题、路径' },
-        to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动建）' },
-        confirm: { type: 'boolean', description: 'move-cleanup 用：true 才真的删旧备份' },
+        parent: { type: 'string', description: 'init 用：目标父目录的绝对路径（不存在时创建）；全局根建于其中' },
+        name: { type: 'string', description: 'init 用：全局根目录名，缺省 _Workspace' },
+        register: { type: 'boolean', description: 'init 用：建立后一并注册为工作区（缺省 false）' },
+        path: { type: 'string', description: 'create 用：目录绝对路径；缺省要求已存在，ensure=true 时自动创建' },
+        title: { type: 'string', description: 'create、init 用：工作区显示标题（init 缺省「全局」）' },
+        ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（缺省 false，不代建目录）' },
+        workspace: { type: 'string', description: 'delete 用：工作区 id、标题或路径' },
+        to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动创建）' },
+        confirm: { type: 'boolean', description: 'move-cleanup 用：为 true 才实际删除旧备份' },
       },
     },
     output: textOutput(),
@@ -73,20 +76,20 @@ export function pmWorkspaceTool(env) {
           out.push('未建立：' + r.error);
           if (r.root) out.push('目标：' + r.root);
           out.push('');
-          out.push('用法：ho_workspace(action="init", parent="<已存在的目录绝对路径>")。插件只新建、不覆盖。');
+          out.push('用法：ho_workspace(action="init", parent="<已存在的目录绝对路径>")。插件仅新建，不覆盖。');
           return { text: out.join(NL) };
         }
         out.push('已建立全局文件体系：' + r.root);
         out.push('  目录 ' + r.created.length + ' 个：' + r.created.slice(0, 5).join('、') + (r.created.length > 5 ? ' 等' : ''));
-        out.push('  文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（都已存在，未覆盖）'));
-        if (r.existed) out.push('  目标目录原为空目录，直接使用。');
-        if (r.createdParent) out.push('  父目录原本不存在，已创建。');
+        out.push('  文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（均已存在，未覆盖）'));
+        if (r.existed) out.push('  目标原为空目录，直接使用。');
+        if (r.createdParent) out.push('  父目录原不存在，已创建。');
         if (r.skipped.length) out.push('  跳过（已存在、未覆盖）：' + r.skipped.join('、'));
         let registered = null;
         if (args.register === true) {
           if (!reg || typeof reg.create !== 'function') {
             out.push('');
-            out.push('注册未完成：workspaceRegistry 不可用。请把下面这个路径粘进 DSH 的新建工作区窗口：');
+            out.push('注册未完成：workspaceRegistry 不可用。请将下列路径粘贴到 DSH 的新建工作区窗口：');
             out.push('  ' + r.root);
             return { text: out.join(NL) };
           }
@@ -99,7 +102,7 @@ export function pmWorkspaceTool(env) {
           } catch (e) {
             out.push('');
             out.push('注册失败：' + String(e && e.message ? e.message : e));
-            out.push('可把下面这个路径粘进 DSH 的新建工作区窗口：');
+            out.push('可将下列路径粘贴到 DSH 的新建工作区窗口：');
             out.push('  ' + r.root);
             return { text: out.join(NL) };
           }
@@ -107,12 +110,12 @@ export function pmWorkspaceTool(env) {
         out.push('');
         out.push('下一步：');
         if (!registered) {
-          out.push('  1. 注册为工作区：ho_workspace(action="create", path="' + r.root + '", title="全局")，或把该路径粘进 DSH 的新建工作区窗口；');
-          out.push('  2. 新建一个标题含「全局」的会话，闸门、交接体检、会话水位即接入。');
+          out.push('  1. 注册为工作区：ho_workspace(action="create", path="' + r.root + '", title="全局")，或将该路径粘贴到 DSH 的新建工作区窗口；');
+          out.push('  2. 新建一个标题含「全局」的会话，闸门、交接体检与会话水位即接入。');
         } else {
-          out.push('  新建一个标题含「全局」的会话，闸门、交接体检、会话水位即接入。');
+          out.push('  新建一个标题含「全局」的会话，闸门、交接体检与会话水位即接入。');
         }
-        out.push('（也可以在设置页的 dsh-handover 中完成「首次安装」，效果相同。）');
+        out.push('（也可在设置页的 dsh-handover 中完成「首次安装」，效果相同。）');
         return { text: out.join(NL) };
       }
 
@@ -129,7 +132,36 @@ export function pmWorkspaceTool(env) {
         out.push('  新建目录 ' + r.created.length + ' 个：' + (r.created.length ? r.created.join('、') : '（无缺失）'));
         out.push('  新建文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（无缺失）'));
         out.push('  已存在未覆盖 ' + r.skipped.length + ' 个' + (r.skipped.length ? '：' + r.skipped.join('、') : ''));
-        out.push('只新建、不覆盖、不删：已有文件的内容一字未改。');
+        if (r.missingTemplates && r.missingTemplates.length) {
+          out.push('  内置模板缺失 ' + r.missingTemplates.length + ' 个（未写空文件）：' + r.missingTemplates.join('、'));
+        }
+        out.push('只新建，不覆盖、不删除：已有文件的内容未作任何改动。');
+        const legacy = legacyInfo(root);
+        if (legacy.exists) out.push('提示：检测到旧文档定位（' + legacy.dir + '），执行 ho_workspace(action="migrate") 并入体系注册。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'migrate') {
+        const root = currentRoot(env);
+        if (!root) throw new Error('未找到全局根（工作区未接入）');
+        const pre = legacyInfo(root);
+        if (!pre.exists) {
+          out.push('没有旧文档定位：' + pre.dir);
+          out.push('判定：无需迁移。');
+          return { text: out.join(NL) };
+        }
+        const r = migrateLegacyDocmaps(root);
+        out.push('旧文档定位迁移：' + (r.ok ? '完成' : '部分完成'));
+        out.push('  已并入体系注册 ' + r.converted.length + ' 份' + (r.converted.length ? '：' + r.converted.join('、') : ''));
+        out.push('  全局旧内容保留为工作区文档清单 ' + r.kept.length + ' 份' + (r.kept.length ? '：' + r.kept.join('、') : ''));
+        if (r.archived) out.push('  旧目录已归档（未删除）：' + r.archived);
+        for (const p of r.problems || []) out.push('  未迁移：' + p);
+        try {
+          const g = syncGlobalRefs(root);
+          out.push('  全局总注册已重建：' + g.rows.length + ' 个任务');
+        } catch (e) {
+          out.push('  全局总注册重建失败：' + String(e && e.message ? e.message : e));
+        }
         return { text: out.join(NL) };
       }
 
@@ -147,7 +179,7 @@ export function pmWorkspaceTool(env) {
           }
         }
         const rows = workspaceRows();
-        out.push('工作区（退化：读 workspace.json，' + rows.length + ' 个）');
+        out.push('工作区（退化读取 workspace.json，' + rows.length + ' 个）');
         for (const r of rows) out.push('  ' + r.id + '  ' + r.title + '  ' + r.path + '  会话 ' + r.sessions);
         return { text: out.join(NL) };
       }
@@ -161,13 +193,13 @@ export function pmWorkspaceTool(env) {
         if ((!st || !st.isDirectory()) && args.ensure === true) {
           try { fs.mkdirSync(p, { recursive: true }); st = fs.statSync(p); } catch (e) { throw new Error('建目录失败：' + p + '（' + String(e && e.message ? e.message : e) + '）'); }
         }
-        if (!st || !st.isDirectory()) throw new Error('目录不存在或不是目录：' + p + '（默认不替你建目录；要建请传 ensure=true，或先手工建好）');
+        if (!st || !st.isDirectory()) throw new Error('目录不存在或不是目录：' + p + '（缺省不代建目录；需要创建时传 ensure=true，或先行手工建好）');
         const title = String(args.title || '').trim() || p.split(/[\\/]/).filter(Boolean).pop() || p;
         let w = null;
         try { w = await reg.create(p, title); } catch (e) { throw new Error('建工作区失败：' + String(e && e.message ? e.message : e)); }
         out.push('已注册工作区 ' + String(w && w.id ? w.id : '?') + '  ' + String(w && w.title ? w.title : title));
         out.push('路径 ' + String(w && w.path ? w.path : p));
-        out.push('同一路径重复调用返回原记录、不改标题；新登记的工作区排在列表最前。');
+        out.push('同一路径重复调用返回原记录，不改标题；新登记的工作区排在列表最前。');
         return { text: out.join(NL) };
       }
 
@@ -177,13 +209,13 @@ export function pmWorkspaceTool(env) {
         if (!key) throw new Error('delete 需要 workspace（id、标题、路径）');
         let list = [];
         try { list = reg.list() || []; } catch { list = []; }
-        const norm = (s) => String(s || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+        const norm = (s) => pathKey(String(s || ''));
         const hit = list.find((w) => String(w.id) === key || w.title === key || norm(w.path) === norm(key));
         if (!hit) throw new Error('找不到工作区：' + key);
         if (String(hit.title || '').indexOf('全局') !== -1) throw new Error(BAD);
         const ok = await reg.delete(hit.id);
         out.push((ok ? '已删除工作区注册 ' : '该工作区不存在（无操作）') + String(hit.id) + '  ' + String(hit.title || '-'));
-        out.push('注意：只删注册；目录与全部会话日志都保留在原处。');
+        out.push('注意：只删注册；目录与全部会话日志均保留在原处。');
         return { text: out.join(NL) };
       }
 
@@ -200,11 +232,11 @@ export function pmWorkspaceTool(env) {
         if (!p.ok) return { text: renderProbe(p) + NL + '未开始复制。' };
         const r = await startMove({ src, to });
         if (!r.ok) {
-          out.push('复制完成但**校验有差异**，未生成切换脚本。');
+          out.push('复制完成，但校验存在差异，未生成切换脚本。');
           out.push('  文件 源 ' + r.report.files + ' / 目标 ' + r.report.copies);
           out.push('  缺失 ' + r.report.missingCount + ' 条' + (r.report.missing.length ? '：' + r.report.missing.join('、') : ''));
           out.push('  多出 ' + r.report.extraCount + ' 条' + (r.report.extra.length ? '：' + r.report.extra.join('、') : ''));
-          out.push('处置：清空目标目录后重跑，或先停掉在写文件的会话。');
+          out.push('处置：清空目标目录后重跑，或先停止正在写入文件的会话。');
           return { text: out.join(NL) };
         }
         out.push('复制并校验通过：' + r.report.files + ' 文件 · ' + gb(r.report.bytes));
@@ -213,20 +245,20 @@ export function pmWorkspaceTool(env) {
         out.push('  切换助手  ' + r.marker.script.helper);
         out.push('  手工启动器（Windows、POSIX）  ' + r.marker.script.cmd + ' 、 ' + r.marker.script.sh);
         out.push('');
-        out.push('下一步（三条，顺序不能换）：');
+        out.push('下一步（3 步，顺序不可调换）：');
         out.push('  ① 完全退出 DSH（源目录被占用，改名会失败）');
-        out.push('  ② 执行 ho_workspace(action="move-switch") 派后台助手（推荐）；助手会等待 DSH 退出后自动完成');
+        out.push('  ② 执行 ho_workspace(action="move-switch") 派出后台助手（推荐用法）；该助手会在 DSH 退出后自动完成');
         out.push('  ③ 重新启动 DSH；确认无误后可在设置页删除旧备份');
         return { text: out.join(NL) };
       }
 
       if (action === 'move-switch') {
         const r = stageSwitch({ relaunch: args.relaunch === true });
-        if (r.already) { out.push('已经是切换态（旧路径就是 junction），无需再切。'); return { text: out.join(NL) }; }
+        if (r.already) { out.push('已处于切换态（原路径即链接），无需再次切换。'); return { text: out.join(NL) }; }
         out.push('已派出后台切换助手（pid ' + r.pid + '）。');
-        out.push('  它会在你**完全退出 DSH** 后自动完成：旧目录改名、原位建 junction、校验指向' + (r.relaunch ? '，然后重新启动 DSH' : '') + '。');
+        out.push('  该助手会在完全退出 DSH 后自动完成：旧目录改名、原位建立链接、校验指向' + (r.relaunch ? '，然后重新启动 DSH' : '') + '。');
         out.push('  日志：' + r.log);
-        out.push('  提醒：从现在起不要改这个工作区里的文件（改动只会落在还活着的旧目录上）。');
+        out.push('  提醒：此后不得修改该工作区内的文件（改动只会落在仍在使用的旧目录上）。');
         return { text: out.join(NL) };
       }
 
@@ -234,14 +266,14 @@ export function pmWorkspaceTool(env) {
         const st = moveStatus();   // 以标记里的源路径为准：修改登记后当前根已是新位置，拿它比对会误报
         const label = { none: '没有迁移记录', verified: '已复制并校验通过，待切换', switched: '已切换（原路径为链接）', partial: '复制有差异，未生成脚本' };
         out.push('迁移状态：' + (label[st.phase] || st.phase));
-        out.push('  源  ' + st.src + (st.linkTarget ? '（→ ' + st.linkTarget + '）' : ''));
+        out.push('  源  ' + st.src + (st.linkTarget ? '（当前为链接，指向 ' + st.linkTarget + '）' : ''));
         if (st.dst) out.push('  目标  ' + st.dst);
         if (st.marker && st.marker.files) out.push('  清单  ' + st.marker.files + ' 文件 · ' + (st.marker.digest || '').slice(0, 16) + '…');
         if (st.retarget) {
           if (st.retarget.needed) {
-            out.push('  DSH 登记仍指着旧路径：' + st.retarget.total + ' 处');
+            out.push('  DSH 登记仍指向旧路径：' + st.retarget.total + ' 处');
             for (const f of st.retarget.files) out.push('    ' + f.path + '  ×' + f.count);
-            out.push('  修改登记：ho_workspace(action="move-retarget")（退出 DSH 后由助手改写，先备份）');
+            out.push('  修改登记：ho_workspace(action="move-retarget")（退出 DSH 后由助手改写，改写前先备份）');
           } else {
             out.push('  DSH 登记已在新位置（无需修改登记）');
           }
@@ -250,7 +282,7 @@ export function pmWorkspaceTool(env) {
           for (const o of st.olds) out.push('  旧备份  ' + o.path + '  ' + gb(o.bytes));
           out.push('  删除：ho_workspace(action="move-cleanup", confirm=true)');
         } else if (st.phase === 'switched') {
-          out.push('  没有旧备份');
+          out.push('  无旧备份');
         }
         return { text: out.join(NL) };
       }
@@ -258,32 +290,32 @@ export function pmWorkspaceTool(env) {
       if (action === 'move-retarget') {
         const r = stageRetarget();
         if (r.already) { out.push('DSH 登记已在新位置，无需修改登记。'); return { text: out.join(NL) }; }
-        if (!r.ok) { out.push('派助手失败：' + r.error); out.push('  手工执行：' + (r.script && r.script.helper)); return { text: out.join(NL) }; }
-        out.push('已派出登记修改登记助手（pid ' + r.pid + '）。');
-        out.push('  它会在你完全退出 DSH 后改写这些登记（每份先备份）：');
+        if (!r.ok) { out.push('派出助手失败：' + r.error); out.push('  手工执行：' + (r.script && r.script.helper)); return { text: out.join(NL) }; }
+        out.push('已派出修改登记的助手（pid ' + r.pid + '）。');
+        out.push('  该助手会在完全退出 DSH 后改写下列登记（每份先备份）：');
         for (const f of (r.plan.files || [])) if (f.count) out.push('    ' + f.path + '  ×' + f.count);
-        out.push('  只改登记文本，不动任何数据文件；日志：' + (r.script && r.script.log));
+        out.push('  只改登记文本，不改动任何数据文件；日志：' + (r.script && r.script.log));
         return { text: out.join(NL) };
       }
 
       if (action === 'move-repair') {
         const r = repairLink();
         if (r.already) { out.push('原路径已是指向新根的链接，无需重建。'); return { text: out.join(NL) }; }
-        out.push('已重建链接：' + r.src + ' → ' + r.dst + '（' + r.kind + '）');
-        out.push('  说明：只建链接，未改动任何文件。');
+        out.push('已重建链接：' + r.src + ' 指向 ' + r.dst + '（' + r.kind + '）');
+        out.push('  说明：仅建立链接，未改动任何文件。');
         return { text: out.join(NL) };
       }
 
       if (action === 'move-cleanup') {
-        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（会真删旧备份目录）');
+        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（将实际删除旧备份目录）');
         const r = await cleanupOld({ confirm: true });
         out.push(r.note);
-        for (const p of r.removed) out.push('  已删 ' + p);
+        for (const p of r.removed) out.push('  已删除 ' + p);
         if (r.bytes) out.push('  释放 ' + gb(r.bytes));
         return { text: out.join(NL) };
       }
 
-      throw new Error('action 只能是 init / scaffold / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
+      throw new Error('action 只能是 init / scaffold / migrate / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
     },
   };
 }

package/src/tools/peer.mjs

@@ -10,6 +10,9 @@
  * 动作级权限在这里再判一次：角色矩阵只决定「这个工具可不可见」，不细分动作。
  */
 import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { textOutput } from '../lib/output.mjs';
 import { PEER_NAME } from '../lib/names.mjs';
 import { NL } from '../lib/text.mjs';
@@ -18,9 +21,197 @@ import {
   projectName, pick, peerMarker, resolveWorkspaceId, findSessionLog, decodeSessionLog, conversation,
 } from '../lib/peer.mjs';
 
-export const ACTIONS = ['list', 'status', 'send', 'peek', 'rename', 'new'];
+export const ACTIONS = ['list', 'status', 'send', 'wait', 'collect', 'collab', 'peek', 'rename', 'new'];
 const GLOBAL_ONLY = ['list', 'peek', 'rename'];
 
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const COLLECT_POLL_MS = 30000;
+const WAIT_MIN_MS = 120000;
+
+/** 协作游标：交办者 → 目标 → { since }。只存时间戳，不存消息正文。 */
+function collectFile() {
+  const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
+  return path.join(home, '.dsh', 'storages', 'dsh-handover.collect.json');
+}
+function loadCollect() {
+  try {
+    const data = JSON.parse(fs.readFileSync(collectFile(), 'utf8'));
+    if (data && typeof data === 'object' && data.cursors) {
+      if (!Array.isArray(data.groups)) data.groups = [];
+      return data;
+    }
+  } catch (error) { void error; }
+  return { version: 1, cursors: {}, groups: [] };
+}
+function saveCollect(data) {
+  const file = collectFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+  fs.renameSync(tmp, file);
+}
+function callerOf(exec) {
+  return String(exec?.agent?.session?.header?.id ?? 'unknown');
+}
+function sinceOf(data, caller, target) {
+  const row = data.cursors[caller] && data.cursors[caller][target];
+  return row && Number.isFinite(row.since) ? row.since : null;
+}
+function setSince(data, caller, target, since) {
+  if (!data.cursors[caller]) data.cursors[caller] = {};
+  data.cursors[caller][target] = { since };
+}
+
+/** 协作注册：被交办方在协作期间不得向交办者或同组成员发明文消息；收集完自动解除。 */
+function groupsOf(state) {
+  return Array.isArray(state.groups) ? state.groups : [];
+}
+function groupOf(state, sid) {
+  return groupsOf(state).find((g) => String(sid) === String(g.coordinator) || (Array.isArray(g.members) && g.members.indexOf(String(sid)) !== -1)) || null;
+}
+function assertNotReplyingInCollab(state, sender, target) {
+  const g = groupOf(state, sender);
+  if (!g) return;
+  if (String(sender) === String(g.coordinator)) return;
+  const inGroup = String(target) === String(g.coordinator)
+    || (Array.isArray(g.members) && g.members.indexOf(String(target)) !== -1);
+  if (!inGroup) return;
+  throw new Error(
+    '协作注册期间，被交办方不得向交办者或同组成员发送明文消息（target=' + target + '）：'
+    + '完成即结束回合，最终回复即为结果，协调者用 peer(action="collect") 取回。'
+    + '如需请示，将问题写入最终回复并结束回合；普通对话不受此限制。',
+  );
+}
+
+/**
+ * 供宿主工具守卫使用：某会话是协作成员（非协调者）时返回拒绝理由，否则空串。
+ * 用于拦住 DSH 自带的 send_message 等明文投递通道。
+ */
+export function collabMemberReason(sid) {
+  try {
+    const state = loadCollect();
+    const g = groupOf(state, sid);
+    if (!g) return '';
+    if (String(sid) === String(g.coordinator)) return '';
+    return '协作注册期间，被交办方不得发送明文消息：完成即结束回合，最终回复由协调者用 peer(action="collect") 取回。';
+  } catch (error) { void error; }
+  return '';
+}
+
+/** 协作注册：开始或结束一组协作；结束即解除明文交流限制。 */
+function collabText(args, exec) {
+  const caller = callerOf(exec);
+  const state = loadCollect();
+  // 结束模式取 collabMode（schema 参数名）；兼容早期把 mode 当结束开关的调用。
+  const ending = args.collabMode === 'end' || args.mode === 'end';
+  if (ending) {
+    const before = groupsOf(state).length;
+    state.groups = groupsOf(state).filter((g) => String(g.coordinator) !== String(caller));
+    saveCollect(state);
+    return '已结束协作注册（' + String(before - state.groups.length) + ' 组），明文交流限制已解除。';
+  }
+  const members = (Array.isArray(args.sessions) ? args.sessions : [])
+    .map((x) => String(x || '').trim()).filter(Boolean).filter((s) => s !== caller);
+  if (!members.length) throw new Error('peer(action="collab")：sessions 至少列一个协作会话');
+  state.groups = groupsOf(state).filter((g) => String(g.coordinator) !== String(caller));
+  state.groups.push({ coordinator: caller, members, at: Date.now() });
+  saveCollect(state);
+  return '已注册协作：协调者 ' + caller + '，成员 ' + members.join('、')
+    + '。协作期间成员不得向协调者或同组成员发送明文消息；collect 取回全部结果后自动解除。';
+}
+
+/** 助手文本：读目标日志里 since 之后的助手回复，不定长截断。 */
+function assistantReplies(file, sinceMs) {
+  const events = decodeSessionLog(file);
+  if (events === null) return null;
+  const items = conversation(events, 500).filter((it) => it.who === 'assistant' && Number(it.t) > sinceMs);
+  return items.map((it) => it.text);
+}
+
+/** 单个目标的完成判定：这一轮已结束，且 since 之后有助手文本。 */
+function inspectTarget(sid, since) {
+  const file = findSessionLog(sid);
+  if (file === null) return { sid, state: 'missing', text: '' };
+  let replies = null;
+  try { replies = assistantReplies(file, since); } catch (error) { void error; }
+  if (replies === null) return { sid, state: 'nozstd', text: '' };
+  const cache = readProjCache(sid);
+  const busy = cache === null ? null : isBusy(cache);
+  if (busy === false && replies.length) {
+    return { sid, state: 'done', text: replies[replies.length - 1], at: Date.now() };
+  }
+  return { sid, state: busy === null ? 'unknown' : busy ? 'running' : 'ended-no-text', text: '' };
+}
+
+/** 一对一：等单个目标的回复。 */
+async function waitText(args) {
+  const sid = String(args.session_id || '').trim();
+  if (!sid) throw new Error('peer(action="wait")：session_id 不能为空');
+  const timeout = Math.max(WAIT_MIN_MS, Math.min(3600000, Number(args.timeout_ms) || WAIT_MIN_MS));
+  const since = Number(args.since_ms) || Date.now();
+  const deadline = Date.now() + timeout;
+  let lastError = '';
+  for (;;) {
+    const one = inspectTarget(sid, since);
+    if (one.state === 'done') return '回复 ' + sid + '：' + NL + one.text;
+    if (one.state === 'missing') throw new Error('peer(action="wait")：找不到目标会话日志：' + sid);
+    if (one.state === 'nozstd') throw new Error('peer(action="wait")：本 Node 构建没有 zstd 支持，读不了会话日志');
+    lastError = one.state;
+    if (Date.now() >= deadline) break;
+    await sleep(2000);
+  }
+  return '等待超时（' + String(Math.round(timeout / 1000)) + ' 秒）：' + sid + ' 状态 ' + lastError
+    + '。可先用 peer(action="status") 查看状态，稍后重试 wait。';
+}
+
+/**
+ * 多会话收集：列一串会话，谁先完成先返回；同时完成多个就一起返回。
+ * 一次调用最多等 timeout_ms（最低 120 秒，由助手按任务预估设置）；到点一个都没完成则返回仍在运行的名单。
+ */
+async function collectText(args, exec) {
+  const caller = callerOf(exec);
+  const state = loadCollect();
+  const list = Array.isArray(args.sessions)
+    ? args.sessions.map((x) => String(x || '').trim()).filter(Boolean)
+    : [];
+  const targets = list.length ? list : Object.keys(state.cursors[caller] || {});
+  if (!targets.length) throw new Error('peer(action="collect")：sessions 为空，且没有已交办的目标');
+  const timeout = Math.max(WAIT_MIN_MS, Math.min(3600000, Number(args.timeout_ms) || WAIT_MIN_MS));
+  const deadline = Date.now() + timeout;
+  const explicitSince = Number(args.since_ms) || null;
+  const since = {};
+  for (const sid of targets) since[sid] = sinceOf(state, caller, sid) ?? explicitSince ?? Date.now();
+  const done = [];
+  const running = new Map(targets.map((sid) => [sid, 'running']));
+  for (;;) {
+    for (const sid of targets) {
+      if (done.some((d) => d.sid === sid)) continue;
+      const one = inspectTarget(sid, since[sid]);
+      running.set(sid, one.state);
+      if (one.state === 'done') done.push(one);
+    }
+    if (done.length) {
+      for (const one of done) setSince(state, caller, one.sid, one.at);
+      const groups = groupsOf(state);
+      const g = groups.find((x) => String(x.coordinator) === caller);
+      if (g) {
+        g.members = (Array.isArray(g.members) ? g.members : []).filter((m) => !done.some((d) => d.sid === m));
+        if (!g.members.length) state.groups = groups.filter((x) => x !== g);
+      }
+      saveCollect(state);
+      const out = ['已完成 ' + String(done.length) + ' 个：'];
+      for (const one of done) out.push('[' + one.sid + ']' + NL + one.text);
+      return out.join(NL);
+    }
+    if (Date.now() >= deadline) break;
+    await sleep(COLLECT_POLL_MS);
+  }
+  const lines = ['本轮没有完成的会话（已等待 ' + String(Math.round(timeout / 1000)) + ' 秒）：'];
+  for (const sid of targets) lines.push('  ' + sid + '  ' + (running.get(sid) || 'running'));
+  lines.push('可稍后重试 collect；已完成的会立即返回。');
+  return lines.join(NL);
+}
+
 function roleOf(env, exec) {
   try { return env.roleOf(exec) || { role: 'plain' }; } catch { return { role: 'plain' }; }
 }
@@ -85,11 +276,23 @@ async function sendText(env, args, exec, info) {
   const sender = exec?.agent?.session?.header?.id ?? 'unknown';
   const marker = peerMarker(sender);
   const body = message.startsWith(marker) ? message : marker + NL + message;
+  const before = loadCollect();
+  assertNotReplyingInCollab(before, sender, target);
+  const since = Date.now();
   const receipt = await controller.prompt(
     { requestId: randomUUID(), sessionId: target, mode, content: [{ type: 'text', text: body }] },
     new AbortController().signal,
   );
-  return 'accepted=' + String(receipt.accepted) + ' mode=' + mode + ' target=' + target + ' from=' + sender;
+  try {
+    const state = loadCollect();
+    setSince(state, sender, target, since);
+    saveCollect(state);
+  } catch (error) { void error; }
+  const head = 'accepted=' + String(receipt.accepted) + ' mode=' + mode + ' target=' + target + ' from=' + sender;
+  if (args.wait === true) {
+    return head + NL + await waitText({ session_id: target, since_ms: since, timeout_ms: args.timeout_ms });
+  }
+  return head;
 }
 
 async function peekText(args) {
@@ -132,7 +335,7 @@ async function newText(env, args, info) {
   // 会话创建仅属全局；杂项可以把会话建在 Misc 下（落到本任务体系内）。
   const wantsWorkspace = typeof args.workspace === 'string' && args.workspace.trim() !== '';
   if (wantsWorkspace && args.cwd !== undefined) {
-    throw new Error('peer(action="new")：传 workspace 时不要再传 cwd —— session.create 只接受其中之一（cwd 会自动取该工作区的 path）');
+    throw new Error('peer(action="new")：传 workspace 时不得再传 cwd，session.create 只接受其中之一（cwd 会自动取该工作区的 path）');
   }
   const targetText = String(args.workspace || args.cwd || '').toLowerCase();
   const allowed = info.role === 'global' || (info.role === 'misc' && targetText.indexOf('misc') !== -1);
@@ -171,17 +374,22 @@ export function pmPeerTool(env) {
   return {
     name: PEER_NAME,
     description:
-      '平级会话：action=list 一览、status 详情、send 投消息（耗对方 token）、peek 读近期会话历史（耗本会话 token）、rename 改标题、new 新建。list、peek、rename 与 new 仅全局会话可用。',
+      '平级会话：action=list 会话一览、status 单会话详情、send 投递消息（wait=true 时同轮等待回复）、wait 等待单个回复、collect 收集多个会话中先完成的最终回复、collab 注册或结束协作、peek 读取历史、rename 修改标题、new 新建会话。list、peek、rename 与 new 仅全局会话可用。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       required: ['action'],
       properties: {
-        action: { type: 'string', enum: ACTIONS, description: '要做的动作' },
-        session_id: { type: 'string', description: 'status、send、peek、rename：目标会话 id' },
+        action: { type: 'string', enum: ACTIONS, description: '要执行的动作' },
+        session_id: { type: 'string', description: 'status、send、wait、peek、rename：目标会话 id' },
+        sessions: { type: 'array', items: { type: 'string' }, description: 'collect：要等待的会话 id 列表；留空则取已交办的目标' },
         message: { type: 'string', description: 'send：要投递的正文' },
-        mode: { type: 'string', enum: ['queue', 'steer'], description: 'send：queue（默认）或 steer' },
-        limit: { type: 'number', description: 'list：最多多少行（默认 40）；peek：最近多少条（默认 8，上限 40）' },
+        mode: { type: 'string', enum: ['queue', 'steer'], description: 'send：queue（缺省）或 steer' },
+        wait: { type: 'boolean', description: 'send：投递后在同一轮等待回复（一对一对话用）' },
+        collabMode: { type: 'string', enum: ['start', 'end'], description: 'collab：start 注册协作（缺省）、end 结束并解除限制' },
+        timeout_ms: { type: 'number', description: 'wait、collect：单次等待上限（毫秒，最低 120000，按任务预估设置）' },
+        since_ms: { type: 'number', description: 'wait、collect：从哪一时刻之后查找回复（缺省取交办时刻）' },
+        limit: { type: 'number', description: 'list：最多多少行（缺省 40）；peek：最近多少条（缺省 8，上限 40）' },
         include_subagents: { type: 'boolean', description: 'list：同时列出子会话' },
         title: { type: 'string', description: 'new、rename：显示标题' },
         workspace: { type: 'string', description: 'new：工作区 id、标题或路径（与 cwd 互斥）' },
@@ -197,6 +405,9 @@ export function pmPeerTool(env) {
       if (action === 'list') return { text: await listText(env, args) };
       if (action === 'status') return { text: await statusText(env, args) };
       if (action === 'send') return { text: await sendText(env, args, exec, info) };
+      if (action === 'wait') return { text: await waitText(args) };
+      if (action === 'collect') return { text: await collectText(args, exec) };
+      if (action === 'collab') return { text: collabText(args, exec) };
       if (action === 'peek') return { text: await peekText(args) };
       if (action === 'rename') return { text: await renameText(env, args) };
       return { text: await newText(env, args, info) };