dsh-session-conductor 1.3.19 → 1.4.5

package/lib/features/member-model/switch.js

@@ -14,7 +14,7 @@ import { cfg } from "../../core/config.js";
 import { hasOpenTurn } from "../../sessions/turn.js";
 import { foldLastModelSelection } from "../../sessions/route.js";
 import { lazyZstd, lazyRepair } from "../../core/lazy.js";
-import { setMemberModelOverride } from "./override.js";
+import { setMemberModelOverride, deleteMemberModelOverride } from "./override.js";
 
 /**
  * 等待一个成员进入空闲（当前回合结束/暂停）。
@@ -171,29 +171,38 @@ async function repairDescriptorIfStale(ctx, filePath, sessionId, provider, model
   const descriptor = found.descriptor;
   if (!descriptor || typeof descriptor !== "object") return { skipped: "不是子代理会话（无 descriptor）" };
 
-  // 取当前可用 provider 列表；拿不到就不猜、不动日志
-  const sc = ctx.get("sessionController");
-  if (typeof sc?.modelCatalog !== "function") return { skipped: "modelCatalog 不可用，跳过 descriptor 校验" };
-  let groups;
-  try {
-    const catalog = await sc.modelCatalog();
-    groups = catalog?.groups ?? [];
-  } catch (error) {
-    return { skipped: `modelCatalog 调用失败，跳过：${String(error?.message ?? error)}` };
+  // 何时改写 descriptor：目标模型 ≠ descriptor 当前值就改 ——
+  // 子代理冷恢复（reason=resume）的请求模型直接取 descriptor，不经过官方
+  // model/selection 投影链路，selection 事件对它无效（只写 selection 时 resume 仍用
+  // descriptor 旧模型）。要「不带 override 也能切子代理」，必须把 descriptor 同步到目标，
+  // 两条通道（挂载期 selection / 冷恢复 descriptor）才都生效。
+  const driftsFromTarget = descriptor.agentProvider === undefined
+    || descriptor.agentModel === undefined
+    || descriptor.agentProvider !== provider
+    || descriptor.agentModel !== model;
+  if (!driftsFromTarget) return { skipped: "descriptor 已指向目标模型" };
+
+  // modelCatalog 只用于**校验目标合法**（防止把 descriptor 写成一个不存在的路由，
+  // 那会让成员永久唤不醒）。它不可用时不再直接放弃同步 —— 早先版本把它当硬前置，
+  // 结果「目录服务不可用」= 同步静默失效，成员冷恢复又回落旧模型。
+  const sc = ctx.get?.("sessionController");
+  if (typeof sc?.modelCatalog === "function") {
+    try {
+      const catalog = await sc.modelCatalog();
+      const groups = catalog?.groups ?? [];
+      if (groups.length > 0) {
+        const group = groups.find((g) => g.id === provider);
+        if (!group) return { skipped: `目标 provider ${provider} 不在模型目录，跳过（避免写入失效路由）` };
+        const known = (group.models ?? []).some((m) => m.id === model);
+        if (!known) return { skipped: `目标模型 ${model} 不在 ${provider} 目录，跳过（避免写入失效路由）` };
+      }
+    } catch (error) {
+      // 目录调用失败不阻断同步：目标值由调用方给出，宿主侧还有组合校验兜底
+      ctx.logger?.info?.(`dsh-session-conductor: descriptor 同步：模型目录调用失败，仍按目标写入：${String(error?.message ?? error)}`);
+    }
   }
-  if (groups.length === 0) return { skipped: "模型目录为空，跳过 descriptor 校验" };
-
-  const providerIds = new Set(groups.map((g) => g.id));
-  const staleProvider = descriptor.agentProvider !== undefined && !providerIds.has(descriptor.agentProvider);
-  const staleModel = (() => {
-    if (descriptor.agentProvider === undefined || descriptor.agentModel === undefined) return false;
-    const group = groups.find((g) => g.id === descriptor.agentProvider);
-    if (!group) return false;
-    return !(group.models ?? []).some((m) => m.id === descriptor.agentModel);
-  })();
-  if (!staleProvider && !staleModel) return { skipped: "descriptor 路由有效" };
-
-  // 整份重写（descriptor 在文件头部，追加帧改不了它）；这条路径只在路由失效时走一次，代价可接受
+
+  // 整份重写（descriptor 在文件头部，追加帧改不了它）；这条路径只在路由失效或目标漂移时走一次，代价可接受
   const { encodeSessionText } = await lazyRepair();
   const { decodeAllFrames } = await import("../../zstd-frames.js");
   const fullText = buf.length > 0 ? await decodeAllFrames(buf) : "";
@@ -226,7 +235,7 @@ async function repairDescriptorIfStale(ctx, filePath, sessionId, provider, model
   const backup = backupSwitchLog(filePath, sessionId);
   if (backup.error) return { error: backup.error };
   replaceFileSync(filePath, await encodeSessionText(lines.join("\n") + "\n"), { tmpSuffix: ".descfixtmp" });
-  log(ctx, `切换写日志：descriptor 路由失效（${staleProvider ? "provider 已不存在" : "model 不在目录"}），已改为 ${provider}/${model}`);
+  log(ctx, `切换写日志：descriptor 已同步为 ${provider}/${model}（原 ${descriptor.agentProvider ?? "?"}/${descriptor.agentModel ?? "?"}，防冷恢复回落）`);
   return { repaired: true };
 }
 
@@ -251,6 +260,17 @@ export async function appendSelectionEventToLog(ctx, sessionId, provider, model)
     count: events.length,
   });
 
+  // descriptor 同步放在「selection 是否已相同」的判定**之前**：
+  // 两者是独立通道（selection 管挂载期、descriptor 管冷恢复），日志里 selection 已是目标值
+  // 并不代表 descriptor 也对齐了。早先放在追加帧之后，遇到「重复切换同一模型」就提前返回，
+  // 于是 descriptor 永远修不到，成员下次 resume 仍回落旧模型。
+  const descFixEarly = await repairDescriptorIfStale(ctx, filePath, sessionId, provider, model);
+  if (descFixEarly.repaired) {
+    log(ctx, `切换写日志：descriptor 已同步到 ${provider}/${model}（防冷恢复回落）`);
+  } else if (descFixEarly.error) {
+    log(ctx, `切换写日志：descriptor 校验失败（不影响本次切换）：${descFixEarly.error}`);
+  }
+
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const { events } = logInfo;
     const last = foldLastModelSelection(events);
@@ -279,9 +299,8 @@ export async function appendSelectionEventToLog(ctx, sessionId, provider, model)
     const written = await appendEventFrame(filePath, event);
     log(ctx, `切换写日志：追加帧 ${Date.now() - writeStartedAt}ms（seq ${event.seq}）`);
     if (!written.ok) return { error: `写入会话日志失败：${written.error}` };
-    // descriptor 路由失效会让成员永久唤不醒（宿主报 subagent/not-resumable），这里顺带修
-    const descFix = await repairDescriptorIfStale(ctx, filePath, sessionId, provider, model);
-    if (descFix.error) log(ctx, `切换写日志：descriptor 校验失败（不影响本次切换）：${descFix.error}`);
+    // descriptor 同步已在进入循环前做过一次（那时 selection 可能是「已是该模型」而提前返回），
+    // 这里不再重复整份重写 —— 只有追加帧改变了文件尾部，descriptor 在头部、不受影响。
 
     // 附带排查提示：本机实测「成员唤不醒」的真凶是部署侧的「自动审查」开关被关掉，
     // 与 descriptor / 帧校验和 / 写锁全都无关（详见 docs/VERSIONS.md 1.3.15）。
@@ -334,12 +353,30 @@ export async function appendSelectionEventToLog(ctx, sessionId, provider, model)
  * ① 持久化切换意图：不依赖 live agent —— 成员 inactive/未挂载时也能切，下次运行生效。
  * @returns {Promise<{note: string}>} note 直接拼进回执
  */
