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

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: session-trash
+      name: '@wangxiaocuo/dsh-session-trash'

package/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="Session trash">
+  <rect width="64" height="64" rx="14" fill="#2A6FF0"/>
+  <g transform="translate(14 14) scale(2.25)" fill="none" stroke="#FFFFFF" stroke-width="1">
+    <path d="M1.28149 3.88831H14.7187"/>
+    <path d="M5.41602 3.88833V2.47962C5.41602 2.29282 5.52492 2.11366 5.71876 1.98157C5.9126 1.84948 6.17551 1.77527 6.44964 1.77527H9.55053C9.82466 1.77527 10.0876 1.84948 10.2814 1.98157C10.4753 2.11366 10.5842 2.29282 10.5842 2.47962V3.88833"/>
+    <path d="M2.57349 3.88831L3.19366 13.2943C3.21937 13.5502 3.33952 13.7872 3.53065 13.9593C3.72178 14.1313 3.97016 14.2259 4.22729 14.2246H11.7728C12.0299 14.2259 12.2783 14.1313 12.4694 13.9593C12.6605 13.7872 12.7807 13.5502 12.8064 13.2943L13.4266 3.88831"/>
+    <path d="M6.44946 6.98926V11.1238"/>
+    <path d="M9.55054 6.98926V11.1238"/>
+  </g>
+</svg>

package/index.js

