@mingmaple/dsh-handover 0.0.0-stage → 0.9.12

package/src/lib/phase.mjs

@@ -0,0 +1,36 @@
+/** 阶段决策：纯函数，便于单测。 */
+
+/**
+ * @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）：先处理再排新压缩' };
+  }
+  // 额度用尽优先于水位判定：3 次压满后再压不是「水位没到」，而是该换任了。
+  // 放在水位判定之前，force 也就绕不过去（force 只在水位分支里放行）。
+  if (used >= maxComp) {
+    return { action: 'new_session', reason: '已压缩 ' + used + '/' + maxComp + ' 次：压缩额度用尽，应写交接并建新会话' };
+  }
+  if (input.ratio === null || input.ratio === undefined) {
+    return { action: 'unknown', reason: '水位读不到：人工判断，不要盲目压缩' };
+  }
+  if (input.ratio >= hard) {
+    return { action: 'force_compact', reason: '已到硬顶（' + Math.round(hard * 100) + '%）：强制压缩兜底，哪怕任务中途' };
+  }
+  if (input.ratio >= handover) {
+    return { action: 'checkpoint', reason: '过交接线（' + Math.round(handover * 100) + '%）：写交接，随后压缩，再读交接续跑' };
+  }
+  if (input.ratio >= warn) {
+    return { action: 'pause', reason: '过提醒线（' + Math.round(warn * 100) + '%）：建议在阶段完成处调 ho_checkpoint（关键步骤返回 pause）' };
+  }
+  return { action: 'continue', reason: '水位正常' };
+}

package/src/lib/profile.mjs

@@ -0,0 +1,204 @@
+/**
+ * 项目与杂项的骨架档案：由本会话自行判断、写入、注册；插件只校验与引用。
+ * 项目：_Project_Meta/<项目>/project.profile.json
+ * 杂项：_Misc/tasks/<任务>/task.profile.json
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isFile } from './text.mjs';
+
+const PROFILE_SCHEMA = 1;
+export const PROFILE_KINDS = ['application', 'animation', 'library', 'general'];
+const PROJECT_FILE = 'project.profile.json';
+const TASK_FILE = 'task.profile.json';
+
+const PRESETS = {
+  application: {
+    kind: 'application',
+    required: ['README.md', 'src'],
+    optional: ['SKILL.md', 'CHANGELOG.md'],
+    docs: ['docs/'],
+    gate: { libraryBlock: false },
+    notes: '构建型项目：不要求插件类项目的文档集。',
+  },
+  animation: {
+    kind: 'animation',
+    required: ['README.md'],
+    optional: ['src', 'public', 'assets'],
+    docs: [],
+    gate: { libraryBlock: false },
+    notes: '动画与视频项目：不要求代码库式的目录与文档。',
+  },
+  library: {
+    kind: 'library',
+    required: ['README.md', 'RULES.md'],
+    optional: ['docs/', 'SKILL.md'],
+    docs: ['docs/'],
+    gate: { libraryBlock: true },
+    notes: '库型项目：启用 24 行通用约束条校验。',
+  },
+  general: {
+    kind: 'general',
+    required: [],
+    optional: [],
+    docs: [],
+    gate: { libraryBlock: false },
+    notes: '通用骨架：只保留最小约束。',
+  },
+};
+
+export function presets() {
+  return JSON.parse(JSON.stringify(PRESETS));
+}
+
+export function profilePathFor(ws, info) {
+  if (!ws || !info) return null;
+  if (info.role === 'project' && info.project) return path.join(ws, '_Project_Meta', info.project, PROJECT_FILE);
+  if (info.role === 'misc' && info.task) return path.join(ws, '_Misc', 'tasks', info.task, TASK_FILE);
+  return null;
+}
+
+/** 未注册时的默认骨架：沿用现有目录约定，24 行约束条默认启用（向后兼容）。 */
+function defaultProfile(info) {
+  const base = {
+    schema: PROFILE_SCHEMA,
+    kind: 'general',
+    root: '',
+    required: [],
+    optional: [],
+    docs: [],
+    meta: [],
+    gate: { libraryBlock: true },
+    handover: { extraSections: [] },
+    notes: '未注册：按默认骨架运行。',
+  };
+  if (info && info.role === 'project' && info.project) {
+    base.root = 'Projects/' + info.project;
+    base.required = [];
+    base.optional = ['SKILL.md'];
+    base.meta = [];
+    base.notes = '未注册：按默认骨架运行，请由本项目会话补注册。';
+  } else if (info && info.role === 'misc' && info.task) {
+    base.root = '_Misc/tasks/' + info.task;
+    base.required = [];
+    base.notes = '未注册：按默认骨架运行，请由本任务会话补注册。';
+  }
+  return base;
+}
+
+function cleanList(v, field, errors) {
+  if (v === undefined) return [];
+  if (!Array.isArray(v)) { errors.push(field + ' 必须是数组'); return []; }
+  const out = [];
+  for (const x of v) {
+    const s = String(x == null ? '' : x).trim().replace(/\\/g, '/');
+    if (!s) continue;
+    if (path.isAbsolute(s) || /^[A-Za-z]:/.test(s) || s.split('/').indexOf('..') !== -1) {
+      errors.push(field + ' 不得使用绝对路径或 ..：' + s);
+      continue;
+    }
+    if (out.indexOf(s) === -1) out.push(s);
+  }
+  return out;
+}
+
+/** 规范化并校验结构；返回 { profile, errors }。路径越界与类型错误进 errors。 */
+export function normalizeProfile(raw, info) {
+  const errors = [];
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const kind = PROFILE_KINDS.indexOf(String(src.kind || '')) !== -1 ? String(src.kind) : 'general';
+  const rootDefault = info && info.role === 'project' && info.project
+    ? 'Projects/' + info.project
+    : (info && info.role === 'misc' && info.task ? '_Misc/tasks/' + info.task : '');
+  const root = String(src.root || rootDefault).trim().replace(/\\/g, '/');
+  if (path.isAbsolute(root) || /^[A-Za-z]:/.test(root) || root.split('/').indexOf('..') !== -1) {
+    errors.push('root 不得使用绝对路径或 ..');
+  }
+  const profile = {
+    schema: PROFILE_SCHEMA,
+    kind,
+    root,
+    required: cleanList(src.required, 'required', errors),
+    optional: cleanList(src.optional, 'optional', errors),
+    docs: cleanList(src.docs, 'docs', errors),
+    meta: cleanList(src.meta, 'meta', errors),
+    gate: { libraryBlock: !!(src.gate && src.gate.libraryBlock === true) },
+    handover: { extraSections: cleanList(src.handover && src.handover.extraSections, 'handover.extraSections', errors) },
+    notes: String(src.notes == null ? '' : src.notes).trim(),
+  };
+  return { profile, errors };
+}
+
+export function readProfile(ws, info) {
+  const p = profilePathFor(ws, info);
+  if (!p) return { exists: false, path: null, profile: defaultProfile(info), errors: [] };
+  if (!isFile(p)) return { exists: false, path: p, profile: defaultProfile(info), errors: [] };
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const r = normalizeProfile(raw, info);
+    return { exists: true, path: p, profile: r.profile, errors: r.errors };
+  } catch (e) {
+    return { exists: true, path: p, profile: defaultProfile(info), errors: ['读或解析失败：' + (e && e.message ? e.message : String(e))] };
+  }
+}
+
+export function writeProfile(ws, info, raw) {
+  const p = profilePathFor(ws, info);
+  if (!p) throw new Error('当前角色没有骨架路径（须为项目或杂项）');
+  const r = normalizeProfile(raw, info);
+  if (r.errors.length) throw new Error('骨架结构不合法：' + r.errors.join('；'));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  if (isFile(p)) fs.copyFileSync(p, p + '.bak');
+  fs.writeFileSync(p, JSON.stringify(r.profile, null, 2) + String.fromCharCode(10), 'utf8');
+  return { path: p, profile: r.profile };
+}
+
+/** 校验：结构错误与必需项缺失分开报；docs 与 optional 不强制存在。 */
+export function validateProfile(ws, info, profile) {
+  const p = profile || readProfile(ws, info).profile;
+  const errors = [];
+  const missing = [];
+  const root = path.join(ws, p.root || '');
+  for (const rel of p.required || []) {
+    const f = path.join(root, rel);
+    if (!fs.existsSync(f)) missing.push(rel);
+  }
+  const metaRoot = info && info.role === 'project' && info.project
+    ? path.join(ws, '_Project_Meta', info.project)
+    : (info && info.role === 'misc' && info.task ? path.join(ws, '_Misc', 'tasks', info.task) : null);
+  // meta 条目相对档案目录（_Project_Meta/<项目>/ 或 _Misc/tasks/<任务>/），不是库内路径；
+  // 报缺时给全路径，避免被读成库内或某个 _meta/ 子目录。
+  const metaLabel = info && info.role === 'project' && info.project
+    ? '_Project_Meta/' + info.project + '/'
+    : (info && info.task ? '_Misc/tasks/' + info.task + '/' : '');
+  if (metaRoot) {
+    for (const rel of p.meta || []) {
+      if (!fs.existsSync(path.join(metaRoot, rel))) missing.push(metaLabel + rel);
+    }
+  }
+  return { ok: errors.length === 0 && missing.length === 0, errors, missing };
+}
+
+/** 已注册骨架清单（读文件，不写）：项目与杂项各一组。 */
+export function listProfiles(ws) {
+  const out = [];
+  const scan = (dir, role, nameKey) => {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return; }
+    for (const name of names) {
+      const d = path.join(dir, name);
+      try { if (!fs.statSync(d).isDirectory()) continue; } catch { continue; }
+      const file = path.join(d, role === 'project' ? PROJECT_FILE : TASK_FILE);
+      const info = { role, project: role === 'project' ? name : '', task: role === 'misc' ? name : '' };
+      const r = readProfile(ws, info);
+      const v = validateProfile(ws, info, r.profile);
+      out.push({
+        role, name, path: file, exists: r.exists,
+        kind: r.profile.kind, ok: v.ok, missing: v.missing, errors: r.errors.concat(v.errors),
+      });
+    }
+  };
+  scan(path.join(ws, '_Project_Meta'), 'project');
+  scan(path.join(ws, '_Misc', 'tasks'), 'misc');
+  return out;
+}

