@wangxiaocuo/dsh-session-trash 0.5.1 → 0.6.1

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,9 @@ import {
   moveDirectory,
   samePath,
 } from './fsops.js'
-import { reconcileIndex, rebuildIndex } from './inventory.js'
+import { mapLimit } from './concurrency.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
@@ -20,6 +23,9 @@ const VISIBILITY_RETRIES = 5
 /** Delay between visibility probes. */
 const VISIBILITY_DELAY_MS = 100
 
+/** Maximum concurrent object deletions and sidecar rewrites during a purge. */
+const PURGE_CONCURRENCY = 4
+
 /**
  * @param {number} milliseconds delay length.
  * @returns {Promise<void>} resolution after the delay.
@@ -170,9 +176,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 +213,229 @@ 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.
+   * Probe every member directory in parallel: where the source copy and the
+   * trash copy currently live.
+   *
+   * @param {object} entry index entry.
+   * @returns {Promise<{ index: number, member: object, source: boolean, trash: boolean }[]>} member positions.
    */
-  async function trashSessionExists(entry) {
-    return (await entryKind(store.sessionPath(entry.trashId))) === 'directory'
+  async function memberRows(entry) {
+    const members = membersOf(entry)
+    return Promise.all(
+      members.map(async (member, index) => {
+        const [sourceKind, trashKind] = await Promise.all([
+          kindOf(member.originalSessionDir),
+          kindOf(memberTrashPath(entry, index)),
+        ])
+        return {
+          index,
+          member,
+          source: sourceKind === 'directory',
+          trash: trashKind === 'directory',
+        }
+      }),
+    )
+  }
+
+  /**
+   * Probe only the original session directories of every member, in parallel.
+   * Used by recovery after the trash copies were already proven present.
+   *
+   * @param {object} entry index entry.
+   * @returns {Promise<{ index: number, member: object, source: boolean }[]>} member source positions.
+   */
+  async function sourceRows(entry) {
+    const members = membersOf(entry)
+    return Promise.all(
+      members.map(async (member, index) => ({
+        index,
+        member,
+        source: (await kindOf(member.originalSessionDir)) === 'directory',
+      })),
+    )
+  }
+
+  /**
+   * @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 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) {
+    const results = await Promise.all(
+      membersOf(entry).map(async (member) => ({
+        sessionId: member.sessionId,
+        hidden: await waitForVisibility(member.sessionId, (current) => current === undefined || current === null),
+      })),
+    )
+    const failed = results.find((result) => !result.hidden)
+    return failed === undefined ? { hidden: true } : { hidden: false, sessionId: failed.sessionId }
+  }
+
+  /**
+   * @param {object} entry index entry.
+   * @returns {Promise<{ visible: boolean, sessionId?: string }>} whether session storage reports every member again.
+   */
+  async function waitForMembersVisible(entry) {
+    const results = await Promise.all(
+      membersOf(entry).map(async (member) => ({
+        sessionId: member.sessionId,
+        visible: await waitForVisibility(
+          member.sessionId,
+          (current) => current !== undefined && current !== null && current.location !== undefined,
+        ),
+      })),
+    )
+    const failed = results.find((result) => !result.visible)
+    return failed === undefined ? { visible: true } : { visible: false, sessionId: failed.sessionId }
   }
 
   /**
@@ -419,98 +665,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
   }
 
   /**
@@ -524,6 +857,99 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     return entry.trashedAt + config.retentionDays * 86_400_000 <= now
   }
 
+  /**
+   * Permanently remove a batch of object directories and their index entries in
+   * a bounded number of index writes. Every entry is first committed as
+   * `purging` in one write, so a crash still settles forward on the next
+   * recovery; successes are dropped and failures annotated in one final write.
+   * The caller owns the trash lock.
+   *
+   * @param {readonly object[]} targets `trashed` entries to purge.
+   * @returns {Promise<{ purged: number, failures: { entry: object, error: unknown, phase: string }[] }>} per-entry outcome.
+   */
+  async function purgeManyInsideLock(targets) {
+    const failures = []
+    const purging = []
+    for (const entry of targets) {
+      try {
+        await assertSafeObject(entry)
+        purging.push({ ...entry, state: 'purging', lastError: null })
+      } catch (error) {
+        failures.push({ entry, error, phase: 'validate' })
+      }
+    }
+    if (purging.length === 0) return { purged: 0, failures }
+
+    let marked = store.entries()
+    for (const entry of purging) marked = upsertEntry(marked, entry)
+    try {
+      await store.commit(marked)
+    } catch (error) {
+      const failure = new TrashError(
+        'INDEX_WRITE_FAILED',
+        'The session logs were not deleted because the trash index could not be updated.',
+        { code: error instanceof TrashError ? error.code : null },
+      )
+      for (const entry of purging) failures.push({ entry, error: failure, phase: 'mark' })
+      return { purged: 0, failures }
+    }
+    await mapLimit(purging, PURGE_CONCURRENCY, async (entry) => {
+      await store.writeMeta(entry).catch((error) => {
+        logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${messageOf(error)}`)
+      })
+    })
+
+    const deleted = await mapLimit(purging, PURGE_CONCURRENCY, async (entry) => {
+      try {
+        await store.removeObjectDir(entry.trashId)
+        return { entry, deleted: true }
+      } catch (error) {
+        return { entry, deleted: false, error }
+      }
+    })
+    const completed = []
+    const annotated = []
+    for (const result of deleted) {
+      if (result.deleted) {
+        completed.push(result.entry)
+        logger.info(`permanently deleted ${result.entry.sessionId} (${result.entry.trashId})`)
+        continue
+      }
+      annotated.push({
+        ...result.entry,
+        lastError: errorText(`The session log could not be deleted: ${messageOf(result.error)}`),
+      })
+      failures.push({
+        entry: result.entry,
+        error: new TrashError('IO_ERROR', 'The session log could not be deleted.', { trashId: result.entry.trashId }),
+        phase: 'delete',
+      })
+    }
+
+    let settled = store.entries()
+    for (const entry of completed) settled = dropEntry(settled, entry.sessionId)
+    for (const entry of annotated) settled = upsertEntry(settled, entry)
+    try {
+      await store.commit(settled)
+    } catch (error) {
+      const failure = new TrashError(
+        'INDEX_WRITE_FAILED',
+        'The session logs were deleted, but the trash index could not be updated.',
+        { code: error instanceof TrashError ? error.code : null },
+      )
+      for (const entry of completed) failures.push({ entry, error: failure, phase: 'drop' })
+      // The deleted objects no longer match the purging entries; the next
+      // recovery drops them, so nothing is reported as successfully purged.
+      return { purged: 0, failures }
+    }
+    await mapLimit(annotated, PURGE_CONCURRENCY, async (entry) => {
+      await store.writeMeta(entry).catch((error) => {
+        logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${messageOf(error)}`)
+      })
+    })
+    return { purged: completed.length, failures }
+  }
+
   /**
    * Permanently remove one object directory and its index entry. The caller
    * owns the trash lock.
@@ -532,26 +958,35 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * @returns {Promise<void>} resolution once the object and entry are gone.
    */
   async function purgeInsideLock(entry) {
-    await assertSafeObject(entry)
-    const purging = { ...entry, state: 'purging', lastError: null }
-    await store.commit(upsertEntry(store.entries(), purging))
-    await store.writeMeta(purging).catch((error) => {
-      logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${messageOf(error)}`)
-    })
-    try {
-      await store.removeObjectDir(entry.trashId)
-    } catch (error) {
-      await markFailure(purging, `The session log could not be deleted: ${messageOf(error)}`)
-      throw new TrashError('IO_ERROR', 'The session log could not be deleted.', { trashId: entry.trashId })
-    }
+    const result = await purgeManyInsideLock([entry])
+    if (result.failures.length > 0) throw result.failures[0].error
+  }
+
+  /**
+   * Drop a batch of `missing` entries from the index in one write and remove
+   * their plugin-owned remnants. No session file is deleted. The caller owns
+   * the trash lock.
+   *
+   * @param {readonly object[]} entries `missing` index entries to forget.
+   * @returns {Promise<number>} how many entries were removed from the index.
+   */
+  async function forgetManyInsideLock(entries) {
+    if (entries.length === 0) return 0
+    let next = store.entries()
+    for (const entry of entries) next = dropEntry(next, entry.sessionId)
     try {
-      await store.commit(dropEntry(store.entries(), entry.sessionId))
+      await store.commit(next)
     } catch (error) {
-      throw new TrashError('INDEX_WRITE_FAILED', 'The session log was deleted, but the trash index could not be updated.', {
+      throw new TrashError('INDEX_WRITE_FAILED', 'The trash index could not be updated.', {
         code: error instanceof TrashError ? error.code : null,
       })
     }
-    logger.info(`permanently deleted ${entry.sessionId} (${entry.trashId})`)
+    for (const entry of entries) {
+      await store.removeObjectRemnants(entry.trashId).catch((error) => {
+        logger.warn(`cannot remove the remnants of ${entry.trashId}: ${messageOf(error)}`)
+      })
+    }
+    return entries.length
   }
 
   /**
@@ -562,28 +997,20 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * @returns {Promise<{ sessionId: string, title: string }>} the removed identity.
    */
   async function forgetInsideLock(entry) {
-    try {
-      await store.commit(dropEntry(store.entries(), entry.sessionId))
-    } catch (error) {
-      throw new TrashError('INDEX_WRITE_FAILED', 'The trash index could not be updated.', {
-        code: error instanceof TrashError ? error.code : null,
-      })
-    }
-    await store.removeObjectRemnants(entry.trashId).catch((error) => {
-      logger.warn(`cannot remove the remnants of ${entry.trashId}: ${messageOf(error)}`)
-    })
+    await forgetManyInsideLock([entry])
     return { sessionId: entry.sessionId, title: entry.title }
   }
 
   /**
-   * 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 +1030,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 +1103,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 +1140,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)}`)
-      }
-      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,
+        throw error instanceof TrashError
+          ? error
+          : new TrashError('IO_ERROR', `Cannot move the session tree into the trash: ${messageOf(error)}`)
+      }
+      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 +1223,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 +1282,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 })
+        settled = await resolveRestoring(restoring)
       } 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)}`)
-        }
+        throw error instanceof TrashError
+          ? error
+          : new TrashError('IO_ERROR', `Cannot move the session tree back: ${messageOf(error)}`)
       }
-
-      let measured
-      try {
-        measured = await measureDirectory(target)
-      } catch (error) {
-        throw new TrashError('RESTORE_VERIFY_FAILED', `Cannot verify the restored session: ${messageOf(error)}`)
+      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.')
       }
-      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 === '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 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.')
-      }
-
-      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,
@@ -898,12 +1346,16 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   /**
    * Apply the crash matrix to every index entry. The caller must hold the trash
    * lock. It never deletes an unindexed object and never removes a `missing`
-   * entry on its own.
+   * entry on its own. An optional presence map lets the caller reuse the probe
+   * results from the preceding reconcile instead of stat-ing every member
+   * directory again.
    *
+   * @param {Map<string, { total: number, present: number, missing: string[] }>} [presenceByTrashId] reconcile probe results keyed by object identity.
    * @returns {Promise<{ changed: number, completed: number, rolledBack: number, missing: number }>} recovery summary.
    */
-  async function recoverInsideLock() {
+  async function recoverInsideLock(presenceByTrashId = new Map()) {
     let entries = [...store.entries()]
+    const metaUpdates = []
     let changed = 0
     let completed = 0
     let rolledBack = 0
@@ -911,6 +1363,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     const commit = (next) => {
       if (next === undefined) return
       entries = upsertEntry(entries, next)
+      metaUpdates.push(next)
     }
     const drop = (sessionId) => {
       entries = dropEntry(entries, sessionId)
@@ -930,40 +1383,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 +1403,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 +1422,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 +1429,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 = presenceByTrashId.get(original.trashId) ?? (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 sources = await sourceRows(original)
+          if (sources.some((row) => row.source)) {
+            commit(fail(original, 'An original session directory unexpectedly exists alongside the trash copy; both were kept.'))
             changed += 1
           }
         }
@@ -1031,7 +1457,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
     if (changed > 0) {
       await store.commit(entries)
-      for (const entry of entries) {
+      for (const entry of metaUpdates) {
         await store.writeMeta(entry).catch((error) => {
           logger.warn(`cannot refresh trash metadata for ${entry.trashId}: ${messageOf(error)}`)
         })
@@ -1058,7 +1484,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
       return summary
     } catch (error) {
       logger.warn(`trash index reconciliation failed: ${messageOf(error)}`)
-      return { imported: 0, markedMissing: 0, unindexed: store.unindexed, changed: 0 }
+      return { imported: 0, markedMissing: 0, unindexed: store.unindexed, changed: 0, presence: new Map() }
     }
   }
 
@@ -1075,18 +1501,17 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
         throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses cleanup.')
       }
       const reconcile = await reconcileInsideLock(now)
-      const recovery = await recoverInsideLock()
+      const recovery = await recoverInsideLock(reconcile.presence)
       let purged = 0
       let failed = 0
       if (allowPurge) {
-        for (const entry of [...store.entries()]) {
-          if (!isExpired(entry, now)) continue
-          try {
-            await purgeInsideLock(entry)
-            purged += 1
-          } catch (error) {
-            failed += 1
-            logger.warn(`cannot purge the expired session ${entry.sessionId}: ${messageOf(error)}`)
+        const expired = [...store.entries()].filter((entry) => isExpired(entry, now))
+        if (expired.length > 0) {
+          const result = await purgeManyInsideLock(expired)
+          purged = result.purged
+          failed = result.failures.length
+          for (const failure of result.failures) {
+            logger.warn(`cannot purge the expired session ${failure.entry.sessionId}: ${messageOf(failure.error)}`)
           }
         }
       }
@@ -1156,34 +1581,59 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
         throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses deletion.')
       }
       const reconcile = await reconcileInsideLock(Date.now())
-      const recovery = await recoverInsideLock()
-      let purged = 0
-      let forgotten = 0
-      let failed = 0
+      const recovery = await recoverInsideLock(reconcile.presence)
       const failures = []
+      const purgeTargets = []
+      const forgetTargets = []
+      let failed = 0
       for (const entry of [...store.entries()]) {
+        if (entry.state === 'trashed') {
+          purgeTargets.push(entry)
+          continue
+        }
+        if (entry.state === 'missing') {
+          forgetTargets.push(entry)
+          continue
+        }
         const title = typeof entry.title === 'string' ? entry.title : ''
-        try {
-          if (entry.state === 'trashed') {
-            await purgeInsideLock(entry)
-            purged += 1
-            continue
-          }
-          if (entry.state === 'missing') {
-            await forgetInsideLock(entry)
-            forgotten += 1
-            continue
-          }
+        const message = `The trash entry is in state "${entry.state}" and cannot be cleaned up.`
+        failed += 1
+        failures.push({ sessionId: entry.sessionId, title, message })
+        logger.warn(`cannot purge the session ${entry.sessionId}: ${message}`)
+      }
+
+      let purged = 0
+      if (purgeTargets.length > 0) {
+        const result = await purgeManyInsideLock(purgeTargets)
+        purged = result.purged
+        for (const failure of result.failures) {
           failed += 1
-          const message = `The trash entry is in state "${entry.state}" and cannot be cleaned up.`
-          failures.push({ sessionId: entry.sessionId, title, message })
-          logger.warn(`cannot purge the session ${entry.sessionId}: ${message}`)
+          failures.push({
+            sessionId: failure.entry.sessionId,
+            title: typeof failure.entry.title === 'string' ? failure.entry.title : '',
+            message: messageOf(failure.error),
+          })
+          logger.warn(`cannot purge the trashed session ${failure.entry.sessionId}: ${messageOf(failure.error)}`)
+        }
+      }
+
+      let forgotten = 0
+      if (forgetTargets.length > 0) {
+        try {
+          forgotten = await forgetManyInsideLock(forgetTargets)
         } catch (error) {
-          failed += 1
-          failures.push({ sessionId: entry.sessionId, title, message: messageOf(error) })
-          logger.warn(`cannot purge the trashed session ${entry.sessionId}: ${messageOf(error)}`)
+          failed += forgetTargets.length
+          for (const entry of forgetTargets) {
+            failures.push({
+              sessionId: entry.sessionId,
+              title: typeof entry.title === 'string' ? entry.title : '',
+              message: messageOf(error),
+            })
+            logger.warn(`cannot forget the missing session ${entry.sessionId}: ${messageOf(error)}`)
+          }
         }
       }
+
       logger.info(`bulk purge finished: purged ${purged}, forgotten ${forgotten}, failed ${failed}`)
       return {
         purged,
@@ -1272,8 +1722,8 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     try {
       summary = await store.withLock(async () => {
         if (store.isProtected()) return { changed: 0, completed: 0, rolledBack: 0, missing: 0 }
-        await reconcileInsideLock(Date.now())
-        return await recoverInsideLock()
+        const reconcile = await reconcileInsideLock(Date.now())
+        return await recoverInsideLock(reconcile.presence)
       })
     } catch (error) {
       if (error instanceof TrashError && error.code === 'LOCKED') {