-async function persistSwitchIntent(ctx, sessionId, provider, model) {
+async function persistSwitchIntent(ctx, sessionId, provider, model, options = {}) {
+  // override 是**显式参数**：带 `override` → 写入/更新（旧行为，每轮强制改写）；
+  // 不带 → **删除该成员的存量 override**，让官方 model/selection 链路接管。
+  // 为什么必须删而不是「不写」：override 一旦存在，agent/request 会每轮按它改写请求，
+  // 优先级压过新写的 model/selection，结果就是「selection 写入成功但下一条请求仍用旧模型」。
+  // 只删该成员这一条，不做批量清理。
+  if (options?.override === true) {
+    try {
+      await setMemberModelOverride(ctx, sessionId, provider, model);
+      return { note: "，已写 override（每轮强制改写，旧行为；UI 切换依赖同步机制）" };
+    } catch (error) {
+      return { note: `，override 持久化失败：${String(error?.message ?? error)}` };
+    }
+  }
   try {
-    await setMemberModelOverride(ctx, sessionId, provider, model);
-    return { note: "，已记录切换意图" };
+    const { removed, error } = await deleteMemberModelOverride(ctx, sessionId);
+    if (error) return { note: `，清除 override 失败（旧 override 仍会压制切换）：${error}` };
+    return {
+      note: removed
+        ? "，已清除该成员的 override（改走官方 model/selection 链路）"
+        : "，未写 override（走官方 model/selection 链路）",
+    };
   } catch (error) {
-    return { note: `，意图持久化失败：${String(error?.message ?? error)}` };
+    return { note: `，清除 override 失败：${String(error?.message ?? error)}` };
   }
 }
 
@@ -382,10 +419,40 @@ async function tryOfficialSelectModel(ctx, sessionId, provider, model, overrideN
   }
 }
 
