dsh-session-manager 0.7.0 → 0.7.2

package/lib/index.js

@@ -22,14 +22,13 @@
  * The compatibility adapter normalizes service access and list snapshots.
  * Optional live-writer/coordinator internals are guarded before mutation.
  */
-import { statSync } from "node:fs";
 import { lstat, mkdir, readdir, realpath, rename, rm } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { createAnnotationStore } from "./annotation-store.js";
 import { createWorkspaceArchiveStore, assertWorkspaceId } from "./workspace-archive-store.js";
 import { createDshAdapter, normalizeSessionHeader, compareSemver } from "./compat/dsh-adapter.js";
-import { ARTIFACT_NAMES, assertSessionId, assertSessionDirectory, encodeSessionSegment, parseSessionGenerationFromFilename, readSessionHeader, readSessionFile, writeTempFile, replaceSessionFile } from "./session-files.js";
+import { ARTIFACT_NAMES, assertSessionId, assertSessionDirectory, candidateSessionDirs, encodeFsSessionSegment, decodeFsSessionSegment, encodeProjectSegment, encodeSessionSegment, parseSessionGenerationFromFilename, readSessionHeader, readSessionFile, writeTempFile, replaceSessionFile } from "./session-files.js";
 
 export const name = "dsh-session-manager";
 
@@ -126,10 +125,16 @@ const scanSessionHeaders = async (persistence, dshHome) => {
   }
   const result = () => ({ headers, complete: listed && errors.length === 0, errors });
   // Skip known files before fopen; retain the orphan/raw-id compatibility path.
+  // Only add canonical session directories that do not start and end with "--"
+  // to avoid colliding with legacy projectKey candidates (e.g. "--s1--").
   const knownDirs = new Set();
   for (const id of seen) {
-    knownDirs.add(id);
-    knownDirs.add(encodeSessionSegment(id));
+    try {
+      const canonical = encodeFsSessionSegment(id);
+      if (!canonical.startsWith("--") || !canonical.endsWith("--")) {
+        knownDirs.add(canonical);
+      }
+    } catch (_) {}
   }
   if (typeof dshHome !== "function") return result();
   const root = dshHome("sessions");