package/src/lib/prompt.mjs

@@ -0,0 +1,18 @@
+/**
+ * 会话投递的唯一入口：把一条纯文本作为用户消息排进目标会话。
+ * 角色整理指令、换任启动提示词、压缩后继续，三处都用它，避免各自拼一套 requestId 与中止信号。
+ */
+
+/** 投递一条文本；controller 由调用方按自己的服务句柄给出。 */
+export function sendPrompt(controller, sessionId, text, mode) {
+  if (!controller || typeof controller.prompt !== 'function') throw new Error('sessionController.prompt 不可用');
+  const requestId = (globalThis.crypto && globalThis.crypto.randomUUID)
+    ? globalThis.crypto.randomUUID()
+    : String(Date.now());
+  return controller.prompt({
+    requestId,
+    sessionId: String(sessionId),
+    mode: mode || 'queue',
+    content: [{ type: 'text', text: String(text) }],
+  }, new AbortController().signal);
+}

package/src/lib/registry.mjs

@@ -0,0 +1,53 @@
+/** 工作区与会话生命周期：只走 DSH 官方服务（workspaceRegistry），读不到就明确报错，不自己改注册表文件。 */
+import os from 'node:os';
+import path from 'node:path';
+import { readUtf8 } from './text.mjs';
+
+function workspaceJsonPath() {
+  return path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
+}
+
+/** 读 workspace.json 的 workspaces 表（只读；读不到返回空表）。 */
+function readWorkspaceTable() {
+  try {
+    const data = JSON.parse(readUtf8(workspaceJsonPath()));
+    return (data && data.tables && data.tables.workspaces) || {};
+  } catch { return {}; }
+}
+
+/** 官方服务：ctx.workspaceRegistry（session-controller 就是这么用的）；无法获取返回 null。 */
+export function resolveRegistry(ctx) {
+  let v = null;
+  try { v = ctx.workspaceRegistry || null; } catch { /* ignore */ }
+  if (!v) { try { v = typeof ctx.get === 'function' ? ctx.get('workspaceRegistry') : null; } catch { /* ignore */ } }
+  return v || null;
+}
+
+/** 「全局」工作区里的会话 id 集合（判定会话是否属于全局）。 */
+export function globalWorkspaceSessionIds() {
+  const out = [];
+  const tables = readWorkspaceTable();
+  for (const id of Object.keys(tables)) {
+    const w = tables[id] || {};
+    const title = typeof w.title === 'string' ? w.title : '';
+    if (title.indexOf('全局') === -1) continue;
+    for (const sid of (Array.isArray(w.sessionIds) ? w.sessionIds : [])) {
+      if (out.indexOf(sid) === -1) out.push(sid);
+    }
+  }
+  return out;
+}
+
+/** 工作区表投影：id / 标题 / 路径 / 会话数，供 ho_workspace list 用。 */
+export function workspaceRows() {
+  const tables = readWorkspaceTable();
+  return Object.keys(tables).map((id) => {
+    const w = tables[id] || {};
+    return {
+      id,
+      title: typeof w.title === 'string' ? w.title : '-',
+      path: typeof w.path === 'string' ? w.path : '-',
+      sessions: Array.isArray(w.sessionIds) ? w.sessionIds.length : 0,
+    };
+  });
+}

