@wangxiaocuo/dsh-session-trash 0.6.3 → 0.6.5

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 {Record<string, unknown>} [details] optional structured context.
    */
   constructor(code, message, details) {
     super(message)
@@ -87,25 +87,28 @@ const SAFE_DETAIL_KEYS = new Set([
  * only their numeric counters so no path can ride along.
  *
  * @param {unknown} value candidate metrics object.
- * @returns {object | undefined} the numeric metrics.
+ * @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 {unknown} details arbitrary structured context.
- * @returns {object | undefined} the same context restricted to whitelisted keys.
+ * @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)
@@ -123,7 +126,7 @@ export function sanitizeDetails(details) {
 
 /**
  * @param {unknown} error arbitrary thrown value.
- * @returns {{ code: string, message: string, details?: object }} the wire error shape.
+ * @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

@@ -40,7 +40,9 @@ const COPY_OPTIONS = {
  * @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
 }
 
 /**
@@ -286,8 +288,8 @@ 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) {
@@ -303,7 +305,7 @@ export function metricsMatch(entry, measured) {
 }
 
 /**
- * @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) {
@@ -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: object) => 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: object) => 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

@@ -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,25 @@ 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>,
+ *     purgeEmptyOrphans: () => Promise<{ removed: number }>,
+ *   },
+ *   cleanupService?: {
+ *     runNow: (options?: any) => Promise<any>,
+ *     sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: any }>,
+ *     diagnostics?: () => any,
  *   },
- *   cleanupService?: { runNow: (options?: object) => Promise<object>, maybeSweepOnPageOpen: () => void },
  *   ready: Promise<unknown>,
- *   config: object,
- *   logger: object,
+ *   config: any,
+ *   logger: any,
  * }} deps host services.
  * @returns {void}
  */
@@ -260,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) => {
@@ -292,7 +314,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
@@ -336,13 +336,37 @@ 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
  * 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

@@ -10,6 +10,7 @@ const PROBE_CONCURRENCY = 3
  * 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'],
@@ -22,7 +23,7 @@ const LAST_ERROR_KINDS = [
 ]
 
 /**
- * @param {unknown} message raw `lastError` text.
+ * @param {any} message raw `lastError` text.
  * @returns {string | null} a stable failure family, or null when none was recorded.
  */
 export function lastErrorCode(message) {
@@ -55,9 +56,10 @@ 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,
@@ -68,7 +70,7 @@ export function createStateService({
   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') {
@@ -92,10 +94,10 @@ export function createStateService({
   }
 
   /**
-   * @param {object} entry committed index 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<object>} the wire entry.
+   * @returns {Promise<any>} the wire entry.
    */
   async function describeEntry(entry, probeCache = new Map()) {
     const cwd = typeof entry.originalCwd === 'string' && entry.originalCwd !== '' ? entry.originalCwd : null
@@ -138,12 +140,12 @@ export function createStateService({
 
   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 probeCache = new Map()

package/lib/store.js

@@ -14,9 +14,25 @@ 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: 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 +42,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 +56,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 +157,7 @@ export class TrashStore {
   }
 
   /**
-   * @returns {readonly object[]} the committed entries.
+   * @returns {readonly any[]} the committed entries.
    */
   entries() {
     return this.index.entries
@@ -149,7 +165,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 +251,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 +295,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 +347,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 +362,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 +408,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 +424,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))
@@ -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,13 +597,21 @@ 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 {
           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,
           })
         }
       }