@wangxiaocuo/dsh-session-trash 0.6.4 → 0.6.6

package/lib/cleanup.js

@@ -68,7 +68,7 @@ function resolveTimer(ctx) {
  *   start: () => void,
  *   stop: () => void,
  *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<any>,
- *   maybeSweepOnPageOpen: () => void,
+ *   sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: object }>,
  *   nextSweepAt: () => number | null,
  *   lastSweepAt: () => number,
  *   diagnostics: () => any,
@@ -294,17 +294,24 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
     runNow,
 
     /**
-     * Trigger a throttled background sweep when the trash page opens. The
+     * Run the throttled sweep the trash page requests when it opens. The
      * timer-backed composition uses a one-hour throttle; without a timer the
-     * configured sweep interval throttles instead.
+     * configured sweep interval throttles instead. This is an explicit POST so
+     * the read-only `/state` projection never deletes anything.
      *
-     * @returns {void}
+     * @returns {Promise<{ ran: boolean, reason?: string, result?: object }>} the sweep outcome.
      */
-    maybeSweepOnPageOpen() {
-      if (stopped) return
+    async sweepOnPageOpen() {
+      if (stopped) return { ran: false, reason: 'stopped' }
       const throttle = timer === undefined || !config.enableAutoCleanup ? intervalMs : PAGE_OPEN_THROTTLE_MS
-      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return
-      void runNow({ reason: 'page-open' }).catch(report)
+      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return { ran: false, reason: 'throttled' }
+      try {
+        const result = await runNow({ reason: 'page-open' })
+        return { ran: true, result }
+      } catch (error) {
+        report(error)
+        return { ran: false, reason: 'failed' }
+      }
     },
 
     /**

package/lib/errors.js

@@ -43,7 +43,7 @@ export class TrashError extends Error {
   /**
    * @param {string} code stable error code.
    * @param {string} message owner-facing explanation.
-   * @param {any} [details] optional structured context.
+   * @param {Record<string, unknown>} [details] optional structured context.
    */
   constructor(code, message, details) {
     super(message)
@@ -54,7 +54,7 @@ export class TrashError extends Error {
 }
 
 /**
- * @param {any} error arbitrary thrown value.
+ * @param {unknown} error arbitrary thrown value.
  * @returns {number} HTTP status for this error.
  */
 export function statusOf(error) {
@@ -86,26 +86,29 @@ const SAFE_DETAIL_KEYS = new Set([
  * Metrics snapshots are the only nested detail value the Host returns; keep
  * only their numeric counters so no path can ride along.
  *
- * @param {any} value candidate metrics object.
- * @returns {any | undefined} the numeric metrics.
+ * @param {unknown} value candidate metrics object.
+ * @returns {{ sizeBytes?: number, fileCount?: number, symlinkCount?: number } | undefined} the numeric metrics.
  */
 function sanitizeMetrics(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = /** @type {Record<string, unknown>} */ (value)
+  /** @type {Record<string, unknown>} */
   const safe = {}
   for (const key of ['sizeBytes', 'fileCount', 'symlinkCount']) {
-    if (typeof value[key] === 'number') safe[key] = value[key]
+    if (typeof record[key] === 'number') safe[key] = record[key]
   }
   return Object.keys(safe).length === 0 ? undefined : safe
 }
 
 /**
- * @param {any} details arbitrary structured context.
- * @returns {any | undefined} the same context restricted to whitelisted keys.
+ * @param {unknown} details arbitrary structured context.
+ * @returns {Record<string, unknown> | undefined} the same context restricted to whitelisted keys.
  */
 export function sanitizeDetails(details) {
   if (details === null || typeof details !== 'object' || Array.isArray(details)) return undefined
+  /** @type {Record<string, unknown>} */
   const safe = {}
-  for (const [key, value] of Object.entries(details)) {
+  for (const [key, value] of Object.entries(/** @type {Record<string, unknown>} */ (details))) {
     if (!SAFE_DETAIL_KEYS.has(key)) continue
     if (key === 'expected' || key === 'measured') {
       const metrics = sanitizeMetrics(value)
@@ -122,8 +125,8 @@ export function sanitizeDetails(details) {
 }
 
 /**
- * @param {any} error arbitrary thrown value.
- * @returns {{ code: string, message: string, details?: object }} the wire error shape.
+ * @param {unknown} error arbitrary thrown value.
+ * @returns {{ code: string, message: string, details?: Record<string, unknown> }} the wire error shape.
  */
 export function toWireError(error) {
   if (error instanceof TrashError) {

package/lib/fsops.js

@@ -36,11 +36,13 @@ const COPY_OPTIONS = {
 }
 
 /**
- * @param {any} error thrown filesystem failure.
+ * @param {unknown} error thrown filesystem failure.
  * @returns {string | undefined} the Node error code.
  */
 export function errorCode(error) {
-  return error !== null && typeof error === 'object' && typeof error.code === 'string' ? error.code : undefined
+  if (error === null || typeof error !== 'object') return undefined
+  const code = /** @type {Record<string, unknown>} */ (error).code
+  return typeof code === 'string' ? code : undefined
 }
 
 /**
@@ -194,7 +196,7 @@ export function isInside(root, target) {
 }
 
 /**
- * @param {any} trashId candidate object identity.
+ * @param {unknown} trashId candidate object identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeTrashId(trashId) {
@@ -214,7 +216,7 @@ export function isSafeTrashId(trashId) {
  * object. Session ids are `session-<uuid>` or a bare uuid today, so the
  * accepted alphabet is deliberately conservative.
  *
- * @param {any} sessionId candidate member identity.
+ * @param {unknown} sessionId candidate member identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeMemberId(sessionId) {
@@ -339,7 +341,7 @@ export function createTrashId() {
  * @param {string} destination final directory path.
  * @param {{ sizeBytes: number, fileCount: number }} expected recorded metrics.
  * @param {(from: string, to: string) => Promise<void>} rename rename implementation for tests.
- * @param {(source: string, destination: string, options: any) => Promise<void>} copy copy implementation for tests.
+ * @param {(source: string, destination: string, options: import('node:fs').CopyOptions) => Promise<void>} copy copy implementation for tests.
  * @returns {Promise<void>} resolution after the destination is published.
  */
 async function copyAcrossDevices(source, destination, expected, rename, copy) {
@@ -382,7 +384,7 @@ async function copyAcrossDevices(source, destination, expected, rename, copy) {
  * @param {{
  *   logger?: { warn: Function },
  *   rename?: (from: string, to: string) => Promise<void>,
- *   copy?: (source: string, destination: string, options: any) => Promise<void>,
+ *   copy?: (source: string, destination: string, options: import('node:fs').CopyOptions) => Promise<void>,
  * }} [options] diagnostics sink and test seams.
  * @returns {Promise<void>} resolution after the directory lives at `destination`.
  */

package/lib/http.js

@@ -160,12 +160,13 @@ function requireSessionId(body) {
  *     forget: (sessionId: string) => Promise<any>,
  *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<any>,
  *     rebuild: () => Promise<any>,
+ *     purgeEmptyOrphans: () => Promise<{ removed: number }>,
  *   },
  *   cleanupService?: {
-    runNow: (options?: any) => Promise<any>,
-    maybeSweepOnPageOpen: () => void,
-    diagnostics?: () => any,
-  },
+ *     runNow: (options?: any) => Promise<any>,
+ *     sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: any }>,
+ *     diagnostics?: () => any,
+ *   },
  *   ready: Promise<unknown>,
  *   config: any,
  *   logger: any,
@@ -264,11 +265,28 @@ export function registerApi({ ctx, eligibility, stateService, trashService, clea
 
   route('state', 'GET', async (_req, res) => {
     sendJson(res, 200, await stateService.snapshot())
-    try {
-      cleanupService?.maybeSweepOnPageOpen()
-    } catch (error) {
-      logger.warn(`cannot schedule the page-open trash sweep: ${error instanceof Error ? error.message : String(error)}`)
-    }
+  })
+
+  route('sweep', 'POST', async (_req, res) => {
+    const outcome = await cleanupService.sweepOnPageOpen()
+    const result = outcome.result !== null && outcome.result !== undefined ? outcome.result : null
+    sendJson(res, 200, {
+      ok: true,
+      ran: outcome.ran === true,
+      ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+      ...(result === null
+        ? {}
+        : {
+            purged: result.purged ?? 0,
+            failed: result.failed ?? 0,
+            settled: result.changed ?? 0,
+          }),
+    })
+  })
+
+  route('orphans/forget', 'POST', async (_req, res) => {
+    const result = await trashService.purgeEmptyOrphans()
+    sendJson(res, 200, { ok: true, removed: result.removed ?? 0 })
   })
 
   route('preflight', 'POST', async (req, res) => {

package/lib/inventory.js

@@ -336,6 +336,30 @@ export async function scanObjects(store, logger) {
   return { objects, unindexed }
 }
 
+/**
+ * Plugin-owned sidecar names that may remain inside an otherwise empty object
+ * directory. Everything else (session/, children/, stray files) is payload.
+ */
+const PLUGIN_OWNED_OBJECT_NAMES = new Set(['meta.json', 'meta.json.tmp'])
+
+/**
+ * Whether an object directory holds no session payload, only plugin metadata
+ * that can be recreated. Used to offer a safe cleanup for unindexed leftovers.
+ *
+ * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
+ * @param {string} trashId object identity.
+ * @returns {Promise<boolean>} whether the directory is safe to remove.
+ */
+export async function isEmptyObjectDir(store, trashId) {
+  if (!isSafeTrashId(trashId)) return false
+  try {
+    const names = await fs.readdir(store.objectDir(trashId))
+    return names.every((name) => PLUGIN_OWNED_OBJECT_NAMES.has(name))
+  } catch {
+    return false
+  }
+}
+
 /**
  * Import object directories the index does not know about and mark entries
  * whose object directory vanished. Never deletes a session file or an object

package/lib/members.js

@@ -8,39 +8,74 @@
  */
 
 /**
- * @param {any} entry index entry (v1 or v2 shape).
- * @returns {object|null} the parent member, or null when the entry has no directory data.
+ * @typedef {object} Member
+ * @property {string} sessionId
+ * @property {'subagent' | null} [origin]
+ * @property {string} [title]
+ * @property {string} [originalSessionDir]
+ * @property {string} [originalLogPath]
+ * @property {string} [persistenceProjectDirHint]
+ * @property {string} [formatStatus]
+ * @property {number | null} [sizeBytes]
+ * @property {number | null} [fileCount]
+ */
+
+/**
+ * @typedef {object} TrashEntry
+ * @property {string} sessionId
+ * @property {string} [trashId]
+ * @property {string} [state]
+ * @property {string} [title]
+ * @property {number} [trashedAt]
+ * @property {number} [startedAt]
+ * @property {string | null} [originalCwd]
+ * @property {boolean} [workspaceExistsAtDeletion]
+ * @property {string} [originalSessionDir]
+ * @property {string} [originalLogPath]
+ * @property {string} [persistenceProjectDirHint]
+ * @property {string} [formatStatus]
+ * @property {number | null} [sizeBytes]
+ * @property {number | null} [fileCount]
+ * @property {string | null} [lastError]
+ * @property {Member[]} [members]
+ */
+
+/**
+ * @param {unknown} entry index entry (v1 or v2 shape).
+ * @returns {Member | null} the parent member, or null when the entry has no directory data.
  */
 export function parentMember(entry) {
   if (entry === null || typeof entry !== 'object') return null
-  if (typeof entry.sessionId !== 'string' || entry.sessionId === '') return null
+  const record = /** @type {Record<string, any>} */ (entry)
+  if (typeof record.sessionId !== 'string' || record.sessionId === '') return null
   return {
-    sessionId: entry.sessionId,
+    sessionId: record.sessionId,
     origin: null,
-    title: typeof entry.title === 'string' ? entry.title : entry.sessionId,
-    originalSessionDir: entry.originalSessionDir,
-    originalLogPath: entry.originalLogPath,
-    persistenceProjectDirHint: entry.persistenceProjectDirHint,
-    formatStatus: entry.formatStatus,
-    sizeBytes: entry.sizeBytes,
-    fileCount: entry.fileCount,
+    title: typeof record.title === 'string' ? record.title : record.sessionId,
+    originalSessionDir: record.originalSessionDir,
+    originalLogPath: record.originalLogPath,
+    persistenceProjectDirHint: record.persistenceProjectDirHint,
+    formatStatus: record.formatStatus,
+    sizeBytes: record.sizeBytes,
+    fileCount: record.fileCount,
   }
 }
 
 /**
- * @param {any} entry index entry (v1 or v2 shape).
- * @returns {any[]} every owned directory, parent first.
+ * @param {unknown} entry index entry (v1 or v2 shape).
+ * @returns {Member[]} every owned directory, parent first.
  */
 export function memberList(entry) {
-  if (entry !== null && typeof entry === 'object' && Array.isArray(entry.members) && entry.members.length > 0) {
-    return entry.members
+  if (entry !== null && typeof entry === 'object') {
+    const record = /** @type {Record<string, any>} */ (entry)
+    if (Array.isArray(record.members) && record.members.length > 0) return record.members
   }
   const parent = parentMember(entry)
   return parent === null ? [] : [parent]
 }
 
 /**
- * @param {readonly any[]} members member list.
+ * @param {ReadonlyArray<Partial<Member> | null | undefined>} members member list.
  * @returns {{ sizeBytes: number, fileCount: number }} summed measurable totals.
  */
 export function aggregateMetrics(members) {
@@ -57,21 +92,26 @@ export function aggregateMetrics(members) {
  * Shape-level validation shared by the durable index and object sidecars.
  * Path strictness belongs to the sidecar validator.
  *
- * @param {any} member candidate member.
+ * @param {unknown} member candidate member.
  * @returns {boolean} whether the member carries the required v2 identity.
  */
 export function isValidMemberShape(member) {
   if (member === null || typeof member !== 'object' || Array.isArray(member)) return false
-  if (typeof member.sessionId !== 'string' || member.sessionId === '' || member.sessionId.length > 256) return false
-  if (member.origin !== undefined && member.origin !== null && member.origin !== 'subagent') return false
-  if (member.title !== undefined && typeof member.title !== 'string') return false
-  if (member.formatStatus !== undefined && member.formatStatus !== 'current' && member.formatStatus !== 'migration-required') {
+  const record = /** @type {Record<string, any>} */ (member)
+  if (typeof record.sessionId !== 'string' || record.sessionId === '' || record.sessionId.length > 256) return false
+  if (record.origin !== undefined && record.origin !== null && record.origin !== 'subagent') return false
+  if (record.title !== undefined && typeof record.title !== 'string') return false
+  if (
+    record.formatStatus !== undefined &&
+    record.formatStatus !== 'current' &&
+    record.formatStatus !== 'migration-required'
+  ) {
     return false
   }
-  if (member.sizeBytes !== undefined && member.sizeBytes !== null && typeof member.sizeBytes !== 'number') return false
-  if (member.fileCount !== undefined && member.fileCount !== null && typeof member.fileCount !== 'number') return false
+  if (record.sizeBytes !== undefined && record.sizeBytes !== null && typeof record.sizeBytes !== 'number') return false
+  if (record.fileCount !== undefined && record.fileCount !== null && typeof record.fileCount !== 'number') return false
   for (const key of ['originalSessionDir', 'originalLogPath', 'persistenceProjectDirHint']) {
-    if (member[key] !== undefined && member[key] !== null && typeof member[key] !== 'string') return false
+    if (record[key] !== undefined && record[key] !== null && typeof record[key] !== 'string') return false
   }
   return true
 }
@@ -79,17 +119,19 @@ export function isValidMemberShape(member) {
 /**
  * Whether the v2 member list is internally consistent with its parent entry.
  *
- * @param {any} entry index entry carrying `members`.
+ * @param {unknown} entry index entry carrying `members`.
  * @returns {boolean} whether the list is acceptable.
  */
 export function isValidMemberList(entry) {
   if (entry === null || typeof entry !== 'object') return false
-  if (!Array.isArray(entry.members) || entry.members.length === 0 || entry.members.length > 64) return false
+  const record = /** @type {Record<string, any>} */ (entry)
+  const members = record.members
+  if (!Array.isArray(members) || members.length === 0 || members.length > 64) return false
   const seen = new Set()
-  for (const member of entry.members) {
+  for (const member of members) {
     if (!isValidMemberShape(member)) return false
     if (seen.has(member.sessionId)) return false
     seen.add(member.sessionId)
   }
-  return entry.members[0].sessionId === entry.sessionId
+  return members[0].sessionId === record.sessionId
 }

package/lib/state.js

@@ -48,18 +48,60 @@ async function directoryExists(directory) {
   }
 }
 
+/**
+ * @typedef {object} TrashConfig
+ * @property {number} retentionDays
+ * @property {number} sweepIntervalHours
+ * @property {boolean} enableAutoCleanup
+ */
+
+/**
+ * @typedef {object} CleanupDiagnostics
+ * @property {boolean} enabled
+ * @property {boolean} timerBacked
+ * @property {number | null} lastAttemptAt
+ * @property {number | null} lastSuccessAt
+ * @property {number | null} nextSweepAt
+ * @property {number | null} retryAt
+ * @property {number} consecutiveFailures
+ * @property {object | null} lastRun
+ */
+
+/**
+ * @typedef {object} StateEntry
+ * @property {string} sessionId
+ * @property {string | undefined} title
+ * @property {number | undefined} trashedAt
+ * @property {number | null} expiresAt
+ * @property {string | null} originalCwd
+ * @property {boolean | null} workspaceExistsAtDeletion
+ * @property {boolean | null} workspaceNowExists
+ * @property {number | null} sizeBytes
+ * @property {number | null} fileCount
+ * @property {string | null} formatStatus
+ * @property {string | undefined} state
+ * @property {boolean} canRestore
+ * @property {boolean} canPurge
+ * @property {boolean} canForget
+ * @property {boolean} requiresOrphanRestore
+ * @property {string | null} lastError
+ * @property {string | null} lastErrorCode
+ * @property {number} subagentCount
+ * @property {{ sessionId: string, origin: 'subagent' | null, sizeBytes: number | null }[]} members
+ */
+
 /**
  * Build the read-only `/state` projection from the committed index.
  *
  * @param {{
  *   store: import('./store.js').TrashStore,
- *   config: { retentionDays: number, sweepIntervalHours: number, enableAutoCleanup: boolean },
+ *   config: TrashConfig,
  *   trashRootDisplay: string,
  *   nextSweepAt?: () => number | null,
- *   cleanup?: () => any,
- *   directoryExists?: (directory?: any) => Promise<boolean>,
+ *   cleanup?: () => CleanupDiagnostics | null,
+ *   directoryExists?: (directory?: string | null) => Promise<boolean>,
  * }} deps state inputs.
- * @returns {{ snapshot: () => Promise<any>, describe: (entry: any) => Promise<any> }} the state service.
+ * @returns {{ snapshot: () => Promise<object>, describe: (entry: import('./members.js').TrashEntry) => Promise<StateEntry> }} the state service.
  */
 export function createStateService({
   store,
@@ -70,13 +112,13 @@ export function createStateService({
   directoryExists: probeDirectory = directoryExists,
 }) {
   /**
-   * @returns {any} cleanup diagnostics, or a neutral fallback.
+   * @returns {CleanupDiagnostics} cleanup diagnostics, or a neutral fallback.
    */
   function cleanupDiagnostics() {
     if (typeof cleanup === 'function') {
       try {
         const value = cleanup()
-        if (value !== null && typeof value === 'object') return value
+        if (value !== null && typeof value === 'object') return /** @type {CleanupDiagnostics} */ (value)
       } catch {
         // Diagnostics must never break the read-only state projection.
       }
@@ -94,10 +136,10 @@ export function createStateService({
   }
 
   /**
-   * @param {any} entry committed index entry.
+   * @param {import('./members.js').TrashEntry} entry committed index entry.
    * @param {Map<string, Promise<boolean>>} [probeCache] workspace probes already
    *   started for this snapshot, so entries sharing a cwd probe it once.
-   * @returns {Promise<any>} the wire entry.
+   * @returns {Promise<StateEntry>} the wire entry.
    */
   async function describeEntry(entry, probeCache = new Map()) {
     const cwd = typeof entry.originalCwd === 'string' && entry.originalCwd !== '' ? entry.originalCwd : null
@@ -140,12 +182,12 @@ export function createStateService({
 
   return {
     /**
-     * @param {any} entry committed index entry.
-     * @returns {Promise<any>} the wire entry.
+     * @param {import('./members.js').TrashEntry} entry committed index entry.
+     * @returns {Promise<StateEntry>} the wire entry.
      */
     describe: describeEntry,
     /**
-     * @returns {Promise<any>} the complete `/state` response body.
+     * @returns {Promise<object>} the complete `/state` response body.
      */
     async snapshot() {
       const probeCache = new Map()

package/lib/store.js

@@ -14,6 +14,22 @@ export const LOCK_STALE_MS = 10 * 60 * 1000
 /** How often a long-running operation refreshes its lock heartbeat. */
 export const LOCK_REFRESH_MS = 60 * 1000
 
+/** How many times a caller retries a lock held by another live process. */
+export const LOCK_WAIT_ATTEMPTS = 3
+
+/** Base delay between live-lock retries. */
+export const LOCK_WAIT_DELAY_MS = 200
+
+/**
+ * @param {number} milliseconds delay length.
+ * @returns {Promise<void>} resolution after the delay.
+ */
+function sleep(milliseconds) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds)
+  })
+}
+
 /**
  * @param {number} [now] timestamp for the new index.
  * @returns {{ version: number, updatedAt: number, entries: any[] }} an empty index document.
@@ -558,10 +574,15 @@ export class TrashStore {
   }
 
   /**
+   * Acquire the cross-process lock. A lock held by another live process is
+   * retried for a short window first, so two windows clicking at the same time
+   * do not surface a spurious LOCKED error.
+   *
    * @returns {Promise<void>} resolution once this process owns the lock.
    */
   async acquireLock() {
-    for (let attempt = 0; attempt < 3; attempt += 1) {
+    let waits = 0
+    for (let attempt = 0; attempt < 6; attempt += 1) {
       try {
         const handle = await fs.open(this.lockPath, 'wx', 0o600)
         try {
@@ -576,6 +597,11 @@ export class TrashStore {
           throw new TrashError('IO_ERROR', `Cannot create the trash lock: ${error instanceof Error ? error.message : String(error)}`)
         }
         if (!(await this.lockIsStale())) {
+          if (waits < LOCK_WAIT_ATTEMPTS - 1) {
+            waits += 1
+            await sleep(LOCK_WAIT_DELAY_MS * waits)
+            continue
+          }
           throw new TrashError('LOCKED', 'Another trash operation is in progress. Try again in a moment.')
         }
         try {

package/lib/trash-service.js

@@ -14,7 +14,7 @@ import {
   samePath,
 } from './fsops.js'
 import { mapLimit } from './concurrency.js'
-import { reconcileIndex, rebuildIndex, memberPresence } from './inventory.js'
+import { isEmptyObjectDir, memberPresence, rebuildIndex, reconcileIndex, scanObjects } from './inventory.js'
 import { aggregateMetrics, memberList } from './members.js'
 
 /** How many short retries confirm a moved or restored session is visible. */
@@ -1011,15 +1011,17 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    */
   async function trash(sessionId) {
     const startedAt = Date.now()
+    // Lineage listing and live checks are slow; resolve them before taking the
+    // cross-process lock and keep only the directory re-checks inside it.
+    eligibility.invalidate(sessionId)
+    const verdict = await eligibility.evaluate(sessionId)
+    if (verdict.eligible !== true) {
+      throw new TrashError(verdict.code, verdict.message, verdict.details)
+    }
     return store.withLock(async () => {
       if (store.isProtected()) {
         throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses new entries.')
       }
-      eligibility.invalidate(sessionId)
-      const verdict = await eligibility.evaluate(sessionId)
-      if (verdict.eligible !== true) {
-        throw new TrashError(verdict.code, verdict.message, verdict.details)
-      }
       const existing = store.findEntry(sessionId)
       if (existing !== undefined) {
         if (existing.state === 'missing') {
@@ -1034,6 +1036,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
       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.')
+      /** @type {import('./members.js').Member[]} */
       const members = []
       let parentSnapshot
       for (let index = 0; index < plan.length; index += 1) {
@@ -1520,6 +1523,40 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     })
   }
 
+  /**
+   * Remove unindexed object directories that contain no session payload, only
+   * plugin metadata. Directories that may still hold session logs are kept for
+   * manual inspection.
+   *
+   * @returns {Promise<{ removed: number }>} how many empty object directories were removed.
+   */
+  async function purgeEmptyOrphans() {
+    return store.withLock(async () => {
+      if (store.isProtected()) {
+        throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses changes.')
+      }
+      const { objects } = await scanObjects(store, logger)
+      const indexed = new Set(store.entries().map((entry) => entry.trashId))
+      let removed = 0
+      for (const object of objects) {
+        if (indexed.has(object.trashId)) continue
+        if (!(await isEmptyObjectDir(store, object.trashId))) continue
+        try {
+          await store.removeObjectDir(object.trashId)
+          removed += 1
+          logger.info(`removed an empty unindexed trash object (${object.trashId})`)
+        } catch (error) {
+          logger.warn(`cannot remove empty unindexed trash object ${object.trashId}: ${messageOf(error)}`)
+        }
+      }
+      if (removed > 0) {
+        const { unindexed } = await scanObjects(store, logger)
+        store.unindexed = unindexed
+      }
+      return { removed }
+    })
+  }
+
   /**
    * Restore the index from object sidecars after the primary index and its
    * backup were both rejected.
@@ -1741,5 +1778,5 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     return summary
   }
 
-  return { trash, restore, recover, purge, purgeAll, forget, sweep, rebuild, reveal }
+  return { trash, restore, recover, purge, purgeAll, forget, sweep, rebuild, reveal, purgeEmptyOrphans }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangxiaocuo/dsh-session-trash",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "DeepSeek Harness plugin: move cold sessions into a recoverable trash, restore them within the retention window, or delete their logs permanently.",
   "license": "MIT",
   "author": "wangxiaocuo",