@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/lib/names.mjs

@@ -0,0 +1,33 @@
+/**
+ * 工具名集中管理：ho_* 由 PREFIX 与 KEYS 生成，peer_* 由 PEER_KEYS 生成。
+ * 工具文件一律用 nameOf、peerNameOf 取名，index.mjs 启动时校验位置表，改名只需改这里。
+ */
+const PREFIX = 'ho';
+
+export const nameOf = (key) => PREFIX + '_' + key;
+
+/**
+ * ho_* 16 个。合并过的家族（刻意保持旧名，参数里用 action 分流）：
+ *   ho_pack     —— 打包 / 校验 / 预演 / 恢复（原 ho_pack_verify、ho_pack_restore、ho_pack_precheck）
+ *   ho_sessions —— 清点 / 设定角色 / 建会话 / 出提示词 / 归档 / 解归档（原 ho_session_new、ho_prompt、ho_session_archive、ho_session_unarchive）
+ *   ho_profile  —— 骨架读取 / 注册 / 校验 / 预设
+ */
+const KEYS = [
+  'brief', 'gate', 'sessions', 'phase', 'charter',
+  'handover', 'checkpoint', 'snapshot', 'diag',
+  'drift', 'changelog', 'tokens',
+  'pack', 'workspace', 'init', 'profile',
+];
+
+export const NAMES = KEYS.reduce((acc, k) => { acc[k] = nameOf(k); return acc; }, {});
+
+export const TOOL_NAMES = KEYS.map((k) => NAMES[k]);
+
+/** 平级会话工具：名字固定为 peer_*，不走 PREFIX。 */
+export const peerNameOf = (key) => 'peer_' + key;
+
+const PEER_KEYS = ['list', 'status', 'send', 'new', 'rename', 'peek'];
+
+export const PEER_NAMES = PEER_KEYS.map((k) => peerNameOf(k));
+
+export const ALL_TOOL_NAMES = TOOL_NAMES.concat(PEER_NAMES);

package/src/lib/output.mjs

@@ -0,0 +1,11 @@
+export function textOutput() {
+  return {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { text: { type: 'string' } },
+      required: ['text'],
+    },
+    render: (_a, value) => [{ type: 'text', text: String(value.text) }],
+  };
+}

package/src/lib/pack-ops.mjs