package/src/lib/retarget-helper.tmpl

@@ -0,0 +1,46 @@
+// dsh-handover 登记改址助手（由插件生成，勿手改）
+// 只改 DSH 的登记文件（workspace.json、聊天集成的归属表），不动任何数据文件。
+import fs from 'node:fs';
+
+const LOG = %%LOG%%;
+const WAIT_PID = Number(process.argv[2] || 0) || 0;
+const FROM = %%FROM%%;
+const TO = %%TO%%;
+const FILES = %%FILES%%;
+
+function log(m) {
+  try { fs.appendFileSync(LOG, new Date().toISOString() + '  ' + m + '\n', 'utf8'); } catch { /* ignore */ }
+  try { console.log(m); } catch { /* ignore */ }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function alive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === 'EPERM'; }
+}
+const esc = (p) => JSON.stringify(String(p)).slice(1, -1);
+
+(async () => {
+  log('== 登记改址助手 ==  pid=' + process.pid);
+  if (WAIT_PID) {
+    log('等待 DSH 退出（最多 30 分钟）…');
+    for (let i = 0; i < 900; i++) { if (!alive(WAIT_PID)) break; await sleep(2000); }
+    if (alive(WAIT_PID)) { log('[中止] 等 DSH 退出超时，未做任何改动'); process.exit(1); }
+    await sleep(1500);
+    log('DSH 已退出，开始改址');
+  }
+  const from = esc(FROM);
+  const to = esc(TO);
+  let changed = 0;
+  for (const p of FILES) {
+    let text = '';
+    try { text = fs.readFileSync(p, 'utf8'); } catch { log('跳过（读不到）：' + p); continue; }
+    const n = text.split(from).length - 1;
+    if (!n) { log('无需改：' + p); continue; }
+    const bak = p + '.bak-' + new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    try { fs.copyFileSync(p, bak); } catch { log('跳过（备份失败）：' + p); continue; }
+    try { fs.writeFileSync(p, text.split(from).join(to), 'utf8'); } catch (e) { log('跳过（写入失败）：' + p + ' :: ' + e.message); continue; }
+    changed += n;
+    log('已改 ' + n + ' 处：' + p + '   备份 ' + bak);
+  }
+  log(changed ? ('完成：共改 ' + changed + ' 处登记，重启 DSH 后工作区即在新位置。') : '无需改动。');
+})();

