dsh-compact-relay 0.5.1 → 0.5.3

package/lib/actions/favorite.js

@@ -0,0 +1,435 @@
+/**
+ * 收藏的动作层 —— 命令与 HTTP 共用，不含 UI。
+ *
+ * 与旧 pin 的区别：pin 是「压缩时截断范围」，收藏**不改变压缩选段**，
+ * 只在压缩摘要里留一段目录 + 让用户随时按序号取回原文。
+ */
+import { actionError } from '../core/errors.js';
+import { roleLabelOf } from '../core/pin-anchors.js';
+import { decideFavoriteSuggest } from '../core/favorite-score.js';
+import { FAVORITE_MAX, buildFavoriteDirectoryLines, buildFavoriteTitle } from '../core/favorites.js';
+import { appendFavoriteRecord, appendSnapshotEntries, favoriteMapForRoot, favoritesFileForRoot, favoriteMapOf, favoritesFileOf, rootSessionIdOfId, snapshotFileOf, snapshotTextFor } from '../dsh/favorites-file.js';
+import { scoreFavoriteMessage } from '../dsh/favorite-scorer.js';
+import { sessionLog, surfaceSeqs } from '../dsh/session-view.js';
+
+/** 粗略 token 估算（字符数 / 2）——只用于「先报体积」，不参与预算决策。 */
+export function estimateTextTokens(text) {
+  const length = typeof text === 'string' ? text.length : 0;
+  return Math.max(1, Math.round(length / 2));
+}
+
+function blockTextOf(block) {
+  return block !== null && typeof block === 'object' && typeof block.text === 'string' ? block.text : '';
+}
+
+/**
+ * 从事件里抠完整原文（content 可能是字符串或 block 数组）。
+ * @param {object|undefined} event
+ * @returns {string}
+ */
+export function eventTextOf(event) {
+  const data = event !== null && typeof event === 'object' ? event.data : undefined;
+  const candidates = [data?.content, data?.message?.content];
+  for (const content of candidates) {
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+      const text = content.map(blockTextOf).filter((part) => part.length > 0).join('\n');
+      if (text.length > 0) return text;
+    }
+  }
+  return '';
+}
+
+/**
+ * messageId → seq：扫会话日志匹配宿主消息 id。
+ * 助手消息的 id 在 `data.message.id`，用户消息在 `data.id`（2026-10-28 真机核实）。
+ * @param {object} session
+ * @param {string} messageId
+ * @returns {number|null}
+ */
+export function seqOfMessageId(session, messageId) {
+  if (typeof messageId !== 'string' || messageId.length === 0) return null;
+  const log = sessionLog(session);
+  for (let index = log.length - 1; index >= 0; index -= 1) {
+    const event = log[index];
+    const data = event?.data;
+    if (data === null || typeof data !== 'object') continue;
+    if (event.type === 'assistant/message' && data.message?.id === messageId) return event.seq;
+    if (event.type === 'user/message' && data.id === messageId) return event.seq;
+  }
+  return null;
+}
+
+/**
+ * messageId 落在哪个**活会话**里（收藏兜底用）。
+ *
+ * 客户端可能没带 sessionId、或带的是切换前的旧会话：messageId 是宿主生成的 UUID，
+ * 扫一遍活 agent 的会话日志即可反查。命中 0 个或多个都返回 null——宁可报错，也不收错会话。
+ * @param {{ctx:object}} deps
+ * @param {string} messageId
+ * @returns {object|null}
+ */
+export function ownerAgentOfMessage(deps, messageId) {
+  const agents = deps?.ctx?.agents;
+  if (agents === null || agents === undefined || typeof agents.list !== 'function') return null;
+  if (typeof messageId !== 'string' || messageId.length === 0) return null;
+  let all = [];
+  try {
+    all = agents.list();
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(all)) return null;
+  const hits = [];
+  for (const candidate of all) {
+    const session = candidate?.session;
+    if (session === null || session === undefined) continue;
+    if (seqOfMessageId(session, messageId) !== null) hits.push(candidate);
+  }
+  return hits.length === 1 ? hits[0] : null;
+}
+
+function sessionOf(agent) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('favorite', '当前没有打开的会话');
+  return session;
+}
+
+function writeFavorite(deps, session, op, seq) {
+  const record = {
+    schema: 'dcr-favorite/v1',
+    op,
+    sessionId: session.id,
+    seq,
+    at: Date.now(),
+  };
+  return appendFavoriteRecord(record, favoritesFileOf(deps.ctx, session)).ok;
+}
+
+function liveFavoriteSeqs(deps, session) {
+  const map = favoriteMapOf(deps.ctx, session);
+  const set = map.get(session.id);
+  return set === undefined ? [] : [...set].sort((a, b) => a - b);
+}
+
+/** 收藏 / 取消收藏一条消息（按宿主 messageId，UI 按钮走这里）。 */
+export function toggleFavorite(deps, { agent, messageId } = {}) {
+  if (typeof messageId !== 'string' || messageId.length === 0) throw actionError('favorite', '缺少 messageId');
+  // 传进来的 agent 不一定对（多会话时客户端可能带错 sessionId）：先认它，认不出再按 messageId 反查。
+  const owner = (() => {
+    const passed = agent?.session;
+    if (passed !== null && passed !== undefined && seqOfMessageId(passed, messageId) !== null) return agent;
+    return ownerAgentOfMessage(deps, messageId);
+  })();
+  if (owner === null) {
+    throw actionError('favorite', '找不到这条消息所属的会话（会话可能已关闭，或这条已被压缩）');
+  }
+  const session = sessionOf(owner);
+  const seq = seqOfMessageId(session, messageId);
+  if (seq === null) throw actionError('favorite', '找不到这条消息（会话可能被压缩过），换一条试试');
+  const set = new Set(liveFavoriteSeqs(deps, session));
+  if (set.has(seq)) {
+    writeFavorite(deps, session, 'remove', seq);
+    set.delete(seq);
+    return { active: false, seq, count: set.size, message: '已取消收藏' };
+  }
+  if (set.size >= FAVORITE_MAX) throw actionError('favorite', `这条工作的收藏已达上限 ${FAVORITE_MAX} 条，先取消一些`);
+  writeFavorite(deps, session, 'add', seq);
+  set.add(seq);
+  return { active: true, seq, count: set.size, message: '已收藏' };
+}
+
+/**
+ * 按「会话 id + seq」收藏/取消（**不要求活会话**）——归档/关闭的会话也能标。
+ *
+ * 这是「标记」与「压缩落档」解耦的第一步：标记只写一行 JSONL，不读会话日志、不碰压缩。
+ * 链根解析走 `ctx.get('workspaceRegistry').readSessionHeader`（对已存会话同样可读）；
+ * 解析不到就把 sessionId 当根（不猜更多）。写失败明确报错，不假装成功。
+ *
+ * @param {{ctx:object}} deps
+ * @param {{sessionId:string, seq:number, active?:boolean}} input
+ *   active 省略 = 切换；true = 只加；false = 只删。已是目标状态时幂等返回（不重复写）。
+ * @returns {Promise<{active:boolean, seq:number, count:number, sessionId:string, note?:string, message:string}>}
+ */
+export async function markFavoriteBySeq(deps, { sessionId, seq, active } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) throw actionError('favorite', '缺少 sessionId');
+  if (!Number.isInteger(seq) || seq < 0) throw actionError('favorite', '缺少或非法的消息序号 seq（应为非负整数）');
+  const rootId = (await rootSessionIdOfId(deps.ctx, sessionId)) ?? sessionId;
+  const file = favoritesFileForRoot(rootId);
+  const map = favoriteMapForRoot(rootId);
+  const set = new Set(map.get(sessionId) ?? []);
+  const already = set.has(seq);
+  // active 省略 = 切换；true/false = 只加/只删，已是目标状态就幂等返回（不重复写盘）。
+  let add;
+  if (active === undefined) {
+    add = !already;
+  } else if (active === true) {
+    if (already) return { active: true, seq, count: set.size, sessionId, note: 'already', message: `第 ${seq} 条已经收藏过了` };
+    add = true;
+  } else {
+    if (!already) return { active: false, seq, count: set.size, sessionId, note: 'already', message: `第 ${seq} 条本来就没收藏` };
+    add = false;
+  }
+  if (add && set.size >= FAVORITE_MAX) throw actionError('favorite', `这条工作的收藏已达上限 ${FAVORITE_MAX} 条，先取消一些`);
+  const record = { schema: 'dcr-favorite/v1', op: add ? 'add' : 'remove', sessionId, seq, at: Date.now() };
+  const written = appendFavoriteRecord(record, file);
+  if (written.ok !== true) throw actionError('favorite', '收藏文件写不进去（检查 ~/.dsh 的权限）');
+  if (add) set.add(seq);
+  else set.delete(seq);
+  return {
+    active: add,
+    seq,
+    count: set.size,
+    sessionId,
+    message: add ? `已收藏第 ${seq} 条` : `已取消收藏第 ${seq} 条`,
+  };
+}
+
+/** 日志里最后一条助手消息的 seq（命令 /favorite mark 不带参数时用）。 */
+function lastAssistantSeqOf(session) {
+  const log = sessionLog(session);
+  for (let index = log.length - 1; index >= 0; index -= 1) {
+    const event = log[index];
+    if (event !== null && typeof event === 'object' && event.type === 'assistant/message') return event.seq;
+  }
+  return null;
+}
+
+/**
+ * 命令 `/favorite mark [seq]`：按 seq 收藏（不传 seq = 最后一条已完成的助手回复）。
+ * 与星标共用同一个 JSONL；绝不因为「消息被压走」就静默失败——那条不在日志里会明确报错。
+ */
+export function markFavoriteInSession(deps, { agent, seq } = {}) {
+  const session = sessionOf(agent);
+  const target = seq === undefined ? lastAssistantSeqOf(session) : seq;
+  if (target === null) throw actionError('favorite', '这个会话里还没有助手回复可收藏');
+  if (!Number.isInteger(target) || target < 0) throw actionError('favorite', '序号须为非负整数，例如 /favorite mark 1234');
+  const event = typeof session.eventAt === 'function' ? session.eventAt(target) : undefined;
+  if (event === undefined || event === null) {
+    throw actionError('favorite', `没有 seq ${target} 这条消息（可能已被压缩或清理）；要标别的先看 /favorite list 或压缩摘要里的序号`);
+  }
+  const set = new Set(liveFavoriteSeqs(deps, session));
+  if (set.has(target)) {
+    const snapshot = snapshotIfCompacted(deps, session, target, event);
+    return {
+      active: true,
+      seq: target,
+      count: set.size,
+      note: 'already',
+      snapshot,
+      message: snapshot === 'written' ? `第 ${target} 条已经收藏过了（原文已补写进快照）` : `第 ${target} 条已经收藏过了`,
+    };
+  }
+  if (set.size >= FAVORITE_MAX) throw actionError('favorite', `这条工作的收藏已达上限 ${FAVORITE_MAX} 条，先取消一些`);
+  if (writeFavorite(deps, session, 'add', target) !== true) throw actionError('favorite', '收藏文件写不进去（检查 ~/.dsh 的权限）');
+  set.add(target);
+  const snapshot = snapshotIfCompacted(deps, session, target, event);
+  return {
+    active: true,
+    seq: target,
+    count: set.size,
+    snapshot,
+    message: `已收藏第 ${target} 条${snapshot === 'written' ? '（这条已被压走，原文已写进快照）' : ''}`,
+  };
+}
+
+/**
+ * P0-3 兜底：给「已经被压走、但原文还在日志里」的收藏**当场写快照**。
+ *
+ * 压缩摘要里的「收藏（本段）」是压缩那一刻的快照，之后补标不会回写摘要；
+ * 不写快照就会出现「标记在、原文读不到」。这里只兜日志可读的情形
+ * （读不到就保持无快照，由 read 侧明确报错；完整档案读取是 0.6）。
+ * @returns {'written'|'present'|'none'}
+ */
+function snapshotIfCompacted(deps, session, seq, event) {
+  if (event === undefined || event === null) return 'none';
+  const surface = new Set(surfaceSeqs(session));
+  if (surface.has(seq)) return 'none'; // 还在界面上：走正常星标路径，不需要兜底
+  const file = snapshotFileOf(deps.ctx, session);
+  if (snapshotTextFor(file, seq) !== null) return 'present';
+  const text = eventTextOf(event);
+  if (text.length === 0) return 'none';
+  const written = appendSnapshotEntries(file, [
+    { seq, role: roleLabelOf(event.type), title: buildFavoriteTitle(event), text, at: Date.now() },
+  ]);
+  return written.ok === true && written.written === 1 ? 'written' : 'none';
+}
+
+/** 收藏「我刚发的最后一条」。 */export function favoriteLast(deps, { agent } = {}) {
+  const session = sessionOf(agent);
+  const seqs = surfaceSeqs(session);
+  let seq = null;
+  for (let index = seqs.length - 1; index >= 0; index -= 1) {
+    const event = typeof session.eventAt === 'function' ? session.eventAt(seqs[index]) : undefined;
+    if (event?.type === 'user/message' && event.data?.source?.kind === 'user') {
+      seq = seqs[index];
+      break;
+    }
+  }
+  if (seq === null) throw actionError('favorite', '没有找到你发的消息');
+  const set = new Set(liveFavoriteSeqs(deps, session));
+  if (set.has(seq)) {
+    writeFavorite(deps, session, 'remove', seq);
+    return { active: false, seq, count: set.size, message: '已取消收藏（这条本来已收藏）' };
+  }
+  if (set.size >= FAVORITE_MAX) throw actionError('favorite', `这条工作的收藏已达上限 ${FAVORITE_MAX} 条`);
+  writeFavorite(deps, session, 'add', seq);
+  set.add(seq);
+  return { active: true, seq, count: set.size, message: '已收藏你刚发的这条' };
+}
+
+/** 当前会话收藏的条目（编号从 1 开始，按 seq 升序）。 */
+export function favoriteEntries(deps, session) {
+  return liveFavoriteSeqs(deps, session).map((seq, index) => {
+    const event = typeof session.eventAt === 'function' ? session.eventAt(seq) : undefined;
+    const live = event !== undefined && event !== null;
+    const snapshot = live ? null : snapshotTextFor(snapshotFileOf(deps.ctx, session), seq);
+    const status = live ? 'live' : snapshot !== null ? 'snapshot' : 'lost';
+    return {
+      index: index + 1,
+      seq,
+      role: live ? roleLabelOf(event?.type) : '原消息',
+      title: live ? buildFavoriteTitle(event) : snapshot !== null ? snapshot.replace(/\s+/gu, ' ').slice(0, 60) : '（原文已不可达）',
+      tokens: estimateTextTokens(live ? eventTextOf(event) : snapshot ?? ''),
+      status,
+    };
+  });
+}
+
+/** 列表（目录）。 */
+export function listFavorites(deps, { agent } = {}) {
+  const session = sessionOf(agent);
+  const entries = favoriteEntries(deps, session);
+  const lines = buildFavoriteDirectoryLines(entries, 20);
+  const lost = entries.filter((entry) => entry.status !== 'live').length;
+  const lostNote =
+    lost === 0
+      ? ''
+      : `\n其中 ${lost} 条原件日志已不在：${entries
+          .filter((entry) => entry.status !== 'live')
+          .map((entry) => `${entry.index}${entry.status === 'snapshot' ? '（可用快照读）' : '（快照也没有）'}`)
+          .join('、')}`;
+  return {
+    entries,
+    count: entries.length,
+    message:
+      entries.length === 0
+        ? '当前会话还没有收藏。点消息下面的星，或输入 /favorite last 收藏你刚发的这条。'
+        : `当前会话收藏 ${entries.length} 条：\n${lines.join('\n')}${lostNote}\n\n读原文：/favorite <序号>（先报体积）｜取消：/favorite rm <序号>`,
+  };
+}
+
+function entryOf(deps, session, index) {
+  const wanted = Number(index);
+  if (!Number.isInteger(wanted) || wanted < 1) throw actionError('favorite', '序号须为正整数，例如 /favorite 2');
+  const entries = favoriteEntries(deps, session);
+  const entry = entries.find((item) => item.index === wanted);
+  if (entry === undefined) {
+    throw actionError('favorite', `没有第 ${wanted} 条（当前共 ${entries.length} 条，用 /favorite list 查看）`);
+  }
+  return entry;
+}
+
+/** 读原文（先报体积，不输出正文）。 */
+export function readFavoriteInfo(deps, { agent, index } = {}) {
+  const session = sessionOf(agent);
+  const entry = entryOf(deps, session, index);
+  return {
+    entry,
+    message: `第 ${entry.index} 条（${entry.role}）：${entry.title}\n原文约 ${entry.tokens} token。要读的话输入：/favorite ${entry.index} read`,
+  };
+}
+
+/** 读原文正文（用户已经看过体积并确认）。 */
+export function readFavoriteFull(deps, { agent, index } = {}) {
+  const session = sessionOf(agent);
+  const entry = entryOf(deps, session, index);
+  const event = typeof session.eventAt === 'function' ? session.eventAt(entry.seq) : undefined;
+  let text = eventTextOf(event);
+  let source = 'log';
+  if (text.length === 0) {
+    const snapshot = snapshotTextFor(snapshotFileOf(deps.ctx, session), entry.seq);
+    if (snapshot !== null) {
+      text = snapshot;
+      source = 'snapshot';
+    }
+  }
+  if (text.length === 0) {
+    throw actionError('favorite', '这条收藏的原文已不可达（日志与压缩快照里都没有；可能日志被清理且从未经过压缩）');
+  }
+  const note = source === 'snapshot' ? '（来自压缩快照：原件日志已不在）' : '';
+  return {
+    entry,
+    text,
+    source,
+    message: `第 ${entry.index} 条原文${note}（约 ${entry.tokens} token）：\n\n${text}`,
+  };
+}
+
+/** 取消收藏（按序号）。 */
+export function unfavoriteByIndex(deps, { agent, index } = {}) {
+  const session = sessionOf(agent);
+  const entry = entryOf(deps, session, index);
+  writeFavorite(deps, session, 'remove', entry.seq);
+  return { seq: entry.seq, message: `已取消收藏第 ${entry.index} 条：${entry.title}` };
+}
+
+/**
+ * 推荐收藏「试算」（0.5.3 P1-7）：按传入（或当前配置）档位/词表跑一次真实打分 + 判定。
+ * 只读：不写收藏、不改变任何状态；失败时 `score:null` + decisionReason 说明。
+ *
+ * @param {{ctx:object, engine:object, cfg:object, log?:object}} deps
+ * @param {{agent:object, text:string, level?:string, mustWords?:unknown, muteWords?:unknown}} input
+ * @returns {Promise<{score:number|null, scoreReason:string, suggest:boolean, decisionReason:string, matched:string|null, level:string|null}>}
+ */
+export async function trialFavoriteScore(deps, { agent, text, level, mustWords, muteWords } = {}) {
+  const body = typeof text === 'string' ? text : '';
+  const useLevel = level ?? deps.cfg?.favorite?.level;
+  const useMust = mustWords ?? deps.cfg?.favorite?.mustWords;
+  const useMute = muteWords ?? deps.cfg?.favorite?.muteWords;
+  const scored = await scoreFavoriteMessage(deps, { agent, text: body });
+  const decision = decideFavoriteSuggest({
+    text: body,
+    score: scored?.score ?? null,
+    level: useLevel,
+    mustWords: useMust,
+    muteWords: useMute,
+  });
+  return {
+    score: scored?.score ?? null,
+    scoreReason: scored?.reason ?? '',
+    suggest: decision.suggest === true,
+    decisionReason: decision.reason,
+    matched: decision.matched,
+    level: typeof useLevel === 'string' ? useLevel : null,
+  };
+}
+
+/**
+ * 推荐收藏（半自动）—— 命令 `/favorite suggest` 的出口。
+ *
+ * 0.5.3 P1-6：建议由 `dsh/favorite-watch.js` 在助手消息落地后异步打分生成（模型 0-100 +
+ * 三档阈值 + 必亮/屏蔽词），这里只读内存投影，不再做规则匹配。
+ * 红线不变：命令只**列出**建议，不写收藏；确认仍要用户点星或 `/favorite mark`。
+ */
+export function listFavoriteSuggestions(deps, { agent } = {}) {
+  const session = sessionOf(agent);
+  const suggestions = deps.favoriteWatch?.suggestionOf?.(session.id) ?? [];
+  const roleOf = (item) => {
+    const event = typeof session.eventAt === 'function' ? session.eventAt(item.seq) : undefined;
+    return roleLabelOf(event?.type ?? '');
+  };
+  return {
+    suggestions,
+    message:
+      suggestions.length === 0
+        ? '暂时没有推荐。推荐会在每轮助手回复落地后自动打分（默认标准档≥75 才亮），' +
+          '也可以手动点星或 /favorite mark。'
+        : `建议收藏这 ${suggestions.length} 条（只点亮、不会自动收藏）：\n${suggestions
+            .map((item) => {
+              const score = typeof item.score === 'number' ? `${item.score} 分` : '必亮词命中';
+              return `- 第 ${item.seq} 条（${roleOf(item)}）：${score}${item.matched !== null && item.matched !== undefined ? ` — ${item.matched}` : ''}`;
+            })
+            .join('\n')}\n\n确认收藏：点消息下面的星，或 /favorite mark <seq>`,
+  };
+}

