@mingmaple/dsh-handover 0.9.13 → 0.9.22

package/src/index.mjs

@@ -1,7 +1,7 @@
 /**
  * dsh-handover —— 全局运行期插件。
  * 判据进代码、流程进工具；规则正文留磁盘，需要时用 ho_charter 取节（完整流程 doc="runtime"）。
- * 按会话角色载入工具与提示段：全局 24 个工具、项目 11、杂项 11、普通 0。
+ * 按会话角色载入工具与提示段：全局 14 个工具、项目 11、杂项 10、普通 0。
  * 源码不热加载：改完要重启 DSH。
  */
 import fs from 'node:fs';
@@ -11,35 +11,25 @@ import { resolveConfig } from './lib/config.mjs';
 import { projCacheDir, pressurePct } from './lib/sessions.mjs';
 import { createScheduler } from './lib/schedule.mjs';
 import { compactionStateOf, stalePressureNote } from './lib/events.mjs';
-import { pmBriefTool } from './tools/ho_brief.mjs';
+import { pmStatusTool } from './tools/ho_status.mjs';
 import { pmGateTool } from './tools/ho_gate.mjs';
 import { pmSessionsTool } from './tools/ho_sessions.mjs';
-import { pmPhaseTool } from './tools/ho_phase.mjs';
 import { pmCharterTool } from './tools/ho_charter.mjs';
 import { pmHandoverTool } from './tools/ho_handover.mjs';
 import { pmCheckpointTool } from './tools/ho_checkpoint.mjs';
-import { pmSnapshotTool } from './tools/ho_snapshot.mjs';
-import { pmDiagTool } from './tools/ho_diag.mjs';
-import { pmDriftTool } from './tools/ho_drift.mjs';
 import { pmChangelogTool } from './tools/ho_changelog.mjs';
-import { pmTokensTool } from './tools/ho_tokens.mjs';
-import { pmPackTool } from './tools/ho_pack.mjs';
+import { pmBackupTool } from './tools/ho_backup.mjs';
 import { pmWorkspaceTool } from './tools/ho_workspace.mjs';
-import { pmInitTool } from './tools/ho_init.mjs';
 import { pmProfileTool } from './tools/ho_profile.mjs';
 import { pmOfficeTool } from './tools/ho_office.mjs';
 import { pmSucceedTool } from './tools/ho_succeed.mjs';
-import { pmPeerListTool } from './tools/peer_list.mjs';
-import { pmPeerStatusTool } from './tools/peer_status.mjs';
-import { pmPeerSendTool } from './tools/peer_send.mjs';
-import { pmPeerNewTool } from './tools/peer_new.mjs';
-import { pmPeerRenameTool } from './tools/peer_rename.mjs';
-import { pmPeerPeekTool } from './tools/peer_peek.mjs';
+import { pmDocmapTool } from './tools/ho_docmap.mjs';
+import { pmPeerTool } from './tools/peer.mjs';
 import { resolveRegistry } from './lib/registry.mjs';
 import { registerStatusRoute } from './lib/webroute.mjs';
 import { createApi, statusSnapshot } from './lib/api.mjs';
 import { registerRpcCarrier } from './lib/rpc-carrier.mjs';
