@wangxiaocuo/dsh-session-trash 0.6.3 → 0.6.5

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. */
@@ -45,7 +45,7 @@ function errorText(message) {
 }
 
 /**
- * @param {unknown} error arbitrary failure.
+ * @param {any} error arbitrary failure.
  * @returns {string} a user-facing error message.
  */
 function messageOf(error) {
@@ -53,9 +53,9 @@ function messageOf(error) {
 }
 
 /**
- * @param {readonly object[]} entries current index entries.
- * @param {object} next replacement entry.
- * @returns {object[]} a new list with the entry replaced or appended.
+ * @param {readonly any[]} entries current index entries.
+ * @param {any} next replacement entry.
+ * @returns {any[]} a new list with the entry replaced or appended.
  */
 function upsertEntry(entries, next) {
   const copy = [...entries]
@@ -66,9 +66,9 @@ function upsertEntry(entries, next) {
 }
 
 /**
- * @param {readonly object[]} entries current index entries.
+ * @param {readonly any[]} entries current index entries.
  * @param {string} sessionId session to drop.
- * @returns {object[]} a new list without that session.
+ * @returns {any[]} a new list without that session.
  */
 function dropEntry(entries, sessionId) {
   return entries.filter((entry) => entry.sessionId !== sessionId)
@@ -81,23 +81,23 @@ function dropEntry(entries, sessionId) {
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,
  *   store: import('./store.js').TrashStore,
- *   eligibility: { evaluate: (sessionId: string) => Promise<object>, invalidate: (sessionId?: string) => void },
+ *   eligibility: { evaluate: (sessionId: string) => Promise<any>, invalidate: (sessionId?: string) => void },
  *   config: { retentionDays: number, sweepIntervalHours: number, enableAutoCleanup: boolean },
  *   logger: { info: Function, warn: Function, error: Function, debug: Function },
  *   paths: { root: string, display: string },
  * }} deps host services and resolved paths.
- * @returns {object} the operation surface.
+ * @returns {any} the operation surface.
  */
 export function createTrashService({ ctx, store, eligibility, config, logger, paths }) {
   /**
-   * @returns {object | undefined} the optional title service.
+   * @returns {any | undefined} the optional title service.
    */
   function sessionQuery() {
     return ctx.get('sessionQuery')
   }
 
   /**
-   * @returns {object | undefined} the optional workspace registry.
+   * @returns {any | undefined} the optional workspace registry.
    */
   function workspaceRegistry() {
     return ctx.get('workspaceRegistry')
@@ -105,7 +105,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
   /**
    * @param {string} sessionId session whose storage snapshot to read.
-   * @returns {Promise<object | undefined>} the persistence snapshot.
+   * @returns {Promise<any | undefined>} the persistence snapshot.
    */
   async function stat(sessionId) {
     return ctx.sessionPersistence.stat(sessionId)
@@ -113,7 +113,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
   /**
    * @param {string} sessionId session to check.
-   * @returns {Promise<boolean>} whether the session is live in this process.
+   * @returns {boolean} whether the session is live in this process.
    */
   function isLive(sessionId) {
     const liveSession = typeof ctx.sessions?.get === 'function' ? ctx.sessions.get(sessionId) : undefined
@@ -122,7 +122,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} snapshot persistence snapshot.
+   * @param {any} snapshot persistence snapshot.
    * @returns {string} the session header's cwd, or an empty string when absent.
    */
   function cwdOf(snapshot) {
@@ -134,7 +134,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * query service.
    *
    * @param {string} sessionId session whose title to read.
-   * @param {object} header persistence header.
+   * @param {any} header persistence header.
    * @returns {Promise<string>} the title, then cwd basename, then session id.
    */
   async function resolveTitle(sessionId, header) {
@@ -158,7 +158,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * Find the Workspace that currently accounts for a session.
    *
    * @param {string} sessionId session to locate.
-   * @returns {{ workspace: object, nextSessionId: string | null } | undefined} owning workspace and following sibling.
+   * @returns {{ workspace: any, nextSessionId: string | null } | undefined} owning workspace and following sibling.
    */
   function findOwningWorkspace(sessionId) {
     const registry = workspaceRegistry()
@@ -177,7 +177,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {unknown} target path to probe.
+   * @param {any} target path to probe.
    * @returns {Promise<string>} the entry kind, treating an absent path as missing.
    */
   async function kindOf(target) {
@@ -185,15 +185,15 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
-   * @returns {object[]} every owned directory, parent first.
+   * @param {any} entry index entry.
+   * @returns {any[]} every owned directory, parent first.
    */
   function membersOf(entry) {
     return memberList(entry)
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {number} index member position.
    * @returns {string} this member's directory inside the trash object.
    */
@@ -202,7 +202,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry trash index entry.
+   * @param {any} entry trash index entry.
    * @returns {Promise<void>} resolution once every member path stays inside `objects/`.
    */
   async function assertSafeObject(entry) {
@@ -226,8 +226,8 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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.
+   * @param {any} entry index entry.
+   * @returns {Promise<{ index: number, member: any, source: boolean, trash: boolean }[]>} member positions.
    */
   async function memberRows(entry) {
     const members = membersOf(entry)
@@ -251,8 +251,8 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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.
+   * @param {any} entry index entry.
+   * @returns {Promise<{ index: number, member: any, source: boolean }[]>} member source positions.
    */
   async function sourceRows(entry) {
     const members = membersOf(entry)
@@ -266,7 +266,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {number} index member position.
    * @returns {Promise<void>} resolution once the member directory moved into its object.
    */
@@ -276,7 +276,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {number} index member position.
    * @returns {Promise<void>} resolution once the member directory moved back to its original location.
    */
@@ -286,7 +286,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {readonly { index: number }[]} rows members to move into the object.
    * @returns {Promise<{ index: number, error: unknown }[]>} per-member failures.
    */
@@ -303,7 +303,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} 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.
    */
@@ -323,7 +323,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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.
+   * @param {any} entry index entry.
    * @returns {Promise<void>} resolution once every member directory moved.
    */
   async function moveMembersToTrash(entry) {
@@ -337,7 +337,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {number} index member position.
    * @returns {Promise<void>} resolution once the unusable trash copy is gone.
    */
@@ -351,7 +351,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} member planned member whose restored copy failed verification.
+   * @param {any} member planned member whose restored copy failed verification.
    * @returns {Promise<void>} resolution once the unusable restored copy is gone.
    */
   async function removeRestoredMember(member) {
@@ -363,7 +363,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @returns {Promise<{ ok: boolean, index?: number, message?: string }>} whether every member landed with its recorded metrics.
    */
   async function verifyTrashedMembers(entry) {
@@ -386,7 +386,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @returns {Promise<{ ok: boolean, index?: number, message?: string }>} whether every member returned with its recorded metrics.
    */
   async function verifyRestoredMembers(entry) {
@@ -406,7 +406,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @returns {Promise<{ hidden: boolean, sessionId?: string }>} whether session storage stopped reporting every member.
    */
   async function waitForMembersHidden(entry) {
@@ -421,7 +421,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @returns {Promise<{ visible: boolean, sessionId?: string }>} whether session storage reports every member again.
    */
   async function waitForMembersVisible(entry) {
@@ -440,7 +440,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
 
   /**
    * @param {string} sessionId session to probe.
-   * @param {(snapshot: object | undefined) => boolean} predicate expected visibility state.
+   * @param {(snapshot: any | undefined) => boolean} predicate expected visibility state.
    * @returns {Promise<boolean>} whether the persistence backend agreed within the retry budget.
    */
   async function waitForVisibility(sessionId, predicate) {
@@ -479,8 +479,8 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    *
    * @param {string} sessionId restored session identity.
    * @param {string} title restored display title.
-   * @param {object | undefined} snapshot persistence snapshot.
-   * @returns {object} a `SessionSummary`.
+   * @param {any | undefined} snapshot persistence snapshot.
+   * @returns {any} a `SessionSummary`.
    */
   function buildSummary(sessionId, title, snapshot) {
     const header = snapshot?.header ?? {}
@@ -501,9 +501,9 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   /**
    * Record a failure summary on one entry and commit it, best effort.
    *
-   * @param {object} entry entry to annotate.
+   * @param {any} entry entry to annotate.
    * @param {string} message failure summary.
-   * @returns {Promise<object>} the annotated entry.
+   * @returns {Promise<any>} the annotated entry.
    */
   async function markFailure(entry, message) {
     const next = { ...entry, lastError: errorText(message) }
@@ -521,7 +521,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   /**
    * Restore the workspace accounting after a normal restore.
    *
-   * @param {object} entry restored index entry.
+   * @param {any} entry restored index entry.
    * @returns {Promise<{ reattached: boolean, warning?: string }>} reattachment outcome.
    */
   async function reattachWorkspace(entry) {
@@ -584,7 +584,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * Remove a session from every workspace that still accounts for it. Used by
    * orphan restore so the restored log appears under “Ungrouped”.
    *
-   * @param {object} entry restored index entry.
+   * @param {any} entry restored index entry.
    * @returns {Promise<{ detached: boolean, warning?: string }>} detach outcome.
    */
   async function detachWorkspace(entry) {
@@ -625,7 +625,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    *
    * @param {string} from current path.
    * @param {string} to previous path.
-   * @param {object | null | undefined} expected metrics for a cross-device copy.
+   * @param {any | null | undefined} expected metrics for a cross-device copy.
    * @returns {Promise<boolean>} whether the directory now lives at `to`.
    */
   async function moveBack(from, to, expected) {
@@ -669,7 +669,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * object or its original location. Never writes the index: the caller owns
    * the commit so startup recovery can accumulate one write.
    *
-   * @param {object} entry `trashing` index entry.
+   * @param {any} entry `trashing` index entry.
    * @returns {Promise<{ kind: 'ready' } | { kind: 'rolledBack' } | { kind: 'missing', entry: object }>} the settled position.
    */
   async function resolveTrashing(entry) {
@@ -725,7 +725,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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` index entry.
+   * @param {any} entry `restoring` index entry.
    * @returns {Promise<{ kind: 'ready' } | { kind: 'trashed', entry: object } | { kind: 'missing', entry: object }>} the settled position.
    */
   async function resolveRestoring(entry) {
@@ -752,6 +752,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
         row.source = false
       }
     }
+    /** @returns {{ kind: 'trashed', entry: any }} */
     const rolledBack = () => ({
       kind: 'trashed',
       entry: {
@@ -787,9 +788,9 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry settled `trashing` entry.
+   * @param {any} entry settled `trashing` entry.
    * @param {{ emitRemoval?: boolean }} [options] whether to announce the removal to clients.
-   * @returns {Promise<object>} the committed `trashed` entry.
+   * @returns {Promise<any>} the committed `trashed` entry.
    */
   async function commitTrashed(entry, options = {}) {
     const next = { ...entry, state: 'trashed', trashedAt: Date.now(), lastError: null }
@@ -811,9 +812,9 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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 {any} entry settled `restoring` entry.
    * @param {{ mode?: 'normal' | 'orphan', emitAdded?: boolean, reattach?: boolean }} [options] finishing policy.
-   * @returns {Promise<object>} the workspace attachment outcome.
+   * @returns {Promise<any>} the workspace attachment outcome.
    */
   async function completeRestore(entry, options = {}) {
     const mode = options.mode ?? 'normal'
@@ -847,7 +848,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
   }
 
   /**
-   * @param {object} entry index entry.
+   * @param {any} entry index entry.
    * @param {number} now current timestamp.
    * @returns {boolean} whether the retention window has elapsed.
    */
@@ -864,8 +865,8 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * 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.
+   * @param {readonly any[]} targets `trashed` entries to purge.
+   * @returns {Promise<{ purged: number, failures: { entry: any, error: unknown, phase: string }[] }>} per-entry outcome.
    */
   async function purgeManyInsideLock(targets) {
     const failures = []
@@ -954,7 +955,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * Permanently remove one object directory and its index entry. The caller
    * owns the trash lock.
    *
-   * @param {object} entry `trashed` index entry to purge.
+   * @param {any} entry `trashed` index entry to purge.
    * @returns {Promise<void>} resolution once the object and entry are gone.
    */
   async function purgeInsideLock(entry) {
@@ -967,7 +968,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * their plugin-owned remnants. No session file is deleted. The caller owns
    * the trash lock.
    *
-   * @param {readonly object[]} entries `missing` index entries to forget.
+   * @param {readonly any[]} entries `missing` index entries to forget.
    * @returns {Promise<number>} how many entries were removed from the index.
    */
   async function forgetManyInsideLock(entries) {
@@ -993,7 +994,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * Drop one `missing` entry from the index and remove its plugin-owned
    * remnants. No session file is deleted. The caller owns the trash lock.
    *
-   * @param {object} entry `missing` index entry to forget.
+   * @param {any} entry `missing` index entry to forget.
    * @returns {Promise<{ sessionId: string, title: string }>} the removed identity.
    */
   async function forgetInsideLock(entry) {
@@ -1006,19 +1007,21 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * `origin: 'subagent'` descendants moves together with them.
    *
    * @param {string} sessionId session to trash.
-   * @returns {Promise<object>} the committed `trashed` entry.
+   * @returns {Promise<any>} the committed `trashed` entry.
    */
   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') {
@@ -1206,7 +1209,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    *
    * @param {string} sessionId session to restore.
    * @param {'normal' | 'orphan'} [mode] restore mode; orphan restores the log and detaches the Workspace.
-   * @returns {Promise<object>} the restore result.
+   * @returns {Promise<any>} the restore result.
    */
   async function restore(sessionId, mode = 'normal') {
     if (mode !== 'normal' && mode !== 'orphan') {
@@ -1471,7 +1474,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * object directory vanished. The caller must hold the trash lock.
    *
    * @param {number} now current timestamp.
-   * @returns {Promise<object>} reconcile summary.
+   * @returns {Promise<any>} reconcile summary.
    */
   async function reconcileInsideLock(now) {
     try {
@@ -1493,7 +1496,7 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    * entries. Used by startup recovery, the scheduled sweep, and manual cleanup.
    *
    * @param {{ allowPurge?: boolean, now?: number, reason?: string }} [options] sweep policy.
-   * @returns {Promise<object>} the sweep summary.
+   * @returns {Promise<any>} the sweep summary.
    */
   async function sweep({ allowPurge = true, now = Date.now(), reason = 'scheduled' } = {}) {
     return store.withLock(async () => {
@@ -1519,6 +1522,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.
@@ -1740,5 +1777,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.3",
+  "version": "0.6.5",
   "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",
@@ -47,14 +47,21 @@
     "test": "node test/run-unit.mjs",
     "test:coverage": "node test/run-unit.mjs --experimental-test-coverage",
     "test:e2e": "node test/e2e-web.mjs",
-    "test:smoke": "node test/smoke-host.mjs"
+    "test:smoke": "node test/smoke-host.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:dom": "node --test test/client-dom.test.js"
   },
   "dependencies": {
     "@deepseek-ai/dsh-home-paths": "0.2.2-rc.1",
     "@deepseek-ai/schemastery": "3.19.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.1.0"
+    "@deepseek-ai/cordis": "4.1.0",
+    "@types/node": "20.19.43",
+    "jsdom": "27.4.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "5.9.3"
   },
   "dsh": {
     "bundle": {