@xmanrui/dsh-im 4.9.1 → 4.11.0

package/plugin-src/host/delivery-service.mjs

@@ -7,6 +7,7 @@ const DRAFT_TARGET_ID = '__test__';
 
 const ADAPTER_METHODS = Object.freeze([
   'ownsBot',
+  'listBots',
   'listTargets',
   'listSuggestions',
   'createTarget',
@@ -24,9 +25,16 @@ const DELIVERY_ERROR_CODES = new Set([
   'bot-not-connected',
   'target-rejected',
   'delivery-failed',
+  'session-sync-unavailable',
   'cancelled',
 ]);
 
+const SESSION_SYNC_METHODS = Object.freeze([
+  'setSessionSync',
+  'listSessionSyncTargets',
+  'sendSessionSyncText',
+]);
+
 function deliveryError(code, message = code, options) {
   const error = new Error(message, options);
   error.code = code;
@@ -92,8 +100,29 @@ function validateAdapter(adapter) {
   return adapter;
 }
 
+function sessionSyncState(value, available) {
+  const enabled = value?.enabled === true;
+  if (!available) return { enabled, state: 'unavailable' };
+  const state = value?.state;
+  if (['off', 'active', 'waiting', 'unavailable'].includes(state)) {
+    return { enabled, state };
+  }
+  return { enabled: false, state: 'unavailable' };
+}
+
 export class DeliveryService {
   #adapters = new Map();
+  #unavailableSessionSyncChannels;
+
+  constructor({ unavailableSessionSyncChannels = [] } = {}) {
+    if (!Array.isArray(unavailableSessionSyncChannels)
+      || unavailableSessionSyncChannels.some((channel) => (
+        typeof channel !== 'string' || !CHANNEL_PATTERN.test(channel)
+      ))) {
+      throw new TypeError('unavailableSessionSyncChannels must contain valid channel ids');
+    }
+    this.#unavailableSessionSyncChannels = new Set(unavailableSessionSyncChannels);
+  }
 
   registerAdapter(value) {
     const adapter = validateAdapter(value);
@@ -112,12 +141,34 @@ export class DeliveryService {
     try {
       const targets = await adapter.listTargets(id);
       if (!Array.isArray(targets)) throw new TypeError('Adapter returned invalid targets');
-      return { botId: id, channel: adapter.channel, targets };
+      const available = this.#supportsSessionSync(adapter);
+      return {
+        botId: id,
+        channel: adapter.channel,
+        targets: targets.map((target) => ({
+          ...target,
+          sessionSync: sessionSyncState(target?.sessionSync, available),
+        })),
+      };
     } catch (error) {
       throw publicOperationError(error);
     }
   }
 
+  async listBots() {
+    const bots = [];
+    for (const { adapter } of this.#adapters.values()) {
+      try {
+        const ids = await adapter.listBots();
+        if (!Array.isArray(ids)) throw new TypeError('Adapter returned invalid bots');
+        for (const botId of ids) bots.push({ botId: botIdOf(botId), channel: adapter.channel });
+      } catch (error) {
+        throw publicOperationError(error);
+      }
+    }
+    return bots;
+  }
+
   async listSuggestions(botId) {
     const id = botIdOf(botId);
     const adapter = await this.#adapterFor(id);
@@ -173,6 +224,72 @@ export class DeliveryService {
     }
   }
 
+  async setSessionSync(botId, targetId, enabled) {
+    const id = botIdOf(botId);
+    const targetKey = targetIdOf(targetId);
+    if (typeof enabled !== 'boolean') throw deliveryError('bad-request', 'Invalid enabled state');
+    const adapter = await this.#adapterFor(id);
+    const hasMethods = SESSION_SYNC_METHODS.every((method) => typeof adapter[method] === 'function');
+    if (!hasMethods || (enabled && !this.#supportsSessionSync(adapter))) {
+      throw deliveryError('session-sync-unavailable', 'Session sync is unavailable');
+    }
+    try {
+      return await adapter.setSessionSync(id, targetKey, enabled);
+    } catch (error) {
+      throw publicOperationError(error);
+    }
+  }
+
+  async listSessionSyncTargets(sessionId) {
+    if (typeof sessionId !== 'string' || !sessionId) {
+      throw deliveryError('bad-request', 'Invalid Session id');
+    }
+    const targets = [];
+    for (const { adapter } of this.#adapters.values()) {
+      if (!this.#supportsSessionSync(adapter)) continue;
+      try {
+        const listed = await adapter.listSessionSyncTargets(sessionId);
+        if (!Array.isArray(listed)) throw new TypeError('Adapter returned invalid sync targets');
+        for (const target of listed) {
+          targets.push({
+            channel: adapter.channel,
+            botId: botIdOf(target?.botId),
+            targetId: targetIdOf(target?.targetId),
+          });
+        }
+      } catch (error) {
+        console.warn(
+          `[dsh-im] ignored ${adapter.channel} Session sync target lookup failure`
+            + ` (${error?.code ?? error?.name ?? 'unknown-error'})`,
+        );
+      }
+    }
+    return targets;
+  }
+
+  async sendSessionSyncText(botId, targetId, sessionId, text, { signal } = {}) {
+    const id = botIdOf(botId);
+    const targetKey = targetIdOf(targetId);
+    if (typeof sessionId !== 'string' || !sessionId
+      || typeof text !== 'string' || !text.trim()) {
+      throw deliveryError('bad-request', 'Invalid session sync delivery');
+    }
+    cancellation(signal);
+    const adapter = await this.#adapterFor(id);
+    if (!this.#supportsSessionSync(adapter)) {
+      throw deliveryError('session-sync-unavailable', 'Session sync is unavailable');
+    }
+    try {
+      await adapter.sendSessionSyncText(id, targetKey, sessionId, text, { signal });
+      return { sent: true };
+    } catch (error) {
+      if (signal?.aborted || error?.name === 'AbortError' || error?.code === 'ABORT_ERR') {
+        throw deliveryError('cancelled', 'Request cancelled', { cause: error });
+      }
+      throw publicOperationError(error);
+    }
+  }
+
   async send(botId, targetIdOrDraft, text, { signal } = {}) {
     const id = botIdOf(botId);
     const targetKey = typeof targetIdOrDraft === 'string'
@@ -217,8 +334,13 @@ export class DeliveryService {
     }
     throw deliveryError('unknown-bot', 'Unknown bot');
   }
+
+  #supportsSessionSync(adapter) {
+    return !this.#unavailableSessionSyncChannels.has(adapter.channel)
+      && SESSION_SYNC_METHODS.every((method) => typeof adapter[method] === 'function');
+  }
 }
 
-export function createDeliveryService() {
-  return new DeliveryService();
+export function createDeliveryService(options) {
+  return new DeliveryService(options);
 }

package/plugin-src/host/delivery-suggestions.mjs

@@ -115,6 +115,52 @@ export function deliverySuggestionFromConversationKey(channel, key) {
   }
 }
 
+/** Convert only a persisted private-chat key into its stable delivery route. */
+export function privateDeliverySuggestionFromConversationKey(channel, key) {
+  const separator = typeof key === 'string' ? key.indexOf(':') : -1;
+  const prefix = separator > 0 ? key.slice(0, separator) : '';
+  const privatePrefix = {
+    weixin: 'p2p',
+    feishu: 'p2p',
+    dingtalk: 'p2p',
+    wecom: 'direct',
+    qq: 'c2c',
+    slack: 'direct',
+    telegram: 'direct',
+    discord: 'direct',
+    whatsapp: 'direct',
+  }[channel];
+  if (!privatePrefix || prefix !== privatePrefix) return null;
+  return deliverySuggestionFromConversationKey(channel, key);
+}
+
+function routeIdentity(value) {
+  if (!isRecord(value?.route) || typeof value.kind !== 'string') return null;
+  return JSON.stringify([
+    value.kind,
+    Object.keys(value.route).sort().map((key) => [key, value.route[key]]),
+  ]);
+}
+
+/** Check that one saved private conversation key still identifies this target route. */
+export function privateConversationKeyMatchesTarget(channel, key, target) {
+  const suggestion = privateDeliverySuggestionFromConversationKey(channel, key);
+  const suggestionIdentity = routeIdentity(suggestion);
+  return suggestionIdentity !== null && suggestionIdentity === routeIdentity(target);
+}
+
+/** Resolve exactly one current private conversation for a normalized delivery target. */
+export function resolvePrivateConversationKey(channel, sessions, target) {
+  if (!CHANNELS.has(channel) || !isRecord(sessions)) return null;
+  const matches = [];
+  for (const [key, sessionId] of Object.entries(sessions)) {
+    if (typeof sessionId !== 'string' || !sessionId) continue;
+    if (privateConversationKeyMatchesTarget(channel, key, target)) matches.push(key);
+    if (matches.length > 1) return null;
+  }
+  return matches[0] ?? null;
+}
+
 /**
  * Extract and de-duplicate stable delivery routes from a persisted sessions map.
  * Session ids and every other state field are intentionally ignored.

package/plugin-src/host/harness-session-coordinator.mjs

@@ -22,7 +22,9 @@ function agentsFromContext(ctx) {
 
 function currentOwnedTurn(agent, expectedTurn, promptRpcId) {
   if (agent?.status !== 'running') return false;
-  const events = agent?.session?.events;
+  const events = typeof agent?.session?.snapshotEvents === 'function'
+    ? agent.session.snapshotEvents()
+    : agent?.session?.events;
   if (!Array.isArray(events)) return false;
 
   let openTurn = null;
@@ -53,12 +55,12 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
-function steeringMessage(text) {
+function steeringMessage(text, rpcId) {
   return deepFreeze({
     id: randomUUID(),
     role: 'user',
     content: [{ type: 'text', text }],
-    source: { kind: 'user' },
+    source: { kind: 'user', rpcId },
   });
 }
 
@@ -69,7 +71,7 @@ function agentBusyError(cause) {
 }
 
 function createControlExecutor(agents) {
-  return ({ sessionId, expectedTurn, promptRpcId, action, text }) => {
+  return ({ sessionId, expectedTurn, promptRpcId, inputRpcId, action, text }) => {
     const agent = agents.get(sessionId);
     // An unattached Session cannot be coordinated in-process. Let the client
     // retain its legacy HTTP path for deployments where attachment is lazy.
@@ -81,10 +83,11 @@ function createControlExecutor(agents) {
       return true;
     }
     if (action === 'steer') {
-      if (typeof text !== 'string' || !text.trim()) return false;
+      if (typeof text !== 'string' || !text.trim()
+        || typeof inputRpcId !== 'string' || !inputRpcId) return false;
       // inject() never wakes an idle driver. Because validation and injection
       // share one JS tick, this context can only target this live turn's next step.
-      agent.inject(steeringMessage(text));
+      agent.inject(steeringMessage(text, inputRpcId));
       return true;
     }
     throw new TypeError(`Unsupported Harness control action: ${String(action)}`);
@@ -113,7 +116,7 @@ function createSessionMaintenanceExecutor(agents) {
   };
 }
 
-function createFileIngressExecutor(agents) {
+function createFileIngressExecutor(agents, { inboundTtlService } = {}) {
   return ({ sessionId, workspace, files, signal }) => {
     const agent = agents.get(sessionId);
     const attachedWorkspace = agent?.session?.header?.cwd;
@@ -126,7 +129,19 @@ function createFileIngressExecutor(agents) {
         'The Harness Session workspace is unavailable for inbound files.',
       );
     }
-    return stageInboundFiles({ files }, { workspace: exactWorkspace, signal });
+    const staged = stageInboundFiles({ files }, {
+      workspace: exactWorkspace,
+      signal,
+      ...(inboundTtlService ? { retention: inboundTtlService.stagingRetention() } : {}),
+      // Registration at creation time closes the mid-staging sweep window;
+      // trackStaged later re-registers idempotently and owns the release.
+      ...(typeof inboundTtlService?.trackDirectory === 'function'
+        ? { onStagedDirectory: (directory) => inboundTtlService.trackDirectory(directory) }
+        : {}),
+    });
+    return inboundTtlService
+      ? staged.then((result) => (result ? inboundTtlService.trackStaged(result) : result))
+      : staged;
   };
 }
 
@@ -136,7 +151,9 @@ function createFileIngressExecutor(agents) {
  * when an Agent is attached, its live Session header remains authoritative.
  */
 export function createHarnessSessionExecutors(ctx, provided = {}) {
-  const { controlExecutor, sessionMaintenanceExecutor, fileIngressExecutor } = provided;
+  const {
+    controlExecutor, sessionMaintenanceExecutor, fileIngressExecutor, inboundTtlService,
+  } = provided;
   if (controlExecutor !== undefined && typeof controlExecutor !== 'function') {
     throw new TypeError('controlExecutor must be a function');
   }
@@ -147,6 +164,11 @@ export function createHarnessSessionExecutors(ctx, provided = {}) {
   if (fileIngressExecutor !== undefined && typeof fileIngressExecutor !== 'function') {
     throw new TypeError('fileIngressExecutor must be a function');
   }
+  if (inboundTtlService !== undefined
+    && (typeof inboundTtlService?.stagingRetention !== 'function'
+      || typeof inboundTtlService?.trackStaged !== 'function')) {
+    throw new TypeError('inboundTtlService must expose stagingRetention() and trackStaged()');
+  }
 
   const agents = controlExecutor && sessionMaintenanceExecutor && fileIngressExecutor
     ? undefined
@@ -156,6 +178,6 @@ export function createHarnessSessionExecutors(ctx, provided = {}) {
     sessionMaintenanceExecutor: sessionMaintenanceExecutor
       ?? (agents ? createSessionMaintenanceExecutor(agents) : undefined),
     fileIngressExecutor: fileIngressExecutor
-      ?? createFileIngressExecutor(agents ?? { get: () => undefined }),
+      ?? createFileIngressExecutor(agents ?? { get: () => undefined }, { inboundTtlService }),
   };
 }

package/plugin-src/host/inbound-ttl-rpc.mjs

@@ -0,0 +1,83 @@
+import { normalizeInboundTtlHours } from '../../src/channels/shared/inbound-ttl.mjs';
+import { getInboundTtlRuntime } from './inbound-ttl-runtime.mjs';
+
+export const INBOUND_TTL_RPC_CHANNEL = '/dsh-im-settings';
+export const INBOUND_TTL_ENDPOINTS = Object.freeze({
+  get: 'settings.inbound-ttl.get',
+  set: 'settings.inbound-ttl.set',
+  sweep: 'settings.inbound-ttl.sweep',
+});
+
+const ENDPOINTS = new Set(Object.values(INBOUND_TTL_ENDPOINTS));
+
+export function validInboundTtlPayload(endpoint, payload) {
+  if (!ENDPOINTS.has(endpoint)) return false;
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return false;
+  const keys = Object.keys(payload);
+  if (endpoint === INBOUND_TTL_ENDPOINTS.set) {
+    return keys.length === 1 && keys[0] === 'ttlHours'
+      && normalizeInboundTtlHours(payload.ttlHours) !== null;
+  }
+  return keys.length === 0;
+}
+
+export function createInboundTtlRpcHandler({ store, service, logger = null } = {}) {
+  if (!store || typeof store.getTtlHours !== 'function'
+    || typeof store.setTtlHours !== 'function'
+    || !service || typeof service.sweepNow !== 'function') {
+    throw new TypeError('createInboundTtlRpcHandler requires an inbound TTL store and service');
+  }
+  return async (endpoint, payload, signal) => {
+    if (!validInboundTtlPayload(endpoint, payload)) {
+      return { ok: false, error: { code: 'bad-request', message: 'Invalid inbound TTL request.' } };
+    }
+    if (signal?.aborted) {
+      return { ok: false, error: { code: 'cancelled', message: 'Request cancelled.' } };
+    }
+    try {
+      if (endpoint === INBOUND_TTL_ENDPOINTS.get) {
+        return { ok: true, value: { ttlHours: store.getTtlHours() } };
+      }
+      if (endpoint === INBOUND_TTL_ENDPOINTS.set) {
+        const ttlHours = await store.setTtlHours(payload.ttlHours);
+        // Re-arm the sweep interval so the saved value gets a full window
+        // before its first scheduled enforcement.
+        service.resetSweepSchedule?.();
+        return { ok: true, value: { ttlHours } };
+      }
+      const summary = await service.sweepNow();
+      // The UI shows no result text, so the host log is the only place a
+      // manual sweep can be diagnosed (TTL applied, coverage, deletions).
+      logger?.info?.(
+        `[dsh-im] manual inbound attachment sweep: ${summary.deletedDirectories} deleted`
+        + ` across ${summary.sweptWorkspaces} workspaces (ttl ${store.getTtlHours()}h)`,
+      );
+      return { ok: true, value: summary };
+    } catch (error) {
+      if (error?.code === 'inbound-ttl-invalid') {
+        return {
+          ok: false,
+          error: {
+            code: 'inbound-ttl-invalid',
+            message: '附件保留时长无效：请输入 -1、0 或 1-8760 之间的整数小时数。',
+          },
+        };
+      }
+      return { ok: false, error: { code: 'inbound-ttl-unavailable', message: 'inbound-ttl-unavailable' } };
+    }
+  };
+}
+
+export function installInboundTtlRpc(ctx, options = {}) {
+  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
+    throw new TypeError('DSH Host Connection RPC is required');
+  }
+  const runtime = options.runtime ?? getInboundTtlRuntime(ctx, options.config);
+  const logger = typeof ctx?.logger === 'function'
+    ? ctx.logger('dsh-im:inbound-ttl') : (ctx?.logger ?? null);
+  return ctx.connection.rpc.handle(
+    INBOUND_TTL_RPC_CHANNEL,
+    createInboundTtlRpcHandler({ ...runtime, logger }),
+    { authority: 'loopback' },
+  );
+}

package/plugin-src/host/inbound-ttl-runtime.mjs

@@ -0,0 +1,85 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { InboundTtlStore } from '../../src/channels/shared/inbound-ttl-store.mjs';
+import { createInboundTtlService } from './inbound-ttl-service.mjs';
+
+const runtimes = new Map();
+
+/**
+ * Resolve the global settings file shared by every channel. The dshHome
+ * resolution mirrors pluginPaths: config.dshHome, then DSH_HOME, then the
+ * user's home directory. Channel-specific dataDir values never apply.
+ */
+export function inboundTtlSettingsPath(config = {}) {
+  const dshHome = resolve(config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh'));
+  return resolve(dshHome, 'integrations', 'dsh-im', 'settings.json');
+}
+
+/**
+ * Per-process inbound TTL runtime, cached by resolved settings path so every
+ * channel shares one store, one staged registry, and one sweep timer. The
+ * entry is dropped (and the sweeper stopped) when the owning context is
+ * disposed, letting a later activation rebuild from disk.
+ */
+export function getInboundTtlRuntime(ctx, config = {}) {
+  const settingsPath = inboundTtlSettingsPath(config);
+  const existing = runtimes.get(settingsPath);
+  if (existing) return existing.runtime;
+  const logger = typeof ctx?.logger === 'function'
+    ? ctx.logger('dsh-im:inbound-ttl') : (ctx?.logger ?? console);
+  const store = new InboundTtlStore(settingsPath);
+  const service = createInboundTtlService({ store, logger });
+  const runtime = Object.freeze({ store, service });
+  const entry = { runtime };
+  runtimes.set(settingsPath, entry);
+  // Load persisted settings before the first sweep so a keep-forever TTL can
+  // never be overtaken by the in-memory default. An unreadable store keeps
+  // sweeping disabled rather than deleting files of unknown intent.
+  void store.load().then(
+    () => service.start(),
+    (error) => logger.error?.('[dsh-im] unable to load inbound attachment settings; sweeping stays disabled', error),
+  );
+  if (typeof ctx?.effect === 'function') {
+    ctx.effect(() => () => {
+      if (runtimes.get(settingsPath) !== entry) return;
+      runtimes.delete(settingsPath);
+      service.stop();
+    }, 'dsh-im: stop inbound attachment TTL sweeper');
+  }
+  return runtime;
+}
+
+/**
+ * Advertise one channel's bot workspaces to the global sweeper. The provider
+ * is consulted at sweep time, so bots added or removed later are always
+ * current. The default workspace is always included.
+ */
+export function registerInboundTtlWorkspaces(ctx, service, {
+  workspaces,
+  configStore,
+  defaultWorkspace,
+  botIdFrom = (bot) => bot?.botId,
+} = {}) {
+  if (!service || typeof service.registerWorkspaceProvider !== 'function') return undefined;
+  if (!workspaces || typeof workspaces.workspaceFor !== 'function'
+    || typeof defaultWorkspace !== 'string' || !defaultWorkspace) {
+    return undefined;
+  }
+  const unregister = service.registerWorkspaceProvider(() => {
+    const bots = typeof configStore?.list === 'function' ? configStore.list() : [];
+    const paths = [defaultWorkspace];
+    for (const bot of Array.isArray(bots) ? bots : []) {
+      try {
+        paths.push(workspaces.workspaceFor(botIdFrom(bot)));
+      } catch {
+        // A malformed config entry must not hide the remaining workspaces.
+      }
+    }
+    return paths;
+  });
+  if (typeof ctx?.effect === 'function') {
+    ctx.effect(() => unregister, 'dsh-im: unregister inbound TTL workspaces');
+  }
+  return unregister;
+}

package/plugin-src/host/inbound-ttl-service.mjs

@@ -0,0 +1,179 @@
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { sweepInboundAttachments } from '../../src/channels/shared/inbound-file.mjs';
+
+const DEFAULT_SWEEP_INTERVAL_MS = 30 * 60_000;
+
+// A tracked directory is shielded from sweeps while its turn may still be
+// running. Aborted or stalled turns never call cleanup(), so protection has
+// an upper bound — far above the default reply timeout — after which the
+// directory falls back under TTL control instead of leaking forever.
+const TRACKED_PROTECTION_MS = 24 * 60 * 60_000;
+
+/**
+ * Host-process coordinator for the global inbound attachment TTL. The staged
+ * registry marks directories owned by in-flight turns so a slow turn can
+ * outlive any TTL window without the sweeper deleting its files.
+ */
+export function createInboundTtlService({
+  store,
+  logger = console,
+  intervalMs = DEFAULT_SWEEP_INTERVAL_MS,
+} = {}) {
+  if (!store || typeof store.getTtlHours !== 'function') {
+    throw new TypeError('createInboundTtlService requires a store exposing getTtlHours()');
+  }
+  const tracked = new Map();
+  const providers = new Set();
+  let timer = null;
+
+  const runSweep = () => {
+    sweepNow().catch((error) => {
+      logger.error?.('[dsh-im] inbound attachment sweep failed', error);
+    });
+  };
+
+  function registerWorkspaceProvider(provider) {
+    if (typeof provider !== 'function') {
+      throw new TypeError('inbound TTL workspace provider must be a function');
+    }
+    const wasEmpty = providers.size === 0;
+    providers.add(provider);
+    // The startup sweep races channel activation and usually runs before any
+    // provider exists; re-sweep on the first registration so crash leftovers
+    // do not wait a full interval.
+    if (wasEmpty && timer) runSweep();
+    return () => {
+      providers.delete(provider);
+    };
+  }
+
+  function stagingRetention() {
+    // TTL 0 deletes at turn end; every other mode keeps files for the sweeper.
+    return store.getTtlHours() === 0 ? 'turn' : 'persistent';
+  }
+
+  function canonicalPath(directory) {
+    try {
+      return realpathSync(directory);
+    } catch {
+      return null;
+    }
+  }
+
+  function trackDirectory(directory, { now = () => Date.now() } = {}) {
+    if (typeof directory !== 'string' || !directory) return;
+    const trackedAt = now();
+    tracked.set(directory, trackedAt);
+    // The harness-reported cwd and workspaceFor() may normalize symlinks
+    // differently; track both spellings so either side finds the entry.
+    const canonical = canonicalPath(directory);
+    if (canonical && canonical !== directory) tracked.set(canonical, trackedAt);
+  }
+
+  function releaseDirectory(directory) {
+    tracked.delete(directory);
+    const canonical = canonicalPath(directory);
+    if (canonical && canonical !== directory) tracked.delete(canonical);
+  }
+
+  function isTrackedNow(directory) {
+    const trackedAt = tracked.get(directory);
+    if (trackedAt === undefined) return false;
+    if (Date.now() - trackedAt >= TRACKED_PROTECTION_MS) {
+      tracked.delete(directory);
+      return false;
+    }
+    return true;
+  }
+
+  function trackStaged(staged) {
+    if (!staged || typeof staged !== 'object') return staged;
+    const { directory } = staged;
+    if (typeof directory !== 'string' || !directory) return staged;
+    trackDirectory(directory);
+    const cleanup = typeof staged.cleanup === 'function' ? staged.cleanup : null;
+    return Object.freeze({
+      ...staged,
+      async cleanup() {
+        try {
+          await cleanup?.call(staged);
+        } finally {
+          releaseDirectory(directory);
+        }
+      },
+    });
+  }
+
+  async function sweepNow() {
+    const ttlHours = store.getTtlHours();
+    // Keep-forever never deletes, so no workspace is even inspected.
+    if (ttlHours === -1) return { deletedDirectories: 0, sweptWorkspaces: 0 };
+    const workspaces = new Set();
+    for (const provider of providers) {
+      try {
+        const provided = await provider();
+        for (const workspace of Array.isArray(provided) ? provided : []) {
+          if (typeof workspace === 'string' && workspace) workspaces.add(resolve(workspace));
+        }
+      } catch (error) {
+        logger.warn?.('[dsh-im] inbound TTL workspace provider failed', error);
+      }
+    }
+    const isTracked = (directory) => isTrackedNow(directory)
+      || (canonicalPath(directory) !== null && isTrackedNow(canonicalPath(directory)));
+    let deletedDirectories = 0;
+    let sweptWorkspaces = 0;
+    for (const workspace of workspaces) {
+      try {
+        const result = await sweepInboundAttachments(workspace, ttlHours, { isTracked });
+        deletedDirectories += result.deleted;
+        sweptWorkspaces += 1;
+      } catch (error) {
+        logger.warn?.(`[dsh-im] inbound attachment sweep failed under ${workspace}`, error);
+      }
+    }
+    if (deletedDirectories > 0) {
+      logger.info?.(
+        `[dsh-im] inbound attachment sweep deleted ${deletedDirectories} directories`
+        + ` across ${sweptWorkspaces} workspaces (ttl ${ttlHours}h)`,
+      );
+    }
+    return { deletedDirectories, sweptWorkspaces };
+  }
+
+  function start() {
+    if (timer) return;
+    runSweep();
+    timer = setInterval(runSweep, intervalMs);
+    timer.unref?.();
+  }
+
+  // A freshly saved TTL postpones the next scheduled sweep by a full
+  // interval so the new value is never enforced by a sweep firing moments
+  // after the change, and is not starved of one either.
+  function resetSweepSchedule() {
+    if (!timer) return;
+    clearInterval(timer);
+    timer = setInterval(runSweep, intervalMs);
+    timer.unref?.();
+  }
+
+  function stop() {
+    if (!timer) return;
+    clearInterval(timer);
+    timer = null;
+  }
+
+  return Object.freeze({
+    registerWorkspaceProvider,
+    stagingRetention,
+    trackDirectory,
+    trackStaged,
+    sweepNow,
+    start,
+    resetSweepSchedule,
+    stop,
+  });
+}