@wangxiaocuo/dsh-session-trash 0.0.0-stage → 0.5.1

package/lib/http.js

@@ -0,0 +1,346 @@
+import { TrashError, statusOf, toWireError } from './errors.js'
+
+/** Prefix shared by every route this plugin owns. */
+export const API_PREFIX = '/plugins/dsh-session-trash/api'
+
+/** Request header that proves a same-origin scripted call. */
+export const CSRF_HEADER = 'x-dsh-session-trash'
+
+/** Largest accepted JSON request body. */
+export const MAX_BODY_BYTES = 64 * 1024
+
+/** Budget for one native reveal request. */
+const REVEAL_TIMEOUT_MS = 10_000
+
+/**
+ * @returns {AbortSignal} a signal that aborts the reveal after its budget.
+ */
+function revealSignal() {
+  if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') {
+    return AbortSignal.timeout(REVEAL_TIMEOUT_MS)
+  }
+  const controller = new AbortController()
+  const handle = setTimeout(() => controller.abort(), REVEAL_TIMEOUT_MS)
+  handle.unref?.()
+  return controller.signal
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req incoming request.
+ * @returns {Headers} a Fetch-shaped header bag for the connection service.
+ */
+function headerBag(req) {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item)
+    } else {
+      headers.set(name, value)
+    }
+  }
+  return headers
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res response to complete.
+ * @param {number} status HTTP status.
+ * @param {unknown} body JSON-serializable body.
+ * @returns {void}
+ */
+function sendJson(res, status, body) {
+  if (res.headersSent || res.writableEnded) return
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(payload),
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+  })
+  res.end(payload)
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res response to complete.
+ * @param {unknown} error thrown failure.
+ * @returns {void}
+ */
+function sendError(res, error) {
+  sendJson(res, statusOf(error), { ok: false, error: toWireError(error) })
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req request whose body to read.
+ * @param {number} limit maximum accepted bytes.
+ * @returns {Promise<Buffer>} the complete body.
+ */
+function readBody(req, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    let failed = false
+    req.on('data', (chunk) => {
+      if (failed) return
+      size += chunk.length
+      if (size > limit) {
+        failed = true
+        chunks.length = 0
+        reject(new TrashError('INVALID_REQUEST', 'Request body is too large.'))
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (!failed) resolve(Buffer.concat(chunks))
+    })
+    req.on('error', (error) => {
+      if (!failed) reject(error)
+    })
+    req.on('aborted', () => {
+      if (!failed) reject(new TrashError('INVALID_REQUEST', 'Request was aborted.'))
+    })
+  })
+}
+
+/**
+ * @param {Buffer} buffer raw request body.
+ * @returns {Record<string, unknown>} the decoded JSON object.
+ */
+function parseJsonObject(buffer) {
+  if (buffer.length === 0) return {}
+  let parsed
+  try {
+    parsed = JSON.parse(buffer.toString('utf8'))
+  } catch {
+    throw new TrashError('INVALID_REQUEST', 'Request body is not valid JSON.')
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new TrashError('INVALID_REQUEST', 'Request body must be a JSON object.')
+  }
+  return parsed
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req request whose JSON body to read.
+ * @returns {Promise<Record<string, unknown>>} the validated JSON object.
+ */
+async function readJsonRequest(req) {
+  if (!String(req.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+    throw new TrashError('INVALID_REQUEST', 'Content-Type must be application/json.')
+  }
+  return parseJsonObject(await readBody(req, MAX_BODY_BYTES))
+}
+
+/**
+ * @param {Record<string, unknown>} body decoded request body.
+ * @returns {string} a validated session identity.
+ */
+function requireSessionId(body) {
+  const sessionId = body.sessionId
+  if (typeof sessionId !== 'string' || sessionId === '' || sessionId.length > 256) {
+    throw new TrashError('INVALID_REQUEST', 'sessionId must be a non-empty string.')
+  }
+  return sessionId
+}
+
+/**
+ * Register the plugin HTTP surface: state, menu preflight, trash/restore,
+ * permanent deletion (single and bulk), index maintenance, reveal, and
+ * cleanup.
+ *
+ * @param {{
+ *   ctx: import('@deepseek-ai/cordis').Context,
+ *   eligibility: { evaluate: Function, invalidate: Function },
+ *   stateService: { snapshot: () => Promise<object>, describe: (entry: object) => Promise<object> },
+ *   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>,
+ *   },
+ *   cleanupService?: { runNow: (options?: object) => Promise<object>, maybeSweepOnPageOpen: () => void },
+ *   ready: Promise<unknown>,
+ *   config: object,
+ *   logger: object,
+ * }} deps host services.
+ * @returns {void}
+ */
+export function registerApi({ ctx, eligibility, stateService, trashService, cleanupService, ready, config, logger }) {
+  /**
+   * Apply the shared trust, ownership, and CSRF checks.
+   *
+   * @param {import('node:http').IncomingMessage} req incoming request.
+   * @param {import('node:http').ServerResponse} res response to complete on refusal.
+   * @param {{ csrf: boolean }} options whether the scripted-call header is required.
+   * @returns {boolean} whether the request may proceed.
+   */
+  function authorize(req, res, { csrf }) {
+    const headers = headerBag(req)
+    let rejection
+    try {
+      rejection = ctx.connection.requestRejection({ headers })
+    } catch (error) {
+      logger.warn(`connection rejection check failed: ${error instanceof Error ? error.message : String(error)}`)
+      sendError(res, new TrashError('FORBIDDEN', 'The request could not be authenticated.'))
+      return false
+    }
+    if (rejection !== undefined) {
+      sendJson(res, rejection, { ok: false, error: { code: 'FORBIDDEN', message: 'The request is not trusted.' } })
+      return false
+    }
+    let admission
+    try {
+      admission = ctx.connection.admit({ headers })
+    } catch (error) {
+      logger.warn(`connection admission failed: ${error instanceof Error ? error.message : String(error)}`)
+      sendError(res, new TrashError('FORBIDDEN', 'The request could not be admitted.'))
+      return false
+    }
+    if (admission.rejection !== undefined) {
+      sendJson(res, admission.rejection, {
+        ok: false,
+        error: { code: 'FORBIDDEN', message: 'The request is not authenticated.' },
+      })
+      return false
+    }
+    if (admission.peer?.principal?.kind !== 'owner') {
+      sendJson(res, 403, { ok: false, error: { code: 'FORBIDDEN', message: 'Only the owner may use the trash.' } })
+      return false
+    }
+    if (csrf && headers.get(CSRF_HEADER) !== '1') {
+      sendJson(res, 403, { ok: false, error: { code: 'FORBIDDEN', message: `Missing the ${CSRF_HEADER} header.` } })
+      return false
+    }
+    return true
+  }
+
+  /**
+   * @param {string} pathname route path below the API prefix.
+   * @param {string} method allowed HTTP method.
+   * @param {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>} handler route body.
+   * @returns {void}
+   */
+  function route(pathname, method, handler) {
+    const path = `${API_PREFIX}/${pathname}`
+    ctx.effect(
+      () =>
+        ctx.webServer.register({
+          kind: 'exact',
+          path,
+          async handler(req, res) {
+            const startedAt = Date.now()
+            try {
+              if (req.method !== method) {
+                res.setHeader('Allow', method)
+                sendJson(res, 405, {
+                  ok: false,
+                  error: { code: 'METHOD_NOT_ALLOWED', message: `Use ${method} for this endpoint.` },
+                })
+                return
+              }
+              if (!authorize(req, res, { csrf: method !== 'GET' })) return
+              await ready
+              await handler(req, res)
+            } catch (error) {
+              if (error instanceof TrashError) {
+                logger.debug(`${method} ${path} -> ${error.code} (${Date.now() - startedAt}ms)`)
+              } else {
+                logger.error(`${method} ${path} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`)
+              }
+              sendError(res, error)
+            }
+          },
+        }),
+      `session-trash: route ${method} ${path}`,
+    )
+  }
+
+  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('preflight', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    const verdict = await eligibility.evaluate(sessionId)
+    if (config.debug) {
+      logger.debug(`preflight ${sessionId} -> ${verdict.eligible ? 'eligible' : verdict.code}`)
+    }
+    sendJson(res, 200, verdict)
+  })
+
+  route('trash', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    const entry = await trashService.trash(sessionId)
+    sendJson(res, 200, { ok: true, entry: await stateService.describe(entry) })
+  })
+
+  route('restore', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    const mode = body.mode
+    if (mode !== undefined && mode !== 'normal' && mode !== 'orphan') {
+      throw new TrashError('INVALID_REQUEST', 'mode must be "normal" or "orphan".')
+    }
+    const session = await trashService.restore(sessionId, mode ?? 'normal')
+    sendJson(res, 200, { ok: true, session })
+  })
+
+  route('purge', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    const result = await trashService.purge(sessionId)
+    sendJson(res, 200, { ok: true, sessionId: result.sessionId })
+  })
+
+  route('purge-all', 'POST', async (_req, res) => {
+    const result = await trashService.purgeAll()
+    sendJson(res, 200, {
+      ok: true,
+      purged: result.purged ?? 0,
+      forgotten: result.forgotten ?? 0,
+      failed: result.failed ?? 0,
+    })
+  })
+
+  route('forget', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    const result = await trashService.forget(sessionId)
+    sendJson(res, 200, { ok: true, sessionId: result.sessionId })
+  })
+
+  route('reveal', 'POST', async (req, res) => {
+    const body = await readJsonRequest(req)
+    const sessionId = requireSessionId(body)
+    await trashService.reveal(sessionId, revealSignal())
+    sendJson(res, 200, { ok: true, opened: true })
+  })
+
+  route('cleanup', 'POST', async (_req, res) => {
+    const result = await cleanupService.runNow({ manual: true, reason: 'manual' })
+    const diagnostics =
+      typeof cleanupService.diagnostics === 'function' ? cleanupService.diagnostics() : undefined
+    sendJson(res, 200, {
+      ok: true,
+      purged: result.purged ?? 0,
+      failed: result.failed ?? 0,
+      settled: result.changed ?? 0,
+      ...(diagnostics === undefined ? {} : { cleanup: diagnostics }),
+    })
+  })
+
+  route('rebuild', 'POST', async (_req, res) => {
+    const result = await trashService.rebuild()
+    sendJson(res, 200, { ok: true, entries: result.entries, unindexed: result.unindexed })
+  })
+}

