dsh-session-manager 0.7.3 → 0.7.5

package/lib/index.js

@@ -28,7 +28,7 @@ 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, detectPluginSource, isHmrActive, resolveProfileDir } from "./compat/dsh-adapter.js";
+import { createDshAdapter, getService, normalizeSessionHeader, compareSemver, detectPluginSource, isHmrActive, resolveProfileDir } from "./compat/dsh-adapter.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";
@@ -39,7 +39,8 @@ export const inject = [
   "sessions",
   "agents",
   "sessionPersistence",
-  "agentPresets"
+  "agentPresets",
+  "connection"
 ];
 
 /** Like JSON.stringify but swallows circular-reference/BigInt errors so the
@@ -101,6 +102,12 @@ function rebindLiveWriter(persistence, sessionId, newHeader) {
  * disk fallback semantics are preserved -- the orphan is the whole
  * reason this loop exists.
  *
+ * The result carries two completeness flags: "persisted" reports whether the
+ * persistence index itself listed successfully (its rows are authoritative),
+ * while "complete" additionally requires the disk sweep to finish without
+ * errors. Callers that only add validated memberships may run on "persisted";
+ * callers that remove records must wait for "complete".
+ *
  * @param {object|undefined} persistence  DSH's sessionPersistence service
  * @param {((segment: string) => string)|undefined} dshHome  Resolver for
  *   DSH home sub-paths; only "sessions" is read.
@@ -110,6 +117,7 @@ const scanSessionHeaders = async (persistence, dshHome) => {
   const headers = [];
   const errors = [];
   let listed = false;
+  let persisted = false;
   if (typeof persistence?.list === "function") {
     try {
       const rows = await persistence.list();
@@ -122,9 +130,10 @@ const scanSessionHeaders = async (persistence, dshHome) => {
         if (!seen.has(header.id)) { seen.add(header.id); headers.push(header); }
       }
       listed = true;
+      persisted = true;
     } catch (error) { errors.push(error); }
   }
-  const result = () => ({ headers, complete: listed && errors.length === 0, errors });
+  const result = () => ({ headers, persisted, 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--").
@@ -175,6 +184,16 @@ const scanSessionHeaders = async (persistence, dshHome) => {
 
 const listSessionHeaders = async (persistence, dshHome) => (await scanSessionHeaders(persistence, dshHome)).headers;
 
+/** Canonicalize a directory path the way DSH's workspace registry does
+ * (fs.realpath on a fully qualified path). Returns undefined when the path
+ * cannot be resolved so callers skip instead of guessing; DSH stores
+ * workspace paths canonicalized, so canonical equality is the only safe
+ * membership comparison on Windows (case, separators, 8.3 names, junctions). */
+const canonicalizeDirectory = async (path) => {
+  if (typeof path !== "string" || path === "") return undefined;
+  try { return await realpath(path); } catch { return undefined; }
+};
+
 const UPDATE_STATUS_FILE = ".dsh-session-manager-update.json";
 const STALE_EXTERNAL_TASK_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes fallback for dead external processes
 const HEARTBEAT_STALE_TIMEOUT_MS = 3 * 60 * 1000; // 3 minutes without heartbeat for external processes
