@mingmaple/dsh-handover 0.9.6 → 0.9.13

package/src/lib/office.mjs

@@ -0,0 +1,272 @@
+/**
+ * 在任登记表（office）：回答「这条类别现在谁在任」。
+ *
+ * 记录保存在 <工作区根>/_Control_Center/records/Office.json：每一类会话（全局／项目名／杂项任务名）
+ * 记一个在任会话与历史编号。Registry.md 的「在役会话」列由本文件定点改写——只换那一格，
+ * 不动人写的状态文字与整表结构。编号由这里分配（历史最大号 + 1），不采信会话自述。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { NL, readUtf8 } from './text.mjs';
+
+export const OFFICE_VERSION = 1;
+
+/** 带时区偏移的时刻文本（与交接、登记表同一写法）。 */
+export function stampNow() {
+  const d = new Date(Date.now() + 8 * 3600 * 1000);
+  const p = (n) => String(n).padStart(2, '0');
+  return d.getUTCFullYear() + '-' + p(d.getUTCMonth() + 1) + '-' + p(d.getUTCDate())
+    + ' ' + p(d.getUTCHours()) + ':' + p(d.getUTCMinutes()) + ' +0800';
+}
+
+export const KIND_LABEL = { global: '全局', project: '项目', misc: '杂项' };
+
+export function officePath(ws) {
+  return path.join(String(ws || ''), '_Control_Center', 'records', 'Office.json');
+}
+
+export function loadOffice(ws) {
+  let v = null;
+  try { v = JSON.parse(readUtf8(officePath(ws)).replace(/^\uFEFF/, '')); } catch { v = null; }
+  if (!v || typeof v !== 'object' || Array.isArray(v)) v = {};
+  if (!v.lineages || typeof v.lineages !== 'object' || Array.isArray(v.lineages)) v.lineages = {};
+  v.version = OFFICE_VERSION;
+  return v;
+}
+
+/** 原子写：临时文件 + rename，半截文件不会被下一次读当成事实。 */
+export function saveOffice(ws, store) {
+  const p = officePath(ws);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  store.version = OFFICE_VERSION;
+  store.updatedAt = stampNow();
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(store, null, 2) + NL, 'utf8');
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+/** 类别名：全局固定「全局」，项目用项目名，杂项用任务名。 */
+export function lineageKeyOf(kind, project, task) {
+  if (kind === 'global') return '全局';
+  if (kind === 'project') return String(project || '').trim();
+  if (kind === 'misc') return String(task || '').trim();
+  return '';
+}
+
+const GEN_RE = /^(.*\D)(\d+)$/;
+
+/** 名字去掉尾部代际：全局11 → 全局；没有数字返回空串。 */
+export function baseOf(name) {
+  const m = GEN_RE.exec(String(name || '').trim());
+  return m ? m[1] : '';
+}
+
+/** 名字里的代际号：全局11 → 11；没有数字返回 null。 */
+export function generationOf(name) {
+  const m = GEN_RE.exec(String(name || '').trim());
+  return m ? Number(m[2]) : null;
+}
+
+/** 下一编号：该类别历史上出现过的最大号 + 1；没有历史就从 1 起算。 */
+export function nextName(store, key) {
+  const lin = store && store.lineages ? store.lineages[key] : null;
+  const names = [];
+  if (lin && lin.current && lin.current.name) names.push(lin.current.name);
+  for (const h of (lin && Array.isArray(lin.history) ? lin.history : [])) {
+    if (h && h.name) names.push(h.name);
+  }
+  let max = 0;
+  for (const n of names) {
+    const g = generationOf(n);
+    if (g !== null && g > max) max = g;
+  }
+  return String(key) + String(max + 1);
+}
+
+/**
+ * 名字 → 类别。用户给的多半是不确定的名字（全局3、全局、Mingent、赢了两次的旧叫法），
+ * 按「类别名精确 → 去尾部编号 → 现任名 → 唯一子串」四步收敛；收敛不了就报候选，不瞎猜。
+ */
+export function resolveOffice(store, query) {
+  const q = String(query || '').trim();
+  if (!q) return { ok: false, reason: '空查询' };
+  const keys = Object.keys((store && store.lineages) || {});
+  const lower = q.toLowerCase();
+  let key = '';
+  let via = '';
+  const exact = keys.filter((k) => k.toLowerCase() === lower);
+  if (exact.length === 1) { key = exact[0]; via = 'exact'; }
+  if (!key) {
+    const base = baseOf(q);
+    if (base) {
+      const hit = keys.filter((k) => k.toLowerCase() === base.toLowerCase());
+      if (hit.length === 1) { key = hit[0]; via = 'generation'; }
+    }
+  }
+  if (!key) {
+    const hit = keys.filter((k) => {
+      const cur = store.lineages[k] && store.lineages[k].current;
+      return cur && cur.name && String(cur.name).toLowerCase() === lower;
+    });
+    if (hit.length === 1) { key = hit[0]; via = 'current'; }
+  }
+  if (!key) {
+    const hit = keys.filter((k) => {
+      const a = k.toLowerCase();
+      return a.indexOf(lower) !== -1 || lower.indexOf(a) !== -1;
+    });
+    if (hit.length === 1) { key = hit[0]; via = 'fuzzy'; }
+    else if (hit.length > 1) return { ok: false, reason: '与多个类别相近：' + hit.join('、') + '（请写全名）', candidates: hit };
+  }
+  if (!key) return { ok: false, reason: '没有名为「' + q + '」的全局、项目或杂项任务' };
+  const lin = store.lineages[key];
+  const cur = lin && lin.current;
+  if (!cur || !cur.name) return { ok: true, key, lineage: lin, via, vacant: true };
+  return { ok: true, key, lineage: lin, via, vacant: false };
+}
+
+export function rowsOf(store) {
+  const lines = (store && store.lineages) || {};
+  return Object.keys(lines).map((key) => {
+    const lin = lines[key] || {};
+    return {
+      key,
+      kind: String(lin.kind || ''),
+      project: String(lin.project || ''),
+      task: String(lin.task || ''),
+      workspace: String(lin.workspace || ''),
+      current: lin.current || null,
+    };
+  }).sort((a, b) => {
+    const order = { global: 0, project: 1, misc: 2 };
+    const d = (order[a.kind] === undefined ? 9 : order[a.kind]) - (order[b.kind] === undefined ? 9 : order[b.kind]);
+    return d !== 0 ? d : a.key.localeCompare(b.key, 'zh');
+  });
+}
+
+/** 一行人类可读：名字、会话 id、类别、（提到旧编号时的来处）。 */
+export function formatRow(row, askedAs) {
+  const cur = row && row.current;
+  if (!cur || !cur.name) return (row && row.key ? row.key : '?') + '  — 当前空缺';
+  const label = KIND_LABEL[row.kind] || row.kind || '-';
+  // 只有「拿旧编号问现任」时才加来处标注；直接问类别名或现任名就不必重复。
+  const tail = askedAs && askedAs !== cur.name && askedAs !== row.key ? '（' + askedAs + ' → ' + row.key + '）' : '';
+  return cur.name + '  ' + cur.sessionId + '  ' + label + (cur.since ? '  自 ' + cur.since : '') + tail;
+}
+
+/** 登记一位在任者：原在任者进历史，写盘后同步 Registry.md。 */
+export function registerHolder(ws, opts) {
+  const o = opts || {};
+  const key = lineageKeyOf(o.kind, o.project, o.task);
+  if (!key) throw new Error('类别名缺失：全局用 kind=global，项目给 project，杂项给 task');
+  const store = loadOffice(ws);
+  const lin = store.lineages[key] || (store.lineages[key] = {
+    kind: o.kind, project: String(o.project || ''), task: String(o.task || ''),
+    workspace: String(o.workspace || ''), current: null, history: [],
+  });
+  if (!Array.isArray(lin.history)) lin.history = [];
+  const previous = lin.current && lin.current.name ? { ...lin.current } : null;
+  if (previous) {
+    lin.history.push({
+      name: previous.name, sessionId: previous.sessionId,
+      from: previous.since || '', to: stampNow(), note: previous.note || '',
+    });
+  }
+  lin.kind = o.kind;
+  if (o.project) lin.project = String(o.project);
+  if (o.task) lin.task = String(o.task);
+  if (o.workspace) lin.workspace = String(o.workspace);
+  lin.current = { name: String(o.name || ''), sessionId: String(o.sessionId || ''), since: stampNow(), note: String(o.note || '') };
+  if (!lin.current.name || !lin.current.sessionId) throw new Error('在任登记需要 name 与 sessionId');
+  saveOffice(ws, store);
+  let registry = { changed: [], error: '' };
+  try { registry = syncRegistry(ws, store); } catch (e) { registry = { changed: [], error: String(e && e.message ? e.message : e) }; }
+  return { key, previous, current: lin.current, registry };
+}
+
+/** 类别当前空缺（会话退役、项目暂停）。 */
+export function retireHolder(ws, key, note) {
+  const store = loadOffice(ws);
+  const lin = store.lineages[String(key || '')];
+  if (!lin) throw new Error('没有这条类别：' + key);
+  const previous = lin.current && lin.current.name ? { ...lin.current } : null;
+  if (previous) {
+    lin.history.push({ name: previous.name, sessionId: previous.sessionId, from: previous.since || '', to: stampNow(), note: note || previous.note || '' });
+  }
+  lin.current = null;
+  saveOffice(ws, store);
+  let registry = { changed: [], error: '' };
+  try { registry = syncRegistry(ws, store); } catch (e) { registry = { changed: [], error: String(e && e.message ? e.message : e) }; }
+  return { key, previous, registry };
+}
+
+// ---------------------------------------------------------------- Registry.md 定点同步
+
+function splitCells(line) {
+  // "| a | b |" → ['', ' a ', ' b ', '']；保持两端空格原样，便于回写。
+  return line.split('|');
+}
+
+function tailOf(cell) {
+  const m = /（[^（）]*）\s*$/.exec(cell) || /\([^()]*\)\s*$/.exec(cell);
+  return m ? ' ' + m[0].trim() : '';
+}
+
+function currentCellFor(row, withName) {
+  const cur = row.current;
+  if (!cur || !cur.name) return null;
+  return withName ? cur.name + ' `' + cur.sessionId + '`' : '`' + cur.sessionId + '`';
+}
+
+/**
+ * 把 Registry.md 里的「在役会话」格改成登记表里的现任。
+ * 只认两张表（项目清单、未登记但存在的任务），只换那一格；其它文字一律不动。
+ */
+export function syncRegistry(ws, store) {
+  const file = path.join(String(ws || ''), '_Project_Meta', 'Registry.md');
+  let text = '';
+  try { text = readUtf8(file); } catch { return { changed: [], error: '读不到 Registry.md' }; }
+  const bom = text.charCodeAt(0) === 0xFEFF ? '\uFEFF' : '';
+  if (bom) text = text.slice(1);
+  const lines = text.split(NL);
+  const changed = [];
+  let mode = '';
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith('## ')) {
+      if (line.indexOf('项目清单') !== -1) mode = 'project';
+      else if (line.indexOf('未登记但存在的任务') !== -1) mode = 'misc';
+      else mode = '';
+      continue;
+    }
+    if (!mode || !line.startsWith('|')) continue;
+    const cells = splitCells(line);
+    // 表头与分隔行跳过
+    if (cells.length < 4) continue;
+    const name = String(cells[1] || '').trim();
+    if (!name || name === '项目名' || name === '任务短名' || /^-+$/.test(name)) continue;
+    const row = rowsOf(store).find((r) => r.key === name);
+    if (!row) continue;
+    if (mode === 'project') {
+      if (cells.length < 9) continue; // 8 列 + 首尾空
+      const old = String(cells[6] || '');
+      const next = currentCellFor(row, true);
+      if (!next) continue;
+      const want = ' ' + next + tailOf(old) + ' ';
+      if (old === want) continue;
+      cells[6] = want;
+    } else {
+      if (cells.length < 5) continue; // 4 列 + 首尾空
+      const next = currentCellFor(row, false);
+      if (!next) continue;
+      const want = ' ' + next + tailOf(String(cells[3] || '')) + ' ';
+      if (String(cells[3] || '') === want) continue;
+      cells[3] = want;
+    }
+    lines[i] = cells.join('|');
+    changed.push(name);
+  }
+  if (changed.length) fs.writeFileSync(file, bom + lines.join(NL), 'utf8');
+  return { changed, error: '' };
+}

