dsh-session-manager 0.4.1 → 0.4.6

package/lib/index.js

@@ -1,1231 +1,1233 @@
-/**
- * @dsh-session-manager — Host half.
- *
- * DSH 0.1.0-rc.6 ships `workspace.archiveSession` (归档) but has NO session
- * 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
- *      session store entry (emits session/disposed -> host/session-removed so
- *      every tab drops the row), flush + remove the JSONL artifact directory,
- *      remove workspace accounting, and remove the archive-set membership.
- *  - POST /session-manager/api/unarchive  { sessionId }
- *      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 { 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";
-
-export const inject = [
-  "webServer",
-  "workspaceRegistry",
-  "sessions",
-  "agents",
-  "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));
-
-export function apply(ctx) {
-  const readBody = async (req) => {
-    const chunks = [];
-    for await (const chunk of req) chunks.push(Buffer.from(chunk));
-    return Buffer.concat(chunks).toString("utf8");
-  };
-
-  const send = (res, code, obj) => {
-    res.writeHead(code, { "content-type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify(obj));
-  };
-
-  /** Remove one id from the registry-global archive set (durable, serialized). */
-  const unarchiveSession = async (sessionId) => {
-    const registry = ctx.workspaceRegistry;
-    await registry.enqueueOperation(async () => {
-      const state = registry.requireState();
-      if (!state.archivedSessionIds.includes(sessionId)) return;
-      await registry.setState({
-        ...state,
-        archivedSessionIds: state.archivedSessionIds.filter((id) => id !== sessionId)
-      });
-    });
-  };
-
-  /** Detach one session from every workspace's ordered accounting. */
-  const detachFromWorkspaces = async (sessionId) => {
-    for (const entity of ctx.workspaceRegistry.list()) {
-      if (entity.sessionIds.includes(sessionId)) {
-        await entity.detachSession(sessionId);
-      }
-    }
-  };
-
-  /** 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;
-    const headers = await persistence.list();
-    const meta = headers.find((header) => header.id === sessionId);
-    if (meta === void 0) return void 0;
-    const location = persistence.locate(meta);
-    if (location === void 0) return void 0;
-    return dirname(location.path);
-  };
-
-  /**
-   * Delete one session end to end. Returns a summary of what was torn down.
-   * Idempotent-ish: unknown sessions resolve to { ok: true, deleted: false }.
-   */
-  const deleteSession = async (sessionId) => {
-    const session = ctx.sessions.get(sessionId);
-    const agent = ctx.agents.get(sessionId);
-
-    if (agent !== void 0) {
-      // Stop any running turn (disposed-kind suppresses re-wake).
-      agent.cancel({ kind: "disposed" });
-      // Quiesce the agent's own fiber (idempotent; bounded in case teardown stalls).
-      if (typeof agent.scope?.dispose === "function") {
-        await Promise.race([agent.scope.dispose(), sleep(3000)]);
-      }
-      // Drop the zombie from the registry so a later session.create/open with
-      // the same id cannot resurrect it.
-      try {
-        ctx.agents.store?.delete?.(sessionId);
-      } 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 {
-        await ctx.sessions.flush(session);
-      } catch { /* best-effort */ }
-      // Detach the session store entry: emits session/disposed, which the
-      // persistence write-path answers with a final drain, and the API proxy
-      // relays as host/session-removed so every connected client drops the row.
-      try {
-        const entry = ctx.sessions.store?.get?.(sessionId);
-        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);
-    await unarchiveSession(sessionId);
-
-    // Physical artifact (session.jsonl / session.jsonl.zstd) + any extras.
-    const dir = await sessionDirOf(sessionId);
-    if (dir !== void 0) {
-      await rm(dir, { recursive: true, force: true });
-    }
-
-    return {
-      ok: true,
-      sessionId,
-      wasLive: session !== void 0 || agent !== void 0,
-      filesRemoved: dir !== void 0
-    };
-  };
-
-  /**
-   * 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,
-    handler: async (req, res) => {
-      try {
-        const url = new URL(req.url ?? "/", "http://localhost");
-        const path = url.pathname.startsWith(API_PREFIX)
-          ? url.pathname.slice(API_PREFIX.length) || "/"
-          : "/";
-        let body = {};
-        if (req.method === "POST") {
-          const raw = await readBody(req);
-          if (raw.trim() !== "") {
-            try {
-              body = JSON.parse(raw);
-            } catch {
-              return send(res, 400, { ok: false, error: "请求体不是合法 JSON" });
-            }
-          }
-        }
-        const sessionId = typeof body.sessionId === "string" && body.sessionId.trim() !== ""
-          ? body.sessionId.trim()
-          : null;
-
-        if (req.method === "POST" && path === "/delete") {
-          if (sessionId === null) return send(res, 400, { ok: false, error: "sessionId 必填" });
-          try {
-            const result = await deleteSession(sessionId);
-            return send(res, 200, { ok: true, result });
-          } catch (error) {
-            ctx.logger.warn(`session-manager: delete "${sessionId}" failed: ${String(error)}`);
-            return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
-          }
-        }
-
-        if (req.method === "POST" && path === "/unarchive") {
-          if (sessionId === null) return send(res, 400, { ok: false, error: "sessionId 必填" });
-          try {
-            await unarchiveSession(sessionId);
-            return send(res, 200, { ok: true, result: { sessionId } });
-          } catch (error) {
-            ctx.logger.warn(`session-manager: unarchive "${sessionId}" failed: ${String(error)}`);
-            return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
-          }
-        }
-
-          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)}; type=${error?.constructor?.name}; json=${safeJson(error)}`);
-        return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
-      }
-    }
-  }), "session-manager: http api");
-}
+/**
+ * @dsh-session-manager — Host half.
+ *
+ * DSH 0.1.0-rc.6 ships `workspace.archiveSession` (归档) but has NO session
+ * 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
+ *      session store entry (emits session/disposed -> host/session-removed so
+ *      every tab drops the row), flush + remove the JSONL artifact directory,
+ *      remove workspace accounting, and remove the archive-set membership.
+ *  - POST /session-manager/api/unarchive  { sessionId }
+ *      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 { mkdir, open, readdir, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export const name = "dsh-session-manager";
+
+export const inject = [
+  "webServer",
+  "workspaceRegistry",
+  "sessions",
+  "agents",
+  "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));
+
+export function apply(ctx) {
+  const readBody = async (req) => {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+  };
+
+  const send = (res, code, obj) => {
+    res.writeHead(code, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(obj));
+  };
+
+  /** Remove one id from the registry-global archive set (durable, serialized). */
+  const unarchiveSession = async (sessionId) => {
+    const registry = ctx.workspaceRegistry;
+    await registry.enqueueOperation(async () => {
+      const state = registry.requireState();
+      if (!state.archivedSessionIds.includes(sessionId)) return;
+      await registry.setState({
+        ...state,
+        archivedSessionIds: state.archivedSessionIds.filter((id) => id !== sessionId)
+      });
+    });
+  };
+
+  /** Detach one session from every workspace's ordered accounting. */
+  const detachFromWorkspaces = async (sessionId) => {
+    for (const entity of ctx.workspaceRegistry.list()) {
+      if (entity.sessionIds.includes(sessionId)) {
+        await entity.detachSession(sessionId);
+      }
+    }
+  };
+
+  /** 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
+          };
+
+    });
+  };
+
+
+       /**
+     * 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.locate !== "function") {
+        throw new Error("当前持久化后端无法定位会话工件，无法跨工作区移动");
+      }
+
+      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;
+
+      const storedHeaders = await listSessionHeaders(persistence);
+      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;
+      }
+      if (storedHeader.cwd !== void 0) {
+        let currentCanonical;
+        try { currentCanonical = await realpath(storedHeader.cwd); } catch { /* re-home below */ }
+        if (currentCanonical === targetPath) {
+          return { ok: true, sessionId, moved: false, message: "会话已属于目标工作区" };
+        }
+      }
+
+      const liveSession = ctx.sessions.get(sessionId);
+      let liveAgent;
+      try { liveAgent = ctx.agents.get(sessionId); } catch { liveAgent = void 0; }
+      // The session header is immutable. A live session therefore has to be
+      // retired as one agent-loop lifecycle and recreated after the artifact is
+      // re-homed. Never delete registry map entries directly: doing so skips
+      // the agent-loop/session disposal effects and leaves a live persistence
+      // owner behind.
+            // NO-TEARDOWN approach: keep the live agent/session intact so the
+      // client UI never has to re-init. Just flush pending events to
+      // disk (still at OLD cwd), then atomically rename the artifact to
+      // NEW cwd. The persistence coordinator's serialize() inside the
+      // move block holds the per-id lock, so the write-behind can't append
+      // to the hidden file. The agent's UI keeps showing the same in-memory
+      // session -- no client state flip, no half-initialized resume, no
+      // "session unavailable" symptoms.
+      if (liveSession !== void 0) {
+        try { await ctx.sessions.flush(liveSession); } catch { /* best-effort */ }
+      }
+
+            // No teardown -- the agent and session are still live and that's
+      // intentional. Move straight to file re-home.
+      const coordinator = persistence.coordinator;
+      const serialize = typeof coordinator?.serialize === "function"
+        ? (operation) => coordinator.serialize(sessionId, operation)
+        : (operation) => operation();
+
+      const result = await serialize(async () => {
+        const raw = await readSessionArtifact(sessionId);
+        if (raw === void 0) throw new Error("读取会话工件失败：未找到会话文件");
+        const newlineAt = raw.content.indexOf("\n");
+        if (newlineAt === -1) throw new Error("会话工件缺少头行，数据可能损坏");
+        const rest = raw.content.slice(newlineAt + 1);
+        let oldHeader;
+        try { oldHeader = JSON.parse(raw.content.slice(0, newlineAt)); }
+        catch (error) { throw new Error(`会话工件头行无法解析: ${String(error)}`); }
+        if (oldHeader.id !== sessionId) throw new Error("会话工件头行 id 与请求不符，拒绝移动");
+
+        // Keep the stored generation in sync with the filename selected by
+        // persistence.locate(). Rewriting a v2 header to v0 while locating it
+        // through the same v2 backend creates a v2 filename with v0 content,
+        // which makes DSH reject the session on the next startup.
+        const newHeader = { ...oldHeader, cwd: targetPath };
+        const oldPath = raw.path ?? persistence.locate(raw.meta)?.path;
+        const newLocation = persistence.locate(newHeader);
+        if (typeof oldPath !== "string" || newLocation === void 0) {
+          throw new Error("持久化后端无法定位会话工件路径");
+        }
+        const newPath = newLocation.path;
+        if (oldPath === newPath) throw new Error("会话源路径与目标路径相同，但 cwd 不一致，拒绝覆盖");
+        const bytes = await encodeArtifact(JSON.stringify(newHeader), rest, newPath.endsWith(".zstd"));
+        await mkdir(dirname(newPath), { recursive: true });
+        const tempNew = await writeTempFile(newPath, bytes);
+        const oldHidden = `${oldPath}.${randomBytes(6).toString("hex")}.tmp`;
+        try {
+          await rename(oldPath, oldHidden);
+        } catch (error) {
+          await rm(tempNew, { force: true });
+          throw new Error(`移动失败（无法隐藏旧会话工件，已取消，会话保持原状）: ${String(error)}`);
+        }
+        try {
+          await rename(tempNew, newPath);
+        } catch (error) {
+          try { await rename(oldHidden, oldPath); } catch { /* reported below */ }
+          await rm(tempNew, { force: true });
+          throw new Error(`移动失败（发布新会话工件失败，已尝试回滚）: ${String(error)}`);
+        }
+
+        const state = coordinator?.states?.get?.(sessionId);
+        if (state?.owner !== void 0 && liveSession !== void 0 && state.owner !== liveSession) {
+          await rm(newPath, { force: true });
+          await rename(oldHidden, oldPath);
+          throw new Error(`会话 ${sessionId} 的持久化 owner 与当前 live session 不一致，已回滚`);
+        }
+        const oldStateMeta = state?.meta;
+        const oldLiveHeader = liveSession?.header;
+        const oldIndexedHeader = registry.headers?.get?.(sessionId);
+        const oldIndexedPath = registry.sessionPaths?.get?.(sessionId);
+        const oldInvalidPath = registry.invalidSessionPaths?.get?.(sessionId);
+        const fromWorkspaceIds = registry.list()
+          .filter((entity) => entity.id !== target.id && (entity.record?.sessionIds ?? entity.sessionIds).includes(sessionId))
+          .map((entity) => entity.id);
+        let targetAttached = false;
+        const detachedFrom = [];
+
+        try {
+          if (state !== void 0) {
+            state.meta = { ...state.meta, ...newHeader, cwd: targetPath };
+            state.materialized = true;
+          }
+          coordinator?.preparations?.invalidate?.(sessionId);
+          if (liveSession !== void 0) liveSession.header = Object.freeze({ ...newHeader });
+          registry.headers?.set?.(sessionId, { ...newHeader });
+          registry.sessionPaths?.set?.(sessionId, targetPath);
+          registry.invalidSessionPaths?.delete?.(sessionId);
+
+          await registry.enqueueOperation(async () => {
+            for (const id of fromWorkspaceIds) {
+              const entity = registry.list().find((candidate) => candidate.id === id);
+              if (entity === void 0) continue;
+              await entity.detachSession(sessionId);
+              detachedFrom.push(id);
+            }
+            await target.attachSession(sessionId);
+            targetAttached = true;
+          });
+        } catch (error) {
+          if (state !== void 0 && oldStateMeta !== void 0) state.meta = oldStateMeta;
+          coordinator?.preparations?.invalidate?.(sessionId);
+          if (liveSession !== void 0 && oldLiveHeader !== void 0) liveSession.header = oldLiveHeader;
+          if (oldIndexedHeader === void 0) registry.headers?.delete?.(sessionId);
+          else registry.headers?.set?.(sessionId, oldIndexedHeader);
+          if (oldIndexedPath === void 0) registry.sessionPaths?.delete?.(sessionId);
+          else registry.sessionPaths?.set?.(sessionId, oldIndexedPath);
+          if (oldInvalidPath === void 0) registry.invalidSessionPaths?.delete?.(sessionId);
+          else registry.invalidSessionPaths?.set?.(sessionId, oldInvalidPath);
+
+          const rollbackErrors = [];
+          try { if (targetAttached) await target.detachSession(sessionId); } catch (e) { rollbackErrors.push(e); }
+          for (const id of detachedFrom) {
+            try {
+              const entity = registry.list().find((candidate) => candidate.id === id);
+              if (entity !== void 0) await entity.attachSession(sessionId);
+            } catch (e) { rollbackErrors.push(e); }
+          }
+          try { await rm(newPath, { force: true }); } catch (e) { rollbackErrors.push(e); }
+          try { await rename(oldHidden, oldPath); } catch (e) { rollbackErrors.push(e); }
+          if (rollbackErrors.length > 0) {
+            throw new AggregateError([error, ...rollbackErrors], "移动失败且回滚不完整");
+          }
+          throw error;
+        }
+
+        try { await rm(oldHidden, { force: true }); } catch { /* best-effort */ }
+        try { await rm(dirname(oldPath), { recursive: true, force: true }); } catch { /* best-effort */ }
+        return {
+          ok: true,
+          sessionId,
+          moved: true,
+          fromWorkspaceIds,
+          toWorkspaceId: target.id,
+          toWorkspaceTitle: target.title || target.id,
+          artifactFrom: oldPath,
+          artifactTo: newPath,
+          wasLive: liveSession !== void 0 || liveSession !== void 0
+        };
+      });
+
+      const cache = ctx.get("sessionProjectionCache");
+      if (cache !== void 0 && typeof cache.coldSnapshot === "function") {
+        try { await cache.coldSnapshot(sessionId); }
+        catch (error) { ctx.logger.warn(`session-manager: post-move cache refresh failed for "${sessionId}": ${String(error)}`); }
+      }
+            // The agent is still live (no teardown). The session's in-memory
+      // header was rewritten above and the workspace registry updated;
+      // future writes go through persistence.locate() against the new
+      // cwd, so the file at the new location accumulates new events.
+      // Re-resuming the agent here re-creates a half-initialized
+      // Session/agent pair and leaves the client UI in a "session
+      // unavailable" state (agent/status is only emitted on PHASE
+      // CHANGES, never on agent construction). Leaving the live
+      // agent/session in place avoids the broken UI entirely.
+            ctx.logger.info(`session-manager: moved "${sessionId}" to workspace "${target.id}"${liveSession !== void 0 ? " and resumed" : ""}`);
+      return result;
+    };
+    /* === 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");
+      // Don't pre-flight check readRaw/list -- the actual JSONL backend
+      // exposes both. listSessionHeaders is wrapped in try/catch below so
+      // any missing-method error surfaces as a useful per-session "no
+      // artifact" message instead of a hard "backend does not support"
+      // failure that hides which session actually failed.
+      let headers = [];
+      try {
+        headers = await listSessionHeaders(persistence);
+      } catch (probeError) {
+        throw new Error("failed to enumerate sessions: " + String(probeError.message ?? probeError));
+      }
+      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 readSessionArtifact(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; }
+        let selected = scanSelectedEvents(raw.content);
+        const live = ctx.sessions.get(header.id);
+        if (live !== void 0) {
+          const liveEvents = Array.isArray(live.events)
+            ? live.events
+            : Array.isArray(live.log) ? live.log : [];
+          const liveSelected = liveEvents
+            .filter((event) => event?.type === "agent-preset/selected" && typeof event.data?.agentPreset === "string")
+            .map((event) => ({ agentPreset: event.data.agentPreset, time: event.time, seq: event.seq }));
+          if (liveSelected.length > selected.length) selected = liveSelected;
+        }
+        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").
+     */
+    /** Cold-path preset migration: read disk, rewrite, publish. Works whether
+     * or not the session is currently in the coordinator, and does not depend on
+     * `coordinator.states` carrying a fresh `meta.cwd`. */
+    const applyMigrationToArtifact = async (args) => {
+      const sessionId = typeof args.sessionId === "string" ? args.sessionId : "";
+      const toPreset = typeof args.toPreset === "string" ? args.toPreset : "";
+      const liveSession = (args !== void 0 && typeof args === "object") ? args.liveSession : void 0;
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence === void 0) throw new Error("sessionPersistence service unavailable");
+      const coordinator = persistence.coordinator;
+      const serialize = typeof coordinator?.serialize === "function"
+        ? (operation) => coordinator.serialize(sessionId, operation)
+        : (operation) => operation();
+      return await serialize(async () => {
+        const raw = await readSessionArtifact(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 header;
+        try { header = JSON.parse(lines[0]); } catch { throw new Error("session header parse failed"); }
+        if (header.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?.type === "agent-preset/selected" && typeof event.data?.agentPreset === "string") {
+            selectedIndex = index;
+            selectedPreset = event.data.agentPreset;
+          }
+        }
+        const oldPreset = selectedIndex >= 0 ? selectedPreset : header.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 {
+          header.agentPreset = toPreset;
+          lines[0] = JSON.stringify(header);
+        }
+
+        const artifactPath = raw.path ?? persistence.locate?.(raw.meta)?.path;
+        if (typeof artifactPath !== "string") throw new Error("cannot locate session artifact");
+        const replacementContent = lines.join(NL);
+        const firstNewline = replacementContent.indexOf(NL);
+        const bytes = await encodeArtifact(
+          replacementContent.slice(0, firstNewline),
+          replacementContent.slice(firstNewline + 1),
+          artifactPath.endsWith(".zstd")
+        );
+        const tempPath = await writeTempFile(artifactPath, bytes);
+        const hiddenPath = `${artifactPath}.${randomBytes(6).toString("hex")}.tmp`;
+        try {
+          await rename(artifactPath, hiddenPath);
+          await rename(tempPath, artifactPath);
+        } catch (error) {
+          try { await rm(artifactPath, { force: true }); } catch { /* best-effort */ }
+          try { await rename(hiddenPath, artifactPath); } catch { /* reported below */ }
+          try { await rm(tempPath, { force: true }); } catch { /* best-effort */ }
+          throw new Error(`preset migration publish failed: ${String(error)}`);
+        }
+        try { await rm(hiddenPath, { force: true }); } catch { /* best-effort */ }
+
+        const state = coordinator?.states?.get?.(sessionId);
+        if (state !== void 0 && selectedIndex < 0) state.meta = { ...state.meta, agentPreset: toPreset };
+        coordinator?.preparations?.invalidate?.(sessionId);
+        // Mirror the disk rewrite into the in-memory live session: the cold path
+        // bypasses the persistence write controller (which is intentionally
+        // skipped when its state is stale), so the session header, projection,
+        // and downstream agent composition would otherwise keep reporting the old
+        // preset. Update both the header and the in-memory event log so DSH's
+        // `resolveSessionPreset` and any projection subscribers observe the new
+        // preset from the same source.
+        if (liveSession !== void 0) {
+          try {
+            const nextHeader = { ...(liveSession.header ?? {}), agentPreset: toPreset };
+            try { liveSession.header = Object.freeze(nextHeader); }
+            catch { liveSession.header = nextHeader; }
+          } catch { /* live session may have been retired mid-flight */ }
+          // Append the new selection to the live log so the session/store
+            // observers (agent-presets, projections, ctx) fire their normal
+            // `session/event` + `agent-preset/selected` pipeline. We append
+            // unconditionally (not only when the disk had no prior selection)
+            // because the in-memory projection reads the latest appended event
+            // and the cold path deliberately skipped the persistence write
+            // controller; the appended event will be persisted on the next
+            // normal flush, keeping disk and memory consistent.
+          if (typeof liveSession.append === "function") {
+            try { liveSession.append("agent-preset/selected", { agentPreset: toPreset }); } catch { /* best-effort */ }
+          }
+        }
+        return { sessionId, migrated: true, oldPreset, newPreset: toPreset };
+      });
+    };
+    /** 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 liveSession = ctx.sessions.get(sessionId);
+      let liveAgent;
+      try { liveAgent = ctx.agents.get(sessionId); } catch { liveAgent = void 0; }
+      // Resolve persistence up front so the live path can read the coordinator
+      // without tripping JavaScript's temporal dead zone on `const persistence`.
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence === void 0) throw new Error("sessionPersistence service unavailable");
+
+      if (liveSession !== void 0) {
+        const coordinator = persistence.coordinator;
+        const states = coordinator?.states;
+        const beforeState = states?.get?.(sessionId);
+        const liveCwd = liveSession.header?.cwd;
+        // A just-completed moveSession mutates `liveSession.header.cwd` in place,
+        // but the persistence coordinator's tracked state may not see the new cwd
+        // until its serialize chain drains. If we hand the migration to the
+        // coordinator now, its `state.meta.cwd` may still be the pre-move cwd and
+        // appendBatch will open the old (now deleted) artifact path, producing the
+        // "ENOENT ... session.v2.jsonl.zstd" regression. Falling back to the cold
+        // path is always correct: the disk copy already reflects the new cwd.
+        const stateStale = beforeState === void 0
+          || beforeState.meta?.cwd === void 0
+          || (liveCwd !== void 0 && beforeState.meta.cwd !== liveCwd);
+        if (stateStale) {
+          const raw = await readSessionArtifact(sessionId);
+          if (raw !== void 0) {
+            const result = await applyMigrationToArtifact({ sessionId, toPreset, liveSession });
+            if (result.migrated) { try { ctx.emit("agent-preset/selected", sessionId, toPreset); } catch { /* best-effort */ } }
+            ctx.logger.info(`session-manager: migrated live preset for "${sessionId}" via cold path (state was stale, live cwd=${String(liveCwd)}, state cwd=${String(beforeState?.meta?.cwd)})`);
+            return { sessionId, migrated: true, oldPreset: result.oldPreset, newPreset: toPreset };
+          }
+          // No artifact yet; fall through to the in-memory + flush path below,
+          // which materializes the empty file using the live cwd.
+        }
+        let oldPreset = liveSession.header?.agentPreset;
+        // SessionStore implementations from older DSH builds may expose the
+        // history as `log` rather than the newer `events` snapshot getter.
+        // Do not dereference `.length` on an absent compatibility surface.
+        const liveEvents = Array.isArray(liveSession.events)
+          ? liveSession.events
+          : Array.isArray(liveSession.log) ? liveSession.log : [];
+        for (let index = liveEvents.length - 1; index >= 0; index -= 1) {
+          const event = liveEvents[index];
+          if (event?.type === "agent-preset/selected" && typeof event.data?.agentPreset === "string") {
+            oldPreset = event.data.agentPreset;
+            break;
+          }
+        }
+        if (oldPreset === toPreset) {
+          return { sessionId, migrated: false, oldPreset, newPreset: toPreset };
+        }
+        if (liveAgent !== void 0 && typeof presets?.recompose === "function" && liveAgent.ctx) {
+            try { await presets.recompose(liveAgent.ctx, toPreset); } catch { /* best-effort */ }
+        }
+        liveSession.append("agent-preset/selected", { agentPreset: toPreset });
+        await ctx.sessions.flush(liveSession);
+        ctx.logger.info(`session-manager: migrated live preset for "${sessionId}" from "${String(oldPreset)}" to "${toPreset}"`);
+        return { sessionId, migrated: true, oldPreset, newPreset: toPreset };
+      }
+
+      // A session absent from SessionStore is cold. If an older plugin left its
+      // exact Session object in the coordinator, retire that proven orphan by
+      // the coordinator's own drain path instead of deleting owner bookkeeping.
+      const coordinator = persistence.coordinator;
+      let tracked = coordinator?.states?.get?.(sessionId);
+      if (tracked?.owner !== void 0 && ctx.sessions.get(sessionId) === void 0) {
+        coordinator.retire?.(tracked.owner);
+        const retirement = coordinator.retirements?.get?.(sessionId);
+        if (retirement !== void 0) await retirement;
+        tracked = coordinator.states?.get?.(sessionId);
+        if (tracked?.owner !== void 0) {
+          throw new Error(`会话 ${sessionId} 仍有未释放的持久化 owner，已停止迁移以保护数据`);
+        }
+      }
+
+      const result = await applyMigrationToArtifact({ sessionId, toPreset, liveSession });
+
+      if (result.migrated) {
+        try { ctx.emit("agent-preset/selected", sessionId, toPreset); } catch { /* best-effort */ }
+        ctx.logger.info(`session-manager: migrated cold preset for "${sessionId}" from "${String(result.oldPreset)}" to "${toPreset}"`);
+      }
+      return result;
+    };
+
+  /* ==== 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. */
+    /**
+     * Encode a session id the way DSH stores it on disk: "--<encoded>--".
+     * Mirrors @deepseek-ai/dsh-session-persistence-jsonl encodeSegment.
+     */
+    const encodeSessionSegment = (id) => {
+      let readable = "";
+      let separatorRun = false;
+      for (let i = 0; i < id.length; i++) {
+        const ch = id[i];
+        const code = id.charCodeAt(i);
+        if (ch === "/" || ch === "\\" || ch === ":") {
+          if (!separatorRun) readable += "-";
+          separatorRun = true;
+        } else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) {
+          readable += ch;
+          separatorRun = false;
+        } else {
+          readable += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+          separatorRun = false;
+        }
+      }
+      return "--" + (readable.replace(/^-+/, "") || "root").slice(0, 251) + "--";
+    };
+    /** Read one session artifact verbatim, falling back to direct disk access when the
+     * configured persistence backend cannot see the id (e.g. an older DSH build
+     * wrote a "session.v2.jsonl.zstd" file under the raw-id directory).
+     */
+    const readSessionArtifact = async (sessionId, signal) => {
+      const persistence = ctx.get("sessionPersistence");
+      if (persistence !== void 0 && typeof persistence.readRaw === "function") {
+        try {
+          const raw = await persistence.readRaw(sessionId, signal);
+          if (raw !== void 0) {
+            const located = typeof persistence.locate === "function" ? persistence.locate(raw.meta) : void 0;
+            // After a cross-workspace move, a backend may return a raw artifact
+            // whose metadata cache still points at the pre-move cwd. Do not
+            // hand that stale path to a mutator; verify it and fall through to
+            // the id-based filesystem scan when it no longer exists.
+            if (located?.path !== void 0) {
+              try {
+                if ((await stat(located.path)).isFile()) {
+                  return { ...raw, path: located.path };
+                }
+              } catch { /* stale locate result; scan the durable files below */ }
+            } else {
+              return { ...raw };
+            }
+          }
+        } catch { /* fall through to direct disk */ }
+      }
+      const dshHomePath = ctx.get("dshHomePath");
+      if (typeof dshHomePath !== "function") return void 0;
+      const root = dshHomePath("sessions");
+      let projects;
+      try { projects = await readdir(root, { withFileTypes: true }); }
+      catch { return void 0; }
+      const encoded = encodeSessionSegment(sessionId);
+      const { createRequire } = await import("node:module"); const require_ = createRequire(import.meta.url); const { zstdDecompressSync } = require_("node:zlib");
+      for (const proj of projects) {
+        if (!proj.isDirectory()) continue;
+        for (const candidate of [encoded, sessionId]) {
+          const dir = join(root, proj.name, candidate);
+          for (const filename of ["session.jsonl.zstd", "session.v2.jsonl.zstd", "session.jsonl"]) {
+            const filePath = join(dir, filename);
+            try {
+              const buf = await readFile(filePath);
+              let content;
+              if (filename.endsWith(".zstd")) {
+                // Node's zstdDecompressSync only decodes the FIRST frame in a
+                // multi-frame file; DSH writes one frame per batch, so a real
+                // artifact contains many concatenated frames and the rest is
+                // otherwise silently lost. Walk every magic-prefixed frame and
+                // concatenate their plaintexts.
+                const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+                const plaintexts = [];
+                let pos = 0;
+                while (pos < buf.length) {
+                  const next = buf.indexOf(ZSTD_MAGIC, pos);
+                  if (next < 0) break;
+                  try {
+                    plaintexts.push(zstdDecompressSync(buf.subarray(next)));
+                  } catch {
+                    break;
+                  }
+                  pos = next + 4;
+                }
+                if (plaintexts.length === 0) continue;
+                content = Buffer.concat(plaintexts).toString("utf8");
+              } else {
+                content = buf.toString("utf8");
+              }
+              const headerLine = content.split("\n", 1)[0];
+              let meta;
+              try { meta = JSON.parse(headerLine); } catch { continue; }
+              if (typeof meta?.id !== "string" || meta.id !== sessionId) continue;
+              return { meta, filename, content, path: filePath };
+            } catch { /* keep scanning */ }
+          }
+        }
+      }
+      return void 0;
+    };
+    /** List every persisted session header visible to the configured persistence
+     * backend, supplemented by raw-id sessions written by older DSH builds. */
+    const listSessionHeaders = async (persistence) => {
+      const seen = new Set();
+      const out = [];
+      if (persistence !== void 0 && typeof persistence.list === "function") {
+        try {
+          for (const header of await persistence.list()) {
+            if (header === void 0 || typeof header.id !== "string") continue;
+            seen.add(header.id);
+            out.push(header);
+          }
+        } catch { /* fall through to disk */ }
+      }
+      const dshHomePath = ctx.get("dshHomePath");
+      if (typeof dshHomePath !== "function") return out;
+      const root = dshHomePath("sessions");
+      let projects;
+      try { projects = await readdir(root, { withFileTypes: true }); }
+      catch { return out; }
+      const { createRequire } = await import("node:module"); const require_ = createRequire(import.meta.url); const { zstdDecompressSync } = require_("node:zlib");
+      for (const proj of projects) {
+        if (!proj.isDirectory()) continue;
+        let dirs;
+        try { dirs = await readdir(join(root, proj.name), { withFileTypes: true }); }
+        catch { continue; }
+        for (const entry of dirs) {
+          if (!entry.isDirectory()) continue;
+          for (const filename of ["session.v2.jsonl.zstd", "session.jsonl.zstd", "session.jsonl"]) {
+            const filePath = join(root, proj.name, entry.name, filename);
+            try {
+              const buf = await readFile(filePath);
+              let content;
+              if (filename.endsWith(".zstd")) {
+                const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+                const plaintexts = [];
+                let pos = 0;
+                while (pos < buf.length) {
+                  const next = buf.indexOf(ZSTD_MAGIC, pos);
+                  if (next < 0) break;
+                  try { plaintexts.push(zstdDecompressSync(buf.subarray(next))); }
+                  catch { break; }
+                  pos = next + 4;
+                }
+                if (plaintexts.length === 0) continue;
+                content = Buffer.concat(plaintexts).toString("utf8");
+              } else {
+                content = buf.toString("utf8");
+              }
+              const headerLine = content.split("\n", 1)[0];
+              const meta = JSON.parse(headerLine);
+              if (typeof meta?.id !== "string" || seen.has(meta.id)) continue;
+              seen.add(meta.id);
+              out.push({ id: meta.id, cwd: meta.cwd, createdAt: meta.createdAt, version: meta.version, origin: meta.origin });
+            } catch { /* skip */ }
+          }
+        }
+      }
+      return out;
+    };
+      const sessionDirOf = async (sessionId) => {
+    const persistence = ctx.get("sessionPersistence");
+    if (persistence !== void 0) {
+      try {
+        const headers = await persistence.list();
+        const meta = headers.find((header) => header.id === sessionId);
+        if (meta !== void 0) {
+          const location = persistence.locate(meta);
+          if (location !== void 0) return dirname(location.path);
+        }
+      } catch { /* fall through to filesystem scan */ }
+    }
+    const dshHomePath = ctx.get("dshHomePath");
+    if (typeof dshHomePath !== "function") return void 0;
+    const root = dshHomePath("sessions");
+    let projects;
+    try { projects = await readdir(root, { withFileTypes: true }); }
+    catch { return void 0; }
+    const encoded = encodeSessionSegment(sessionId);
+    const candidates = [encoded, sessionId];
+    for (const proj of projects) {
+      if (!proj.isDirectory()) continue;
+      for (const candidate of candidates) {
+        const dir = join(root, proj.name, candidate);
+        try {
+          if ((await stat(dir)).isDirectory()) return dir;
+        } catch { /* keep scanning */ }
+      }
+    }
+    return void 0;
+  };
+
+  /**
+   * Delete one session end to end. Returns a summary of what was torn down.
+   * Idempotent-ish: unknown sessions resolve to { ok: true, deleted: false }.
+   */
+  const deleteSession = async (sessionId) => {
+    const session = ctx.sessions.get(sessionId);
+    // 0.1.1-rc.2 throws ApiRemoteSessionNotFound for cold sessions here.
+    let agent;try{agent=ctx.agents.get(sessionId)}catch{agent=void 0}
+
+    if (agent !== void 0) {
+      // Stop any running turn (disposed-kind suppresses re-wake).
+      agent.cancel({ kind: "disposed" });
+      // Quiesce the agent's own fiber (idempotent; bounded in case teardown stalls).
+      if (typeof agent.scope?.dispose === "function") {
+        await Promise.race([agent.scope.dispose(), sleep(3000)]);
+      }
+      // Drop the zombie from the registry so a later session.create/open with
+      // the same id cannot resurrect it.
+      try {
+        ctx.agents.store?.delete?.(sessionId);
+      } 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 {
+        await ctx.sessions.flush(session);
+      } catch { /* best-effort */ }
+      // Detach the session store entry: emits session/disposed, which the
+      // persistence write-path answers with a final drain, and the API proxy
+      // relays as host/session-removed so every connected client drops the row.
+      try {
+        const entry = ctx.sessions.store?.get?.(sessionId);
+        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);
+    await unarchiveSession(sessionId);
+
+    // Physical artifact (session.jsonl / session.jsonl.zstd) + any extras.
+    const dir = await sessionDirOf(sessionId);
+    if (dir !== void 0) {
+      await rm(dir, { recursive: true, force: true });
+    }
+
+    return {
+      ok: true,
+      sessionId,
+      wasLive: session !== void 0 || agent !== void 0,
+      filesRemoved: dir !== void 0
+    };
+  };
+
+  /**
+   * 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 listSessionHeaders(persistence);
+      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,
+    handler: async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const path = url.pathname.startsWith(API_PREFIX)
+          ? url.pathname.slice(API_PREFIX.length) || "/"
+          : "/";
+        let body = {};
+        if (req.method === "POST") {
+          const raw = await readBody(req);
+          if (raw.trim() !== "") {
+            try {
+              body = JSON.parse(raw);
+            } catch {
+              return send(res, 400, { ok: false, error: "请求体不是合法 JSON" });
+            }
+          }
+        }
+        const sessionId = typeof body.sessionId === "string" && body.sessionId.trim() !== ""
+          ? body.sessionId.trim()
+          : null;
+
+        if (req.method === "POST" && path === "/delete") {
+          if (sessionId === null) return send(res, 400, { ok: false, error: "sessionId 必填" });
+          try {
+            const result = await deleteSession(sessionId);
+            return send(res, 200, { ok: true, result });
+          } catch (error) {
+            ctx.logger.warn(`session-manager: delete "${sessionId}" failed: ${String(error)}`);
+            return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
+          }
+        }
+
+        if (req.method === "POST" && path === "/unarchive") {
+          if (sessionId === null) return send(res, 400, { ok: false, error: "sessionId 必填" });
+          try {
+            await unarchiveSession(sessionId);
+            return send(res, 200, { ok: true, result: { sessionId } });
+          } catch (error) {
+            ctx.logger.warn(`session-manager: unarchive "${sessionId}" failed: ${String(error)}`);
+            return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
+          }
+        }
+
+          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)}; type=${error?.constructor?.name}; json=${safeJson(error)}`);
+        return send(res, 500, { ok: false, error: String(error instanceof Error ? error.message : error) });
+      }
+    }  }), "session-manager: http api");
+
+
+}