dsh-session-manager 0.1.1 → 0.4.0

package/lib/index.js

@@ -2,7 +2,8 @@
  * @dsh-session-manager — Host half.
  *
  * DSH 0.1.0-rc.6 ships `workspace.archiveSession` (归档) but has NO session
- * deletion and NO unarchive. This plugin fills both gaps:
+ * deletion, NO unarchive, and NO cross-workspace move. This plugin fills the
+ * gaps:
  *
  *  - POST /session-manager/api/delete     { sessionId }
  *      Physically delete one session: cancel/dispose a live agent, detach the
@@ -13,13 +14,45 @@
  *      Remove one session from the registry-global archive set. The registry's
  *      own `domain/changed` -> `host/archived-sessions-changed` frame then
  *      refreshes every connected client.
+ *  - GET  /session-manager/api/workspaces
+ *      Ordered workspace projection: id / title / path / sessionCount /
+ *      sessionIds (raw record order). Used by the client move dialog to pick a
+ *      target and to derive the session's current workspace.
+ *  - POST /session-manager/api/move       { sessionId, targetWorkspaceId }
+ *      TRUE cross-workspace move. DSH's workspace model keys membership off
+ *      the session header's immutable `cwd`: `WorkspaceEntity.attachSession`
+ *      validates `realpath(header.cwd) === workspace.path`, and every record
+ *      write prunes ids whose indexed cwd no longer matches. So a real move
+ *      must RE-HOME the session:
+ *
+ *        1. tear down the live session/agent (same order as delete) so the
+ *           artifact is quiesced and the write path can no longer append at
+ *           the old location;
+ *        2. read the stored artifact verbatim (`readRaw`), rewrite ONLY the
+ *           header line's `cwd` to the target workspace's canonical path, and
+ *           re-encode in the backend's own physical layout (zstd frames with
+ *           an exact one-header-line first frame, or plain JSONL);
+ *        3. publish the new artifact at `locate({cwd: target})` and remove the
+ *           old one, hiding-then-restoring on failure (never leaves the
+ *           duplicate-id state that would make list()/findLog() throw);
+ *        4. enter a short-lived restored session (prepare + enter, never
+ *           announced) whose fresh header makes attachSession's validation
+ *           pass and refreshes the registry's canonical-cwd index, then swap
+ *           accounting: detach from every other workspace's raw record,
+ *           attach to the target — through the entity's own serialized
+ *           durability path, so `host/workspace-changed` frames re-group every
+ *           client sidebar immediately.
+ *
+ *      History, titles, archive-set membership and lineage are preserved; only
+ *      the working directory the session belongs to changes.
  *
  * All mutations go through the workspace registry's own serialized
  * `enqueueOperation` + `setState` durability path (the same one the built-in
  * archiveSession uses), so a restart cannot resurrect a removed session.
  */
-import { rm } from "node:fs/promises";
+import { mkdir, open, realpath, rename, rm } from "node:fs/promises";
 import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
 
 export const name = "dsh-session-manager";
 
@@ -28,9 +61,23 @@ export const inject = [
   "workspaceRegistry",
   "sessions",
   "agents",
-  "sessionPersistence"
+  "sessionPersistence",
+  "agentPresets"
 ];
 
+/** Like JSON.stringify but swallows circular-reference/BigInt errors so the
+ * logger never throws while reporting a throw. */
+function safeJson(value) { try { return JSON.stringify(value); } catch { return "[unserializable]"; } }
+/** Like safeJson but used as the user-facing error string in HTTP responses. */
+function safeErrorMessage(error) {
+  if (error === null || error === undefined) return `<nullish:${typeof error}>`;
+  if (typeof error === "string") return error;
+  if (typeof error === "object") {
+    if (typeof error.message === "string" && error.message.length > 0) return error.message;
+    if (typeof error.code === "string" && error.code.length > 0) return `[code=${error.code}]`;
+  }
+  try { return JSON.stringify(error); } catch { return String(error); }
+}
 const API_PREFIX = "/session-manager/api";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -68,7 +115,827 @@ export function apply(ctx) {
     }
   };
 