package/src/lib/pack-ops.mjs

@@ -13,6 +13,7 @@ import { scanAbsoluteRefs, renderAbsoluteRefs } from './absrefs.mjs';
 import { stampTz } from './brief.mjs';
 import { scanSessions } from './sessions.mjs';
 import { lintProject } from './lint.mjs';
+import { assertProjectName, assertTaskName } from './role.mjs';
 
 const SKIP_DIRS = ['__pycache__', '.git', 'node_modules', '.obsidian'];
 const SKIP_FILES = ['.DS_Store', 'Thumbs.db'];
@@ -152,11 +153,13 @@ export function packNow(env, args, exec) {
     roots.push(['_Project_Meta', path.join(ws, '_Project_Meta')]);
   } else if (kind === 'project') {
     if (!name) throw new Error('kind=project 需要 name');
+    assertProjectName(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');
+    assertTaskName(name);
     roots.push(['_Misc/tasks/' + name, path.join(ws, '_Misc', 'tasks', name)]);
   } else throw new Error('未知 kind：' + kind);
   const entries = [];

package/src/lib/phase.mjs

@@ -15,19 +15,21 @@ export function decide(input) {
   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) {
-    if (used >= maxComp) return { action: 'new_session', reason: '已到硬顶且压缩额度用尽，应写交接并建新会话' };
-    return { action: 'force_compact', reason: '已到硬顶（' + Math.round(hard * 100) + '%）：强制压缩兜底，哪怕任务中途' };
+    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: '水位正常' };

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/role.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { readJsonDir, pick } from './text.mjs';
+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';
@@ -19,8 +19,8 @@ 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')],
+  project: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('gate'), nameOf('snapshot'), nameOf('profile'), nameOf('office'), nameOf('succeed'), peerNameOf('send'), peerNameOf('status')],
+  misc: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('snapshot'), nameOf('profile'), nameOf('office'), nameOf('succeed'), peerNameOf('send'), peerNameOf('status'), peerNameOf('new')],
   plain: [],
 };
 