package/lib/actions/force-archive.js

@@ -0,0 +1,161 @@
+/**
+ * 0.5.2 L 项：**强制归档旧会话**（显式用户确认后才停止后台任务）。
+ *
+ * 背景：自动归档（`dsh/handoff-archive.js:archiveHandoffSource`）在旧会话还有
+ * turn/subagent/job/schedule 时**故意不归档**（`status:'active'`）—— 静默杀后台任务
+ * 比「旧会话多留一行」破坏性大得多。但这也意味着「旧会话一直有任务在跑」时用户
+ * 没有清理出路（0.5.x 补丁计划 P4）。这里补的就是那条**显式**出路：
+ *
+ *   - 只有 `confirmStop === true`（用户在二次确认里点过「强制归档（停止任务）」）
+ *     才会调用 `workspaceRegistry.archiveSession(sessionId, { stopActivity: true })`；
+ *   - 没有确认 → 直接拒绝（不静默降级成普通归档，也不静默停止任务）；
+ *   - 旧会话在侧栏置顶时要求 `confirmUnpin === true`（宿主归档会在同一次写盘里
+ *     取消置顶），否则返回 `pinned` + 现有置顶文案，**不归档**；
+ *   - 失败抛可读错误（`code:'force-archive'`），不吞、不假装成功。
+ *
+ * 宿主实证（`@deepseek-ai/dsh-workspace/lib/index.js`）：
+ *   - `archiveSession(id)` 先跑 `workspace/session-activity` waterfall，有 provider
+ *     报活就抛 `WorkspaceActiveSessionError`（带 `activity` 数组）；
+ *   - `archiveSession(id, { stopActivity:true })` 跳过活动检查、先写归档集合，再
+ *     `workspace/session-stop` 停止旧会话的 turn/subagent/job/schedule；
+ *   - 归档与置顶互斥：同一笔写盘会把该 id 从 `pinnedSessionIds` 移除。
+ */
+import { actionError } from '../core/errors.js';
+import {
+  archivedSessionIdsOf,
+  handoffArchiveNoteOf,
+  isSessionArchived,
+  isSessionPinned,
+  workspaceRegistryOf,
+} from '../dsh/handoff-archive.js';
+
+function errorMessageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * 强制归档旧会话（会停止它上面正在跑的 turn / subagent / job / schedule）。
+ *
+ * 返回值（全部 `ok:true`；失败一律抛 `actionError('force-archive', …)`）：
+ *   - `status:'archived'`  刚写入归档集合（已停止任务）；
+ *   - `status:'already'`   之前就已经归档（幂等，不再写盘、不再停任务）；
+ *   - `status:'pinned'`    已置顶且未确认取消置顶 —— **没有归档**，note 是现有置顶文案。
+ * 三种情况的 `note` 都复用 `handoffArchiveNoteOf`（与交接自动归档同一套告知文案）。
+ *
+ * @param {{ctx:object, log?:{warn?:Function}}} deps
+ * @param {{sessionId:string, confirmStop:boolean, confirmUnpin?:boolean}} input
+ *   sessionId 是**旧会话** id（不是当前会话）；confirmStop 必须是 true（二次确认的凭证）。
+ * @returns {Promise<{ok:true, status:'archived'|'already'|'pinned', archived:boolean, note:string, archivedCount:number|null, newlyArchived:string[], stopActivity?:'done'|'skipped'|'failed'}>}
+ */
+export async function forceArchiveSession(deps, { sessionId, confirmStop, confirmUnpin } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw actionError('force-archive', '缺少要强制归档的会话 id', undefined, 400);
+  }
+
+  const registry = workspaceRegistryOf(deps.ctx);
+  if (registry === null || typeof registry.archiveSession !== 'function') {
+    throw actionError('force-archive', '当前 DSH 宿主没有 Workspace 归档接口，无法强制归档旧会话', undefined, 503);
+  }
+
+  const archivedCountOf = () => {
+    const ids = archivedSessionIdsOf(deps.ctx);
+    return Array.isArray(ids) ? ids.length : null;
+  };
+
+  // 0.5.3 P2-1：幂等判断在 confirmStop 之前 —— 已归档 + 不带确认应回 already（200），
+  // 不再因为「没带二次确认」先 400（devgod 052 真机：已归档会话点归档直接报错）。
+  if (isSessionArchived(deps.ctx, sessionId) === true) {
+    const base = handoffArchiveNoteOf({ status: 'already', archived: true });
+    // 0.5.3 P2-下：already 防漏杀加固 —— 归档会话可能在归档前还有后台任务残留。
+    // 用户这次显式要求「强制归档」时，补跑一次 stopActivity 兜底（幂等）；未要求则明确
+    // 报告「本次未执行 stopActivity」，不假装已经停干净。
+    if (confirmStop === true) {
+      try {
+        await registry.archiveSession(sessionId, { stopActivity: true });
+        return {
+          ok: true,
+          status: 'already',
+          archived: true,
+          stopActivity: 'done',
+          note: `${base}（本次已补停旧会话上的任务）`,
+          archivedCount: archivedCountOf(),
+          newlyArchived: [],
+        };
+      } catch (error) {
+        deps.log?.warn?.(`compact-relay: 补停归档会话 ${sessionId} 的任务失败：${errorMessageOf(error)}`);
+        return {
+          ok: true,
+          status: 'already',
+          archived: true,
+          stopActivity: 'failed',
+          note: `${base}（补停任务失败：${errorMessageOf(error)}）`,
+          archivedCount: archivedCountOf(),
+          newlyArchived: [],
+        };
+      }
+    }
+    return {
+      ok: true,
+      status: 'already',
+      archived: true,
+      stopActivity: 'skipped',
+      note: `${base}（本次未执行 stopActivity）`,
+      archivedCount: archivedCountOf(),
+      newlyArchived: [],
+    };
+  }
+
+  // 防御性：真正要归档的路径仍然要求显式确认（HTTP 层与客户端都会带）。
+  if (confirmStop !== true) {
+    throw actionError(
+      'force-archive',
+      '强制归档会停止旧会话上正在跑的任务，需要显式确认（confirmStop:true）',
+      undefined,
+      400,
+    );
+  }
+
+  // 置顶保护：归档会取消置顶（宿主在同一笔写盘里做），必须用户单独确认；
+  // 读不到置顶集合（null）时不猜 —— 按「未置顶」继续，由宿主自己决定。
+  if (confirmUnpin !== true && isSessionPinned(deps.ctx, sessionId) === true) {
+    deps.log?.warn?.(
+      `compact-relay: 旧会话 ${sessionId} 在侧栏置顶，未确认取消置顶前不强制归档（归档会取消置顶）`,
+    );
+    return {
+      ok: true,
+      status: 'pinned',
+      archived: false,
+      // 0.5.2 审查 P1-3：本场景没有「交接确认」可点，不能复用交接流程的 pinned 文案。
+      note: '旧会话已置顶，本次未归档（归档会取消置顶）；确认「仍然归档（取消置顶）」后才会归档并可恢复。',
+      archivedCount: archivedCountOf(),
+      newlyArchived: [],
+    };
+  }
+
+  try {
+    // 唯一允许传 stopActivity 的地方：用户已确认「会停止旧会话上正在跑的任务」。
+    await registry.archiveSession(sessionId, { stopActivity: true });
+  } catch (error) {
+    deps.log?.warn?.(`compact-relay: 强制归档旧会话 ${sessionId} 失败：${errorMessageOf(error)}`);
+    const unknown = error !== null && typeof error === 'object' && error.name === 'WorkspaceUnknownSessionError';
+    throw actionError(
+      'force-archive',
+      unknown
+        ? `强制归档失败：宿主里找不到这个会话（${errorMessageOf(error)}）`
+        : `强制归档失败：${errorMessageOf(error)}`,
+      error,
+      unknown ? 404 : 500,
+    );
+  }
+
+  return {
+    ok: true,
+    status: 'archived',
+    archived: true,
+    note: handoffArchiveNoteOf({ status: 'archived', archived: true }),
+    // 0.5.3 P3-a：不再回全量归档集合（142 条 ≈ 7KB，随归档线性增长，客户端根本不读）。
+    // 只回数量 + 本次新归档的 id，语义与体积都对。
+    archivedCount: archivedCountOf(),
+    newlyArchived: [sessionId],
+  };
+}