@@ -151,7 +156,7 @@ const scanSessionHeaders = async (persistence, dshHome) => {
       for (const filename of ARTIFACT_NAMES) {
         try {
           const header = await readSessionHeader(join(root, proj.name, entry.name, filename));
-          if (![header.id, encodeSessionSegment(header.id)].includes(entry.name)) {
+          if (!candidateSessionDirs(header.id).includes(entry.name)) {
             throw new Error("会话目录与 header id 不一致");
           }
           if (!seen.has(header.id)) { seen.add(header.id); headers.push(header); }
@@ -171,7 +176,7 @@ const listSessionHeaders = async (persistence, dshHome) => (await scanSessionHea
 
 export function apply(ctx) {
   try {
-    const buildId = "dsh-session-manager v0.7.0 (workspace-archive)";
+    const buildId = "dsh-session-manager v0.7.2 (workspace-archive)";
     if (typeof ctx?.logger?.info === "function") ctx.logger.info(buildId);
     else if (typeof console !== "undefined" && console?.info) console.info(buildId);
   } catch (_) { /* ignore logging failures */ }
@@ -200,6 +205,9 @@ export function apply(ctx) {
     }
     return workspaceArchiveStore;
   };
+  const safeGetAgent = (sessionId) => {
+    try { return ctx.agents?.get?.(sessionId); } catch { return undefined; }
+  };
   const assertAnnotatable = id => {
     const registry = adapter.workspaceRegistry;
     if (adapter.getSession(id) !== undefined || registry?.headers?.has?.(id)
@@ -308,7 +316,7 @@ export function apply(ctx) {
 
       if (!stopActivity) {
         const liveSession = ctx.sessions?.get?.(sessionId);
-        const liveAgent = ctx.agents?.get?.(sessionId);
+        const liveAgent = safeGetAgent(sessionId);
         const activeTurn = liveSession?.activeTurn;
         const agentRunning = liveAgent?.status === "running" || liveAgent?.busy === true;
         if (activeTurn !== undefined || agentRunning) {
@@ -380,13 +388,7 @@ export function apply(ctx) {
       const rawIds = Array.isArray(entity.record?.sessionIds)
         ? [...entity.record.sessionIds]
         : [...entity.sessionIds];
-      let selfUpdatedAt = entity.updatedAt ?? entity.record?.updatedAt ?? null;
-      if (selfUpdatedAt === null && entity.path) {
-        try {
-          const st = statSync(entity.path);
-          selfUpdatedAt = st.mtimeMs;
-        } catch (_) {}
-      }
+      const selfUpdatedAt = entity.updatedAt ?? entity.record?.updatedAt ?? null;
       return {
         id: entity.id,
         name: entity.title || entity.id,
@@ -469,6 +471,178 @@ ${rest}`, "utf8");
       return undefined;
     };
 
+    const MAX_BOOT_REFOLD_COUNT = 50;
+    const MAX_BOOT_REFOLD_MS = 2000;
+    const MAX_SINGLE_ARTIFACT_BYTES = 5 * 1024 * 1024; // 5 MB
+
+    const getSessionSizeBytes = async (sessionId, fallbackPath) => {
+      if (typeof adapter.statSession === "function") {
+        try {
+          const stat = await adapter.statSession(sessionId);
+          const size = stat?.sizeBytes ?? stat?.size;
+          if (typeof size === "number") return size;
+        } catch { /* proceed */ }
+      }
+      try {
+        const resolvedPath = fallbackPath ?? (await adapter.resolveSessionPath?.(sessionId));
+        if (typeof resolvedPath === "string") {
+          const fileStat = await lstat(resolvedPath);
+          return fileStat.size;
+        }
+      } catch { /* proceed */ }
+      return undefined;
+    };
+
+    /**
+     * Refold the projection cache for a session using properly decoded/migrated logical events.
+     * Prioritizes the official persistence interface (openSessionRead) to obtain logical events
+     * (expanding packed rows and handling generational migrations). Falls back to disk reading
+     * only when the official interface is unavailable, strictly verifying continuous logical seq
+     * and safe JSON parsing without swallowing corruption. (Issue #32)
+     */
+    const refoldSessionProjection = async ({
+      sessionId,
+      header,
+      movedArtifactRest,
+      isThreeArgCache,
+      cache: cacheParam,
+      liveSession: liveSessionParam,
+      caller = "boot"
+    }) => {
+      const cache = cacheParam ?? (ctx.get("sessionProjectionCache") ?? adapter.projectionCache);
+      if (typeof cache?.coldSnapshot !== "function") return false;
+      const isThreeArg = isThreeArgCache ?? (typeof cache.cachedSnapshot === "function" || cache.coldSnapshot.length >= 3);
+
+      // Check file size budget across all reconstruction paths before any decoding/reading
+      let artifactSize = await getSessionSizeBytes(sessionId);
+      if (typeof movedArtifactRest === "string") {
+        const restBytes = Buffer.byteLength(movedArtifactRest);
+        artifactSize = artifactSize !== undefined ? Math.max(artifactSize, restBytes) : restBytes;
+      }
+      if (artifactSize !== undefined && artifactSize > MAX_SINGLE_ARTIFACT_BYTES) {
+        ctx.logger.info(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for large artifact "${sessionId}" (${artifactSize} bytes)`);
+        return false;
+      }
+
+      let events = null;
+      let inheritedEventCount = undefined;
+      let effectiveHeader = header;
+
+      // Priority 1: Official persistence handle via adapter.openSessionRead
+      const hasOfficialReader = typeof adapter.persistence?.open === "function";
+
+      if (hasOfficialReader) {
+        let handle = null;
+        try {
+          handle = await adapter.openSessionRead(sessionId);
+          if (handle && typeof handle.read === "function") {
+            try {
+              const readResult = await handle.read(0);
+              const handleEvents = Array.isArray(readResult) ? readResult : readResult?.events;
+              if (Array.isArray(handleEvents)) {
+                // Verify all events are contiguous logical events
+                if (handleEvents.length === 0 || handleEvents.every((e, idx) => e && typeof e === "object" && e.seq === idx)) {
+                  events = handleEvents;
+                  inheritedEventCount = handle.inheritedEventCount;
+                  if (handle.header && typeof handle.header === "object") {
+                    effectiveHeader = { ...effectiveHeader, ...handle.header };
+                  }
+                } else {
+                  ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": official handle returned non-contiguous logical events`);
+                  return false;
+                }
+              } else {
+                ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": official handle returned empty or invalid events`);
+                return false;
+              }
+            } catch (readErr) {
+              ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": official read/migration failed: ${safeErrorMessage(readErr)}`);
+              return false;
+            }
+          }
+        } catch (err) {
+          const msg = safeErrorMessage(err);
+          if (!msg.includes("unavailable")) {
+            ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": official read/migration failed: ${msg}`);
+            return false;
+          }
+        } finally {
+          if (typeof handle?.close === "function") {
+            try { await handle.close(); } catch { /* best-effort */ }
+          }
+        }
+      }
+
+      // Priority 2: Fallback to reading disk artifact or moved rest ONLY when official API is unavailable or handle lacks read
+      if (events === null) {
+        let rest = movedArtifactRest;
+        if (typeof rest !== "string") {
+          const raw = await readSessionArtifact(sessionId, undefined, { storedHeader: effectiveHeader });
+          if (!raw || typeof raw.content !== "string") return false;
+          const newlineAt = raw.content.indexOf("\n");
+          rest = newlineAt === -1 ? "" : raw.content.slice(newlineAt + 1);
+        }
+
+        if (typeof rest === "string" && rest.length > 0) {
+          const rawEvents = [];
+          let parseFailed = false;
+          for (const line of rest.split("\n")) {
+            if (!line.trim()) continue;
+            try {
+              rawEvents.push(JSON.parse(line));
+            } catch {
+              parseFailed = true;
+              break;
+            }
+          }
+
+          if (parseFailed) {
+            ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": JSON parse error in artifact events`);
+            return false;
+          }
+
+          // Strictly check that all rows are contiguous logical events with valid seq starting at 0.
+          // Physical rows without seq (like packed tool-call-chunks) MUST NOT be passed to coldSnapshot.
+          const isContiguous = rawEvents.length === 0 || rawEvents.every((e, idx) => e && typeof e === "object" && e.seq === idx);
+          if (!isContiguous) {
+            ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for "${sessionId}": physical rows cannot be restored as logical events without official migration`);
+            return false;
+          }
+
+          events = rawEvents;
+          inheritedEventCount = await resolveInheritedEventCount({
+            sessionId,
+            header: effectiveHeader,
+            events,
+            persistence: adapter.persistence,
+            liveSession: liveSessionParam ?? adapter.getSession(sessionId)
+          });
+        }
+      }
+
+      if (events !== null) {
+        if (effectiveHeader?.isSeeded && inheritedEventCount === undefined) {
+          ctx.logger.warn(`session-manager: skipping ${caller === "post-move" ? "post-move cache refresh" : "cache refold"} for seeded session "${sessionId}": cannot determine inheritedEventCount`);
+          return false;
+        }
+        if (isThreeArg) {
+          await cache.coldSnapshot(effectiveHeader, inheritedEventCount, events);
+        } else {
+          try {
+            await cache.coldSnapshot(effectiveHeader.id);
+          } catch (error) {
+            if (String(error).includes("SessionLogOffset") && effectiveHeader) {
+              await cache.coldSnapshot(effectiveHeader, inheritedEventCount, events);
+            } else {
+              throw error;
+            }
+          }
+        }
+        return true;
+      }
+      return false;
+    };
+
     /**
      * TRUE cross-workspace move. See the module docstring for the full design:
      * re-home the stored cwd, migrate the artifact, then swap accounting.
@@ -587,17 +761,13 @@ ${rest}`, "utf8");
         if (typeof oldPath !== "string" || newLocation === void 0) {
           throw new Error("持久化后端无法定位会话工件路径");
         }
-        const newPath = newLocation.path;
-        // Keep the stored generation in sync with the filename selected by
-        // persistence.locate(). persistence.locate() always returns the
-        // SESSION_FORMAT_VERSION path (DSH 0.1.7+ ships v4 by default),
-        // regardless of oldHeader.version. Without the stamp below, the
-        // rewritten file is `session.v4.jsonl.zstd` carrying a v0/v3 header,
-        // which JsonlSessionPersistence.listArtifacts rejects on the next
-        // startup (`session generation filename identifies v4, but its
-        // header identifies v0`), breaking persistence.list() and crashing
-        // the workspace registry while it boots. (issue #18)
-        const expectedVersion = parseSessionGenerationFromFilename(basename(newPath));
+        // For live sessions, the active writer targets the latest generation returned by persistence.locate().
+        // For cold sessions, preserve the source artifact's filename and generation to avoid producing an
+        // artifact claiming a newer format version without its event contents being migrated. (Issue #32)
+        const targetFilename = liveSession !== void 0 ? basename(newLocation.path) : (raw.filename ?? basename(oldPath));
+        const targetDir = dirname(newLocation.path);
+        const newPath = join(targetDir, targetFilename);
+        const expectedVersion = parseSessionGenerationFromFilename(targetFilename);
         if (typeof expectedVersion === "number") newHeader.version = expectedVersion;
         const root = typeof dshHomePath === "function" ? dshHomePath("sessions") : undefined;
         await assertSessionDirectory(root, dirname(oldPath), sessionId);
@@ -727,36 +897,15 @@ ${rest}`, "utf8");
       if (cache !== void 0 && typeof cache.coldSnapshot === "function") {
         try {
           const isThreeArg = typeof cache.cachedSnapshot === "function" || cache.coldSnapshot.length >= 3;
-          const header = movedArtifact?.header;
-          const events = [];
-          if (typeof movedArtifact?.rest === "string") {
-            for (const line of movedArtifact.rest.split("\n")) {
-              if (!line.trim()) continue;
-              try { events.push(JSON.parse(line)); } catch { /* ignore torn line */ }
-            }
-          }
-          const inheritedEventCount = await resolveInheritedEventCount({
+          await refoldSessionProjection({
             sessionId,
-            header,
-            events,
-            persistence,
-            liveSession
+            header: movedArtifact?.header,
+            movedArtifactRest: movedArtifact?.rest,
+            isThreeArgCache: isThreeArg,
+            cache,
+            liveSession,
+            caller: "post-move"
           });
-          if (header?.isSeeded && inheritedEventCount === undefined) {
-            ctx.logger.warn(`session-manager: skipping post-move cache refresh for seeded session "${sessionId}": cannot determine inheritedEventCount`);
-          } else if (isThreeArg) {
-            await cache.coldSnapshot(header, inheritedEventCount, events);
-          } else {
-            try {
-              await cache.coldSnapshot(sessionId);
-            } catch (error) {
-              if (String(error).includes("SessionLogOffset") && header) {
-                await cache.coldSnapshot(header, inheritedEventCount, events);
-              } else {
-                throw error;
-              }
-            }
-          }
         } catch (error) {
           ctx.logger.warn(`session-manager: post-move cache refresh failed for "${sessionId}": ${String(error)}`);
         }
@@ -1109,14 +1258,19 @@ ${rest}`, "utf8");
       catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
       for (const proj of projects) {
         if (!proj.isDirectory() || proj.isSymbolicLink()) continue;
-        for (const candidate of [encodeSessionSegment(sessionId), sessionId]) {
+        for (const candidate of candidateSessionDirs(sessionId)) {
           const dir = join(root, proj.name, candidate);
           try { await assertSessionDirectory(root, dir, sessionId); }
           catch (error) { if (error.code === "ENOENT") continue; throw error; }
           for (const filename of ARTIFACT_NAMES) {
             try {
               const artifact = await read(join(dir, filename));
-              if (artifact.meta.id !== sessionId) throw new Error("会话工件 header id 与请求不一致");
+              if (artifact.meta.id !== sessionId) {
+                if (candidate === candidateSessionDirs(sessionId)[0]) {
+                  throw new Error("会话工件 header id 与请求不一致");
+                }
+                break;
+              }
               return artifact;
             } catch (error) { if (error.code !== "ENOENT") throw error; }
           }
@@ -1125,98 +1279,326 @@ ${rest}`, "utf8");
       return undefined;
     };
 
-  const sessionDirOf = async (sessionId) => {
+  const sessionDirOf = async (sessionId, storedHeader) => {
     // Require a matching artifact header instead of deleting an arbitrary
     // directory merely because its name matches user input.
-    const artifact = await readSessionArtifact(sessionId, undefined, { headerOnly: true });
+    const artifact = await readSessionArtifact(sessionId, undefined, { headerOnly: true, storedHeader });
     return artifact === undefined ? undefined : dirname(artifact.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 }.
+   * Enumerate all descendant subagent session headers for one or more root session IDs.
+   * Recursively traverses subagent relations (origin === "subagent" && parentSession === parentId).
+   * Normal fork sessions (origin !== "subagent") are strictly ignored.
+   * Only returns verified local sessions with valid directories or live runtime state.
    */
-  const deleteSession = async (sessionId) => {
-    assertSessionId(sessionId);
-    // Resolve/validate before cancelling the agent or changing registry state.
-    let dir = await sessionDirOf(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 */ }
+  const findDescendantSubagents = async (rootSessionIds) => {
+    const roots = Array.from(new Set((rootSessionIds || []).filter(id => typeof id === "string" && id.trim() !== "")));
+    if (roots.length === 0) return [];
+    for (const id of roots) assertSessionId(id);
+
+    const headerMap = new Map();
+    try {
+      const cached = adapter.cachedSessionHeaders?.();
+      if (Array.isArray(cached)) {
+        for (const h of cached) if (h?.id) headerMap.set(h.id, h);
+      }
+    } catch { /* proceed */ }
+
+    try {
+      const live = adapter.sessions?.list?.();
+      if (Array.isArray(live)) {
+        for (const s of live) if (s?.header?.id) headerMap.set(s.header.id, s.header);
+      }
+    } catch { /* proceed */ }
+
+    const scanResult = await scanSessionHeaders(adapter.persistence, adapter.homePath);
+    if (!scanResult || !scanResult.complete || (Array.isArray(scanResult.errors) && scanResult.errors.length > 0)) {
+      const errSummary = (scanResult?.errors || []).map(safeErrorMessage).join("; ") || "扫描未完成";
+      throw new Error("扫描子智能体会话失败 (元数据不完整): " + errSummary);
+    }
+    if (Array.isArray(scanResult.headers)) {
+      for (const h of scanResult.headers) {
+        if (h?.id) {
+          headerMap.set(h.id, { ...(headerMap.get(h.id) || {}), ...h });
+        }
+      }
     }
 
-    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;
+    const allHeaders = [...headerMap.values()];
+    const visited = new Set(roots);
+    const descendants = [];
+    let currentParents = new Set(roots);
+
+    while (currentParents.size > 0) {
+      const nextParents = new Set();
+      for (const header of allHeaders) {
+        if (!header || !header.id || !header.parentSession) continue;
+        if (header.origin === "subagent" && currentParents.has(header.parentSession)) {
+          if (!visited.has(header.id)) {
+            visited.add(header.id);
+            nextParents.add(header.id);
+            descendants.push(header);
+          }
         }
-      } catch { /* best-effort */ }
+      }
+      currentParents = nextParents;
     }
-    // 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) {
+
+    const verifiedDescendants = [];
+    for (const sub of descendants) {
+      assertSessionId(sub.id);
+      const dir = await sessionDirOf(sub.id, sub);
+      const isLive = ctx.sessions?.get?.(sub.id) !== undefined || safeGetAgent(sub.id) !== undefined;
+      if (dir !== undefined || isLive) {
+        verifiedDescendants.push({ ...sub, dir });
+      }
+    }
+
+    return verifiedDescendants;
+  };
+
+  /**
+   * Safety check and activity stop for a session before deletion.
+   * If running, attempts safe stop via cancel, dispose, and activity stop interfaces.
+   * If it cannot be safely stopped, rejects deletion.
+   */
+  const assertAndStopActiveSession = async (sessionId, isSubagent = false) => {
+    assertSessionId(sessionId);
+    const liveSession = ctx.sessions?.get?.(sessionId);
+    const liveAgent = safeGetAgent(sessionId);
+
+    const activeTurn = liveSession?.activeTurn;
+    const agentRunning = liveAgent?.status === "running" || liveAgent?.busy === true;
+    let waterfallActivities = [];
+    if (typeof ctx.waterfall === "function") {
       try {
-        ctx.emit("session/disposed", { id: sessionId });
-      } catch (_) { /* best-effort */ }
+        waterfallActivities = await ctx.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]));
+      } catch (err) {
+        throw new Error(`无法检查会话 '${sessionId}' 的活动状态: ${safeErrorMessage(err)}`);
+      }
     }
 
-    // A blank live session may have materialized its first artifact during
-    // flush/retirement. Re-resolve after teardown rather than leaking that file.
-    dir = await sessionDirOf(sessionId);
+    const isActive = activeTurn !== undefined || agentRunning || (Array.isArray(waterfallActivities) && waterfallActivities.length > 0);
+    if (!isActive) return;
 
-    // Workspace accounting + archive-set membership.
-    await detachFromWorkspaces(sessionId);
-    await unarchiveSession(sessionId);
+    const registry = ctx.get("workspaceRegistry") ?? ctx.workspaceRegistry ?? adapter.workspaceRegistry;
+    const hasAgent = liveAgent !== void 0;
+    const hasStopFn = typeof registry?.stopSessionActivity === "function" || typeof ctx.parallel === "function" || typeof liveAgent?.cancel === "function";
 
-    // Physical artifact (session.jsonl / session.jsonl.zstd) + any extras.
-    if (dir !== void 0) {
-      await assertSessionDirectory(adapter.homePath("sessions"), dir, sessionId);
-      await rm(dir, { recursive: true, force: true });
+    if (!hasStopFn) {
+      const label = isSubagent ? `子智能体 '${sessionId}'` : `会话 '${sessionId}'`;
+      throw new Error(`无法安全停止运行中的${label}: 没有可用的停止接口`);
     }
 
-    let warning;
-    try { await annotations().remove(sessionId); }
-    catch (error) {
-      warning = "会话已删除，但独立标记清理失败: " + safeErrorMessage(error);
-      ctx.logger.warn("session-manager: " + warning);
+    if (hasAgent) {
+      if (typeof liveAgent.cancel === "function") {
+        liveAgent.cancel({ kind: "disposed" });
+      }
+      if (typeof liveAgent.scope?.dispose === "function") {
+        await Promise.race([liveAgent.scope.dispose(), sleep(3000)]);
+      }
+    }
+
+    if (typeof registry?.stopSessionActivity === "function") {
+      try { await registry.stopSessionActivity(sessionId); }
+      catch (err) {
+        throw new Error(`停止会话 '${sessionId}' 活动失败: ${safeErrorMessage(err)}`);
+      }
+    } else if (typeof ctx.parallel === "function") {
+      try { await ctx.parallel("workspace/session-stop", { sessionId }); }
+      catch (err) {
+        throw new Error(`停止会话 '${sessionId}' 活动失败: ${safeErrorMessage(err)}`);
+      }
+    }
+
+    const postAgent = safeGetAgent(sessionId);
+    if (postAgent?.status === "running" || postAgent?.busy === true) {
+      const label = isSubagent ? `子智能体 '${sessionId}'` : `会话 '${sessionId}'`;
+      throw new Error(`${label} 仍在运行中，无法安全停止`);
+    }
+  };
+
+  /**
+   * Delete one session end to end. Returns a summary of what was torn down.
+   * Recursively cascades to all descendant subagents (origin === "subagent").
+   * Idempotent-ish: unknown sessions resolve to { ok: true, deleted: false }.
+   */
+  const deleteSession = async (sessionId, options = {}) => {
+    assertSessionId(sessionId);
+
+    let deletedSubagentIds = [];
+    const cleanupWarnings = [];
+
+    if (!options.skipSubagents) {
+      // 1. Discover all descendant subagents (verifying scan completeness)
+      const descendants = await findDescendantSubagents([sessionId]);
+
+      // 2. Pre-delete validation for BOTH main session and all descendants BEFORE any deletion
+      // 2.1 Identity validation
+      assertSessionId(sessionId);
+      for (const sub of descendants) {
+        assertSessionId(sub.id);
+      }
+
+      // 2.2 Directory validation (prevent traversal / outside directory issues)
+      const mainDir = await sessionDirOf(sessionId);
+      if (mainDir !== undefined) {
+        await assertSessionDirectory(adapter.homePath("sessions"), mainDir, sessionId);
+      }
+      for (const sub of descendants) {
+        const subDir = sub.dir ?? (await sessionDirOf(sub.id, sub));
+        if (subDir !== undefined) {
+          await assertSessionDirectory(adapter.homePath("sessions"), subDir, sub.id);
+        }
+      }
+
+      // 2.3 Activity validation and safe stop
+      for (const sub of descendants) {
+        await assertAndStopActiveSession(sub.id, true);
+      }
+      await assertAndStopActiveSession(sessionId, false);
+
+      // 3. Deletion order: descendant-first (reverse), parent-last
+      const deletePlan = [...descendants].reverse();
+      const remainingSubagentIds = descendants.map(d => d.id);
+
+      for (const sub of deletePlan) {
+        try {
+          const subResult = await mutate(sub.id, async () => {
+            return await deleteSession(sub.id, { skipSubagents: true });
+          });
+          deletedSubagentIds.push(sub.id);
+          const rIdx = remainingSubagentIds.indexOf(sub.id);
+          if (rIdx !== -1) remainingSubagentIds.splice(rIdx, 1);
+
+          if (Array.isArray(subResult?.warnings)) {
+            cleanupWarnings.push(...subResult.warnings);
+          } else if (subResult?.warning) {
+            cleanupWarnings.push(subResult.warning);
+          }
+
+          try {
+            await workspaceArchives().removeSession(sub.id);
+          } catch (archErr) {
+            cleanupWarnings.push(`子智能体 '${sub.id}' 归档记录清理失败: ${safeErrorMessage(archErr)}`);
+          }
+        } catch (subErr) {
+          const err = new Error(`删除子智能体 '${sub.id}' 失败: ${safeErrorMessage(subErr)}`);
+          err.deletedSubagentIds = [...deletedSubagentIds];
+          err.remainingSessionIds = [sessionId, ...remainingSubagentIds];
+          err.partialFailure = deletedSubagentIds.length > 0;
+          if (subErr?.code) err.code = subErr.code;
+          throw err;
+        }
+      }
+    } else {
+      await assertAndStopActiveSession(sessionId, true);
+    }
+
+    try {
+      // Resolve/validate before cancelling the agent or changing registry state.
+      let dir = await sessionDirOf(sessionId);
+      const session = ctx.sessions?.get?.(sessionId);
+      let agent = safeGetAgent(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 */ }
+      }
+
+      // A blank live session may have materialized its first artifact during
+      // flush/retirement. Re-resolve after teardown rather than leaking that file.
+      dir = await sessionDirOf(sessionId);
+
+      // Workspace accounting + archive-set membership.
+      await detachFromWorkspaces(sessionId);
+      await unarchiveSession(sessionId);
+
+      // Physical artifact (session.jsonl / session.jsonl.zstd) + any extras.
+      if (dir !== void 0) {
+        await assertSessionDirectory(adapter.homePath("sessions"), dir, sessionId);
+        await rm(dir, { recursive: true, force: true });
+      }
+
+      try {
+        await annotations().remove(sessionId);
+      } catch (error) {
+        const warn = "会话已删除，但独立标记清理失败: " + safeErrorMessage(error);
+        cleanupWarnings.push(warn);
+        ctx.logger.warn("session-manager: " + warn);
+      }
+
+      try {
+        await workspaceArchives().removeSession(sessionId);
+      } catch (error) {
+        const warn = "会话已删除，但工作区归档记录清理失败: " + safeErrorMessage(error);
+        cleanupWarnings.push(warn);
+        ctx.logger.warn("session-manager: " + warn);
+      }
+
+      const aggregatedWarning = cleanupWarnings.length > 0 ? cleanupWarnings.join("; ") : undefined;
+
+      return {
+        ok: true,
+        ...(aggregatedWarning ? { warning: aggregatedWarning, warnings: cleanupWarnings } : {}),
+        sessionId,
+        wasLive: session !== void 0 || agent !== void 0,
+        filesRemoved: dir !== void 0,
+        deletedSubagents: deletedSubagentIds,
+        subagentCount: deletedSubagentIds.length
+      };
+    } catch (parentErr) {
+      const err = deletedSubagentIds.length > 0
+        ? new Error(`删除主会话 '${sessionId}' 失败: ${safeErrorMessage(parentErr)}`)
+        : parentErr;
+      err.deletedSubagentIds = [...deletedSubagentIds];
+      err.remainingSessionIds = [sessionId];
+      err.partialFailure = deletedSubagentIds.length > 0;
+      if (parentErr?.code && err !== parentErr) err.code = parentErr.code;
+      throw err;
     }
-    return {
-      ok: true,
-      ...(warning ? { warning } : {}),
-      sessionId,
-      wasLive: session !== void 0 || agent !== void 0,
-      filesRemoved: dir !== void 0
-    };
   };
 
   /**
@@ -1230,11 +1612,20 @@ ${rest}`, "utf8");
    * pass-through refold, and a stale one triggers the unrelated-identity
    * full re-read path.
    */
+  /**
+   * On plugin boot:
+   * 1. Reconcile workspace session membership using header metadata only.
+   *    This step is fast, safe, and completely separated from projection cache refolding. (Issue #32)
+   * 2. Perform a budgeted background projection cache sweep for missing cache records,
+   *    prioritizing sessions in active workspaces, yielding to the event loop, and
+   *    safely skipping unmigrated physical rows or corrupt artifacts. (Issue #32)
+   */
   ctx.effect(async () => {
     const cache = adapter.projectionCache;
     const persistence = adapter.persistence;
     const registry = adapter.workspaceRegistry;
-    if (typeof cache?.coldSnapshot !== "function" || typeof persistence?.list !== "function" || typeof registry?.list !== "function") return;
+    if (typeof persistence?.list !== "function" || typeof registry?.list !== "function") return;
+
     try {
       // Remember only ids that existed before the async scan. Concurrently
       // attached ids must never be removed using this older disk snapshot.
@@ -1246,55 +1637,10 @@ ${rest}`, "utf8");
       }
       const headers = scan.headers;
       const validIds = new Set(headers.map(header => header.id));
-      const isThreeArgCache = typeof cache.cachedSnapshot === "function" || cache.coldSnapshot.length >= 3;
-      if (isThreeArgCache) {
-        for (const header of headers) {
-          try {
-            // Fast path: cachedSnapshot performs an in-memory lifecycle check (formatVersion, cwd, createdAt, isSeeded).
-            // If the cache record is already present and matches, skip disk I/O and projection fold.
-            if (typeof cache.cachedSnapshot === "function" && cache.cachedSnapshot(header) !== undefined) {
-              continue;
-            }
-            const raw = await readSessionArtifact(header.id, undefined, { storedHeader: header });
-            if (!raw || typeof raw.content !== "string") continue;
-            const newlineAt = raw.content.indexOf("\n");
-            const rest = newlineAt === -1 ? "" : raw.content.slice(newlineAt + 1);
-            const events = [];
-            if (rest) {
-              for (const line of rest.split("\n")) {
-                if (!line.trim()) continue;
-                try { events.push(JSON.parse(line)); } catch { /* ignore torn line */ }
-              }
-            }
-            const inheritedEventCount = await resolveInheritedEventCount({
-              sessionId: header.id,
-              header,
-              events,
-              persistence,
-              liveSession: adapter.getSession(header.id)
-            });
-            if (header.isSeeded && inheritedEventCount === undefined) {
-              ctx.logger.warn('session-manager: skipping cache refold for seeded session "' + header.id + '": cannot determine inheritedEventCount');
-              continue;
-            }
-            await cache.coldSnapshot(header, inheritedEventCount, events);
-          } catch (error) {
-            ctx.logger.warn('session-manager: post-boot cache refold failed for "' + header.id + '": ' + safeErrorMessage(error));
-          }
-        }
-      } else {
-        for (const header of headers) {
-          try { await cache.coldSnapshot(header.id); }
-          catch (error) {
-            if (String(error).includes("SessionLogOffset")) break;
-            ctx.logger.warn('session-manager: post-boot cache refold failed: ' + safeErrorMessage(error));
-          }
-        }
-      }
+
+      // Step 1: Immediate Workspace Member Reconciliation (isolated from projection rebuild)
       let removed = 0;
       let added = 0;
-      // Read current state *inside* its queue, and publish an immutable copy.
-      // A failed setState must not mutate the registry's live state object.
       await registry.enqueueOperation(async () => {
         const state = registry.requireState();
         const pathById = new Map(registry.list().map(ws => [ws.id, ws.path]));
@@ -1316,9 +1662,68 @@ ${rest}`, "utf8");
         });
         if (removed || added) await registry.setState({ ...state, workspaces });
       });
-      if (removed || added) ctx.logger.info('session-manager: post-boot workspace reconcile removed ' + removed + ' orphans, attached ' + added + ' disk-only sessions');
+      if (removed || added) {
+        ctx.logger.info('session-manager: post-boot workspace reconcile removed ' + removed + ' orphans, attached ' + added + ' disk-only sessions');
+      }
+
+      // Step 2: Budgeted Background Projection Cache Rebuild
+      if (typeof cache?.coldSnapshot !== "function") return;
+      const isThreeArgCache = typeof cache.cachedSnapshot === "function" || cache.coldSnapshot.length >= 3;
+
+      const assignedIds = new Set(registry.list().flatMap(ws => ws.record?.sessionIds ?? []));
+      const candidates = headers.filter(header => assignedIds.has(header.id) || headers.length <= MAX_BOOT_REFOLD_COUNT);
+
+      const startTime = Date.now();
+      let attemptedCount = 0;
+      let refoldCount = 0;
+
+      for (const header of candidates) {
+        if (attemptedCount >= MAX_BOOT_REFOLD_COUNT || Date.now() - startTime > MAX_BOOT_REFOLD_MS) {
+          ctx.logger.info(`session-manager: boot projection cache refold budget reached (${attemptedCount} attempted, ${refoldCount} refolded, ${candidates.length - attemptedCount} remaining deferred)`);
+          break;
+        }
+
+        try {
+          if (typeof cache.cachedSnapshot === "function" && cache.cachedSnapshot(header) !== undefined) {
+            continue;
+          }
+
+          attemptedCount++;
+
+          // Check file size budget before any I/O
+          const size = await getSessionSizeBytes(header.id);
+          if (typeof size === "number" && size > MAX_SINGLE_ARTIFACT_BYTES) {
+            ctx.logger.info(`session-manager: skipping boot cache refold for large artifact "${header.id}" (${size} bytes)`);
+            continue;
+          }
+
+          // Yield to event loop between sessions so other tasks/HTTP requests stay responsive
+          await new Promise(resolve => setImmediate(resolve));
+
+          if (!isThreeArgCache) {
+            try {
+              await cache.coldSnapshot(header.id);
+              refoldCount++;
+            } catch (error) {
+              if (String(error).includes("SessionLogOffset")) break;
+              ctx.logger.warn('session-manager: post-boot cache refold failed: ' + safeErrorMessage(error));
+            }
+            continue;
+          }
+
+          const ok = await refoldSessionProjection({
+            sessionId: header.id,
+            header,
+            isThreeArgCache,
+            cache
+          });
+          if (ok) refoldCount++;
+        } catch (error) {
+          ctx.logger.warn('session-manager: post-boot cache refold failed for "' + header.id + '": ' + safeErrorMessage(error));
+        }
+      }
     } catch (error) {
-      ctx.logger.warn('session-manager: post-boot reconcile failed: ' + safeErrorMessage(error));
+      ctx.logger.warn("session-manager: post-boot reconcile failed: " + safeErrorMessage(error));
     }
   }, "session-manager: post-boot re-fold stale projection cache rows");
 
@@ -1419,8 +1824,20 @@ ${rest}`, "utf8");
           assertSessionId(sessionId);
           let result;
           if (path === "/delete") {
-            result = await mutate(sessionId, () => deleteSession(sessionId));
-            try { await workspaceArchives().removeSession(sessionId); } catch (_) {}
+            try {
+              result = await mutate(sessionId, () => deleteSession(sessionId));
+              try { await workspaceArchives().removeSession(sessionId); } catch (_) {}
+            } catch (delErr) {
+              const status = delErr?.code === "bad-request" ? 400 : 500;
+              return send(res, status, {
+                ok: false,
+                error: safeErrorMessage(delErr),
+                ...(typeof delErr?.code === "string" ? { code: delErr.code } : {}),
+                deletedSubagents: Array.isArray(delErr?.deletedSubagentIds) ? delErr.deletedSubagentIds : [],
+                remainingSessions: Array.isArray(delErr?.remainingSessionIds) ? delErr.remainingSessionIds : [sessionId],
+                partialFailure: Boolean(delErr?.partialFailure)
+              });
+            }
           } else if (path === "/unarchive") {
             await mutate(sessionId, () => unarchiveSession(sessionId));
             result = { sessionId };
@@ -1492,21 +1909,66 @@ ${rest}`, "utf8");
           if (!BATCH_ACTIONS.has(rawAction)) return send(res, 400, { ok: false, error: "action 不支持: " + rawAction, code: "bad-request" });
           const items = [];
           let success = 0, failed = 0, skipped = 0;
-          for (const sessionId of ids) {
-            try {
-              await runBatchAction({ action: rawAction, sessionId, payload, mutate, deleteSession, unarchiveSession, moveSession, migratePreset, adapter });
-              items.push({ sessionId, status: "success" });
-              success++;
-            } catch (error) {
-              const code = error && typeof error.code === "string" ? error.code : undefined;
-              if (code === "subagent-skip" || code === "blank-skip") {
-                items.push({ sessionId, status: "skipped", reason: code });
-                skipped++;
-              } else {
-                items.push({ sessionId, status: "failed", code, error: safeErrorMessage(error) });
+          if (rawAction === "delete") {
+            const deletedSet = new Set();
+            for (const sessionId of ids) {
+              if (deletedSet.has(sessionId)) {
+                items.push({ sessionId, status: "success", cascaded: true, subagentCount: 0 });
+                success++;
+                continue;
+              }
+              try {
+                const res = await mutate(sessionId, () => deleteSession(sessionId));
+                deletedSet.add(sessionId);
+                if (Array.isArray(res?.deletedSubagents)) {
+                  for (const subId of res.deletedSubagents) {
+                    deletedSet.add(subId);
+                  }
+                }
+                items.push({
+                  sessionId,
+                  status: "success",
+                  deletedSubagents: res?.deletedSubagents || [],
+                  subagentCount: res?.subagentCount || 0,
+                  warnings: res?.warnings || (res?.warning ? [res.warning] : [])
+                });
+                success++;
+              } catch (error) {
+                const code = error && typeof error.code === "string" ? error.code : undefined;
+                if (Array.isArray(error?.deletedSubagentIds)) {
+                  for (const subId of error.deletedSubagentIds) {
+                    deletedSet.add(subId);
+                  }
+                }
+                items.push({
+                  sessionId,
+                  status: "failed",
+                  code,
+                  error: safeErrorMessage(error),
+                  deletedSubagents: error?.deletedSubagentIds || [],
+                  remainingSessions: error?.remainingSessionIds || [sessionId],
+                  partialFailure: Boolean(error?.partialFailure)
+                });
                 failed++;
               }
             }
+          } else {
+            for (const sessionId of ids) {
+              try {
+                await runBatchAction({ action: rawAction, sessionId, payload, mutate, deleteSession, unarchiveSession, moveSession, migratePreset, adapter });
+                items.push({ sessionId, status: "success" });
+                success++;
+              } catch (error) {
+                const code = error && typeof error.code === "string" ? error.code : undefined;
+                if (code === "subagent-skip" || code === "blank-skip") {
+                  items.push({ sessionId, status: "skipped", reason: code });
+                  skipped++;
+                } else {
+                  items.push({ sessionId, status: "failed", code, error: safeErrorMessage(error) });
+                  failed++;
+                }
+              }
+            }
           }
           return send(res, 200, { ok: true, result: {
             summary: { total: ids.length, success, failed, skipped },
@@ -1514,14 +1976,41 @@ ${rest}`, "utf8");
             aborted: false,
           } });
         }
+        if (req.method === "GET" && path === "/delete-preview") {
+          const rawId = url.searchParams.get("sessionId") || "";
+          const sessionId = rawId.trim();
+          if (sessionId) assertSessionId(sessionId);
+          const rawIds = url.searchParams.get("sessionIds");
+          let sessionIds = sessionId ? [sessionId] : [];
+          if (rawIds) {
+            const split = rawIds.split(",").map(s => s.trim()).filter(Boolean);
+            for (const id of split) assertSessionId(id);
+            sessionIds = Array.from(new Set([...sessionIds, ...split]));
+          }
+          if (sessionIds.length === 0) {
+            return send(res, 400, { ok: false, error: "sessionId 或 sessionIds 必填" });
+          }
+          try {
+            const descendants = await findDescendantSubagents(sessionIds);
+            return send(res, 200, {
+              ok: true,
+              result: {
+                subagentCount: descendants.length,
+                subagents: descendants.map(d => ({ id: d.id, parentSession: d.parentSession }))
+              }
+            });
+          } catch (err) {
+            return send(res, 500, { ok: false, error: safeErrorMessage(err) });
+          }
+        }
         if (req.method === "GET" && path === "/workspaces") {
           const cachedHeaders = adapter.cachedSessionHeaders();
           const sessionCreatedAt = Object.fromEntries(cachedHeaders
             .filter(header => typeof header.createdAt === "number" || typeof header.createdAt === "string")
             .map(header => [header.id, header.createdAt]));
           const sessionUpdatedAt = Object.fromEntries(cachedHeaders
-            .filter(header => header && (typeof header.updatedAt === "number" || typeof header.updatedAt === "string" || typeof header.lastModified === "number" || typeof header.mtime === "number"))
-            .map(header => [header.id, header.updatedAt ?? header.lastModified ?? header.mtime]));
+            .filter(header => header && (typeof header.updatedAt === "number" || typeof header.updatedAt === "string" || typeof header.lastModified === "number"))
+            .map(header => [header.id, header.updatedAt ?? header.lastModified]));
           let workspaceArchivesMap = {};
           try {
             workspaceArchivesMap = await workspaceArchives().getAll();
@@ -1535,7 +2024,7 @@ ${rest}`, "utf8");
           return send(res, 200, { ok: true, result });
         }
         if (req.method === "GET" && path === "/update/check") {
-          const currentVersion = adapter.pluginVersion() || "0.7.0";
+          const currentVersion = adapter.pluginVersion() || "0.7.2";
           let latestVersion = currentVersion;
           let hasUpdate = false;
           try {
@@ -1620,10 +2109,17 @@ ${rest}`, "utf8");
         const status = error?.code === "bad-request" ? 400 : error?.code === "body-too-large" ? 413
           : error?.code === "annotation-conflict" || error?.code === "annotations-busy" ? 409
           : error?.code === "session-not-found" ? 404 : error?.code?.startsWith("annotations-") ? 503 : 500;
-        return send(res, status, { ok: false, error: safeErrorMessage(error), ...(typeof error?.code === "string" ? { code: error.code } : {}) });
+        return send(res, status, {
+          ok: false,
+          error: safeErrorMessage(error),
+          ...(typeof error?.code === "string" ? { code: error.code } : {}),
+          ...(Array.isArray(error?.deletedSubagentIds) ? { deletedSubagents: error.deletedSubagentIds } : {}),
+          ...(Array.isArray(error?.remainingSessionIds) ? { remainingSessions: error.remainingSessionIds } : {}),
+          ...(typeof error?.partialFailure === "boolean" ? { partialFailure: error.partialFailure } : {})
+        });
       }
     }
   }), "session-manager: http api");
 }
 
-export { listSessionHeaders, scanSessionHeaders, encodeSessionSegment, compareSemver };
+export { listSessionHeaders, scanSessionHeaders, candidateSessionDirs, encodeFsSessionSegment, decodeFsSessionSegment, encodeProjectSegment, encodeSessionSegment, compareSemver };