@@ -0,0 +1,129 @@
+import z from '@deepseek-ai/schemastery'
+import { resolveTrashPaths } from './lib/paths.js'
+import { TrashStore } from './lib/store.js'
+import { createEligibility } from './lib/eligibility.js'
+import { createStateService } from './lib/state.js'
+import { createTrashService } from './lib/trash-service.js'
+import { createCleanupService } from './lib/cleanup.js'
+import { registerApi } from './lib/http.js'
+
+/** Host services this plugin cannot work without. */
+export const inject = ['sessionPersistence', 'webServer', 'connection', 'sessions', 'agents']
+
+/** Validated plugin configuration; ordinary fields restart the plugin when changed. */
+export const Config = z.object({
+  retentionDays: z.natural().min(1).max(3650).default(30).description('Days a trashed session is kept before automatic deletion.'),
+  sweepIntervalHours: z
+    .natural()
+    .min(1)
+    .max(168)
+    .default(6)
+    .description('Hours between automatic cleanup sweeps.'),
+  enableAutoCleanup: z.boolean().default(true).description('Automatically delete sessions past the retention period.'),
+  debug: z.boolean().default(false).description('Emit detailed trash diagnostics.'),
+})
+
+/**
+ * Build a plain diagnostics sink that never depends on the shape of the
+ * harness logger service.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @returns {{ info: Function, warn: Function, error: Function, debug: Function }} a prefixed diagnostics sink.
+ */
+function createLogger(ctx) {
+  const prefix = 'dsh-session-trash'
+  let sink = null
+  try {
+    const factory = ctx.get('logger')
+    if (typeof factory === 'function') {
+      const instance = factory(prefix)
+      if (instance !== null && instance !== undefined && typeof instance.info === 'function') sink = instance
+    } else if (factory !== null && factory !== undefined && typeof factory.info === 'function') {
+      sink = factory
+    }
+  } catch {
+    sink = null
+  }
+  const emit = (level, args) => {
+    if (sink !== null && typeof sink[level] === 'function') {
+      sink[level](...args)
+      return
+    }
+    const method = level === 'debug' ? 'log' : level
+    console[method](`[${prefix}]`, ...args)
+  }
+  return {
+    info: (...args) => emit('info', args),
+    warn: (...args) => emit('warn', args),
+    error: (...args) => emit('error', args),
+    debug: (...args) => emit('debug', args),
+  }
+}
+
+/**
+ * Register the trash services, its state projection, the HTTP API, crash
+ * recovery, and the retention sweep.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @param {object} config validated plugin configuration.
+ * @returns {void}
+ */
+export function apply(ctx, config) {
+  const logger = createLogger(ctx)
+  const scoped = config.debug ? logger : { ...logger, debug: () => {} }
+  const paths = resolveTrashPaths()
+  const store = new TrashStore({ root: paths.root, logger: scoped })
+  const eligibility = createEligibility({ ctx, store, logger: scoped })
+  const trashService = createTrashService({
+    ctx,
+    store,
+    eligibility,
+    config,
+    logger: scoped,
+    paths,
+  })
+  const cleanupService = createCleanupService({
+    ctx,
+    trashService,
+    config,
+    logger: scoped,
+  })
+  const stateService = createStateService({
+    store,
+    config,
+    trashRootDisplay: paths.display,
+    nextSweepAt: () => cleanupService.nextSweepAt(),
+    cleanup: () => cleanupService.diagnostics(),
+  })
+
+  ctx.effect(() => () => cleanupService.stop(), 'session-trash: cleanup disposal')
+
+  const ready = store
+    .init()
+    .then(async (summary) => {
+      logger.info(
+        `trash root ready at ${paths.display}; retention ${config.retentionDays}d, sweep every ${config.sweepIntervalHours}h; index ${summary.status}, ${store.entries().length} entries`,
+      )
+      try {
+        const recovery = await trashService.recover()
+        if (recovery.changed > 0) {
+          logger.info(
+            `startup recovery settled ${recovery.changed} entries (${recovery.completed} completed, ${recovery.rolledBack} rolled back, ${recovery.missing} missing)`,
+          )
+        }
+      } catch (error) {
+        logger.error(
+          `startup trash recovery failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
+        )
+      }
+      cleanupService.start()
+      return summary
+    })
+    .catch((error) => {
+      logger.error(`trash root initialization failed at ${paths.display}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`)
+      throw error
+    })
+  ready.catch(() => {})
+
+  registerApi({ ctx, eligibility, stateService, trashService, cleanupService, ready, config, logger: scoped })
+}

package/lib/cleanup.js

@@ -0,0 +1,342 @@
+/** Delay before the first automatic sweep after activation. */
+export const ACTIVATION_SWEEP_DELAY_MS = 10_000
+
+/** How long a page-open sweep waits before triggering another one. */
+export const PAGE_OPEN_THROTTLE_MS = 60 * 60 * 1000
+
+/** First delay after a failed sweep; doubled on every further consecutive failure. */
+export const CLEANUP_RETRY_BASE_MS = 60 * 1000
+
+/** Upper bound for the automatic retry delay. */
+export const CLEANUP_RETRY_MAX_MS = 60 * 60 * 1000
+
+/** Result returned after the service was stopped. */
+const STOPPED_RESULT = Object.freeze({ purged: 0, failed: 0, settled: 0 })
+
+/**
+ * @param {unknown} error arbitrary failure.
+ * @returns {string} a concise message.
+ */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * @param {unknown} error arbitrary failure.
+ * @returns {string} a bounded diagnostic message for `/state`.
+ */
+function errorText(error) {
+  const message = messageOf(error)
+  return message.length > 500 ? `${message.slice(0, 497)}...` : message
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
+ * @returns {{ interval: Function, timeout: Function } | undefined} the timer service, when composed.
+ */
+function resolveTimer(ctx) {
+  let timer
+  try {
+    timer = typeof ctx.get === 'function' ? ctx.get('timer') : undefined
+  } catch {
+    timer = undefined
+  }
+  if (timer !== null && timer !== undefined && typeof timer.interval === 'function' && typeof timer.timeout === 'function') {
+    return timer
+  }
+  if (typeof ctx.interval === 'function' && typeof ctx.timeout === 'function') {
+    return { interval: ctx.interval.bind(ctx), timeout: ctx.timeout.bind(ctx) }
+  }
+  return undefined
+}
+
+/**
+ * Schedule the retention sweep. Automatic cleanup runs once shortly after
+ * activation and then every `sweepIntervalHours`; when the timer service is
+ * absent it degrades to activation + trash-page open. A scheduled sweep that
+ * fails, or that reports failed purges, is retried with exponential backoff so
+ * a transient sharing violation does not wait for the next full interval.
+ * Manual cleanup is always available and never gated by `enableAutoCleanup`.
+ *
+ * @param {{
+ *   ctx: import('@deepseek-ai/cordis').Context,
+ *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<object> },
+ *   config: { sweepIntervalHours: number, enableAutoCleanup: boolean },
+ *   logger: { info: Function, warn: Function, error: Function, debug: Function },
+ * }} deps host services and the configured cadence.
+ * @returns {{
+ *   start: () => void,
+ *   stop: () => void,
+ *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<object>,
+ *   maybeSweepOnPageOpen: () => void,
+ *   nextSweepAt: () => number | null,
+ *   lastSweepAt: () => number,
+ *   diagnostics: () => object,
+ * }} the cleanup service.
+ */
+export function createCleanupService({ ctx, trashService, config, logger }) {
+  const intervalMs = config.sweepIntervalHours * 60 * 60 * 1000
+  const timer = resolveTimer(ctx)
+  let lastAttemptAt = 0
+  let lastSuccessAt = 0
+  let lastRun = null
+  let scheduledAt = null
+  let retryAt = null
+  let consecutiveFailures = 0
+  let inFlight = null
+  let started = false
+  let stopped = false
+  let disposeActivation = null
+  let disposeInterval = null
+  let disposeRetry = null
+
+  /**
+   * @param {unknown} error sweep failure.
+   * @returns {void}
+   */
+  function report(error) {
+    logger.warn(`automatic trash cleanup failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`)
+  }
+
+  /**
+   * @returns {void}
+   */
+  function clearRetry() {
+    const dispose = disposeRetry
+    disposeRetry = null
+    retryAt = null
+    if (typeof dispose !== 'function') return
+    try {
+      dispose()
+    } catch (error) {
+      logger.debug(`cannot dispose the trash cleanup retry timer: ${messageOf(error)}`)
+    }
+  }
+
+  /**
+   * Schedule one backoff retry after a failed automatic sweep.
+   *
+   * @param {string} reason failure trigger for diagnostics.
+   * @returns {void}
+   */
+  function scheduleRetry(reason) {
+    if (stopped || !config.enableAutoCleanup) return
+    clearRetry()
+    const exponent = Math.min(Math.max(consecutiveFailures - 1, 0), 8)
+    const delay = Math.min(CLEANUP_RETRY_BASE_MS * 2 ** exponent, CLEANUP_RETRY_MAX_MS)
+    retryAt = Date.now() + delay
+    const fire = () => {
+      retryAt = null
+      disposeRetry = null
+      void runNow({ reason: 'retry' }).catch(report)
+    }
+    if (timer !== undefined) {
+      disposeRetry = ctx.effect(() => timer.timeout(fire, delay), 'session-trash: cleanup retry')
+    } else {
+      const handle = setTimeout(fire, delay)
+      handle.unref?.()
+      disposeRetry = () => clearTimeout(handle)
+    }
+    logger.warn(
+      `trash cleanup (${reason}) will retry in ${Math.round(delay / 1000)}s after ${consecutiveFailures} consecutive failure(s)`,
+    )
+  }
+
+  /**
+   * Run one sweep, joining an in-flight sweep instead of queuing another. A
+   * manual request waits for the in-flight sweep and then runs its own purge,
+   * because an automatic sweep may have been started with `allowPurge: false`.
+   *
+   * @param {{ manual?: boolean, reason?: string }} [options] manual trigger and diagnostic label.
+   * @returns {Promise<object>} the sweep summary.
+   */
+  async function runNow(options = {}) {
+    if (stopped) return { ...STOPPED_RESULT }
+    const manual = options.manual === true
+    while (inFlight !== null) {
+      if (!manual) return inFlight
+      await inFlight.catch(() => {})
+    }
+    const reason = options.reason ?? (manual ? 'manual' : 'scheduled')
+    const startedAt = Date.now()
+    inFlight = (async () => {
+      const allowPurge = manual || config.enableAutoCleanup
+      try {
+        let result
+        try {
+          result = await trashService.sweep({ allowPurge, now: Date.now(), reason })
+        } catch (error) {
+          lastAttemptAt = Date.now()
+          lastRun = {
+            at: lastAttemptAt,
+            reason,
+            purged: 0,
+            failed: 0,
+            settled: 0,
+            allowPurge,
+            durationMs: lastAttemptAt - startedAt,
+            error: errorText(error),
+          }
+          consecutiveFailures += 1
+          logger.error(`trash cleanup (${reason}) failed after ${lastRun.durationMs}ms: ${messageOf(error)}`)
+          if (!manual) scheduleRetry(reason)
+          throw error
+        }
+        lastAttemptAt = Date.now()
+        lastSuccessAt = lastAttemptAt
+        lastRun = {
+          at: lastAttemptAt,
+          reason,
+          purged: typeof result.purged === 'number' ? result.purged : 0,
+          failed: typeof result.failed === 'number' ? result.failed : 0,
+          settled: typeof result.changed === 'number' ? result.changed : 0,
+          allowPurge,
+          durationMs: lastAttemptAt - startedAt,
+          error: null,
+        }
+        if (lastRun.failed > 0) {
+          consecutiveFailures += 1
+          logger.warn(
+            `trash cleanup (${reason}) finished with ${lastRun.failed} failed purge(s) after ${lastRun.durationMs}ms`,
+          )
+          if (!manual) scheduleRetry(reason)
+        } else {
+          consecutiveFailures = 0
+          clearRetry()
+          if (lastRun.purged > 0 || lastRun.settled > 0) {
+            logger.info(
+              `trash cleanup (${reason}) purged ${lastRun.purged} expired sessions, settled ${lastRun.settled} entries in ${lastRun.durationMs}ms`,
+            )
+          } else {
+            logger.debug(`trash cleanup (${reason}) found nothing to do in ${lastRun.durationMs}ms`)
+          }
+        }
+        return result
+      } finally {
+        inFlight = null
+      }
+    })()
+    return inFlight
+  }
+
+  /**
+   * @returns {void}
+   */
+  function scheduleInterval() {
+    if (stopped || timer === undefined || !config.enableAutoCleanup) return
+    if (disposeInterval !== null) return
+    disposeInterval = ctx.effect(
+      () =>
+        timer.interval(() => {
+          scheduledAt = Date.now() + intervalMs
+          void runNow({ reason: 'interval' }).catch(report)
+        }, intervalMs),
+      'session-trash: retention sweep',
+    )
+  }
+
+  /**
+   * @returns {number | null} the soonest scheduled automatic sweep, preferring a retry.
+   */
+  function computeNextSweepAt() {
+    if (!config.enableAutoCleanup) return null
+    if (retryAt !== null) return retryAt
+    return timer === undefined ? null : scheduledAt
+  }
+
+  return {
+    /**
+     * Schedule the activation sweep. Automatic cleanup is skipped when disabled;
+     * crash recovery has already run by this point either way.
+     *
+     * @returns {void}
+     */
+    start() {
+      if (started || stopped) return
+      started = true
+      if (!config.enableAutoCleanup) {
+        scheduledAt = null
+        return
+      }
+      scheduledAt = timer === undefined ? null : Date.now() + ACTIVATION_SWEEP_DELAY_MS
+      const fire = () => {
+        void runNow({ reason: 'activation' })
+          .catch(report)
+          .finally(() => {
+            if (stopped || !config.enableAutoCleanup) return
+            scheduledAt = timer === undefined ? null : Date.now() + intervalMs
+            scheduleInterval()
+          })
+      }
+      if (timer !== undefined) {
+        disposeActivation = ctx.effect(() => timer.timeout(fire, ACTIVATION_SWEEP_DELAY_MS), 'session-trash: activation sweep')
+      } else {
+        const handle = setTimeout(fire, ACTIVATION_SWEEP_DELAY_MS)
+        handle.unref?.()
+        disposeActivation = () => clearTimeout(handle)
+      }
+    },
+
+    /**
+     * Stop every scheduled sweep and retry, and ignore later triggers.
+     *
+     * @returns {void}
+     */
+    stop() {
+      stopped = true
+      if (typeof disposeActivation === 'function') disposeActivation()
+      if (typeof disposeInterval === 'function') disposeInterval()
+      clearRetry()
+      disposeActivation = null
+      disposeInterval = null
+    },
+
+    runNow,
+
+    /**
+     * Trigger a throttled background sweep when the trash page opens. The
+     * timer-backed composition uses a one-hour throttle; without a timer the
+     * configured sweep interval throttles instead.
+     *
+     * @returns {void}
+     */
+    maybeSweepOnPageOpen() {
+      if (stopped) return
+      const throttle = timer === undefined || !config.enableAutoCleanup ? intervalMs : PAGE_OPEN_THROTTLE_MS
+      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return
+      void runNow({ reason: 'page-open' }).catch(report)
+    },
+
+    /**
+     * @returns {number | null} the next scheduled automatic sweep, when one exists.
+     */
+    nextSweepAt() {
+      return computeNextSweepAt()
+    },
+
+    /**
+     * @returns {number} the last succeeded sweep timestamp, or zero.
+     */
+    lastSweepAt() {
+      return lastSuccessAt
+    },
+
+    /**
+     * Read-only cleanup diagnostics for `/state` and the settings page.
+     *
+     * @returns {object} a JSON-safe diagnostic snapshot.
+     */
+    diagnostics() {
+      return {
+        enabled: config.enableAutoCleanup,
+        timerBacked: timer !== undefined,
+        lastAttemptAt: lastAttemptAt === 0 ? null : lastAttemptAt,
+        lastSuccessAt: lastSuccessAt === 0 ? null : lastSuccessAt,
+        nextSweepAt: computeNextSweepAt(),
+        retryAt,
+        consecutiveFailures,
+        lastRun: lastRun === null ? null : { ...lastRun },
+      }
+    },
+  }
+}

package/lib/eligibility.js

@@ -0,0 +1,212 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { isSafeDirectoryPath } from './fsops.js'
+
+/** How long a successful preflight answer is reused by the menu. */
+export const PREFLIGHT_TTL_MS = 2000
+
+/**
+ * @typedef {{ eligible: true } | { eligible: false, code: string, message: string, details?: object }} PreflightResult
+ */
+
+/**
+ * @param {string} code refusal code.
+ * @param {string} message owner-facing explanation.
+ * @param {object} [details] optional structured context.
+ * @returns {{ eligible: false, code: string, message: string, details?: object }} a refusal.
+ */
+function refuse(code, message, details) {
+  return details === undefined ? { eligible: false, code, message } : { eligible: false, code, message, details }
+}
+
+/**
+ * Collect the ids of every stored session whose lineage descends from `sessionId`.
+ *
+ * @param {import('@deepseek-ai/dsh-session-persistence').SessionPersistence} persistence persistence service.
+ * @param {string} sessionId root session.
+ * @returns {Promise<string[]>} descendant ids.
+ */
+async function descendantsFromListing(persistence, sessionId) {
+  const snapshots = await persistence.list()
+  const childrenByParent = new Map()
+  for (const snapshot of snapshots) {
+    const parent = snapshot?.header?.parentSession
+    if (typeof parent !== 'string') continue
+    const bucket = childrenByParent.get(parent)
+    if (bucket === undefined) childrenByParent.set(parent, [snapshot.header.id])
+    else bucket.push(snapshot.header.id)
+  }
+  const found = []
+  const queue = [sessionId]
+  const visited = new Set([sessionId])
+  while (queue.length > 0) {
+    const current = queue.shift()
+    for (const child of childrenByParent.get(current) ?? []) {
+      if (visited.has(child)) continue
+      visited.add(child)
+      found.push(child)
+      queue.push(child)
+    }
+  }
+  return found
+}
+
+/**
+ * Flatten the nested descendant tree returned by `sessionQuery.traceSession`.
+ * A grandchild whose direct parent is no longer stored still proves that the
+ * root session owns a lineage the trash must not split.
+ *
+ * @param {readonly object[]} nodes descendant nodes from the trace.
+ * @returns {string[]} every descendant session id.
+ */
+function collectTraceDescendants(nodes) {
+  const ids = []
+  const visit = (list) => {
+    for (const node of list) {
+      const id = node?.session?.header?.id ?? node?.session?.id
+      if (typeof id === 'string' && id !== '') ids.push(id)
+      if (Array.isArray(node?.descendants)) visit(node.descendants)
+    }
+  }
+  visit(Array.isArray(nodes) ? nodes : [])
+  return ids
+}
+
+/**
+ * Decide whether one session may move into the trash. The same predicate backs
+ * both the menu preflight and (from Phase 2) the write path.
+ *
+ * @param {{ ctx: import('@deepseek-ai/cordis').Context, store: import('./store.js').TrashStore, logger: object }} deps host services.
+ * @returns {{ evaluate: (sessionId: string) => Promise<PreflightResult>, invalidate: (sessionId?: string) => void }} the cached evaluator.
+ */
+export function createEligibility({ ctx, store, logger }) {
+  /** @type {Map<string, { expires: number, value: PreflightResult }>} */
+  const cache = new Map()
+
+  /**
+   * @param {string} sessionId session to inspect.
+   * @returns {Promise<PreflightResult>} the uncached verdict.
+   */
+  async function evaluateUncached(sessionId) {
+    let snapshot
+    try {
+      snapshot = await ctx.sessionPersistence.stat(sessionId)
+    } catch (error) {
+      logger.warn(`preflight stat failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+      return refuse('IO_ERROR', 'The session storage could not be read.')
+    }
+    if (snapshot === undefined || snapshot === null) {
+      return refuse('SESSION_NOT_FOUND', 'This session is not in session storage.')
+    }
+
+    const existing = store.findEntry(sessionId)
+    if (
+      existing !== undefined &&
+      (existing.state === 'trashed' ||
+        existing.state === 'trashing' ||
+        existing.state === 'restoring' ||
+        existing.state === 'purging')
+    ) {
+      return refuse('ALREADY_TRASHED', 'This session is already recorded in the trash.')
+    }
+
+    const location = snapshot.location
+    if (location === undefined || location === null || typeof location.path !== 'string') {
+      return refuse('SESSION_NOT_MATERIALIZED', 'This session has no stored log yet, so it has nothing to remove.')
+    }
+    if (location.kind !== 'jsonl') {
+      return refuse('STORAGE_UNSUPPORTED', `The "${String(location.kind)}" session storage backend is not supported.`)
+    }
+    if (!path.isAbsolute(location.path)) {
+      return refuse('STORAGE_UNSUPPORTED', 'The session log path is not absolute.')
+    }
+
+    if (snapshot.header?.origin === 'subagent') {
+      return refuse('SESSION_SUBAGENT', 'Subagent sessions cannot be moved to the trash on their own.')
+    }
+
+    let descendants
+    const sessionQuery = ctx.get('sessionQuery')
+    if (sessionQuery !== undefined && typeof sessionQuery.traceSession === 'function') {
+      try {
+        const trace = await sessionQuery.traceSession(sessionId)
+        descendants = collectTraceDescendants(trace?.descendants ?? [])
+      } catch (error) {
+        logger.warn(`preflight lineage failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+        return refuse('SESSION_LINEAGE_UNRESOLVED', 'The session lineage could not be resolved, so the session is left untouched.')
+      }
+    } else {
+      try {
+        descendants = await descendantsFromListing(ctx.sessionPersistence, sessionId)
+      } catch (error) {
+        logger.warn(`preflight lineage listing failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+        return refuse('SESSION_LINEAGE_UNRESOLVED', 'The session lineage could not be resolved, so the session is left untouched.')
+      }
+    }
+    const childCount = descendants.filter((id) => typeof id === 'string' && id !== '').length
+    if (childCount > 0) {
+      return refuse('SESSION_HAS_DESCENDANTS', 'This session still has child sessions; archive the tree instead.', {
+        descendants: childCount,
+      })
+    }
+
+    const liveSession = typeof ctx.sessions?.get === 'function' ? ctx.sessions.get(sessionId) : undefined
+    const liveAgent = typeof ctx.agents?.get === 'function' ? ctx.agents.get(sessionId) : undefined
+    if (liveSession !== undefined || liveAgent !== undefined) {
+      return refuse('SESSION_LIVE', 'This session is open right now. Close it before moving it to the trash.')
+    }
+
+    let activity
+    try {
+      activity = await ctx.waterfall('workspace/session-activity', { sessionId }, () => Promise.resolve([]))
+    } catch (error) {
+      logger.warn(`preflight activity failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+      return refuse('SESSION_ACTIVE', 'Session activity could not be checked, so the session is left untouched.')
+    }
+    if (Array.isArray(activity) && activity.length > 0) {
+      return refuse('SESSION_ACTIVE', 'This session still has running work.', {
+        activity: activity.map((item) => item?.kind ?? 'unknown'),
+      })
+    }
+
+    const sessionDir = path.dirname(location.path)
+    let stats
+    try {
+      stats = await fs.lstat(sessionDir)
+    } catch (error) {
+      logger.warn(`preflight cannot stat ${sessionDir}: ${error instanceof Error ? error.message : String(error)}`)
+      return refuse('IO_ERROR', 'The session directory could not be read.')
+    }
+    if (!stats.isDirectory() || !isSafeDirectoryPath(sessionDir)) {
+      return refuse('UNSAFE_SESSION_DIR', 'The session directory is not a plain directory this plugin can move.')
+    }
+
+    return { eligible: true }
+  }
+
+  return {
+    /**
+     * @param {string} sessionId session to inspect.
+     * @returns {Promise<PreflightResult>} the cached verdict.
+     */
+    async evaluate(sessionId) {
+      if (store.isProtected()) {
+        return refuse('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses new entries.')
+      }
+      const now = Date.now()
+      const hit = cache.get(sessionId)
+      if (hit !== undefined && hit.expires > now) return hit.value
+      const value = await evaluateUncached(sessionId)
+      cache.set(sessionId, { expires: now + PREFLIGHT_TTL_MS, value })
+      return value
+    },
+    /**
+     * @param {string} [sessionId] session whose cached verdict is stale, or every session.
+     * @returns {void}
+     */
+    invalidate(sessionId) {
+      if (sessionId === undefined) cache.clear()
+      else cache.delete(sessionId)
+    },
+  }
+}