package/lib/actions/handoff.js

@@ -30,11 +30,12 @@ import { buildSiteSnapshot } from '../dsh/site-info.js';
 import { generateHandoffDoc } from '../dsh/handoff-writer.js';
 import { buildHandoffProgramSections } from '../core/handoff-facts.js';
 import { checkHandoffReadiness } from '../core/readiness.js';
+import { parentRelayRecordOf } from '../core/relay-record.js';
 import { changedFilesOf } from '../dsh/session-files.js';
 import { errorCodeOf, localIso } from '../dsh/diag-counters.js';
 import { surfaceMessages } from '../dsh/prefix.js';
 import { handoffTitlePlanOf, createHandoffSession, renameHistoryOf, sourceTitleOf } from '../dsh/sessions.js';
-import { writeRelayRecord } from '../dsh/relay.js';
+import { relayInboundRecordOf, writeRelayRecord } from '../dsh/relay.js';
 import { archiveHandoffSource, handoffArchiveNoteOf, isSessionPinned } from '../dsh/handoff-archive.js';
 import { withLock } from './lock.js';
 import { beginInflight, cancelErrorOf, combinedSignal, finishInflight } from './support.js';
@@ -263,29 +264,34 @@ async function runHandoff(deps, { agent, signal, commandId, edits, archive, conf
       });
 
       // A5：把接力链写成父会话里的结构化记录；写失败不阻断交接（标题解析仍可兜底）。
