@shawnstack/quickforge 1.7.10 → 1.7.12

package/server/agent-manager.mjs

@@ -28,8 +28,8 @@ import {
   validateModelReference,
 } from './agent-profile-schema.mjs'
 import { projectContextFromId, defaultGlobalWorkspaceContext, readProjectConfig } from './project-config.mjs'
-import { ensureStorage, readStore, atomicUpdate, atomicSessionMetadataUpdate, readSessionValue, writeSessionValue, deleteSessionValue, tempAgentsDir } from './storage.mjs'
-import { isSessionStateAuthoritative, readSessionStateRecord, saveSessionStatePair, deleteSessionState, storedMessagesState, sessionMessagesTailDigest } from './session-state-service.mjs'
+import { ensureStorage, readStore, atomicUpdate, readSessionValue, tempAgentsDir } from './storage.mjs'
+import { readSessionStateRecord, saveSessionStatePair, deleteSessionState, storedMessagesState, sessionMessagesTailDigest } from './session-state-service.mjs'
 import { logger } from './utils/logger.mjs'
 import { publishChannelSessionChanged } from './channels/event-relay.mjs'
 import { withSessionPersistenceLock } from './session-persistence-lock.mjs'
@@ -68,6 +68,15 @@ import {
   commandToolPermissionError,
   createCommandToolPermissions,
 } from './approval-store.mjs'
+import {
+  ASK_TIMEOUT_MS,
+  pendingAsks,
+  getPendingAskForSession,
+  normalizeAskQuestions,
+  formatAskResult,
+} from './ask-store.mjs'
+
+export { getPendingAskForSession, normalizeAskQuestions } from './ask-store.mjs'
 
 // ---------------------------------------------------------------------------
 // Tool definitions (server-side, no REST roundtrip)
@@ -88,8 +97,25 @@ function wrapSubagentToolDefinition(definition, parentSessionId) {
   }
 }
 
+function wrapAskUserToolDefinition(definition, parentSessionId) {
+  return {
+    ...definition,
+    execute: async (toolCallId, params) => {
+      const session = agentSessions.get(parentSessionId)
+      if (!session) {
+        return {
+          content: [{ type: 'text', text: 'No active session for ask_user.' }],
+          details: { askId: null, skipped: true },
+        }
+      }
+      return createAskUserPromise(session, toolCallId, params || {})
+    },
+  }
+}
+
 function wrapWorkspaceToolDefinition(definition, context, toolPermissions, options = {}) {
   if (definition.name === 'run_subagent') return wrapSubagentToolDefinition(definition, options.parentSessionId)
+  if (definition.name === 'ask_user') return wrapAskUserToolDefinition(definition, options.parentSessionId)
   return wrapToolDefinition(definition, context, toolPermissions)
 }
 
@@ -304,8 +330,83 @@ function createApprovalPromise(session, toolCallId, toolName, args, source) {
   })
 }
 
