dsh-synapse 0.4.1 → 0.4.2

package/index.js

@@ -1,465 +1,469 @@
-import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
-import { randomUUID } from 'node:crypto'
-import { dirname } from 'node:path'
-
-export const name = 'synapse'
-export const inject = ['webServer', 'sessions']
-
-const MAX_BODY_BYTES = 32 * 1024
-const MAX_TITLE_LENGTH = 120
-const MAX_NOTE_LENGTH = 4_000
-// Projected message text cap: longer replies truncate with a marker pointing
-// at the detail view instead of silently cutting mid-sentence.
-const MAX_PROJECTION_LENGTH = 8_000
-const PROJECTION_TRUNCATED_SUFFIX = '\n——…（详情查看全文）'
-const TOPIC_COLORS = ['#0f766e', '#2563eb', '#be123c', '#7c3aed', '#b45309']
-const LOCK_STALE_MS = 60_000
-// Deferred (event-projection) writes coalesce into one save per window, so a
-// burst of session events costs a single full-state write instead of one per
-// event (issue #13: per-event saves pinned the main thread at ~90% CPU).
-const SAVE_DEBOUNCE_MS = 800
-
-/** JSON persistence for the Synapse workspace graph. */
-export class WorkspaceStore {
-  constructor(dataFile) {
-    if (typeof dataFile !== 'string' || dataFile.length === 0) throw new Error('synapse: config.dataFile must be a non-empty path')
-    this.dataFile = dataFile
-    this.state = undefined
-    this.serial = Promise.resolve()
-    this.ready = this.load()
-    this.lastKnownMtime = null
-    this.externalModWarned = false
-    this.lockWarned = false
-    this.dirty = false
-    this.flushTimer = null
-  }
-
-  async list() {
-    await this.ready
-    return this.state.workspaces.map(workspace => this.summary(workspace))
-  }
-
-  async get(workspaceId) {
-    await this.ready
-    const workspace = this.workspace(workspaceId)
-    return structuredClone(workspace)
-  }
-
-  async create(title) {
-    return this.mutate(() => {
-      const now = new Date().toISOString()
-      const workspace = { id: randomUUID(), title: requiredText(title, MAX_TITLE_LENGTH, 'title'), createdAt: now, updatedAt: now, threads: [] }
-      this.state.workspaces.unshift(workspace)
-      return this.summary(workspace)
-    })
-  }
-
-  async createThread(workspaceId, input) {
-    return this.mutate(() => {
-      const workspace = this.workspace(workspaceId)
-      const now = new Date().toISOString()
-      const thread = this.thread({
-        title: input?.title,
-        parentId: input?.parentId,
-        dshSessionId: input?.dshSessionId,
-        dshSessionTitle: input?.dshSessionTitle,
-        position: input?.position,
-        color: input?.color,
-        now,
-        order: workspace.threads.length,
-      })
-      if (thread.parentId !== null && !workspace.threads.some(item => item.id === thread.parentId)) throw new InputError('分支来源不存在')
-      workspace.threads.push(thread)
-      workspace.updatedAt = now
-      return structuredClone(thread)
-    })
-  }
-
-  async branch(threadId, input) {
-    return this.mutate(() => {
-      const { workspace, thread: parent } = this.locateThread(threadId)
-      const now = new Date().toISOString()
-      const sessionId = typeof input?.dshSessionId === 'string' && input.dshSessionId.length > 0 ? input.dshSessionId : null
-      // A DSH fork emits session/created while the browser receives its fork
-      // response. Either path may win the race, but both must resolve to one node.
-      if (sessionId !== null) {
-        const existing = workspace.threads.find(item => item.dshSessionId === sessionId)
-        if (existing !== undefined) {
-          existing.parentId ??= parent.id
-          if (typeof input?.title === 'string' && input.title.trim() !== '') existing.title = requiredText(input.title, MAX_TITLE_LENGTH, 'title')
-          if (typeof input?.dshSessionTitle === 'string') existing.dshSessionTitle = input.dshSessionTitle.slice(0, MAX_TITLE_LENGTH)
-          existing.updatedAt = now
-          workspace.updatedAt = now
-          return structuredClone(existing)
-        }
-      }
-      const siblings = workspace.threads.filter(item => item.parentId === parent.id)
-      const thread = this.thread({
-        title: input?.title,
-        parentId: parent.id,
-        dshSessionId: input?.dshSessionId,
-        dshSessionTitle: input?.dshSessionTitle,
-        position: input?.position ?? { x: parent.position.x + 420, y: parent.position.y + siblings.length * 248 },
-        color: input?.color ?? parent.color,
-        now,
-        order: workspace.threads.length,
-      })
-      workspace.threads.push(thread)
-      workspace.updatedAt = now
-      return structuredClone(thread)
-    })
-  }
-
-  /** Keep only the canvas graph in Synapse; DSH remains the source of session truth. */
-  async syncSessions(sessions, removedSessionIds = []) {
-    return this.mutate(() => {
-      if (!Array.isArray(sessions)) throw new InputError('sessions 必须是数组')
-      if (!Array.isArray(removedSessionIds) || removedSessionIds.some(item => typeof item !== 'string')) throw new InputError('removedSessionIds 必须是字符串数组')
-      const blankIds = new Set(sessions.filter(item => item?.blank === true && typeof item.id === 'string').map(item => item.id))
-      const removedIds = new Set(removedSessionIds)
-      for (const workspace of this.state.workspaces) {
-        if (workspace.kind !== 'dsh') continue
-        workspace.threads = workspace.threads.filter(thread => !blankIds.has(thread.dshSessionId) && !removedIds.has(thread.dshSessionId))
-      }
-      this.state.workspaces = this.state.workspaces.filter(workspace => workspace.kind !== 'dsh' || workspace.threads.length > 0)
-      for (const item of sessions) {
-        if (typeof item?.id !== 'string' || item.id === '' || typeof item.cwd !== 'string' || item.cwd === '') continue
-        if (item.blank === true) continue
-        // Canvas archiving is persistent UI state. A normal DSH list refresh
-        // must not recreate a session that the user deliberately archived.
-        if (this.state.hiddenSessionIds.includes(item.id)) continue
-        const workspace = this.dshWorkspace(item.cwd, 'DSH 任务')
-        const session = { id: item.id, header: { meta: { cwd: item.cwd }, parentSession: typeof item.parentId === 'string' ? item.parentId : undefined }, title: typeof item.title === 'string' ? item.title : undefined, events: [] }
-        const thread = this.dshThread(workspace, session)
-        if (typeof item.title === 'string' && item.title.trim() !== '') {
-          thread.title = item.title.slice(0, MAX_TITLE_LENGTH)
-          thread.dshSessionTitle = thread.title
-        }
-      }
-      return this.list()
-    }, { deferred: true })
-  }
-
-  async addMessage(threadId, text) {
-    return this.mutate(() => {
-      const { workspace, thread } = this.locateThread(threadId)
-      const at = new Date().toISOString()
-      const message = { id: randomUUID(), text: requiredText(text, MAX_NOTE_LENGTH, 'text'), kind: 'user', at }
-      thread.messages.push(message)
-      thread.updatedAt = at
-      workspace.updatedAt = at
-      return structuredClone(thread)
-    })
-  }
-
-  async updateThread(threadId, input) {
-    return this.mutate(() => {
-      const { workspace, thread } = this.locateThread(threadId)
-      if (input?.title !== undefined) thread.title = requiredText(input.title, MAX_TITLE_LENGTH, 'title')
-      if (input?.position !== undefined) thread.position = positionOf(input.position)
-      thread.updatedAt = new Date().toISOString()
-      workspace.updatedAt = thread.updatedAt
-      return structuredClone(thread)
-    })
-  }
-
-  async removeThread(threadId) {
-    return this.mutate(() => {
-      const { workspace, thread } = this.locateThread(threadId)
-      const removal = new Set([thread.id])
-      for (let changed = true; changed;) {
-        changed = false
-        for (const item of workspace.threads) {
-          if (item.parentId !== null && removal.has(item.parentId) && !removal.has(item.id)) { removal.add(item.id); changed = true }
-        }
-      }
-      for (const item of workspace.threads) {
-        if (removal.has(item.id) && item.dshSessionId !== null && !this.state.hiddenSessionIds.includes(item.dshSessionId)) this.state.hiddenSessionIds.push(item.dshSessionId)
-      }
-      workspace.threads = workspace.threads.filter(item => !removal.has(item.id))
-      workspace.updatedAt = new Date().toISOString()
-      if (workspace.threads.length === 0) this.state.workspaces = this.state.workspaces.filter(item => item.id !== workspace.id)
-      return { removed: removal.size }
-    })
-  }
-
-  async clearLegacy(sessions) {
-    return this.mutate(() => {
-      const hidden = new Set(this.state.hiddenSessionIds)
-      for (const workspace of this.state.workspaces) for (const thread of workspace.threads) if (thread.dshSessionId !== null) hidden.add(thread.dshSessionId)
-      for (const session of sessions) hidden.add(session.id)
-      this.state.hiddenSessionIds = [...hidden]
-      this.state.workspaces = []
-      return { cleared: true }
-    })
-  }
-
-  /** Replay one live DSH session into the dedicated projection workspace. */
-  async projectSession(session, replayFrom = 0, workspaceTitle = 'DSH 任务') {
-    return this.mutate(() => {
-      if (this.state.hiddenSessionIds.includes(session.id)) return null
-      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
-      const thread = this.dshThread(workspace, session)
-      for (const event of session.events) {
-        if (event.seq >= replayFrom) this.projectEventInto(workspace, thread, event)
-      }
-      return structuredClone(thread)
-    }, { deferred: true })
-  }
-
-  /** Project one committed DSH session event. Repeated sequence numbers are ignored. */
-  async projectEvent(session, event, workspaceTitle = 'DSH 任务') {
-    return this.mutate(() => {
-      if (this.state.hiddenSessionIds.includes(session.id)) return null
-      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
-      const thread = this.dshThread(workspace, session)
-      this.projectEventInto(workspace, thread, event)
-      return structuredClone(thread)
-    }, { deferred: true })
-  }
-
-  /** Project a batch of committed events for one session in a single write. */
-  async projectEvents(session, events, workspaceTitle = 'DSH 任务') {
-    if (events.length === 0) return null
-    return this.mutate(() => {
-      if (this.state.hiddenSessionIds.includes(session.id)) return null
-      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
-      const thread = this.dshThread(workspace, session)
-      for (const event of events) this.projectEventInto(workspace, thread, event)
-      return structuredClone(thread)
-    }, { deferred: true })
-  }
-
-  async load() {
-    await mkdir(dirname(this.dataFile), { recursive: true })
-    try {
-      const parsed = JSON.parse(await readFile(this.dataFile, 'utf8'))
-      const { state, migrated } = normalizeState(parsed)
-      this.state = state
-      if (migrated) await this.save()
-    } catch (error) {
-      if (error?.code !== 'ENOENT') throw new Error(`synapse: cannot read ${this.dataFile}: ${error.message}`)
-      this.state = { version: 4, hiddenSessionIds: [], workspaces: [] }
-      await this.save()
-    }
-  }
-
-  async mutate(action, { deferred = false } = {}) {
-    await this.ready
-    const task = this.serial.then(async () => {
-      const result = action()
-      if (deferred) this.markDirty()
-      else await this.save()
-      return result
-    })
-    this.serial = task.catch(() => undefined)
-    return task
-  }
-
-  /** Mark the state dirty and schedule one trailing flush for the window. */
-  markDirty() {
-    this.dirty = true
-    if (this.flushTimer !== null) return
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null
-      void this.flush()
-    }, SAVE_DEBOUNCE_MS)
-  }
-
-  /** Persist the current state when dirty, ordered after in-flight mutations. */
-  flush() {
-    if (!this.dirty) return Promise.resolve()
-    this.dirty = false
-    const task = this.serial.then(() => this.save())
-    this.serial = task.catch(() => undefined)
-    return task
-  }
-
-  async save() {
-    // Two dsh web instances sharing one profile clobber each other's canvas
-    // state. Warn loudly instead of silently losing work; a live lock held by
-    // another process or a file mtime that moved since our last write both
-    // indicate a second writer.
-    const before = await this.fileMtime()
-    if (this.lastKnownMtime !== null && before !== null && before !== this.lastKnownMtime) {
-      this.lastKnownMtime = before
-      if (!this.externalModWarned) {
-        this.externalModWarned = true
-        process.stderr.write('synapse: workspaces.json 已被另一个 dsh web 实例修改，本实例的写入可能覆盖其更改——请只运行一个实例\n')
-      }
-    }
-    await this.acquireLock()
-    try {
-      const temporaryFile = `${this.dataFile}.${process.pid}.tmp`
-      await writeFile(temporaryFile, `${JSON.stringify(this.state)}\n`, 'utf8')
-      await rename(temporaryFile, this.dataFile)
-      this.lastKnownMtime = (await stat(this.dataFile)).mtimeMs
-    } finally {
-      await this.releaseLock()
-    }
-  }
-
-  async fileMtime() {
-    try { return (await stat(this.dataFile)).mtimeMs } catch { return null }
-  }
-
-  /** Take an exclusive cross-process lock, breaking a stale one; warn when a live process holds it. */
-  async acquireLock() {
-    const lockFile = `${this.dataFile}.lock`
-    if (await this.tryAcquire(lockFile)) return
-    if (await this.lockIsStale(lockFile)) {
-      await unlink(lockFile).catch(() => {})
-      if (await this.tryAcquire(lockFile)) return
-    }
-    if (!this.lockWarned) {
-      this.lockWarned = true
-      process.stderr.write('synapse: 另一个 dsh web 实例正在写入 workspaces.json——请只运行一个实例，否则画布数据可能互相覆盖\n')
-    }
-  }
-
-  async tryAcquire(lockFile) {
-    try {
-      await writeFile(lockFile, `${process.pid}\n`, { flag: 'wx' })
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  /** A lock is stale when its owner PID is gone or the lock file is older than the stale window. */
-  async lockIsStale(lockFile) {
-    try {
-      const [content, stats] = await Promise.all([readFile(lockFile, 'utf8'), stat(lockFile)])
-      const tooOld = Date.now() - stats.mtimeMs > LOCK_STALE_MS
-      const pid = Number.parseInt(content, 10)
-      if (!Number.isInteger(pid)) return tooOld
-      if (pid === process.pid) return false
-      try {
-        process.kill(pid, 0)
-        return tooOld
-      } catch {
-        return true
-      }
-    } catch {
-      return false
-    }
-  }
-
-  async releaseLock() {
-    await unlink(`${this.dataFile}.lock`).catch(() => {})
-  }
-
-  workspace(workspaceId) {
-    const workspace = this.state.workspaces.find(item => item.id === workspaceId)
-    if (workspace === undefined) throw new NotFoundError('工作空间不存在')
-    return workspace
-  }
-
-  locateThread(threadId) {
-    for (const workspace of this.state.workspaces) {
-      const thread = workspace.threads.find(item => item.id === threadId)
-      if (thread !== undefined) return { workspace, thread }
-    }
-    throw new NotFoundError('节点不存在')
-  }
-
-  dshWorkspace(cwd, fallbackTitle) {
-    let workspace = this.state.workspaces.find(item => item.kind === 'dsh' && item.cwd === cwd)
-    if (workspace !== undefined) return workspace
-    const now = new Date().toISOString()
-    workspace = { id: randomUUID(), kind: 'dsh', cwd, title: workspaceTitle(cwd, fallbackTitle), createdAt: now, updatedAt: now, threads: [] }
-    this.state.workspaces.unshift(workspace)
-    return workspace
-  }
-
-  dshThread(workspace, session) {
-    let thread = workspace.threads.find(item => item.dshSessionId === session.id)
-    if (thread !== undefined) {
-      if (typeof session.title === 'string' && session.title.trim() !== '') {
-        const title = session.title.slice(0, MAX_TITLE_LENGTH)
-        thread.title = title
-        thread.dshSessionTitle = title
-      }
-      // `seedLength` is DSH's durable fork cut. Keep it even after the
-      // session has been restored, when its in-process `firstLiveSeq` moves.
-      const seedLength = session.header?.seedLength
-      if (Number.isSafeInteger(seedLength) && seedLength >= 0) thread.sourceSeedLength = seedLength
-      return thread
-    }
-    const parentSessionId = typeof session.header?.parentSession === 'string' ? session.header.parentSession : null
-    const parent = parentSessionId === null ? undefined : workspace.threads.find(item => item.dshSessionId === parentSessionId)
-    const siblings = workspace.threads.filter(item => item.sourceParentSessionId === parentSessionId)
-    const now = new Date().toISOString()
-    thread = {
-      id: randomUUID(),
-      title: typeof session.title === 'string' && session.title.trim() !== '' ? session.title.slice(0, MAX_TITLE_LENGTH) : (parent === undefined ? 'DSH 会话' : `${parent.title} 分支`),
-      parentId: parent?.id ?? null,
-      sourceParentSessionId: parentSessionId,
-      sourceSeedLength: Number.isSafeInteger(session.header?.seedLength) && session.header.seedLength >= 0 ? session.header.seedLength : null,
-      dshSessionId: session.id,
-      dshSessionTitle: typeof session.title === 'string' ? session.title.slice(0, MAX_TITLE_LENGTH) : null,
-      color: TOPIC_COLORS[workspace.threads.length % TOPIC_COLORS.length],
-      // DSH projection stores only a neutral semantic anchor. The visual map
-      // lays out visible cards from the current conversation graph each render,
-      // so old/archived session counts must never leak into future coordinates.
-      position: parent === undefined ? { x: 86, y: 82 } : { x: parent.position.x + 400, y: parent.position.y },
+import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { dirname } from 'node:path'
+
+export const name = 'synapse'
+export const inject = ['webServer', 'sessions']
+
+const MAX_BODY_BYTES = 32 * 1024
+const MAX_TITLE_LENGTH = 120
+const MAX_NOTE_LENGTH = 4_000
+// Projected message text cap: longer replies truncate with a marker pointing
+// at the detail view instead of silently cutting mid-sentence.
+const MAX_PROJECTION_LENGTH = 8_000
+const PROJECTION_TRUNCATED_SUFFIX = '\n——…（详情查看全文）'
+const TOPIC_COLORS = ['#0f766e', '#2563eb', '#be123c', '#7c3aed', '#b45309']
+const LOCK_STALE_MS = 60_000
+// Deferred (event-projection) writes coalesce into one save per window, so a
+// burst of session events costs a single full-state write instead of one per
+// event (issue #13: per-event saves pinned the main thread at ~90% CPU).
+const SAVE_DEBOUNCE_MS = 800
+
+/** JSON persistence for the Synapse workspace graph. */
+export class WorkspaceStore {
+  constructor(dataFile) {
+    if (typeof dataFile !== 'string' || dataFile.length === 0) throw new Error('synapse: config.dataFile must be a non-empty path')
+    this.dataFile = dataFile
+    this.state = undefined
+    this.serial = Promise.resolve()
+    this.ready = this.load()
+    this.lastKnownMtime = null
+    this.externalModWarned = false
+    this.lockWarned = false
+    this.dirty = false
+    this.flushTimer = null
+  }
+
+  async list() {
+    await this.ready
+    return this.state.workspaces.map(workspace => this.summary(workspace))
+  }
+
+  async get(workspaceId) {
+    await this.ready
+    const workspace = this.workspace(workspaceId)
+    return structuredClone(workspace)
+  }
+
+  async create(title) {
+    return this.mutate(() => {
+      const now = new Date().toISOString()
+      const workspace = { id: randomUUID(), title: requiredText(title, MAX_TITLE_LENGTH, 'title'), createdAt: now, updatedAt: now, threads: [] }
+      this.state.workspaces.unshift(workspace)
+      return this.summary(workspace)
+    })
+  }
+
+  async createThread(workspaceId, input) {
+    return this.mutate(() => {
+      const workspace = this.workspace(workspaceId)
+      const now = new Date().toISOString()
+      const thread = this.thread({
+        title: input?.title,
+        parentId: input?.parentId,
+        dshSessionId: input?.dshSessionId,
+        dshSessionTitle: input?.dshSessionTitle,
+        position: input?.position,
+        color: input?.color,
+        now,
+        order: workspace.threads.length,
+      })
+      if (thread.parentId !== null && !workspace.threads.some(item => item.id === thread.parentId)) throw new InputError('分支来源不存在')
+      workspace.threads.push(thread)
+      workspace.updatedAt = now
+      return structuredClone(thread)
+    })
+  }
+
+  async branch(threadId, input) {
+    return this.mutate(() => {
+      const { workspace, thread: parent } = this.locateThread(threadId)
+      const now = new Date().toISOString()
+      const sessionId = typeof input?.dshSessionId === 'string' && input.dshSessionId.length > 0 ? input.dshSessionId : null
+      // A DSH fork emits session/created while the browser receives its fork
+      // response. Either path may win the race, but both must resolve to one node.
+      if (sessionId !== null) {
+        const existing = workspace.threads.find(item => item.dshSessionId === sessionId)
+        if (existing !== undefined) {
+          existing.parentId ??= parent.id
+          if (typeof input?.title === 'string' && input.title.trim() !== '') existing.title = requiredText(input.title, MAX_TITLE_LENGTH, 'title')
+          if (typeof input?.dshSessionTitle === 'string') existing.dshSessionTitle = input.dshSessionTitle.slice(0, MAX_TITLE_LENGTH)
+          existing.updatedAt = now
+          workspace.updatedAt = now
+          return structuredClone(existing)
+        }
+      }
+      const siblings = workspace.threads.filter(item => item.parentId === parent.id)
+      const thread = this.thread({
+        title: input?.title,
+        parentId: parent.id,
+        dshSessionId: input?.dshSessionId,
+        dshSessionTitle: input?.dshSessionTitle,
+        position: input?.position ?? { x: parent.position.x + 420, y: parent.position.y + siblings.length * 248 },
+        color: input?.color ?? parent.color,
+        now,
+        order: workspace.threads.length,
+      })
+      workspace.threads.push(thread)
+      workspace.updatedAt = now
+      return structuredClone(thread)
+    })
+  }
+
+  /** Keep only the canvas graph in Synapse; DSH remains the source of session truth. */
+  async syncSessions(sessions, removedSessionIds = []) {
+    return this.mutate(() => {
+      if (!Array.isArray(sessions)) throw new InputError('sessions 必须是数组')
+      if (!Array.isArray(removedSessionIds) || removedSessionIds.some(item => typeof item !== 'string')) throw new InputError('removedSessionIds 必须是字符串数组')
+      const blankIds = new Set(sessions.filter(item => item?.blank === true && typeof item.id === 'string').map(item => item.id))
+      const removedIds = new Set(removedSessionIds)
+      for (const workspace of this.state.workspaces) {
+        if (workspace.kind !== 'dsh') continue
+        workspace.threads = workspace.threads.filter(thread => !blankIds.has(thread.dshSessionId) && !removedIds.has(thread.dshSessionId))
+      }
+      this.state.workspaces = this.state.workspaces.filter(workspace => workspace.kind !== 'dsh' || workspace.threads.length > 0)
+      for (const item of sessions) {
+        if (typeof item?.id !== 'string' || item.id === '' || typeof item.cwd !== 'string' || item.cwd === '') continue
+        if (item.blank === true) continue
+        // Canvas archiving is persistent UI state. A normal DSH list refresh
+        // must not recreate a session that the user deliberately archived.
+        if (this.state.hiddenSessionIds.includes(item.id)) continue
+        const workspace = this.dshWorkspace(item.cwd, 'DSH 任务')
+        const session = { id: item.id, header: { meta: { cwd: item.cwd }, parentSession: typeof item.parentId === 'string' ? item.parentId : undefined }, title: typeof item.title === 'string' ? item.title : undefined, events: [] }
+        const thread = this.dshThread(workspace, session)
+        if (typeof item.title === 'string' && item.title.trim() !== '') {
+          thread.title = item.title.slice(0, MAX_TITLE_LENGTH)
+          thread.dshSessionTitle = thread.title
+        }
+      }
+      return this.list()
+    }, { deferred: true })
+  }
+
+  async addMessage(threadId, text) {
+    return this.mutate(() => {
+      const { workspace, thread } = this.locateThread(threadId)
+      const at = new Date().toISOString()
+      const message = { id: randomUUID(), text: requiredText(text, MAX_NOTE_LENGTH, 'text'), kind: 'user', at }
+      thread.messages.push(message)
+      thread.updatedAt = at
+      workspace.updatedAt = at
+      return structuredClone(thread)
+    })
+  }
+
+  async updateThread(threadId, input) {
+    return this.mutate(() => {
+      const { workspace, thread } = this.locateThread(threadId)
+      if (input?.title !== undefined) thread.title = requiredText(input.title, MAX_TITLE_LENGTH, 'title')
+      if (input?.position !== undefined) thread.position = positionOf(input.position)
+      thread.updatedAt = new Date().toISOString()
+      workspace.updatedAt = thread.updatedAt
+      return structuredClone(thread)
+    })
+  }
+
+  async removeThread(threadId) {
+    return this.mutate(() => {
+      const { workspace, thread } = this.locateThread(threadId)
+      const removal = new Set([thread.id])
+      for (let changed = true; changed;) {
+        changed = false
+        for (const item of workspace.threads) {
+          if (item.parentId !== null && removal.has(item.parentId) && !removal.has(item.id)) { removal.add(item.id); changed = true }
+        }
+      }
+      for (const item of workspace.threads) {
+        if (removal.has(item.id) && item.dshSessionId !== null && !this.state.hiddenSessionIds.includes(item.dshSessionId)) this.state.hiddenSessionIds.push(item.dshSessionId)
+      }
+      workspace.threads = workspace.threads.filter(item => !removal.has(item.id))
+      workspace.updatedAt = new Date().toISOString()
+      if (workspace.threads.length === 0) this.state.workspaces = this.state.workspaces.filter(item => item.id !== workspace.id)
+      return { removed: removal.size }
+    })
+  }
+
+  async clearLegacy(sessions) {
+    return this.mutate(() => {
+      const hidden = new Set(this.state.hiddenSessionIds)
+      for (const workspace of this.state.workspaces) for (const thread of workspace.threads) if (thread.dshSessionId !== null) hidden.add(thread.dshSessionId)
+      for (const session of sessions) hidden.add(session.id)
+      this.state.hiddenSessionIds = [...hidden]
+      this.state.workspaces = []
+      return { cleared: true }
+    })
+  }
+
+  /** Replay one live DSH session into the dedicated projection workspace. */
+  async projectSession(session, replayFrom = 0, workspaceTitle = 'DSH 任务') {
+    return this.mutate(() => {
+      if (this.state.hiddenSessionIds.includes(session.id)) return null
+      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
+      const thread = this.dshThread(workspace, session)
+      // `snapshotEvents()` replaces the removed `session.events` getter. It is
+      // marked deprecated because DSH is moving complete logs out of memory, but
+      // rebuilding this canvas from history needs the full sequence and the
+      // reader is the only complete-log access a plugin still has.
+      for (const event of session.snapshotEvents()) {
+        if (event.seq >= replayFrom) this.projectEventInto(workspace, thread, event)
+      }
+      return structuredClone(thread)
+    }, { deferred: true })
+  }
+
+  /** Project one committed DSH session event. Repeated sequence numbers are ignored. */
+  async projectEvent(session, event, workspaceTitle = 'DSH 任务') {
+    return this.mutate(() => {
+      if (this.state.hiddenSessionIds.includes(session.id)) return null
+      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
+      const thread = this.dshThread(workspace, session)
+      this.projectEventInto(workspace, thread, event)
+      return structuredClone(thread)
+    }, { deferred: true })
+  }
+
+  /** Project a batch of committed events for one session in a single write. */
+  async projectEvents(session, events, workspaceTitle = 'DSH 任务') {
+    if (events.length === 0) return null
+    return this.mutate(() => {
+      if (this.state.hiddenSessionIds.includes(session.id)) return null
+      const workspace = this.dshWorkspace(sessionCwd(session), workspaceTitle)
+      const thread = this.dshThread(workspace, session)
+      for (const event of events) this.projectEventInto(workspace, thread, event)
+      return structuredClone(thread)
+    }, { deferred: true })
+  }
+
+  async load() {
+    await mkdir(dirname(this.dataFile), { recursive: true })
+    try {
+      const parsed = JSON.parse(await readFile(this.dataFile, 'utf8'))
+      const { state, migrated } = normalizeState(parsed)
+      this.state = state
+      if (migrated) await this.save()
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw new Error(`synapse: cannot read ${this.dataFile}: ${error.message}`)
+      this.state = { version: 4, hiddenSessionIds: [], workspaces: [] }
+      await this.save()
+    }
+  }
+
+  async mutate(action, { deferred = false } = {}) {
+    await this.ready
+    const task = this.serial.then(async () => {
+      const result = action()
+      if (deferred) this.markDirty()
+      else await this.save()
+      return result
+    })
+    this.serial = task.catch(() => undefined)
+    return task
+  }
+
+  /** Mark the state dirty and schedule one trailing flush for the window. */
+  markDirty() {
+    this.dirty = true
+    if (this.flushTimer !== null) return
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null
+      void this.flush()
+    }, SAVE_DEBOUNCE_MS)
+  }
+
+  /** Persist the current state when dirty, ordered after in-flight mutations. */
+  flush() {
+    if (!this.dirty) return Promise.resolve()
+    this.dirty = false
+    const task = this.serial.then(() => this.save())
+    this.serial = task.catch(() => undefined)
+    return task
+  }
+
+  async save() {
+    // Two dsh web instances sharing one profile clobber each other's canvas
+    // state. Warn loudly instead of silently losing work; a live lock held by
+    // another process or a file mtime that moved since our last write both
+    // indicate a second writer.
+    const before = await this.fileMtime()
+    if (this.lastKnownMtime !== null && before !== null && before !== this.lastKnownMtime) {
+      this.lastKnownMtime = before
+      if (!this.externalModWarned) {
+        this.externalModWarned = true
+        process.stderr.write('synapse: workspaces.json 已被另一个 dsh web 实例修改，本实例的写入可能覆盖其更改——请只运行一个实例\n')
+      }
+    }
+    await this.acquireLock()
+    try {
+      const temporaryFile = `${this.dataFile}.${process.pid}.tmp`
+      await writeFile(temporaryFile, `${JSON.stringify(this.state)}\n`, 'utf8')
+      await rename(temporaryFile, this.dataFile)
+      this.lastKnownMtime = (await stat(this.dataFile)).mtimeMs
+    } finally {
+      await this.releaseLock()
+    }
+  }
+
+  async fileMtime() {
+    try { return (await stat(this.dataFile)).mtimeMs } catch { return null }
+  }
+
+  /** Take an exclusive cross-process lock, breaking a stale one; warn when a live process holds it. */
+  async acquireLock() {
+    const lockFile = `${this.dataFile}.lock`
+    if (await this.tryAcquire(lockFile)) return
+    if (await this.lockIsStale(lockFile)) {
+      await unlink(lockFile).catch(() => {})
+      if (await this.tryAcquire(lockFile)) return
+    }
+    if (!this.lockWarned) {
+      this.lockWarned = true
+      process.stderr.write('synapse: 另一个 dsh web 实例正在写入 workspaces.json——请只运行一个实例，否则画布数据可能互相覆盖\n')
+    }
+  }
+
+  async tryAcquire(lockFile) {
+    try {
+      await writeFile(lockFile, `${process.pid}\n`, { flag: 'wx' })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /** A lock is stale when its owner PID is gone or the lock file is older than the stale window. */
+  async lockIsStale(lockFile) {
+    try {
+      const [content, stats] = await Promise.all([readFile(lockFile, 'utf8'), stat(lockFile)])
+      const tooOld = Date.now() - stats.mtimeMs > LOCK_STALE_MS
+      const pid = Number.parseInt(content, 10)
+      if (!Number.isInteger(pid)) return tooOld
+      if (pid === process.pid) return false
+      try {
+        process.kill(pid, 0)
+        return tooOld
+      } catch {
+        return true
+      }
+    } catch {
+      return false
+    }
+  }
+
+  async releaseLock() {
+    await unlink(`${this.dataFile}.lock`).catch(() => {})
+  }
+
+  workspace(workspaceId) {
+    const workspace = this.state.workspaces.find(item => item.id === workspaceId)
+    if (workspace === undefined) throw new NotFoundError('工作空间不存在')
+    return workspace
+  }
+
+  locateThread(threadId) {
+    for (const workspace of this.state.workspaces) {
+      const thread = workspace.threads.find(item => item.id === threadId)
+      if (thread !== undefined) return { workspace, thread }
+    }
+    throw new NotFoundError('节点不存在')
+  }
+
+  dshWorkspace(cwd, fallbackTitle) {
+    let workspace = this.state.workspaces.find(item => item.kind === 'dsh' && item.cwd === cwd)
+    if (workspace !== undefined) return workspace
+    const now = new Date().toISOString()
+    workspace = { id: randomUUID(), kind: 'dsh', cwd, title: workspaceTitle(cwd, fallbackTitle), createdAt: now, updatedAt: now, threads: [] }
+    this.state.workspaces.unshift(workspace)
+    return workspace
+  }
+
+  dshThread(workspace, session) {
+    let thread = workspace.threads.find(item => item.dshSessionId === session.id)
+    if (thread !== undefined) {
+      if (typeof session.title === 'string' && session.title.trim() !== '') {
+        const title = session.title.slice(0, MAX_TITLE_LENGTH)
+        thread.title = title
+        thread.dshSessionTitle = title
+      }
+      // `inheritedEventCount` is DSH's durable fork cut, the successor of the
+      // removed `header.seedLength`. It survives restore, unlike `firstLiveSeq`.
+      const seedLength = session.inheritedEventCount
+      if (Number.isSafeInteger(seedLength) && seedLength >= 0) thread.sourceSeedLength = seedLength
+      return thread
+    }
+    const parentSessionId = typeof session.header?.parentSession === 'string' ? session.header.parentSession : null
+    const parent = parentSessionId === null ? undefined : workspace.threads.find(item => item.dshSessionId === parentSessionId)
+    const siblings = workspace.threads.filter(item => item.sourceParentSessionId === parentSessionId)
+    const now = new Date().toISOString()
+    thread = {
+      id: randomUUID(),
+      title: typeof session.title === 'string' && session.title.trim() !== '' ? session.title.slice(0, MAX_TITLE_LENGTH) : (parent === undefined ? 'DSH 会话' : `${parent.title} 分支`),
+      parentId: parent?.id ?? null,
+      sourceParentSessionId: parentSessionId,
+      sourceSeedLength: Number.isSafeInteger(session.inheritedEventCount) && session.inheritedEventCount >= 0 ? session.inheritedEventCount : null,
+      dshSessionId: session.id,
+      dshSessionTitle: typeof session.title === 'string' ? session.title.slice(0, MAX_TITLE_LENGTH) : null,
+      color: TOPIC_COLORS[workspace.threads.length % TOPIC_COLORS.length],
+      // DSH projection stores only a neutral semantic anchor. The visual map
+      // lays out visible cards from the current conversation graph each render,
+      // so old/archived session counts must never leak into future coordinates.
+      position: parent === undefined ? { x: 86, y: 82 } : { x: parent.position.x + 400, y: parent.position.y },
       createdAt: now,
       updatedAt: now,
       messages: [],
       pendingProcess: [],
-    }
-    workspace.threads.push(thread)
-    // A child may arrive before its parent during startup replay. Repair that
-    // relation when the missing parent later reaches the projection.
-    for (const child of workspace.threads) {
-      if (child.sourceParentSessionId === session.id && child.parentId === null) child.parentId = thread.id
-    }
-    workspace.updatedAt = now
-    return thread
-  }
-
-  projectEventInto(workspace, thread, event) {
-    if (event.type === 'session/title' && typeof event.data?.title === 'string') {
-      thread.title = event.data.title.slice(0, MAX_TITLE_LENGTH)
-      thread.dshSessionTitle = thread.title
-      thread.updatedAt = new Date(event.time).toISOString()
-      workspace.updatedAt = thread.updatedAt
-      return
-    }
-    if (event.type === 'tool/call' || event.type === 'tool/result') {
-      this.foldToolProcess(thread, event)
-      workspace.updatedAt = thread.updatedAt
-      return
-    }
-    const projection = projectableEvent(event)
-    if (projection === null || thread.messages.some(message => message.sourceSeq === event.seq)) return
-    const at = new Date(event.time).toISOString()
-    const message = {
-      id: randomUUID(),
-      text: projection.text,
-      kind: projection.kind,
-      sourceSeq: event.seq,
-      at,
+    }
+    workspace.threads.push(thread)
+    // A child may arrive before its parent during startup replay. Repair that
+    // relation when the missing parent later reaches the projection.
+    for (const child of workspace.threads) {
+      if (child.sourceParentSessionId === session.id && child.parentId === null) child.parentId = thread.id
+    }
+    workspace.updatedAt = now
+    return thread
+  }
+
+  projectEventInto(workspace, thread, event) {
+    if (event.type === 'session/title' && typeof event.data?.title === 'string') {
+      thread.title = event.data.title.slice(0, MAX_TITLE_LENGTH)
+      thread.dshSessionTitle = thread.title
+      thread.updatedAt = new Date(event.time).toISOString()
+      workspace.updatedAt = thread.updatedAt
+      return
+    }
+    if (event.type === 'tool/call' || event.type === 'tool/result') {
+      this.foldToolProcess(thread, event)
+      workspace.updatedAt = thread.updatedAt
+      return
+    }
+    const projection = projectableEvent(event)
+    if (projection === null || thread.messages.some(message => message.sourceSeq === event.seq)) return
+    const at = new Date(event.time).toISOString()
+    const message = {
+      id: randomUUID(),
+      text: projection.text,
+      kind: projection.kind,
+      sourceSeq: event.seq,
+      at,
       ...(projection.kind === 'assistant' || projection.kind === 'error'
         ? { turn: event.data?.turn, step: event.data?.step, process: [] }
         : {}),
     }
     this.attachPendingProcess(thread, message)
-    thread.messages.push(message)
-    thread.updatedAt = at
-    workspace.updatedAt = at
-    if (thread.dshSessionTitle === null && projection.kind === 'user') {
-      thread.title = titleFromText(projection.text)
-      thread.dshSessionTitle = thread.title
-    }
-  }
-
-  /**
-   * Fold one tool call or result into the assistant message of its own
+    thread.messages.push(message)
+    thread.updatedAt = at
+    workspace.updatedAt = at
+    if (thread.dshSessionTitle === null && projection.kind === 'user') {
+      thread.title = titleFromText(projection.text)
+      thread.dshSessionTitle = thread.title
+    }
+  }
+
+  /**
+   * Fold one tool call or result into the assistant message of its own
    * turn/step, keyed by `callId`, so a tool invocation never becomes a
    * separate canvas card. If a tool result arrives before its associated
    * assistant/error message, retain it on the thread until that turn appears.
-   */
+   */
   foldToolProcess(thread, event) {
     const at = new Date(event.time).toISOString()
     const data = event.data ?? {}
@@ -482,11 +486,11 @@ export class WorkspaceStore {
       const error = errorText(data.error)
       if (entry === undefined) {
         process.push({ callId, turn: data.turn, step: data.step, name: '工具调用', arguments: null, result: outcome, error })
-      } else {
-        entry.result = outcome
-        entry.error = error
-      }
-    }
+      } else {
+        entry.result = outcome
+        entry.error = error
+      }
+    }
     thread.updatedAt = at
   }
 
@@ -497,157 +501,157 @@ export class WorkspaceStore {
     message.process.push(...matching.map(({ turn, step, ...entry }) => entry))
     thread.pendingProcess = thread.pendingProcess.filter(entry => entry.turn !== message.turn || entry.step !== message.step)
   }
-
-  thread({ title, parentId, dshSessionId, dshSessionTitle, position, color, now, order }) {
-    return {
-      id: randomUUID(),
-      title: requiredText(title, MAX_TITLE_LENGTH, 'title'),
-      parentId: typeof parentId === 'string' && parentId.length > 0 ? parentId : null,
-      dshSessionId: typeof dshSessionId === 'string' && dshSessionId.length > 0 ? dshSessionId : null,
-      dshSessionTitle: typeof dshSessionTitle === 'string' ? dshSessionTitle.slice(0, MAX_TITLE_LENGTH) : null,
-      color: TOPIC_COLORS.includes(color) ? color : TOPIC_COLORS[order % TOPIC_COLORS.length],
-      position: positionOf(position ?? { x: 86 + (order % 3) * 410, y: 82 + Math.floor(order / 3) * 260 }),
-      createdAt: now,
+
+  thread({ title, parentId, dshSessionId, dshSessionTitle, position, color, now, order }) {
+    return {
+      id: randomUUID(),
+      title: requiredText(title, MAX_TITLE_LENGTH, 'title'),
+      parentId: typeof parentId === 'string' && parentId.length > 0 ? parentId : null,
+      dshSessionId: typeof dshSessionId === 'string' && dshSessionId.length > 0 ? dshSessionId : null,
+      dshSessionTitle: typeof dshSessionTitle === 'string' ? dshSessionTitle.slice(0, MAX_TITLE_LENGTH) : null,
+      color: TOPIC_COLORS.includes(color) ? color : TOPIC_COLORS[order % TOPIC_COLORS.length],
+      position: positionOf(position ?? { x: 86 + (order % 3) * 410, y: 82 + Math.floor(order / 3) * 260 }),
+      createdAt: now,
       updatedAt: now,
       messages: [],
       pendingProcess: [],
-    }
-  }
-
-  summary(workspace) {
-    return { id: workspace.id, kind: workspace.kind ?? 'manual', cwd: workspace.cwd ?? null, title: workspace.title, createdAt: workspace.createdAt, updatedAt: workspace.updatedAt, threadCount: workspace.threads.length }
-  }
-}
-
-class InputError extends Error {}
-class NotFoundError extends Error {}
-
-function normalizeState(value) {
-  let migrated = false
-  let state
-  if ((value?.version === 2 || value?.version === 3 || value?.version === 4) && Array.isArray(value.workspaces)) {
-    const hiddenSessionIds = Array.isArray(value.hiddenSessionIds) ? value.hiddenSessionIds.filter(item => typeof item === 'string') : []
-    migrated = value.version < 3 || !Array.isArray(value.hiddenSessionIds)
-    const workspaces = value.workspaces.map(workspace => ({
-      ...workspace,
-      threads: Array.isArray(workspace.threads) ? workspace.threads.map(thread => {
-        if (Array.isArray(thread.messages)) {
-          const messages = thread.messages.filter(message => !isRuntimeContextMessage(message))
-          if (messages.length !== thread.messages.length) migrated = true
+    }
+  }
+
+  summary(workspace) {
+    return { id: workspace.id, kind: workspace.kind ?? 'manual', cwd: workspace.cwd ?? null, title: workspace.title, createdAt: workspace.createdAt, updatedAt: workspace.updatedAt, threadCount: workspace.threads.length }
+  }
+}
+
+class InputError extends Error {}
+class NotFoundError extends Error {}
+
+function normalizeState(value) {
+  let migrated = false
+  let state
+  if ((value?.version === 2 || value?.version === 3 || value?.version === 4) && Array.isArray(value.workspaces)) {
+    const hiddenSessionIds = Array.isArray(value.hiddenSessionIds) ? value.hiddenSessionIds.filter(item => typeof item === 'string') : []
+    migrated = value.version < 3 || !Array.isArray(value.hiddenSessionIds)
+    const workspaces = value.workspaces.map(workspace => ({
+      ...workspace,
+      threads: Array.isArray(workspace.threads) ? workspace.threads.map(thread => {
+        if (Array.isArray(thread.messages)) {
+          const messages = thread.messages.filter(message => !isRuntimeContextMessage(message))
+          if (messages.length !== thread.messages.length) migrated = true
           return { ...thread, messages }
-        }
-        migrated = true
-        const notes = Array.isArray(thread.notes) ? thread.notes : []
-        const { notes: _notes, ...rest } = thread
+        }
+        migrated = true
+        const notes = Array.isArray(thread.notes) ? thread.notes : []
+        const { notes: _notes, ...rest } = thread
         return { ...rest, messages: notes, pendingProcess: [] }
-      }) : [],
-    }))
-    state = { ...value, version: value.version, hiddenSessionIds, workspaces }
-  } else if (value?.version === 1 && Array.isArray(value.workspaces)) {
-    const now = typeof value.updatedAt === 'string' ? value.updatedAt : new Date().toISOString()
-    state = {
-      version: 3,
-      hiddenSessionIds: [],
-      workspaces: value.workspaces.map((workspace, index) => {
-        const events = Array.isArray(workspace.events) ? workspace.events : []
-        const workspaceNow = typeof workspace.updatedAt === 'string' ? workspace.updatedAt : now
-        return {
-          id: typeof workspace.id === 'string' ? workspace.id : randomUUID(),
-          title: typeof workspace.title === 'string' && workspace.title.trim() ? workspace.title : '未命名工作空间',
-          createdAt: typeof workspace.createdAt === 'string' ? workspace.createdAt : workspaceNow,
-          updatedAt: workspaceNow,
-          threads: events.length === 0 ? [] : [{
-            id: randomUUID(), title: workspace.title || '历史记录', parentId: null, dshSessionId: null, dshSessionTitle: null,
-            color: TOPIC_COLORS[index % TOPIC_COLORS.length], position: { x: 86, y: 82 }, createdAt: workspaceNow, updatedAt: workspaceNow,
-            messages: events.map(event => ({ id: typeof event.id === 'string' ? event.id : randomUUID(), text: String(event.text ?? ''), at: typeof event.at === 'string' ? event.at : workspaceNow })),
-          }],
-        }
-      }),
-    }
-    migrated = true
-  } else {
-    throw new Error('expected Synapse data version 1, 2, 3, or 4')
-  }
-  if (state.version !== 4) {
-    if (foldLegacyToolCards(state.workspaces)) migrated = true
-    state.version = 4
-    migrated = true
-  }
-  return { state, migrated }
-}
-
-/**
- * Fold v3-era standalone tool cards (kinds `tool` / `tool-result`) into the
- * preceding assistant message's `process` list, pairing each call with the
- * result that follows it in order, so every tool invocation lives in one
- * home: the assistant turn card.
- */
-function foldLegacyToolCards(workspaces) {
-  let changed = false
-  for (const workspace of workspaces) {
-    for (const thread of workspace.threads ?? []) {
-      if (!Array.isArray(thread.messages)) continue
-      const folded = []
-      let assistant = null
-      let pending = []
-      for (const message of thread.messages) {
-        if (message.kind === 'assistant') {
-          assistant = message
-          assistant.process ??= []
-          pending = []
-          folded.push(message)
-          continue
-        }
-        if (message.kind !== 'tool' && message.kind !== 'tool-result') {
-          folded.push(message)
-          continue
-        }
-        if (assistant === null) {
-          folded.push(message)
-          continue
-        }
-        changed = true
-        if (message.kind === 'tool') {
-          const [name = '工具调用', ...argumentLines] = message.text.split('\n')
-          const entry = { callId: `legacy-${assistant.process.length}`, name, arguments: argumentLines.join('\n'), result: null, error: null }
-          pending.push(entry)
-          assistant.process.push(entry)
-        } else {
-          const entry = pending.shift() ?? (() => {
-            const orphan = { callId: `legacy-orphan-${assistant.process.length}`, name: '工具调用', arguments: null, result: null, error: null }
-            assistant.process.push(orphan)
-            return orphan
-          })()
-          entry.result = message.text
-        }
-      }
-      thread.messages = folded
-    }
-  }
-  return changed
-}
-
-function positionOf(value) {
-  const x = Number(value?.x)
-  const y = Number(value?.y)
-  if (!Number.isFinite(x) || !Number.isFinite(y)) throw new InputError('position 必须包含有效坐标')
-  return { x: Math.round(Math.max(-2000, Math.min(5000, x))), y: Math.round(Math.max(-2000, Math.min(5000, y))) }
-}
-
-function requiredText(value, maxLength, field) {
-  if (typeof value !== 'string') throw new InputError(`${field} 必须是文本`)
-  const text = value.trim()
-  if (text.length === 0) throw new InputError(`${field} 不能为空`)
-  if (text.length > maxLength) throw new InputError(`${field} 超过长度限制`)
-  return text
-}
-
-function projectableEvent(event) {
-  switch (event.type) {
-    case 'user/message': {
-      const text = contentText(event.data.content)
-      return isRuntimeContextText(text) ? null : noteProjection('user', text)
-    }
+      }) : [],
+    }))
+    state = { ...value, version: value.version, hiddenSessionIds, workspaces }
+  } else if (value?.version === 1 && Array.isArray(value.workspaces)) {
+    const now = typeof value.updatedAt === 'string' ? value.updatedAt : new Date().toISOString()
+    state = {
+      version: 3,
+      hiddenSessionIds: [],
+      workspaces: value.workspaces.map((workspace, index) => {
+        const events = Array.isArray(workspace.events) ? workspace.events : []
+        const workspaceNow = typeof workspace.updatedAt === 'string' ? workspace.updatedAt : now
+        return {
+          id: typeof workspace.id === 'string' ? workspace.id : randomUUID(),
+          title: typeof workspace.title === 'string' && workspace.title.trim() ? workspace.title : '未命名工作空间',
+          createdAt: typeof workspace.createdAt === 'string' ? workspace.createdAt : workspaceNow,
+          updatedAt: workspaceNow,
+          threads: events.length === 0 ? [] : [{
+            id: randomUUID(), title: workspace.title || '历史记录', parentId: null, dshSessionId: null, dshSessionTitle: null,
+            color: TOPIC_COLORS[index % TOPIC_COLORS.length], position: { x: 86, y: 82 }, createdAt: workspaceNow, updatedAt: workspaceNow,
+            messages: events.map(event => ({ id: typeof event.id === 'string' ? event.id : randomUUID(), text: String(event.text ?? ''), at: typeof event.at === 'string' ? event.at : workspaceNow })),
+          }],
+        }
+      }),
+    }
+    migrated = true
+  } else {
+    throw new Error('expected Synapse data version 1, 2, 3, or 4')
+  }
+  if (state.version !== 4) {
+    if (foldLegacyToolCards(state.workspaces)) migrated = true
+    state.version = 4
+    migrated = true
+  }
+  return { state, migrated }
+}
+
+/**
+ * Fold v3-era standalone tool cards (kinds `tool` / `tool-result`) into the
+ * preceding assistant message's `process` list, pairing each call with the
+ * result that follows it in order, so every tool invocation lives in one
+ * home: the assistant turn card.
+ */
+function foldLegacyToolCards(workspaces) {
+  let changed = false
+  for (const workspace of workspaces) {
+    for (const thread of workspace.threads ?? []) {
+      if (!Array.isArray(thread.messages)) continue
+      const folded = []
+      let assistant = null
+      let pending = []
+      for (const message of thread.messages) {
+        if (message.kind === 'assistant') {
+          assistant = message
+          assistant.process ??= []
+          pending = []
+          folded.push(message)
+          continue
+        }
+        if (message.kind !== 'tool' && message.kind !== 'tool-result') {
+          folded.push(message)
+          continue
+        }
+        if (assistant === null) {
+          folded.push(message)
+          continue
+        }
+        changed = true
+        if (message.kind === 'tool') {
+          const [name = '工具调用', ...argumentLines] = message.text.split('\n')
+          const entry = { callId: `legacy-${assistant.process.length}`, name, arguments: argumentLines.join('\n'), result: null, error: null }
+          pending.push(entry)
+          assistant.process.push(entry)
+        } else {
+          const entry = pending.shift() ?? (() => {
+            const orphan = { callId: `legacy-orphan-${assistant.process.length}`, name: '工具调用', arguments: null, result: null, error: null }
+            assistant.process.push(orphan)
+            return orphan
+          })()
+          entry.result = message.text
+        }
+      }
+      thread.messages = folded
+    }
+  }
+  return changed
+}
+
+function positionOf(value) {
+  const x = Number(value?.x)
+  const y = Number(value?.y)
+  if (!Number.isFinite(x) || !Number.isFinite(y)) throw new InputError('position 必须包含有效坐标')
+  return { x: Math.round(Math.max(-2000, Math.min(5000, x))), y: Math.round(Math.max(-2000, Math.min(5000, y))) }
+}
+
+function requiredText(value, maxLength, field) {
+  if (typeof value !== 'string') throw new InputError(`${field} 必须是文本`)
+  const text = value.trim()
+  if (text.length === 0) throw new InputError(`${field} 不能为空`)
+  if (text.length > maxLength) throw new InputError(`${field} 超过长度限制`)
+  return text
+}
+
+function projectableEvent(event) {
+  switch (event.type) {
+    case 'user/message': {
+      const text = contentText(event.data.content)
+      return isRuntimeContextText(text) ? null : noteProjection('user', text)
+    }
     case 'assistant/message':
       return noteProjection('assistant', contentText(event.data?.message?.content))
     case 'todo/write':
@@ -674,156 +678,159 @@ function errorText(value) {
   if (message !== '') return [name, code].filter(Boolean).concat(message).join(': ')
   return [name, code].filter(Boolean).join(': ') || null
 }
-
-function noteProjection(kind, text) {
-  const normalized = text.trim()
-  if (normalized === '') return null
-  if (normalized.length <= MAX_PROJECTION_LENGTH) return { kind, text: normalized }
-  return { kind, text: `${normalized.slice(0, MAX_PROJECTION_LENGTH)}${PROJECTION_TRUNCATED_SUFFIX}` }
-}
-
-function isRuntimeContextText(text) {
-  return typeof text === 'string' && text.trimStart().startsWith('Current runtime context. This snapshot supersedes earlier runtime-context snapshots.')
-}
-
-function isRuntimeContextMessage(message) {
-  return message?.kind === 'user' && isRuntimeContextText(message.text)
-}
-
-function contentText(content) {
-  if (!Array.isArray(content)) return ''
-  return content.flatMap(block => {
-    if (block?.type === 'text') return [block.text]
-    if (block?.type === 'tool-call') return [block.name, block.arguments]
-    if (block?.type === 'tool-result') return contentText(block.content)
-    return []
-  }).filter(value => typeof value === 'string' && value.trim() !== '').join('\n')
-}
-
-function titleFromText(text) {
-  const line = text.replaceAll(/\s+/g, ' ').trim()
-  return (line.length > 42 ? `${line.slice(0, 42)}...` : line) || 'DSH 会话'
-}
-
-function sessionCwd(session) {
-  const cwd = session.header?.meta?.cwd ?? session.header?.cwd
-  return typeof cwd === 'string' && cwd.trim() !== '' ? cwd : '未指定工作目录'
-}
-
-function workspaceTitle(cwd, fallbackTitle) {
-  if (cwd === '未指定工作目录') return fallbackTitle
-  const segment = cwd.replace(/[\\/]+$/, '').split(/[\\/]/).at(-1)
-  return segment && segment.trim() !== '' ? segment : fallbackTitle
-}
-
-async function readJson(req) {
-  const chunks = []
-  let length = 0
-  for await (const chunk of req) {
-    length += chunk.length
-    if (length > MAX_BODY_BYTES) throw new InputError('请求内容过大')
-    chunks.push(chunk)
-  }
-  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { throw new InputError('请求不是有效 JSON') }
-}
-
-function sendJson(res, status, body) {
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-  res.end(JSON.stringify(body))
-}
-
-function sendFile(res, contentType, body) {
-  res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' })
-  res.end(body)
-}
-
-function page() {
-  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Synapse for DSH</title><link rel="stylesheet" href="/synapse/styles.css"></head><body><div id="app"></div><script src="/synapse/app.js"></script></body></html>`
-}
-
-/** Mount Synapse routes on the existing DSH Web Server. */
-export function apply(ctx, config) {
-  const store = new WorkspaceStore(config?.dataFile)
-  const autoProjection = config?.autoProjection !== false
-  const projectionWorkspaceTitle = typeof config?.projectionWorkspaceTitle === 'string' && config.projectionWorkspaceTitle.trim() !== ''
-    ? config.projectionWorkspaceTitle.trim().slice(0, MAX_TITLE_LENGTH)
-    : 'DSH 任务'
-  const reportProjectionFailure = error => {
-    ctx.logger.warn(error instanceof Error ? error : new Error(String(error)))
-  }
-  const replaySession = session => {
-    // Forks inherit their parent's log. The canvas already represents that
-    // history through the parent node, so only project the child's live tail.
-    const replayFrom = session.header?.parentSession === undefined ? 0 : session.firstLiveSeq
-    void store.projectSession(session, replayFrom, projectionWorkspaceTitle).catch(reportProjectionFailure)
-  }
-  // Buffer live events per session and flush them in one write per microtask,
-  // so a burst of turn events coalesces into a single save instead of N.
-  const projectionQueue = []
-  let projectionScheduled = false
-  const enqueueProjection = (session, event) => {
-    projectionQueue.push({ session, event })
-    if (projectionScheduled) return
-    projectionScheduled = true
-    queueMicrotask(() => {
-      projectionScheduled = false
-      const batch = projectionQueue.splice(0)
-      const bySession = new Map()
-      for (const item of batch) {
-        const entry = bySession.get(item.session.id)
-        if (entry === undefined) bySession.set(item.session.id, [item.session, [item.event]])
-        else entry[1].push(item.event)
-      }
-      for (const [sessionId, [session, events]] of bySession) {
-        void store.projectEvents(session, events, projectionWorkspaceTitle).catch(reportProjectionFailure)
-      }
-    })
-  }
-  if (autoProjection) {
-    ctx.on('session/created', replaySession)
-    ctx.on('session/event', enqueueProjection)
-    for (const session of ctx.sessions.list()) replaySession(session)
-  }
-  // The DSH /api browser-trust fence does not cover /synapse routes, so this
-  // handler checks the Host header itself: localhost is allowed by default and
-  // additional authorities opt in through config.trustedHosts (mirrors the
-  // fence's DNS-rebinding defense).
-  const trustedHosts = new Set(['localhost', '127.0.0.1', ...[...(config?.trustedHosts ?? [])].map(host => String(host).trim().toLowerCase()).filter(Boolean)])
-  const api = async (req, res) => {
-    try {
-      const hostname = (typeof req.headers.host === 'string' ? req.headers.host : '').replace(/:\d+$/, '').toLowerCase()
-      if (!trustedHosts.has(hostname)) return sendJson(res, 403, { error: '不被信任的 Host' })
-      const path = new URL(req.url ?? '/', 'http://dsh.local').pathname
-      if (path === '/synapse/api/reset' && req.method === 'POST') return sendJson(res, 200, await store.clearLegacy(ctx.sessions.list()))
-      if (path === '/synapse/api/workspaces') {
-        if (req.method === 'GET') return sendJson(res, 200, { workspaces: await store.list() })
-        if (req.method === 'POST') return sendJson(res, 201, { workspace: await store.create((await readJson(req)).title) })
-      }
-      const workspace = /^\/synapse\/api\/workspaces\/([0-9a-f-]+)$/i.exec(path)
-      if (workspace !== null) {
-        if (req.method === 'GET') return sendJson(res, 200, { workspace: await store.get(workspace[1]) })
-        if (req.method === 'POST') return sendJson(res, 201, { thread: await store.createThread(workspace[1], await readJson(req)) })
-      }
-      const branch = /^\/synapse\/api\/threads\/([0-9a-f-]+)\/branch$/i.exec(path)
-      if (branch !== null && req.method === 'POST') return sendJson(res, 201, { thread: await store.branch(branch[1], await readJson(req)) })
-      if (path === '/synapse/api/sessions/sync' && req.method === 'POST') { const body = await readJson(req); return sendJson(res, 200, { workspaces: await store.syncSessions(body.sessions, body.removedSessionIds) }) }
-      const messages = /^\/synapse\/api\/threads\/([0-9a-f-]+)\/messages$/i.exec(path)
-      if (messages !== null && req.method === 'POST') return sendJson(res, 201, { thread: await store.addMessage(messages[1], (await readJson(req)).text) })
-      const thread = /^\/synapse\/api\/threads\/([0-9a-f-]+)$/i.exec(path)
-      if (thread !== null && req.method === 'PATCH') return sendJson(res, 200, { thread: await store.updateThread(thread[1], await readJson(req)) })
-      if (thread !== null && req.method === 'DELETE') return sendJson(res, 200, await store.removeThread(thread[1]))
-      return sendJson(res, 404, { error: '接口不存在' })
-    } catch (error) {
-      if (error instanceof InputError) return sendJson(res, 400, { error: error.message })
-      if (error instanceof NotFoundError) return sendJson(res, 404, { error: error.message })
-      ctx.logger.error(error instanceof Error ? error : new Error(String(error)))
-      return sendJson(res, 500, { error: 'Synapse 数据暂时不可用' })
-    }
-  }
-  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse', handler: (_req, res) => { res.writeHead(302, { location: '/synapse/' }); res.end() } }), 'synapse: redirect')
-  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/', handler: (_req, res) => { sendFile(res, 'text/html; charset=utf-8', page()) } }), 'synapse: page')
-  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/app.js', handler: async (_req, res) => { sendFile(res, 'text/javascript; charset=utf-8', await readFile(new URL('./app.js', import.meta.url), 'utf8')) } }), 'synapse: app')
-  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/styles.css', handler: async (_req, res) => { sendFile(res, 'text/css; charset=utf-8', await readFile(new URL('./styles.css', import.meta.url), 'utf8')) } }), 'synapse: styles')
-  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/deepseek-mark.svg', handler: async (_req, res) => { sendFile(res, 'image/svg+xml', await readFile(new URL('./deepseek-mark.svg', import.meta.url), 'utf8')) } }), 'synapse: DeepSeek mark')
-  ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/synapse/api', handler: api }), 'synapse: api')
-}
+
+function noteProjection(kind, text) {
+  const normalized = text.trim()
+  if (normalized === '') return null
+  if (normalized.length <= MAX_PROJECTION_LENGTH) return { kind, text: normalized }
+  return { kind, text: `${normalized.slice(0, MAX_PROJECTION_LENGTH)}${PROJECTION_TRUNCATED_SUFFIX}` }
+}
+
+function isRuntimeContextText(text) {
+  return typeof text === 'string' && text.trimStart().startsWith('Current runtime context. This snapshot supersedes earlier runtime-context snapshots.')
+}
+
+function isRuntimeContextMessage(message) {
+  return message?.kind === 'user' && isRuntimeContextText(message.text)
+}
+
+function contentText(content) {
+  if (!Array.isArray(content)) return ''
+  return content.flatMap(block => {
+    if (block?.type === 'text') return [block.text]
+    if (block?.type === 'tool-call') return [block.name, block.arguments]
+    if (block?.type === 'tool-result') return contentText(block.content)
+    return []
+  }).filter(value => typeof value === 'string' && value.trim() !== '').join('\n')
+}
+
+function titleFromText(text) {
+  const line = text.replaceAll(/\s+/g, ' ').trim()
+  return (line.length > 42 ? `${line.slice(0, 42)}...` : line) || 'DSH 会话'
+}
+
+function sessionCwd(session) {
+  // The Session header defines `cwd` as its only working-directory carrier; the
+  // old `header.meta.cwd` fallback never matched a real header field.
+  const cwd = session.header?.cwd
+  return typeof cwd === 'string' && cwd.trim() !== '' ? cwd : '未指定工作目录'
+}
+
+function workspaceTitle(cwd, fallbackTitle) {
+  if (cwd === '未指定工作目录') return fallbackTitle
+  const segment = cwd.replace(/[\\/]+$/, '').split(/[\\/]/).at(-1)
+  return segment && segment.trim() !== '' ? segment : fallbackTitle
+}
+
+async function readJson(req) {
+  const chunks = []
+  let length = 0
+  for await (const chunk of req) {
+    length += chunk.length
+    if (length > MAX_BODY_BYTES) throw new InputError('请求内容过大')
+    chunks.push(chunk)
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { throw new InputError('请求不是有效 JSON') }
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(body))
+}
+
+function sendFile(res, contentType, body) {
+  res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' })
+  res.end(body)
+}
+
+function page() {
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Synapse for DSH</title><link rel="stylesheet" href="/synapse/styles.css"></head><body><div id="app"></div><script src="/synapse/app.js"></script></body></html>`
+}
+
+/** Mount Synapse routes on the existing DSH Web Server. */
+export function apply(ctx, config) {
+  const store = new WorkspaceStore(config?.dataFile)
+  const autoProjection = config?.autoProjection !== false
+  const projectionWorkspaceTitle = typeof config?.projectionWorkspaceTitle === 'string' && config.projectionWorkspaceTitle.trim() !== ''
+    ? config.projectionWorkspaceTitle.trim().slice(0, MAX_TITLE_LENGTH)
+    : 'DSH 任务'
+  const reportProjectionFailure = error => {
+    ctx.logger.warn(error instanceof Error ? error : new Error(String(error)))
+  }
+  const replaySession = session => {
+    // Forks inherit their parent's log. The canvas already represents that
+    // history through the parent node, so only project the child's live tail:
+    // `inheritedEventCount` is 0 without a fork and the durable cut with one.
+    const replayFrom = session.inheritedEventCount ?? 0
+    void store.projectSession(session, replayFrom, projectionWorkspaceTitle).catch(reportProjectionFailure)
+  }
+  // Buffer live events per session and flush them in one write per microtask,
+  // so a burst of turn events coalesces into a single save instead of N.
+  const projectionQueue = []
+  let projectionScheduled = false
+  const enqueueProjection = (session, event) => {
+    projectionQueue.push({ session, event })
+    if (projectionScheduled) return
+    projectionScheduled = true
+    queueMicrotask(() => {
+      projectionScheduled = false
+      const batch = projectionQueue.splice(0)
+      const bySession = new Map()
+      for (const item of batch) {
+        const entry = bySession.get(item.session.id)
+        if (entry === undefined) bySession.set(item.session.id, [item.session, [item.event]])
+        else entry[1].push(item.event)
+      }
+      for (const [sessionId, [session, events]] of bySession) {
+        void store.projectEvents(session, events, projectionWorkspaceTitle).catch(reportProjectionFailure)
+      }
+    })
+  }
+  if (autoProjection) {
+    ctx.on('session/created', replaySession)
+    ctx.on('session/event', enqueueProjection)
+    for (const session of ctx.sessions.list()) replaySession(session)
+  }
+  // The DSH /api browser-trust fence does not cover /synapse routes, so this
+  // handler checks the Host header itself: localhost is allowed by default and
+  // additional authorities opt in through config.trustedHosts (mirrors the
+  // fence's DNS-rebinding defense).
+  const trustedHosts = new Set(['localhost', '127.0.0.1', ...[...(config?.trustedHosts ?? [])].map(host => String(host).trim().toLowerCase()).filter(Boolean)])
+  const api = async (req, res) => {
+    try {
+      const hostname = (typeof req.headers.host === 'string' ? req.headers.host : '').replace(/:\d+$/, '').toLowerCase()
+      if (!trustedHosts.has(hostname)) return sendJson(res, 403, { error: '不被信任的 Host' })
+      const path = new URL(req.url ?? '/', 'http://dsh.local').pathname
+      if (path === '/synapse/api/reset' && req.method === 'POST') return sendJson(res, 200, await store.clearLegacy(ctx.sessions.list()))
+      if (path === '/synapse/api/workspaces') {
+        if (req.method === 'GET') return sendJson(res, 200, { workspaces: await store.list() })
+        if (req.method === 'POST') return sendJson(res, 201, { workspace: await store.create((await readJson(req)).title) })
+      }
+      const workspace = /^\/synapse\/api\/workspaces\/([0-9a-f-]+)$/i.exec(path)
+      if (workspace !== null) {
+        if (req.method === 'GET') return sendJson(res, 200, { workspace: await store.get(workspace[1]) })
+        if (req.method === 'POST') return sendJson(res, 201, { thread: await store.createThread(workspace[1], await readJson(req)) })
+      }
+      const branch = /^\/synapse\/api\/threads\/([0-9a-f-]+)\/branch$/i.exec(path)
+      if (branch !== null && req.method === 'POST') return sendJson(res, 201, { thread: await store.branch(branch[1], await readJson(req)) })
+      if (path === '/synapse/api/sessions/sync' && req.method === 'POST') { const body = await readJson(req); return sendJson(res, 200, { workspaces: await store.syncSessions(body.sessions, body.removedSessionIds) }) }
+      const messages = /^\/synapse\/api\/threads\/([0-9a-f-]+)\/messages$/i.exec(path)
+      if (messages !== null && req.method === 'POST') return sendJson(res, 201, { thread: await store.addMessage(messages[1], (await readJson(req)).text) })
+      const thread = /^\/synapse\/api\/threads\/([0-9a-f-]+)$/i.exec(path)
+      if (thread !== null && req.method === 'PATCH') return sendJson(res, 200, { thread: await store.updateThread(thread[1], await readJson(req)) })
+      if (thread !== null && req.method === 'DELETE') return sendJson(res, 200, await store.removeThread(thread[1]))
+      return sendJson(res, 404, { error: '接口不存在' })
+    } catch (error) {
+      if (error instanceof InputError) return sendJson(res, 400, { error: error.message })
+      if (error instanceof NotFoundError) return sendJson(res, 404, { error: error.message })
+      ctx.logger.error(error instanceof Error ? error : new Error(String(error)))
+      return sendJson(res, 500, { error: 'Synapse 数据暂时不可用' })
+    }
+  }
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse', handler: (_req, res) => { res.writeHead(302, { location: '/synapse/' }); res.end() } }), 'synapse: redirect')
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/', handler: (_req, res) => { sendFile(res, 'text/html; charset=utf-8', page()) } }), 'synapse: page')
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/app.js', handler: async (_req, res) => { sendFile(res, 'text/javascript; charset=utf-8', await readFile(new URL('./app.js', import.meta.url), 'utf8')) } }), 'synapse: app')
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/styles.css', handler: async (_req, res) => { sendFile(res, 'text/css; charset=utf-8', await readFile(new URL('./styles.css', import.meta.url), 'utf8')) } }), 'synapse: styles')
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: '/synapse/deepseek-mark.svg', handler: async (_req, res) => { sendFile(res, 'image/svg+xml', await readFile(new URL('./deepseek-mark.svg', import.meta.url), 'utf8')) } }), 'synapse: DeepSeek mark')
+  ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/synapse/api', handler: api }), 'synapse: api')
+}