-      // 0.4 P2-2：canonical 字段 parentId/childId/ordinal/at/atIso 补齐；旧字段 parentSessionId/index 保留兼容。
-      // 0.5.0：父/子记录都写 scheme（本次链的命名方案）+ titleSeq（各自 rename 的 eventSeq）；
-      // 新链父记录再写 historyTitle（旧会话改名后的标题），供审计/幂等核对。
+      // 0.5.2 S2：形状（含 0.3 旧字段双写、planId、条件写入的 historyTitle、**键顺序**）
+      // 全部由 core/relay-record 的唯一构造器负责，这里只传语义参数。
+      // historyTitle 只在改名真的生效（renamed / already）时传；失败/服务不可用时
+      // 不能记一个不存在的标题 —— 构造器对空/非字符串一律不写这个键。
       const relayAt = Date.now();
-      const relayWrote = writeRelayRecord(deps.engine, session, {
-        parentId: session.id,
-        childId: created.childId,
-        ordinal: titlePlan.index,
-        at: relayAt,
-        atIso: localIso(new Date(relayAt)),
-        parentSessionId: session.id,
-        index: titlePlan.index,
-        path: file,
-        planId: compactOutcome?.planId ?? null,
-        title: titlePlan.title,
-        baseTitle: titlePlan.baseTitle,
-        scheme: titlePlan.scheme,
-        titleSeq: historyRename.titleSeq,
-        // historyTitle 只在改名真的生效时写；失败/服务不可用时不能记一个不存在的标题。
-        ...(titlePlan.scheme === 'history-n' && (historyRename.renamed || historyRename.reason === 'already')
-          ? { historyTitle: historyRename.title }
-          : {}),
-      });
+      const relayWrote = writeRelayRecord(
+        deps.engine,
+        session,
+        parentRelayRecordOf({
+          parentId: session.id,
+          childId: created.childId,
+          ordinal: titlePlan.index,
+          at: relayAt,
+          atIso: localIso(new Date(relayAt)),
+          path: file,
+          planId: compactOutcome?.planId,
+          title: titlePlan.title,
+          baseTitle: titlePlan.baseTitle,
+          // 0.6：收藏文件按链根分文件——初代传自己，后代沿用入站记录的 rootId。
+          rootId: relayInboundRecordOf(session)?.rootId ?? session.id,
+          scheme: titlePlan.scheme,
+          titleSeq: historyRename.titleSeq,
+          historyTitle:
+            titlePlan.scheme === 'history-n' && (historyRename.renamed || historyRename.reason === 'already')
+              ? historyRename.title
+              : undefined,
+        }),
+      );
       if (!relayWrote) deps.log?.warn?.('compact-relay: 接力链记录写入失败，下次交接将回退到标题解析');
       // renameHistoryOf 的 flush 发生在父记录之前；这里再 flush 一次，保证旧会话的
       // 「历史 N」标题与这条父记录一起落盘（失败只 warn，不影响交接结果）。