@@ -65,18 +65,15 @@ export function writeRole(cfg, sessionId, patch) {
   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());
-  // 角色变了就重新引导一次；只是改项目名也重引导，因为路径变了。
-  if (prev.role !== next.role || prev.project !== next.project || prev.task !== next.task) delete next.bootstrappedAt;
   data.sessions[sid] = next;
   writeRolesFile(cfg, data);
   return next;
 }
 
-export function bootstrappedAt(cfg, sessionId) {
-  const cur = readRoles(cfg).sessions[String(sessionId || '')];
-  return cur && cur.bootstrappedAt ? String(cur.bootstrappedAt) : '';
-}
 
 // ---------------------------------------------------------------- 判定
 
@@ -99,24 +96,44 @@ function parts(p) {
   return String(p || '').replace(/\\/g, '/').split('/').filter(Boolean);
 }
 
-/** cwd 落在 Projects/<名>/ 或 _Misc/tasks/<任务>/ 里就据此判定。 */
+/** 项目名当目录名用，长度与字符集都比任务名紧一些；任务名放宽到 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' && seg[i + 1] && seg[i + 1] !== '_Project_Meta') {
+    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' && seg[i + 2]) {
+    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' && seg[i + 1]) {
+    if (seg[i] === '_Project_Meta' && projectNameOk(seg[i + 1])) {
       return { role: 'project', project: seg[i + 1], task: '' };
     }
   }
   return null;
 }
 
-/** 首条提示里能解析出 Projects/<名>/ 或「<名>」项目 就算项目会话。 */
+/** 首条提示里能解析出 Projects/<名>/ 或「<名>」项目 就算项目会话；名字不合法不认。 */
 function roleFromPrompt(text) {
   const t = String(text || '').replace(/\\/g, '/');   // Windows 路径也能解析
   const i = t.indexOf('Projects/');
@@ -127,13 +144,17 @@ function roleFromPrompt(text) {
       if (ch === '/' || ch === ' ' || ch === String.fromCharCode(9) || ch === String.fromCharCode(10) || ch === String.fromCharCode(13)) break;
       name += ch;
     }
-    if (name) return { role: 'project', project: name, task: '' };
+    // 首条提示常把规则写成 `_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) return { role: 'project', project: rest.slice(0, j), task: '' };
+    if (j > 0) {
+      const name = rest.slice(0, j);
+      if (projectNameOk(name)) return { role: 'project', project: name, task: '' };
+    }
   }
   return null;
 }