@@ -367,7 +386,7 @@ function verifyInstalledPackage(profileDir, expectedVersion) {
 
 export function apply(ctx) {
   try {
-    const buildId = "dsh-session-manager v0.7.3 (workspace-archive)";
+    const buildId = "dsh-session-manager v0.7.5 (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 */ }
@@ -399,10 +418,26 @@ export function apply(ctx) {
   const safeGetAgent = (sessionId) => {
     try { return ctx.agents?.get?.(sessionId); } catch { return undefined; }
   };
+  /** Durable workspace membership for one entity. The record account is the
+   * authoritative persisted list on DSH 0.2.x (registry entities expose it as
+   * the private `record` field); the runtime `sessionIds` getter is filtered
+   * by the canonical-cwd index and may hide members whose index entry is
+   * stale, so it is only a fallback for hosts without a readable record. */
+  const workspaceMemberIds = (entity) => {
+    if (entity === null || entity === undefined) return [];
+    const record = entity.record;
+    if (record !== null && record !== undefined && Array.isArray(record.sessionIds)) return record.sessionIds;
+    const ids = entity.sessionIds;
+    if (Array.isArray(ids)) return ids;
+    if (typeof ids === "function") {
+      try { const value = ids(); if (Array.isArray(value)) return value; } catch { /* ignore */ }
+    }
+    return [];
+  };
   const assertAnnotatable = id => {
     const registry = adapter.workspaceRegistry;
     if (adapter.getSession(id) !== undefined || registry?.headers?.has?.(id)
-      || adapter.workspaceList().some(ws => (ws.record?.sessionIds ?? ws.sessionIds ?? []).includes(id))) return;
+      || adapter.workspaceList().some(ws => workspaceMemberIds(ws).includes(id))) return;
     throw Object.assign(new Error("会话不存在或尚未加载，请先打开该会话后重试"), { code: "session-not-found" });
   };
   const operations = new Map();
@@ -567,7 +602,9 @@ export function apply(ctx) {
   const detachFromWorkspaces = async (sessionId) => {
     const registry = ctx.get("workspaceRegistry") ?? ctx.workspaceRegistry ?? adapter.workspaceRegistry;
     for (const entity of registry.list()) {
-      if (entity.sessionIds.includes(sessionId)) {
+      // Durable record, not the runtime-filtered getter: deleting a session
+      // must purge its account even when the cwd index is stale.
+      if (workspaceMemberIds(entity).includes(sessionId)) {
         await entity.detachSession(sessionId);
       }
     }
@@ -576,9 +613,7 @@ export function apply(ctx) {
   /** 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];
+      const rawIds = [...workspaceMemberIds(entity)];
       const selfUpdatedAt = entity.updatedAt ?? entity.record?.updatedAt ?? null;
       return {
         id: entity.id,
@@ -834,6 +869,291 @@ ${rest}`, "utf8");
       return false;
     };
 
+    /**
+     * Attach one session to the registered workspace that owns its cwd.
+     * Returns true only when a new durable membership was written.
+     *
+     * DSH's own create/fork flow attaches through workspaceRegistry, but a
+     * session created outside that flow (cwd-only create, an attach the host
+     * declined, or a session that predates this plugin load) stays
+     * unaccounted even though its cwd names a registered workspace. The
+     * official entity API re-validates the stored header cwd against the
+     * canonical workspace path and persists through the domain table, so a
+     * wrong match can never be written. Subagent sessions never join a
+     * workspace account, and a session any workspace already accounts for is
+     * left untouched (no session is ever registered twice).
+     */
+    const attachSessionToOwningWorkspace = async (header) => {
+      const registry = adapter.workspaceRegistry;
+      if (registry === void 0 || typeof registry.list !== "function") return false;
+      if (header === void 0 || typeof header.id !== "string") return false;
+      if (header.origin === "subagent") return false;
+      if (typeof header.cwd !== "string" || header.cwd === "") return false;
+      const run = async () => {
+        const entities = registry.list();
+        for (const entity of entities) {
+          if (workspaceMemberIds(entity).includes(header.id)) return false;
+        }
+        const byPath = new Map();
+        for (const entity of entities) {
+          if (typeof entity.path === "string" && !byPath.has(entity.path)) byPath.set(entity.path, entity);
+        }
+        let target = byPath.get(header.cwd);
+        if (target === void 0 && typeof registry.resolveByPath === "function") {
+          try { target = await registry.resolveByPath(header.cwd); } catch { target = void 0; }
+        }
+        if (target === void 0) {
+          const canonical = await canonicalizeDirectory(header.cwd);
+          if (canonical !== void 0) target = byPath.get(canonical);
+        }
+        if (target === void 0 || typeof target.attachSession !== "function") return false;
+        await target.attachSession(header.id);
+        return true;
+      };
+      if (typeof registry.enqueueOperation === "function") return await registry.enqueueOperation(run);
+      return await run();
+    };
+
+    /**
+     * Resolve the header the official attachSession() will validate against.
+     * WorkspaceEntity.readSessionHeader prefers the live session, then the
+     * registry's own header index, and only then a fresh persistence listing.
+     * Mirroring that order lets the repair predict a rejection instead of
+     * attempting an attach that cannot succeed.
+     */
+    const effectiveSessionHeader = (sessionId, storedHeader) => {
+      try {
+        const live = ctx.sessions?.get?.(sessionId);
+        if (live !== undefined && live !== null && live.header !== undefined) return live.header;
+      } catch { /* fall through to the index */ }
+      try {
+        const indexed = adapter.workspaceRegistry?.headers?.get?.(sessionId);
+        if (indexed !== undefined) return indexed;
+      } catch { /* fall through to the stored header */ }
+      return storedHeader;
+    };
+
+    /**
+     * Complete the durable workspace membership of a session whose artifact
+     * already lives under the target workspace path (same-path move). DSH 0.2.x
+     * keeps "cwd matches the workspace path" and "the workspace accounts for
+     * the session" as separate facts, so a matching cwd alone must not be
+     * reported as success.
+     *
+     * Conservative policy. The official domain offers no cross-record
+     * transaction (single-record updates on one serialized storage unit), and
+     * attachSession() validates the session cwd against the workspace path --
+     * so an account held by a DIFFERENT workspace can never be restored
+     * through the official API once it is removed. Automatic migration would
+     * therefore risk destroying the only remaining account if the target
+     * attach then failed. Hence:
+     *   - no workspace accounts for the session: complete the target
+     *     membership through attachSession(), after pre-checking every
+     *     condition it validates so a predictable rejection fails before any
+     *     write;
+     *   - already accounted by the target and by nobody else: idempotent
+     *     no-op, no write;
+     *   - accounted by another workspace: refuse with a membership-conflict
+     *     error; no automatic cross-record migration;
+     *   - membership state cannot be confirmed: refuse.
+     *
+     * No artifact is rewritten, no cwd is touched, and no live session is
+     * restarted. A true cross-workspace move re-homes the artifact first and
+     * is a separate, unchanged path.
+     *
+     * @returns {status: "already-member"|"attached", attached: boolean}
+     * @throws with code workspace-membership-unknown | workspace-membership-conflict |
+     *   workspace-attach-unavailable | workspace-repair-unsafe | workspace-repair-failed.
+     */
+    const repairWorkspaceMembership = async (target, sessionId, storedHeader) => {
+      const registry = ctx.get("workspaceRegistry") ?? ctx.workspaceRegistry ?? adapter.workspaceRegistry;
+      const run = async () => {
+        // Confirm the current accounting from a fresh, readable listing. An
+        // unreadable registry must never be guessed at.
+        let entities;
+        let inTarget;
+        let stale;
+        try {
+          if (typeof registry?.list !== "function") throw new Error("workspace registry 不可用");
+          const listed = registry.list();
+          if (!Array.isArray(listed)) throw new Error("workspace registry 返回了无效数据");
+          entities = listed;
+          inTarget = workspaceMemberIds(target).includes(sessionId);
+          stale = entities.filter((entity) =>
+            entity !== target && entity.id !== target.id && workspaceMemberIds(entity).includes(sessionId));
+        } catch (cause) {
+          const error = new Error("无法确认会话当前的工作区归属状态（" + safeErrorMessage(cause) + "），已拒绝修复操作");
+          error.code = "workspace-membership-unknown";
+          throw error;
+        }
+
+        if (stale.length > 0) {
+          // Membership conflict: the session is accounted by a workspace whose
+          // path differs from its cwd. That account cannot be restored through
+          // the official API once removed, so an automatic migration could
+          // destroy the only remaining account if the target attach failed.
+          // Refuse and let the operator resolve the conflict.
+          const names = stale.map((entity) => entity.title || entity.id).join("、");
+          const error = new Error(
+            "会话当前登记在其他工作区（" + names + "），与其 cwd 指向的目标工作区不一致。"
+            + "为避免修复失败造成数据损失，已拒绝自动迁移；请先处理该归属冲突，或使用真正的跨工作区移动"
+          );
+          error.code = "workspace-membership-conflict";
+          throw error;
+        }
+        if (inTarget) return { status: "already-member", attached: false };
+        if (typeof target.attachSession !== "function") {
+          const error = new Error("当前 DSH 宿主未提供官方工作区归属接口（attachSession），无法补全会话归属");
+          error.code = "workspace-attach-unavailable";
+          throw error;
+        }
+
+        // Pre-check every condition attachSession() validates so a predictable
+        // rejection fails before any write. The header it reads is the live
+        // session first, then the registry index, then a fresh persistence
+        // listing -- not necessarily the header this request was validated
+        // against.
+        const effective = effectiveSessionHeader(sessionId, storedHeader);
+        if (effective === void 0 || typeof effective.cwd !== "string" || effective.cwd === "") {
+          const error = new Error("拒绝补全归属：会话没有可校验的 cwd，官方接口无法登记");
+          error.code = "workspace-repair-unsafe";
+          throw error;
+        }
+        const canonical = await canonicalizeDirectory(effective.cwd);
+        if (canonical === void 0 || canonical !== target.path) {
+          const error = new Error(
+            "拒绝补全归属：会话当前 cwd（" + effective.cwd + "）解析后与目标工作区（" + target.path
+            + "）不一致，官方接口会拒绝登记；未做任何修改"
+          );
+          error.code = "workspace-repair-unsafe";
+          throw error;
+        }
+        try {
+          await target.attachSession(sessionId);
+        } catch (cause) {
+          // Nothing has been written yet, so the previous state (no account) is
+          // intact; surface the failure with its cause.
+          const error = new Error("补全归属失败：" + safeErrorMessage(cause));
+          error.code = "workspace-repair-failed";
+          throw error;
+        }
+        return { status: "attached", attached: true };
+      };
+      if (registry !== void 0 && typeof registry.enqueueOperation === "function") {
+        return await registry.enqueueOperation(run);
+      }
+      return await run();
+    };
+
+    /**
+     * Issue #42: record the working-directory change a move implies.
+     *
+     * A cross-workspace move rewrites the artifact header's `cwd`, but DSH
+     * folds the `workingDirectory` projection from the session log: the unit
+     * initializes from `header.cwd` only while it has no checkpoint, and both
+     * the projection cache and every `working-directory/change` event
+     * supersede that initial value. A live session therefore keeps reporting
+     * its pre-move directory -- the projection state is never re-initialized --
+     * and the cache checkpoints that stale state under the NEW header identity,
+     * so a rebuild cannot recover the target either. Route the change through
+     * the host's own path (the `workingDirectory` service is what a user `cd`
+     * uses) so the log gains the event the projection folds from; without that
+     * service, append the equivalent event directly, which is the same shape
+     * the host's `commit()` writes.
+     *
+     * @param agent - the live Agent owning the moved session, when one exists.
+     * @param session - the live Session owning the moved log.
+     * @param targetPath - the destination workspace directory.
+     * @returns `{status}`: "synced" (host service committed the change),
+     *   "recorded" (event appended directly) or "restart-required" (the host
+     *   rejected the change; the move itself has already succeeded).
+     */
+    const rehomeLiveWorkingDirectory = async ({ agent, session, targetPath }) => {
+      const service = getService(ctx, "workingDirectory");
+      if (service !== undefined && typeof service.set === "function" && agent !== undefined) {
+        try {
+          const cwd = await service.set(agent, targetPath);
+          return { status: "synced", cwd: typeof cwd === "string" && cwd !== "" ? cwd : targetPath };
+        } catch (error) {
+          const isFiberError = error?.code === "INACTIVE_EFFECT" ||
+            String(error?.message || error).toLowerCase().includes("inactive") ||
+            String(error?.message || error).toLowerCase().includes("fiber");
+          if (!isFiberError) {
+            ctx.logger.warn(`session-manager: moved "${safeJson(session?.id)}" but the host rejected the working-directory change: ${safeErrorMessage(error)}`);
+            return { status: "restart-required", reason: safeErrorMessage(error) };
+          }
+        }
+      }
+      if (session === undefined || session === null || typeof session.append !== "function") {
+        return { status: "restart-required", reason: "no live session to record the working-directory change" };
+      }
+      try {
+        session.append("working-directory/change", { cwd: targetPath });
+        return { status: "recorded", cwd: targetPath };
+      } catch (error) {
+        ctx.logger.warn(`session-manager: moved "${safeJson(session.id)}" but could not record the working-directory change: ${safeErrorMessage(error)}`);
+        return { status: "restart-required", reason: safeErrorMessage(error) };
+      }
+    };
+
+    /**
+     * Issue #42 (cold sessions): append the `working-directory/change` event a
+     * live move records, but only when the stored log already carries one --
+     * otherwise the rewritten `header.cwd` alone initializes the projection on
+     * the next resume and touching the log would be gratuitous. A stale change
+     * event would otherwise fold the pre-move directory back in. Rows whose
+     * `seq` does not match their position (packed physical rows) cannot be
+     * extended without the persistence codec, so the body is left untouched and
+     * the caller reports that a restart is required.
+     *
+     * @param rest - the artifact body (everything after the header line).
+     * @param targetPath - the destination workspace directory.
+     * @returns `{rest, status}` with the body to publish.
+     */
+    const rehomeColdWorkingDirectory = (rest, targetPath) => {
+      const nl = String.fromCharCode(10);
+      const terminated = rest.endsWith(nl);
+      const body = terminated ? rest.slice(0, -1) : rest;
+      if (body === "") return { rest, status: "header-only" };
+      const lines = body.split(nl);
+      let lastChange;
+      let hasPackedOrUnparseableRows = false;
+      let hasNonSequentialSeq = false;
+      for (let index = 0; index < lines.length; index += 1) {
+        let event;
+        try {
+          event = JSON.parse(lines[index]);
+        } catch {
+          hasPackedOrUnparseableRows = true;
+          continue;
+        }
+        if (event === null || typeof event !== "object") {
+          hasPackedOrUnparseableRows = true;
+          continue;
+        }
+        if (event.seq !== index) {
+          hasNonSequentialSeq = true;
+        }
+        if (event.type === "working-directory/change") {
+          lastChange = event.data?.cwd;
+        }
+      }
+      if (lastChange === undefined) return { rest, status: "header-only" };
+      if (lastChange === targetPath) return { rest, status: "already-target" };
+      if (hasPackedOrUnparseableRows || hasNonSequentialSeq) {
+        const error = new Error("无法安全同步会话工作目录（会话日志包含压缩行且已有工作目录变更历史），为防止工作目录不一致，已取消移动。原始会话保持原状");
+        error.code = "working-directory-sync-unsafe";
+        throw error;
+      }
+      const appended = JSON.stringify({
+        type: "working-directory/change",
+        seq: lines.length,
+        time: Date.now(),
+        data: { cwd: targetPath }
+      });
+      return { rest: `${body}${nl}${appended}${nl}`, status: "recorded" };
+    };
+
     /**
      * TRUE cross-workspace move. See the module docstring for the full design:
      * re-home the stored cwd, migrate the artifact, then swap accounting.
@@ -896,7 +1216,25 @@ ${rest}`, "utf8");
         let currentCanonical;
         try { currentCanonical = await realpath(storedHeader.cwd); } catch { /* re-home below */ }
         if (currentCanonical === targetPath) {
-          return { ok: true, sessionId, moved: false, message: "会话已属于目标工作区" };
+          // The artifact already lives under the target workspace path, but on
+          // DSH 0.2.x "cwd matches" and "the workspace accounts for the
+          // session" are separate facts: a matching cwd with a missing
+          // registration used to return a silent no-op success. Repair the
+          // durable membership through the official entity API (idempotent,
+          // no artifact rewrite, no live-session restart) and report what
+          // actually happened. A repair that cannot be completed fails loudly
+          // instead of reporting success.
+          const repair = await repairWorkspaceMembership(target, sessionId, storedHeader);
+          return {
+            ok: true,
+            sessionId,
+            moved: false,
+            attached: repair.attached,
+            membership: repair.status,
+            message: repair.attached
+              ? "会话已归属目标工作区（已补全归属记录）"
+              : "会话已属于目标工作区"
+          };
         }
       }
 
@@ -968,7 +1306,14 @@ ${rest}`, "utf8");
           throw new Error("目标位置已有会话工件，拒绝覆盖");
         } catch (error) { if (error.code !== "ENOENT") throw error; }
         if (oldPath === newPath) throw new Error("会话源路径与目标路径相同，但 cwd 不一致，拒绝覆盖");
-        const bytes = await encodeArtifact(JSON.stringify(newHeader), rest, newPath.endsWith(".zstd"));
+        // Issue #42: a cold log is the only authority its working-directory
+        // projection folds from on the next resume, so re-home it together
+        // with the artifact header. Live sessions get the equivalent event
+        // through the host path once the artifact has been published.
+        const bodyRehome = liveSession === void 0
+          ? rehomeColdWorkingDirectory(rest, targetPath)
+          : { rest, status: "live" };
+        const bytes = await encodeArtifact(JSON.stringify(newHeader), bodyRehome.rest, newPath.endsWith(".zstd"));
         await mkdir(dirname(newPath), { recursive: true });
         const tempNew = await writeTempFile(newPath, bytes);
         const oldHidden = `${oldPath}.${randomBytes(6).toString("hex")}.tmp`;
@@ -1003,7 +1348,7 @@ ${rest}`, "utf8");
         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))
+          .filter((entity) => entity.id !== target.id && workspaceMemberIds(entity).includes(sessionId))
           .map((entity) => entity.id);
         let targetAttached = false;
         const detachedFrom = [];
@@ -1069,7 +1414,7 @@ ${rest}`, "utf8");
           await rm(dirname(oldPath), { recursive: true, force: true });
         } catch (error) { ctx.logger.warn(`session-manager: old directory retained: ${String(error)}`); }
 
-        movedArtifact = { header: newHeader, rest };
+        movedArtifact = { header: newHeader, rest: bodyRehome.rest, workingDirectory: bodyRehome.status };
 
         return {
           ok: true,
@@ -1101,7 +1446,34 @@ ${rest}`, "utf8");
           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
+      // Issue #42: the artifact header was rewritten, but the folded
+      // `workingDirectory` projection was not. Align it now -- after the
+      // artifact has been published (a live session's change event must land in
+      // the moved log) and after the registry swap.
+      let workingDirectory = movedArtifact?.workingDirectory ?? "not-needed";
+      let restartRequired = false;
+      if (liveSession !== void 0) {
+        const rehomed = await rehomeLiveWorkingDirectory({ agent: liveAgent, session: liveSession, targetPath });
+        workingDirectory = rehomed.status;
+        if (rehomed.status === "restart-required") restartRequired = true;
+        if (rehomed.status === "synced" || rehomed.status === "recorded") {
+          // The refold above seeds from the projection cache, so it cannot see
+          // a change committed after the move: checkpoint what the live
+          // session now actually folds (this flushes the new event first).
+          if (cache !== void 0 && typeof cache.write === "function") {
+            try {
+              await cache.write(liveSession);
+            } catch (error) {
+              ctx.logger.warn(`session-manager: post-move working-directory checkpoint failed for "${sessionId}": ${safeErrorMessage(error)}`);
+            }
+          }
+        }
+      } else if (workingDirectory === "restart-required") {
+        restartRequired = true;
+      }
+      result.workingDirectory = workingDirectory;
+      result.restartRequired = restartRequired;
+      // 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.
@@ -1168,8 +1540,7 @@ ${rest}`, "utf8");
             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);
+          for (const id of workspaceMemberIds(ws)) allowedIds.add(id);
         }
       }
       const requestedSessionId = filter !== void 0 && typeof filter === "object" && typeof filter.sessionId === "string"
@@ -1818,43 +2189,103 @@ ${rest}`, "utf8");
     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.
