@wangxiaocuo/dsh-session-trash 0.5.1 → 0.6.0

package/lib/trash-service.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs/promises'
 import path from 'node:path'
 import { TrashError } from './errors.js'
 import {
@@ -12,7 +13,8 @@ import {
   moveDirectory,
   samePath,
 } from './fsops.js'
-import { reconcileIndex, rebuildIndex } from './inventory.js'
+import { reconcileIndex, rebuildIndex, memberPresence } from './inventory.js'
+import { aggregateMetrics, memberList } from './members.js'
 
 /** How many short retries confirm a moved or restored session is visible. */
 const VISIBILITY_RETRIES = 5
@@ -170,9 +172,34 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     return undefined
   }
 
+  /**
+   * @param {unknown} target path to probe.
+   * @returns {Promise<string>} the entry kind, treating an absent path as missing.
+   */
+  async function kindOf(target) {
+    return typeof target === 'string' && target !== '' ? entryKind(target) : 'missing'
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {object[]} every owned directory, parent first.
+   */
+  function membersOf(entry) {
+    return memberList(entry)
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {number} index member position.
+   * @returns {string} this member's directory inside the trash object.
+   */
+  function memberTrashPath(entry, index) {
+    return store.memberPath(entry.trashId, index, membersOf(entry)[index].sessionId)
+  }
+
   /**
    * @param {object} entry trash index entry.
-   * @returns {Promise<void>} resolution once the object directory is inside `objects/`.
+   * @returns {Promise<void>} resolution once every member path stays inside `objects/`.
    */
   async function assertSafeObject(entry) {
     if (!isSafeTrashId(entry.trashId)) {
@@ -182,14 +209,202 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     if (!isInside(store.objectsDir, objectDir)) {
       throw new TrashError('IO_ERROR', 'The trash entry names an object outside the trash root.')
     }
+    const members = membersOf(entry)
+    for (let index = 0; index < members.length; index += 1) {
+      const memberPath = path.resolve(memberTrashPath(entry, index))
+      if (!isInside(objectDir, memberPath)) {
+        throw new TrashError('IO_ERROR', 'The trash entry names a member outside its object.')
+      }
+    }
   }
 
   /**
-   * @param {object} entry trash index entry.
-   * @returns {Promise<boolean>} whether the moved session directory still exists.
+   * @param {object} entry index entry.
+   * @returns {Promise<{ index: number, member: object, source: boolean, trash: boolean }[]>} member positions.
+   */
+  async function memberRows(entry) {
+    const members = membersOf(entry)
+    const rows = []
+    for (let index = 0; index < members.length; index += 1) {
+      const member = members[index]
+      rows.push({
+        index,
+        member,
+        source: (await kindOf(member.originalSessionDir)) === 'directory',
+        trash: (await kindOf(memberTrashPath(entry, index))) === 'directory',
+      })
+    }
+    return rows
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {number} index member position.
+   * @returns {Promise<void>} resolution once the member directory moved into its object.
+   */
+  async function moveMemberToTrash(entry, index) {
+    const member = membersOf(entry)[index]
+    await moveDirectory(member.originalSessionDir, memberTrashPath(entry, index), member, { logger })
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {number} index member position.
+   * @returns {Promise<void>} resolution once the member directory moved back to its original location.
+   */
+  async function moveMemberBack(entry, index) {
+    const member = membersOf(entry)[index]
+    await moveDirectory(memberTrashPath(entry, index), member.originalSessionDir, member, { logger })
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {readonly { index: number }[]} rows members to move into the object.
+   * @returns {Promise<{ index: number, error: unknown }[]>} per-member failures.
+   */
+  async function moveMembersIntoTrash(entry, rows) {
+    const failures = []
+    for (const row of [...rows].sort((left, right) => right.index - left.index)) {
+      try {
+        await moveMemberToTrash(entry, row.index)
+      } catch (error) {
+        failures.push({ index: row.index, error })
+      }
+    }
+    return failures
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {readonly { index: number }[]} rows members to move back to their original locations.
+   * @returns {Promise<{ index: number, error: unknown }[]>} per-member failures.
+   */
+  async function moveMembersBackFromTrash(entry, rows) {
+    const failures = []
+    for (const row of [...rows].sort((left, right) => left.index - right.index)) {
+      try {
+        await moveMemberBack(entry, row.index)
+      } catch (error) {
+        failures.push({ index: row.index, error })
+      }
+    }
+    return failures
+  }
+
+  /**
+   * Move every member directory into the trash object, children first and the
+   * visible parent last so the sidebar keeps the row until the move settles.
+   *
+   * @param {object} entry index entry.
+   * @returns {Promise<void>} resolution once every member directory moved.
+   */
+  async function moveMembersToTrash(entry) {
+    const rows = membersOf(entry).map((_, index) => ({ index }))
+    const failures = await moveMembersIntoTrash(entry, rows)
+    if (failures.length === 0) return
+    const failure = failures[0]
+    throw failure.error instanceof TrashError
+      ? failure.error
+      : new TrashError('IO_ERROR', `Cannot move a session directory into the trash: ${messageOf(failure.error)}`)
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @param {number} index member position.
+   * @returns {Promise<void>} resolution once the unusable trash copy is gone.
+   */
+  async function removeTrashMember(entry, index) {
+    const target = path.resolve(memberTrashPath(entry, index))
+    const objectDir = path.resolve(store.objectDir(entry.trashId))
+    if (samePath(objectDir, target) || !isInside(objectDir, target)) {
+      throw new TrashError('IO_ERROR', 'Refusing to remove a member directory outside its trash object.')
+    }
+    await fs.rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  }
+
+  /**
+   * @param {object} member planned member whose restored copy failed verification.
+   * @returns {Promise<void>} resolution once the unusable restored copy is gone.
    */
-  async function trashSessionExists(entry) {
-    return (await entryKind(store.sessionPath(entry.trashId))) === 'directory'
+  async function removeRestoredMember(member) {
+    const target = path.resolve(String(member.originalSessionDir))
+    if (!isSafeDirectoryPath(target) || isInside(paths.root, target)) {
+      throw new TrashError('IO_ERROR', 'Refusing to remove an unsafe session directory.')
+    }
+    await fs.rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {Promise<{ ok: boolean, index?: number, message?: string }>} whether every member landed with its recorded metrics.
+   */
+  async function verifyTrashedMembers(entry) {
+    const members = membersOf(entry)
+    for (let index = 0; index < members.length; index += 1) {
+      let measured
+      try {
+        measured = await measureDirectory(memberTrashPath(entry, index))
+      } catch (error) {
+        return { ok: false, index, message: messageOf(error) }
+      }
+      if (!metricsMatch(members[index], measured)) {
+        return { ok: false, index, message: 'the recorded size does not match' }
+      }
+      if ((await kindOf(members[index].originalSessionDir)) !== 'missing') {
+        return { ok: false, index, message: 'the original directory still exists' }
+      }
+    }
+    return { ok: true }
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {Promise<{ ok: boolean, index?: number, message?: string }>} whether every member returned with its recorded metrics.
+   */
+  async function verifyRestoredMembers(entry) {
+    const members = membersOf(entry)
+    for (let index = 0; index < members.length; index += 1) {
+      let measured
+      try {
+        measured = await measureDirectory(members[index].originalSessionDir)
+      } catch (error) {
+        return { ok: false, index, message: messageOf(error) }
+      }
+      if (!metricsMatch(members[index], measured)) {
+        return { ok: false, index, message: 'the recorded size does not match' }
+      }
+    }
+    return { ok: true }
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {Promise<{ hidden: boolean, sessionId?: string }>} whether session storage stopped reporting every member.
+   */
+  async function waitForMembersHidden(entry) {
+    for (const member of membersOf(entry)) {
+      const hidden = await waitForVisibility(
+        member.sessionId,
+        (current) => current === undefined || current === null,
+      )
+      if (!hidden) return { hidden: false, sessionId: member.sessionId }
+    }
+    return { hidden: true }
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {Promise<{ visible: boolean, sessionId?: string }>} whether session storage reports every member again.
+   */
+  async function waitForMembersVisible(entry) {
+    for (const member of membersOf(entry)) {
+      const visible = await waitForVisibility(
+        member.sessionId,
+        (current) => current !== undefined && current !== null && current.location !== undefined,
+      )
+      if (!visible) return { visible: false, sessionId: member.sessionId }
+    }
+    return { visible: true }
   }
 
   /**
@@ -419,98 +634,185 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * Settle a failed move by applying the `trashing` crash matrix to the live
-   * filesystem. Returns a committed `trashed` entry when the data landed in the
-   * trash, or `undefined` when the operation rolled back.
+   * Resolve every member directory of a `trashing` entry to either the trash
+   * object or its original location. Never writes the index: the caller owns
+   * the commit so startup recovery can accumulate one write.
    *
-   * @param {object} entry current `trashing` entry.
-   * @param {unknown} cause failure that triggered recovery.
-   * @returns {Promise<object | undefined>} the completed entry, or undefined after rollback.
+   * @param {object} entry `trashing` index entry.
+   * @returns {Promise<{ kind: 'ready' } | { kind: 'rolledBack' } | { kind: 'missing', entry: object }>} the settled position.
    */
-  async function settleFailedTrashMove(entry, cause) {
-    const sourceExists = (await entryKind(entry.originalSessionDir)) === 'directory'
-    const targetExists = await trashSessionExists(entry)
-    const failure = messageOf(cause)
-    if (sourceExists && !targetExists) {
-      await rollbackTrash(entry.sessionId, entry.trashId)
-      return undefined
-    }
-    if (!sourceExists && targetExists) {
-      const measured = await measureDirectory(store.sessionPath(entry.trashId))
-      if (!metricsMatch(entry, measured)) {
-        await markFailure(entry, `The moved session does not match its recorded size (${failure}).`)
-        throw new TrashError('MOVE_CONFLICT', 'The moved session does not match its recorded size.', { measured })
+  async function resolveTrashing(entry) {
+    const rows = await memberRows(entry)
+    const lost = rows.filter((row) => !row.source && !row.trash)
+    if (lost.length > 0) {
+      return {
+        kind: 'missing',
+        entry: {
+          ...entry,
+          state: 'missing',
+          lastError: errorText(`The trash copy is missing for: ${lost.map((row) => row.member.sessionId).join(', ')}`),
+        },
       }
-      const next = { ...entry, state: 'trashed', trashedAt: Date.now(), lastError: null }
-      await store.commit(upsertEntry(store.entries(), next))
-      await store.writeMeta(next).catch(() => {})
-      eligibility.invalidate(entry.sessionId)
-      emit('api-session/removed', entry.sessionId)
-      return next
     }
-    if (sourceExists && targetExists) {
-      const measured = await measureDirectory(store.sessionPath(entry.trashId))
-      if (metricsMatch(entry, measured)) {
-        try {
-          await store.removeSessionSource(entry.originalSessionDir)
-          const next = { ...entry, state: 'trashed', trashedAt: Date.now(), lastError: null }
-          await store.commit(upsertEntry(store.entries(), next))
-          await store.writeMeta(next).catch(() => {})
-          eligibility.invalidate(entry.sessionId)
-          emit('api-session/removed', entry.sessionId)
-          return next
-        } catch (error) {
-          logger.warn(`cannot remove the source after copying session ${entry.sessionId}: ${messageOf(error)}`)
-        }
+    for (const row of rows) {
+      if (!row.source || !row.trash) continue
+      const measured = await measureDirectory(memberTrashPath(entry, row.index))
+      if (metricsMatch(row.member, measured)) {
+        await store.removeSessionSource(row.member.originalSessionDir)
+        row.source = false
       } else {
-        // The source is authoritative: remove the unusable copy and roll back.
-        await rollbackTrash(entry.sessionId, entry.trashId)
-        return undefined
+        await removeTrashMember(entry, row.index)
+        row.trash = false
+      }
+    }
+    const inTrash = rows.filter((row) => row.trash)
+    const inSource = rows.filter((row) => row.source)
+    if (inTrash.length === 0) return { kind: 'rolledBack' }
+    if (inSource.length > 0) {
+      const failures = await moveMembersIntoTrash(entry, inSource)
+      if (failures.length > 0) {
+        const current = await memberRows(entry)
+        const rollback = await moveMembersBackFromTrash(entry, current.filter((row) => row.trash))
+        if (rollback.length === 0) return { kind: 'rolledBack' }
+        await markFailure(entry, `The session tree could not be completed or rolled back: ${messageOf(failures[0].error)}`)
+        throw new TrashError('MOVE_CONFLICT', 'The session tree could not be moved or rolled back; both copies were kept.')
       }
-      await markFailure(entry, failure)
-      throw new TrashError('MOVE_CONFLICT', 'The session move could not be completed; both copies were kept.', {
-        source: entry.originalSessionDir,
-      })
     }
-    await markFailure(entry, `The session log disappeared during the move (${failure}).`)
-    throw new TrashError('MOVE_CONFLICT', 'The session log disappeared during the move.', {})
+    const verified = await verifyTrashedMembers(entry)
+    if (!verified.ok) {
+      const current = await memberRows(entry)
+      const rollback = await moveMembersBackFromTrash(entry, current.filter((row) => row.trash))
+      if (rollback.length === 0) return { kind: 'rolledBack' }
+      await markFailure(entry, `The moved session tree does not match its recorded size (${verified.message}).`)
+      throw new TrashError('MOVE_VERIFY_FAILED', 'The moved session tree does not match its recorded size.')
+    }
+    return { kind: 'ready' }
   }
 
   /**
-   * Settle a failed restore move. Returns `true` when the session directory is
-   * at its original location and the operation may continue.
+   * Resolve every member directory of a `restoring` entry back to its original
+   * location, or back into the trash object when the restore cannot complete.
+   * Never writes the index: the caller owns the commit.
    *
-   * @param {object} entry `restoring` entry.
-   * @param {unknown} cause failure that triggered recovery.
-   * @returns {Promise<boolean>} whether the target now contains the restored session.
+   * @param {object} entry `restoring` index entry.
+   * @returns {Promise<{ kind: 'ready' } | { kind: 'trashed', entry: object } | { kind: 'missing', entry: object }>} the settled position.
    */
-  async function settleFailedRestoreMove(entry, cause) {
-    const targetExists = (await entryKind(entry.originalSessionDir)) === 'directory'
-    const trashExists = await trashSessionExists(entry)
-    const failure = messageOf(cause)
-    if (targetExists) {
-      const measured = await measureDirectory(entry.originalSessionDir)
-      if (metricsMatch(entry, measured)) {
-        if (trashExists) {
-          try {
-            await store.removeObjectDir(entry.trashId)
-          } catch (error) {
-            logger.warn(`cannot remove the leftover trash copy for ${entry.sessionId}: ${messageOf(error)}`)
-          }
-        }
-        return true
+  async function resolveRestoring(entry) {
+    const rows = await memberRows(entry)
+    const lost = rows.filter((row) => !row.source && !row.trash)
+    if (lost.length > 0) {
+      return {
+        kind: 'missing',
+        entry: {
+          ...entry,
+          state: 'missing',
+          lastError: errorText(`Both copies are missing for: ${lost.map((row) => row.member.sessionId).join(', ')}`),
+        },
       }
-      await markFailure(entry, `The restored session does not match its recorded size (${failure}).`)
-      return false
     }
-    if (trashExists) {
-      const next = { ...entry, state: 'trashed', lastError: errorText(failure) }
+    for (const row of rows) {
+      if (!row.source || !row.trash) continue
+      const measured = await measureDirectory(row.member.originalSessionDir)
+      if (metricsMatch(row.member, measured)) {
+        await removeTrashMember(entry, row.index)
+        row.trash = false
+      } else {
+        await removeRestoredMember(row.member)
+        row.source = false
+      }
+    }
+    const rolledBack = () => ({
+      kind: 'trashed',
+      entry: {
+        ...entry,
+        state: 'trashed',
+        trashedAt:
+          typeof entry.trashedAt === 'number' && entry.trashedAt > 0 ? entry.trashedAt : entry.startedAt || Date.now(),
+        lastError: 'Recovered the trash copy after an interrupted restore.',
+      },
+    })
+    const inSource = rows.filter((row) => row.source)
+    const inTrash = rows.filter((row) => row.trash)
+    if (inSource.length === 0) return rolledBack()
+    if (inTrash.length > 0) {
+      const failures = await moveMembersBackFromTrash(entry, inTrash)
+      if (failures.length > 0) {
+        const current = await memberRows(entry)
+        const rollback = await moveMembersIntoTrash(entry, current.filter((row) => row.source && !row.trash))
+        if (rollback.length === 0) return rolledBack()
+        await markFailure(entry, `The restore could not be completed or rolled back: ${messageOf(failures[0].error)}`)
+        throw new TrashError('MOVE_CONFLICT', 'The restore could not be completed or rolled back; both copies were kept.')
+      }
+    }
+    const verified = await verifyRestoredMembers(entry)
+    if (!verified.ok) {
+      const current = await memberRows(entry)
+      const rollback = await moveMembersIntoTrash(entry, current.filter((row) => row.source))
+      if (rollback.length === 0) return rolledBack()
+      await markFailure(entry, `The restored session tree does not match its recorded size (${verified.message}).`)
+      throw new TrashError('RESTORE_VERIFY_FAILED', 'The restored session tree does not match its recorded size.')
+    }
+    return { kind: 'ready' }
+  }
+
+  /**
+   * @param {object} entry settled `trashing` entry.
+   * @param {{ emitRemoval?: boolean }} [options] whether to announce the removal to clients.
+   * @returns {Promise<object>} the committed `trashed` entry.
+   */
+  async function commitTrashed(entry, options = {}) {
+    const next = { ...entry, state: 'trashed', trashedAt: Date.now(), lastError: null }
+    try {
       await store.commit(upsertEntry(store.entries(), next))
-      await store.writeMeta(next).catch(() => {})
-      return false
+    } catch (error) {
+      await markFailure(entry, `The trash index could not be committed: ${messageOf(error)}`)
+      throw new TrashError('INDEX_WRITE_FAILED', 'The session moved, but the trash index could not be updated.')
     }
-    await markFailure(entry, `Both the trash copy and the restore target are missing (${failure}).`)
-    return false
+    await store.writeMeta(next).catch((error) => {
+      logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${messageOf(error)}`)
+    })
+    eligibility.invalidate(entry.sessionId)
+    if (options.emitRemoval === true) emit('api-session/removed', entry.sessionId)
+    return next
+  }
+
+  /**
+   * Finish a settled restore: wait for visibility, restore workspace
+   * accounting, drop the entry, and optionally announce the session.
+   *
+   * @param {object} entry settled `restoring` entry.
+   * @param {{ mode?: 'normal' | 'orphan', emitAdded?: boolean, reattach?: boolean }} [options] finishing policy.
+   * @returns {Promise<object>} the workspace attachment outcome.
+   */
+  async function completeRestore(entry, options = {}) {
+    const mode = options.mode ?? 'normal'
+    const visible = await waitForMembersVisible(entry)
+    if (!visible.visible) {
+      throw new TrashError('RESTORE_VERIFY_FAILED', 'The restored session tree is not visible to session storage.', {
+        sessionId: visible.sessionId,
+      })
+    }
+    const attachment =
+      options.reattach === false
+        ? { reattached: false }
+        : mode === 'orphan'
+          ? await detachWorkspace(entry)
+          : await reattachWorkspace(entry)
+    try {
+      await store.commit(dropEntry(store.entries(), entry.sessionId))
+    } catch (error) {
+      await markFailure(entry, `The trash index could not be committed after restore: ${messageOf(error)}`)
+      throw new TrashError('INDEX_WRITE_FAILED', 'The session was restored, but the trash index could not be updated.')
+    }
+    await store.removeObjectDir(entry.trashId).catch((error) => {
+      logger.warn(`cannot remove the restored trash object ${entry.trashId}: ${messageOf(error)}`)
+    })
+    eligibility.invalidate(entry.sessionId)
+    if (options.emitAdded !== false) {
+      const restoredSnapshot = await stat(entry.sessionId).catch(() => undefined)
+      emit('api-session/added', buildSummary(entry.sessionId, entry.title, restoredSnapshot))
+    }
+    return attachment
   }
 
   /**
@@ -576,14 +878,15 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * Move one cold session into the trash.
+   * Move one cold session tree into the trash. A session that owns only hidden
+   * `origin: 'subagent'` descendants moves together with them.
    *
    * @param {string} sessionId session to trash.
    * @returns {Promise<object>} the committed `trashed` entry.
    */
   async function trash(sessionId) {
     const startedAt = Date.now()
-    const result = await store.withLock(async () => {
+    return store.withLock(async () => {
       if (store.isProtected()) {
         throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses new entries.')
       }
@@ -603,28 +906,65 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
           throw new TrashError('ALREADY_TRASHED', 'This session is already recorded in the trash.')
         }
       }
-      const snapshot = await stat(sessionId)
-      if (snapshot === undefined) throw new TrashError('SESSION_NOT_FOUND', 'This session is not in session storage.')
-      if (isLive(sessionId)) throw new TrashError('SESSION_LIVE', 'This session is open right now.')
-      const location = snapshot.location
-      if (location === undefined || location === null || location.kind !== 'jsonl' || typeof location.path !== 'string') {
-        throw new TrashError('SESSION_NOT_MATERIALIZED', 'This session has no movable JSONL log.')
-      }
-      const resolvedLogPath = path.resolve(location.path)
-      if (!path.isAbsolute(location.path)) {
-        throw new TrashError('STORAGE_UNSUPPORTED', 'The session log path is not absolute.')
-      }
-      const sessionDir = path.dirname(resolvedLogPath)
-      const projectDir = path.dirname(sessionDir)
-      if (!isSafeDirectoryPath(sessionDir) || (await entryKind(sessionDir)) !== 'directory') {
-        throw new TrashError('UNSAFE_SESSION_DIR', 'The session directory is not a plain directory this plugin can move.')
+
+      const plan = Array.isArray(verdict.members) ? verdict.members : []
+      if (plan.length === 0) throw new TrashError('SESSION_NOT_FOUND', 'This session is not in session storage.')
+      const members = []
+      let parentSnapshot
+      for (let index = 0; index < plan.length; index += 1) {
+        const planned = plan[index]
+        const snapshot = await stat(planned.sessionId)
+        if (snapshot === undefined || snapshot === null) {
+          throw new TrashError('SESSION_NOT_FOUND', 'A session in this lineage is not in session storage.', {
+            sessionId: planned.sessionId,
+          })
+        }
+        if (index === 0) parentSnapshot = snapshot
+        const location = snapshot.location
+        if (
+          location === undefined ||
+          location === null ||
+          typeof location.path !== 'string' ||
+          location.kind !== 'jsonl' ||
+          !path.isAbsolute(location.path)
+        ) {
+          throw new TrashError('SESSION_NOT_MATERIALIZED', 'A session in this lineage has no movable JSONL log.', {
+            sessionId: planned.sessionId,
+          })
+        }
+        const resolvedLogPath = path.resolve(location.path)
+        const sessionDir = path.dirname(resolvedLogPath)
+        const projectDir = path.dirname(sessionDir)
+        if (!isSafeDirectoryPath(sessionDir) || (await kindOf(sessionDir)) !== 'directory') {
+          throw new TrashError('UNSAFE_SESSION_DIR', 'A session directory is not a plain directory this plugin can move.', {
+            sessionId: planned.sessionId,
+          })
+        }
+        if (isLive(planned.sessionId)) {
+          throw new TrashError('SESSION_LIVE', 'A session in this lineage became live before it could be moved.', {
+            sessionId: planned.sessionId,
+          })
+        }
+        const measured = await measureDirectory(sessionDir)
+        const title = await resolveTitle(planned.sessionId, snapshot.header)
+        members.push({
+          sessionId: planned.sessionId,
+          origin: index === 0 ? null : 'subagent',
+          title,
+          originalSessionDir: sessionDir,
+          originalLogPath: resolvedLogPath,
+          persistenceProjectDirHint: projectDir,
+          formatStatus: snapshot.formatStatus === 'migration-required' ? 'migration-required' : 'current',
+          sizeBytes: measured.sizeBytes,
+          fileCount: measured.fileCount,
+        })
       }
 
       let trashId
       for (let attempt = 0; attempt < 5; attempt += 1) {
         const candidate = createTrashId()
         const indexed = store.entries().some((entry) => entry.trashId === candidate)
-        if (!indexed && (await entryKind(store.objectDir(candidate))) === 'missing') {
+        if (!indexed && (await kindOf(store.objectDir(candidate))) === 'missing') {
           trashId = candidate
           break
         }
@@ -639,32 +979,34 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
           phase: 'create-object',
         })
       }
-      let entry
+
+      const totals = aggregateMetrics(members)
+      const parent = members[0]
+      const header = parentSnapshot?.header ?? {}
+      const originalCwd = typeof header.cwd === 'string' && header.cwd !== '' ? header.cwd : null
+      const workspaceInfo = findOwningWorkspace(sessionId)
+      const entry = {
+        sessionId,
+        trashId,
+        state: 'trashing',
+        title: parent.title,
+        trashedAt: 0,
+        startedAt,
+        originalCwd,
+        workspaceExistsAtDeletion: originalCwd === null ? null : await directoryExists(originalCwd),
+        originalWorkspaceId: workspaceInfo?.workspace?.id ?? null,
+        originalWorkspaceTitle: workspaceInfo?.workspace?.title ?? null,
+        originalNextSessionId: workspaceInfo?.nextSessionId ?? null,
+        originalSessionDir: parent.originalSessionDir,
+        originalLogPath: parent.originalLogPath,
+        persistenceProjectDirHint: parent.persistenceProjectDirHint,
+        formatStatus: parent.formatStatus,
+        sizeBytes: totals.sizeBytes,
+        fileCount: totals.fileCount,
+        members,
+        lastError: null,
+      }
       try {
-        const measured = await measureDirectory(sessionDir)
-        const title = await resolveTitle(sessionId, snapshot.header)
-        const originalCwd = cwdOf(snapshot) === '' ? null : cwdOf(snapshot)
-        const workspaceInfo = findOwningWorkspace(sessionId)
-        entry = {
-          sessionId,
-          trashId,
-          state: 'trashing',
-          title,
-          trashedAt: 0,
-          startedAt,
-          originalCwd,
-          workspaceExistsAtDeletion: originalCwd === null ? null : await directoryExists(originalCwd),
-          originalWorkspaceId: workspaceInfo?.workspace?.id ?? null,
-          originalWorkspaceTitle: workspaceInfo?.workspace?.title ?? null,
-          originalNextSessionId: workspaceInfo?.nextSessionId ?? null,
-          originalSessionDir: sessionDir,
-          originalLogPath: resolvedLogPath,
-          persistenceProjectDirHint: projectDir,
-          formatStatus: snapshot.formatStatus ?? 'current',
-          sizeBytes: measured.sizeBytes,
-          fileCount: measured.fileCount,
-          lastError: null,
-        }
         await store.writeMeta(entry)
         await store.commit(upsertEntry(store.entries(), entry))
       } catch (error) {
@@ -674,88 +1016,69 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
           : new TrashError('IO_ERROR', `Cannot prepare the trash entry: ${messageOf(error)}`)
       }
 
-      // Another process may have opened or resumed the session between the
-      // preflight and the move. Re-check live state while the trash lock is
-      // held; the source is still untouched at this point.
-      if (isLive(sessionId)) {
+      // Another process may have opened or resumed a member between the
+      // preflight and the move. Re-check every member while the trash lock is
+      // held; the sources are still untouched at this point.
+      const raced = members.find((member) => isLive(member.sessionId))
+      if (raced !== undefined) {
         await rollbackTrash(sessionId, trashId)
-        throw new TrashError('SESSION_LIVE', 'This session became live before it could be moved.')
+        throw new TrashError('SESSION_LIVE', 'A session in this lineage became live before it could be moved.', {
+          sessionId: raced.sessionId,
+        })
       }
 
+      let moveError
       try {
-        await moveDirectory(sessionDir, store.sessionPath(trashId), entry, { logger })
+        await moveMembersToTrash(entry)
       } catch (error) {
-        let settled
-        try {
-          settled = await settleFailedTrashMove(entry, error)
-        } catch (settleError) {
-          await markFailure(entry, messageOf(settleError))
-          throw settleError
-        }
-        if (settled !== undefined) return settled
-        throw error instanceof TrashError
-          ? error
-          : new TrashError('IO_ERROR', `Cannot move the session into the trash: ${messageOf(error)}`)
+        moveError = error
       }
-
-      let measured
+      let settled
       try {
-        measured = await measureDirectory(store.sessionPath(trashId))
+        settled = await resolveTrashing(entry)
       } catch (error) {
-        let settled
-        try {
-          settled = await settleFailedTrashMove(entry, error)
-        } catch (settleError) {
-          await markFailure(entry, messageOf(settleError))
-          throw settleError
-        }
-        if (settled !== undefined) return settled
-        throw new TrashError('MOVE_VERIFY_FAILED', `Cannot verify the moved session: ${messageOf(error)}`)
+        throw error instanceof TrashError
+          ? error
+          : new TrashError('IO_ERROR', `Cannot move the session tree into the trash: ${messageOf(error)}`)
       }
-      if (!metricsMatch(entry, measured)) {
-        const movedBack = await moveBack(store.sessionPath(trashId), sessionDir, entry)
-        if (!movedBack) {
-          await markFailure(entry, 'The moved session does not match its recorded size, and moving it back failed.')
-          throw new TrashError('MOVE_CONFLICT', 'The session was moved but could not be verified or rolled back.')
-        }
-        await rollbackTrash(sessionId, trashId)
-        throw new TrashError('MOVE_VERIFY_FAILED', 'The moved session does not match its recorded size.', {
-          expected: { sizeBytes: entry.sizeBytes, fileCount: entry.fileCount },
-          measured,
+      if (settled.kind === 'missing') {
+        await store.commit(upsertEntry(store.entries(), settled.entry))
+        await store.writeMeta(settled.entry).catch(() => {})
+        throw new TrashError('MOVE_CONFLICT', 'A session directory disappeared during the move.', {
+          sessionId: settled.entry.sessionId,
+          lastError: settled.entry.lastError,
         })
       }
-      const hidden = await waitForVisibility(sessionId, (current) => current === undefined)
-      if (!hidden) {
-        const movedBack = await moveBack(store.sessionPath(trashId), sessionDir, entry)
-        if (!movedBack) {
-          await markFailure(entry, 'Session storage still reports the moved session, and moving it back failed.')
-          throw new TrashError('MOVE_CONFLICT', 'The session was moved but session storage still reports it.')
-        }
+      if (settled.kind === 'rolledBack') {
         await rollbackTrash(sessionId, trashId)
-        throw new TrashError('MOVE_VERIFY_FAILED', 'Session storage still reports the session after the move.')
+        throw moveError instanceof TrashError
+          ? moveError
+          : new TrashError('MOVE_VERIFY_FAILED', 'The session tree could not be moved into the trash.')
       }
-
-      const next = { ...entry, state: 'trashed', trashedAt: Date.now(), lastError: null }
-      try {
-        await store.commit(upsertEntry(store.entries(), next))
-      } catch (error) {
-        await markFailure(entry, `The trash index could not be committed: ${messageOf(error)}`)
-        throw new TrashError('INDEX_WRITE_FAILED', 'The session moved, but the trash index could not be updated.')
+      const hidden = await waitForMembersHidden(entry)
+      if (!hidden.hidden) {
+        const rows = await memberRows(entry)
+        const rollback = await moveMembersBackFromTrash(entry, rows.filter((row) => row.trash))
+        if (rollback.length > 0) {
+          await markFailure(entry, 'Session storage still reports the moved session tree, and moving it back failed.')
+          throw new TrashError('MOVE_CONFLICT', 'The session tree was moved but session storage still reports it.')
+        }
+        await rollbackTrash(sessionId, trashId)
+        throw new TrashError('MOVE_VERIFY_FAILED', 'Session storage still reports the session after the move.', {
+          sessionId: hidden.sessionId,
+        })
       }
-      await store.writeMeta(next).catch((error) => {
-        logger.warn(`cannot rewrite trash metadata for ${trashId}: ${messageOf(error)}`)
-      })
-      eligibility.invalidate(sessionId)
-      emit('api-session/removed', sessionId)
-      logger.info(`trashed ${sessionId} as ${trashId} in ${Date.now() - startedAt}ms`)
+      const next = await commitTrashed(entry, { emitRemoval: true })
+      logger.info(
+        `trashed ${sessionId} as ${trashId} with ${members.length - 1} child sessions in ${Date.now() - startedAt}ms`,
+      )
       return next
     })
-    return result
   }
 
   /**
-   * Restore one trashed session to its original directory. Phase 2 supports
-   * `normal` only; orphan restore arrives later.
+   * Restore one trashed session tree to its original directories. Phase 2
+   * supports `normal` only; orphan restore arrives later.
    *
    * @param {string} sessionId session to restore.
    * @param {'normal' | 'orphan'} [mode] restore mode; orphan restores the log and detaches the Workspace.
@@ -776,28 +1099,49 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
         throw new TrashError('TRASH_STATE_INVALID', `The trash entry is in state "${entry.state}" and cannot be restored.`)
       }
       await assertSafeObject(entry)
-      const target = path.resolve(String(entry.originalSessionDir))
-      const projectDirHint = path.resolve(String(entry.persistenceProjectDirHint))
+      const members = membersOf(entry)
+      const parent = members[0]
       if (
-        !isSafeDirectoryPath(target) ||
-        !samePath(path.dirname(target), projectDirHint) ||
-        isInside(paths.root, target) ||
-        !isInside(paths.root, store.objectDir(entry.trashId)) ||
-        typeof entry.originalLogPath !== 'string' ||
-        !samePath(path.dirname(path.resolve(entry.originalLogPath)), target)
+        !samePath(path.resolve(String(entry.originalSessionDir)), path.resolve(String(parent.originalSessionDir))) ||
+        !samePath(path.resolve(String(entry.originalLogPath)), path.resolve(String(parent.originalLogPath))) ||
+        !samePath(
+          path.resolve(String(entry.persistenceProjectDirHint)),
+          path.resolve(String(parent.persistenceProjectDirHint)),
+        )
       ) {
-        throw new TrashError('UNSAFE_RESTORE_PATH', 'The restore target failed the path safety check.')
+        throw new TrashError('UNSAFE_RESTORE_PATH', 'The trash entry names inconsistent restore paths.')
       }
-      const projectDirKind = await entryKind(projectDirHint)
-      if (projectDirKind !== 'missing' && projectDirKind !== 'directory') {
-        throw new TrashError('UNSAFE_RESTORE_PATH', 'The restore target parent is not a plain directory.')
-      }
-      const targetKind = await entryKind(target)
-      if (targetKind !== 'missing') {
-        throw new TrashError('RESTORE_TARGET_EXISTS', 'A directory already exists at the restore target.')
+      for (let index = 0; index < members.length; index += 1) {
+        const member = members[index]
+        const target = path.resolve(String(member.originalSessionDir))
+        const projectDirHint = path.resolve(String(member.persistenceProjectDirHint))
+        if (
+          !isSafeDirectoryPath(target) ||
+          !samePath(path.dirname(target), projectDirHint) ||
+          isInside(paths.root, target) ||
+          typeof member.originalLogPath !== 'string' ||
+          !samePath(path.dirname(path.resolve(member.originalLogPath)), target)
+        ) {
+          throw new TrashError('UNSAFE_RESTORE_PATH', 'The restore target failed the path safety check.', {
+            sessionId: member.sessionId,
+          })
+        }
+        const projectDirKind = await kindOf(projectDirHint)
+        if (projectDirKind !== 'missing' && projectDirKind !== 'directory') {
+          throw new TrashError('UNSAFE_RESTORE_PATH', 'The restore target parent is not a plain directory.', {
+            sessionId: member.sessionId,
+          })
+        }
+        const targetKind = await kindOf(target)
+        if (targetKind !== 'missing') {
+          throw new TrashError('RESTORE_TARGET_EXISTS', 'A directory already exists at the restore target.', {
+            sessionId: member.sessionId,
+          })
+        }
       }
-      if (!(await trashSessionExists(entry))) {
-        const missing = { ...entry, state: 'missing', lastError: 'The trash object directory is missing.' }
+      const presence = await memberPresence(store, entry)
+      if (presence.present !== presence.total) {
+        const missing = { ...entry, state: 'missing', lastError: 'The trash copy of this session is missing.' }
         await store.commit(upsertEntry(store.entries(), missing))
         await store.writeMeta(missing).catch(() => {})
         throw new TrashError('TRASH_DIR_MISSING', 'The trash copy of this session is missing.')
@@ -814,76 +1158,56 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
         logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${messageOf(error)}`)
       })
 
+      let moveError
+      const rows = members.map((_, index) => ({ index }))
+      const moveFailures = await moveMembersBackFromTrash(restoring, rows)
+      if (moveFailures.length > 0) moveError = moveFailures[0].error
+      let settled
       try {
-        await moveDirectory(store.sessionPath(entry.trashId), target, entry, { logger })
-      } catch (error) {
-        // A target created between the pre-check and the move belongs to
-        // someone else: never treat it as the restored copy.
-        if (error instanceof TrashError && error.code === 'RESTORE_TARGET_EXISTS') throw error
-        let completed
-        try {
-          completed = await settleFailedRestoreMove(restoring, error)
-        } catch (settleError) {
-          await markFailure(restoring, messageOf(settleError))
-          throw settleError
-        }
-        if (!completed) {
-          throw error instanceof TrashError
-            ? error
-            : new TrashError('IO_ERROR', `Cannot move the session back: ${messageOf(error)}`)
-        }
-      }
-
-      let measured
-      try {
-        measured = await measureDirectory(target)
+        settled = await resolveRestoring(restoring)
       } catch (error) {
-        throw new TrashError('RESTORE_VERIFY_FAILED', `Cannot verify the restored session: ${messageOf(error)}`)
+        throw error instanceof TrashError
+          ? error
+          : new TrashError('IO_ERROR', `Cannot move the session tree back: ${messageOf(error)}`)
       }
-      if (!metricsMatch(entry, measured)) {
-        const rolledBack = await moveBack(target, store.sessionPath(entry.trashId), measured)
-        if (!rolledBack) {
-          await markFailure(restoring, 'The restored session does not match its recorded size, and moving it back failed.')
-          throw new TrashError('MOVE_CONFLICT', 'The restored session does not match its recorded size.')
-        }
-        const next = { ...restoring, state: 'trashed', lastError: 'The restored session did not match its recorded size.' }
-        await store.commit(upsertEntry(store.entries(), next))
-        await store.writeMeta(next).catch(() => {})
-        throw new TrashError('RESTORE_VERIFY_FAILED', 'The restored session does not match its recorded size.', {
-          expected: { sizeBytes: entry.sizeBytes, fileCount: entry.fileCount },
-          measured,
-        })
+      if (settled.kind === 'missing') {
+        await store.commit(upsertEntry(store.entries(), settled.entry))
+        await store.writeMeta(settled.entry).catch(() => {})
+        throw new TrashError('RESTORE_VERIFY_FAILED', settled.entry.lastError ?? 'The restored session tree is missing.')
       }
-      const visible = await waitForVisibility(
-        sessionId,
-        (current) => current !== undefined && current !== null && current.location !== undefined,
-      )
-      if (!visible) {
-        const rolledBack = await moveBack(target, store.sessionPath(entry.trashId), measured)
-        if (!rolledBack) {
-          await markFailure(restoring, 'Session storage cannot see the restored session, and moving it back failed.')
-          throw new TrashError('MOVE_CONFLICT', 'Session storage cannot see the restored session.')
-        }
-        const next = { ...restoring, state: 'trashed', lastError: 'The restored session was not visible to session storage.' }
-        await store.commit(upsertEntry(store.entries(), next))
-        await store.writeMeta(next).catch(() => {})
-        throw new TrashError('RESTORE_VERIFY_FAILED', 'The restored session was not visible to session storage.')
+      if (settled.kind === 'trashed') {
+        await store.commit(upsertEntry(store.entries(), settled.entry))
+        await store.writeMeta(settled.entry).catch(() => {})
+        throw moveError instanceof TrashError
+          ? moveError
+          : new TrashError('RESTORE_VERIFY_FAILED', 'The session tree could not be restored.')
       }
 
-      const attachment = mode === 'orphan' ? await detachWorkspace(entry) : await reattachWorkspace(entry)
-      const restoredSnapshot = await stat(sessionId).catch(() => undefined)
-
+      let attachment
       try {
-        await store.commit(dropEntry(store.entries(), sessionId))
+        attachment = await completeRestore(restoring, { mode })
       } catch (error) {
-        await markFailure(restoring, `The trash index could not be committed after restore: ${messageOf(error)}`)
-        throw new TrashError('INDEX_WRITE_FAILED', 'The session was restored, but the trash index could not be updated.')
+        if (error instanceof TrashError && error.code === 'RESTORE_VERIFY_FAILED') {
+          const current = await memberRows(restoring)
+          const rollback = await moveMembersIntoTrash(
+            restoring,
+            current.filter((row) => row.source && !row.trash),
+          )
+          if (rollback.length > 0) {
+            await markFailure(restoring, 'The restored session tree is not visible, and rolling it back failed.')
+            throw new TrashError('MOVE_CONFLICT', 'The restored session tree is not visible, and rolling it back failed.')
+          }
+          const next = {
+            ...restoring,
+            state: 'trashed',
+            trashedAt: entry.trashedAt,
+            lastError: 'The restored session was not visible to session storage.',
+          }
+          await store.commit(upsertEntry(store.entries(), next))
+          await store.writeMeta(next).catch(() => {})
+        }
+        throw error
       }
-      await store.removeObjectDir(entry.trashId).catch((error) => {
-        logger.warn(`cannot remove the restored trash object ${entry.trashId}: ${messageOf(error)}`)
-      })
-      eligibility.invalidate(sessionId)
-      emit('api-session/added', buildSummary(sessionId, entry.title, restoredSnapshot))
       logger.info(`restored ${sessionId} from ${entry.trashId} (${mode}) in ${Date.now() - startedAt}ms`)
       return {
         sessionId,
@@ -930,40 +1254,19 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
         if (original.state === 'trashing') {
           await assertSafeObject(original)
-          const sourceExists = (await entryKind(original.originalSessionDir)) === 'directory'
-          const targetExists = await trashSessionExists(original)
-          if (!sourceExists && !targetExists) {
-            commit({ ...original, state: 'missing', lastError: 'Both the session source and the trash copy are missing.' })
+          const settled = await resolveTrashing(original)
+          if (settled.kind === 'missing') {
+            commit(settled.entry)
             missing += 1
-          } else if (!sourceExists && targetExists) {
-            const measured = await measureDirectory(store.sessionPath(original.trashId))
-            if (!metricsMatch(original, measured)) {
-              commit(fail({ ...original, state: 'trashing' }, 'The trash copy does not match the recorded size.'))
-            } else {
-              commit({ ...original, state: 'trashed', trashedAt: original.startedAt || Date.now(), lastError: null })
-              completed += 1
-            }
-          } else if (sourceExists && !targetExists) {
+          } else if (settled.kind === 'rolledBack') {
             await store.removeObjectDir(original.trashId).catch((error) => {
               logger.warn(`cannot remove the rolled-back trash object ${original.trashId}: ${messageOf(error)}`)
             })
             drop(original.sessionId)
             rolledBack += 1
           } else {
-            const measured = await measureDirectory(store.sessionPath(original.trashId))
-            if (!metricsMatch(original, measured)) {
-              await store.removeObjectDir(original.trashId)
-              drop(original.sessionId)
-              rolledBack += 1
-            } else {
-              try {
-                await store.removeSessionSource(original.originalSessionDir)
-                commit({ ...original, state: 'trashed', trashedAt: original.startedAt || Date.now(), lastError: null })
-                completed += 1
-              } catch (error) {
-                commit(fail(original, `Cannot remove the source after completing the move: ${messageOf(error)}`))
-              }
-            }
+            commit({ ...original, state: 'trashed', trashedAt: original.startedAt || Date.now(), lastError: null })
+            completed += 1
           }
           changed += 1
           continue
@@ -971,15 +1274,17 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
         if (original.state === 'restoring') {
           await assertSafeObject(original)
-          const sourceExists = (await entryKind(original.originalSessionDir)) === 'directory'
-          const targetExists = await trashSessionExists(original)
-          if (sourceExists) {
-            const measured = await measureDirectory(original.originalSessionDir)
-            const visible = metricsMatch(original, measured)
-              ? await waitForVisibility(original.sessionId, (current) => current !== undefined && current !== null && current.location !== undefined)
-              : false
-            if (!visible) {
-              commit(fail(original, 'The restored session is not visible to session storage.'))
+          const settled = await resolveRestoring(original)
+          if (settled.kind === 'missing') {
+            commit(settled.entry)
+            missing += 1
+          } else if (settled.kind === 'trashed') {
+            commit(settled.entry)
+            rolledBack += 1
+          } else {
+            const visible = await waitForMembersVisible(original)
+            if (!visible.visible) {
+              commit(fail(original, 'The restored session tree is not visible to session storage.'))
               changed += 1
               continue
             }
@@ -988,15 +1293,6 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
             })
             drop(original.sessionId)
             completed += 1
-            changed += 1
-            continue
-          }
-          if (targetExists) {
-            commit({ ...original, state: 'trashed', lastError: 'Recovered the trash copy after an interrupted restore.' })
-            rolledBack += 1
-          } else {
-            commit({ ...original, state: 'missing', lastError: 'Both the trash copy and the restore target are missing.' })
-            missing += 1
           }
           changed += 1
           continue
@@ -1004,22 +1300,23 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
         if (original.state === 'trashed') {
           await assertSafeObject(original)
-          const sourceExists = (await entryKind(original.originalSessionDir)) === 'directory'
-          const targetExists = await trashSessionExists(original)
-          if (!targetExists) {
+          const presence = await memberPresence(store, original)
+          if (presence.present < presence.total) {
             commit({
               ...original,
               state: 'missing',
-              lastError: sourceExists
-                ? 'The trash copy is missing; the original session directory is still present.'
-                : 'The trash copy is missing.',
+              lastError:
+                presence.present === 0
+                  ? 'The trash copy is missing.'
+                  : `The trash copy is missing these member sessions: ${presence.missing.join(', ')}.`,
             })
             missing += 1
             changed += 1
             continue
           }
-          if (sourceExists) {
-            commit(fail(original, 'The original session directory unexpectedly exists alongside the trash copy; both were kept.'))
+          const rows = await memberRows(original)
+          if (rows.some((row) => row.source)) {
+            commit(fail(original, 'An original session directory unexpectedly exists alongside the trash copy; both were kept.'))
             changed += 1
           }
         }