package/src/lib/role.mjs

@@ -0,0 +1,251 @@
+/**
+ * 会话角色：判定、逐角色交接路径、工具集与文案。角色表是本机状态（不进仓库、不进迁移包）。
+ * 判定顺序：角色表 → 全局标题 → 全局工作区 → 子会话（默认普通）→ cwd（Projects/<名> 或 _Misc/tasks/<任务>）→ 首条提示 → 普通。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonDir, pick, isSafeName, assertSafeName } from './text.mjs';
+import { projCacheDir, isSubagent } from './sessions.mjs';
+import { globalWorkspaceSessionIds } from './registry.mjs';
+import { TOOL_NAMES, PEER_NAMES, nameOf, peerNameOf } from './names.mjs';
+import { stampTz } from './brief.mjs';
+
+export const ROLES = ['global', 'project', 'misc', 'plain'];
+export const ROLE_LABEL = { global: '全局', project: '项目', misc: '杂项', plain: '普通' };
+
+export const ALL_TOOL_NAMES = TOOL_NAMES.concat(PEER_NAMES);
+
+/** 角色 → 可见工具（其余一律 deny）。改这张表就是改成本结构。 */
+const ROLE_TOOLS = {
+  global: ALL_TOOL_NAMES.slice(),
+  project: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('gate'), nameOf('snapshot'), nameOf('profile'), peerNameOf('send'), peerNameOf('status')],
+  misc: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('snapshot'), nameOf('profile'), peerNameOf('send'), peerNameOf('status'), peerNameOf('new')],
+  plain: [],
+};
+
+export function toolsetFor(role) {
+  const allow = ROLE_TOOLS[role] || ROLE_TOOLS.plain;
+  const deny = ALL_TOOL_NAMES.filter((n) => allow.indexOf(n) === -1);
+  return { allow: allow.slice(), deny };
+}
+
+// ---------------------------------------------------------------- 角色表（本机状态）
+
+export function rolesPath(cfg) {
+  try {
+    if (cfg && cfg.rolesPath) return String(cfg.rolesPath);
+  } catch { /* ignore */ }
+  return path.join(os.homedir(), '.dsh', 'storages', 'dsh-handover.roles.json');
+}
+
+export function readRoles(cfg) {
+  try {
+    const j = JSON.parse(fs.readFileSync(rolesPath(cfg), 'utf8'));
+    const sessions = j && typeof j.sessions === 'object' && j.sessions ? j.sessions : {};
+    return { version: 1, sessions };
+  } catch {
+    return { version: 1, sessions: {} };
+  }
+}
+
+function writeRolesFile(cfg, data) {
+  const file = rolesPath(cfg);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + String.fromCharCode(10), 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** 写入/更新一条角色；返回写入后的条目。 */
+export function writeRole(cfg, sessionId, patch) {
+  const sid = String(sessionId || '');
+  if (!sid) throw new Error('缺会话 id');
+  const data = readRoles(cfg);
+  const prev = data.sessions[sid] || {};
+  const next = Object.assign({}, prev, patch || {});
+  // 名字要落成目录：不合法就当场拒绝，别等拼路径时才 ENOENT。
+  if (next.role === 'project') assertProjectName(next.project);
+  if (next.role === 'misc') assertTaskName(next.task);
+  next.setAt = stampTz(Date.now());
+  data.sessions[sid] = next;
+  writeRolesFile(cfg, data);
+  return next;
+}
+
+
+// ---------------------------------------------------------------- 判定
+
+/** 从投影缓存读会话的 cwd 与首条提示（读不到返回空串）。 */
+export function sessionMeta(sessionId) {
+  const sid = String(sessionId || '');
+  if (!sid) return { cwd: '', firstPrompt: '', subagent: false };
+  for (const f of readJsonDir(projCacheDir())) {
+    if (f.name.replace('.json', '') !== sid) continue;
+    return {
+      cwd: String(pick(f.data, 'record', 'identity', 'cwd') || ''),
+      firstPrompt: String(pick(f.data, 'record', 'rows', 'titleInput', 'val', 'first', 'text') || ''),
+      subagent: isSubagent(f.data),
+    };
+  }
+  return { cwd: '', firstPrompt: '', subagent: false };
+}
+
+function parts(p) {
+  return String(p || '').replace(/\\/g, '/').split('/').filter(Boolean);
+}
+
+/** 项目名当目录名用，长度与字符集都比任务名紧一些；任务名放宽到 40 字符。 */
+export const PROJECT_NAME_MAX = 24;
+export const TASK_NAME_MAX = 40;
+
+export function projectNameOk(name) {
+  return isSafeName(name, PROJECT_NAME_MAX);
+}
+
+export function taskNameOk(name) {
+  return isSafeName(name, TASK_NAME_MAX);
+}
+
+export function assertProjectName(name) {
+  return assertSafeName(name, '项目名', PROJECT_NAME_MAX);
+}
+
+export function assertTaskName(name) {
+  return assertSafeName(name, '任务名', TASK_NAME_MAX);
+}
+
+/** cwd 落在 Projects/<名>/ 或 _Misc/tasks/<任务>/ 里就据此判定；名字不合法一律不认。 */
+function roleFromPath(cwd) {
+  const seg = parts(cwd);
+  for (let i = 0; i < seg.length; i++) {
+    if (seg[i] === 'Projects' && projectNameOk(seg[i + 1]) && seg[i + 1] !== '_Project_Meta') {
+      return { role: 'project', project: seg[i + 1], task: '' };
+    }
+    if (seg[i] === '_Misc' && seg[i + 1] === 'tasks' && taskNameOk(seg[i + 2])) {
+      return { role: 'misc', project: '', task: seg[i + 2] };
+    }
+    if (seg[i] === '_Project_Meta' && projectNameOk(seg[i + 1])) {
+      return { role: 'project', project: seg[i + 1], task: '' };
+    }
+  }
+  return null;
+}
+
+/** 首条提示里能解析出 Projects/<名>/ 或「<名>」项目 就算项目会话；名字不合法不认。 */
+function roleFromPrompt(text) {
+  const t = String(text || '').replace(/\\/g, '/');   // Windows 路径也能解析
+  const i = t.indexOf('Projects/');
+  if (i !== -1) {
+    const rest = t.slice(i + 'Projects/'.length);
+    let name = '';
+    for (const ch of rest) {
+      if (ch === '/' || ch === ' ' || ch === String.fromCharCode(9) || ch === String.fromCharCode(10) || ch === String.fromCharCode(13)) break;
+      name += ch;
+    }
+    // 首条提示常把规则写成 `_Control_Center/**、Projects/**` 这样的通配，解析结果必须过名称校验。
+    if (projectNameOk(name)) return { role: 'project', project: name, task: '' };
+  }
+  const q = t.indexOf(String.fromCharCode(12300));
+  if (q !== -1) {
+    const rest = t.slice(q + 1);
+    const j = rest.indexOf(String.fromCharCode(12301) + '项目');
+    if (j > 0) {
+      const name = rest.slice(0, j);
+      if (projectNameOk(name)) return { role: 'project', project: name, task: '' };
+    }
+  }
+  return null;
+}
+
+/**
+ * 判定一个会话的角色。
+ * @param {{ cfg?: object, sessionId?: string, title?: string, cwd?: string, firstPrompt?: string, roles?: object }} opts
+ */
+export function resolveRole(opts) {
+  const o = opts || {};
+  const sid = String(o.sessionId || '');
+  const store = o.roles || readRoles(o.cfg);
+  const hit = sid ? store.sessions[sid] : null;
+  if (hit) {
+    const role = String(hit.role || '');
+    if (ROLES.indexOf(role) !== -1) {
+      // 角色表里的名字要当目录名用。历史写入或手工编辑留下的非法名字一律不认，继续往下推断，
+      // 否则会把整条「写交接 → 备份 → 归档」链路卡在 Windows 的非法路径上。
+      const named = role === 'project' ? projectNameOk(hit.project)
+        : role === 'misc' ? taskNameOk(hit.task) : true;
+      if (named) {
+        return { role, project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
+      }
+    }
+    // 旧角色表的 unknown 是兜底态，按新口径并入普通。
+    if (role === 'unknown') {
+      return { role: 'plain', project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
+    }
+  }
+  const title = String(o.title || '');
+  if (title.indexOf('全局') !== -1) return { role: 'global', project: '', task: '', source: 'title', sessionId: sid };
+  try {
+    if (sid && globalWorkspaceSessionIds().indexOf(sid) !== -1) {
+      return { role: 'global', project: '', task: '', source: 'workspace', sessionId: sid };
+    }
+  } catch { /* 读不到工作区表就继续往下判 */ }
+  // 子会话默认按普通处理，不再按 cwd 注入项目段；项目中显式指定角色的子会话仍以角色表为准。
+  if (o.subagent === true) return { role: 'plain', project: '', task: '', source: 'subagent', sessionId: sid };
+  const byPath = roleFromPath(o.cwd);
+  if (byPath) return Object.assign(byPath, { source: 'cwd', sessionId: sid });
+  const byPrompt = roleFromPrompt(o.firstPrompt);
+  if (byPrompt) return Object.assign(byPrompt, { source: 'prompt', sessionId: sid });
+  return { role: 'plain', project: '', task: '', source: 'none', sessionId: sid };
+}
+
+// ---------------------------------------------------------------- 路径
+
+/**
+ * 逐角色交接路径。
+ * @returns {{ path: string|null, kind: string|null, scope: string, role: string, reason?: string }}
+ */
+export function handoverPathFor(ws, info) {
+  const role = info && info.role ? info.role : 'plain';
+  if (!ws) return { path: null, kind: null, scope: '', role, reason: '没有工作区根' };
+  if (role === 'global') {
+    return { path: path.join(ws, '_Control_Center', 'records', 'Global_Handover.md'), kind: 'global', scope: '_Global', role };
+  }
+  if (role === 'project') {
+    const project = String(info.project || '');
+    if (!project) return { path: null, kind: null, scope: '', role, reason: '项目名缺失' };
+    if (!projectNameOk(project)) return { path: null, kind: null, scope: '', role, reason: '项目名不合法（当目录名用）：' + JSON.stringify(project) };
+    return { path: path.join(ws, '_Project_Meta', project, 'Handover.md'), kind: 'project', scope: project, role, project };
+  }
+  if (role === 'misc') {
+    const task = String(info.task || '');
+    if (!task) return { path: null, kind: null, scope: '', role, reason: '任务名缺失' };
+    if (!taskNameOk(task)) return { path: null, kind: null, scope: '', role, reason: '任务名不合法（当目录名用）：' + JSON.stringify(task) };
+    return { path: path.join(ws, '_Misc', 'tasks', task, 'Handover.md'), kind: 'misc', scope: path.join('_Misc', task), role, task };
+  }
+  if (role === 'plain') return { path: null, kind: null, scope: '', role, reason: '普通会话不参与交接' };
+  return { path: null, kind: null, scope: '', role, reason: '本会话未设定角色' };
+}
+
+export function snapshotDirFor(ws, info) {
+  const t = handoverPathFor(ws, info);
+  return path.join(ws, '_Temp', t.scope || '_Global', 'Snapshots');
+}
+
+export function archiveDirFor(ws, info) {
+  // 规范 §4.1：杂项归档自包含在任务目录里（`_Misc/tasks/<任务>/_archive/`），不进全局归档；
+  // 全局与项目归档在 `_Archives/<范围>/Handover/`。
+  if (info && info.role === 'misc' && taskNameOk(info.task)) {
+    return path.join(ws, '_Misc', 'tasks', String(info.task), '_archive');
+  }
+  const t = handoverPathFor(ws, info);
+  return path.join(ws, '_Archives', t.scope || '_Global', 'Handover');
+}
+
+export function scopeLabel(info) {
+  const role = info && info.role ? info.role : 'plain';
+  if (role === 'project') return '项目「' + (info.project || '?') + '」';
+  if (role === 'misc') return '杂项任务「' + (info.task || '?') + '」';
+  return ROLE_LABEL[role] || role;
+}