@@ -150,9 +171,15 @@ export function resolveRole(opts) {
   if (hit) {
     const role = String(hit.role || '');
     if (ROLES.indexOf(role) !== -1) {
-      return { role, project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
+      // 角色表里的名字要当目录名用。历史写入或手工编辑留下的非法名字一律不认，继续往下推断，
+      // 否则会把整条「写交接 → 备份 → 归档」链路卡在 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 是兜底态，按新口径并入普通。
+    // 旧角色表的 unknown 是备用状态，按新口径并入普通。
     if (role === 'unknown') {
       return { role: 'plain', project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
     }
@@ -188,11 +215,13 @@ export function handoverPathFor(ws, info) {
   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: '普通会话不参与交接' };
@@ -205,6 +234,11 @@ export function snapshotDirFor(ws, info) {
 }
 
 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');
 }

package/src/lib/schedule.mjs

@@ -1,7 +1,8 @@
-import fsx from "node:fs";
+import fsx from "node:fs";
 import osx from "node:os";
 import pathx from "node:path";
 import { checkConsent } from './consent.mjs';
+import { sendPrompt } from './prompt.mjs';
 
 /**
  * 压缩调度：compactNow 只允许 idle，所以 ho_checkpoint 只登记，轮次结束后由这里排程。
@@ -92,16 +93,8 @@ export function createScheduler(deps) {
     return fillResumePrompt(cfg, { n, handover: hp && hp.path ? hp.path : '', role: info && info.role ? info.role : 'plain' });
   }
 
-  async function promptSelf(sessionId, text) {
-    const controller = service('sessionController');
-    if (!controller || typeof controller.prompt !== "function") throw new Error("sessionController.prompt 不可用");
-    const req = {
-      requestId: (globalThis.crypto && globalThis.crypto.randomUUID) ? globalThis.crypto.randomUUID() : String(Date.now()),
-      sessionId,
-      mode: "queue",
-      content: [{ type: "text", text }],
-    };
-    return controller.prompt(req, new AbortController().signal);
+  function promptSelf(sessionId, text) {
+    return sendPrompt(service('sessionController'), sessionId, text, 'queue');
   }
 
   /**
@@ -146,7 +139,9 @@ export function createScheduler(deps) {
         return;
       }
       note("compacted " + sessionId + " shadowed=" + (result.shadowedTokenCount || "?"));
-      if (cfg.autoResume !== false) {
+      // resume=wait：任务已收尾，压缩后不唤醒，等用户派新任务。
+      // resume=continue（默认）：照旧投续跑消息，按交接 §2 继续。
+      if (cfg.autoResume !== false && job.resume !== "wait") {
         const text = resumeText(sessionId, job.n);
         try {
           await promptSelf(sessionId, text);
@@ -156,7 +151,8 @@ export function createScheduler(deps) {
           note("resume prompt failed: " + e.message);
         }
       } else {
-        job.done("ok", result);
+        if (job.resume === "wait") note("resume skipped (wait): " + sessionId);
+        job.done(job.resume === "wait" ? "ok-wait" : "ok", result);
       }
       pending.delete(sessionId);
     } catch (e) {
@@ -209,7 +205,7 @@ export function createScheduler(deps) {
           return;
         }
       }
-      pending.set(sessionId, { n: opts.n || 0, attempts: 0, done, startedAt: Date.now() });
+      pending.set(sessionId, { n: opts.n || 0, resume: opts.resume === "wait" ? "wait" : "continue", attempts: 0, done, startedAt: Date.now() });
       retryLater(sessionId, opts.delayMs === undefined ? 600 : opts.delayMs);
     });
   }

package/src/lib/session-create.mjs

@@ -0,0 +1,42 @@
+/**
+ * 新建会话的唯一落点：建会话、改名、登记角色、当场装配。
+ * ho_sessions(new)、设置页一键部署与补建全局会话共用这一段，避免三处各写一遍。
+ */
+
+/**
+ * @param env 插件环境（需要 controller、writeRole、applyScopedLive）
+ * @param opts { workspaceId?, cwd?, title?, role?, project?, task? }
+ * @returns { sessionId, workspaceId, error }
+ */
+export async function newSessionIn(env, opts) {
+  const o = opts || {};
+  const controller = typeof env.controller === 'function' ? env.controller() : null;
+  if (!controller || typeof controller.create !== 'function') {
+    return { error: 'sessionController.create 不可用' };
+  }
+  const workspaceId = String(o.workspaceId || '');
+  const cwd = String(o.cwd || '');
+  if (!workspaceId && !cwd) return { error: '建会话要么给 workspaceId，要么给 cwd' };
+  let created = null;
+  try {
+    created = workspaceId ? await controller.create({ workspaceId }) : await controller.create({ cwd });
+  } catch (e) {
+    return { error: '建会话失败：' + String(e && e.message ? e.message : e) };
+  }
+  const sessionId = String((created && created.sessionId) || '');
+  if (!sessionId) return { error: 'create 没有返回 sessionId' };
+  const title = String(o.title || '');
+  if (title) {
+    try { if (typeof controller.rename === 'function') await controller.rename({ sessionId, title }); } catch { /* 改名失败可事后 peer_rename */ }
+  }
+  const role = String(o.role || '');
+  if (role && role !== 'plain' && typeof env.writeRole === 'function') {
+    try {
+      env.writeRole(sessionId, { role, project: String(o.project || ''), task: String(o.task || ''), source: 'create' });
+    } catch { /* 角色登记失败不影响建会话 */ }
+  }
+  if (typeof env.applyScopedLive === 'function') {
+    try { env.applyScopedLive(sessionId, { role: role || 'plain', project: String(o.project || ''), task: String(o.task || '') }); } catch { /* 下一轮的开轮核对会补齐 */ }
+  }
+  return { sessionId, workspaceId };
+}