@mingmaple/dsh-handover 0.9.13 → 0.9.22

package/src/tools/ho_checkpoint.mjs

@@ -18,17 +18,17 @@ export function pmCheckpointTool(env) {
       properties: {
         handover_text: { type: 'string', description: '要写入的交接正文；不给则要求磁盘上已有合格交接' },
         handover_path: { type: 'string', description: '覆盖交接路径（演练用）' },
-        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（默认）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等用户派新任务' },
+        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（默认）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等当前用户派新任务' },
         at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线～交接线之间只提醒、不压缩（过交接线仍会压）' },
         force: { type: 'boolean', description: '忽略关键步骤判定，直接排压缩' },
-        confirm: { type: 'boolean', description: '判定为「可压缩」后须经用户同意才传 true；还需用户在设置页点「允许压缩」（5 分钟一次性授权），否则不排压缩' },
+        confirm: { type: 'boolean', description: '判定为「可压缩」后须经当前用户同意才传 true；还需当前用户在设置页点击「授权压缩」（5 分钟一次性授权），否则不排压缩' },
       },
     },
     output: textOutput(),
     async execute(args, exec) {
       const ws = env.resolveWs(exec);
       const meId = env.selfId(exec);
-      if (!meId) throw new Error("拿不到本会话 id，无法调度压缩");
+      if (!meId) throw new Error("无法获取本会话 id，无法调度压缩");
       const info = env.roleOf(exec);
       const target = args.handover_path
         ? { path: args.handover_path, kind: info.role === 'project' ? 'project' : info.role === 'misc' ? 'misc' : 'global' }
@@ -46,6 +46,7 @@ export function pmCheckpointTool(env) {
       const self = env.selfPct(meId);
       const ratio = self === null ? null : self / 100;
       const out = [];
+      const ratioText = ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%';
       const recentSec = st && st.lastSummaryMs ? (Date.now() - st.lastSummaryMs) / 1000 : null;
       if (recentSec !== null && recentSec < 120 && args.force !== true) {
         out.push("拒绝排压缩：" + Math.round(recentSec) + " 秒前刚完成一次压缩（日志里有 compaction/summary），避免重复排程。");
@@ -54,7 +55,7 @@ export function pmCheckpointTool(env) {
       }
       if (count.lock === "open") {
         out.push("拒绝排压缩：检测到未闭合的压缩锁（compaction/start 无配对 end）。");
-        out.push("处理：等当前压缩结束后用 ho_phase 复查；若长时间不动，说明上次压缩崩在中间。");
+        out.push("处理：等当前压缩结束后用 ho_status 复查；若长时间不动，说明上次压缩崩在中间。");
         return { text: out.join(NL) };
       }
       const adv = decide({ ratio, compactionsUsed: count.used, cfg: env.cfg, lockState: count.lock });
@@ -69,15 +70,15 @@ export function pmCheckpointTool(env) {
         return { text: out.join(NL) };
       }
       if (adv.action === "continue" && args.force !== true) {
-        out.push("水位未到线（" + (ratio === null ? "读不到" : (Math.round(ratio * 1000) / 10).toFixed(1) + "%") + "）：不压。");
+        out.push("水位未到线（" + ratioText + "）：不压。");
         out.push("需要强制演练可加 force=true。");
         return { text: out.join(NL) };
       }
       // 判断逻辑不动；只有判定可以压缩之后，才停下来问用户。
       if (args.confirm !== true) {
         out.push('判定：可以压缩（' + adv.reason + '）。');
-        out.push('水位 ' + (ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%') + '，已压缩 ' + count.used + '/3。');
-        out.push('压缩会丢历史并自动续跑 —— 先问用户「要压缩吗？」，回答同意后再调 ho_checkpoint(confirm=true)；不同意就保持原样。');
+        out.push('水位 ' + ratioText + '，已压缩 ' + count.used + '/3。');
+        out.push('压缩会丢历史并自动续跑 —— 先问当前用户「要压缩吗？」，回答同意后再调 ho_checkpoint(confirm=true)；不同意就保持原样。');
         return { text: out.join(NL) };
       }
       let wrote = null;
@@ -105,8 +106,8 @@ export function pmCheckpointTool(env) {
       const cs = checkConsent(meId);
       if (!cs.ok) {
         out.push('交接已写好，但**没有排压缩**：' + cs.reason + '。');
-        out.push('授权方式（任选其一）：① 在聊天框发送 /allow-compact（最快，仅授权本会话）；② 在设置页的 dsh-handover 中点击「压缩授权」一次。授权有效期 5 分钟，其后须再调用 ho_checkpoint(confirm=true)。');
-        out.push('如此设限的原因：压缩会丢弃历史，而参数由 AI 自行填写——惟有用户在设置页当面点击的那一次，方视为同意。');
+        out.push('授权方式（任选其一）：① 在聊天框发送 /allow-compact（最快，仅授权本会话）；② 在设置页的 dsh-handover 中点击「授权压缩」一次。授权有效期 5 分钟，其后须再调用 ho_checkpoint(confirm=true)。');
+        out.push('如此设限的原因：压缩会丢弃历史，而参数由 AI 自行填写——惟有当前用户在设置页当面点击的那一次，方视为同意。');
         return { text: out.join(NL) };
       }
       // 成本提示：低于交接线强行压缩会白付一次摘要，且本轮前缀缓存失效。
@@ -118,12 +119,12 @@ export function pmCheckpointTool(env) {
       const n = count.used + 1;
       const resume = args.resume === 'wait' ? 'wait' : 'continue';
       env.schedule(meId, n, { resume });
-      out.push('用户已授权（' + cs.atText + ' 点击，剩 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
+      out.push('当前用户已授权（' + cs.atText + ' 点击，剩 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
       out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次）。本回合结束后执行。");
       if (resume === 'wait') {
         out.push("去向：wait —— 压缩完成后不会唤醒本会话，等你派新任务。");
       } else {
-        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内没有续跑消息，用 ho_phase 看状态。");
+        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内没有续跑消息，用 ho_status 看状态。");
       }
       out.push("压缩期间不要结束会话。");
       return { text: out.join(NL) };

package/src/tools/ho_docmap.mjs

@@ -0,0 +1,153 @@
+/**
+ * ho_docmap —— 本会话的文档定位 map（只指路，不规定读多少）。
+ *
+ * 写入范围由会话已登记的角色决定，不接受传入项目名或任务名：全局只写 global.md，
+ * 项目只写 project-<本项目>.md，杂项只写 misc-<本任务>.md。
+ * 写入者必须是在任会话（以 Office.json 为准）；已交出的旧会话只读。
+ * 不设字数上限；写盘前逐条校验路径存在，缺项整条拒绝并列出。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { loadOffice, lineageKeyOf } from '../lib/office.mjs';
+import {
+  lineageOf, lineageLabel, docmapRelPath, docmapAbsPath, readDocmap,
+  renderDocmap, validateEntries,
+} from '../lib/docmap.mjs';
+
+export const ACTIONS = ['read', 'write', 'check'];
+
+function ownLineage(env, exec) {
+  let info = null;
+  try { info = env.roleOf(exec); } catch { info = null; }
+  const lin = lineageOf(info);
+  return { info, lin };
+}
+
+function holderOf(ws, lin) {
+  try {
+    const store = loadOffice(ws);
+    const key = lineageKeyOf(lin.kind, lin.project, lin.task);
+    const row = store.lineages ? store.lineages[key] : null;
+    return { key, current: row && row.current ? row.current : null };
+  } catch {
+    return { key: '', current: null };
+  }
+}
+
+function entriesText(entries) {
+  if (!entries.length) return '（空 map：不注入提示段）';
+  return entries.map((e) => '- ' + e.path + (e.about ? ' —— ' + e.about : '') + (e.when ? '（' + e.when + '）' : '')).join(NL);
+}
+
+export function pmDocmapTool(env) {
+  return {
+    name: nameOf('docmap'),
+    description:
+      '本会话的文档定位：action=read 读、write 写（逐条校验路径存在）、check 查自己的 map；只指路，不规定读多少。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ACTIONS, description: '缺省 read' },
+        entries: {
+          type: 'array',
+          description: 'write：整份替换。每项 { path: 工作区相对路径, about: 一句话介绍, when: 何时读 }',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['path', 'about'],
+            properties: {
+              path: { type: 'string', description: '工作区相对路径，必须存在' },
+              about: { type: 'string', description: '一句话介绍' },
+              when: { type: 'string', description: '什么时候该读（可选，建议写）' },
+            },
+          },
+        },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const { info, lin } = ownLineage(env, exec);
+      if (!lin) throw new Error('本会话没有角色：文档定位只对全局、项目、杂项会话开放');
+      const action = typeof args.action === 'string' && args.action ? args.action : 'read';
+      if (ACTIONS.indexOf(action) === -1) throw new Error('action 只能是 ' + ACTIONS.join(' | ') + '（收到 ' + String(action) + '）');
+      const rel = docmapRelPath(info);
+      const abs = docmapAbsPath(ws, info);
+      const label = lineageLabel(info);
+
+      if (action === 'read') {
+        const map = readDocmap(ws, info);
+        const out = [];
+        out.push('文档定位（' + label + '）  ' + rel);
+        out.push(map.exists ? '状态  已设置，' + map.entries.length + ' 条' : '状态  未设置（空 map 不注入提示段）');
+        if (map.entries.length) out.push('', entriesText(map.entries));
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'check') {
+        const map = readDocmap(ws, info);
+        const bad = validateEntries(ws, map.entries);
+        const out = [];
+        out.push('文档定位体检（' + label + '）  ' + rel);
+        out.push(map.exists ? '条目 ' + map.entries.length + ' 条' : '未设置（空 map 不注入）');
+        for (const b of bad) out.push('  失效：' + b.path + ' —— ' + b.problem);
+        out.push(bad.length ? '判定：' + bad.length + ' 条失效，请更新 map。' : '判定：路径全部存在。');
+        return { text: out.join(NL) };
+      }
+
+      // action=write
+      const holder = holderOf(ws, lin);
+      const meId = String(env.selfId(exec) || '');
+      if (!holder.current) {
+        throw new Error('登记表里没有「' + (holder.key || label) + '」的在任记录：以在任记录为写入依据，先由全局完成登记');
+      }
+      if (!meId || String(holder.current.sessionId || '') !== meId) {
+        throw new Error('只有在任会话可以写：本条登记的在任会话为 ' + (holder.current.name || '?') + '（' + holder.current.sessionId + '），本会话为只读');
+      }
+      const list = Array.isArray(args.entries) ? args.entries : null;
+      if (!list) throw new Error('write 需要 entries 数组（每项 path、about、when）');
+      const entries = [];
+      for (const raw of list) {
+        const e = raw || {};
+        const p = String(e.path === undefined || e.path === null ? '' : e.path).trim();
+        const about = String(e.about === undefined || e.about === null ? '' : e.about).trim();
+        const when = String(e.when === undefined || e.when === null ? '' : e.when).trim();
+        if (!p) throw new Error('entries 里有空路径');
+        for (const [field, val] of [['path', p], ['about', about], ['when', when]]) {
+          if (val.indexOf('|') !== -1) throw new Error(field + ' 里不能出现竖线「|」（表格分隔符）：' + val);
+          if (val.indexOf(String.fromCharCode(10)) !== -1) throw new Error(field + ' 里不能换行');
+        }
+        entries.push({ path: p, about, when });
+      }
+      const bad = validateEntries(ws, entries);
+      if (bad.length) {
+        const lines = ['未写入：下列路径不存在或不合法，逐条修正后重试。'];
+        for (const b of bad) lines.push('  - ' + b.path + '：' + b.problem);
+        lines.push('路径一律写工作区相对路径（例：Projects/<项目>/SKILL.md）。');
+        throw new Error(lines.join(NL));
+      }
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      let backup = '';
+      if (fs.existsSync(abs)) {
+        backup = abs + '.bak';
+        try { fs.copyFileSync(abs, backup); } catch { backup = ''; }
+      }
+      const body = renderDocmap(info, entries);
+      const tmp = abs + '.tmp-' + process.pid;
+      fs.writeFileSync(tmp, body, 'utf8');
+      fs.renameSync(tmp, abs);
+      let refreshed = false;
+      try { if (typeof env.refreshPromptFor === 'function') refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+      const out = [];
+      out.push('已写入 ' + rel + '（' + entries.length + ' 条）' + (backup ? '；原文件备份为 ' + path.basename(backup) : ''));
+      out.push(refreshed ? '提示段已重装：下一轮即按新 map 注入。' : '提示段未能在本进程重装：重启 DSH 或让会话重建后生效。');
+      out.push('建议精炼：每条一句介绍、一句时机即可；不设字数上限，但太长的介绍会挤占提示段。');
+      if (!entries.length) out.push('空 map：不注入提示段（相当于撤销）。');
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_gate.mjs

@@ -4,7 +4,7 @@ import { nameOf } from '../lib/names.mjs';
 import fs from 'node:fs';
 import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
-import { syncCheck, renderSyncCheck } from '../lib/gates.mjs';
+import { syncCheck, renderSyncCheck, docmapReport, renderDocmapCheck } from '../lib/gates.mjs';
 import { lintGlobal, lintProject, renderLintGlobal, renderLintProject } from '../lib/lint.mjs';
 import { SETUP_STEPS } from '../lib/guide.mjs';
 
@@ -53,6 +53,7 @@ export function pmGateTool(env) {
         }
         out.push(renderSyncCheck(g).join(NL));
         out.push(renderLintProject(null, lintAllProjects(ws)).join(NL));
+        out.push(renderDocmapCheck(docmapReport(ws)).join(NL));
       } else if (scope === "project") {
         const name = args.project;
         if (!name) throw new Error("scope=project 时必须给 project 参数");

package/src/tools/ho_office.mjs

@@ -13,7 +13,7 @@ export function pmOfficeTool(env) {
       type: 'object',
       additionalProperties: false,
       properties: {
-        query: { type: 'string', description: '要查的名字，如「全局」「全局3」「Mingent」「抢名额脚本」；多个用空格或逗号分隔；留空＝列出全部在任' },
+        query: { type: 'string', description: '要查的名字，如「全局」「全局3」「Demo1」「示例任务」；多个用空格或逗号分隔；留空＝列出全部在任' },
         json: { type: 'boolean', description: 'true 时输出机器可读 JSON（供脚本解析）' },
       },
     },

package/src/tools/ho_sessions.mjs

@@ -2,7 +2,6 @@
 import { textOutput } from '../lib/output.mjs';
 import { nameOf } from '../lib/names.mjs';
 import { NL } from '../lib/text.mjs';
-import path from 'node:path';
 import { scanSessions } from '../lib/sessions.mjs';
 import { syncCheck } from '../lib/gates.mjs';
 import { stamp } from '../lib/brief.mjs';
@@ -37,9 +36,9 @@ function list(env, args, exec) {
   }
   const notifProjects = new Set(scan.notify.map((r) => r.project));
   const skipProjects = new Set(scan.skip.map((r) => r.project));
-  out.push("通知判定：活跃项目 " + notifProjects.size + " 个，需要通知 " + scan.notify.length + " 个会话（仅各项目在任）/ 沉默项目 " + skipProjects.size + " 个，跳过 " + scan.skip.length + " 个会话（沉默项目全部＋前任）");
+  out.push("通知判定：活跃项目 " + notifProjects.size + " 个，需要通知 " + scan.notify.length + " 个会话（仅各项目在任）/ 沉默项目 " + skipProjects.size + " 个，跳过 " + scan.skip.length + " 个会话（沉默项目全部＋已交出的旧会话）");
   for (const r of scan.notify) out.push("  要通知【在任】" + r.project + "(" + r.sid + ")  最后活动 " + stamp(r.mtime));
-  if (scan.skip.length) out.push("  跳过（沉默项目，含其前任）：" + scan.skip.map((x) => x.project + "(" + x.sid.slice(-8) + ")").join("、"));
+  if (scan.skip.length) out.push("  跳过（沉默项目，含其已交出的旧会话）：" + scan.skip.map((x) => x.project + "(" + x.sid.slice(-8) + ")").join("、"));
   const gate = syncCheck(env.resolveWs(exec));
   if (gate.error) out.push("通用约束条闸门（Charter §7.2.3）：读不到 §8.1.1.4 正文 —— 请人工核 " + gate.path);
   else if (!gate.ok) {
@@ -85,7 +84,7 @@ export function pmSessionsTool(env) {
         sessionId: { type: 'string', description: 'prompt：新会话自己的 id' },
         globalSessionId: { type: 'string', description: 'prompt：现任全局 id' },
         extra: { type: 'string', description: 'prompt 附加一句；order 时作为「全局附加」拼进指令' },
-        confirm: { type: 'boolean', description: 'new、order 需要用户明确同意后传 true；否则只报错、不做任何事' },
+        confirm: { type: 'boolean', description: 'new、order 需要当前用户明确同意后传 true；否则只报错、不做任何事' },
       },
     },
     output: textOutput(),

package/src/tools/ho_status.mjs

@@ -0,0 +1,246 @@
+/**
+ * ho_status —— 会话状态：一个入口，按 view 分流。
+ *   phase（默认）：水位、压缩次数、锁、建议动作
+ *   brief：水位、闸门、会话清点、交接漂移、阶段建议
+ *   diag：服务可解析性、调度器、初始化错误、角色与工具集
+ *   drift：交接漂移体检
+ *   tokens：按会话 id 统计轮数、步数、每步 token
+ * 全部只读；原 ho_phase、ho_brief、ho_diag、ho_drift、ho_tokens 合并于此。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL, pick } from '../lib/text.mjs';
+import { syncCheck } from '../lib/gates.mjs';
+import { scanSessions, readSelfPressure } from '../lib/sessions.mjs';
+import { composeBrief } from '../lib/brief.mjs';
+import { decide } from '../lib/phase.mjs';
+import { computeDrift, driftVerdict } from '../lib/drift.mjs';
+import { watermark } from '../lib/facts.mjs';
+import { eventsOf, countCompactions } from '../lib/events.mjs';
+import { findLog, decodeLog, turnStarts } from '../lib/zstd-log.mjs';
+import { activeConsentsFor, formatConsentLine } from '../lib/consent.mjs';
+
+export const VIEWS = ['phase', 'brief', 'diag', 'drift', 'tokens'];
+
+function analyzeLog(records) {
+  const turns = turnStarts(records).length;
+  let steps = 0, outTok = 0, maxResult = 0, toolResults = 0;
+  const perTurn = new Map();
+  for (const r of records) {
+    if (!r || !r.type) continue;
+    if (r.type === 'step/start') {
+      steps++;
+      const t = pick(r, 'data', 'turn');
+      if (typeof t === 'number') perTurn.set(t, (perTurn.get(t) || 0) + 1);
+    } else if (r.type === 'assistant/message') {
+      const u = pick(r, 'data', 'usage');
+      if (u && typeof u.outputTokens === 'number') outTok += u.outputTokens;
+    } else if (r.type === 'tool/result') {
+      toolResults++;
+      try { const len = JSON.stringify(pick(r, 'data') || '').length; if (len > maxResult) maxResult = len; } catch { /* ignore */ }
+    }
+  }
+  const heavyTurns = Array.from(perTurn.values()).filter((n) => n > 20).length;
+  return { turns, steps, outTok, maxResult, toolResults, heavyTurns, perStep: steps ? Math.round(outTok / steps) : 0 };
+}
+
+/** 授权状态行：压缩与换任各一句，未授权写「无授权」。 */
+function consentLine(meId) {
+  try { return formatConsentLine(activeConsentsFor(meId)); } catch { return ''; }
+}
+
+function phaseText(env, args, exec) {
+  const meId = env.selfId(exec);
+  const real = env.selfPct(meId);
+  const ratio = typeof args.simulateRatio === 'number' ? args.simulateRatio : (real === null ? null : real / 100);
+  const count = env.compactionCount(exec);
+  const lock = env.lockState(exec);
+  const adv = decide({ ratio, compactionsUsed: count.used, cfg: env.cfg, lockState: lock });
+  const out = [];
+  out.push('会话      ' + (meId || '未知'));
+  out.push('水位      ' + (ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%')
+    + (typeof args.simulateRatio === 'number' ? '  （演练模拟值）' : '')
+    + (typeof env.staleNote === 'function' ? env.staleNote(exec) : ''));
+  out.push('压缩      ' + count.used + '/' + env.cfg.maxCompactions + ' 次' + (count.note ? '  ' + count.note : ''));
+  out.push('锁        ' + lock);
+  out.push('建议      ' + adv.action + ' —— ' + adv.reason);
+  const c = consentLine(meId);
+  if (c) out.push('授权      ' + c);
+  return out;
+}
+
+function briefText(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const w = watermark(env.cfg);
+  const warn = typeof args.threshold === 'number' ? args.threshold : w.warnValue;
+  const gate = syncCheck(ws);
+  const meId = env.selfId(exec);
+  const self = readSelfPressure(env.cacheDir(), meId);
+  const scan = scanSessions({
+    dir: env.cacheDir(),
+    meId,
+    meCwd: env.selfCwd(exec),
+    warn,
+    silentHours: env.cfg.sessionScanHours,
+  });
+  const drift = computeDrift({ ws, cacheDir: env.cacheDir(), slack: env.cfg.driftSlack, all: false });
+  const ratio = self.used === null || self.win === null ? null : self.used / self.win;
+  const adv = decide({ ratio, compactionsUsed: 0, cfg: env.cfg, lockState: 'unknown' });
+  const selfPct = self.used === null || self.win === null ? null : (self.used / self.win) * 100;
+  const ok = gate.ok && (selfPct === null || selfPct < warn);
+  const lines = composeBrief({
+    cfg: env.cfg,
+    selfUsed: self.used,
+    selfWin: self.win,
+    gate,
+    scan,
+    drift,
+    advice: { text: adv.action + ' —— ' + adv.reason },
+    ok,
+  });
+  const c = consentLine(meId);
+  if (c) lines.push('授权   ' + c);
+  return lines;
+}
+
+function diagText(env, state, exec) {
+  const out = [];
+  const meId = env.selfId(exec);
+  out.push('会话      ' + (meId || '?'));
+  if (typeof env.version === 'function') out.push('版本      ' + env.version());
+  out.push('调度器    ' + (state.schedulerReady() ? '就绪' : '未就绪' + (state.schedulerError() ? '：' + state.schedulerError() : '（稍后重试或重启）')));
+  if (typeof env.injectList === 'function') out.push('inject    ' + env.injectList().join(' / '));
+  if (typeof env.initErrors === 'function') {
+    const errs = env.initErrors();
+    out.push('初始化    ' + (errs.length ? '有 ' + errs.length + ' 处失败：' + errs.join('；') : '无错误'));
+  }
+  if (typeof env.probeServices === 'function') {
+    const svc = env.probeServices();
+    out.push('服务      ' + Object.keys(svc).map((k) => k + '=' + (svc[k] ? '可用' : '—')).join('  '));
+  }
+  if (typeof env.guardLast === 'function') {
+    const g = env.guardLast();
+    out.push('通信判定  ' + (g
+      ? (g.allow ? '放行' : '拦截') + ' · 依据 ' + g.source + (g.title ? ' · 标题 ' + g.title : '') + ' · 会话 ' + g.sid
+      : '本进程还没有 peer（action="send"、"new"）调用'));
+  }
+  if (typeof env.probeAgentScope === 'function') {
+    const a = env.probeAgentScope(exec);
+    const show = ['compaction', 'compactNow', 'tokenMeter', 'sessions', 'llm', 'agents']
+      .map((k) => k + '=' + (a[k] ? '可用' : '—')).join('  ');
+    out.push('会话作用域 ' + (a.ctx ? show : '无法获取 exec.agent.ctx'));
+  }
+  const st = typeof env.compactionState === 'function'
+    ? env.compactionState(exec)
+    : (() => { const c = countCompactions(eventsOf(exec)); return { used: c.used, lock: c.lock, source: 'events' }; })();
+  out.push('压缩      ' + st.used + '/' + env.cfg.maxCompactions + ' 次；锁 ' + st.lock + '；来源 ' + st.source);
+  const pct = env.selfPct(meId);
+  out.push('水位      ' + (pct === null ? '读不到' : pct.toFixed(1) + '%') + (typeof env.staleNote === 'function' ? env.staleNote(exec) : ''));
+  const ws = env.resolveWs(exec);
+  let wsOk = false;
+  try { wsOk = fs.existsSync(path.join(ws, '_Control_Center')); } catch { wsOk = false; }
+  if (typeof env.roleOf === 'function') {
+    try {
+      const info = env.roleOf(exec);
+      const ts = typeof env.toolsetOf === 'function' ? env.toolsetOf(info.role) : null;
+      out.push('角色      ' + info.role + (info.project ? '（项目 ' + info.project + '）' : info.task ? '（任务 ' + info.task + '）' : '') + ' · 依据 ' + info.source + (ts ? ' · 可见工具 ' + ts.allow.length + '/' + (ts.allow.length + ts.deny.length) : ''));
+      if (typeof env.roleState === 'function') {
+        const rs = env.roleState();
+        const cnt = typeof rs.count === 'number' ? ' · 已装配 ' + rs.count + ' 个会话' : '';
+        out.push('角色装配  ' + (rs.mode || '未知') + cnt + (rs.last ? ' · 最近：' + rs.last.sid + ' → ' + rs.last.role + '（' + rs.last.at + '）' : ''));
+      }
+    } catch (e) {
+      out.push('角色      判定失败：' + (e && e.message ? e.message : e));
+    }
+  }
+  out.push('工作区    ' + ws + (wsOk
+    ? '  已接入'
+    : '  — 未接入（未找到 _Control_Center）：让当前用户走设置页「首次安装」，或本会话直接 ho_workspace(action="init", parent="<目录>", register=true)'));
+  try {
+    const mv = typeof env.moveInfo === 'function' ? env.moveInfo() : null;
+    if (mv) out.push('迁移      ' + mv.phase + ' · ' + mv.src + (mv.dst ? '  →  ' + mv.dst : ''));
+  } catch { /* ignore */ }
+  out.push('配置      warn=' + env.cfg.warnRatio + ' handover=' + env.cfg.handoverRatio + ' hard=' + env.cfg.hardRatio + ' max=' + env.cfg.maxCompactions);
+  if (typeof env.handoverFor === 'function') {
+    try {
+      const hp = env.handoverFor(exec);
+      out.push('交接路径  ' + (hp && hp.path ? hp.path + '（' + hp.kind + '）' : '无 —— ' + ((hp && hp.reason) || '角色未定')));
+    } catch (e) {
+      out.push('交接路径  解析失败：' + (e && e.message ? e.message : e));
+    }
+  } else {
+    out.push('交接路径  ' + (env.cfg.handoverPath || '（按角色解析）'));
+  }
+  return out;
+}
+
+function driftText(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const res = computeDrift({
+    ws,
+    cacheDir: env.cacheDir(),
+    slack: typeof args.slack === 'number' ? args.slack : env.cfg.driftSlack,
+    all: args.all === true,
+  });
+  const out = [];
+  out.push('交接匹配检查（跟着交接走；冗余 ' + res.slack + ' 轮）  工作区根 ' + ws);
+  out.push('  项目  会话类型 会话  当前轮  交接轮  Δ  判定');
+  for (const r of res.rows) {
+    const cells = [r.project, r.kind, r.sid.slice(-8), String(r.turns), r.handoverTurn === null ? '?' : String(r.handoverTurn), r.delta === null ? '?' : String(r.delta), r.verdict];
+    out.push('  ' + cells.join('  '));
+  }
+  if (!res.rows.length) out.push('  读不到任何项目会话（Projects/ 下对应库不存在时属正常）');
+  out.push(driftVerdict(res));
+  return out;
+}
+
+function tokensText(args) {
+  const out = [];
+  const list = Array.isArray(args.sessions) ? args.sessions.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+  if (!list.length) throw new Error('view=tokens 时 sessions 不能为空（给会话 id 数组）');
+  out.push('会话 轮 步 输出tok 每步tok 最贵返回 超20步轮 判定');
+  for (const sid of list) {
+    const full = sid.indexOf('session-') === 0 ? sid : 'session-' + sid;
+    const log = findLog(full);
+    if (!log) { out.push(sid + '  ERR 日志找不到'); continue; }
+    const recs = decodeLog(log);
+    if (!recs) { out.push(sid + '  ERR 日志解不出'); continue; }
+    const m = analyzeLog(recs);
+    const verdict = m.perStep > 2000 ? '偏贵（每步 >2k）' : m.heavyTurns > 0 ? '有超 20 步的轮' : '正常';
+    out.push([sid.slice(-8), m.turns, m.steps, m.outTok, m.perStep, Math.round(m.maxResult / 1024) + 'KB', m.heavyTurns, verdict].join('  '));
+  }
+  return out;
+}
+
+export function pmStatusTool(env, state) {
+  const w = watermark(env.cfg);
+  return {
+    name: nameOf('status'),
+    description:
+      '会话状态（只读）：view=phase 水位与建议（默认）、brief 起始简报、diag 插件自检、drift 交接漂移、tokens token 体检。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        view: { type: 'string', enum: VIEWS, description: '缺省 phase' },
+        threshold: { type: 'number', description: 'view=brief：预警阈值百分比（默认 ' + w.warnValue + '）' },
+        simulateRatio: { type: 'number', description: 'view=phase：演练用比例替代真实水位（0-1），不写任何状态' },
+        sessions: { type: 'array', items: { type: 'string' }, description: 'view=tokens：会话 id 列表' },
+        slack: { type: 'number', description: 'view=drift：容忍轮数（默认 3）' },
+        all: { type: 'boolean', description: 'view=drift：列全部会话，而不只是每个项目的在任会话' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const view = typeof args.view === 'string' && args.view ? args.view : 'phase';
+      if (VIEWS.indexOf(view) === -1) throw new Error('view 只能是 ' + VIEWS.join(' | ') + '（收到 ' + String(view) + '）');
+      if (view === 'phase') return { text: phaseText(env, args, exec).join(NL) };
+      if (view === 'brief') return { text: briefText(env, args, exec).join(NL) };
+      if (view === 'diag') return { text: diagText(env, state, exec).join(NL) };
+      if (view === 'drift') return { text: driftText(env, args, exec).join(NL) };
+      return { text: tokensText(args).join(NL) };
+    },
+  };
+}

package/src/tools/ho_succeed.mjs

@@ -7,7 +7,7 @@ export function pmSucceedTool(env) {
   return {
     name: nameOf('succeed'),
     description:
-      '换任：校验本会话交接，建接任会话并登记在任；须用户先授权（/allow-succeed）。',
+      '换任：校验本会话交接，建接任会话并登记在任；须当前用户先授权（/allow-succeed）。',
     parameters: {
       type: 'object',
       additionalProperties: false,