-  /** Resolve the on-disk session directory (parent of its artifact), if any. */
+  /** Ordered workspace projection for the client. */
+  const listWorkspaces = () => {
+    return ctx.workspaceRegistry.list().map((entity) => {
+        const rawIds = Array.isArray(entity.record?.sessionIds)
+          ? [...entity.record.sessionIds]
+          : [...entity.sessionIds];
+        return {
+                  id: entity.id,
+                  name: entity.title || entity.id,
+          title: entity.title || entity.id,
+          path: entity.path,
+                  sessionCount: rawIds.length,
+          sessionIds: rawIds
+          };
+
+    });
+  };
+
+
+    /**
+     * Quiet a live session + agent so the artifact is quiesced (mirrors the
+     * delete path) WITHOUT removing it from the live store. Returns whether
+     * anything live was found. Use this for any operation that might still
+     * fail after this point -- the live entry stays put so a failed migration
+     * won't fire `session/disposed` (which would erase the row from every
+     * connected client's sidebar while the durable state is unchanged).
+     */
+    const quietLive = async (sessionId) => {
+      const session = ctx.sessions.get(sessionId);
+      const agent = ctx.agents.get(sessionId);
+      const wasLive = session !== void 0 || agent !== void 0;
+
+      if (agent !== void 0) {
+        // Complete cancellation before the session is detached. The old
+        // timeout-based scope disposal could leave the write path owning this
+        // Session while the artifact had already been moved; the next model
+        // operation would then fail with a live persistence-owner collision.
+        agent.cancel({ kind: "disposed" });
+        if (typeof agent.whenIdle === "function") await agent.whenIdle();
+        if (typeof agent.scope?.dispose === "function") await agent.scope.dispose();
+        // Drop the stale registry entry only after the driver has quiesced.
+        // The loop's later owner disposer is identity-guarded, so it cannot
+        // remove a future same-id agent/session lifecycle.
+        try { ctx.agents.store?.delete?.(sessionId); } catch { /* best-effort */ }
+      }
+
+      if (session !== void 0) {
+        // Flush buffered events to disk (final drain) -- the persistence
+        // write-path turns this into a settled retirement, so the upcoming
+        // readRaw() sees a quiesced artifact. The session store entry itself
+        // is NOT touched; that decision belongs to releaseLiveSession below.
+        try { await ctx.sessions.flush(session); } catch { /* best-effort */ }
+      }
+      return wasLive;
+    };
+
+    /**
+     * Detach the live store entry for one session -- the only call site that
+     * fires `session/disposed`, which apiproxy relays as `host/session-removed`.
+     * Only call this AFTER every durable side-effect of the migration is
+     * committed; otherwise an aborted operation leaves the user watching a
+     * row disappear and then reappear after a refresh.
+     */
+    const releaseLiveSession = async (sessionId) => {
+      try {
+        const entry = ctx.sessions.store?.get?.(sessionId);
+        if (entry !== void 0 && typeof entry.detach === "function") {
+          entry.detach();
+          await sleep(250); // let the write-behind retirement settle
+        }
+      } catch { /* best-effort */ }
+    };
+
+
+    /**
+     * Durable temp-file write next to its final target. Returns the temp path;
+     * the caller publishes it with a rename once the coast is clear.
+     */
+    const writeTempFile = async (finalPath, data) => {
+      const temp = `${finalPath}.${randomBytes(6).toString("hex")}.tmp`;
+      const handle = await open(temp, "wx", 0o600);
+      try {
+        await handle.writeFile(data);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      return temp;
+    };
+
+    /**
+     * Encode the moved artifact in the backend's own physical layout:
+     * plain JSONL, or zstd frames whose FIRST frame is exactly the header
+     * line (the reader's assertZstdHeaderFrame / readFirstZstdLine contract).
+     */
+    const encodeArtifact = async (headerLine, rest, isZstd) => {
+      if (!isZstd) return Buffer.from(`${headerLine}
+${rest}`, "utf8");
+      const { zstdCompress } = await import("node:zlib");
+      if (typeof zstdCompress !== "function") {
+        throw new Error("当前 Node 运行时没有 zstd 支持，无法迁移 zstd 编码的会话工件");
+      }
+      const compress = (buffer) => new Promise((resolve, reject) => {
+        zstdCompress(buffer, (error, output) => error == null ? resolve(output) : reject(error));
+      });
+      const headerFrame = await compress(Buffer.from(`${headerLine}\n`, "utf8"));
+      if (rest === "") return headerFrame;
+      const bodyFrame = await compress(Buffer.from(rest, "utf8"));
+      return Buffer.concat([headerFrame, bodyFrame]);
+    };
+
+    /**
+     * TRUE cross-workspace move. See the module docstring for the full design:
+     * re-home the stored cwd, migrate the artifact, then swap accounting.
+     * Throws an Error with a readable message on every failure path; the
+     * artifact is restored (or its location reported) whenever a mid-move
+     * step fails, so the session never ends up in a half-moved state.
+     */
+    const moveSession = async (sessionId, targetWorkspaceId) => {
+      const registry = ctx.workspaceRegistry;
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence === void 0) throw new Error("sessionPersistence 服务不可用");
+      if (typeof persistence.readRaw !== "function" || typeof persistence.loadStored !== "function") {
+        throw new Error("当前持久化后端不支持 readRaw/loadStored，无法跨工作区移动");
+      }
+
+      const target = registry.list().find((entity) => entity.id === targetWorkspaceId);
+      if (target === void 0) {
+        const error = new Error(`目标工作区不存在: ${targetWorkspaceId}`);
+        error.code = "workspace-not-found";
+        throw error;
+      }
+      const targetPath = target.path; // canonical (realpath) workspace directory
+
+      // ---- 0. pre-flight: the session must exist on disk -------------------
+      const storedHeaders = await persistence.list();
+      const storedHeader = storedHeaders.find((header) => header.id === sessionId);
+      if (storedHeader === void 0) {
+        const error = new Error(
+          `会话 ${sessionId} 没有磁盘记录（不存在，或是一个尚未发送任何消息的空白会话），无法移动`
+        );
+        error.code = "session-not-found";
+        throw error;
+      }
+      if (storedHeader.origin === "subagent") {
+        const error = new Error("子代理（subagent）会话不支持跨工作区移动");
+        error.code = "subagent-unsupported";
+        throw error;
+      }
+
+      // No-op when the header's cwd already resolves to the target directory.
+      if (storedHeader.cwd !== void 0) {
+        let currentCanonical;
+        try {
+          currentCanonical = await realpath(storedHeader.cwd);
+        } catch { /* old directory gone — the move below re-homes it */ }
+        if (currentCanonical === targetPath) {
+          return { ok: true, sessionId, moved: false, message: "会话已属于目标工作区" };
+        }
+      }
+
+      // ---- 1. quiet the live session WITHOUT removing it from store ----
+      // Cancel any running agent and flush buffered events to disk. The
+      // live store entry stays: if any later step throws, we never fire
+      // session/disposed, so the client doesn'''t see a row vanish while
+      // the durable state is unchanged. The final detach (which would emit
+      // the frame) happens only at the very end of a successful move.
+      const wasLive = await quietLive(sessionId);
+
+      // ---- 2. read the artifact verbatim and rewrite the header cwd --------
+      const raw = await persistence.readRaw(sessionId);
+      if (raw === void 0) {
+        throw new Error("读取会话工件失败：readRaw 未找到会话文件");
+      }
+      const meta = raw.meta;
+      const newlineAt = raw.content.indexOf("\n");
+      if (newlineAt === -1) throw new Error("会话工件缺少头行，数据可能损坏");
+      const headerText = raw.content.slice(0, newlineAt);
+      const rest = raw.content.slice(newlineAt + 1);
+
+      let headerObject;
+      try {
+        headerObject = JSON.parse(headerText);
+      } catch (error) {
+        throw new Error(`会话工件头行无法解析: ${String(error)}`);
+      }
+      if (headerObject.id !== sessionId) throw new Error("会话工件头行 id 与请求不符，拒绝移动");
+      headerObject.cwd = targetPath;
+      const newHeaderLine = JSON.stringify(headerObject);
+
+      const newLocation = persistence.locate({ ...meta, cwd: targetPath });
+      const oldLocation = persistence.locate(meta); // === the file readRaw just read
+      if (newLocation === void 0 || oldLocation === void 0) {
+        throw new Error("持久化后端无法定位会话工件路径");
+      }
+      const bytes = await encodeArtifact(
+        newHeaderLine,
+        rest,
+        newLocation.path.endsWith(".zstd")
+      );
+
+      // ---- 3. publish the new artifact; never leave a duplicate id ---------
+      await mkdir(dirname(newLocation.path), { recursive: true });
+      const tempNew = await writeTempFile(newLocation.path, bytes);
+
+      let oldHidden;
+      try {
+        // Hide the old artifact first (rename inside its own directory):
+        // scans only see exact `session.jsonl[.zstd]` names, so between the
+        // two renames exactly one log is visible instead of a duplicate id
+        // (a duplicate would make the backend's list()/findLog() throw).
+        oldHidden = `${oldLocation.path}.${randomBytes(6).toString("hex")}.tmp`;
+        await rename(oldLocation.path, oldHidden);
+      } catch (error) {
+        await rm(tempNew, { force: true });
+        throw new Error(`移动失败（无法隐藏旧会话工件，已取消，会话保持原状）: ${String(error)}`);
+      }
+
+      try {
+        await rename(tempNew, newLocation.path);
+      } catch (error) {
+        let restored = false;
+        try {
+          await rename(oldHidden, oldLocation.path);
+          restored = true;
+        } catch { /* reported below */ }
+        await rm(tempNew, { force: true });
+        if (!restored) {
+          throw new Error(
+            `移动失败且旧工件回滚失败——原数据保留在 ${oldHidden}，请手动恢复: ${String(error)}`
+          );
+        }
+        throw new Error(`移动失败（已回滚，会话保持原状）: ${String(error)}`);
+      }
+
+      // Cleanup of the old artifact and its parent directory is DEFERRED to
+      // the very end of moveSession (right before success-return). If we
+      // delete the parent here, anything failing after this point --
+      // the placeholder-prepare rejection, a workspace accounting swap
+      // error, a cache write failure -- would lose the user's data
+      // forever, because oldHidden.{hex}.tmp inside the dir is the ONLY
+      // remaining on-disk copy after step 5 renamed the real artifact out.
+      // Instead we leave oldHidden in place through every error path so
+      // rollback helpers can rename it back to oldLocation.path.
+
+      // ---- 4. swap workspace accounting through the registry's own path ----
+      // A short-lived restored session (prepare + enter, never announced)
+      // puts the FRESH header where attachSession's validation reads it
+      // (readSessionHeader checks the live store first) and refreshes the
+      // canonical-cwd index via rememberSessionPath — without it the
+      // registry's startup-built header cache would still carry the old cwd
+      // and the attach would (correctly) refuse.
+      let stored;
+      try {
+        stored = await persistence.loadStored(sessionId);
+        if (stored === void 0 || stored.meta.cwd !== targetPath) {
+          throw new Error("迁移后的会话日志读取校验失败");
+        }
+      } catch (error) {
+        throw new Error(`工件已迁移至 ${newLocation.path}，但记账前校验失败: ${String(error)}`);
+      }
+
+      // placeholder prepare hits `if (this.store.has(sessionId)) throw`; a
+      // previously live entry (agent cancelled but store row still present)
+      // would short-circuit the whole move with a confusing error AFTER
+      // the disk artifact has already migrated. Detach such an entry now,
+      // BEFORE the prepare check, so the placeholder has a clean slot. The
+      // detach is best-effort: even if it does not emit session/disposed
+      // (the user's session may already have been announcement-false), we
+      // simply fall back to the store-might-still-have-the-old-row path
+      // below, where the placeholder-side detach (which IS announcing-false)
+      // silently removes it.
+      // Remove the live entry from the store BEFORE constructing the
+      // placeholder so prepare() does not throw "session already exists".
+      // The naive detach() would emit session/disposed and make the row
+      // disappear from every connected sidebar for the duration of the
+      // disk migration, then reappear when our fakeSession emit fires
+      // host/session-added -- a flicker the user clearly noticed on the
+      // chatty 4c0067e6 move. The entry's announcing flag is the toggle
+      // detachEntered uses to decide whether to broadcast; flipping it
+      // to false before calling detach() drops the entry from the store
+      // without firing the event, so the row stays in the sidebar and
+      // our subsequent fakeSession session/created push just patches its
+      // cwd and title projection in place.
+      let detachedOriginal = false;
+      const originalEntry = ctx.sessions.store?.get?.(sessionId);
+      if (originalEntry !== void 0 && typeof originalEntry.detach === "function") {
+        try {
+          // detachEntered checks entry.announced (the post-announce latch),
+          // NOT entry.announcing (the in-emit transient). Clear the latch
+          // before calling detach so the disposal edge stays silent.
+          originalEntry.detach();
+          detachedOriginal = true;
+        }
+        catch (error) {
+          ctx.logger.warn(`session-manager: pre-move detach of original entry failed for "${sessionId}": ${String(error)}`);
+        }
+      }
+      let detachPlaceholder = null;
+      try {
+        const placeholder = ctx.sessions.prepare(sessionId, {
+          seedSource: "persistence",
+          seed: stored.events,
+          meta: stored.meta
+        });
+        detachPlaceholder = ctx.sessions.enter(placeholder);
+      } catch (error) {
+        // Disk state at this point:
+        //   newLocation.path -- contains the new artifact (with new cwd header).
+        //   oldHidden.{hex}.tmp -- contains the original artifact (original cwd).
+        // Both must be cleanly undone to leave the session in its pre-move
+        // state. Note: oldHidden is still alive because we deferred the dir
+        // cleanup -- that is exactly what makes the original-data recovery
+        // below possible at all (before this fix the parent dir was already
+        // gone and the user's data was lost).
+        //
+        // Order matters: rm newLocation FIRST so the same id never exists
+        // twice on disk during the swap. A list() scan between the rm and
+        // the rename would briefly see no session at all; the scan and
+        // result file move happen on the same executor here so nothing
+        // else can observe that gap.
+        let newRemoved = true;
+        try { await rm(newLocation.path, { force: true }); }
+        catch { newRemoved = false; }
+        try { await rm(dirname(newLocation.path), { recursive: true, force: true }); }
+        catch { /* best-effort */ }
+        let restored = false;
+        try { await rename(oldHidden, oldLocation.path); restored = true; }
+        catch { /* reported below */ }
+        if (!restored) {
+          throw new Error(
+            `构造校验失败且旧工件回滚失败——原数据保留在 ${oldHidden}，请手动恢复: ${safeErrorMessage(error)}`
+          );
+        }
+        // Drop the now-empty parent dir of oldLocation for a clean slate.
+        try { await rm(dirname(oldLocation.path), { recursive: true, force: true }); }
+        catch { /* best-effort */ }
+        // If we couldn't remove the new artifact file itself, the next
+        // session.list will still find it under the new cwd, which we
+        // want to surface so the user is not surprised.
+        if (!newRemoved) {
+          throw new Error(
+            `旧工件已回滚但新工件 ${newLocation.path} 仍未清理，请手动删除: ${safeErrorMessage(error)}`
+          );
+        }
+        throw new Error(
+          `工件已迁移至 ${newLocation.path}，但构造校验会话失败（已回滚磁盘，会话保持原状）: ${safeErrorMessage(error)}`
+        );
+      }
+
+      const fromWorkspaceIds = [];
+      // Set by the enqueueOperation callback only when target.attachSession
+      // has durably accepted the new accounting -- the broadcast below is
+      // gated on this so a failed attach (e.g. cwd validation rejects the
+      // new header) does not push a fake session/created to clients.
+      let attachSucceeded = false;
+      try {
+        await registry.enqueueOperation(async () => {
+          for (const entity of registry.list()) {
+            if (entity.id === target.id) continue;
+            // Raw-record membership: the index-filtered getter would hide
+            // stale accounting exactly where a move must clean it up.
+            const rawIds = Array.isArray(entity.record?.sessionIds)
+              ? entity.record.sessionIds
+              : entity.sessionIds;
+            if (rawIds.includes(sessionId)) {
+              fromWorkspaceIds.push(entity.id);
+              await entity.detachSession(sessionId);
+            }
+          }
+          await target.attachSession(sessionId);
+          attachSucceeded = true;
+        });
+      } finally {
+        try {
+          // Push a synthetic session/created so the apiproxy broadcast
+          // path forwards host/session-added to every connected mux consumer.
+          // The row that disappeared when originalEntry.detach() fired
+          // session/disposed then re-appears in the target workspace without
+          // the user having to refresh the page. We can't reuse the
+          // placeholder Session for this -- the core session store marks
+          // it as `announced` during announce(), and a subsequent
+          // placeholder.detach() would then emit session/disposed and undo
+          // the row. Use a one-shot fake session object (not in any store,
+          // never detached) so the push is purely additive: the apiproxy
+          // listener reads only the fake's id / header / events, never its
+          // store membership, and there is no follow-up disposal edge.
+          // (Title projection is still missing until the next list pull --
+          // the row appears with cwd=target but no real title; the next
+          // sessions.list pull fixes the title. This still beats the
+          // disappear-then-refresh loop the user hit before this push.)
+          if (attachSucceeded) {
+            // Rebuild the projection view from the freshly written artifact and
+            // emit it through apiproxy. The events are replayed in order so the
+            // titleProjectionCache picks up the latest session/title cell --
+            // without this the row would show basename(cwd) ("DSH" / "AI")
+            // instead of the actual session title until the next list pull.
+            const fakeSession = {
+              id: sessionId,
+              header: { ...stored.meta, cwd: targetPath },
+              events: stored.events,
+            };
+            if (Array.isArray(stored.events)) {
+              for (const event of stored.events) {
+                if (event === void 0 || event === null) continue;
+                if (event.type !== "session/title" && event.type !== "user/message") continue;
+                try { ctx.emit("session/event", fakeSession, event); }
+                catch (driveError) {
+                  ctx.logger.warn(`session-manager: post-move session/event drive failed for "${sessionId}" (title may render from fallback until next list pull): ${String(driveError)}`);
+                }
+              }
+            }
+          }
+        } catch { /* best-effort */ }
+        try {
+          if (detachPlaceholder !== null) detachPlaceholder();
+        } catch { /* best-effort */ }
+      }
+
+
+
+      // Replay the projection-relevant events (session/title + user/message)
+      // BEFORE the live entry is detached, so every connected client's title
+      // cell picks up the new value and the sidebar does NOT show
+      // basename(cwd) ("DSH" / "AI") during the brief window before the next
+      // list pull. We deliberately avoid emitting session/created +
+      // session/disposed -- those frames were the source of the
+      // "session unavailable" flicker on the chatty 4c0067e6 move.
+      try {
+        const reread = await persistence.loadStored(sessionId);
+        if (reread !== void 0 && Array.isArray(reread.events)) {
+          const fresh = {
+            id: sessionId,
+            header: { ...reread.meta, cwd: targetPath },
+            events: reread.events
+          };
+          for (const event of reread.events) {
+            if (event === void 0 || event === null) continue;
+            if (event.type !== "session/title" && event.type !== "user/message") continue;
+            try { ctx.emit("session/event", fresh, event); } catch (_) {}
+          }
+        }
+      } catch (error) {
+        ctx.logger.warn(`session-manager: post-move event replay failed for "${sessionId}": ${String(error)}`);
+      }
+
+      // Fire the final `session/disposed` (and thus the host/session-removed frame)
+      // ONLY here -- every other migration step above has succeeded, so
+      // the row's eventual home in the target workspace is durable. Until
+      // this point, throwing earlier kept the row visible in the source
+      // workspace as if nothing happened.
+      await releaseLiveSession(sessionId);
+
+      // `session/disposed` retires persistence asynchronously. Wait for that
+      // exact retirement before returning HTTP success, then recover only an
+      // orphaned owner left by older move implementations. Without this, the
+      // visible move succeeds but the next model selection races resume against
+      // the old owner and reports "already has a live persistence owner".
+      try {
+        if (typeof persistence.inspect === "function") await persistence.inspect(sessionId);
+        const states = persistence.states;
+        const state = states?.get?.(sessionId);
+        if (state?.owner !== void 0 && ctx.sessions.get(sessionId) === void 0 && ctx.agents.get(sessionId) === void 0) {
+          states.delete(sessionId);
+          ctx.logger.warn(`session-manager: cleared stale persistence owner after move for "${sessionId}"`);
+        }
+      } catch (error) {
+        // The move itself is already durable. Keep its success, but make a
+        // future resume error diagnosable rather than hiding it in a best-effort
+        // cleanup branch.
+        ctx.logger.warn(`session-manager: post-move persistence retirement check failed for "${sessionId}": ${String(error)}`);
+      }
+
+      ctx.logger.info(
+        `session-manager: moved "${sessionId}" ` +
+        `${fromWorkspaceIds.length > 0 ? fromWorkspaceIds.join(",") + " -> " : ""}${target.id} ` +
+        `(${oldLocation.path} -> ${newLocation.path})`
+      );
+
+      // Cold artifact migration is now persistent on disk, accounting
+      // has been swapped, the projection cache has been re-folded from
+      // scratch, and the live entry has been detached. The only side-channel
+      // thing still on disk is the renamed original artifact at oldHidden:
+      // any error thrown before this point would have left it behind for
+      // restoration, but here we are about to return success, so dropping
+      // it -- and its (possibly empty) parent directory -- is safe.
+      try {
+        await rm(oldHidden, { force: true });
+      } catch { /* best-effort */ }
+      try {
+        await rm(dirname(oldLocation.path), { recursive: true, force: true });
+      } catch { /* best-effort */ }
+
+
+
+      return {
+        ok: true,
+        sessionId,
+        moved: true,
+        fromWorkspaceIds,
+        toWorkspaceId: target.id,
+        toWorkspaceTitle: target.title || target.id,
+        artifactFrom: oldLocation.path,
+        artifactTo: newLocation.path,
+        wasLive
+      };
+    };
+    /* === preset-migration (session-manager v0.3.0) === */
+    const NL = String.fromCharCode(10);
+
+    const scanSelectedEvents = (content) => {
+      const out = [];
+      const newlineAt = content.indexOf(NL);
+      const after = newlineAt === -1 ? content : content.slice(newlineAt + 1);
+      for (const line of after.split(NL)) {
+        if (line.length === 0) continue;
+        let obj;
+        try { obj = JSON.parse(line); } catch { continue; }
+        if (obj !== null && typeof obj === "object" && obj.type === "agent-preset/selected" && obj.data !== void 0 && typeof obj.data.agentPreset === "string") {
+          out.push({ agentPreset: obj.data.agentPreset, time: obj.time, seq: obj.seq });
+        }
+      }
+      return out;
+    };
+
+    const scanPreset = async (filter) => {
+      // Pull the full preset roster so the UI shows every available preset,
+      // not just the ones currently used by some session.
+      let allPresetIds = [];
+      try {
+        const ap = ctx.get("agentPresets");
+        if (ap !== void 0 && typeof ap.list === "function") {
+          const list = await ap.list();
+          for (const p of (list || [])) {
+            if (p && typeof p.id === "string" && p.id.length > 0) allPresetIds.push(p.id);
+          }
+        }
+      } catch { /* ignore -- fall back to used presets only */ }
+
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence === void 0) throw new Error("sessionPersistence service unavailable");
+      if (typeof persistence.readRaw !== "function" || typeof persistence.list !== "function") {
+        throw new Error("current persistence backend does not support readRaw/list");
+      }
+      const headers = await persistence.list();
+      let allowedIds = null;
+      const workspaceId = filter !== void 0 && typeof filter === "object" ? filter.id : void 0;
+      if (typeof workspaceId === "string" && workspaceId !== "") {
+        const registry = ctx.get("workspaceRegistry");
+        if (registry !== void 0 && typeof registry.list === "function") {
+          const all = registry.list();
+          const ws = all.find((entity) => entity.id === workspaceId);
+          if (ws === void 0) {
+            const error = new Error("workspace not found: " + workspaceId);
+            error.code = "workspace-not-found";
+            throw error;
+          }
+          allowedIds = new Set();
+          const ids = typeof ws.sessionIds === "function" ? ws.sessionIds() : ws.sessionIds;
+          if (Array.isArray(ids)) for (const id of ids) allowedIds.add(id);
+        }
+      }
+      const requestedSessionId = filter !== void 0 && typeof filter === "object" && typeof filter.sessionId === "string"
+        ? filter.sessionId
+        : "";
+      const out = [];
+      for (const header of headers) {
+        if (requestedSessionId !== "" && header.id !== requestedSessionId) continue;
+        if (allowedIds !== null && !allowedIds.has(header.id)) continue;
+        if (header.origin === "subagent") continue;
+        const raw = await persistence.readRaw(header.id);
+        if (raw === void 0) continue;
+        const newlineAt = raw.content.indexOf(NL);
+        if (newlineAt === -1) continue;
+        let headerObj;
+        try { headerObj = JSON.parse(raw.content.slice(0, newlineAt)); } catch { continue; }
+        const selected = scanSelectedEvents(raw.content);
+        const finalPreset = selected.length > 0 ? selected[selected.length - 1].agentPreset : headerObj.agentPreset;
+        out.push({ sessionId: header.id, cwd: header.cwd, origin: header.origin, headerPreset: headerObj.agentPreset, selectedEvents: selected, finalPreset });
+      }
+      // Targets come only from the live roster. A deleted preset can still be
+      // displayed as this session's current value, but must not be offered as
+      // a destination.
+      return { rows: out, availablePresets: Array.from(new Set(allPresetIds)) };
+    };
+
+    /**
+     * Fully retire a live agent/session before rewriting its durable preset.
+     * Waiting through persistence.load() is the important ownership barrier:
+     * session/disposed starts an async final drain, and a disk rewrite before
+     * that drain finishes leaves the coordinator's old Session as the live
+     * persistence owner (the later resume then fails with "already has a live
+     * persistence owner").
+     */
+    const retireForPresetMigration = async (sessionId, persistence) => {
+      const agent = ctx.agents.get(sessionId);
+      if (agent !== void 0) {
+        try { agent.cancel({ kind: "disposed" }); } catch { /* best-effort */ }
+        if (typeof agent.whenIdle === "function") await agent.whenIdle();
+        if (typeof agent.scope?.dispose === "function") await agent.scope.dispose();
+        // AgentRegistry exposes no public disposer for an already-owned Agent.
+        // The loop's later owner teardown is identity-guarded, so removing this
+        // exact stale entry after quiescence is safe and prevents ensureSession
+        // from returning an agent whose composition has just been retired.
+        try { ctx.agents.store?.delete?.(sessionId); } catch { /* best-effort */ }
+      }
+
+      // A session can be live without an Agent (or an Agent disposer can leave
+      // its session detach to the next microtask). Detach the exact remaining
+      // store entry so session/disposed starts persistence retirement.
+      const entry = ctx.sessions.store?.get?.(sessionId);
+      if (entry !== void 0 && typeof entry.detach === "function") entry.detach();
+
+      // Do not mutate the artifact until both registries have released it.
+      for (let attempt = 0; attempt < 100; attempt += 1) {
+        if (ctx.agents.get(sessionId) === void 0 && ctx.sessions.get(sessionId) === void 0) break;
+        await sleep(25);
+      }
+      if (ctx.agents.get(sessionId) !== void 0 || ctx.sessions.get(sessionId) !== void 0) {
+        throw new Error(`会话 "${sessionId}" 无法安全关闭，已取消预设迁移`);
+      }
+
+      // inspect() waits for any queued retirement without claiming a new
+      // persistence owner. load()/prepare() is deliberately NOT used here:
+      // a stale owner left by an older plugin version makes that ownership
+      // claim throw before this repair operation can remove it.
+      if (typeof persistence.inspect === "function") {
+        await persistence.inspect(sessionId);
+      } else if (typeof persistence.load === "function") {
+        await persistence.load(sessionId);
+      }
+
+      // Recovery for sessions affected by the older move/preset code: its
+      // registry cleanup could leave the coordinator holding an owner for a
+      // Session that is no longer present in ctx.sessions or ctx.agents. Such
+      // an owner can never append again, but blocks every later resume. Clear
+      // only that proven-orphaned state; normal live owners were rejected by
+      // the registry checks above and are never touched here.
+      const states = persistence.states;
+      const state = states?.get?.(sessionId);
+      if (state?.owner !== void 0) {
+        states.delete(sessionId);
+        ctx.logger.warn(`session-manager: cleared stale persistence owner for "${sessionId}" during preset migration`);
+      }
+    };
+
+    /** Rewrite exactly one conversation's effective Agent preset. */
+    const migratePreset = async (opts) => {
+      const sessionId = typeof opts.sessionId === "string" ? opts.sessionId.trim() : "";
+      const toPreset = typeof opts.toPreset === "string" ? opts.toPreset.trim() : "";
+      if (sessionId === "") { const e = new Error("sessionId required"); e.code = "bad-request"; throw e; }
+      if (toPreset === "") { const e = new Error("toPreset required"); e.code = "bad-request"; throw e; }
+
+      const presets = ctx.get("agentPresets");
+      if (presets === void 0 || typeof presets.list !== "function") {
+        throw new Error("agentPresets service unavailable");
+      }
+      const roster = await presets.list();
+      const target = (roster || []).find((preset) => preset && preset.id === toPreset);
+      if (target === void 0) {
+        const available = (roster || []).map((preset) => preset?.id).filter(Boolean);
+        throw new Error(`Agent 预设 "${toPreset}" 不存在（可用：${available.join(", ")}）`);
+      }
+      if (target.broken !== void 0) throw new Error(`Agent 预设 "${toPreset}" 不可用：${target.broken}`);
+
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence === void 0) throw new Error("sessionPersistence service unavailable");
+      if (typeof persistence.readRaw !== "function") throw new Error("current persistence backend does not support readRaw");
+
+      // Build the replacement before touching the live lifecycle. Plan B:
+      // sessions that have an agent-preset/selected event derive their preset
+      // from the LAST such event, so rewrite that event; older sessions derive
+      // it from the header, so rewrite only the header field.
+      const raw = await persistence.readRaw(sessionId);
+      if (raw === void 0) throw new Error(`session "${sessionId}" has no artifact`);
+      const lines = raw.content.split(NL);
+      if (lines.length < 2) throw new Error("session artifact has no header line");
+      let headerObj;
+      try { headerObj = JSON.parse(lines[0]); } catch { throw new Error("session header parse failed"); }
+      if (headerObj.id !== sessionId) throw new Error("session header id mismatch");
+
+      let selectedIndex = -1;
+      let selectedPreset;
+      for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index] === "") continue;
+        let event;
+        try { event = JSON.parse(lines[index]); } catch { continue; }
+        if (event && event.type === "agent-preset/selected" && event.data && typeof event.data.agentPreset === "string") {
+          selectedIndex = index;
+          selectedPreset = event.data.agentPreset;
+        }
+      }
+      const oldPreset = selectedIndex >= 0 ? selectedPreset : headerObj.agentPreset;
+      if (oldPreset === toPreset) {
+        return { sessionId, migrated: false, oldPreset, newPreset: toPreset };
+      }
+
+      if (selectedIndex >= 0) {
+        const event = JSON.parse(lines[selectedIndex]);
+        event.data = { ...event.data, agentPreset: toPreset };
+        lines[selectedIndex] = JSON.stringify(event);
+      } else {
+        headerObj.agentPreset = toPreset;
+        lines[0] = JSON.stringify(headerObj);
+      }
+
+      await retireForPresetMigration(sessionId, persistence);
+
+      // Re-read after retirement so a final buffered append cannot be lost. If
+      // the artifact changed while the owner drained, rebuild the replacement
+      // from that final durable text using the same Plan-B rule.
+      const settledRaw = await persistence.readRaw(sessionId);
+      if (settledRaw === void 0) throw new Error(`session "${sessionId}" disappeared during retirement`);
+      const settledLines = settledRaw.content.split(NL);
+      let settledHeader;
+      try { settledHeader = JSON.parse(settledLines[0]); } catch { throw new Error("settled session header parse failed"); }
+      let settledSelectedIndex = -1;
+      for (let index = 1; index < settledLines.length; index += 1) {
+        if (settledLines[index] === "") continue;
+        let event;
+        try { event = JSON.parse(settledLines[index]); } catch { continue; }
+        if (event && event.type === "agent-preset/selected" && event.data && typeof event.data.agentPreset === "string") {
+          settledSelectedIndex = index;
+        }
+      }
+      if (settledSelectedIndex >= 0) {
+        const event = JSON.parse(settledLines[settledSelectedIndex]);
+        event.data = { ...event.data, agentPreset: toPreset };
+        settledLines[settledSelectedIndex] = JSON.stringify(event);
+      } else {
+        settledHeader.agentPreset = toPreset;
+        settledLines[0] = JSON.stringify(settledHeader);
+      }
+
+      const location = persistence.locate(settledRaw.meta);
+      if (location === void 0) throw new Error("locate returned undefined");
+      const replacementContent = settledLines.join(NL);
+      const firstNewline = replacementContent.indexOf(NL);
+      const headerLine = replacementContent.slice(0, firstNewline);
+      const rest = replacementContent.slice(firstNewline + 1);
+      const bytes = await encodeArtifact(headerLine, rest, location.path.endsWith(".zstd"));
+      await mkdir(dirname(location.path), { recursive: true });
+      const tempPath = await writeTempFile(location.path, bytes);
+      try {
+        await rename(tempPath, location.path);
+      } catch (error) {
+        try { await rm(tempPath, { force: true }); } catch { /* ignore */ }
+        throw new Error("preset migration rename failed: " + String(error));
+      }
+
+      // This is the same public notification emitted for the built-in blank
+      // session preset switch. It updates the displayed preset and invalidates
+      // preset-dependent client caches without fabricating a new live Session.
+      try { ctx.emit("agent-preset/selected", sessionId, toPreset); } catch { /* best-effort */ }
+      ctx.logger.info(`session-manager: migrated preset for "${sessionId}" from "${String(oldPreset)}" to "${toPreset}"`);
+      return { sessionId, migrated: true, oldPreset, newPreset: toPreset };
+    };
+
+  /* ==== legacy v0.2.0 move implementation — DISABLED in 0.2.1 ============================
+     It never actually worked: DSH's WorkspaceEntity.attachSession validates
+     realpath(header.cwd) === workspace.path, so a cross-workspace attach always
+     threw "its cwd resolves to ..."; the registry-state fallback below also
+     mutated a state object that has no `workspaces` field. Replaced by the
+     re-home implementation above (cwd rewrite + artifact migration + fresh
+     placeholder header for index refresh).
+    /** Move one session from its current workspace to a target workspace. (legacy)
+  const moveSession = async (sessionId, targetWorkspaceId) => {
+    const registry = ctx.workspaceRegistry;
+    const allWorkspaces = registry.list();
+
+    // Find target workspace
+    const targetWorkspace = allWorkspaces.find((e) => e.id === targetWorkspaceId);
+    if (!targetWorkspace) {
+      throw new Error(`目标工作区不存在: ${targetWorkspaceId}`);
+    }
+
+    // Find current workspace(s) containing this session
+    const currentWorkspaces = allWorkspaces.filter((e) => e.sessionIds.includes(sessionId));
+
+    // Check if already in target workspace
+    if (currentWorkspaces.length === 1 && currentWorkspaces[0].id === targetWorkspaceId) {
+      return { ok: true, sessionId, moved: false, message: "会话已在目标工作区中" };
+    }
+
+    // Detach from all current workspaces
+    for (const entity of currentWorkspaces) {
+      await entity.detachSession(sessionId);
+    }
+
+    // Attach to target workspace
+    if (typeof targetWorkspace.attachSession === "function") {
+      await targetWorkspace.attachSession(sessionId);
+    } else if (typeof targetWorkspace.prependSession === "function") {
+      await targetWorkspace.prependSession(sessionId);
+    } else {
+      // Fallback: try to use the registry's enqueueOperation
+      await registry.enqueueOperation(async () => {
+        const state = registry.requireState();
+        // Find target workspace in state and add session
+        const targetState = state.workspaces?.find((w) => w.id === targetWorkspaceId);
+        if (targetState) {
+          if (!targetState.sessionIds) targetState.sessionIds = [];
+          if (!targetState.sessionIds.includes(sessionId)) {
+            targetState.sessionIds.unshift(sessionId);
+          }
+          await registry.setState(state);
+        }
+      });
+    }
+
+    return {
+      ok: true,
+      sessionId,
+      moved: true,
+      fromWorkspace: currentWorkspaces.map((e) => e.id),
+      toWorkspace: targetWorkspaceId
+    };
+  };
+
+  ==== end legacy v0.2.0 move implementation ==== */
+    /** Resolve the on-disk session directory (parent of its artifact), if any. */
   const sessionDirOf = async (sessionId) => {
     const persistence = ctx.get("sessionPersistence");
     if (persistence === void 0) return void 0;
@@ -102,6 +969,7 @@ export function apply(ctx) {
       } catch { /* best-effort */ }
     }
 