@@ -0,0 +1,329 @@
+/**
+ * 打包、校验、预演、恢复的实现（原 ho_pack / ho_pack_verify / ho_pack_restore / ho_pack_precheck 的代码搬到这里）。
+ * 对外只经 ho_pack(action=…) 暴露，少 3 份 schema 的固定开销。
+ * 共同口径：只报告绝对路径、不改写文件内容；恢复默认预演、覆盖前备份、从不删除目标文件。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { NL, isDir, isFile } from './text.mjs';
+import { sevenZipBin, pack as z7pack, test as z7test, extract } from './sevenzip.mjs';
+import { packDirTarGz, listTarGz, extractTarGz, detectFormat, safeRel } from './archive.mjs';
+import { scanAbsoluteRefs, renderAbsoluteRefs } from './absrefs.mjs';
+import { stampTz } from './brief.mjs';
+import { scanSessions } from './sessions.mjs';
+import { lintProject } from './lint.mjs';
+
+const SKIP_DIRS = ['__pycache__', '.git', 'node_modules', '.obsidian'];
+const SKIP_FILES = ['.DS_Store', 'Thumbs.db'];
+
+/**
+ * 选归档格式：auto（有 7-Zip 用 7z，否则用内置 tar.gz）、7z、tar。
+ * 内置归档器是**功能等价**的兜底：空白机器上没有 7-Zip 也必须能打包、校验、恢复。
+ */
+function chooseFormat(args, cfg) {
+  const want = String((args && args.format) || (cfg && cfg.packFormat) || 'auto').toLowerCase();
+  if (want === '7z') {
+    const bin = sevenZipBin(cfg && cfg.sevenZipPath);
+    if (!bin) throw new Error('指定了 format=7z，但本机没有 7-Zip。去掉 format 用 auto，或写 format="tar" 用内置归档器。');
+    return { fmt: '7z', bin };
+  }
+  if (want === 'tar' || want === 'targz' || want === 'tar.gz') return { fmt: 'tar', bin: '' };
+  const bin = sevenZipBin(cfg && cfg.sevenZipPath);
+  return bin ? { fmt: '7z', bin } : { fmt: 'tar', bin: '' };
+}
+
+/** 解包到 dir（按魔数判断格式，不看扩展名）。返回 { code, out }。 */
+function unpack(packPath, dir) {
+  const fmt = detectFormat(packPath);
+  if (fmt === 'targz') {
+    try {
+      const r = extractTarGz(packPath, dir);
+      const out = 'tar.gz 解包：写入 ' + r.written + ' 个文件、' + r.dirs + ' 个目录' + (r.skipped.length ? '；跳过 ' + r.skipped.length + ' 条（' + r.skipped[0] + '）' : '');
+      return { code: 0, out };
+    } catch (e) {
+      return { code: -1, out: 'tar.gz 解包失败：' + (e && e.message ? e.message : e) };
+    }
+  }
+  if (fmt === '7z') {
+    const bin = sevenZipBin('');
+    if (!bin) return { code: -1, out: '这个包是 7z 格式，但本机没有 7-Zip；装一个 7-Zip，或改用 tar.gz 包。' };
+    fs.mkdirSync(dir, { recursive: true });
+    return run7zSafe(bin, packPath, dir);
+  }
+  return { code: -1, out: '认不出包格式（既不是 7z 魔数也不是 gzip）：' + packPath };
+}
+
+/** 包内路径必须相对且不越界：拒绝绝对路径、盘符、..（防止恢复时写到目标目录之外）。 */
+function unsafeManifestPaths(manifest) {
+  const files = Array.isArray(manifest && manifest.files) ? manifest.files : [];
+  const bad = [];
+  for (const f of files) {
+    const rel = safeRel(f && f.path);
+    if (rel === null) bad.push(String(f && f.path));
+  }
+  return bad;
+}
+
+function run7zSafe(bin, packPath, dir) {
+  try {
+    return extract(bin, packPath, dir);
+  } catch (e) {
+    return { code: -1, out: String(e && e.message ? e.message : e) };
+  }
+}
+
+export function stampNow() {
+  const d = new Date();
+  const p = (n) => (n < 10 ? '0' + n : '' + n);
+  return d.getFullYear() + p(d.getMonth() + 1) + p(d.getDate()) + '-' + p(d.getHours()) + p(d.getMinutes());
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function walk(root, rel, out) {
+  let names = [];
+  try { names = fs.readdirSync(path.join(root, rel)); } catch { return out; }
+  for (const name of names) {
+    const abs = path.join(root, rel, name);
+    const r = rel ? rel + '/' + name : name;
+    let st;
+    try { st = fs.statSync(abs); } catch { continue; }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.indexOf(name) !== -1) continue;
+      walk(root, r, out);
+    } else if (st.isFile()) {
+      if (SKIP_FILES.indexOf(name) !== -1) continue;
+      if (name.endsWith('.pyc')) continue;
+      out.push({ rel: r, abs, bytes: st.size });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- action: check
+
+export function packCheck(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const items = Array.isArray(args.items) && args.items.length ? args.items : [];
+  if (!items.length) throw new Error('action=check 需要 items（项目名列表，写 global 表示全局）');
+  const minAge = (typeof args.min_age_min === 'number' ? args.min_age_min : (env.cfg.prepackMinAgeMin || 90)) * 60000;
+  const now = Date.now();
+  const scan = scanSessions({ dir: env.cacheDir(), meId: env.selfId(exec), warn: 32, silentHours: env.cfg.sessionScanHours });
+  const out = [];
+  let bad = 0;
+  for (const item of items) {
+    const why = [];
+    if (item !== 'global') {
+      const live = scan.rows.filter((r) => r.project === item);
+      if (live.length) {
+        const best = live.slice().sort((a, b) => b.mtime - a.mtime)[0];
+        if (best.state === 'running') why.push('会话 ' + best.sid + ' 正在跑');
+        if (now - best.mtime < minAge) why.push('最后活动距今 ' + Math.round((now - best.mtime) / 60000) + ' 分钟 < ' + Math.round(minAge / 60000));
+      }
+      const hand = path.join(ws, '_Project_Meta', item, 'Handover.md');
+      if (!isFile(hand)) why.push('缺交接：' + hand);
+      else {
+        const r = lintProject(hand);
+        if (r.verdict !== '通过' && r.verdict !== '缺节') why.push('交接体检 ' + r.verdict + (r.reasons.length ? '：' + r.reasons[0] : ''));
+      }
+    } else {
+      const hand = path.join(ws, '_Control_Center', 'records', 'Global_Handover.md');
+      if (!isFile(hand)) why.push('缺全局交接');
+    }
+    if (why.length) { bad++; out.push('未通过 ' + item + '：' + why.join('；')); }
+    else out.push('通过 ' + item + '：可打包');
+  }
+  out.push(bad ? '判定：' + bad + ' 项未就绪，应待会话静止并补齐交接后再打包' : '判定：全部就绪，可以打包');
+  return out.join(NL);
+}
+
+// ---------------------------------------------------------------- action: pack
+
+export function packNow(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const kind = args.kind || 'global';
+  const name = args.name || '';
+  const roots = [];
+  if (kind === 'global') {
+    roots.push(['_Control_Center', path.join(ws, '_Control_Center')]);
+    roots.push(['_Project_Meta', path.join(ws, '_Project_Meta')]);
+  } else if (kind === 'project') {
+    if (!name) throw new Error('kind=project 需要 name');
+    roots.push(['Projects/' + name, path.join(ws, 'Projects', name)]);
+    roots.push(['_Project_Meta/' + name, path.join(ws, '_Project_Meta', name)]);
+    roots.push(['_Archives/' + name + '/Handover', path.join(ws, '_Archives', name, 'Handover')]);
+  } else if (kind === 'task') {
+    if (!name) throw new Error('kind=task 需要 name');
+    roots.push(['_Misc/tasks/' + name, path.join(ws, '_Misc', 'tasks', name)]);
+  } else throw new Error('未知 kind：' + kind);
+  const entries = [];
+  for (const [label, abs] of roots) {
+    if (!isDir(abs)) continue;
+    for (const it of walk(abs, '', [])) entries.push({ rel: label + '/' + it.rel, abs: it.abs, bytes: it.bytes });
+  }
+  if (!entries.length) throw new Error('没有可打包的文件：' + roots.map((r) => r[0]).join('、'));
+  const total = entries.reduce((a, b) => a + b.bytes, 0);
+  const out = [];
+  out.push('目标 ' + kind + (name ? ':' + name : '') + ' → ' + entries.length + ' 个文件 / ' + (total / 1048576).toFixed(2) + ' MB');
+  if (args.dry_run) {
+    for (const e of entries.slice(0, 20)) out.push('  ' + e.rel + '  ' + e.bytes + ' B');
+    const pre = scanAbsoluteRefs(ws, entries.map((e) => e.rel));
+    out.push(...renderAbsoluteRefs(pre, { title: '绝对路径体检（源目录）', max: 5 }));
+    out.push('（dry_run：不打包）');
+    return out.join(NL);
+  }
+  const stamp = stampNow();
+  const label = kind === 'global' ? '全局' : name;
+  const stagingRoot = path.join(ws, '_Temp', '_Global', 'Scratch', 'pack-' + stamp);
+  const payload = path.join(stagingRoot, 'payload');
+  const files = [];
+  for (const e of entries) {
+    const dest = path.join(payload, e.rel.split('/').join(path.sep));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(e.abs, dest);
+    files.push({ path: e.rel, bytes: e.bytes, sha256: sha256(dest) });
+  }
+  const abs = scanAbsoluteRefs(payload, files.map((f) => f.path));
+  const manifest = {
+    kind,
+    name: name || null,
+    createdAt: new Date().toISOString(),
+    createdAtLocal: stampTz(Date.now()),
+    sourcePlatform: process.platform,
+    fileCount: files.length,
+    bytes: total,
+    note: args.note || '',
+    absoluteRefs: { totalHits: abs.totalHits, files: abs.hits.length, scanned: abs.scanned, crlf: abs.crlf, lf: abs.lf, nonUtf8: abs.nonUtf8.length, detail: abs.hits },
+    files,
+  };
+  fs.writeFileSync(path.join(stagingRoot, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  fs.writeFileSync(path.join(stagingRoot, 'CHECKSUMS.sha256'), files.map((f) => f.sha256 + '  ' + f.path).join(NL) + NL, 'utf8');
+  const absLines = renderAbsoluteRefs(abs, { title: '绝对路径体检（包内）', max: 200 });
+  const md = ['# 迁移包（最简版）', '', '- 目标: ' + kind + (name ? ':' + name : ''), '- 生成: ' + manifest.createdAt, '- 文件: ' + files.length + ' 个 / ' + total + ' B', '- 说明: ' + (args.note || '（无）'), '', ...absLines, '', '## 跨平台注意', '', '- **库内引用一律相对路径**：本包里有 ' + abs.totalHits + ' 处写死的绝对路径，插件**只报告、不改写**文件内容——迁移后需由人或项目会话自己改。', '- 源平台 ' + manifest.sourcePlatform + '；换行 CRLF ' + abs.crlf + ' 个 / LF ' + abs.lf + ' 个' + (abs.nonUtf8.length ? '；非 UTF-8 ' + abs.nonUtf8.length + ' 个' : '') + '。', '- 目标机若是别的系统（Windows ↔ macOS/Linux）：盘符、路径分隔符、大小写敏感性、换行、编码都要项目会话自己核一遍。', '', '## 目标环境前置（先做这两件，再做恢复）', '', '1. 安装 dsh-handover 插件（否则本工具不存在）；', '2. 打开本包随附的交接文件（_Project_Meta/<项目名>/Handover.md 或全局 _Control_Center/records/Global_Handover.md），按它恢复状态。', '', '## 恢复', '', 'ho_pack(action="restore", pack="<本包绝对路径>", dry_run=true)   # 先预演，再加 apply=true', '', '> 会话本身**不迁移**：连续性只靠交接文档。'].join(NL);
+  fs.writeFileSync(path.join(stagingRoot, 'MIGRATION.md'), md, 'utf8');
+  const outDir = args.out || path.join(ws, '_Archives', '_Global', 'Backups');
+  fs.mkdirSync(outDir, { recursive: true });
+  const pick = chooseFormat(args, env.cfg);
+  const ext = pick.fmt === '7z' ? '.7z' : '.tar.gz';
+  const archive = path.join(outDir, label + '-migration-' + stamp + ext);
+  if (fs.existsSync(archive)) throw new Error('目标包已存在，不覆盖：' + archive);
+  if (pick.fmt === '7z') {
+    const a = z7pack(pick.bin, archive, stagingRoot);
+    if (a.code !== 0) throw new Error('7z 打包失败（' + a.code + '）：' + a.error + String.fromCharCode(10) + a.out.slice(-400));
+    const t = z7test(pick.bin, archive);
+    if (t.code !== 0) throw new Error('7z 自检失败（' + t.code + '）：' + t.out.slice(-400));
+    out.push('自检 7z t 通过');
+  } else {
+    const r = packDirTarGz(stagingRoot, archive);
+    const listed = listTarGz(archive);
+    const unsafe = listed.filter((x) => !x.safe);
+    if (listed.length < r.files) throw new Error('tar.gz 自检失败：回读条目 ' + listed.length + ' < 写入文件 ' + r.files);
+    if (unsafe.length) throw new Error('tar.gz 自检失败：含不安全路径 ' + unsafe[0].rel);
+    out.push('自检 tar.gz 通过（' + r.files + ' 文件、' + r.entries + ' 条目，内置归档器）');
+  }
+  try { fs.rmSync(stagingRoot, { recursive: true, force: true }); } catch { /* 留着也无害 */ }
+  out.push('已打包 ' + archive + '（' + fs.statSync(archive).size + ' B，格式 ' + pick.fmt + '）');
+  out.push('绝对路径体检：' + (abs.totalHits ? abs.totalHits + ' 处（清单见 MIGRATION.md，插件不改写文件内容）' : '无'));
+  return out.join(NL);
+}
+
+// ---------------------------------------------------------------- action: verify
+
+export function packVerify(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const packPath = args.pack;
+  if (!packPath) throw new Error('action=verify 需要 pack（包路径）');
+  if (!fs.existsSync(packPath)) throw new Error('包不存在：' + packPath);
+  const tmp = path.join(ws, '_Temp', '_Global', 'Scratch', 'verify-' + stampNow());
+  const ex = unpack(packPath, tmp);
+  if (ex.code !== 0) throw new Error('解包失败：' + String(ex.out).slice(-300));
+  const mf = path.join(tmp, 'manifest.json');
+  if (!fs.existsSync(mf)) throw new Error('包内缺 manifest.json：' + packPath);
+  const manifest = JSON.parse(fs.readFileSync(mf, 'utf8'));
+  const unsafe = unsafeManifestPaths(manifest);
+  if (unsafe.length) {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error('包内路径不安全（必须是相对路径、不含 ..）：' + unsafe.slice(0, 3).join('；'));
+  }
+  const same = [], drift = [], missing = [];
+  for (const f of manifest.files) {
+    const local = path.join(ws, f.path.split('/').join(path.sep));
+    if (!fs.existsSync(local)) { missing.push(f.path); continue; }
+    if (sha256(local) === f.sha256) same.push(f.path); else drift.push(f.path);
+  }
+  try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  const out = [];
+  out.push('包 ' + packPath);
+  out.push('文件 ' + manifest.files.length + ' 个；一致 ' + same.length + ' / 漂移 ' + drift.length + ' / 缺失 ' + missing.length);
+  for (const p of drift.slice(0, 10)) out.push('  漂移：' + p);
+  for (const p of missing.slice(0, 10)) out.push('  缺失：' + p);
+  out.push(drift.length === 0 && missing.length === 0 ? '判定：包内即现版，可直接用' : '判定：**包已作废**（盘上已变），必须重打');
+  return out.join(NL);
+}
+
+// ---------------------------------------------------------------- action: restore
+
+export function packRestore(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const target = args.target || ws;
+  const packPath = args.pack;
+  if (!packPath) throw new Error('action=restore 需要 pack（包路径）');
+  if (!fs.existsSync(packPath)) throw new Error('包不存在：' + packPath);
+  const apply = args.apply === true && args.dry_run !== true;
+  const tmp = path.join(ws, '_Temp', '_Global', 'Scratch', 'restore-' + stampNow());
+  const ex = unpack(packPath, tmp);
+  if (ex.code !== 0) throw new Error('解包失败：' + String(ex.out).slice(-300));
+  const mf = path.join(tmp, 'manifest.json');
+  if (!fs.existsSync(mf)) throw new Error('包内缺 manifest.json');
+  const manifest = JSON.parse(fs.readFileSync(mf, 'utf8'));
+  const unsafe = unsafeManifestPaths(manifest);
+  if (unsafe.length) {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error('包内路径不安全（必须是相对路径、不含 ..），已中止、未写任何文件：' + unsafe.slice(0, 3).join('；'));
+  }
+  const bad = [];
+  for (const f of manifest.files) {
+    const src = path.join(tmp, 'payload', f.path.split('/').join(path.sep));
+    if (!fs.existsSync(src)) { bad.push('缺文件 ' + f.path); continue; }
+    if (sha256(src) !== f.sha256) bad.push('哈希不符 ' + f.path);
+  }
+  if (bad.length) {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new Error('校验未通过，已中止（未复制任何文件）：' + bad.slice(0, 5).join('；'));
+  }
+  const abs = scanAbsoluteRefs(path.join(tmp, 'payload'), manifest.files.map((f) => f.path));
+  const crossPlatform = manifest.sourcePlatform && manifest.sourcePlatform !== process.platform;
+  const backupDir = path.join(ws, '_Temp', '_Global', 'Snapshots', 'restore-' + stampNow());
+  const adds = [], overwrites = [];
+  for (const f of manifest.files) {
+    const dest = path.join(target, f.path.split('/').join(path.sep));
+    if (fs.existsSync(dest)) overwrites.push(f.path); else adds.push(f.path);
+  }
+  if (apply) {
+    for (const f of manifest.files) {
+      const src = path.join(tmp, 'payload', f.path.split('/').join(path.sep));
+      const dest = path.join(target, f.path.split('/').join(path.sep));
+      if (fs.existsSync(dest)) {
+        const bak = path.join(backupDir, f.path.split('/').join(path.sep));
+        fs.mkdirSync(path.dirname(bak), { recursive: true });
+        fs.copyFileSync(dest, bak);
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+    }
+  }
+  try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  const out = [];
+  out.push('包 ' + packPath + '，目标 ' + target);
+  out.push('文件 ' + manifest.files.length + ' 个；新增 ' + adds.length + ' / 覆盖 ' + overwrites.length);
+  for (const p of overwrites.slice(0, 10)) out.push('  覆盖：' + p);
+  if (crossPlatform) out.push('注意：源平台 ' + manifest.sourcePlatform + ' ≠ 本机 ' + process.platform + '：路径分隔符、盘符、大小写、换行、编码都需要项目会话自己核一遍。');
+  out.push(...renderAbsoluteRefs(abs, { title: '绝对路径体检（恢复前）', max: 20 }));
+  if (abs.totalHits) out.push('  ⇒ 这些位置插件**不会**改；迁移后由人或项目会话按新机器改，库内引用统一用相对路径。');
+  if (!apply) out.push('**预演**：未写入任何文件。确认无误后用 apply=true 再调一次。');
+  else out.push('已写入；被覆盖的旧文件备份在 ' + backupDir);
+  return out.join(NL);
+}

package/src/lib/peer.mjs

@@ -0,0 +1,260 @@
+/**
+ * 平级会话共享逻辑（原 peer-link 插件的本地只读部分，原样搬进来）。
+ * 数据源与 peer-link 完全一致，不引入任何第三方依赖：
+ *   ~/.dsh/storages/session_projcache/sessions/<session id>.json   水位 / 运行状态 / 项目名
+ *   ~/.dsh/storages/workspace.json                                  工作区 id / 标题 / 路径
+ *   ~/.dsh/sessions/<slug>/<session id>/session.v4.jsonl.zstd       会话日志（peer_peek 用）
+ * 平级会话的判据：投影缓存里 **没有** record.rows.subagent.identity（子会话才有）。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+/** 收到的消息必须能自报来源：宿主把投递消息记成 source.kind === "user"，不加标记就与用户消息无法区分。 */
+const MARK_HEAD = '【peer-link ← ';
+
+export function peerMarker(senderId) {
+  return MARK_HEAD + (typeof senderId === 'string' && senderId !== '' ? senderId : 'unknown') + '】';
+}
+
+// ---------------------------------------------------------------- 本地只读状态
+
+/** DSH 主目录候选（环境变量优先，回退 ~/.dsh）。 */
+function dshRoots() {
+  const roots = [];
+  const env = process.env.DSH_HOME;
+  if (typeof env === 'string' && env.trim() !== '') roots.push(env.trim());
+  roots.push(path.join(os.homedir(), '.dsh'));
+  return roots;
+}
+
+/** 在候选根下找第一个存在的目录；找不到返回 null（不抛）。 */
+function findDir(relative) {
+  for (const root of dshRoots()) {
+    const p = path.join(root, relative);
+    try {
+      if (fs.statSync(p).isDirectory()) return p;
+    } catch (error) {
+      void error;
+    }
+  }
+  return null;
+}
+
+/** 读 storages 下的一个文件；找不到返回 null（不抛）。 */
+function findStateFile(relative) {
+  for (const root of dshRoots()) {
+    const p = path.join(root, relative);
+    try {
+      if (fs.statSync(p).isFile()) return p;
+    } catch (error) {
+      void error;
+    }
+  }
+  return null;
+}
+
+/** 安全地按路径取值；无法获取返回 undefined（与 peer-link 一致，区别于 lib/text.mjs 的 null）。 */
+export function pick(node, ...rest) {
+  let cur = node;
+  for (const key of rest) {
+    if (cur === null || typeof cur !== 'object' || !(key in cur)) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+/**
+ * 把「工作区 id / 标题 / 路径」解析成工作区 id。
+ * 数据源：<DSH_HOME>/storages/workspace.json 的 tables.workspaces[<id>] = { path, title, sessionIds }。
+ * 找不到返回 null（不抛）；读不到文件时原样返回入参，交给 session.create 去报 workspace/not-found。
+ */
+export function resolveWorkspaceId(key) {
+  const raw = String(key).trim();
+  if (raw === '') return null;
+  const file = findStateFile(path.join('storages', 'workspace.json'));
+  if (file === null) return raw;
+  let table;
+  try {
+    table = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    void error;
+    return raw;
+  }
+  const workspaces = pick(table, 'tables', 'workspaces');
+  if (workspaces === undefined) return raw;
+  if (workspaces[raw] !== undefined) return raw;
+  const trimSlash = (v) => String(v).replace(/\/+$/, '');
+  const want = trimSlash(raw);
+  for (const id of Object.keys(workspaces)) {
+    const ws = workspaces[id];
+    if (ws === null || typeof ws !== 'object') continue;
+    if (ws.title === raw) return id;
+    if (ws.path !== undefined) {
+      if (trimSlash(ws.path) === want) return id;
+      // 注册表存的是真实路径，而入参可能是 /root/<项目名> 这类软链接 —— 两条都认
+      try {
+        if (trimSlash(fs.realpathSync(ws.path)) === trimSlash(fs.realpathSync(raw))) return id;
+      } catch (error) {
+        void error;
+      }
+    }
+  }
+  return null;
+}
+
+/** 读一个会话的投影缓存（水位 / 运行状态 / 项目名的来源）。读不到返回 null。 */
+export function readProjCache(sessionId) {
+  const dir = findDir('storages/session_projcache/sessions');
+  if (dir === null) return null;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, sessionId + '.json'), 'utf8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+/** 上下文水位（百分比）；读不到返回 null。 */
+export function pressurePct(cache) {
+  const used = pick(cache, 'record', 'rows', 'contextPressure', 'val', 'pressureTokens');
+  const win = pick(cache, 'record', 'rows', 'contextPressure', 'val', 'contextWindow');
+  if (!Number.isFinite(used) || !Number.isFinite(win) || win === 0) return null;
+  return (used / win) * 100;
+}
+
+/** 子会话才有 record.rows.subagent.identity；没有就是平级会话。 */
+export function isSubagent(cache) {
+  return (
+    pick(cache, 'record', 'rows', 'subagent', 'val', 'identity') !== undefined ||
+    pick(cache, 'record', 'rows', 'subagent', 'identity') !== undefined
+  );
+}
+
+/** 项目名：先看首条提示里的 Projects/<名>/ 或「<名>」项目，再退回标题。 */
+export function projectName(cache) {
+  const text = pick(cache, 'record', 'rows', 'titleInput', 'val', 'first', 'text');
+  if (typeof text === 'string') {
+    const a = text.match(/Projects\/([^\/\s]+)\//);
+    if (a !== null) return a[1];
+    const b = text.match(/「([^」]+)」项目/);
+    if (b !== null) return b[1];
+  }
+  const title = pick(cache, 'record', 'rows', 'title', 'val');
+  return typeof title === 'string' && title.trim() !== '' ? title.trim() : '-';
+}
+
+/** openStep 非空 = 正在跑一个步骤。 */
+export function isBusy(cache) {
+  if (cache === null) return null;
+  const openStep = pick(cache, 'record', 'rows', 'sessionStats', 'val', 'openStep');
+  return openStep !== null && openStep !== undefined;
+}
+
+/** 把时间戳格式化成 MM-DD HH:MM（本地时区）。 */
+export function stamp(ms) {
+  if (!Number.isFinite(ms)) return '--';
+  const d = new Date(ms);
+  const p = (n) => String(n).padStart(2, '0');
+  return p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes());
+}
+
+/** 一行式摘要（给 peer_list 用）。 */
+export function rowLine(sessionId, cache, fallback) {
+  const pct = cache === null ? null : pressurePct(cache);
+  const state = isBusy(cache) === true ? 'running' : fallback === undefined ? 'idle' : fallback;
+  const proj = cache === null ? '-' : projectName(cache);
+  const kind = cache === null ? '' : isSubagent(cache) ? ' [子会话]' : ' [平级]';
+  const water = pct === null ? '水位 ?' : '水位 ' + pct.toFixed(1) + '%';
+  return sessionId + ' | ' + proj + ' | ' + water + ' | ' + state + kind;
+}
+
+/**
+ * 会话清单：controller.list 的结果按 origin 过滤。
+ * 冷会话在这一步就会被服务端从持久化里恢复成可寻址的行，所以 peer_list 本身不花 token。
+ */
+export async function sessionRows(controller, includeSubagents) {
+  const value = await controller.list({}, new AbortController().signal);
+  return value.items.filter((row) => includeSubagents === true || row.origin !== 'subagent');
+}
+
+// ---------------------------------------------------------------- 会话日志（peer_peek）
+
+/** 解 zstd **多帧**日志并按行解析成事件数组；本 Node 构建没有 zstd 时返回 null。 */
+export function decodeSessionLog(file) {
+  if (typeof zlib.zstdDecompressSync !== 'function') return null;
+  const buf = fs.readFileSync(file);
+  const magic = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+  const starts = [];
+  let idx = 0;
+  for (;;) {
+    const at = buf.indexOf(magic, idx);
+    if (at < 0) break;
+    starts.push(at);
+    idx = at + 4;
+  }
+  const parts = [];
+  for (let i = 0; i < starts.length; i++) {
+    const end = i + 1 < starts.length ? starts[i + 1] : buf.length;
+    try {
+      parts.push(zlib.zstdDecompressSync(buf.subarray(starts[i], end)).toString('utf8'));
+    } catch (error) {
+      void error;
+    }
+  }
+  return parts
+    .join('')
+    .split(String.fromCharCode(10))
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        return null;
+      }
+    })
+    .filter((x) => x !== null);
+}
+
+/** 在 <DSH_HOME>/sessions/<任意 slug>/<session id>/ 下找日志文件（不猜 slug）。 */
+export function findSessionLog(sessionId) {
+  const root = findDir('sessions');
+  if (root === null) return null;
+  let buckets = [];
+  try {
+    buckets = fs.readdirSync(root);
+  } catch (error) {
+    return null;
+  }
+  for (const bucket of buckets) {
+    const file = path.join(root, bucket, sessionId, 'session.v4.jsonl.zstd');
+    try {
+      if (fs.statSync(file).isFile()) return file;
+    } catch (error) {
+      void error;
+    }
+  }
+  return null;
+}
+
+/** 从事件流里抽出「人/会话说得出口的话」，跳过运行时上下文与技能目录注入。 */
+export function conversation(events, limit) {
+  const skip = { 'runtime-context': true, 'skill-catalog': true };
+  const items = [];
+  for (const e of events) {
+    if (e.type === 'user/message') {
+      const kind = pick(e, 'data', 'source', 'kind');
+      if (typeof kind === 'string' && skip[kind] === true) continue;
+      const blocks = pick(e, 'data', 'content');
+      const text = Array.isArray(blocks) ? blocks.map((c) => (c && c.text) || '').join(' ') : '';
+      if (text.trim() !== '') items.push({ t: e.time, who: typeof kind === 'string' ? kind : 'user', text });
+    } else if (e.type === 'assistant/message') {
+      const blocks = pick(e, 'data', 'message', 'content');
+      const text = Array.isArray(blocks)
+        ? blocks.filter((b) => b && b.type === 'text').map((b) => b.text || '').join(' ')
+        : '';
+      if (text.trim() !== '') items.push({ t: e.time, who: 'assistant', text });
+    }
+  }
+  return items.slice(-limit);
+}

package/src/lib/phase.mjs

@@ -0,0 +1,34 @@
+/** 阶段决策：纯函数，便于单测。 */
+
+/**
+ * @param {{ratio:number|null, compactionsUsed:number, cfg:object, lockState:string}} input
+ * @returns {{action:string, reason:string}}
+ *   action ∈ continue | pause | checkpoint | new_session | force_compact | blocked | unknown
+ */
+export function decide(input) {
+  const cfg = input.cfg || {};
+  const warn = cfg.warnRatio === undefined ? 0.32 : cfg.warnRatio;
+  const handover = cfg.handoverRatio === undefined ? 0.35 : cfg.handoverRatio;
+  const hard = cfg.hardRatio === undefined ? 0.85 : cfg.hardRatio;
+  const maxComp = cfg.maxCompactions === undefined ? 3 : cfg.maxCompactions;
+  const used = typeof input.compactionsUsed === 'number' ? input.compactionsUsed : 0;
+  if (input.lockState === 'orphaned') {
+    return { action: 'blocked', reason: '检测到未闭合的压缩锁（compaction/start 无配对 end）：先处理再排新压缩' };
+  }
+  if (input.ratio === null || input.ratio === undefined) {
+    return { action: 'unknown', reason: '水位读不到：人工判断，不要盲目压缩' };
+  }
+  if (input.ratio >= hard) {
+    if (used >= maxComp) return { action: 'new_session', reason: '已到硬顶且压缩额度用尽，应写交接并建新会话' };
+    return { action: 'force_compact', reason: '已到硬顶（' + Math.round(hard * 100) + '%）：强制压缩兜底，哪怕任务中途' };
+  }
+  if (input.ratio >= handover) {
+    if (used >= maxComp) return { action: 'new_session', reason: '已压缩 ' + used + '/' + maxComp + ' 次：写交接并建新会话（现行流程）' };
+    return { action: 'checkpoint', reason: '过交接线（' + Math.round(handover * 100) + '%）：写交接，随后压缩，再读交接续跑' };
+  }
+  if (input.ratio >= warn) {
+    if (used >= maxComp) return { action: 'new_session', reason: '已压缩 ' + used + '/' + maxComp + ' 次：到线即走换会话' };
+    return { action: 'pause', reason: '过提醒线（' + Math.round(warn * 100) + '%）：建议在阶段完成处调 ho_checkpoint（关键步骤返回 pause）' };
+  }
+  return { action: 'continue', reason: '水位正常' };
+}