-export async function switchAgentModel(ctx, sessionId, provider, model, agent = null) {
+/**
+ * 把切换结果同步到 live agent 的 `options`（宿主官方「查看子智能体」视图读的就是它）。
+ *
+ * 【为什么需要】宿主 experimental/agent-team 的 `memberView()` 里，成员模型取的是
+ * `live.options.model` —— 即 agent **创建时**的 AgentOptions，与我们写的 `model/selection`
+ * 事件无关。不同步的话会出现「界面一直显示创建时的老模型，而实际请求早已换了模型」，
+ * 两边长期对不上，排查时极易误判。
+ *
+ * 【为什么能改】宿主 ReactLoopAgent 构造里是 `this.options = options` 直接引用、**没有 freeze**
+ * （该文件只冻结 boundaryMessages 与请求标记）。这里仍做 `isFrozen` 兜底：
+ * 万一将来宿主冻结了，跳过同步即可，绝不影响切换本身。
+ *
+ * @returns {boolean} 是否真的写进去了
+ */
+export function syncLiveAgentOptions(ctx, live, provider, model) {
+  if (!live || !live.options) return false;
+  try {
+    if (Object.isFrozen(live.options)) {
+      log(ctx, "成员模型切换：live agent 的 options 已被冻结，跳过视图同步（不影响实际请求）");
+      return false;
+    }
+    live.options.provider = provider;
+    live.options.model = model;
+    return true;
+  } catch (error) {
+    log(ctx, `成员模型切换：同步 live options 失败（不影响实际请求）: ${String(error?.message ?? error)}`);
+    return false;
+  }
+}
+
+export async function switchAgentModel(ctx, sessionId, provider, model, agent = null, options = {}) {
   const timer = createStageTimer();
   try {
-    return await applyModelSwitch(ctx, sessionId, provider, model, agent, timer);
+    return await applyModelSwitch(ctx, sessionId, provider, model, agent, timer, options);
   } finally {
     // 无论成功失败都留一行分阶段耗时：排查「切模型卡很久」时直接看慢在哪一段
     log(ctx, `模型切换耗时：${timer.summary()}（标记合计 ${timer.total()}ms）`);
@@ -393,20 +460,27 @@ export async function switchAgentModel(ctx, sessionId, provider, model, agent =
 }
 
 /** 切换主流程（逐段打点，计时器只观测、不改变行为）。 */
-async function applyModelSwitch(ctx, sessionId, provider, model, agent, timer) {
+async function applyModelSwitch(ctx, sessionId, provider, model, agent, timer, options = {}) {
   if (!sessionId) return { error: "缺少 sessionId（无法定位目标会话）" };
-  // ① 持久化切换意图（不依赖 live agent——成员 inactive/未挂载时也能切，下次运行生效）
-  const { note: overrideNote } = await persistSwitchIntent(ctx, sessionId, provider, model);
+  // ① 持久化切换意图（不依赖 live agent——成员 inactive/未挂载时也能切，下次运行生效）。
+  //    只有显式传 override:true 才写 override（旧行为）；默认走官方 model/selection 链路。
+  const { note: overrideNote } = await persistSwitchIntent(ctx, sessionId, provider, model, options);
   timer.mark("写意图");
   const live = agent ?? ctx.get("agents")?.get?.(sessionId) ?? null;
   timer.mark("定位成员");
-  // ② 成员当前未挂载（inactive）：直接把事件写进会话日志——官方 selectionFor 读投影即生效。
-  //    （Team 成员唤醒走 sendMessage → followup，不经过 resumeSetupFor，只记意图不会被应用。）
-  if (typeof live?.ctx?.on !== "function" || !live?.session) {
+  // ② 成员真的没有被实例化（agents 里取不到、或没有 session）：只能把事件写进会话日志，
+  //    官方 selectionFor 读投影即生效。
+  //
+  // 【判定为什么只看 session】旧条件还要求 `typeof live.ctx.on === "function"`，但 agent 空闲后
+  // `ctx.scope` 已 unwind，`live.ctx.on` 不再可用 —— 于是「空闲但仍在内存」的成员被误判成未挂载，
+  // 走这条分支就永远拿不到 live.options 去同步（官方 list_agents / 查看子智能体显示的模型会一直
+  // 停在创建时的值）。实测：官方 list_agents 对空闲成员仍能返回 model 字段，说明 agents.get() 有对象，
+  // 那就是能同步的。写事件与同步 options 都只需要 session，不需要活跃的 ctx。
+  if (!live?.session) {
     const written = await appendSelectionEventToLog(ctx, sessionId, provider, model);
     timer.mark("写会话日志");
     if (written.error) {
-      return { error: `成员未挂载，且写入会话日志失败：${written.error}（切换意图已记录，可稍后重试）` };
+      return { error: `成员未挂载，且写入会话日志失败：${written.error}${overrideNote}，可稍后重试` };
     }
     return { via: `已写入会话日志的 model/selection 事件（成员未挂载）${written.note ? "，" + written.note : ""}${overrideNote}，该成员下次运行时生效` };
   }
@@ -430,7 +504,25 @@ async function applyModelSwitch(ctx, sessionId, provider, model, agent, timer) {
   } catch (error) {
     eventNote = `，事件写入失败：${String(error?.message ?? error)}`;
   }
-  let via = `model/selection 事件（官方投影接管）${eventNote}${overrideNote}，下一回合生效`;
+  // ④-补：把结果同步进 live agent 的 options —— 官方「查看子智能体」视图显示的是它
+  //      （memberView 读 live.options.model），不跟着改就会一直显示创建时的老模型。
+  const synced = syncLiveAgentOptions(ctx, live, provider, model);
+  timer.mark("同步视图");
+  // ④-补2：descriptor 同步 —— 挂载中切换只写 selection，但成员空闲卸载后冷恢复（resume）
+  //       的请求模型直接取 descriptor，不改它就会「下次唤醒回落旧模型」。与未挂载路径
+  //       （appendSelectionEventToLog 里的修复）保持同一语义：目标 ≠ descriptor 就改写。
+  try {
+    const { findSessionLogById, sessionsRootOf } = await import("../../sessions/events.js");
+    const logPath = findSessionLogById(sessionId, sessionsRootOf());
+    if (logPath) {
+      const descFix = await repairDescriptorIfStale(ctx, logPath, sessionId, provider, model);
+      if (descFix.repaired) log(ctx, `成员模型切换：descriptor 已同步到 ${provider}/${model}（防冷恢复回落）`);
+    }
+  } catch (error) {
+    log(ctx, `成员模型切换：descriptor 同步失败（不影响本次切换）: ${String(error?.message ?? error)}`);
+  }
+  let via = `model/selection 事件（官方投影接管）${eventNote}${overrideNote}，下一回合生效`
+    + (synced ? "；已同步成员视图的模型显示" : "");
   // ⑤ 官方接口优先（若该部署暴露）：
   //    · 新版：ctx.apiProxy.sessions.selectModel（会话级模型选择，持久化到会话）
   //    · 旧版：ctx.get("sessionController").selectModel（Typert @Remote，服务端直调可能不可用）
@@ -549,8 +641,10 @@ export async function readLastRequestModel(sessionId, root = null) {
   const { StringDecoder } = await import("node:string_decoder");
   const buf = await readFile(file); // 日志最大可达数十 MB，异步读避免阻塞事件循环
   const { scanZstdFrames } = await import("../../zstd-frames.js");
-  // 只流式解码最后若干帧：请求头/选择意图判定只关心最近一次，够用且省内存
-  const TAIL_FRAMES = 8;
+  // 只流式解码尾部若干帧：判定只关心最近一次，够用且省内存。
+  // 【为什么不是 8】一个回合常有上百个事件（step/tool/assistant 各占一帧），
+  // 请求头往往落在倒数几十帧之外；取 8 帧会把「跑过很多轮」的会话误报成「从未运行过」。
+  const TAIL_FRAMES = 400;
   let tailFrames;
   try {
     const { frames } = scanZstdFrames(buf);
@@ -565,10 +659,8 @@ export async function readLastRequestModel(sessionId, root = null) {
   let lastRequest = null;
   let lastSelection = null;
   const PENDING_LIMIT = 8 * 1024 * 1024; // 单行缓冲上限：超过即视为异常，避免无上限增长
-  const consume = (line) => {
-    if (!line) return;
-    let event;
-    try { event = JSON.parse(line); } catch { return; }
+  // 事件级处理（行级与全量兜底共用）：只记「最后一次」请求头与选择意图
+  const consumeEvent = (event) => {
     const hit = modelEventOf(event);
     if (hit === null) return;
     if (hit.kind === "request") {
@@ -578,6 +670,12 @@ export async function readLastRequestModel(sessionId, root = null) {
       lastSelection = hit.value;
     }
   };
+  const consume = (line) => {
+    if (!line) return;
+    let event;
+    try { event = JSON.parse(line); } catch { return; }
+    consumeEvent(event);
+  };
   const onChunk = (chunk) => {
     pending += decoder.write(chunk);
     if (pending.length > PENDING_LIMIT) {
@@ -606,5 +704,11 @@ export async function readLastRequestModel(sessionId, root = null) {
   }
   pending += decoder.end();
   consume(pending);
+  // 尾部窗口内没有任何模型事件：退回全量流式扫一遍（复用公共底座，常量内存），
+  // 避免把「跑过很多轮但最近几帧都是工具/正文」的会话误报成「从未运行过」。
+  if (lastRequest === null && lastSelection === null) {
+    const { streamSessionEvents } = await import("../../sessions/log-stream.js");
+    await streamSessionEvents(buf, consumeEvent);
+  }
   return { lastRequest, lastSelection, scanned };
 }

package/lib/features/member-model/tools.js

@@ -98,7 +98,8 @@ async function describeSwitchSnapshot(ctx, sessionId, provider, model) {
       parameters: {
         target: { type: "string", description: "目标成员：成员名、sessionId 或标题关键字。留空 = 全部成员（排除 Lead）" },
         provider: { type: "string", description: "provider 分组名（list_models 的顶层分组）。留空 = 跟随主代理的 provider" },
-        model: { type: "string", description: "该 provider 下的模型 id（含前缀）。留空 = 跟随主代理的 model" }
+        model: { type: "string", description: "该 provider 下的模型 id（含前缀）。留空 = 跟随主代理的 model" },
+        override: { type: "boolean", description: "可选。true = 额外写持久 override（每轮强制改写请求，旧行为；用于官方 selection 链路不生效的场景）。默认 false = 只写 model/selection 事件，走官方链路（UI 切换不被压制）" }
       },
       output: {
         schema: { type: "string" },
@@ -124,10 +125,11 @@ async function describeSwitchSnapshot(ctx, sessionId, provider, model) {
         const pair = await validateModelPair(ctx, provider, model);
         if (pair.error) return `切换失败：${pair.error}`;
         // target 留空 = 作用于全部成员；与聊天指令 /model-switch 走同一套目标解析
+        const wantOverride = args?.override === true;
         const resolved = resolveTargets(ctx, args?.target, { caller });
         if (resolved.error) return `切换失败：${resolved.error}`;
         if (resolved.all) {
-          const report = await applyModelToMany(ctx, resolved.targets, { provider, model });
+          const report = await applyModelToMany(ctx, resolved.targets, { provider, model, override: wantOverride });
           const extra = [];
           if (followedLead) {
             extra.push(`模型来源：跟随主代理 ${followedLead.sessionId}（${followedLead.modelSource}）`);
@@ -137,7 +139,7 @@ async function describeSwitchSnapshot(ctx, sessionId, provider, model) {
           return renderBatchReport(`批量切换模型 → ${provider}/${model}`, report, extra);
         }
         const found = resolved.targets[0];
-        const switchResult = await switchAgentModel(ctx, found.sessionId, provider, model, found.agent);
+        const switchResult = await switchAgentModel(ctx, found.sessionId, provider, model, found.agent, { override: wantOverride });
         if (switchResult.error) return `切换失败：${switchResult.error}`;
         const memberLabel = found.member?.name ? `${found.member.name}(${found.sessionId})` : found.sessionId;
         // 查证（注册 job，不阻塞）：登记待查证项 → 该成员下次发起请求时由 agent/request 事件判定

package/lib/features/memory-recall/index.js

@@ -18,6 +18,8 @@
 //
 // 【失败即静默】日志缺失/损坏、用量读不到、首回合无上次用量 —— 一律返回 null，绝不阻断回合。
 import { readRecentUserTurns } from "../../sessions/events.js";
+// 会话目标解析的公共底座（id / 前缀 / 标题 / 成员名；与成员轨迹共用）
+import { resolveTargetSession } from "../../sessions/resolve.js";
 import { log } from "../../shared/log.js";
 import { cfg } from "../../core/config.js";
 import { writeJsonAtomicSync, readJsonSafeSync } from "../../shared/json-store.js";
@@ -329,40 +331,12 @@ export function registerMemoryRecallTool(ctx, defineTool, tools, deps = {}) {
  * @returns {Promise<{id:string,title?:string|null}|{candidates:Array<{id:string,title?:string|null}>}|null>}
  */
 export async function resolveSessionTarget(ctx, want, selfId) {
-  const { sessionsRootOf } = await import("../../sessions/events.js");
-  // 异步遍历：会话目录可能上千个，同步 stat/readdir 会把事件循环钉住
-  const { readdir, stat } = await import("node:fs/promises");
-  const { join } = await import("node:path");
-  const root = sessionsRootOf();
-  const ids = [];
-  const isDirectory = async (p) => {
-    try { return (await stat(p)).isDirectory(); } catch { return false; }
-  };
-  if (root && await isDirectory(root)) {
-    for (const proj of await readdir(root)) {
-      const pp = join(root, proj);
-      if (!(await isDirectory(pp))) continue;
-      for (const dir of await readdir(pp)) {
-        if (!(await isDirectory(join(pp, dir)))) continue;
-        if (dir.startsWith("session-") || dir === selfId) ids.push(dir);
-      }
-    }
-  }
-  if (ids.includes(want)) return { id: want };
-  const byPrefix = ids.filter((id) => id.startsWith(want));
-  if (byPrefix.length === 1) return { id: byPrefix[0] };
-  if (byPrefix.length > 1) return { candidates: byPrefix.map((id) => ({ id })) };
-  // 标题子串：只在落盘索引里找（避免为了解析一个参数去逐份读日志）
-  try {
-    const { loadListDiskCache } = await import("../../sessions/list-cache.js");
-    let entries = {};
-    try { entries = loadListDiskCache(ctx)?.entries ?? {}; } catch { entries = {}; }
-    const lower = want.toLowerCase();
-    const byTitle = Object.entries(entries)
-      .filter(([, e]) => String(e?.title ?? "").toLowerCase().includes(lower))
-      .map(([id, e]) => ({ id, title: e?.title ?? null }));
-    if (byTitle.length === 1) return byTitle[0];
-    if (byTitle.length > 1) return { candidates: byTitle };
-  } catch { /* 索引不可用：退化为只按 id 匹配 */ }
-  return null;
+  // 实现已抽到公共底座 sessions/resolve.js（成员轨迹与记忆取回共用同一套解析）。
+  //
+  // 旧实现在这里用 `dir.startsWith("session-")` 判断会话目录，而子代理/成员会话的目录名是
+  // **裸 UUID**（不带 session- 前缀），导致那些会话永远进不了候选集 —— 完整 id 与前缀都解析不出来。
+  // 公共底座改为「目录里有会话日志文件」作为判据，与目录命名规则解耦。
+  //
+  // 顺带获得成员名支持：`recall_memory({ session: "writer" })` 这类写法现在也能解析。
+  return await resolveTargetSession(ctx, want, selfId);
 }

package/lib/features/session-ops-routes.js

@@ -7,6 +7,7 @@
  * 其余（会话操作实现、标题工具、日志）在本模块内直接 import，不再依赖 apply 的作用域。
  */
 import { log } from '../shared/log.js';
+import { restoreSessionsFromExport } from '../sessions/export-restore.js';
 import { MSG_NEED_SESSION_ID } from '../shared/constants.js';
 import { titleString, foldTitle, workspaceNameOf, archiveTitleWithWs, stripArchiveWsPrefix } from './rename/title.js';
 import { unarchiveSession, deleteSession, undoLastMessage, deleteBatchSessions, deleteByRule, emptyTrash, purgeExpiredTrash } from './session-ops.js';
@@ -107,6 +108,26 @@ export function registerSessionOpsRoutes({ webServer, ctx, send, readJson, inval
     }
   };
 
+  // ---------- POST /api/session-conductor/restore-from-export ----------
+  // 把「会话导出包」（解压后的明文 jsonl 目录）覆盖回运行时格式。
+  // 为什么不能直接拷：导出包是明文 session.v4.jsonl，而运行时读的是带校验和的多帧
+  // session.v4.jsonl.zstd；直接拷会被宿主判「总和检查码不匹配」或 corrupt。
+  // 默认 dryRun（只报告会覆盖哪些、事件多少），body.dryRun=false 才写盘。
+  route("/api/session-conductor/restore-from-export", "restore-from-export-failed", async (body, res) => {
+    const exportDir = typeof body?.exportDir === "string" ? body.exportDir : "";
+    if (exportDir === "") {
+      return send(res, 400, { ok: false, error: { code: "bad-request", message: "需要 exportDir（解压后的导出包目录绝对路径）" } });
+    }
+    const result = await restoreSessionsFromExport({
+      exportDir,
+      sessionIds: Array.isArray(body?.sessionIds) ? body.sessionIds : undefined,
+      dryRun: body?.dryRun !== false,
+      eventsPerFrame: typeof body?.eventsPerFrame === "number" ? body.eventsPerFrame : undefined,
+      ctx,
+    });
+    send(res, result.ok ? 200 : 400, result);
+  }, { requireSessionId: false });
+
   // ---------- POST /api/session-conductor/archive ----------
   // 归档时给标题加「[工作区名] 」前缀（数据层带前缀，面板显示剥离，已归档视图按前缀分组）。
   route("/api/session-conductor/archive", "archive-failed", async (body, res) => {