package/lib/inventory.js

@@ -0,0 +1,271 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { entryKind, isSafeDirectoryPath, isSafeTrashId, samePath } from './fsops.js'
+
+/** Every state the durable index understands. */
+export const ENTRY_STATES = new Set(['trashing', 'trashed', 'restoring', 'purging', 'missing'])
+
+/** Sidecar schema version understood by this release. */
+const META_VERSION = 1
+
+/**
+ * @param {unknown} value candidate timestamp.
+ * @returns {boolean} whether the value is a finite number.
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * Validate one object sidecar strictly enough to be rebuilt into an index
+ * entry. A malformed sidecar is reported as an unindexed object instead of
+ * being guessed at.
+ *
+ * @param {unknown} meta parsed `meta.json`.
+ * @param {string} trashId object directory identity.
+ * @returns {boolean} whether the sidecar can rebuild one entry.
+ */
+export function isValidMeta(meta, trashId) {
+  if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return false
+  if (meta.version !== undefined && meta.version !== META_VERSION) return false
+  if (typeof meta.sessionId !== 'string' || meta.sessionId === '' || meta.sessionId.length > 256) return false
+  if (meta.trashId !== trashId) return false
+  if (!ENTRY_STATES.has(meta.state)) return false
+  if (!isFiniteNumber(meta.trashedAt) || !isFiniteNumber(meta.startedAt)) return false
+  if (typeof meta.title !== 'string' || meta.title.trim() === '') return false
+  if (!isSafeDirectoryPath(meta.originalSessionDir)) return false
+  if (typeof meta.persistenceProjectDirHint !== 'string' || !path.isAbsolute(meta.persistenceProjectDirHint)) return false
+  if (!samePath(path.dirname(path.resolve(meta.originalSessionDir)), path.resolve(meta.persistenceProjectDirHint))) return false
+  if (typeof meta.originalLogPath !== 'string' || !path.isAbsolute(meta.originalLogPath)) return false
+  if (!samePath(path.dirname(path.resolve(meta.originalLogPath)), path.resolve(meta.originalSessionDir))) return false
+  if (meta.originalCwd !== null && meta.originalCwd !== undefined) {
+    if (typeof meta.originalCwd !== 'string' || !path.isAbsolute(meta.originalCwd)) return false
+  }
+  if (
+    meta.workspaceExistsAtDeletion !== null &&
+    meta.workspaceExistsAtDeletion !== undefined &&
+    typeof meta.workspaceExistsAtDeletion !== 'boolean'
+  ) {
+    return false
+  }
+  return true
+}
+
+/**
+ * @param {Record<string, unknown>} meta valid sidecar.
+ * @returns {object} a clean index entry with defaulted optional fields.
+ */
+function toEntry(meta) {
+  const originalCwd = typeof meta.originalCwd === 'string' && meta.originalCwd !== '' ? meta.originalCwd : null
+  return {
+    sessionId: meta.sessionId,
+    trashId: meta.trashId,
+    state: meta.state,
+    title: meta.title,
+    trashedAt: meta.trashedAt,
+    startedAt: meta.startedAt,
+    originalCwd,
+    workspaceExistsAtDeletion: typeof meta.workspaceExistsAtDeletion === 'boolean' ? meta.workspaceExistsAtDeletion : null,
+    originalWorkspaceId: typeof meta.originalWorkspaceId === 'string' ? meta.originalWorkspaceId : null,
+    originalWorkspaceTitle: typeof meta.originalWorkspaceTitle === 'string' ? meta.originalWorkspaceTitle : null,
+    originalNextSessionId: typeof meta.originalNextSessionId === 'string' ? meta.originalNextSessionId : null,
+    originalSessionDir: path.resolve(meta.originalSessionDir),
+    originalLogPath: path.resolve(meta.originalLogPath),
+    persistenceProjectDirHint: path.resolve(meta.persistenceProjectDirHint),
+    formatStatus: meta.formatStatus === 'migration-required' ? 'migration-required' : 'current',
+    sizeBytes: isFiniteNumber(meta.sizeBytes) ? meta.sizeBytes : null,
+    fileCount: isFiniteNumber(meta.fileCount) ? meta.fileCount : null,
+    lastError: typeof meta.lastError === 'string' && meta.lastError !== '' ? meta.lastError : null,
+  }
+}
+
+/**
+ * Reconcile a rebuilt entry with the object directory observed on disk.
+ *
+ * @param {object} entry index-shaped entry.
+ * @param {boolean} sessionExists whether `objects/<trashId>/session` is a directory.
+ * @param {number} now current timestamp.
+ * @returns {object} the entry whose state matches the filesystem.
+ */
+export function deriveEntry(entry, sessionExists, now) {
+  if (!sessionExists) {
+    if (entry.state === 'purging' || entry.state === 'missing') return { ...entry }
+    return {
+      ...entry,
+      state: 'missing',
+      lastError: 'The trash copy of this session is missing.',
+    }
+  }
+  if (entry.state === 'missing') {
+    return {
+      ...entry,
+      state: 'trashed',
+      trashedAt: isFiniteNumber(entry.trashedAt) && entry.trashedAt > 0 ? entry.trashedAt : entry.startedAt || now,
+      lastError: null,
+    }
+  }
+  if (entry.state === 'trashed' && (!isFiniteNumber(entry.trashedAt) || entry.trashedAt <= 0)) {
+    return { ...entry, trashedAt: entry.startedAt || now }
+  }
+  return { ...entry }
+}
+
+/**
+ * Read every object directory and its sidecar without following symlinks.
+ *
+ * @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 }[], unindexed: number }>} the inventory.
+ */
+export async function scanObjects(store, logger) {
+  let entries
+  try {
+    entries = await fs.readdir(store.objectsDir, { withFileTypes: true })
+  } catch (error) {
+    if (error !== null && error !== undefined && error.code === 'ENOENT') return { objects: [], unindexed: 0 }
+    throw error
+  }
+  const objects = []
+  let unindexed = 0
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !isSafeTrashId(entry.name)) {
+      unindexed += 1
+      continue
+    }
+    const trashId = entry.name
+    let meta
+    try {
+      meta = await store.readMeta(trashId)
+    } catch (error) {
+      logger.warn(`cannot read the trash metadata for ${trashId}: ${error instanceof Error ? error.message : String(error)}`)
+      // Keep the directory in the inventory so reconcile never mistakes an
+      // unreadable sidecar for a vanished object directory.
+      objects.push({ trashId, sessionExists: false, meta: undefined, metaValid: false })
+      unindexed += 1
+      continue
+    }
+    const metaValid = meta !== undefined && isValidMeta(meta, trashId)
+    if (!metaValid) {
+      objects.push({ trashId, sessionExists: false, meta, metaValid: false })
+      unindexed += 1
+      continue
+    }
+    let sessionExists = false
+    try {
+      sessionExists = (await entryKind(store.sessionPath(trashId))) === 'directory'
+    } catch (error) {
+      logger.warn(`cannot inspect the trash copy ${trashId}: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    objects.push({ trashId, sessionExists, meta, metaValid })
+  }
+  return { objects, unindexed }
+}
+
+/**
+ * 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 }>} reconcile summary.
+ */
+export async function reconcileIndex({ store, logger, now = Date.now() }) {
+  if (store.isProtected()) return { imported: 0, markedMissing: 0, unindexed: store.unindexed, changed: 0 }
+  const { objects, unindexed: invalidObjects } = await scanObjects(store, logger)
+  const byTrashId = new Map(objects.map((object) => [object.trashId, object]))
+  const nextEntries = [...store.entries()]
+  const indexedTrashIds = new Set(nextEntries.map((entry) => entry.trashId))
+  const sessionIds = new Set(nextEntries.map((entry) => entry.sessionId))
+  const metaUpdates = []
+  let unindexed = invalidObjects
+  let markedMissing = 0
+  let imported = 0
+  let changed = false
+
+  for (let index = 0; index < nextEntries.length; index += 1) {
+    const entry = nextEntries[index]
+    const object = byTrashId.get(entry.trashId)
+    if (object === undefined) {
+      if (entry.state !== 'trashed') continue
+      nextEntries[index] = {
+        ...entry,
+        state: 'missing',
+        lastError: entry.lastError ?? 'The trash object directory is missing.',
+      }
+      metaUpdates.push(nextEntries[index])
+      markedMissing += 1
+      changed = true
+      continue
+    }
+    if (entry.state === 'missing' && object.sessionExists) {
+      nextEntries[index] = {
+        ...entry,
+        state: 'trashed',
+        trashedAt: entry.trashedAt > 0 ? entry.trashedAt : entry.startedAt || now,
+        lastError: null,
+      }
+      metaUpdates.push(nextEntries[index])
+      changed = true
+    }
+  }
+
+  for (const object of objects) {
+    if (indexedTrashIds.has(object.trashId)) continue
+    if (!object.metaValid || object.meta === undefined) continue
+    const entry = toEntry(object.meta)
+    if (sessionIds.has(entry.sessionId)) {
+      // Two object directories claim the same session: keep the indexed one.
+      unindexed += 1
+      logger.warn(`the trash object ${object.trashId} duplicates the indexed session ${entry.sessionId}`)
+      continue
+    }
+    const derived = deriveEntry(entry, object.sessionExists, now)
+    nextEntries.push(derived)
+    indexedTrashIds.add(derived.trashId)
+    sessionIds.add(derived.sessionId)
+    metaUpdates.push(derived)
+    imported += 1
+    changed = true
+  }
+
+  if (changed) {
+    await store.commit(nextEntries)
+    for (const entry of metaUpdates) {
+      await store.writeMeta(entry).catch((error) => {
+        logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${error instanceof Error ? error.message : String(error)}`)
+      })
+    }
+  }
+  store.unindexed = unindexed
+  return { imported, markedMissing, unindexed, changed: changed ? 1 : 0 }
+}
+
+/**
+ * Rebuild the complete index from one `meta.json` sidecar per object directory.
+ * Used only after the primary index and its backup were both rejected;
+ * unindexed directories stay untouched and are reported.
+ *
+ * @param {{ store: import('./store.js').TrashStore, logger: { warn: Function }, now?: number }} input trash store and diagnostics.
+ * @returns {Promise<{ entries: number, unindexed: number }>} rebuild summary.
+ */
+export async function rebuildIndex({ store, logger, now = Date.now() }) {
+  const { objects, unindexed: invalidObjects } = await scanObjects(store, logger)
+  const entries = []
+  const seen = new Set()
+  let unindexed = invalidObjects
+  for (const object of objects) {
+    if (!object.metaValid || object.meta === undefined) continue
+    const entry = toEntry(object.meta)
+    if (seen.has(entry.sessionId)) {
+      unindexed += 1
+      logger.warn(`the trash object ${object.trashId} duplicates the rebuilt session ${entry.sessionId}`)
+      continue
+    }
+    seen.add(entry.sessionId)
+    entries.push(deriveEntry(entry, object.sessionExists, now))
+  }
+  entries.sort((left, right) => left.startedAt - right.startedAt || left.trashId.localeCompare(right.trashId))
+  await store.commit(entries)
+  store.unindexed = unindexed
+  return { entries: entries.length, unindexed }
+}

