dsh-sessions-manager 3.2.2 → 3.4.0

package/src/index.js

@@ -12,6 +12,11 @@ import { basename, dirname, isAbsolute, join } from 'node:path'
 import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { rewriteFrame0Cwd } from './zstd-frame.js'
+import { renderSessionMarkdown } from './markdown.js'
+import { createStarIndex } from './star-index.js'
+import { aggregateStorage } from './storage-stats.js'
+import { createAutoArchiveStore, pickInactiveCandidates } from './auto-archive.js'
+
 
 export const name = 'dsh-sessions-manager'
 export const inject = ['webServer', 'workspaceRegistry', 'sessionPersistence', 'sessionQuery', 'storageDomain']
@@ -27,6 +32,7 @@ const DEFAULT_TRASH_SETTINGS = Object.freeze({ retentionDays: 0 })
 const FETCH_TOOL_RE = /search|fetch|download|browse/i
 const MAX_FETCHES = 12   // fetch 记录上限（防响应过大）
 const MAX_FILES = 20     // write/edit 文件列表上限
+const MAX_STORAGE_TOP = 50 // 存储排行返回上限（防响应过大）
 
 function json(res, value, status = 200) {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
@@ -151,7 +157,7 @@ export function apply(ctx) {
 
   let wsByPath = {}
 
-  async function resolveOne(id) {
+  async function resolveOne(id, usage) {
     let title = null, createdAt = null, cwd = null
     try {
       const o = await sq.readTitleSnapshot(id)
@@ -173,7 +179,7 @@ export function apply(ctx) {
     const ws = cwd ? wsByPath[cwd] : undefined
     const workspaceGone = !!(cwd && !ws)
     const display = title ? (String(title).length > MAX_TITLE ? String(title).slice(0, MAX_TITLE) + '…' : String(title)) : null
-    return {
+    const base = {
       sessionId: id,
       title: display,
       createdAt: createdAt || null,
@@ -182,6 +188,45 @@ export function apply(ctx) {
       workspaceGone: workspaceGone ? true : false,
       hasWorkspace: !!cwd,
     }
+    // sizeBytes / updatedAt are opt-in: they cost one stat() per session, so
+    // the high-frequency list routes stay exactly as cheap as before.
+    if (usage) {
+      if (usage.sizeById && usage.sizeById.has(id)) base.sizeBytes = usage.sizeById.get(id)
+      if (usage.mtimeById && usage.mtimeById.has(id)) base.updatedAt = usage.mtimeById.get(id)
+    }
+    return base
+  }
+
+  // Disk usage + last-write time for every session, in one pass.
+  //
+  // sp.locate(header) resolves the log file behind a session header; a single
+  // stat() then yields both its size and its mtime. mtime doubles as the
+  // session's last-activity time — appending an event rewrites the log, so the
+  // file's last write tracks the conversation's last turn. It errs safe: a log
+  // we relocated (move) gets a fresh mtime and therefore looks *more* active
+  // than it is, which can only delay an auto-archive, never cause a wrong one.
+  async function collectUsage() {
+    const sizeById = new Map()
+    const mtimeById = new Map()
+    let headers = []
+    try { headers = await sp.list() } catch (e) { headers = [] }
+    if (!Array.isArray(headers)) headers = []
+    const CHUNK = 8
+    for (let i = 0; i < headers.length; i += CHUNK) {
+      await Promise.all(headers.slice(i, i + CHUNK).map(async (header) => {
+        const id = header && header.id != null ? String(header.id) : null
+        if (!id) return
+        try {
+          const loc = sp.locate(header)
+          if (!loc || typeof loc.path !== 'string' || !loc.path) return
+          const st = await stat(loc.path)
+          if (!st) return
+          if (typeof st.size === 'number') sizeById.set(id, st.size)
+          if (typeof st.mtimeMs === 'number' && st.mtimeMs > 0) mtimeById.set(id, Math.floor(st.mtimeMs))
+        } catch (e) { /* best-effort: an unreadable log just stays unknown */ }
+      }))
+    }
+    return { sizeById, mtimeById }
   }
 
   // Restore (unarchive) one session; throws on failure.
@@ -226,6 +271,24 @@ export function apply(ctx) {
     return operation
   }
 
+  // ---- Starred sessions (收藏, schema v3) -----------------------------------
+  // User marks, kept in the plugin's own index (never touches DSH logs). Stars
+  // survive archive & soft-delete — both are reversible — and are dropped only
+  // when the session is really gone (purge, or externally removed; the latter
+  // is caught by gcStars during list builds).
+  const stars = createStarIndex()
+  // Auto-archive settings live in their own schema-v4 store, off by default.
+  const autoArchive = createAutoArchiveStore()
+
+  async function gcStars(validIds) {
+    try {
+      const store = await stars.read()
+      const valid = new Set(validIds.map(String))
+      const gone = store.starredSessionIds.filter((id) => !valid.has(id))
+      if (gone.length) await stars.removeIds(gone)
+    } catch (e) { /* best-effort */ }
+  }
+
   // Soft-delete one session: record it in the recycle-bin index but KEEP its
   // log in the original workspace directory. Moving the file out (and detaching
   // it from the workspace) orphaned the session into DSH's "未分组" group and
@@ -364,6 +427,7 @@ export function apply(ctx) {
       purged = true
     })
     if (!purged) throw new Error('彻底删除失败')
+    stars.removeIds([sid]).catch(() => {})
     return { ok: true, purged: true }
   }
 
@@ -641,12 +705,16 @@ export function apply(ctx) {
     })
   }
 
-  async function allSessionItems() {
+  // opts.usage: fill sizeBytes + updatedAt (one stat() per session). Off by
+  // default so the panel's list route keeps its original cost.
+  async function allSessionItems(opts = {}) {
     let materialized = new Set()
     let live = ctx.get('sessions')
+    let headersOk = false
     try {
       const headers = await sp.list()
       materialized = new Set(headers.map((h) => String(h.id)))
+      headersOk = true
     } catch (e) { /* best-effort */ }
     const ids = []
     try { for (const header of await sp.list()) ids.push(String(header.id)) } catch (e) { /* ignore */ }
@@ -663,14 +731,69 @@ export function apply(ctx) {
     try { for (const ent of w.list()) wsByPath[ent.path] = ent } catch (e) { wsByPath = {} }
     const currentArchived = new Set((await archivedState().catch(() => ({ archivedSessionIds: [] }))).archivedSessionIds || [])
     const items = []
+    const usage = (opts && opts.usage) ? await collectUsage() : null
     const CHUNK = 6
     for (let i = 0; i < visibleIds.length; i += CHUNK) {
-      const res2 = await Promise.all(visibleIds.slice(i, i + CHUNK).map(resolveOne))
+      // Arrow wrapper on purpose: Array#map passes (value, index, array), and
+      // resolveOne's second argument is the usage map.
+      const res2 = await Promise.all(visibleIds.slice(i, i + CHUNK).map((id) => resolveOne(id, usage)))
       for (const it of res2) items.push({ ...it, archived: currentArchived.has(it.sessionId) })
     }
+    // Annotate stars; GC only when we have a trustworthy id baseline, so a
+    // failing sp.list() can never wipe the whole index.
+    let starredSet = new Set()
+    try { starredSet = new Set((await stars.read()).starredSessionIds) } catch (e) {}
+    for (const it of items) it.starred = starredSet.has(String(it.sessionId))
+    if (headersOk) await gcStars(ids)
     return items
   }
 
+  // ---- Storage usage + auto-archive ---------------------------------------
+
+  // Read-only rollup: per-workspace totals plus the largest sessions. The
+  // aggregation itself is a pure function (src/storage-stats.js).
+  async function buildStorage(opts = {}) {
+    const items = await allSessionItems({ usage: true })
+    const raw = Number(opts && opts.topN)
+    const topN = Number.isInteger(raw) && raw > 0 ? Math.min(raw, MAX_STORAGE_TOP) : 10
+    return aggregateStorage(items, { topN })
+  }
+
+  // Archive conversations that have been idle past the configured window.
+  //
+  // Deliberately lazy — there is no timer. The sweep runs when the panel reads
+  // its settings (and on demand), at most once a day: a background interval
+  // would keep the host process alive and would archive conversations while
+  // nobody is looking at the panel.
+  async function autoArchiveSweep(opts = {}) {
+    const store = await autoArchive.read()
+    const days = store.settings.inactiveDays
+    if (!days) return { ok: true, skipped: 'disabled', archived: 0 }
+    const now = Date.now()
+    if (!(opts && opts.force) && autoArchive.isFresh(store, now)) {
+      return { ok: true, skipped: 'throttled', archived: 0, lastRunAt: store.lastRunAt, lastArchivedCount: store.lastArchivedCount }
+    }
+    const items = await allSessionItems({ usage: true })
+    const candidates = pickInactiveCandidates(items, {
+      inactiveDays: days,
+      skipStarred: store.settings.skipStarred,
+      activeSessionId: getActiveSessionId(ctx),
+      now,
+    })
+    let archived = 0
+    const failed = []
+    for (const sid of candidates) {
+      try {
+        const result = await archiveOne(sid)
+        if (result && result.archived) archived++
+      } catch (e) {
+        failed.push({ sessionId: sid, error: String((e && e.message) || e) })
+      }
+    }
+    await autoArchive.recordRun(archived, now)
+    return { ok: true, archived, candidates: candidates.length, failed, lastRunAt: now }
+  }
+
   async function sidebarAuthority() {
     const ids = []
     try { for (const header of await sp.list()) ids.push(String(header.id)) } catch (e) {}
@@ -855,7 +978,7 @@ export function apply(ctx) {
           const items = []
           const CHUNK = 6
           for (let i = 0; i < idStrs.length; i += CHUNK) {
-            const res2 = await Promise.all(idStrs.slice(i, i + CHUNK).map(resolveOne))
+            const res2 = await Promise.all(idStrs.slice(i, i + CHUNK).map((id) => resolveOne(id)))
             items.push.apply(items, res2)
           }
           json(res, { items })
@@ -1049,6 +1172,57 @@ export function apply(ctx) {
       },
     }))
 
+    // Star / unstar one or many sessions (收藏, schema v3).
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/star/set',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const starred = !!(body && body.starred)
+          let ids = parseIds(body)
+          if ((!ids || ids.length === 0) && body && typeof body.sessionId === 'string') {
+            ids = isSafeSessionId(body.sessionId) ? [body.sessionId] : null
+          }
+          if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionId' }, 400)
+          const starredSessionIds = await stars.setStarred(ids, starred)
+          json(res, { ok: true, starredSessionIds })
+        } catch (e) {
+          json(res, { ok: false, error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
+    // Human-readable Markdown export (one session). Raw-log ZIP export is
+    // dsh's own GET /api/session.export — we deliberately do not duplicate it
+    // (see reports/HANDOFF-dsh-sessions-manager-roadmap.md §2.4).
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/export-md',
+      handler: async (req, res) => {
+        try {
+          const url = new URL(req.url, 'http://localhost')
+          const sid = url.searchParams.get('sessionId')
+          requireSessionId(sid)
+          const r = await sp.readFrom(sid, 0)
+          if (!r || !r.meta) {
+            const error = new Error('无法读取该会话的日志')
+            error.status = 404
+            throw error
+          }
+          const md = renderSessionMarkdown({ ...r.meta, id: sid }, r.events || [])
+          res.writeHead(200, {
+            'content-type': 'text/markdown; charset=utf-8',
+            'content-disposition': `attachment; filename="dsh-session-${sid}.md"`,
+            'cache-control': 'no-store',
+          })
+          res.end(md)
+        } catch (e) {
+          json(res, { error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
     disposers.push(ctx.webServer.register({
       kind: 'exact',
       path: '/archived-sessions/sidebar-state',
@@ -1153,6 +1327,65 @@ export function apply(ctx) {
       },
     }))
 
+    // Storage usage rollup (read-only): per-workspace totals + largest sessions.
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/storage',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          json(res, await buildStorage({ topN: body && body.topN }))
+        } catch (e) {
+          json(res, { error: String((e && e.message) || e) }, 500)
+        }
+      },
+    }))
+
+    // Auto-archive settings. A plain read (no patch keys) doubles as the lazy
+    // sweep trigger — that is how the once-a-day cleanup gets a chance to run
+    // without a background timer.
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/auto-archive/settings',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const patch = {}
+          if (body && Object.prototype.hasOwnProperty.call(body, 'inactiveDays')) patch.inactiveDays = body.inactiveDays
+          if (body && Object.prototype.hasOwnProperty.call(body, 'skipStarred')) patch.skipStarred = body.skipStarred
+          const settings = Object.keys(patch).length
+            ? await autoArchive.update(patch)
+            : (await autoArchive.read()).settings
+          const sweep = await autoArchiveSweep()
+          const store = await autoArchive.read()
+          json(res, {
+            ok: true,
+            settings,
+            lastRunAt: store.lastRunAt,
+            lastArchivedCount: store.lastArchivedCount,
+            sweep,
+          })
+        } catch (e) {
+          json(res, { ok: false, error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
+    // Run the auto-archive sweep right now, ignoring the once-a-day throttle.
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/auto-archive/run',
+      handler: async (req, res) => {
+        try {
+          const sweep = await autoArchiveSweep({ force: true })
+          const store = await autoArchive.read()
+          json(res, { ok: true, ...sweep, settings: store.settings, lastRunAt: store.lastRunAt, lastArchivedCount: store.lastArchivedCount })
+        } catch (e) {
+          json(res, { ok: false, error: String((e && e.message) || e) }, 500)
+        }
+      },
+    }))
+
     return () => { for (const d of disposers) d() }
   }, 'dsh-sessions-manager: routes')
 }

package/src/markdown.js

@@ -0,0 +1,175 @@
+// Render a session log as human-readable Markdown.
+//
+// Pure: no DOM, no I/O, no dsh imports. Everything it needs arrives as
+// arguments, so the renderer is unit-testable without a running host.
+//
+// Field shapes below were read off real session logs (2026-09-01), not guessed:
+//   user/message       data.content            = [{ type:'text', text } | { type:'image', ... }]
+//   assistant/message  data.message.content    = [{ type:'text'|'reasoning'|'tool-call', ... }]
+//   tool/call          data.{name, arguments}  (arguments is a JSON *string*)
+//   tool/result        data.message.content    = [{ type:'tool-result', content:[{type:'text',text}] }]
+// Note the asymmetry: user text lives at data.content, assistant text one level
+// deeper at data.message.content. Streaming deltas (`assistant/chunk`,
+// `text-chunks`, `reasoning-chunks`) are never rendered — `assistant/message`
+// already carries the final text for each step.
+
+const MAX_TOOL_ARG = 200
+
+function isoTime(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+  try { return new Date(value).toISOString() } catch { return null }
+}
+
+function yamlString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
+}
+
+function blocksOf(value) {
+  return Array.isArray(value) ? value.filter((b) => b && typeof b === 'object') : []
+}
+
+// Join the text blocks of a content array; image blocks are counted separately.
+function textFromBlocks(blocks) {
+  const parts = []
+  for (const block of blocks) {
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return parts.join('\n\n').trim()
+}
+
+function imageCountOf(blocks) {
+  let count = 0
+  for (const block of blocks) if (block.type === 'image') count++
+  return count
+}
+
+function reasoningFromBlocks(blocks) {
+  const parts = []
+  for (const block of blocks) {
+    if (block.type === 'reasoning' && typeof block.text === 'string' && block.text.trim()) parts.push(block.text.trim())
+  }
+  return parts.join('\n\n')
+}
+
+// A short, human-usable summary of one tool call's arguments.
+export function summarizeToolArguments(name, rawArguments) {
+  let parsed = null
+  if (typeof rawArguments === 'string') {
+    try { parsed = JSON.parse(rawArguments) } catch { parsed = null }
+  } else if (rawArguments && typeof rawArguments === 'object') {
+    parsed = rawArguments
+  }
+  if (parsed === null) return typeof rawArguments === 'string' ? rawArguments.slice(0, MAX_TOOL_ARG) : ''
+  if (typeof parsed !== 'object') return String(parsed).slice(0, MAX_TOOL_ARG)
+  const preferred = ['command', 'file_path', 'path', 'query', 'url', 'pattern']
+  for (const key of preferred) {
+    if (typeof parsed[key] === 'string' && parsed[key].trim()) return parsed[key]
+  }
+  const keys = Object.keys(parsed)
+  if (keys.length === 0) return ''
+  const rest = {}
+  for (const key of keys.slice(0, 6)) {
+    const value = parsed[key]
+    rest[key] = typeof value === 'string' ? value : JSON.stringify(value)
+  }
+  return JSON.stringify(rest).slice(0, MAX_TOOL_ARG)
+}
+
+/**
+ * Render one session as Markdown.
+ * @param {object} meta - Session header (`{ id, cwd, createdAt, title? }`).
+ * @param {Array<object>} events - Session events as stored in the log.
+ * @param {object} [options]
+ * @param {boolean} [options.includeReasoning=false] - Emit assistant reasoning blocks.
+ * @param {boolean} [options.includeToolResults=false] - Emit tool results.
+ * @param {number} [options.exportedAt] - Override the export timestamp (tests).
+ * @returns {string} Markdown document.
+ */
+export function renderSessionMarkdown(meta, events, options = {}) {
+  const includeReasoning = options.includeReasoning === true
+  const includeToolResults = options.includeToolResults === true
+  const header = meta && typeof meta === 'object' ? meta : {}
+  const list = Array.isArray(events) ? events : []
+
+  // The last session/title event wins — DSH may retitle a session later on.
+  let title = typeof header.title === 'string' && header.title.trim() ? header.title.trim() : null
+  for (const ev of list) {
+    const data = ev && ev.data
+    if (ev && ev.type === 'session/title' && data && typeof data.title === 'string' && data.title.trim()) {
+      title = data.title.trim()
+    }
+  }
+
+  const front = ['---']
+  if (title) front.push(`title: ${yamlString(title)}`)
+  if (typeof header.id === 'string' && header.id) front.push(`sessionId: ${yamlString(header.id)}`)
+  if (typeof header.cwd === 'string' && header.cwd) front.push(`cwd: ${yamlString(header.cwd)}`)
+  const created = isoTime(header.createdAt)
+  if (created) front.push(`createdAt: ${created}`)
+  const exported = isoTime(options.exportedAt)
+  if (exported) front.push(`exportedAt: ${exported}`)
+  front.push('---')
+
+  const out = [front.join('\n')]
+  if (title) out.push('', `# ${title}`)
+
+  let turn = null
+  for (const ev of list) {
+    if (!ev || typeof ev !== 'object') continue
+    const data = ev.data && typeof ev.data === 'object' ? ev.data : {}
+    const type = ev.type
+
+    if (type === 'turn/start') {
+      const next = Number.isInteger(data.turn) ? data.turn : null
+      if (next !== null && next !== turn) {
+        turn = next
+        out.push('', `## 第 ${turn} 轮`)
+      }
+      continue
+    }
+
+    if (type === 'user/message') {
+      const blocks = blocksOf(data.content)
+      const text = textFromBlocks(blocks)
+      const images = imageCountOf(blocks)
+      if (!text && images === 0) continue
+      out.push('', '### 用户', '')
+      if (text) out.push(text)
+      for (let i = 0; i < images; i++) out.push('', `![图片 ${i + 1}](attachment)`)
+      continue
+    }
+
+    if (type === 'assistant/message') {
+      const message = data.message && typeof data.message === 'object' ? data.message : {}
+      const blocks = blocksOf(message.content)
+      const text = textFromBlocks(blocks)
+      const reasoning = includeReasoning ? reasoningFromBlocks(blocks) : ''
+      if (!text && !reasoning) continue
+      out.push('', '### 助手', '')
+      if (reasoning) out.push('> 思考：' + reasoning.split('\n').join('\n> '), '')
+      if (text) out.push(text)
+      continue
+    }
+
+    if (type === 'tool/call') {
+      const name = typeof data.name === 'string' && data.name ? data.name : 'tool'
+      const summary = summarizeToolArguments(name, data.arguments)
+      out.push('', `### 工具调用：\`${name}\``, '')
+      out.push(summary ? '```\n' + summary + '\n```' : '（无参数）')
+      continue
+    }
+
+    if (type === 'tool/result' && includeToolResults) {
+      const message = data.message && typeof data.message === 'object' ? data.message : {}
+      const blocks = blocksOf(message.content)
+      let text = ''
+      for (const block of blocks) {
+        if (block.type === 'tool-result') text = textFromBlocks(blocksOf(block.content))
+      }
+      if (text) out.push('', '<details><summary>工具结果</summary>', '', '```\n' + text.slice(0, 2000) + '\n```', '', '</details>')
+    }
+  }
+
+  out.push('')
+  return out.join('\n')
+}

package/src/star-index.js

@@ -0,0 +1,109 @@
+// Durable "starred sessions" index (schema v3).
+//
+// Deliberately mirrors the recycle-bin index in src/index.js: version field,
+// automatic upgrade of older shapes, atomic write (tmp + rename) and a single
+// chained mutation queue so two concurrent requests can never clobber each
+// other. Extracted from the host bundle so it can be unit-tested directly —
+// pass `dir` to point the index at a temp directory.
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// v3 is the first star schema; it starts at 3 so it can never be confused with
+// the recycle bin's v1/v2 documents even if a file is copied between them.
+export const STAR_SCHEMA_VERSION = 3
+
+const DEFAULT_STAR_DIR = join(homedir(), '.dsh', 'sessions-manager')
+
+function isSafeSessionId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\\/\0]/.test(value) && value !== '.' && value !== '..'
+}
+
+/**
+ * Coerce anything on disk (or nothing at all) into a valid v3 store.
+ * Accepts a bare array of ids (the pre-schema shape) and upgrades it.
+ */
+export function normalizeStarStore(raw) {
+  const legacy = Array.isArray(raw) ? raw : null
+  const source = legacy || (raw && typeof raw === 'object' ? raw : null)
+  const ids = source && Array.isArray(source.starredSessionIds) ? source.starredSessionIds : (legacy || [])
+  const clean = []
+  const seen = new Set()
+  for (const id of ids) {
+    // Strings only: silently coercing a number into an id would let junk into
+    // the index and mask a caller bug.
+    if (!isSafeSessionId(id)) continue
+    if (seen.has(id)) continue
+    seen.add(id)
+    clean.push(id)
+  }
+  return { schemaVersion: STAR_SCHEMA_VERSION, starredSessionIds: clean }
+}
+
+/**
+ * Open the star index.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Directory holding the index (tests inject a temp dir).
+ * @param {string} [options.indexPath] - Full index path, overriding `dir`.
+ */
+export function createStarIndex(options = {}) {
+  const dir = options.dir || process.env.DSH_SESSIONS_MANAGER_STAR_DIR || DEFAULT_STAR_DIR
+  const indexPath = options.indexPath || join(dir, 'star.json')
+  let mutation = Promise.resolve()
+
+  async function read() {
+    try {
+      return normalizeStarStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch {
+      return normalizeStarStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.star-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeStarStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  // Serialize read-modify-write cycles: every mutator sees the store as left by
+  // the previous one, and a rejected mutator still keeps the chain alive.
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = await read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  /**
+   * Star or unstar sessions.
+   * @param {string[]} ids - Session ids to change.
+   * @param {boolean} starred - true to star, false to unstar.
+   * @returns {Promise<string[]>} The full starred set after the change.
+   */
+  function setStarred(ids, starred) {
+    const wanted = (Array.isArray(ids) ? ids : []).filter(isSafeSessionId).map(String)
+    return mutate((store) => {
+      const set = new Set(store.starredSessionIds)
+      for (const id of wanted) {
+        if (starred) set.add(id)
+        else set.delete(id)
+      }
+      store.starredSessionIds = [...set]
+      return store.starredSessionIds
+    })
+  }
+
+  // Drop ids once their session is gone (purged / deleted), otherwise the index
+  // would grow forever with ids that can never be listed again.
+  function removeIds(ids) {
+    return setStarred(ids, false)
+  }
+
+  return { read, write, mutate, setStarred, removeIds, indexPath, dir }
+}