triflux 10.44.0 → 10.45.0

package/hub/server.mjs

@@ -961,6 +961,7 @@ function servePublicFile(res, path) {
  * @param {string} [opts.host]
  * @param {string|number} [opts.sessionId]
  * @param {(options: { cwd: string }) => object} [opts.createDelegatorWorker]
+ * @param {(dbPath: string) => object|Promise<object>} [opts.createStoreAdapterFn] test seam
  */
 export async function startHub({
   port: portOpt,
@@ -968,6 +969,7 @@ export async function startHub({
   host = "127.0.0.1",
   sessionId = process.pid,
   createDelegatorWorker = createDelegatorMcpWorker,
+  createStoreAdapterFn = createStoreAdapter,
 } = {}) {
   const resolvedPort = parseHubPort(portOpt);
   const portSpecified = Number.isFinite(resolvedPort);
@@ -1062,7 +1064,7 @@ export async function startHub({
     cleanupOwnedTokenFile({ token: HUB_TOKEN, port });
   }
 
-  const store = await createStoreAdapter(dbPath);
+  const store = await createStoreAdapterFn(dbPath);
   const router = createRouter(store);
   const fingerprintService = createAdaptiveFingerprintService({ store });
 
@@ -1720,6 +1722,8 @@ export async function startHub({
               agent_id,
               reason = "manual",
               requested_by = "http",
+              hub_instance_id,
+              store_fingerprint,
             } = body;
             if (!role || !agent_id) {
               return writeJson(res, 400, {
@@ -1732,6 +1736,8 @@ export async function startHub({
               agent_id,
               reason,
               requested_by,
+              hub_instance_id,
+              store_fingerprint,
             });
             return writeJson(res, result.ok ? 200 : 409, result);
           }
@@ -1748,6 +1754,8 @@ export async function startHub({
               session_id,
               host_id,
               transport_locators_json,
+              hub_instance_id,
+              store_fingerprint,
             } = body;
             if (!agent_id || !cli) {
               return writeJson(res, 400, {
@@ -1782,6 +1790,8 @@ export async function startHub({
               ...(transport_locators_json === undefined
                 ? {}
                 : { transport_locators_json }),
+              ...(hub_instance_id === undefined ? {} : { hub_instance_id }),
+              ...(store_fingerprint === undefined ? {} : { store_fingerprint }),
             });
             if (result.ok) {
               workerSpans.set(agent_id, {
@@ -1816,7 +1826,13 @@ export async function startHub({
           }
 
           if (path === "/bridge/heartbeat" && req.method === "POST") {
-            const { agent_id, ttl_ms } = body;
+            const {
+              agent_id,
+              ttl_ms,
+              presence_generation,
+              hub_instance_id,
+              store_fingerprint,
+            } = body;
             if (!agent_id)
               return writeJson(res, 400, { ok: false, error: "agent_id 필수" });
             const result = await pipe.executeCommand("heartbeat", {
@@ -1825,6 +1841,9 @@ export async function startHub({
                 ttl_ms,
                 resolveWorkerLeaseTtlMs(),
               ),
+              presence_generation,
+              hub_instance_id,
+              store_fingerprint,
             });
             return writeJson(res, result.ok ? 200 : 404, result);
           }
@@ -1905,6 +1924,9 @@ export async function startHub({
               status,
               include_metrics = true,
               trace_id,
+              presence_generation,
+              hub_instance_id,
+              store_fingerprint,
             } = body;
 
             if (agent_id && status) {
@@ -1925,7 +1947,15 @@ export async function startHub({
               ]).has(normalizedStatus)
                 ? normalizedStatus
                 : "online";
-              router.updateAgentStatus(normalizedAgentId, statusForStore);
+              const transition = router.transitionAgentStatus(
+                normalizedAgentId,
+                statusForStore,
+                presence_generation,
+                { hub_instance_id, store_fingerprint },
+              );
+              if (!transition.ok) {
+                return writeJson(res, 409, transition);
+              }
               const snapshot = await pipe.executeQuery("status", {
                 scope: "agent",
                 agent_id: normalizedAgentId,
@@ -1939,6 +1969,8 @@ export async function startHub({
                   reported_status: normalizedStatus,
                   reported_at_ms: Date.now(),
                   snapshot: snapshot?.data?.agent || null,
+                  hub_instance_id: transition.data.hub_instance_id,
+                  store_fingerprint: transition.data.store_fingerprint,
                 },
               });
             }
@@ -1948,6 +1980,8 @@ export async function startHub({
               agent_id,
               include_metrics,
               trace_id,
+              hub_instance_id,
+              store_fingerprint,
             });
             return writeJson(res, 200, result);
           }
@@ -2167,12 +2201,20 @@ export async function startHub({
           }
 
           if (path === "/bridge/deregister" && req.method === "POST") {
-            const { agent_id } = body;
+            const {
+              agent_id,
+              presence_generation,
+              hub_instance_id,
+              store_fingerprint,
+            } = body;
             if (!agent_id) {
               return writeJson(res, 400, { ok: false, error: "agent_id 필수" });
             }
             const result = await pipe.executeCommand("deregister", {
               agent_id,
+              presence_generation,
+              hub_instance_id,
+              store_fingerprint,
             });
             if (result.ok) {
               finishWorkerTrace(agent_id, "deregister");
@@ -2316,102 +2358,107 @@ export async function startHub({
   httpServer.requestTimeout = 30000;
   httpServer.headersTimeout = 10000;
 
-  router.startSweeper();
+  let hitlTimer = null;
+  let sessionTimer = null;
+  let synapsePruneTimer = null;
+  let orphanCleanupTimer = null;
+  let rateLimitTimer = null;
 
-  const hitlTimer = setInterval(() => {
-    try {
-      hitl.checkTimeouts();
-    } catch (err) {
-      hubLog.warn({ err }, "hitl.timeout_check_failed");
-    }
-  }, 10000);
-  hitlTimer.unref();
-
-  // MCP session TTL: sessions idle for SESSION_TTL_MS are closed automatically.
-  // Configurable via SESSION_TTL_MS (default 30 minutes). The sweep runs every 60 s.
-  const SESSION_TTL_MS =
-    parseInt(process.env.TFX_SESSION_TTL_MS || "", 10) || 30 * 60 * 1000;
-  const sessionTimer = setInterval(() => {
-    const now = Date.now();
-    for (const [sid, session] of transports) {
-      if (now - (session.transport._lastActivity || 0) <= SESSION_TTL_MS)
-        continue;
-      void closeMcpTransportSession(sid, session, "session_ttl");
-    }
-  }, 60000);
-  sessionTimer.unref();
+  const startBackgroundTimers = () => {
+    hitlTimer = setInterval(() => {
+      try {
+        hitl.checkTimeouts();
+      } catch (err) {
+        hubLog.warn({ err }, "hitl.timeout_check_failed");
+      }
+    }, 10000);
+    hitlTimer.unref();
+
+    // MCP session TTL: sessions idle for SESSION_TTL_MS are closed automatically.
+    // Configurable via SESSION_TTL_MS (default 30 minutes). The sweep runs every 60 s.
+    const SESSION_TTL_MS =
+      parseInt(process.env.TFX_SESSION_TTL_MS || "", 10) || 30 * 60 * 1000;
+    sessionTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [sid, session] of transports) {
+        if (now - (session.transport._lastActivity || 0) <= SESSION_TTL_MS)
+          continue;
+        void closeMcpTransportSession(sid, session, "session_ttl");
+      }
+    }, 60000);
+    sessionTimer.unref();
 
-  const synapsePruneTimer = setInterval(() => {
-    try {
-      const { count } = synapseRegistry.pruneExpired();
-      if (count > 0) hubLog.info({ count }, "synapse.prune");
-    } catch (err) {
-      hubLog.warn({ err }, "synapse.prune_failed");
-    }
-  }, 60000);
-  synapsePruneTimer.unref();
-
-  // 고아 node.exe 프로세스 + stale spawn 세션 주기적 정리 (5분마다)
-  // TFX_DISABLE_ORPHAN_CLEANUP=1 로 비활성 (active SSH/swarm 세션 보호 회피용 hotfix gate)
-  const orphanCleanupTimer = setInterval(
-    () => {
-      if (process.env.TFX_DISABLE_ORPHAN_CLEANUP === "1") return;
+    synapsePruneTimer = setInterval(() => {
       try {
-        const { killed, killedProcesses = [] } = cleanupOrphanNodeProcesses();
-        const {
-          killed: runtimeKilled,
-          killedProcesses: runtimeKilledProcesses = [],
-        } = cleanupOrphanRuntimeProcesses();
-        const totalKilled = killed + runtimeKilled;
-        if (totalKilled > 0) {
-          hubLog.info(
-            {
-              killed: totalKilled,
-              processes: [...killedProcesses, ...runtimeKilledProcesses],
-              caller: "timer",
-            },
-            "hub.orphan_cleanup",
-          );
-        }
+        const { count } = synapseRegistry.pruneExpired();
+        if (count > 0) hubLog.info({ count }, "synapse.prune");
+      } catch (err) {
+        hubLog.warn({ err }, "synapse.prune_failed");
+      }
+    }, 60000);
+    synapsePruneTimer.unref();
+
+    // 고아 node.exe 프로세스 + stale spawn 세션 주기적 정리 (5분마다)
+    // TFX_DISABLE_ORPHAN_CLEANUP=1 로 비활성 (active SSH/swarm 세션 보호 회피용 hotfix gate)
+    orphanCleanupTimer = setInterval(
+      () => {
+        if (process.env.TFX_DISABLE_ORPHAN_CLEANUP === "1") return;
+        try {
+          const { killed, killedProcesses = [] } = cleanupOrphanNodeProcesses();
+          const {
+            killed: runtimeKilled,
+            killedProcesses: runtimeKilledProcesses = [],
+          } = cleanupOrphanRuntimeProcesses();
+          const totalKilled = killed + runtimeKilled;
+          if (totalKilled > 0) {
+            hubLog.info(
+              {
+                killed: totalKilled,
+                processes: [...killedProcesses, ...runtimeKilledProcesses],
+                caller: "timer",
+              },
+              "hub.orphan_cleanup",
+            );
+          }
 
-        const { killed: fsmonitorKilled, stale } = cleanupStaleFsmonitorDaemons(
-          {
-            minAgeMs: 24 * 60 * 60 * 1000,
-          },
-        );
-        if (fsmonitorKilled > 0) {
-          hubLog.info(
-            { killed: fsmonitorKilled, stale: stale.length },
-            "hub.fsmonitor_cleanup",
-          );
-        }
-      } catch {}
+          const { killed: fsmonitorKilled, stale } =
+            cleanupStaleFsmonitorDaemons({
+              minAgeMs: 24 * 60 * 60 * 1000,
+            });
+          if (fsmonitorKilled > 0) {
+            hubLog.info(
+              { killed: fsmonitorKilled, stale: stale.length },
+              "hub.fsmonitor_cleanup",
+            );
+          }
+        } catch {}
 
-      // stale tfx-spawn-* psmux 세션 정리 (30분 이상 idle)
-      try {
-        const staleKilled = cleanupStaleSpawnSessions(hubLog);
-        if (staleKilled > 0) {
-          hubLog.info({ killed: staleKilled }, "hub.stale_spawn_cleanup");
+        // stale tfx-spawn-* psmux 세션 정리 (30분 이상 idle)
+        try {
+          const staleKilled = cleanupStaleSpawnSessions(hubLog);
+          if (staleKilled > 0) {
+            hubLog.info({ killed: staleKilled }, "hub.stale_spawn_cleanup");
+          }
+        } catch {}
+      },
+      5 * 60 * 1000,
+    );
+    orphanCleanupTimer.unref();
+
+    // Evict stale rate-limit buckets once per minute to bound memory usage.
+    rateLimitTimer = setInterval(() => {
+      const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS;
+      for (const [ip, timestamps] of rateLimitMap) {
+        const fresh = timestamps.filter((t) => t >= cutoff);
+        if (fresh.length === 0) {
+          rateLimitMap.delete(ip);
+        } else {
+          rateLimitMap.set(ip, fresh);
         }
-      } catch {}
-    },
-    5 * 60 * 1000,
-  );
-  orphanCleanupTimer.unref();
-
-  // Evict stale rate-limit buckets once per minute to bound memory usage.
-  const rateLimitTimer = setInterval(() => {
-    const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS;
-    for (const [ip, timestamps] of rateLimitMap) {
-      const fresh = timestamps.filter((t) => t >= cutoff);
-      if (fresh.length === 0) {
-        rateLimitMap.delete(ip);
-      } else {
-        rateLimitMap.set(ip, fresh);
       }
-    }
-  }, RATE_LIMIT_WINDOW_MS);
-  rateLimitTimer.unref();
+    }, RATE_LIMIT_WINDOW_MS);
+    rateLimitTimer.unref();
+  };
 
   mkdirSync(PID_DIR, { recursive: true });
 
@@ -2419,6 +2466,19 @@ export async function startHub({
     try {
       router.stopSweeper();
     } catch {}
+    for (const timer of [
+      hitlTimer,
+      sessionTimer,
+      synapsePruneTimer,
+      orphanCleanupTimer,
+      rateLimitTimer,
+    ]) {
+      if (timer) clearInterval(timer);
+    }
+    for (const [sid, session] of Array.from(transports)) {
+      await closeMcpTransportSession(sid, session, "hub.startup_failure");
+    }
+    transports.clear();
     try {
       await pipe.stop();
     } catch {}
@@ -2428,6 +2488,9 @@ export async function startHub({
     try {
       await delegatorWorker.stop();
     } catch {}
+    try {
+      synapseRegistry.destroy();
+    } catch {}
     try {
       store.close();
     } catch {}
@@ -2438,6 +2501,22 @@ export async function startHub({
   };
 
   try {
+    router.sweepExpired({ now_ms: Date.now(), source: "startup" });
+    router.startSweeper({
+      run_immediately: false,
+      interval_ms: 10000,
+      onSweepError: ({ source, error, consecutive_failures }) => {
+        hubLog.warn(
+          {
+            source,
+            code: error?.code || "UNKNOWN",
+            consecutive_failures,
+          },
+          "hub.sweep_failed",
+        );
+      },
+    });
+    startBackgroundTimers();
     await pipe.start();
     await assignCallbacks.start();
   } catch (error) {

package/hub/store.mjs

@@ -1,6 +1,7 @@
 // hub/store.mjs — SQLite 감사 로그/메타데이터/역할 레지스트리 저장소
 // 실시간 배달은 router/pipe가 담당하고, 역할 권한과 복구 상태는 SQLite가 보존한다.
 
+import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
@@ -119,6 +120,21 @@ function ensureV6Columns(db) {
   }
 }
 
+function ensureV7Columns(db) {
+  if (hasTable(db, "agents")) {
+    ensureColumn(
+      db,
+      "agents",
+      "presence_generation",
+      "INTEGER NOT NULL DEFAULT 0",
+    );
+  }
+}
+
+function storeFingerprint(dbPath) {
+  return `sqlite:${createHash("sha256").update(String(dbPath)).digest("hex")}`;
+}
+
 /**
  * 저장소 생성
  * @param {string} dbPath
@@ -149,7 +165,7 @@ export function createStore(dbPath, options = {}) {
   db.exec(
     "CREATE TABLE IF NOT EXISTS _meta (key TEXT PRIMARY KEY, value TEXT)",
   );
-  const SCHEMA_VERSION = "6";
+  const SCHEMA_VERSION = "7";
   const curVer = (() => {
     try {
       return db
@@ -166,6 +182,7 @@ export function createStore(dbPath, options = {}) {
   // v5 테이블에는 schema.sql의 v6 인덱스가 참조하는 컬럼이 없으므로
   // CREATE IF NOT EXISTS 재실행 전에 멱등 컬럼 seam을 먼저 적용한다.
   ensureV6Columns(db);
+  ensureV7Columns(db);
   if (curVer !== SCHEMA_VERSION) {
     if (curVer != null) {
       // 이미 버전이 기록된 DB에서 버전 불일치가 발생한 경우 경고한다.
@@ -180,6 +197,7 @@ export function createStore(dbPath, options = {}) {
   }
   // 매 부팅 실행해 부분 적용된 마이그레이션도 안전하게 복구한다.
   ensureV6Columns(db);
+  ensureV7Columns(db);
   ensureColumn(
     db,
     "reflexion_entries",
@@ -196,8 +214,8 @@ export function createStore(dbPath, options = {}) {
 
   const S = {
     upsertAgent: db.prepare(`
-      INSERT INTO agents (agent_id, cli, pid, capabilities_json, topics_json, last_seen_ms, lease_expires_ms, status, metadata_json)
-      VALUES (@agent_id, @cli, @pid, @capabilities_json, @topics_json, @last_seen_ms, @lease_expires_ms, @status, @metadata_json)
+      INSERT INTO agents (agent_id, cli, pid, capabilities_json, topics_json, last_seen_ms, lease_expires_ms, presence_generation, status, metadata_json)
+      VALUES (@agent_id, @cli, @pid, @capabilities_json, @topics_json, @last_seen_ms, @lease_expires_ms, 1, @status, @metadata_json)
       ON CONFLICT(agent_id) DO UPDATE SET
         cli=excluded.cli,
         pid=excluded.pid,
@@ -205,6 +223,7 @@ export function createStore(dbPath, options = {}) {
         topics_json=excluded.topics_json,
         last_seen_ms=excluded.last_seen_ms,
         lease_expires_ms=excluded.lease_expires_ms,
+        presence_generation=agents.presence_generation + 1,
         status=excluded.status,
         metadata_json=excluded.metadata_json`),
     getAgent: db.prepare("SELECT * FROM agents WHERE agent_id = ?"),
@@ -212,19 +231,27 @@ export function createStore(dbPath, options = {}) {
       "UPDATE agents SET topics_json=?, last_seen_ms=? WHERE agent_id=?",
     ),
     heartbeat: db.prepare(
+      "UPDATE agents SET last_seen_ms=?, lease_expires_ms=?, status='online' WHERE agent_id=? AND presence_generation=?",
+    ),
+    heartbeatWithoutGeneration: db.prepare(
       "UPDATE agents SET last_seen_ms=?, lease_expires_ms=?, status='online' WHERE agent_id=?",
     ),
-    setAgentStatus: db.prepare("UPDATE agents SET status=? WHERE agent_id=?"),
+    setAgentStatus: db.prepare(
+      "UPDATE agents SET status=? WHERE agent_id=? AND presence_generation=?",
+    ),
+    setAgentStatusWithoutGeneration: db.prepare(
+      "UPDATE agents SET status=? WHERE agent_id=?",
+    ),
     onlineAgents: db.prepare("SELECT * FROM agents WHERE status != 'offline'"),
     allAgents: db.prepare("SELECT * FROM agents"),
     agentsByTopic: db.prepare(
       "SELECT a.* FROM agents a, json_each(a.topics_json) t WHERE t.value=? AND a.status != 'offline'",
     ),
     markStale: db.prepare(
-      "UPDATE agents SET status='stale' WHERE status='online' AND lease_expires_ms < ?",
+      "UPDATE agents SET status='stale' WHERE agent_id=? AND presence_generation=? AND status='online' AND lease_expires_ms < ?",
     ),
     markOffline: db.prepare(
-      "UPDATE agents SET status='offline' WHERE status='stale' AND lease_expires_ms < ? - 300000",
+      "UPDATE agents SET status='offline' WHERE agent_id=? AND presence_generation=? AND status='stale' AND lease_expires_ms < ? - 300000",
     ),
 
     getRole: db.prepare("SELECT * FROM role_registry WHERE role_key_wire = ?"),
@@ -412,12 +439,9 @@ export function createStore(dbPath, options = {}) {
       "UPDATE human_requests SET state=?, response_json=? WHERE request_id=?",
     ),
     pendingHR: db.prepare("SELECT * FROM human_requests WHERE state='pending'"),
-    expireHR: db.prepare(
-      "UPDATE human_requests SET state='timed_out' WHERE state='pending' AND deadline_ms < ?",
-    ),
 
     insertDL: db.prepare(
-      "INSERT OR REPLACE INTO dead_letters (message_id, reason, failed_at_ms, last_error) VALUES (?,?,?,?)",
+      "INSERT INTO dead_letters (message_id, reason, failed_at_ms, last_error) VALUES (?,?,?,?) ON CONFLICT(message_id) DO NOTHING",
     ),
     getDL: db.prepare(
       "SELECT * FROM dead_letters ORDER BY failed_at_ms DESC LIMIT ?",
@@ -464,7 +488,13 @@ export function createStore(dbPath, options = {}) {
       WHERE job_id=@job_id`),
 
     findExpired: db.prepare(
-      "SELECT id FROM messages WHERE status='queued' AND expires_at_ms < ?",
+      "SELECT * FROM messages WHERE status IN ('queued', 'delivered') AND expires_at_ms <= ?",
+    ),
+    claimExpired: db.prepare(
+      "UPDATE messages SET status='dead_letter' WHERE id=? AND status IN ('queued', 'delivered') AND expires_at_ms <= ?",
+    ),
+    claimDeadLetter: db.prepare(
+      "UPDATE messages SET status='dead_letter' WHERE id=? AND status != 'dead_letter'",
     ),
     urgentDepth: db.prepare(
       "SELECT COUNT(*) as cnt FROM messages WHERE status='queued' AND priority >= 7",
@@ -705,6 +735,8 @@ export function createStore(dbPath, options = {}) {
 
   const store = {
     db,
+    type: "sqlite",
+    fingerprint: storeFingerprint(dbPath),
     uuidv7,
 
     close() {
@@ -738,6 +770,7 @@ export function createStore(dbPath, options = {}) {
       return {
         agent_id,
         lease_id: leaseId,
+        presence_generation: persisted?.presence_generation ?? null,
         lease_expires_ms: leaseExpires,
         server_time_ms: now,
         effective: {
@@ -750,6 +783,7 @@ export function createStore(dbPath, options = {}) {
           lease_expires_ms: persisted?.lease_expires_ms ?? null,
           store_type: "sqlite",
           db_path: dbPath ?? null,
+          store_fingerprint: storeFingerprint(dbPath),
         },
       };
     },
@@ -758,9 +792,12 @@ export function createStore(dbPath, options = {}) {
       return parseAgentRow(S.getAgent.get(id));
     },
 
-    refreshLease(agentId, ttlMs = 30000) {
+    refreshLease(agentId, ttlMs = 30000, presenceGeneration) {
       const now = Date.now();
-      const write = S.heartbeat.run(now, now + ttlMs, agentId);
+      const write =
+        presenceGeneration == null
+          ? S.heartbeatWithoutGeneration.run(now, now + ttlMs, agentId)
+          : S.heartbeat.run(now, now + ttlMs, agentId, presenceGeneration);
       return {
         agent_id: agentId,
         lease_expires_ms: now + ttlMs,
@@ -769,6 +806,7 @@ export function createStore(dbPath, options = {}) {
           updated: write.changes > 0,
           store_type: "sqlite",
           db_path: dbPath ?? null,
+          store_fingerprint: storeFingerprint(dbPath),
         },
       };
     },
@@ -794,14 +832,40 @@ export function createStore(dbPath, options = {}) {
 
     sweepStaleAgents() {
       const now = Date.now();
+      const candidates = S.allAgents.all();
+      let stale = 0;
+      let offline = 0;
+      for (const candidate of candidates) {
+        if (candidate.status === "online" && candidate.lease_expires_ms < now) {
+          stale += S.markStale.run(
+            candidate.agent_id,
+            candidate.presence_generation,
+            now,
+          ).changes;
+        } else if (
+          candidate.status === "stale" &&
+          candidate.lease_expires_ms < now - 300000
+        ) {
+          offline += S.markOffline.run(
+            candidate.agent_id,
+            candidate.presence_generation,
+            now,
+          ).changes;
+        }
+      }
       return {
-        stale: S.markStale.run(now).changes,
-        offline: S.markOffline.run(now).changes,
+        stale,
+        offline,
       };
     },
 
-    updateAgentStatus(agentId, status) {
-      return S.setAgentStatus.run(status, agentId).changes > 0;
+    updateAgentStatus(agentId, status, presenceGeneration) {
+      return (
+        (presenceGeneration == null
+          ? S.setAgentStatusWithoutGeneration.run(status, agentId)
+          : S.setAgentStatus.run(status, agentId, presenceGeneration)
+        ).changes > 0
+      );
     },
 
     getRole(roleKeyWire) {
@@ -1179,16 +1243,14 @@ export function createStore(dbPath, options = {}) {
       return S.pendingHR.all().map(parseHumanRequestRow);
     },
 
-    expireHumanRequests() {
-      return S.expireHR.run(Date.now()).changes;
-    },
-
     moveToDeadLetter(messageId, reason, lastError = null) {
-      db.transaction(() => {
-        S.setMsgStatus.run("dead_letter", messageId);
-        S.insertDL.run(messageId, reason, Date.now(), lastError);
+      const failedAt = Date.now();
+      return db.transaction(() => {
+        const changed = S.claimDeadLetter.run(messageId).changes;
+        if (!changed) return false;
+        S.insertDL.run(messageId, reason, failedAt, lastError);
+        return true;
       })();
-      return true;
     },
 
     getDeadLetters(limit = 50) {
@@ -1458,16 +1520,27 @@ export function createStore(dbPath, options = {}) {
       });
     },
 
-    sweepExpired() {
-      const now = Date.now();
+    sweepExpired({ now_ms = Date.now() } = {}) {
       return db.transaction(() => {
-        const expired = S.findExpired.all(now);
-        for (const { id } of expired) {
-          S.setMsgStatus.run("dead_letter", id);
-          S.insertDL.run(id, "ttl_expired", now, null);
+        const transitions = [];
+        for (const row of S.findExpired.all(now_ms)) {
+          if (!S.claimExpired.run(row.id, now_ms).changes) continue;
+          options.beforeDeadLetterInsert?.({
+            message_id: row.id,
+            reason: "ttl_expired",
+            failed_at_ms: now_ms,
+          });
+          const dlqInserted =
+            S.insertDL.run(row.id, "ttl_expired", now_ms, null).changes === 1;
+          transitions.push({
+            message: parseMessageRow(row),
+            previous_status: row.status,
+            reason: "ttl_expired",
+            failed_at_ms: now_ms,
+            dlq_inserted: dlqInserted,
+          });
         }
-        const humanRequests = S.expireHR.run(now).changes;
-        return { messages: expired.length, human_requests: humanRequests };
+        return { now_ms, messages: transitions.length, transitions };
       })();
     },