-function createAcpApprovalPromise(session, request) {
-  return new Promise((resolve, reject) => {
+/**
+ * Create a Promise that resolves when the user answers (or skips) an ask_user
+ * tool call. The tool's execute blocks on this promise, pausing the agent loop
+ * until the user responds.
+ */
+function createAskUserPromise(session, toolCallId, params) {
+  const questions = normalizeAskQuestions(params)
+  if (!questions.length) {
+    return Promise.resolve({
+      content: [{ type: 'text', text: formatAskResult(questions, null, true, 'no-questions') }],
+      details: { askId: null, skipped: true },
+    })
+  }
+  const askId = randomUUID()
+  return new Promise((resolve) => {
+    let settled = false
+    const requestedAt = Date.now()
+    const expiresAt = requestedAt + ASK_TIMEOUT_MS
+
+    const timeout = setTimeout(() => {
+      if (settled) return
+      finish({ skipped: true, reason: 'timeout' })
+    }, ASK_TIMEOUT_MS)
+
+    let onAbort = null
+
+    const finish = (payload) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      if (onAbort && session.agent.signal) session.agent.signal.removeEventListener('abort', onAbort)
+      pendingAsks.delete(askId)
+      const answers = payload.skipped ? null : payload.answers
+      resolve({
+        content: [{ type: 'text', text: formatAskResult(questions, answers, payload.skipped, payload.reason) }],
+        details: { askId, questions, answers, skipped: !!payload.skipped, ...(payload.reason ? { skipReason: payload.reason } : {}) },
+      })
+      emitSessionEvent(session, {
+        type: 'ask_user_answered',
+        sessionId: session.sessionId,
+        askId,
+        toolCallId,
+        skipped: !!payload.skipped,
+        answers: answers || [],
+      })
+    }
+
+    const signal = session.agent.signal
+    if (signal) {
+      if (signal.aborted) {
+        finish({ skipped: true, reason: 'aborted' })
+        return
+      }
+      onAbort = () => finish({ skipped: true, reason: 'aborted' })
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    pendingAsks.set(askId, {
+      finish: (payload) => finish(payload),
+      sessionId: session.sessionId,
+      toolCallId,
+      questions,
+      requestedAt,
+      expiresAt,
+    })
+
+    emitSessionEvent(session, {
+      type: 'ask_user_required',
+      sessionId: session.sessionId,
+      askId,
+      toolCallId,
+      questions,
+    })
+  })
+}
+
+function createAcpApprovalPromise(session, request) {  return new Promise((resolve, reject) => {
     let settled = false
     const requestedAt = Date.now()
     const expiresAt = requestedAt + APPROVAL_TIMEOUT_MS
@@ -1880,6 +1981,8 @@ export async function createAgent(sessionId, config = {}) {
       if (commandPermissionError) return { block: true, reason: commandPermissionError }
       const isSkillTool = toolName === 'activate_skill' || toolName === 'read_skill_resource'
       if (isSkillTool) return undefined
+      // ask_user only waits for the user's answer; it changes nothing and needs no approval.
+      if (toolName === 'ask_user') return undefined
       if (profileToolNames && !profileToolNames.includes(toolName)) return { block: true, reason: `Agent profile ${agentProfile.name} is not allowed to use ${toolName}.` }
       if (toolName === 'manage_global_memory') return undefined
       if (toolName === 'run_subagent') {
@@ -1967,6 +2070,10 @@ export async function createAgent(sessionId, config = {}) {
     persistedMessageCount: Number.isInteger(config.persistedMessageCount) && config.persistedMessageCount >= 0 ? config.persistedMessageCount : null,
     persistedTailDigest: typeof config.persistedTailDigest === 'string' ? config.persistedTailDigest : null,
     persistConflictCount: 0,
+    // Set when an authoritative persist is skipped after CAS conflicts; cleared
+    // on the next successful persist. Surfaced via getSessionState/getSessionStatus
+    // so the UI can warn the user instead of silently losing messages.
+    persistDegraded: null,
     lastAutoCompactAt: null,
     lastAutoCompactRejected: null,
     memoryEnabled: initialMemoryEnabled,
@@ -2153,6 +2260,26 @@ function canonicalStateJson(value) {
   return JSON.stringify(value)
 }
 
+/**
+ * Mark the session as persist-degraded (an authoritative persist was skipped
+ * after CAS conflicts) and notify connected clients so the UI can surface a
+ * non-blocking warning instead of silently losing messages.
+ */
+function markPersistDegraded(session, attempts) {
+  session.persistDegraded = { at: new Date().toISOString(), attempts }
+  emitSessionEvent(session, { type: 'persist_degraded', persistDegraded: true })
+}
+
+/**
+ * Clear the degraded marker after a successful persist and notify clients so
+ * the UI warning disappears.
+ */
+function clearPersistDegraded(session) {
+  if (!session.persistDegraded) return
+  session.persistDegraded = null
+  emitSessionEvent(session, { type: 'persist_degraded', persistDegraded: false })
+}
+
 /**
  * Persist a full session record in one authoritative SQLite transaction with
  * revision CAS. When the CAS fails because a concurrent metadata-only change
@@ -2201,6 +2328,7 @@ async function persistAuthoritativeSessionState(session, sessionData, metadata)
         session.persistedMessageCount = Array.isArray(sessionData.messages) ? sessionData.messages.length : 0
       }
       session.persistedTailDigest = sessionMessagesTailDigest(sessionData.messages)
+      clearPersistDegraded(session)
       return { ...saved, metadata: mergedMetadata }
     } catch (error) {
       if (error?.errorCode !== 'SESSION_STATE_CONFLICT') throw error
@@ -2222,11 +2350,13 @@ async function persistAuthoritativeSessionState(session, sessionData, metadata)
       }
       session.persistConflictCount += 1
       logger.warn(`Session ${sessionId} persist conflict: storage changed agent-owned fields; skipping overwrite`, { sessionId })
+      markPersistDegraded(session, attempt)
       return null
     }
   }
   session.persistConflictCount += 1
   logger.warn(`Session ${sessionId} persist still conflicting after ${maxAttempts} merge retries`, { sessionId, reason: lastConflict?.message })
+  markPersistDegraded(session, maxAttempts)
   return null
 }
 
@@ -2239,14 +2369,7 @@ async function persistSessionUnlocked(session) {
 
   if (messages.length === 0) {
     try {
-      if (isSessionStateAuthoritative()) deleteSessionState(sessionId, { expectedRevision: session.persistedStorageRevision })
-      else {
-        await deleteSessionValue(sessionId)
-        await atomicSessionMetadataUpdate(scope, projectId, (data) => {
-          delete data[sessionId]
-          return data
-        })
-      }
+      deleteSessionState(sessionId, { expectedRevision: session.persistedStorageRevision })
       session.persistedStorageRevision = null
       session.persistedStateVersion = null
       session.persistedStateJson = null
@@ -2353,34 +2476,14 @@ async function persistSessionUnlocked(session) {
     idleRetention: session.idleRetention || undefined,
   }
 
-  // Write body + metadata as one authoritative SQLite transaction after cutover.
+  // Write body + metadata as one authoritative SQLite transaction.
   let persistedMetadata
   try {
-    if (isSessionStateAuthoritative()) {
-      const saved = await persistAuthoritativeSessionState(session, sessionData, metadata)
-      if (!saved) return null
-      session.persistedStorageRevision = saved.revision
-      session.persistedStateVersion = saved.stateVersion
-      persistedMetadata = saved.metadata
-    } else {
-      await writeSessionValue(sessionId, sessionData)
-      await atomicSessionMetadataUpdate(scope, projectId, (data) => {
-        const existingMetadata = data[sessionId]
-        const archivedAt = existingMetadata?.archivedAt
-        // Merge onto the existing record so storage-only fields the in-memory
-        // session does not own (pinnedAt, archivedAt, …) survive the rebuild.
-        persistedMetadata = {
-          ...existingMetadata,
-          ...metadata,
-          ...(archivedAt ? { archivedAt } : {}),
-        }
-        data[sessionId] = persistedMetadata
-        return data
-      })
-      if (persistedMetadata?.archivedAt) {
-        await writeSessionValue(sessionId, { ...sessionData, archivedAt: persistedMetadata.archivedAt })
-      }
-    }
+    const saved = await persistAuthoritativeSessionState(session, sessionData, metadata)
+    if (!saved) return null
+    session.persistedStorageRevision = saved.revision
+    session.persistedStateVersion = saved.stateVersion
+    persistedMetadata = saved.metadata
   } catch (err) {
     logger.error(`Failed to persist session ${sessionId}:`, err, { sessionId })
     return null
@@ -2410,11 +2513,10 @@ const SLOW_PERSIST_LOG_MS = 1_000
 
 async function persistSession(session) {
   const startedAt = performance.now()
-  // Serialize per session once SQLite state is authoritative (per-row revision
-  // CAS guarantees correctness); cross-session persists then run independently
-  // instead of piling onto one global chain that also gates destroyAgent.
-  // JSON-mirror mode keeps the global lock for bucket-level atomicity.
-  const lockKey = isSessionStateAuthoritative() ? `session:${session.sessionId}` : ''
+  // Serialize per session (per-row revision CAS guarantees correctness);
+  // cross-session persists run independently instead of piling onto one
+  // global chain that also gates destroyAgent.
+  const lockKey = `session:${session.sessionId}`
   const result = await withSessionPersistenceLock(() => persistSessionUnlocked(session), lockKey)
   const durationMs = performance.now() - startedAt
   if (durationMs >= SLOW_PERSIST_LOG_MS) {
@@ -2973,9 +3075,11 @@ export function getSessionState(sessionId) {
     contextUsage: getSessionContextUsage(session),
     pendingToolApproval: getPendingApprovalForSession(session.sessionId),
     pendingAutoCompactApproval: getPendingAutoCompactApprovalForSession(session.sessionId),
+    pendingAsk: getPendingAskForSession(session.sessionId),
     acpSession: session.harness === AGENT_HARNESS_OPENCODE ? session.agent.state.acpSession : undefined,
     isStreaming: session.abortPending ? false : session.agent.state.isStreaming,
     errorMessage: session.agent.state.errorMessage,
+    persistDegraded: session.persistDegraded ? true : undefined,
   }
 }
 
@@ -3008,6 +3112,7 @@ export function getSessionStatus(sessionId) {
     errorMessage: session.agent.state.errorMessage,
     messageCount: messages.length,
     lastMessageTimestamp: lastMessage?.timestamp ?? null,
+    persistDegraded: session.persistDegraded ? true : undefined,
   }
 }
 
@@ -3039,6 +3144,21 @@ export function releaseSse(sessionId) {
   if (session) session.sseConnected = false
 }
 
+/**
+ * Count sessions with a live SSE connection — the background-migration idle
+ * signal's "no active stream" input
+ * (docs/architecture/session-storage-background-migration-design.zh-CN.md
+ * §3.3). Derived from the per-session sseConnected flags the SSE route
+ * already maintains, so no extra bookkeeping is required.
+ */
+export function countActiveSseStreams() {
+  let count = 0
+  for (const session of agentSessions.values()) {
+    if (session.sseConnected) count += 1
+  }
+  return count
+}
+
 /**
  * Get the event bus for a session (for SSE connections).
  */
@@ -3128,8 +3248,8 @@ async function restoreAgentUnlocked(sessionId) {
     // Read the authoritative storage record once: the body (split marker),
     // revision for CAS, and the stored message rows (count + tail digest) used
     // for split-representation conflict detection after restore.
-    const record = isSessionStateAuthoritative() ? readSessionStateRecord(sessionId) : null
-    const storedMessages = isSessionStateAuthoritative() && record?.state?.messageStorage === 'split'
+    const record = readSessionStateRecord(sessionId)
+    const storedMessages = record?.state?.messageStorage === 'split'
       ? storedMessagesState(sessionId)
       : null
 
@@ -3156,9 +3276,9 @@ async function restoreAgentUnlocked(sessionId) {
       openCodeUsage: sessionData.openCodeUsage || null,
       idleRetention: sessionData.idleRetention || null,
       stateVersion: sessionData.stateVersion,
-      persistedStateVersion: isSessionStateAuthoritative() ? sessionData.stateVersion : null,
-      persistedStorageRevision: isSessionStateAuthoritative() ? record?.revision ?? null : null,
-      persistedStateJson: isSessionStateAuthoritative() ? canonicalStateJson(stripStorageOwnedStateFields(record?.state || {})) : null,
+      persistedStateVersion: sessionData.stateVersion,
+      persistedStorageRevision: record?.revision ?? null,
+      persistedStateJson: canonicalStateJson(stripStorageOwnedStateFields(record?.state || {})),
       persistedMessageStorage: record?.state?.messageStorage === 'split' ? 'split' : null,
       persistedMessageCount: storedMessages?.count ?? (Array.isArray(sessionData.messages) ? sessionData.messages.length : 0),
       persistedTailDigest: storedMessages?.tailDigest || sessionMessagesTailDigest(sessionData.messages),
@@ -3212,6 +3332,30 @@ export function rejectAutoCompact(sessionId, approvalId) {
   return { rejected: true, approvalId }
 }
 
+/**
+ * Resolve a pending ask_user call with the user's answers (or a skip).
+ * `answers` is an array aligned with the ask's questions:
+ * `[{ choices: string[], custom?: string }]`.
+ */
+export function answerAsk(sessionId, askId, { answers, skipped = false } = {}) {
+  const ask = pendingAsks.get(askId)
+  if (!ask || ask.sessionId !== sessionId) {
+    throw Object.assign(new Error('No pending ask for this session'), { statusCode: 404 })
+  }
+  const normalizedAnswers = (Array.isArray(answers) ? answers : []).slice(0, ask.questions.length).map((answer) => ({
+    choices: (Array.isArray(answer?.choices) ? answer.choices : [])
+      .filter((choice) => typeof choice === 'string')
+      .map((choice) => choice.slice(0, 500))
+      .slice(0, 8),
+    ...(typeof answer?.custom === 'string' && answer.custom.trim()
+      ? { custom: answer.custom.slice(0, 4000) }
+      : {}),
+  }))
+  if (skipped) ask.finish({ skipped: true })
+  else ask.finish({ answers: normalizedAnswers })
+  return { answered: true, askId, skipped: !!skipped }
+}
+
 export function abortToolCall(sessionId, toolCallId) {
   const session = agentSessions.get(sessionId)
   if (!session) {

package/server/approval-store.mjs

@@ -31,6 +31,7 @@ export const planAllowedTools = new Set([
   'activate_skill',
   'read_skill_resource',
   'run_subagent',
+  'ask_user',
 ])
 
 export const safeReadTools = new Set([

package/server/ask-store.mjs

@@ -0,0 +1,78 @@
+/**
+ * Ask-user store — shared pending-question state.
+ *
+ * The Promise-based ask flow (createAskUserPromise) lives in agent-manager.mjs
+ * because it depends on the agent event buses; this module only holds the
+ * pending queue, mirroring approval-store.mjs.
+ */
+
+// Waiting for a user decision is not a security gate — allow generous time
+// before resolving as skipped so the agent can continue on its own.
+export const ASK_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes
+
+/** askId → { finish, sessionId, toolCallId, questions, requestedAt, expiresAt } */
+export const pendingAsks = new Map()
+
+export function getPendingAskForSession(sessionId) {
+  for (const [askId, ask] of pendingAsks) {
+    if (ask.sessionId === sessionId) {
+      return {
+        askId,
+        toolCallId: ask.toolCallId,
+        questions: ask.questions,
+        requestedAt: ask.requestedAt,
+        expiresAt: ask.expiresAt,
+      }
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (no dependencies — unit-tested directly)
+// ---------------------------------------------------------------------------
+
+/** Normalize ask_user params into a bounded questions list (robust against model shorthand). */
+export function normalizeAskQuestions(params) {
+  const rawQuestions = Array.isArray(params?.questions)
+    ? params.questions
+    : (typeof params?.question === 'string' ? [{ ...params }] : [])
+  return rawQuestions
+    .filter((q) => q && typeof q.question === 'string' && q.question.trim())
+    .slice(0, 4)
+    .map((q) => ({
+      question: String(q.question),
+      multiSelect: q.multiSelect === true,
+      allowCustom: q.allowCustom === false ? false : true,
+      options: (Array.isArray(q.options) ? q.options : [])
+        .filter((option) => option && typeof option.label === 'string' && option.label.trim())
+        .slice(0, 4)
+        .map((option) => ({
+          label: String(option.label),
+          ...(typeof option.description === 'string' && option.description ? { description: option.description } : {}),
+        })),
+    }))
+}
+
+/** Render the tool-result text returned to the model. */
+export function formatAskResult(questions, answers, skipped, reason) {
+  if (skipped) {
+    const note = reason === 'timeout'
+      ? '（等待超时）'
+      : reason === 'aborted'
+        ? '（运行被停止）'
+        : reason === 'no-questions'
+          ? '（问题列表无效）'
+          : '（用户跳过）'
+    return `用户没有回答这些问题${note}。请按你的默认方案继续，不要再重复追问。`
+  }
+  const lines = questions.map((q, index) => {
+    const answer = answers?.[index]
+    if (!answer) return `${index + 1}. ${q.question} → 用户未回答`
+    const choiceText = Array.isArray(answer.choices) && answer.choices.length ? answer.choices.join('、') : ''
+    const customText = typeof answer.custom === 'string' && answer.custom.trim() ? answer.custom.trim() : ''
+    const text = [choiceText, customText].filter(Boolean).join('　补充：')
+    return `${index + 1}. ${q.question} → ${text || '用户未回答'}`
+  })
+  return `用户的回答：\n${lines.join('\n')}`
+}

package/server/auto-archive.mjs

@@ -7,10 +7,20 @@ const defaultStorage = { atomicSessionValueUpdate, atomicUpdate, atomicSessionRe
 export const AUTO_ARCHIVE_SETTINGS_KEY = 'auto-archive-settings'
 export const AUTO_ARCHIVE_AFTER_MS = 30 * 24 * 60 * 60 * 1000
 const AUTO_ARCHIVE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+export const AUTO_ARCHIVE_INITIAL_DELAY_MS = 30_000
 
 let autoArchiveTimer = null
+let autoArchiveInitialTimer = null
 let autoArchiveRunning = false
 
+// Yield one macrotask turn between heavy archive commits: each archive is a
+// synchronous SQLite transaction (or JSON read-modify-write) that blocks the
+// thread while it runs, and without yields a large batch of back-to-back
+// archives starves every pending HTTP request for the whole batch.
+function yieldToEventLoop() {
+  return new Promise((resolve) => setImmediate(resolve))
+}
+
 export function normalizeAutoArchiveSettings(value) {
   if (!value || typeof value !== 'object') return { enabled: false }
   return { enabled: value.enabled === true }
@@ -65,8 +75,25 @@ async function archiveInactiveSessionsUnlocked(options = {}) {
   const metadataStore = await storage.readStore('sessions-metadata')
   const candidates = []
 
+  // Metadata-first scan: metadata alone decides activeness whenever it carries
+  // any timestamp, so the common case never loads the session body (loading and
+  // JSON.parsing every 2.9GB-library body is what stalled the event loop for
+  // ~minutes on startup). The body is only read when metadata has no usable
+  // timestamp at all. The scan is therefore deliberately conservative — a body
+  // newer than its (stale) metadata is treated as a candidate — which is safe:
+  // a wrongly suspected candidate is rejected by the full-state re-check inside
+  // the archive transactions below, and a missed candidate is simply picked up
+  // by the next scan. persistSession refreshes metadata timestamps on every
+  // save, so active sessions always stay fresh in metadata.
   for (const [sessionId, metadata] of Object.entries(metadataStore)) {
     if (!metadata || metadata.archivedAt || metadata.messageCount === 0 || metadata.taskStatus === 'running') continue
+    const metadataActivityTime = sessionActivityTime(metadata)
+    if (metadataActivityTime !== null) {
+      if (metadataActivityTime >= cutoff) continue
+      candidates.push(sessionId)
+      continue
+    }
+    // Metadata carries no timestamp at all: fall back to the body.
     const session = await storage.readSessionValue(sessionId)
     if (!session || session.archivedAt) continue
     const activityTime = sessionActivityTime(metadata, session)
@@ -75,10 +102,13 @@ async function archiveInactiveSessionsUnlocked(options = {}) {
   }
 
   const archivedSessionIds = []
-  if (typeof storage.atomicSessionRecordUpdate === 'function' && await storage.isSessionStateAuthoritative()) {
-    // Authoritative: archive body + metadata in one SQLite transaction (CAS
-    // retried on concurrent metadata-only changes), so no half-archived state.
-    for (const sessionId of candidates) {
+  // Authoritative: archive body + metadata in one SQLite transaction (CAS
+  // retried on concurrent metadata-only changes), so no half-archived state.
+  if (typeof storage.atomicSessionRecordUpdate === 'function') {
+    for (const [index, sessionId] of candidates.entries()) {
+      // Let pending requests run between archive transactions (not before the
+      // first candidate — nothing to yield from yet).
+      if (index > 0) await yieldToEventLoop()
       const updated = await storage.atomicSessionRecordUpdate(sessionId, ({ state, metadata }) => {
         const activityTime = sessionActivityTime(metadata, state)
         if (state.archivedAt || metadata.archivedAt || metadata.messageCount === 0 || metadata.taskStatus === 'running' || activityTime === null || activityTime >= cutoff) return null
@@ -87,7 +117,10 @@ async function archiveInactiveSessionsUnlocked(options = {}) {
       if (updated?.state?.archivedAt === archivedAt) archivedSessionIds.push(sessionId)
     }
   } else {
-    for (const sessionId of candidates) {
+    for (const [index, sessionId] of candidates.entries()) {
+      // Let pending requests run between archive transactions (not before the
+      // first candidate — nothing to yield from yet).
+      if (index > 0) await yieldToEventLoop()
       const updatedSession = await storage.atomicSessionValueUpdate(sessionId, (session) => {
         const activityTime = sessionActivityTime(session)
         if (session.archivedAt || activityTime === null || activityTime >= cutoff) return session
@@ -134,16 +167,30 @@ export async function archiveInactiveSessions(options = {}) {
   }
 }
 
-export function startAutoArchiveRunner() {
+// `options` exists for tests (inject storage/now like archiveInactiveSessions);
+// production callers pass nothing and get defaultStorage + Date.now().
+export function startAutoArchiveRunner(options = {}) {
   if (autoArchiveTimer) return
   autoArchiveTimer = setInterval(() => {
-    archiveInactiveSessions().catch((error) => logger.error('Automatic conversation archive failed:', error))
+    archiveInactiveSessions(options).catch((error) => logger.error('Automatic conversation archive failed:', error))
   }, AUTO_ARCHIVE_CHECK_INTERVAL_MS)
   autoArchiveTimer.unref?.()
-  archiveInactiveSessions().catch((error) => logger.error('Initial automatic conversation archive failed:', error))
+  // Delay the first pass off the startup path: right after listen() the server
+  // is absorbing the browser's initial request burst, and the scan + archive
+  // transactions on a large library can block the event loop for a long
+  // stretch. The timer is unref'd so it never keeps the process alive.
+  autoArchiveInitialTimer = setTimeout(() => {
+    autoArchiveInitialTimer = null
+    archiveInactiveSessions(options).catch((error) => logger.error('Initial automatic conversation archive failed:', error))
+  }, AUTO_ARCHIVE_INITIAL_DELAY_MS)
+  autoArchiveInitialTimer.unref?.()
 }
 
 export function stopAutoArchiveRunner() {
+  if (autoArchiveInitialTimer) {
+    clearTimeout(autoArchiveInitialTimer)
+    autoArchiveInitialTimer = null
+  }
   if (!autoArchiveTimer) return
   clearInterval(autoArchiveTimer)
   autoArchiveTimer = null