-import { NAMES } from './lib/names.mjs';
+import { NAMES, PEER_NAME } from './lib/names.mjs';
 import { readExtraPrompt, writeExtraPrompt, EXTRA_PROMPT_ORDER, EXTRA_PROMPT_SECTION } from './lib/extra-prompt.mjs';
 import {
   ROLES, resolveRole, sessionMeta, handoverPathFor, toolsetFor,
@@ -50,12 +40,14 @@ import { sendPrompt } from './lib/prompt.mjs';
 import { resolveShortSid } from './lib/api.mjs';
 import { routeWorkspace } from './lib/workspace.mjs';
 import { stampTz } from './lib/brief.mjs';
-import { grantConsent } from './lib/consent.mjs';
+import { grantConsent, activeConsentsFor } from './lib/consent.mjs';
+import { docmapBlock } from './lib/docmap.mjs';
+import { moveStatus } from './lib/mover.mjs';
 
 export const name = 'dsh-handover';
 // 必需服务（名字已核对：dsh-agent→agents、dsh-compaction→compaction、dsh-api-session-controller→sessionController）。
 // 只 inject 一定存在的服务：多写一个不存在的名字，cordis 会让整个插件静默不激活。
-// agents / compaction 用运行时解析（ctx[name] → ctx.get(name)），无法获取由 ho_diag 报出来、ho_checkpoint 明确报错。
+// agents / compaction 用运行时解析（ctx[name] → ctx.get(name)），无法获取由 ho_status（view="diag"）报出来、ho_checkpoint 明确报错。
 export const inject = ['tools', 'systemPrompt', 'sessionController'];
 
 /** 自身包信息：dist 里读 ./package.json，源码树里退回 ../package.json。 */
@@ -110,6 +102,7 @@ export function apply(ctx, config) {
   // 更早的内核忽略注册选项，只能退回 agent 作用域的 restrict；两条路径按能力二选一，不并行。
   const perStep = (() => { try { return !!(ctx.tools && typeof ctx.tools.resolve === 'function'); } catch { return false; } })();
   const sectionDispose = new Map();       // sessionId → 撤销提示段
+  const consentSig = new Map();           // sessionId → 上次装配时的授权签名（授权出现或过期时重装）
   const legacyRestrict = new Map();       // sessionId → 撤销限制（仅无按步解析的内核）
   const appliedRole = new Map();          // sessionId → 上次装配的角色
   const roleCache = new Map();            // sessionId → { at, info }（每步过滤用，短 TTL）
@@ -153,7 +146,7 @@ export function apply(ctx, config) {
       scheduler.request(sessionId, Object.assign({ n, consent: 'checked' }, opts || {})).catch(() => {});
     },
     registry() { return resolveRegistry(ctx); },
-    /** 迁移感知：根目录是否已搬到别处（旧路径变 junction）。给提示段与 ho_diag 用。 */
+    /** 迁移感知：根目录是否已搬到别处（旧路径变 junction）。给提示段与 ho_status（view="diag"）用。 */
     moveInfo() {
       try {
         const src = cfg.workspaceRoot || walkUpToWorkspace(process.cwd());
@@ -202,7 +195,7 @@ export function apply(ctx, config) {
     staleNote(exec) {
       try { return stalePressureNote(this.selfId(exec)); } catch { return ''; }
     },
-    /** 自身版本：从 dist/package.json 读，设置页与 ho_diag 共用同一值。 */
+    /** 自身版本：从 dist/package.json 读，设置页与 ho_status（view="diag"）共用同一值。 */
     version() {
       try { return pkgInfo().version; } catch { return '?'; }
     },
@@ -288,7 +281,7 @@ export function apply(ctx, config) {
     return saved;
   };
 
-  /** 当前生效的裁剪机制，供 ho_diag 报出。 */
+  /** 当前生效的裁剪机制，供 ho_status（view="diag"）报出。 */
   function roleMode() {
     if (cfg.roleGating === 'off') return '关闭（roleGating=off，所有会话可见全部工具）';
     return perStep
@@ -337,7 +330,11 @@ export function apply(ctx, config) {
     let text = '';
     try {
       const ws = workspaceForAgent(agent);
-      text = manualFor(info, { ws, cfg, move: typeof env.moveInfo === 'function' ? env.moveInfo() : null });
+      // 文档定位与授权状态都是「按会话现算」的：写盘后重装一次即可生效，不另开注入点。
+      const docmap = docmapBlock(ws, info);
+      const consents = activeConsentsFor(sid);
+      text = manualFor(info, { ws, cfg, move: typeof env.moveInfo === 'function' ? env.moveInfo() : null, docmap, consents });
+      consentSig.set(sid, consents.map((r) => r.kind + ':' + r.until).join('|'));
     } catch (e) {
       initErrors.push('角色提示段：' + msgOf(e));
       return;
@@ -432,6 +429,18 @@ export function apply(ctx, config) {
     } catch { return false; }
   };
 
+  /** 重装某会话的提示段：文档定位写盘后、授权到达后各调一次；不唤醒、不投消息。 */
+  env.refreshPromptFor = (sid) => {
+    try {
+      const id = String(sid || '');
+      if (!id) return false;
+      const a = agentOf(id);
+      if (!a) return false;
+      applyRoleTo(a);
+      return true;
+    } catch { return false; }
+  };
+
   // ---------------- 调度器（续跑文案要按角色取交接路径）
   // 注意：调度器拿到的是会话 id 字符串，不是 exec；这里用按 id 解析的版本，直接读角色表与磁盘。
   const schedDeps = { ctx, cfg, logger: (ctx.logger || null), roleOf: null, handoverFor: null };
@@ -472,7 +481,7 @@ export function apply(ctx, config) {
   };
   try { applyExtraPrompt(readExtraPrompt()); } catch (e) { initErrors.push('全局前置提示词：' + msgOf(e)); }
 
-  // ---------------- 工具注册（18 个 ho_* + 6 个 peer_*）
+  // ---------------- 工具注册（13 个 ho_* + 1 个 peer）
   // 0.2.2 起工具按「步」解析：可用工具集合每一步重算。子会话排除与角色过滤都在这里一次做完，
   // 不再另用 agent 作用域 restrict —— 两套机制并行时，换角色要么等到重启、要么互相覆盖。
   const roleToolsets = new Map(ROLES.map((r) => [r, new Set(toolsetFor(r).allow)]));
@@ -498,26 +507,21 @@ export function apply(ctx, config) {
     };
   }
   const tools = [
-    pmBriefTool(env),
+    pmStatusTool(env, { schedulerReady: () => scheduler !== null, schedulerError: () => schedulerError }),
     pmGateTool(env),
     pmSessionsTool(env),
-    pmPhaseTool(env),
     pmCharterTool(env),
     pmHandoverTool(env),
     pmCheckpointTool(env),
-    pmSnapshotTool(env),
-    pmDiagTool(env, { schedulerReady: () => scheduler !== null, schedulerError: () => schedulerError }),
-    pmDriftTool(env),
     pmChangelogTool(env),
-    pmTokensTool(env),
-    pmPackTool(env),
+    pmBackupTool(env),
     pmWorkspaceTool(env),
-    pmInitTool(env),
     pmProfileTool(env),
     pmOfficeTool(env),
     pmSucceedTool(env),
+    pmDocmapTool(env),
   ];
-  const keys = ['brief', 'gate', 'sessions', 'phase', 'charter', 'handover', 'checkpoint', 'snapshot', 'diag', 'drift', 'changelog', 'tokens', 'pack', 'workspace', 'init', 'profile', 'office', 'succeed'];
+  const keys = ['status', 'gate', 'sessions', 'charter', 'handover', 'checkpoint', 'changelog', 'backup', 'workspace', 'profile', 'office', 'succeed', 'docmap'];
   for (let i = 0; i < tools.length; i++) {
     const key = keys[i];
     try {
@@ -531,54 +535,52 @@ export function apply(ctx, config) {
     }
   }
 
-  const peerTools = [
-    pmPeerListTool(env),
-    pmPeerStatusTool(env),
-    pmPeerSendTool(env),
-    pmPeerNewTool(env),
-    pmPeerRenameTool(env),
-    pmPeerPeekTool(env),
-  ];
+  const peerTools = [pmPeerTool(env)];
   for (const t of peerTools) {
     try {
       ctx.tools.register(t, { when: visibleTo(t && t.name ? String(t.name) : '') });
       if (t && t.name) registered.add(t.name);
     } catch (e) {
-      initErrors.push((t && t.name ? String(t.name) : 'peer_?') + '：' + msgOf(e));
+      initErrors.push((t && t.name ? String(t.name) : 'peer') + '：' + msgOf(e));
     }
   }
 
   // ---------------- 会话守卫（Charter §7.2.4）：新建会话与设定角色仅属全局；
-  // 会话之间允许直接 peer_send（不必经全局转述），directPeer=off 时退回「只能向全局报告」的旧口径。
+  // 会话之间允许直接 peer（action=send）通信（不必经全局转述），directPeer=off 时退回「只能向全局报告」的旧口径。
   if (cfg.wakeAuthority !== 'off' && typeof ctx.tools.guard === 'function') {
     try {
       ctx.tools.guard((exec) => {
         const nm = exec && exec.name;
-        if (nm !== 'peer_send' && nm !== 'peer_new') return undefined;
+        if (nm !== PEER_NAME) return undefined;
+        let args = (exec && exec.arguments) || {};
+        if (typeof args === 'string') { try { args = JSON.parse(args); } catch { args = {}; } }
+        const action = String(args.action || '');
+        // list／status／peek／rename 的权限由工具内部按角色判，这里只管两件有外部影响的事。
+        if (action !== 'send' && action !== 'new') return undefined;
         const sid = env.selfId(exec) || '';
-        const args = (exec && exec.arguments) || {};
         let info;
         try { info = env.roleOf(exec); } catch { info = { role: 'plain', source: 'error' }; }
         const mk = (allow, why) => {
           guardLast = { sid, allow, source: why, title: titleOf(sid) };
           if (allow) return undefined;
-          if (nm === 'peer_new') return '会话创建仅属全局：非全局会话不得新建平级会话（杂项落到 Misc 除外）。';
+          if (action === 'new') return '会话创建仅属全局：非全局会话不得新建平级会话（杂项落到 Misc 除外）。';
           return '会话间通信受限（directPeer=off）：非全局会话只能向现任全局报告，不得唤醒其他会话。';
         };
-        if (info.role === 'global') return mk(true, 'global/' + info.source);
-        if (nm === 'peer_send') {
-          // 会话之间可直接对话；向全局报告也在此路。directPeer=off 才退回旧口径。
+        if (info.role === 'global') return mk(true, '全局角色');
+        if (action === 'send') {
+          // 会话之间可直接通信；向全局报告也在此路。directPeer=off 才退回旧口径。
           const target = String(args.session_id || '');
           let t = null;
           try { t = target ? infoFor(target, {}) : null; } catch { t = null; }
-          if (t && t.role === 'global') return mk(true, 'report-to-global/' + (t.source || ''));
-          if (cfg.directPeer !== 'off') return mk(true, 'direct/' + info.role + ' → ' + (t ? t.role : 'unknown'));
-          return mk(false, info.source + '/' + info.role + ' → ' + (t ? t.role : 'unknown'));
+          const tRole = t ? t.role : '未知';
+          if (t && t.role === 'global') return mk(true, '向现任全局报告');
+          if (cfg.directPeer !== 'off') return mk(true, '会话之间直接通信（' + info.role + ' → ' + tRole + '）');
+          return mk(false, 'directPeer=off：仅允许向全局报告（' + info.role + ' → ' + tRole + '）');
         }
-        // peer_new：只有杂项可以落到 Misc
+        // action=new：只有杂项可以落到 Misc
         const target = String(args.workspace || args.cwd || '').toLowerCase();
-        if (info.role === 'misc' && target.indexOf('misc') !== -1) return mk(true, 'misc/' + info.source);
-        return mk(false, info.source + '/' + info.role);
+        if (info.role === 'misc' && target.indexOf('misc') !== -1) return mk(true, '杂项会话新建到 Misc');
+        return mk(false, '非全局角色不得新建平级会话（' + info.role + '）');
       });
     } catch { /* 老版本没有 guard：退化为规则约束 */ }
   }
@@ -629,7 +631,10 @@ export function apply(ctx, config) {
           const sid = String((h && h.id) || agent.id || '');
           if (!sid) return;
           const info = infoFor(sid, scopedMetaOf(h, sid));
-          if (appliedRole.get(sid) === info.role) return;
+          // 角色没变也要看授权签名：用户刚从设置页或斜杠命令授权时，下一轮就该看见那一行。
+          let sig = '';
+          try { sig = activeConsentsFor(sid).map((r) => r.kind + ':' + r.until).join('|'); } catch { sig = ''; }
+          if (appliedRole.get(sid) === info.role && consentSig.get(sid) === sig) return;
           env.log('开轮前换装：' + sid + ' · 已装 ' + (appliedRole.get(sid) || '-') + ' · 目标 ' + info.role);
           applyRoleTo(agent, info);
         } catch (e) { env.log('开轮前装配失败：' + msgOf(e)); }
@@ -700,7 +705,7 @@ export function apply(ctx, config) {
     const allowCommands = [
       {
         name: 'allow-compact',
-        description: '允许本会话压缩一次（用户授权，5 分钟有效；可带会话短号授权别的会话）',
+        description: '允许本会话压缩一次（当前用户授权，5 分钟有效；可带会话短号授权别的会话）',
         hint: '可留空＝本会话；填 8 位短号或 session-id 则授权那个会话',
         kind: 'compact',
         note: '聊天页命令 /allow-compact',
@@ -708,7 +713,7 @@ export function apply(ctx, config) {
       },
       {
         name: 'allow-succeed',
-        description: '允许本会话换任一次（用户授权，5 分钟有效；可带会话短号授权别的会话）',
+        description: '允许本会话换任一次（当前用户授权，5 分钟有效；可带会话短号授权别的会话）',
         hint: '可留空＝本会话；填 8 位短号或 session-id 则授权那个会话',
         kind: 'succeed',
         note: '聊天页命令 /allow-succeed',
@@ -725,8 +730,10 @@ export function apply(ctx, config) {
           handler: ({ agent, rawInput }) => {
             const arg = String(rawInput || '').trim();
             const sid = arg ? resolveShortSid(env, arg) : (agent && agent.id ? String(agent.id) : '');
-            if (!sid) return { kind: 'error', text: '拿不到会话 id：请写成 /' + cmd.name + ' session-xxxx' };
+            if (!sid) return { kind: 'error', text: '无法获取会话 id：请写成 /' + cmd.name + ' session-xxxx' };
             const g = grantConsent(sid, cmd.note, cmd.kind);
+            // 授权一到就重装提示段：目标会话下一轮（哪怕现在空闲）就能看见那一行。
+            try { env.refreshPromptFor(sid); } catch { /* 装配失败不影响授权本身 */ }
             try { env.log(cmd.action + '授权（命令）：' + sid); } catch { /* ignore */ }
             return { kind: 'success', text: '已允许 ' + sid + ' 在 ' + g.minutes + ' 分钟内' + cmd.action + '一次（用掉即失效）。' };
           },

package/src/lib/api.mjs

@@ -218,21 +218,21 @@ export function createApi(env, info) {
       if (method === 'move.start') {
         const src = currentRoot(env);
         if (!src) return bad('no-workspace', '未找到全局根（工作区未接入）');
-        env.log('搬迁：开始复制 ' + src + ' → ' + String(p.to || ''));
+        env.log('迁移：开始复制 ' + src + ' → ' + String(p.to || ''));
         const startedAt = Date.now();
         const r = await startMove({ src, to: p.to });
-        env.log('搬迁：' + (r.ok ? '校验通过' : '校验有差异') + '，用时 ' + Math.round((Date.now() - startedAt) / 1000) + ' s');
+        env.log('迁移：' + (r.ok ? '校验通过' : '校验有差异') + '，用时 ' + Math.round((Date.now() - startedAt) / 1000) + ' s');
         return r.ok ? ok(r) : { ok: false, error: { code: 'verify-failed', message: '复制完成但校验有差异，未生成切换脚本', details: r.report }, http: 500 };
       }
 
       if (method === 'move.switch') {
         const r = stageSwitch({ relaunch: p.relaunch === true });
-        env.log('搬迁：后台切换助手 ' + (r.already ? '无需再派（已切换）' : '已派出 pid=' + r.pid));
+        env.log('迁移：后台切换助手 ' + (r.already ? '无需再派（已切换）' : '已派出 pid=' + r.pid));
         return ok(r);
       }
 
       if (method === 'move.status') {
-        // 一律以搬迁标记里的源路径为准：修改登记生效后当前工作区根已经变成新位置，
+        // 一律以迁移标记里的源路径为准：修改登记生效后当前工作区根已经变成新位置，
         // 再拿它去比对会把「已经是新位置」误报成「还指着旧路径」。
         return ok(moveStatus());
       }
@@ -242,6 +242,8 @@ export function createApi(env, info) {
         if (!sid) return bad('bad-request', '缺少 session_id');
         const kind = p.kind === 'succeed' ? 'succeed' : 'compact';
         const g = grantConsent(sid, kind === 'succeed' ? '设置页点击换任' : '设置页点击', kind);
+        // 授权一到就重装目标会话的提示段：空闲会话下一轮即可看见，不必等它自己去查。
+        if (typeof env.refreshPromptFor === 'function') { try { env.refreshPromptFor(sid); } catch { /* ignore */ } }
         env.log((kind === 'succeed' ? '换任' : '压缩') + '授权：' + sid + '（5 分钟）');
         invalidateStatus(env);
         return ok(g);
@@ -265,20 +267,20 @@ export function createApi(env, info) {
 
       if (method === 'move.retarget-stage') {
         const r = stageRetarget();
-        env.log('搬迁：登记修改登记助手 ' + (r.already ? '无需（已在新位置）' : '已派出 pid=' + r.pid));
+        env.log('迁移：登记修改登记助手 ' + (r.already ? '无需（已在新位置）' : '已派出 pid=' + r.pid));
         return ok(r);
       }
 
       if (method === 'move.repair') {
         const r = repairLink();
-        env.log('搬迁：重建链接 ' + (r.already ? '已存在' : r.src + ' → ' + r.dst));
+        env.log('迁移：重建链接 ' + (r.already ? '已存在' : r.src + ' → ' + r.dst));
         invalidateStatus(env);
         return ok(r);
       }
 
       if (method === 'move.cleanup') {
         const r = await cleanupOld({ confirm: p.confirm === true });
-        env.log('搬迁：清理旧副本 ' + (r.removed || []).length + ' 个');
+        env.log('迁移：清理旧备份 ' + (r.removed || []).length + ' 个');
         return ok(r);
       }
 

package/src/lib/brief.mjs

@@ -59,7 +59,7 @@ export function composeBrief(input) {
     const skipProjects = new Set(scan.skip.map((r) => r.project));
     out.push("活跃   " + notifProjects.size + " 个项目，需要通知 " + scan.notify.length + " 个会话：" + (scan.notify.length ? scan.notify.map((r) => r.project + "(" + sidShort(r.sid) + ",在任)").join("、") : "无"));
     out.push("沉默   " + skipProjects.size + " 个项目，跳过 " + scan.skip.length + " 个会话（不唤醒，省 token）");
-    if (scan.hot.length) out.push("预警   " + scan.hot.length + " 个会话已进预警区（≥" + Math.round(scan.warn) + "%）—— 全为退场、前任则可忽略");
+    if (scan.hot.length) out.push("预警   " + scan.hot.length + " 个会话已进预警区（≥" + Math.round(scan.warn) + "%）—— 全为已交出的旧会话则可忽略");
   }
   if (input.drift) {
     out.push('Δ交接  ' + driftVerdict(input.drift));
@@ -69,6 +69,6 @@ export function composeBrief(input) {
     out.push('Δ交接  读不到（会话日志不可用）');
   }
   if (input.advice && input.advice.text) out.push('阶段   ' + input.advice.text);
-  out.push('提示   ' + (input.ok ? '按「活跃」名单逐个 peer_send 广播本会话 id 并记回 §3；可正常开始作业' : '本会话已过阈值或闸门异常，应先收齐交接，再开展新任务'));
+  out.push('提示   ' + (input.ok ? '按「活跃」名单逐个用 peer（action="send"）广播本会话 id 并记回 §3；可正常开始作业' : '本会话已过阈值或闸门异常，应先收齐交接，再开展新任务'));
   return out;
 }

package/src/lib/config.mjs

@@ -11,14 +11,14 @@ export const DEFAULTS = {
   rolesPath: '',           // 留空 = ~/.dsh/storages/dsh-handover.roles.json
   // 续跑提示：{n} {max} {handover} {role} 会被替换成真值；{handover} 是本会话自己的交接绝对路径。
   // 只在助手登记压缩时选 resume=continue（默认）才投递；resume=wait 表示已收尾，不唤醒。
-  resumePrompt: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。第一步：ho_handover(action=read) 取回本会话的交接（{handover}）；然后按 §2「下一步」继续（若 §2 已无待办，向用户一句话收尾并停止）。不要复述交接内容，不要重做已完成的事。完整流程：ho_charter(doc="runtime")。',
+  resumePrompt: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。第一步：ho_handover(action=read) 取回本会话的交接（{handover}）；然后按 §2「下一步」继续（若 §2 已无待办，向当前用户一句话收尾并停止）。不要复述交接内容，不要重做已完成的事。完整流程：ho_charter(doc="runtime")。',
   resumePromptUnknown: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。本会话是普通会话，不参与交接；如需继续，请由全局会话为其指定角色。',
   compactTimeoutMs: 120000,
   compactAttempts: 3,
   waitIdleMs: 180000,      // 等会话空闲的上限（超过就放弃并回告）
   driftSlack: 3,           // Δ交接容忍轮数（超过即需刷交接）
-  wakeAuthority: 'on',     // 会话守卫硬拦：on / off（off＝连 peer_new 也不拦）
-  directPeer: 'on',        // 会话之间直接 peer_send：on 允许（不经全局转述）；off 退回「只能向全局报告」的旧口径
+  wakeAuthority: 'on',     // 会话守卫硬拦：on / off（off＝连 peer 的 new 动作也不拦）
+  directPeer: 'on',        // 会话之间直接 peer（action="send"）：on 允许（不经全局转述）；off 退回「只能向全局报告」的旧口径
   roleGating: 'on',        // 按角色裁剪工具与提示段：on / off（off＝所有会话都看得见全部工具）
   reuseCheck: true,        // 建新会话前查在任会话水位（低于 warnRatio 拒绝）
   prepackMinAgeMin: 90,    // 打包前要求会话静止分钟数

package/src/lib/consent.mjs

@@ -96,7 +96,7 @@ export function checkConsent(sessionId, kind) {
     return {
       ok: false,
       kind: k,
-      reason: k === 'succeed' ? '用户还没有授权换任（聊天页命令 /allow-succeed）' : '用户还没有在设置页点「允许压缩」',
+      reason: k === 'succeed' ? '当前用户还没有授权换任（聊天页命令 /allow-succeed）' : '当前用户还没有在设置页点击「授权压缩」',
     };
   }
   return { ok: true, kind: k, until: hit.until, leftMs: hit.until - now, atText: hit.atText || '' };
@@ -121,3 +121,56 @@ export function listConsent() {
   })).filter((r) => r.leftMs > 0);
   return rows.sort((a, b) => a.sessionId.localeCompare(b.sessionId, 'zh') || a.kind.localeCompare(b.kind));
 }
+
+/**
+ * 某会话当前有效的授权（只读，不清过期条目）。
+ * 提示段与 ho_status 共用：授权一旦写入，下一轮重建提示段时就能看见；过期自然消失。
+ */
+export function activeConsentsFor(sessionId) {
+  const sid = String(sessionId || '');
+  if (!sid) return [];
+  const all = readAll();
+  const now = Date.now();
+  const rows = [];
+  for (const key of Object.keys(all)) {
+    const entry = all[key];
+    if (!entry || !entry.until || entry.until <= now) continue;
+    if (sidOfKey(key) !== sid) continue;
+    rows.push({
+      kind: kindOfEntry(key, entry),
+      until: entry.until,
+      leftMs: entry.until - now,
+      atText: entry.atText || '',
+      note: entry.note || '',
+    });
+  }
+  return rows.sort((a, b) => a.kind.localeCompare(b.kind));
+}
+
+const KIND_LABEL = { compact: '压缩', succeed: '换任' };
+
+function untilText(ms) {
+  const d = new Date(ms);
+  const off = -d.getTimezoneOffset();
+  const pad = (n) => String(n).padStart(2, '0');
+  const a = Math.abs(off);
+  return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate()) + ' '
+    + pad(d.getHours()) + ':' + pad(d.getMinutes()) + ' ' + (off >= 0 ? '+' : '-') + pad(Math.floor(a / 60)) + pad(a % 60);
+}
+
+/** 提示段用：每种有效授权一行，极短；无授权返回空数组（不占位）。 */
+export function consentPromptLines(rows) {
+  return (rows || []).map((r) => '当前用户已授权' + KIND_LABEL[r.kind] + '，至 ' + untilText(r.until) + '（一次性，用后失效）。');
+}
+
+/** ho_status 用：一行状态，压缩与换任各说一句，未授权的写「无授权」。 */
+export function formatConsentLine(rows) {
+  const hit = new Map((rows || []).map((r) => [r.kind, r]));
+  const parts = CONSENT_KINDS.map((k) => {
+    const r = hit.get(k);
+    if (!r) return KIND_LABEL[k] + ' 无授权';
+    const min = Math.max(1, Math.ceil(r.leftMs / 60000));
+    return KIND_LABEL[k] + ' 剩余 ' + min + ' 分钟（至 ' + untilText(r.until) + '，一次性）';
+  });
+  return parts.join('；');
+}

package/src/lib/docmap.mjs

@@ -0,0 +1,143 @@
+/**
+ * 文档定位 map（docmap）：每个会话（全局、每个项目、每个杂项任务）一份文件，写「本类别有哪些文档、各自一句话介绍、什么时候该读」。
+ *
+ * 定位：只指路，不规定读多少。是否读正文由被注入的会话自己判断；
+ * 空 map 不注入，提示段其余文字一字不动。文件放在 _Control_Center/records/docmap/，
+ * 随工作区迁移；写入者必须是在任会话（由 tools/ho_docmap.mjs 用在任登记表判定）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { NL, readUtf8, isFile, isDir } from './text.mjs';
+
+export const DOCMAP_DIR = path.join('_Control_Center', 'records', 'docmap');
+export const COLUMNS = ['路径', '一句话介绍', '何时读'];
+
+/** 由会话角色推导所属的登记（全局／项目／杂项）；普通会话没有 map。 */
+export function lineageOf(info) {
+  const role = info && info.role ? info.role : '';
+  if (role === 'global') return { kind: 'global', project: '', task: '', key: '全局' };
+  if (role === 'project' && info.project) return { kind: 'project', project: String(info.project), task: '', key: String(info.project) };
+  if (role === 'misc' && info.task) return { kind: 'misc', project: '', task: String(info.task), key: String(info.task) };
+  return null;
+}
+
+export function lineageLabel(info) {
+  const lin = lineageOf(info);
+  if (!lin) return '';
+  if (lin.kind === 'project') return '项目「' + lin.project + '」';
+  if (lin.kind === 'misc') return '杂项任务「' + lin.task + '」';
+  return '全局';
+}
+
+/** 文件名：global.md / project-<项目名>.md / misc-<任务名>.md（相对工作区根）。 */
+export function docmapRelPath(info) {
+  const lin = lineageOf(info);
+  if (!lin) return null;
+  const stem = lin.kind === 'global' ? 'global' : lin.kind === 'project' ? 'project-' + lin.project : 'misc-' + lin.task;
+  return path.join(DOCMAP_DIR, stem + '.md');
+}
+
+export function docmapAbsPath(ws, info) {
+  const rel = docmapRelPath(info);
+  return rel ? path.join(String(ws || ''), rel) : null;
+}
+
+function stripTicks(s) {
+  return String(s || '').replace(/`/g, '').trim();
+}
+
+/** 解析表格行：跳过表头与分隔行；三列之外的多余列合并进第三列。 */
+export function parseDocmap(text) {
+  const entries = [];
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line.startsWith('|')) continue;
+    const cells = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => stripTicks(c));
+    if (!cells.length) continue;
+    if (cells.length < 2) continue;
+    if (cells[0] === COLUMNS[0]) continue;                 // 表头
+    if (cells.every((c) => /^[-:\s]*$/.test(c))) continue;  // 分隔行
+    const p = cells[0];
+    if (!p) continue;
+    const about = cells[1] || '';
+    const when = cells.length > 3 ? cells.slice(2).join('，') : (cells[2] || '');
+    entries.push({ path: p, about, when });
+  }
+  return entries;
+}
+
+export function readDocmap(ws, info) {
+  const file = docmapAbsPath(ws, info);
+  if (!file) return { file: null, exists: false, entries: [] };
+  if (!isFile(file)) return { file, exists: false, entries: [] };
+  let text = '';
+  try { text = readUtf8(file); } catch { return { file, exists: true, entries: [], error: '读取失败' }; }
+  return { file, exists: true, entries: parseDocmap(text) };
+}
+
+/** 渲染文件正文（写盘用）：标题一行、表格、一句判定。 */
+export function renderDocmap(info, entries) {
+  const label = lineageLabel(info);
+  const lines = ['# 文档定位（' + label + '）', '', '| ' + COLUMNS.join(' | ') + ' |', '|' + COLUMNS.map(() => '---').join('|') + '|'];
+  for (const e of entries) lines.push('| `' + e.path + '` | ' + e.about + ' | ' + (e.when || '') + ' |');
+  lines.push('');
+  lines.push('只指路：是否读正文由你判断，不要无目的通读。');
+  return lines.join(NL) + NL;
+}
+
+/**
+ * 注入提示段的文本：空 map 返回空串（不占位）。
+ * 形如「文档定位（项目「X」；只指路…）」＋ 每条一行，路径加反引号。
+ */
+export function docmapBlock(ws, info) {
+  const map = readDocmap(ws, info);
+  if (!map.entries.length) return '';
+  const lines = ['文档定位（' + lineageLabel(info) + '；只指路，是否读正文由你判断，不要无目的通读）'];
+  for (const e of map.entries) {
+    lines.push('- ' + e.path + (e.about ? ' —— ' + e.about : '') + (e.when ? '（' + e.when + '）' : ''));
+  }
+  return lines.join(NL);
+}
+
+/** 路径是否合法且存在：只收工作区相对路径，不得越出工作区。 */
+export function pathProblem(ws, p) {
+  const raw = String(p || '').trim();
+  if (!raw) return '路径为空';
+  if (/^[a-zA-Z]:/.test(raw) || raw.startsWith('/') || raw.startsWith('\\')) return '要写工作区相对路径，不写绝对路径';
+  const norm = path.normalize(raw).replace(/\\/g, '/');
+  if (norm === '..' || norm.startsWith('../')) return '不得指向工作区之外';
+  const abs = path.join(String(ws || ''), norm);
+  if (!isFile(abs) && !isDir(abs)) return '不存在：' + norm;
+  return '';
+}
+
+/** 逐条校验：返回 [{ path, problem }]。 */
+export function validateEntries(ws, entries) {
+  const bad = [];
+  for (const e of entries) {
+    const problem = pathProblem(ws, e.path);
+    if (problem) bad.push({ path: e.path, problem });
+  }
+  return bad;
+}
+
+/** 闸门用：检查所有 map 的路径存在性（只判存在，不判字数）。 */
+export function checkDocmaps(ws) {
+  const dir = path.join(String(ws || ''), DOCMAP_DIR);
+  const rows = [];
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort(); } catch { return { dir, rows, missing: 0 }; }
+  for (const name of files) {
+    const file = path.join(dir, name);
+    const stem = name.slice(0, -3);
+    let info = null;
+    if (stem === 'global') info = { role: 'global' };
+    else if (stem.startsWith('project-')) info = { role: 'project', project: stem.slice(8) };
+    else if (stem.startsWith('misc-')) info = { role: 'misc', task: stem.slice(5) };
+    let entries = [];
+    try { entries = parseDocmap(readUtf8(file)); } catch { entries = []; }
+    const bad = validateEntries(ws, entries);
+    rows.push({ name, label: info ? lineageLabel(info) : '（文件名不符合规范）', entries: entries.length, bad });
+  }
+  return { dir, rows, missing: rows.reduce((a, r) => a + r.bad.length, 0) };
+}

package/src/lib/gates.mjs

@@ -4,6 +4,7 @@ import { readUtf8, isFile, isDir } from './text.mjs';
 import fs from 'node:fs';
 import { charterPath, canonicalBlock, TITLE_KEY, WATER_KEY } from './charter.mjs';
 import { readProfile, listProfiles } from './profile.mjs';
+import { checkDocmaps } from './docmap.mjs';
 
 /**
  * 读 Registry.md 的「形态」列 → { 项目名: 形态 }。
@@ -61,7 +62,6 @@ function libraryRoots(ws) {
   return out;
 }
 
-/** 同步复核：返回 { libraries, total, missing, verdict, ok }。 */
 /** 插件内置的 Charter 骨架（dist/templates/Charter.skeleton.md）；工作区那份只是覆盖。 */
 function bundledCharter() {
   try {
@@ -72,6 +72,7 @@ function bundledCharter() {
   }
 }
 
+/** 同步复核：返回 { libraries, total, missing, verdict, ok }。 */
 export function syncCheck(ws) {
   const charter = charterPath(ws);
   // 口径：**插件自带的这套默认规则才是本体**，工作区里的同名文件是「本地化覆盖」。
@@ -145,4 +146,27 @@ export function renderSyncCheck(res) {
   out.push('');
   out.push('判定：' + res.verdict);
   return out;
+}
+
+/** 文档定位 map：只检查表内路径是否仍然存在（不判字数、不判内容）。 */
+export function docmapReport(ws) {
+  return checkDocmaps(ws);
+}
+
+export function renderDocmapCheck(res) {
+  const out = [];
+  out.push('文档定位 map  目录 ' + res.dir);
+  if (!res.rows.length) {
+    out.push('  还没有任何 map（空 map 不注入提示段，属正常）');
+    out.push('判定：无需检查');
+    return out;
+  }
+  for (const r of res.rows) {
+    out.push('  ' + r.name + '  ' + r.label + '  ' + r.entries + ' 条  ' + (r.bad.length ? '失效 ' + r.bad.length + ' 条' : '路径全部存在'));
+    for (const b of r.bad.slice(0, 3)) out.push('        失效：' + b.path + ' —— ' + b.problem);
+  }
+  out.push('判定：' + (res.missing === 0
+    ? '全部落位。'
+    : res.missing + ' 条路径失效 —— 由该类别在任会话用 ho_docmap(action="write") 更新。'));
+  return out;
 }