-      const initialIds = new Map(registry.list().map(ws => [ws.id, new Set(ws.record?.sessionIds ?? [])]));
-      const scan = await scanSessionHeaders(persistence, adapter.homePath);
-      if (!scan.complete) {
-        ctx.logger.warn("session-manager: incomplete session scan; workspace reconciliation skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+      // Snapshot durable membership BEFORE the async scan. Only ids that
+      // already existed here may ever be pruned later; ids attached
+      // concurrently must never be removed using an older disk snapshot.
+      let entities;
+      try { entities = registry.list(); }
+      catch (error) {
+        ctx.logger.warn("session-manager: workspace registry unavailable; workspace reconciliation skipped: " + safeErrorMessage(error));
         return;
       }
-      const headers = scan.headers;
-      const validIds = new Set(headers.map(header => header.id));
+      const initialIds = new Map(entities.map(ws => [ws.id, new Set(workspaceMemberIds(ws))]));
+      const scan = await scanSessionHeaders(persistence, adapter.homePath);
+      const headers = Array.isArray(scan.headers) ? scan.headers : [];
+
+      // Step 1a: attach sessions whose cwd names a registered workspace but
+      // that no workspace accounts for (issue #41). Every candidate is
+      // re-validated by the official entity API, which persists through the
+      // domain table and is idempotent for already-accounted ids -- so this
+      // pass can only add well-formed memberships, never corrupt records.
+      // It runs whenever the persistence index listed successfully
+      // (scan.persisted); a partial disk sweep cannot make a listed header
+      // invalid.
+      let added = 0;
+      if (scan.persisted) {
+        const assigned = new Set();
+        for (const ws of entities) for (const id of initialIds.get(ws.id)) assigned.add(id);
+        const candidates = headers.filter(header =>
+          typeof header.cwd === "string" && header.cwd !== ""
+          && header.origin !== "subagent"
+          && !assigned.has(header.id));
+        if (candidates.length > 0) {
+          const byPath = new Map();
+          for (const ws of entities) {
+            if (typeof ws.path === "string" && !byPath.has(ws.path)) byPath.set(ws.path, ws);
+          }
+          const attach = async () => {
+            // Re-read membership inside the registry write queue: a concurrent
+            // move may have accounted an id after the snapshot above.
+            const current = typeof registry.list === "function" ? registry.list() : entities;
+            const assignedNow = new Set();
+            for (const ws of current) for (const id of workspaceMemberIds(ws)) assignedNow.add(id);
+            for (const header of candidates) {
+              if (assignedNow.has(header.id)) continue;
+              let target = byPath.get(header.cwd);
+              if (target === void 0) {
+                const canonical = await canonicalizeDirectory(header.cwd);
+                if (canonical !== void 0) target = byPath.get(canonical);
+              }
+              if (target === void 0 || typeof target.attachSession !== "function") continue;
+              try {
+                await target.attachSession(header.id);
+                assignedNow.add(header.id);
+                added += 1;
+              } catch (error) {
+                ctx.logger.warn("session-manager: boot attach of session '" + header.id + "' to workspace '" + target.id + "' failed: " + safeErrorMessage(error));
+              }
+            }
+          };
+          if (typeof registry.enqueueOperation === "function") await registry.enqueueOperation(attach);
+          else await attach();
+        }
+      }
 
-      // Step 1: Immediate Workspace Member Reconciliation (isolated from projection rebuild)
+      // Step 1b: prune record entries whose session no longer exists. Only a
+      // fully complete scan (persistence index plus disk sweep, no errors)
+      // may remove anything; live sessions and ids attached after the
+      // snapshot are always kept. Durable records are read through
+      // workspaceMemberIds so a stale runtime index cannot hide a dead entry.
       let removed = 0;
-      let added = 0;
-      await registry.enqueueOperation(async () => {
-        const state = registry.requireState();
-        const pathById = new Map(registry.list().map(ws => [ws.id, ws.path]));
-        const assignedIds = new Set((state.workspaces ?? []).flatMap(ws => ws.sessionIds ?? []));
-        const workspaces = (state.workspaces ?? []).map(ws => {
-          const original = ws.sessionIds ?? [];
-          const sessionIds = original.filter(id => validIds.has(id)
-            || !initialIds.get(ws.id)?.has(id) || adapter.getSession(id) !== undefined);
-          const removedHere = original.length - sessionIds.length;
-          removed += removedHere;
-          for (const header of headers) {
-            if (header.cwd === undefined || header.cwd !== pathById.get(ws.id) || assignedIds.has(header.id)) continue;
-            sessionIds.unshift(header.id);
-            assignedIds.add(header.id);
-            added += 1;
+      if (scan.complete) {
+        const validIds = new Set(headers.map(header => header.id));
+        const prune = async () => {
+          for (const ws of (typeof registry.list === "function" ? registry.list() : entities)) {
+            const initial = initialIds.get(ws.id);
+            // Snapshot: detachSession replaces the record array while we walk it.
+            for (const id of [...workspaceMemberIds(ws)]) {
+              if (validIds.has(id)) continue;
+              if (initial === void 0 || !initial.has(id)) continue;
+              if (adapter.getSession(id) !== undefined) continue;
+              if (typeof ws.detachSession !== "function") continue;
+              await ws.detachSession(id);
+              removed += 1;
+            }
           }
-          if (sessionIds.length === original.length && sessionIds.every((id, i) => id === original[i])) return ws;
-          return { ...ws, sessionIds, updatedAt: new Date().toISOString() };
-        });
-        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 (typeof registry.enqueueOperation === "function") await registry.enqueueOperation(prune);
+        else await prune();
+      }
+      if (added || removed) {
+        ctx.logger.info('session-manager: post-boot workspace reconcile attached ' + added + ' unaccounted sessions, removed ' + removed + ' orphans');
+      }
+      if (!scan.persisted) {
+        ctx.logger.warn("session-manager: incomplete session scan; workspace reconciliation skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+        return;
+      }
+      if (!scan.complete) {
+        ctx.logger.warn("session-manager: incomplete disk sweep; workspace membership pruning skipped: " + scan.errors.map(safeErrorMessage).join("; "));
+        return;
       }
 
       // Step 2: Budgeted Background Projection Cache Rebuild
@@ -1918,6 +2349,32 @@ ${rest}`, "utf8");
     }
   }, "session-manager: post-boot re-fold stale projection cache rows");
 
+  /**
+   * Runtime membership repair (issue #41): DSH's own create/fork flow attaches
+   * a session to its workspace, but a session created outside that flow -- or
+   * one whose host-side attach failed -- stays unaccounted even though its
+   * cwd names a registered workspace, and would otherwise only be repaired on
+   * the next DSH restart. Repair it as soon as the session is announced.
+   *
+   * The listener must never throw synchronously: a throwing session/created
+   * listener rolls back session creation in DSH. Everything is contained and
+   * fire-and-forget; failures are logged only.
+   */
+  if (typeof ctx.on === "function") ctx.on("session/created", (session) => {
+    void (async () => {
+      try {
+        const header = session?.header ?? session;
+        if (header === void 0 || typeof header.id !== "string") return;
+        const attached = await attachSessionToOwningWorkspace(header);
+        if (attached) {
+          ctx.logger.info("session-manager: attached new session '" + header.id + "' to its cwd workspace");
+        }
+      } catch (error) {
+        ctx.logger.warn("session-manager: session/created membership repair failed: " + safeErrorMessage(error));
+      }
+    })();
+  });
+
   /** Build a normalized annotation patch from one bulk action + payload.
    * Returns null when the payload is missing or malformed so the caller can
    * surface a 400 instead of letting the store throw on a bad value.
@@ -1982,9 +2439,80 @@ ${rest}`, "utf8");
     if (isBlank) { const e = new Error("blank"); e.code = "blank-skip"; throw e; }
   };
 
-  ctx.effect(() => ctx.webServer.register({    kind: "prefix",
+  /**
+   * Issue #43: Validate incoming request with DSH connection authentication.
+   * Reuses DSH official Connection/Gateway authentication and authorization mechanisms.
+   * Strict fail-closed: requires connection.admit() to succeed with a valid Owner peer.
+   * Must execute before request body reading, JSON parsing, or business operations.
+   */
+  const authenticateApiRequest = (req) => {
+    const connection = getService(ctx, "connection");
+    if (!connection || typeof connection.admit !== "function") {
+      return {
+        ok: false,
+        status: 503,
+        code: "auth-unavailable",
+        error: "DSH 认证服务未就绪或不可用，为保护数据安全已拒绝请求"
+      };
+    }
+    try {
+      const admission = connection.admit(req);
+      if (!admission || typeof admission !== "object") {
+        return {
+          ok: false,
+          status: 401,
+          code: "unauthorized",
+          error: "未授权：需要有效的 DSH 会话凭证"
+        };
+      }
+      if ("rejection" in admission) {
+        const status = typeof admission.rejection === "number" ? admission.rejection : 401;
+        const error = status === 403
+          ? "禁止访问：请求未通过 DSH 信任检查或跨站防护"
+          : "未授权：需要有效的 DSH 会话凭证";
+        return { ok: false, status, code: status === 403 ? "forbidden" : "unauthorized", error };
+      }
+      const peer = admission.peer;
+      if (!peer || typeof peer !== "object") {
+        return {
+          ok: false,
+          status: 401,
+          code: "unauthorized",
+          error: "未授权：缺少有效 Peer 凭证"
+        };
+      }
+      const principalKind = peer.principal?.kind;
+      if (principalKind !== "owner") {
+        return {
+          ok: false,
+          status: 403,
+          code: "forbidden",
+          error: "禁止访问：会话管理属于特权操作，需要 owner 权限"
+        };
+      }
+      return { ok: true, peer };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 403,
+        code: "auth-error",
+        error: "认证检查失败: " + safeErrorMessage(err)
+      };
+    }
+  };
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: "prefix",
     path: API_PREFIX,
     handler: async (req, res) => {
+      const auth = authenticateApiRequest(req);
+      if (!auth.ok) {
+        return send(res, auth.status, {
+          ok: false,
+          code: auth.code,
+          error: auth.error
+        });
+      }
       try {
         const url = new URL(req.url ?? "/", "http://localhost");
         const path = url.pathname.startsWith(API_PREFIX) ? url.pathname.slice(API_PREFIX.length) || "/" : "/";
@@ -2215,7 +2743,7 @@ ${rest}`, "utf8");
           return send(res, 200, { ok: true, result });
         }
         if (req.method === "GET" && path === "/update/check") {
-          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          const currentVersion = adapter.pluginVersion() || "0.7.5";
           const runningVersion = currentVersion;
           let installedVersion = runningVersion;
           const profileDir = resolveProfileDir(adapter, ctx);
@@ -2399,7 +2927,7 @@ ${rest}`, "utf8");
           };
           setActiveTask(taskRecord);
 
-          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          const currentVersion = adapter.pluginVersion() || "0.7.5";
           let installedVersion = currentVersion;
           if (profileDir) {
             const pkgFile = join(profileDir, "node_modules", "dsh-session-manager", "package.json");
@@ -2929,7 +3457,7 @@ ${rest}`, "utf8");
         }
         if (req.method === "GET" && path === "/update/status") {
           const profileDir = resolveProfileDir(adapter, ctx);
-          const currentVersion = adapter.pluginVersion() || "0.7.3";
+          const currentVersion = adapter.pluginVersion() || "0.7.5";
           let installedVersion = currentVersion;
           if (profileDir) {
             const diskCheck = verifyInstalledPackage(profileDir);
@@ -3004,7 +3532,10 @@ ${rest}`, "utf8");
         ctx.logger.warn("session-manager: api error: " + safeErrorMessage(error) + "; json=" + safeJson(error));
         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;
+          : error?.code === "working-directory-sync-unsafe" ? 409
+          : error?.code === "session-not-found" ? 404 : error?.code?.startsWith("annotations-") ? 503
+          : error?.code === "workspace-membership-conflict" ? 409
+          : error?.code === "workspace-attach-unavailable" ? 501 : 500;
         return send(res, status, {
           ok: false,
           error: safeErrorMessage(error),