package/lib/paths.js

@@ -0,0 +1,39 @@
+import path from 'node:path'
+import { resolveDshHome, dshHomePath, dshHomeDisplay } from '@deepseek-ai/dsh-home-paths'
+import { TrashError } from './errors.js'
+
+/** Trash directory name under the DSH home. */
+export const TRASH_DIRNAME = '.session-trash'
+
+/**
+ * Resolve every trash path from the harness home.
+ *
+ * The host refuses to activate when the shared path library cannot produce an
+ * absolute home, so no caller falls back to an environment guess of its own.
+ *
+ * @returns {{ home: string, root: string, display: string }} resolved absolute paths plus the symbolic display form.
+ */
+export function resolveTrashPaths() {
+  let home
+  try {
+    home = resolveDshHome()
+  } catch (cause) {
+    throw new TrashError(
+      'HOME_UNRESOLVED',
+      `Cannot resolve the DeepSeek Harness home: ${cause instanceof Error ? cause.message : String(cause)}`,
+    )
+  }
+  if (typeof home !== 'string' || home === '' || !path.isAbsolute(home)) {
+    throw new TrashError(
+      'HOME_UNRESOLVED',
+      '@deepseek-ai/dsh-home-paths resolved a non-absolute harness home; the trash plugin refuses to activate.',
+    )
+  }
+  const root = dshHomePath(TRASH_DIRNAME)
+  if (typeof root !== 'string' || !path.isAbsolute(root)) {
+    throw new TrashError('HOME_UNRESOLVED', '@deepseek-ai/dsh-home-paths did not produce an absolute trash root.')
+  }
+  const homeLabel = dshHomeDisplay(home)
+  const display = `${homeLabel === undefined || homeLabel === null || homeLabel === '' ? home : homeLabel}/${TRASH_DIRNAME}`
+  return { home, root, display }
+}