@wangxiaocuo/dsh-session-trash 0.6.2 → 0.6.4

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 {object} [details] optional structured context.
+   * @param {any} [details] optional structured context.
    */
   constructor(code, message, details) {
     super(message)
@@ -54,7 +54,7 @@ export class TrashError extends Error {
 }
 
 /**
- * @param {unknown} error arbitrary thrown value.
+ * @param {any} error arbitrary thrown value.
  * @returns {number} HTTP status for this error.
  */
 export function statusOf(error) {
@@ -63,15 +63,75 @@ export function statusOf(error) {
 }
 
 /**
- * @param {unknown} error arbitrary thrown value.
+ * Detail keys the Host may return to the Client. Anything else - notably raw
+ * filesystem paths or nested error text - stays in the Host log, because the
+ * wire contract promises that the trash root's absolute path is never exposed.
+ */
+const SAFE_DETAIL_KEYS = new Set([
+  'sessionId',
+  'trashId',
+  'code',
+  'phase',
+  'copied',
+  'kind',
+  'targetKind',
+  'expected',
+  'measured',
+  'activity',
+  'descendants',
+  'sessions',
+])
+
+/**
+ * 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.
+ */
+function sanitizeMetrics(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const safe = {}
+  for (const key of ['sizeBytes', 'fileCount', 'symlinkCount']) {
+    if (typeof value[key] === 'number') safe[key] = value[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.
+ */
+export function sanitizeDetails(details) {
+  if (details === null || typeof details !== 'object' || Array.isArray(details)) return undefined
+  const safe = {}
+  for (const [key, value] of Object.entries(details)) {
+    if (!SAFE_DETAIL_KEYS.has(key)) continue
+    if (key === 'expected' || key === 'measured') {
+      const metrics = sanitizeMetrics(value)
+      if (metrics !== undefined) safe[key] = metrics
+      continue
+    }
+    if (Array.isArray(value)) {
+      safe[key] = value.filter((item) => typeof item === 'string' || typeof item === 'number')
+      continue
+    }
+    if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) safe[key] = value
+  }
+  return Object.keys(safe).length === 0 ? undefined : safe
+}
+
+/**
+ * @param {any} error arbitrary thrown value.
  * @returns {{ code: string, message: string, details?: object }} the wire error shape.
  */
 export function toWireError(error) {
   if (error instanceof TrashError) {
+    const details = sanitizeDetails(error.details)
     return {
       code: error.code,
       message: error.message,
-      ...(error.details === undefined ? {} : { details: error.details }),
+      ...(details === undefined ? {} : { details }),
     }
   }
   const message = error instanceof Error ? error.message : String(error)

package/lib/fsops.js

@@ -36,7 +36,7 @@ const COPY_OPTIONS = {
 }
 
 /**
- * @param {unknown} error thrown filesystem failure.
+ * @param {any} error thrown filesystem failure.
  * @returns {string | undefined} the Node error code.
  */
 export function errorCode(error) {
@@ -194,7 +194,7 @@ export function isInside(root, target) {
 }
 
 /**
- * @param {unknown} trashId candidate object identity.
+ * @param {any} trashId candidate object identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeTrashId(trashId) {
@@ -214,7 +214,7 @@ export function isSafeTrashId(trashId) {
  * object. Session ids are `session-<uuid>` or a bare uuid today, so the
  * accepted alphabet is deliberately conservative.
  *
- * @param {unknown} sessionId candidate member identity.
+ * @param {any} sessionId candidate member identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeMemberId(sessionId) {
@@ -286,19 +286,24 @@ export async function measureDirectory(directory) {
 }
 
 /**
- * @param {{ sizeBytes?: number | null, fileCount?: number | null } | null | undefined} entry index entry.
- * @param {{ sizeBytes: number, fileCount: number }} measured current metrics.
+ * @param {{ sizeBytes?: number | null, fileCount?: number | null, symlinkCount?: number | null } | null | undefined} entry index entry.
+ * @param {{ sizeBytes: number, fileCount: number, symlinkCount?: number }} measured current metrics.
  * @returns {boolean} whether the recorded metrics are absent or match exactly.
  */
 export function metricsMatch(entry, measured) {
   if (entry === null || entry === undefined) return true
   if (typeof entry.sizeBytes === 'number' && entry.sizeBytes !== measured.sizeBytes) return false
   if (typeof entry.fileCount === 'number' && entry.fileCount !== measured.fileCount) return false
+  // A cross-device copy records the symlink count of the source; comparing it
+  // catches a symlink that the copy silently dropped.
+  if (typeof entry.symlinkCount === 'number' && typeof measured.symlinkCount === 'number' && entry.symlinkCount !== measured.symlinkCount) {
+    return false
+  }
   return true
 }
 
 /**
- * @param {{ sizeBytes?: number | null, fileCount?: number | null } | null | undefined} entry index entry.
+ * @param {{ sizeBytes?: number | null, fileCount?: number | null, symlinkCount?: number | null } | null | undefined} entry index entry.
  * @returns {boolean} whether the entry carries a complete move snapshot.
  */
 export function hasMetrics(entry) {
@@ -334,7 +339,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: object) => Promise<void>} copy copy implementation for tests.
+ * @param {(source: string, destination: string, options: any) => Promise<void>} copy copy implementation for tests.
  * @returns {Promise<void>} resolution after the destination is published.
  */
 async function copyAcrossDevices(source, destination, expected, rename, copy) {
@@ -356,10 +361,12 @@ async function copyAcrossDevices(source, destination, expected, rename, copy) {
   try {
     await fs.rm(source, { recursive: true, force: false, maxRetries: 3, retryDelay: 100 })
   } catch (error) {
+    // The paths stay in the Host log; the wire error only carries the error
+    // code and the fact that a verified copy already exists.
     throw new TrashError(
       'IO_ERROR',
       'The session was copied to the destination, but the source could not be removed.',
-      { source, destination, code: errorCode(error) ?? null, copied: true },
+      { code: errorCode(error) ?? null, copied: true },
     )
   }
 }
@@ -375,7 +382,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: object) => Promise<void>,
+ *   copy?: (source: string, destination: string, options: any) => Promise<void>,
  * }} [options] diagnostics sink and test seams.
  * @returns {Promise<void>} resolution after the directory lives at `destination`.
  */

package/lib/http.js

@@ -45,7 +45,7 @@ function headerBag(req) {
 /**
  * @param {import('node:http').ServerResponse} res response to complete.
  * @param {number} status HTTP status.
- * @param {unknown} body JSON-serializable body.
+ * @param {any} body JSON-serializable body.
  * @returns {void}
  */
 function sendJson(res, status, body) {
@@ -62,7 +62,7 @@ function sendJson(res, status, body) {
 
 /**
  * @param {import('node:http').ServerResponse} res response to complete.
- * @param {unknown} error thrown failure.
+ * @param {any} error thrown failure.
  * @returns {void}
  */
 function sendError(res, error) {
@@ -151,20 +151,24 @@ function requireSessionId(body) {
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,
  *   eligibility: { evaluate: Function, invalidate: Function },
- *   stateService: { snapshot: () => Promise<object>, describe: (entry: object) => Promise<object> },
+ *   stateService: { snapshot: () => Promise<any>, describe: (entry: any) => Promise<any> },
  *   trashService: {
- *     trash: (sessionId: string) => Promise<object>,
- *     restore: (sessionId: string, mode?: string) => Promise<object>,
- *     purge: (sessionId: string) => Promise<object>,
- *     purgeAll: () => Promise<object>,
- *     forget: (sessionId: string) => Promise<object>,
- *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<object>,
- *     rebuild: () => Promise<object>,
+ *     trash: (sessionId: string) => Promise<any>,
+ *     restore: (sessionId: string, mode?: string) => Promise<any>,
+ *     purge: (sessionId: string) => Promise<any>,
+ *     purgeAll: () => Promise<any>,
+ *     forget: (sessionId: string) => Promise<any>,
+ *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<any>,
+ *     rebuild: () => Promise<any>,
  *   },
- *   cleanupService?: { runNow: (options?: object) => Promise<object>, maybeSweepOnPageOpen: () => void },
+ *   cleanupService?: {
+    runNow: (options?: any) => Promise<any>,
+    maybeSweepOnPageOpen: () => void,
+    diagnostics?: () => any,
+  },
  *   ready: Promise<unknown>,
- *   config: object,
- *   logger: object,
+ *   config: any,
+ *   logger: any,
  * }} deps host services.
  * @returns {void}
  */
@@ -292,7 +296,11 @@ export function registerApi({ ctx, eligibility, stateService, trashService, clea
   route('restore', 'POST', async (req, res) => {
     const body = await readJsonRequest(req)
     const sessionId = requireSessionId(body)
-    const mode = body.mode
+    const rawMode = body.mode
+    if (rawMode !== undefined && typeof rawMode !== 'string') {
+      throw new TrashError('INVALID_REQUEST', 'mode must be "normal" or "orphan".')
+    }
+    const mode = typeof rawMode === 'string' ? rawMode : undefined
     if (mode !== undefined && mode !== 'normal' && mode !== 'orphan') {
       throw new TrashError('INVALID_REQUEST', 'mode must be "normal" or "orphan".')
     }

package/lib/inventory.js

@@ -17,7 +17,7 @@ const META_VERSION = 2
 const MAX_MEMBERS = 64
 
 /**
- * @param {unknown} value candidate timestamp.
+ * @param {any} value candidate timestamp.
  * @returns {boolean} whether the value is a finite number.
  */
 function isFiniteNumber(value) {
@@ -25,7 +25,7 @@ function isFiniteNumber(value) {
 }
 
 /**
- * @param {unknown} value candidate metric.
+ * @param {any} value candidate metric.
  * @returns {boolean} whether the value is a usable number or absent.
  */
 function isMetric(value) {
@@ -36,7 +36,7 @@ function isMetric(value) {
  * Validate one v2 member's absolute paths. The parent's sidecar is validated
  * field by field so a hand-edited file is rejected instead of guessed at.
  *
- * @param {unknown} member candidate member.
+ * @param {any} member candidate member.
  * @returns {boolean} whether the member names safe, coherent paths.
  */
 function isValidMemberPaths(member) {
@@ -72,7 +72,7 @@ function isValidMemberPaths(member) {
 /**
  * Validate the v2 member list of one sidecar.
  *
- * @param {object} meta candidate sidecar.
+ * @param {any} meta candidate sidecar.
  * @returns {boolean} whether the list is coherent with its parent fields.
  */
 function isValidMetaMembers(meta) {
@@ -100,7 +100,7 @@ function isValidMetaMembers(meta) {
  * entry. A malformed sidecar is reported as an unindexed object instead of
  * being guessed at.
  *
- * @param {unknown} meta parsed `meta.json`.
+ * @param {any} meta parsed `meta.json`.
  * @param {string} trashId object directory identity.
  * @returns {boolean} whether the sidecar can rebuild one entry.
  */
@@ -132,9 +132,9 @@ export function isValidMeta(meta, trashId) {
 }
 
 /**
- * @param {Record<string, unknown>} member raw member fields.
+ * @param {any} member raw member fields.
  * @param {string} fallbackTitle title used when the member carries none.
- * @returns {object} one normalized v2 member.
+ * @returns {any} one normalized v2 member.
  */
 function toMember(member, fallbackTitle) {
   return {
@@ -151,8 +151,8 @@ function toMember(member, fallbackTitle) {
 }
 
 /**
- * @param {Record<string, unknown>} meta valid sidecar.
- * @returns {object} a clean index entry with defaulted optional fields.
+ * @param {any} meta valid sidecar.
+ * @returns {any} a clean index entry with defaulted optional fields.
  */
 export function toEntry(meta) {
   const originalCwd = typeof meta.originalCwd === 'string' && meta.originalCwd !== '' ? meta.originalCwd : null
@@ -201,7 +201,7 @@ export function toEntry(meta) {
  * Which of one entry's member directories currently exist inside its object.
  *
  * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
- * @param {object} entry index entry, v1 or v2 shaped.
+ * @param {any} entry index entry, v1 or v2 shaped.
  * @returns {Promise<{ total: number, present: number, missing: string[] }>} presence summary.
  */
 export async function memberPresence(store, entry) {
@@ -229,8 +229,8 @@ export async function memberPresence(store, entry) {
  * Whether two member lists name the same directories in the same order, so a
  * presence probe taken for one can be reused for the other.
  *
- * @param {readonly object[]} left first member list.
- * @param {readonly object[]} right second member list.
+ * @param {readonly any[]} left first member list.
+ * @param {readonly any[]} right second member list.
  * @returns {boolean} whether both lists describe the same members.
  */
 function sameMembers(left, right) {
@@ -244,10 +244,10 @@ function sameMembers(left, right) {
 /**
  * Reconcile a rebuilt entry with the object directory observed on disk.
  *
- * @param {object} entry index-shaped entry.
+ * @param {any} entry index-shaped entry.
  * @param {{ total: number, present: number, missing: string[] }} presence member presence.
  * @param {number} now current timestamp.
- * @returns {object} the entry whose state matches the filesystem.
+ * @returns {any} the entry whose state matches the filesystem.
  */
 export function deriveEntry(entry, presence, now) {
   const complete = presence.total > 0 && presence.present === presence.total
@@ -282,7 +282,7 @@ export function deriveEntry(entry, presence, now) {
  *
  * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
  * @param {{ warn: Function }} logger diagnostics sink.
- * @returns {Promise<{ objects: { trashId: string, sessionExists: boolean, meta: object | undefined, metaValid: boolean, entry?: object, presence?: object }[], unindexed: number }>} the inventory.
+ * @returns {Promise<{ objects: { trashId: string, sessionExists: boolean, meta: any | undefined, metaValid: boolean, entry?: any, presence?: object }[], unindexed: number }>} the inventory.
  */
 export async function scanObjects(store, logger) {
   let entries
@@ -342,7 +342,7 @@ export async function scanObjects(store, logger) {
  * directory.
  *
  * @param {{ store: import('./store.js').TrashStore, logger: { warn: Function }, now?: number }} input trash store and diagnostics.
- * @returns {Promise<{ imported: number, markedMissing: number, unindexed: number, changed: number, presence: Map<string, object> }>} reconcile summary plus the presence probe per object.
+ * @returns {Promise<{ imported: number, markedMissing: number, unindexed: number, changed: number, presence: Map<string, any> }>} reconcile summary plus the presence probe per object.
  */
 export async function reconcileIndex({ store, logger, now = Date.now() }) {
   if (store.isProtected()) {

package/lib/members.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * @param {unknown} entry index entry (v1 or v2 shape).
+ * @param {any} entry index entry (v1 or v2 shape).
  * @returns {object|null} the parent member, or null when the entry has no directory data.
  */
 export function parentMember(entry) {
@@ -28,8 +28,8 @@ export function parentMember(entry) {
 }
 
 /**
- * @param {unknown} entry index entry (v1 or v2 shape).
- * @returns {object[]} every owned directory, parent first.
+ * @param {any} entry index entry (v1 or v2 shape).
+ * @returns {any[]} every owned directory, parent first.
  */
 export function memberList(entry) {
   if (entry !== null && typeof entry === 'object' && Array.isArray(entry.members) && entry.members.length > 0) {
@@ -40,7 +40,7 @@ export function memberList(entry) {
 }
 
 /**
- * @param {readonly object[]} members member list.
+ * @param {readonly any[]} members member list.
  * @returns {{ sizeBytes: number, fileCount: number }} summed measurable totals.
  */
 export function aggregateMetrics(members) {
@@ -57,7 +57,7 @@ export function aggregateMetrics(members) {
  * Shape-level validation shared by the durable index and object sidecars.
  * Path strictness belongs to the sidecar validator.
  *
- * @param {unknown} member candidate member.
+ * @param {any} member candidate member.
  * @returns {boolean} whether the member carries the required v2 identity.
  */
 export function isValidMemberShape(member) {
@@ -79,7 +79,7 @@ export function isValidMemberShape(member) {
 /**
  * Whether the v2 member list is internally consistent with its parent entry.
  *
- * @param {unknown} entry index entry carrying `members`.
+ * @param {any} entry index entry carrying `members`.
  * @returns {boolean} whether the list is acceptable.
  */
 export function isValidMemberList(entry) {

package/lib/state.js

@@ -5,6 +5,35 @@ import { memberList } from './members.js'
 /** Maximum concurrent filesystem probes while describing entries. */
 const PROBE_CONCURRENCY = 3
 
+/**
+ * Known failure families recorded in `lastError`, in match order. The raw text
+ * stays an English diagnostic for logs and tooltips; the code is what the
+ * Client localizes.
+ */
+/** @type {[RegExp, string][]} */
+const LAST_ERROR_KINDS = [
+  [/^The trash copy of this session is missing\./, 'TRASH_COPY_MISSING'],
+  [/^The trash copy is missing these member sessions:/, 'TRASH_COPY_MISSING_MEMBERS'],
+  [/^The trash object directory is missing\./, 'TRASH_OBJECT_MISSING'],
+  [/^The session log could not be deleted:/, 'PURGE_FAILED'],
+  [/^The restored session (tree )?(is|was) not visible to session storage\./, 'RESTORE_INVISIBLE'],
+  [/^Session storage still reports the moved session tree/, 'MOVE_UNSETTLED'],
+  [/^An original session directory unexpectedly exists/, 'SOURCE_CONFLICT'],
+  [/^The trash index could not be committed/, 'INDEX_WRITE_FAILED'],
+]
+
+/**
+ * @param {any} message raw `lastError` text.
+ * @returns {string | null} a stable failure family, or null when none was recorded.
+ */
+export function lastErrorCode(message) {
+  if (typeof message !== 'string' || message === '') return null
+  for (const [pattern, code] of LAST_ERROR_KINDS) {
+    if (pattern.test(message)) return code
+  }
+  return 'IO_ERROR'
+}
+
 /**
  * @param {string | null | undefined} directory candidate workspace directory.
  * @returns {Promise<boolean>} whether the directory exists right now.
@@ -27,13 +56,21 @@ async function directoryExists(directory) {
  *   config: { retentionDays: number, sweepIntervalHours: number, enableAutoCleanup: boolean },
  *   trashRootDisplay: string,
  *   nextSweepAt?: () => number | null,
- *   cleanup?: () => object,
+ *   cleanup?: () => any,
+ *   directoryExists?: (directory?: any) => Promise<boolean>,
  * }} deps state inputs.
- * @returns {{ snapshot: () => Promise<object>, describe: (entry: object) => Promise<object> }} the state service.
+ * @returns {{ snapshot: () => Promise<any>, describe: (entry: any) => Promise<any> }} the state service.
  */
-export function createStateService({ store, config, trashRootDisplay, nextSweepAt = () => null, cleanup }) {
+export function createStateService({
+  store,
+  config,
+  trashRootDisplay,
+  nextSweepAt = () => null,
+  cleanup,
+  directoryExists: probeDirectory = directoryExists,
+}) {
   /**
-   * @returns {object} cleanup diagnostics, or a neutral fallback.
+   * @returns {any} cleanup diagnostics, or a neutral fallback.
    */
   function cleanupDiagnostics() {
     if (typeof cleanup === 'function') {
@@ -57,12 +94,18 @@ export function createStateService({ store, config, trashRootDisplay, nextSweepA
   }
 
   /**
-   * @param {object} entry committed index entry.
-   * @returns {Promise<object>} the wire entry.
+   * @param {any} 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.
    */
-  async function describeEntry(entry) {
+  async function describeEntry(entry, probeCache = new Map()) {
     const cwd = typeof entry.originalCwd === 'string' && entry.originalCwd !== '' ? entry.originalCwd : null
-    const workspaceNowExists = cwd === null ? null : await directoryExists(cwd)
+    let workspaceNowExists = null
+    if (cwd !== null) {
+      if (!probeCache.has(cwd)) probeCache.set(cwd, probeDirectory(cwd))
+      workspaceNowExists = await probeCache.get(cwd)
+    }
     const expiresAt =
       typeof entry.trashedAt === 'number' && entry.trashedAt > 0 ? entry.trashedAt + config.retentionDays * 86_400_000 : null
     const trashed = entry.state === 'trashed'
@@ -85,6 +128,7 @@ export function createStateService({ store, config, trashRootDisplay, nextSweepA
       canForget: entry.state === 'missing',
       requiresOrphanRestore: cwd !== null && workspaceNowExists === false,
       lastError: entry.lastError ?? null,
+      lastErrorCode: lastErrorCode(entry.lastError),
       subagentCount: Math.max(0, members.length - 1),
       members: members.map((member) => ({
         sessionId: member.sessionId,
@@ -96,15 +140,16 @@ export function createStateService({ store, config, trashRootDisplay, nextSweepA
 
   return {
     /**
-     * @param {object} entry committed index entry.
-     * @returns {Promise<object>} the wire entry.
+     * @param {any} entry committed index entry.
+     * @returns {Promise<any>} the wire entry.
      */
     describe: describeEntry,
     /**
-     * @returns {Promise<object>} the complete `/state` response body.
+     * @returns {Promise<any>} the complete `/state` response body.
      */
     async snapshot() {
-      const entries = await mapLimit(store.entries(), PROBE_CONCURRENCY, (entry) => describeEntry(entry))
+      const probeCache = new Map()
+      const entries = await mapLimit(store.entries(), PROBE_CONCURRENCY, (entry) => describeEntry(entry, probeCache))
       let totalBytes = 0
       let failedEntries = 0
       for (const entry of entries) {

package/lib/store.js

@@ -16,7 +16,7 @@ export const LOCK_REFRESH_MS = 60 * 1000
 
 /**
  * @param {number} [now] timestamp for the new index.
- * @returns {{ version: number, updatedAt: number, entries: never[] }} an empty index document.
+ * @returns {{ version: number, updatedAt: number, entries: any[] }} an empty index document.
  */
 export function emptyIndex(now = Date.now()) {
   return { version: INDEX_VERSION, updatedAt: now, entries: [] }
@@ -26,8 +26,8 @@ export function emptyIndex(now = Date.now()) {
  * Coerce one durable entry to the v2 shape. A v1 entry names a single
  * directory, which becomes the parent member of a one-member tree.
  *
- * @param {object} entry entry from either durable shape.
- * @returns {object} the v2 entry.
+ * @param {any} entry entry from either durable shape.
+ * @returns {any} the v2 entry.
  */
 function normalizeEntry(entry) {
   if (entry === null || typeof entry !== 'object') return entry
@@ -40,7 +40,7 @@ function normalizeEntry(entry) {
  * Validate the persisted index shape strictly enough that a truncated or
  * hand-edited file enters protection mode instead of silently vanishing.
  *
- * @param {unknown} value parsed JSON document.
+ * @param {any} value parsed JSON document.
  * @returns {boolean} whether the document is a supported index.
  */
 export function isValidIndex(value) {
@@ -141,7 +141,7 @@ export class TrashStore {
   }
 
   /**
-   * @returns {readonly object[]} the committed entries.
+   * @returns {readonly any[]} the committed entries.
    */
   entries() {
     return this.index.entries
@@ -149,7 +149,7 @@ export class TrashStore {
 
   /**
    * @param {string} sessionId session to look up.
-   * @returns {object | undefined} the index entry for this session.
+   * @returns {any | undefined} the index entry for this session.
    */
   findEntry(sessionId) {
     return this.index.entries.find((entry) => entry.sessionId === sessionId)
@@ -235,7 +235,7 @@ export class TrashStore {
 
   /**
    * @param {string} trashId object identity.
-   * @returns {Promise<object | undefined>} the parsed sidecar metadata, when present.
+   * @returns {Promise<any | undefined>} the parsed sidecar metadata, when present.
    */
   async readMeta(trashId) {
     try {
@@ -279,7 +279,7 @@ export class TrashStore {
    * Atomically write one object sidecar. Metadata is written before the session
    * directory moves, so a damaged index can rebuild from it later.
    *
-   * @param {object} entry index-shaped entry carrying `trashId`.
+   * @param {any} entry index-shaped entry carrying `trashId`.
    * @returns {Promise<void>} resolution once the sidecar is durable.
    */
   async writeMeta(entry) {
@@ -331,7 +331,7 @@ export class TrashStore {
   /**
    * Commit a complete entry list and refresh the in-memory projection.
    *
-   * @param {readonly object[]} entries complete new entry list.
+   * @param {readonly any[]} entries complete new entry list.
    * @returns {Promise<void>} resolution once committed.
    */
   async commit(entries) {
@@ -346,7 +346,7 @@ export class TrashStore {
 
   /**
    * @param {string} file index file to read.
-   * @returns {Promise<unknown>} parsed JSON.
+   * @returns {Promise<any>} parsed JSON.
    */
   async readJson(file) {
     return JSON.parse(await fs.readFile(file, 'utf8'))
@@ -392,8 +392,8 @@ export class TrashStore {
   }
 
   /**
-   * @param {{ version: number, updatedAt: number, entries: readonly object[] }} data parsed index document.
-   * @returns {{ version: number, updatedAt: number, entries: object[] }} the v2 document.
+   * @param {{ version: number, updatedAt: number, entries: readonly any[] }} data parsed index document.
+   * @returns {{ version: number, updatedAt: number, entries: any[] }} the v2 document.
    */
   normalizeIndex(data) {
     if (data.version !== INDEX_VERSION) this.needsUpgrade = true
@@ -408,8 +408,8 @@ export class TrashStore {
    * Atomically commit the index: write a temporary file, preserve the previous
    * commit as `.bak`, then rename over the live index.
    *
-   * @param {readonly object[]} entries the complete entry list to persist.
-   * @returns {Promise<{ version: number, updatedAt: number, entries: readonly object[] }>} the committed document.
+   * @param {readonly any[]} entries the complete entry list to persist.
+   * @returns {Promise<{ version: number, updatedAt: number, entries: readonly any[] }>} the committed document.
    */
   async writeIndex(entries) {
     const normalized = entries.map((entry) => normalizeEntry(entry))
@@ -582,7 +582,10 @@ export class TrashStore {
           await removePathWithRetry(this.lockPath, { recursive: false, force: true, attempts: 5, delayMs: 20 })
         } catch (removeError) {
           throw new TrashError('LOCKED', 'A stale trash lock could not be removed. Try again in a moment.', {
-            code: removeError instanceof Error && typeof removeError.code === 'string' ? removeError.code : null,
+            code:
+              removeError instanceof Error && typeof /** @type {any} */ (removeError).code === 'string'
+                ? /** @type {any} */ (removeError).code
+                : null,
           })
         }
       }