+    let detached = false;
     if (session !== void 0) {
       // Flush buffered events to disk first so the retirement drain is a no-op.
       try {
@@ -115,9 +983,23 @@ export function apply(ctx) {
         if (entry !== void 0 && typeof entry.detach === "function") {
           entry.detach();
           await sleep(200); // let the write-behind retirement settle
+          detached = true;
         }
       } catch { /* best-effort */ }
     }
+    // Some sessions have a stored artifact but no live store row (e.g.
+    // already-scoped scope torn down, or never attached). Without a live
+    // entry, ctx.sessions.store?.get?.(sessionId) returns undefined and
+    // entry.detach() never fires — so the apiproxy never queues a
+    // host/session-removed frame, every connected client keeps showing the
+    // session row, and the row collapses into the ungrouped section the
+    // moment host/workspace-changed drops its workspace membership. Emit
+    // session/disposed explicitly so every connected client drops the row.
+    if (!detached) {
+      try {
+        ctx.emit("session/disposed", { id: sessionId });
+      } catch (_) { /* best-effort */ }
+    }
 
     // Workspace accounting + archive-set membership.
     await detachFromWorkspaces(sessionId);
@@ -137,6 +1019,107 @@ export function apply(ctx) {
     };
   };
 
+  /**
+   * On plugin boot, refold every persisted session projection cache
+   * row from disk. Sessions moved before coldSnapshot was wired into
+   * moveSession would otherwise keep their pre-move {createdAt, cwd}
+   * identity and let the cold list path fall back to basename(cwd),
+   * surfacing the workspace title (for example "DSH") where the
+   * session's own title was expected. The sweep is one-shot and
+   * idempotent: a row whose identity already matches is a cheap
+   * pass-through refold, and a stale one triggers the unrelated-identity
+   * full re-read path.
+   */
+  ctx.effect(async () => {
+    const cache = ctx.get("sessionProjectionCache");
+    const persistence = ctx.get("sessionPersistence");
+    const registry = ctx.get("workspaceRegistry");
+    if (cache === void 0 || typeof cache.coldSnapshot !== "function") return;
+    if (persistence === void 0 || typeof persistence.list !== "function") return;
+    if (registry === void 0 || typeof registry.list !== "function") return;
+    try {
+      // ---- step 1: re-fold every active session's projection cache row,
+      // so a session moved before coldSnapshot was wired in stops being
+      // identity-stuck under a stale {createdAt, cwd} key.
+      const headers = await persistence.list();
+      let refolded = 0;
+      const headerById = new Map();
+      for (const header of headers) {
+        if (header === void 0 || header.cwd === void 0) continue;
+        headerById.set(header.id, header);
+        try {
+          await cache.coldSnapshot(header.id);
+          refolded += 1;
+        } catch (error) {
+          ctx.logger.warn(`session-manager: post-boot cache refold failed for "${header.id}": ${String(error)}`);
+        }
+      }
+      ctx.logger.info(`session-manager: post-boot re-folded ${refolded} session projection cache rows`);
+
+      // ---- step 2: reconcile workspace accounting with disk. After a few
+      // pre-fix moves, a workspace record could keep a session id whose
+      // disk artifact is gone, OR miss a session whose disk artifact is on
+      // a matching cwd but not in any record. Both symptoms show up as
+      // "AI count higher than visible" / "another session in ungrouped".
+      // Walk the registry, drop missing-disk ids, and add missing-in-record
+      // ids back into the workspace whose path matches header.cwd.
+      const allWorkspaces = registry.list();
+      const recordByWs = new Map();
+      for (const ws of allWorkspaces) {
+        recordByWs.set(ws.id, ws);
+      }
+      const validIds = new Set(headerById.keys());
+      const pathToWs = new Map();
+      for (const ws of allWorkspaces) {
+        pathToWs.set(ws.path, ws);
+      }
+      // Pass 1: drop ids whose disk artifact no longer exists.
+      let removed = 0;
+      for (const ws of allWorkspaces) {
+        const filtered = ws.record?.sessionIds?.filter((id) => validIds.has(id));
+        const original = ws.record?.sessionIds ?? [];
+        if (filtered && filtered.length !== original.length) {
+          await registry.enqueueOperation(async () => {
+            const state = registry.requireState();
+            const w = state.workspaces?.find((s) => s.id === ws.id);
+            if (w !== undefined) {
+              w.sessionIds = filtered;
+              w.updatedAt = new Date().toISOString();
+              await registry.setState(state);
+            }
+          });
+          removed += original.length - filtered.length;
+        }
+      }
+      // Pass 2: attach disk-only sessions to the workspace whose path
+      // matches their cwd.
+      let added = 0;
+      for (const header of headers) {
+        if (header.cwd === void 0) continue;
+        const ws = pathToWs.get(header.cwd);
+        if (ws === undefined) continue;
+        const rec = ws.record;
+        if (rec === undefined || rec.sessionIds === undefined) continue;
+        if (rec.sessionIds.includes(header.id)) continue;
+        await registry.enqueueOperation(async () => {
+          const state = registry.requireState();
+          const w = state.workspaces?.find((s) => s.id === ws.id);
+          if (w !== undefined && w.sessionIds !== undefined && !w.sessionIds.includes(header.id)) {
+            w.sessionIds = [header.id, ...w.sessionIds];
+            w.updatedAt = new Date().toISOString();
+            await registry.setState(state);
+            added += 1;
+          }
+        });
+      }
+      if (removed > 0 || added > 0) {
+        ctx.logger.info(`session-manager: post-boot workspace reconcile removed ${removed} orphans, attached ${added} disk-only sessions`);
+      }
+    } catch (error) {
+      ctx.logger.warn(`session-manager: post-boot reconcile failed: ${String(error)}`);
+    }
+  }, "session-manager: post-boot re-fold stale projection cache rows");
+
   ctx.effect(() => ctx.webServer.register({
     kind: "prefix",
     path: API_PREFIX,
@@ -183,9 +1166,64 @@ export function apply(ctx) {
           }
         }
 
+          if (req.method === "POST" && path === "/move") {
+            if (sessionId === null) return send(res, 400, { ok: false, error: "sessionId 必填" });
+            const targetWorkspaceId = typeof body.targetWorkspaceId === "string" && body.targetWorkspaceId.trim() !== ""
+              ? body.targetWorkspaceId.trim()
+              : null;
+            if (targetWorkspaceId === null) return send(res, 400, { ok: false, error: "targetWorkspaceId 必填" });
+            try {
+              const result = await moveSession(sessionId, targetWorkspaceId);
+              return send(res, 200, { ok: true, result });
+            } catch (error) {
+ctx.logger.warn(`session-manager: api error: ${String(error)}; type=${error?.constructor?.name}; json=${safeJson(error)}`);
+              return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
+            }
+          }
+
+          if (req.method === "GET" && path === "/workspaces") {
+            try {
+              const workspaces = listWorkspaces();
+              return send(res, 200, { ok: true, result: { workspaces } });
+            } catch (error) {
+              ctx.logger.warn(`session-manager: listWorkspaces failed: ${String(error)}`);
+              return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
+            }
+          }
+
+        if (req.method === "GET" && path === "/preset-scan") {
+          try {
+            const workspaceId = url.searchParams.get("workspaceId") || "";
+            const requestedSessionId = url.searchParams.get("sessionId") || "";
+            const filter = {
+              ...(workspaceId !== "" ? { id: workspaceId } : {}),
+              ...(requestedSessionId !== "" ? { sessionId: requestedSessionId } : {})
+            };
+            const result = await scanPreset(filter);
+            return send(res, 200, { ok: true, result });
+          } catch (error) {
+            ctx.logger.warn("session-manager: preset-scan failed: " + String(error));
+            return send(res, 500, { ok: false, error: String(error.message || error) });
+          }
+        }
+        if (req.method === "POST" && path === "/preset-migrate") {
+          const requestedSessionId = typeof body.sessionId === "string" ? body.sessionId.trim() : "";
+          const toPreset = typeof body.toPreset === "string" ? body.toPreset.trim() : "";
+          if (requestedSessionId === "" || toPreset === "") {
+            return send(res, 400, { ok: false, error: "sessionId and toPreset required" });
+          }
+          try {
+            const result = await migratePreset({ sessionId: requestedSessionId, toPreset });
+            return send(res, 200, { ok: true, result });
+          } catch (error) {
+            ctx.logger.warn("session-manager: preset-migrate failed: " + String(error));
+            return send(res, 500, { ok: false, error: String(error.message || error) });
+          }
+        }
+
         return send(res, 404, { ok: false, error: `not found: ${req.method} ${path}` });
       } catch (error) {
-        ctx.logger.warn(`session-manager: api error: ${String(error)}`);
+        ctx.logger.warn(`session-manager: api error: ${String(error)}; type=${error?.constructor?.name}; json=${safeJson(error)}`);
         return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
       }
     }