dsh-session-mng 0.1.4 → 0.2.1

package/lib/service.js

@@ -11,6 +11,21 @@
  */
 
 import { SessionMngError, messageOf } from './errors.js'
+import {
+  buildBlanks,
+  buildDetail,
+  buildOverview,
+  buildPage,
+  buildSearchGroups,
+  catalogAvailable,
+  createLegacyCatalogCache,
+  decorateRows,
+  fromContext,
+  readPageTitles,
+  SORTS,
+  TABS,
+  UNGROUPED,
+} from './catalog.js'
 import { normalizeTitle, proposeTitle, textOfEvent } from './title.js'
 import { buildState, classifySession } from './state.js'
 import {
@@ -19,6 +34,7 @@ import {
   findSessionDirs,
   finalizeMove,
   pathExists,
+  readLogFactsBatch,
   removeStagedDelete,
   restoreStagedDelete,
   stageDelete,
@@ -41,6 +57,15 @@ import {
 /** Hard ceiling on one cascade delete, regardless of maxBatch. */
 const MAX_DELETE_TOTAL = 500
 
+/** How long one slow-path `buildState` result may serve catalog reads. */
+const LEGACY_TTL_MS = 30_000
+
+/** How long a locally written cold title outranks the host projection cache. */
+const TITLE_OVERRIDE_TTL_MS = 5 * 60_000
+
+/** Hard budget for the one O(n) size scan behind `GET /sizes`. */
+const SIZE_SCAN_TIMEOUT_MS = 20_000
+
 /** Load-time defaults; a patch entry's `config` overrides them field by field. */
 export const DEFAULT_CONFIG = {
   maxBatch: 50,
@@ -51,6 +76,9 @@ export const DEFAULT_CONFIG = {
   titleMaxBytes: 120,
   allowRemote: false,
   sessionsRoot: '',
+  sizesTtlMs: 60_000,
+  sizeScanMax: 20_000,
+  pageLimitMax: 50,
 }
 
 /** Clamp one integer config field. */
@@ -71,9 +99,38 @@ export function normalizeConfig(input) {
     titleMaxBytes: integer(src.titleMaxBytes, DEFAULT_CONFIG.titleMaxBytes, 16, 512),
     allowRemote: src.allowRemote === true,
     sessionsRoot: typeof src.sessionsRoot === 'string' ? src.sessionsRoot : '',
+    sizesTtlMs: integer(src.sizesTtlMs, DEFAULT_CONFIG.sizesTtlMs, 1_000, 3_600_000),
+    sizeScanMax: integer(src.sizeScanMax, DEFAULT_CONFIG.sizeScanMax, 100, 1_000_000),
+    pageLimitMax: integer(src.pageLimitMax, DEFAULT_CONFIG.pageLimitMax, 1, 200),
   }
 }
 
+/** Interpret one query flag: `1`/`true`, `0`/`false`, or the fallback. */
+function flagOf(value, fallback = false) {
+  if (value === undefined || value === null) return fallback
+  if (value === true || value === '1' || value === 'true') return true
+  if (value === false || value === '0' || value === 'false') return false
+  return fallback
+}
+
+/** Validate one enumerated query value against its allowed set. */
+function choiceOf(value, allowed, fallback, label) {
+  if (value === undefined || value === null || value === '') return fallback
+  if (typeof value !== 'string' || !allowed.has(value)) {
+    throw new SessionMngError('bad-request', `${label} must be one of: ${[...allowed].join(', ')}`, 400)
+  }
+  return value
+}
+
+/** Validate the workspace selector of one page request. */
+function workspaceSelector(value) {
+  const id = typeof value === 'string' ? value.trim() : ''
+  if (id === '') {
+    throw new SessionMngError('bad-request', 'workspaceId is required (a workspace id or "ungrouped")', 400)
+  }
+  return id
+}
+
 /** Read a service without declaring it as a hard dependency. */
 function serviceOf(ctx, name) {
   try {
@@ -184,6 +241,41 @@ function summarize(results) {
 export function createService(ctx, config) {
   const withLock = createLock()
 
+  // -------------------------------------------------------------------------
+  // Process-local read memory
+  //
+  // `deletedIds` and `titleOverrides` exist because two host facts can lag a
+  // write this plugin just made: the registry keeps a deleted session's header
+  // until the next restart, and a cold title only reaches the projection cache
+  // on its next fold. They are reconciled (never authoritative) and bounded by
+  // a TTL or by the next `/sizes` scan.
+  // -------------------------------------------------------------------------
+
+  /** Ids this process deleted; filtered from the catalog until reconciliation. */
+  const deletedIds = new Set()
+  /** Titles this process wrote, preferred until the host projection catches up. */
+  const titleOverrides = new Map()
+  /** One all-store size snapshot: TTL-cached, shared by pages and `/sizes`. */
+  const sizeState = { at: 0, byId: new Map(), inflight: undefined, epoch: 0 }
+  /** Slow-path `buildState` catalogue, memoized for hosts without the seams. */
+  const legacyCatalog = createLegacyCatalogCache(ctx, config, LEGACY_TTL_MS)
+
+  /**
+   * Drop every process-local read cache after a mutation.
+   *
+   * The catalog itself holds no cache (it is rebuilt per request from memory),
+   * so only the two things that outlive a request are cleared: the size
+   * snapshot and the slow-path state. Both would otherwise answer a fresh
+   * request with pre-mutation numbers.
+   */
+  const invalidateReadCaches = () => {
+    sizeState.epoch += 1
+    sizeState.at = 0
+    sizeState.byId = new Map()
+    sizeState.inflight = undefined
+    legacyCatalog.invalidate()
+  }
+
   const persistence = () => ctx.sessionPersistence
   const registry = () => ctx.workspaceRegistry
   const query = () => ctx.sessionQuery
@@ -347,6 +439,8 @@ export function createService(ctx, config) {
         if (titles === undefined) throw new SessionMngError('unsupported-host', 'this deployment mounts no session-title service', 501)
         try {
           const accepted = titles.rename(live, normalized)
+          titleOverrides.set(id, { title: accepted.title, at: Date.now() })
+          invalidateReadCaches()
           return { title: accepted.title, seq: accepted.eventSeq, mode: 'live' }
         } catch (error) {
           if (String(error?.name).includes('TitleInvalid')) {
@@ -408,6 +502,8 @@ export function createService(ctx, config) {
           actual,
         })
       }
+      titleOverrides.set(id, { title: normalized, at: Date.now() })
+      invalidateReadCaches()
       return result
     })
   }
@@ -429,6 +525,7 @@ export function createService(ctx, config) {
         results.push({ sessionId: id, ok: false, error: resultError(error) })
       }
     }
+    if (results.some((item) => item.ok)) invalidateReadCaches()
     return summarize(results)
   }
 
@@ -445,6 +542,7 @@ export function createService(ctx, config) {
         results.push({ sessionId: id, ok: false, error: resultError(error) })
       }
     }
+    if (results.some((item) => item.ok)) invalidateReadCaches()
     return summarize(results)
   }
 
@@ -681,6 +779,20 @@ export function createService(ctx, config) {
         })
       }
 
+      // The registry caches headers at startup and keeps the deleted session's
+      // slot until the next restart. Remember what this process removed so the
+      // catalog stops listing it (a ghost row would offer buttons that 404),
+      // and clear the cached header when that seam is writable.
+      for (const record of records) {
+        deletedIds.add(record.id)
+        try {
+          registry()?.headers?.delete?.(record.id)
+        } catch {
+          // A read-only header cache only costs a stale row until `/sizes`.
+        }
+      }
+      invalidateReadCaches()
+
       const results = []
       for (const rootId of roots) {
         const failure = failures.get(rootId)
@@ -750,76 +862,85 @@ export function createService(ctx, config) {
         }
       }
     })
+    if (results.some((item) => item.ok)) invalidateReadCaches()
     return summarize(results)
   }
 
-  /** Move one cold session. Throws on any failure; the caller converts it. */
-  async function moveOne(id, target) {
+  /**
+   * Validate one member of a move family before any byte moves.
+   *
+   * Every member is checked first, so a family with one live or running member
+   * is refused as a whole instead of leaving a half-moved branch behind.
+   *
+   * @param {string} id - session id.
+   * @param {object} header - stored header of that session.
+   * @param {object} target - target workspace entity.
+   * @returns {Promise<{id: string, header: object, source: object|undefined, sourceDir: string, targetDir: string}>}
+   */
+  async function planMember(id, header, target) {
     const store = persistence()
-    if (store === undefined || typeof store.stat !== 'function' || typeof store.locate !== 'function') {
-      throw new SessionMngError('unsupported-backend', 'moving a session requires the local JSONL session backend', 501)
-    }
-    const snapshot = await store.stat(id)
-    const header = snapshot?.header
-    if (header === undefined) throw new SessionMngError('not-found', `session "${id}" is not stored`, 404)
     if (typeof header.cwd !== 'string' || header.cwd === '') {
-      throw new SessionMngError('no-cwd', 'this session has no recorded working directory, so it cannot be moved', 409)
+      throw new SessionMngError('no-cwd', `session "${id}" has no recorded working directory, so it cannot be moved`, 409, {
+        sessionId: id,
+      })
     }
     if (ctx.sessions?.get?.(id) !== undefined) {
-      throw new SessionMngError('session-live', 'this session is open in the running DSH process; restart DSH and retry the move', 409)
-    }
-    if (serviceOf(ctx, 'agents')?.get?.(id)?.status === 'running') {
-      throw new SessionMngError('session-running', 'this session is running; stop it before moving', 409)
-    }
-    if (header.origin === 'subagent' || (typeof header.delegationDepth === 'number' && header.delegationDepth >= 1)) {
-      throw new SessionMngError('subagent-session', 'subagent sessions are not moved on their own', 409)
-    }
-    if (header.parentSession !== undefined && header.parentSession !== null) {
       throw new SessionMngError(
-        'branch-session',
-        "a branch session must stay in its parent's workspace, so it is not moved on its own",
+        'session-live',
+        `session "${id}" is open in the running DSH process; restart DSH and retry the move`,
         409,
+        { sessionId: id },
       )
     }
-    // Only subagent descendants block a move. An ordinary fork (historical or
-    // not) is an independent session, so it no longer blocks its source.
-    const lineage = await descendantsOf(id)
-    if (lineage.subagents.length > 0) {
-      throw new SessionMngError('has-descendants', 'this session has subagent descendants; they cannot follow it yet', 409, {
-        descendants: lineage.subagents.length,
+    if (serviceOf(ctx, 'agents')?.get?.(id)?.status === 'running') {
+      throw new SessionMngError('session-running', `session "${id}" is running; stop it before moving`, 409, {
+        sessionId: id,
       })
     }
-    const source = workspaceOfId(id)
     const sourceDir = await dirsOf(id, header.cwd)
     const targetDir = sessionDirFromLocate(store, id, target.path)
     if (targetDir === undefined) {
       throw new SessionMngError('unsupported-backend', 'the session backend cannot locate a target directory', 501)
     }
+    return { id, header, source: workspaceOfId(id), sourceDir, targetDir }
+  }
 
+  /**
+   * Relocate one already-validated cold member: rewrite its log header, move
+   * its directory and reconcile the workspace ledger. Throws after restoring
+   * its own bytes and cache entry.
+   *
+   * @param {{id: string, header: object, source: object|undefined, sourceDir: string, targetDir: string}} member
+   * @param {object} target - target workspace entity.
+   * @returns {Promise<{member: object, staged: object|undefined, alreadyThere: boolean}>}
+   */
+  async function relocateMember(member, target) {
+    const { id, header, source, sourceDir, targetDir } = member
     if (targetDir === sourceDir) {
       // Bytes are already in the target project directory; only the ledger and
       // the cache may disagree.
       await reconcileMove({ registry: registry(), id, oldHeader: header, newHeader: header, source, target })
-      return { sessionId: id, ok: true, moved: false, alreadyThere: true, to: target.id }
+      return { member, staged: undefined, alreadyThere: true }
     }
-    if (await pathExists(targetDir)) {
-      throw new SessionMngError('move-conflict', `destination already holds a session directory: ${targetDir}`, 409)
-    }
-
+    const store = persistence()
     // Prove the log is readable and that no other process is writing it before
     // touching a single byte.
     let original
     try {
       original = await query().readSession(id)
     } catch (error) {
-      throw new SessionMngError('unreadable-session', `could not replay session "${id}": ${messageOf(error)}`, 422)
+      throw new SessionMngError('unreadable-session', `could not replay session "${id}": ${messageOf(error)}`, 422, {
+        sessionId: id,
+      })
     }
     const originalCount = Array.isArray(original?.events) ? original.events.length : 0
     let lease
     try {
       lease = await store.open(id, 'write')
     } catch (error) {
-      throw new SessionMngError('session-writer-held', `session "${id}" is being written by another process: ${messageOf(error)}`, 409)
+      throw new SessionMngError('session-writer-held', `session "${id}" is being written by another process: ${messageOf(error)}`, 409, {
+        sessionId: id,
+      })
     }
     await lease.close().catch(() => {})
 
@@ -837,6 +958,7 @@ export function createService(ctx, config) {
       const validatedCount = Array.isArray(validation?.events) ? validation.events.length : -1
       if (validatedCwd !== target.path || validatedCount !== originalCount) {
         throw new SessionMngError('move-verify-failed', 'the moved session did not read back with the expected header and event count', 500, {
+          sessionId: id,
           expectedCwd: target.path,
           actualCwd: validatedCwd,
           expectedEvents: originalCount,
@@ -864,6 +986,7 @@ export function createService(ctx, config) {
         await rollbackMove({ sourceDir, targetDir, backupDir: staged.backupDir })
       } catch (rollbackError) {
         throw new SessionMngError('manual-recovery', 'the move failed and the automatic rollback also failed', 500, {
+          sessionId: id,
           sourceDir,
           targetDir,
           backupDir: staged.backupDir,
@@ -873,22 +996,447 @@ export function createService(ctx, config) {
       }
       throw error
     }
+    return { member, staged, alreadyThere: false }
+  }
 
-    let leftoverBackup
+  /** Undo one completed member, restoring bytes, cache and ledger. */
+  async function undoMember(done, target) {
+    const { member, staged } = done
+    await rollbackMoveReconcile({
+      registry: registry(),
+      id: member.id,
+      oldHeader: member.header,
+      source: member.source,
+      target,
+      sourcePath: member.source?.path ?? member.header.cwd,
+    })
+    if (staged !== undefined) {
+      await rollbackMove({ sourceDir: member.sourceDir, targetDir: member.targetDir, backupDir: staged.backupDir })
+    }
+  }
+
+  /**
+   * Move one cold session and every subagent descendant it owns.
+   *
+   * Subagent sessions exist only to serve their root, so leaving them behind
+   * would strand them in the old project directory. Ordinary forks are
+   * independent user sessions and stay where they are.
+   *
+   * Throws on any failure; the caller converts it.
+   */
+  async function moveOne(id, target) {
+    const store = persistence()
+    if (store === undefined || typeof store.stat !== 'function' || typeof store.locate !== 'function') {
+      throw new SessionMngError('unsupported-backend', 'moving a session requires the local JSONL session backend', 501)
+    }
+    const snapshot = await store.stat(id)
+    const header = snapshot?.header
+    if (header === undefined) throw new SessionMngError('not-found', `session "${id}" is not stored`, 404)
+    if (header.origin === 'subagent' || (typeof header.delegationDepth === 'number' && header.delegationDepth >= 1)) {
+      throw new SessionMngError('subagent-session', 'subagent sessions are not moved on their own', 409)
+    }
+    if (header.parentSession !== undefined && header.parentSession !== null) {
+      throw new SessionMngError(
+        'branch-session',
+        "a branch session must stay in its parent's workspace, so it is not moved on its own",
+        409,
+      )
+    }
+
+    // Subagent descendants travel with their root; an ordinary fork (historical
+    // or not) is an independent session and stays behind.
+    const lineage = await descendantsOf(id)
+    const members = [
+      { id, header },
+      ...lineage.subagents.map((record) => ({ id: record.header.id, header: record.header })),
+    ]
+
+    // Validate the whole family before touching any bytes.
+    const planned = []
+    for (const member of members) planned.push(await planMember(member.id, member.header, target))
+
+    const completed = []
     try {
-      await finalizeMove(staged.backupDir)
+      for (const member of planned) completed.push(await relocateMember(member, target))
     } catch (error) {
-      leftoverBackup = { path: staged.backupDir, reason: messageOf(error) }
+      const rollbackFailures = []
+      for (const done of [...completed].reverse()) {
+        try {
+          await undoMember(done, target)
+        } catch (rollbackError) {
+          rollbackFailures.push({ sessionId: done.member.id, error: messageOf(rollbackError) })
+        }
+      }
+      if (rollbackFailures.length > 0) {
+        throw new SessionMngError('manual-recovery', 'the move failed and the automatic rollback also failed', 500, {
+          cause: messageOf(error),
+          sessions: completed.map((done) => done.member.id),
+          rollback: rollbackFailures,
+        })
+      }
+      throw error
     }
+
+    const leftover = []
+    for (const done of completed) {
+      if (done.staged === undefined) continue
+      try {
+        await finalizeMove(done.staged.backupDir)
+      } catch (error) {
+        leftover.push({ path: done.staged.backupDir, reason: messageOf(error) })
+      }
+    }
+    const root = completed[0]
+    const moved = completed.filter((done) => !done.alreadyThere)
     return {
       sessionId: id,
       ok: true,
-      moved: true,
-      from: source?.id ?? null,
+      moved: moved.length > 0,
+      from: root.member.source?.id ?? null,
       to: target.id,
       cwd: { from: header.cwd, to: target.path },
-      bytes: staged.bytes,
-      ...(leftoverBackup === undefined ? {} : { leftoverBackup }),
+      family: completed.length,
+      sessions: completed.map((done) => done.member.id),
+      ...(completed.every((done) => done.alreadyThere) ? { alreadyThere: true } : {}),
+      ...(moved.length === 0 ? {} : { bytes: moved.reduce((sum, done) => sum + done.staged.bytes, 0) }),
+      ...(leftover.length === 0 ? {} : { leftoverBackup: leftover }),
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Read surfaces (0.2.0): overview / paged sessions / search / detail / sizes
+  // -------------------------------------------------------------------------
+
+  /** One O(n) store scan behind a timeout and an explicit size ceiling. */
+  const scanSizes = async (signal) => {
+    const store = persistence()
+    if (store === undefined || typeof store.list !== 'function') {
+      throw new SessionMngError('sizes-pending', 'this deployment has no listable session persistence, so sizes are unavailable', 503)
+    }
+    const epoch = sizeState.epoch
+    const budget = AbortSignal.timeout(SIZE_SCAN_TIMEOUT_MS)
+    let combined = budget
+    if (signal !== undefined && typeof AbortSignal.any === 'function') {
+      try {
+        combined = AbortSignal.any([signal, budget])
+      } catch {
+        combined = budget
+      }
+    }
+    let entries
+    try {
+      entries = await store.list({ signal: combined })
+    } catch (error) {
+      throw new SessionMngError('sizes-pending', `could not scan session sizes: ${messageOf(error)}`, 503)
+    }
+    const list = Array.isArray(entries) ? entries : []
+    if (list.length > config.sizeScanMax) {
+      throw new SessionMngError(
+        'sizes-pending',
+        `size scan skipped: ${list.length} stored sessions exceed the configured limit of ${config.sizeScanMax}`,
+        503,
+        { count: list.length, max: config.sizeScanMax },
+      )
+    }
+    const byId = new Map()
+    for (const entry of list) {
+      const id = entry?.header?.id
+      if (typeof id !== 'string') continue
+      byId.set(id, {
+        sizeBytes: Number.isFinite(entry.sizeBytes) ? entry.sizeBytes : 0,
+        formatStatus: typeof entry.formatStatus === 'string' ? entry.formatStatus : undefined,
+      })
+    }
+    const at = Date.now()
+    if (epoch === sizeState.epoch) {
+      sizeState.at = at
+      sizeState.byId = byId
+    }
+    // Reconciliation: a store that no longer lists an id we deleted means the
+    // ghost marker can go, and a title override past its window has served its
+    // purpose (the host projection has caught up by then).
+    for (const id of [...deletedIds]) if (!byId.has(id)) deletedIds.delete(id)
+    for (const [id, override] of [...titleOverrides]) {
+      if (at - override.at > TITLE_OVERRIDE_TTL_MS) titleOverrides.delete(id)
+    }
+    return { at, byId, cached: false }
+  }
+
+  /** The size snapshot, reusing a fresh one and de-duplicating concurrent scans. */
+  const ensureSizes = (signal) => {
+    if (sizeState.at !== 0 && Date.now() - sizeState.at < config.sizesTtlMs) {
+      return Promise.resolve({ at: sizeState.at, byId: sizeState.byId, cached: true })
+    }
+    if (sizeState.inflight !== undefined) return sizeState.inflight
+    const promise = scanSizes(signal).finally(() => {
+      sizeState.inflight = undefined
+    })
+    sizeState.inflight = promise
+    return promise
+  }
+
+  /**
+   * Build one request's catalog: the zero-I/O fast path when the host exposes
+   * both seams, otherwise the cached `buildState` slow path. The response shape
+   * is identical either way; only `source` and the cost differ.
+   */
+  const catalogFor = async (options = {}) => {
+    const includeSubagents = options.includeSubagents === true
+    // An override is only a bridge until the host projection catches up; drop
+    // the ones that outlived their window so an external rename converges.
+    for (const [id, override] of [...titleOverrides]) {
+      if (Date.now() - override.at > TITLE_OVERRIDE_TTL_MS) titleOverrides.delete(id)
+    }
+    if (!catalogAvailable(ctx)) {
+      return legacyCatalog.catalog(includeSubagents, options.signal)
+    }
+    return fromContext(ctx, config, {
+      includeSubagents,
+      extraIds: options.extraIds,
+      deletedIds,
+      titleOverrides,
+    })
+  }
+
+  /** Fill this page's missing titles within the fallback budget. */
+  const applyTitles = async (rows, signal) => {
+    const ids = rows.filter((row) => row.title === '').map((row) => row.id)
+    if (ids.length === 0) return 0
+    const titles = await readPageTitles(ctx, ids, signal)
+    let pending = 0
+    for (const row of rows) {
+      if (row.title !== '') continue
+      const title = titles.get(row.id)
+      if (typeof title === 'string' && title !== '') row.title = title
+      else pending += 1
+    }
+    return pending
+  }
+
+  /**
+   * Size/format facts for one bounded row set: from the warm `/sizes` snapshot
+   * when it covers a row, otherwise one readdir+stat on that row's own log.
+   *
+   * `cacheOnly` keeps the per-row stat out of surfaces with an unbounded number
+   * of groups (search): those read the warm snapshot and leave the rest for the
+   * group the user actually expands.
+   */
+  const factsFor = async (rows, options = {}) => {
+    const facts = new Map()
+    if (options.sizes === false) return facts
+    if (sizeState.at !== 0 && Date.now() - sizeState.at < config.sizesTtlMs) {
+      for (const row of rows) {
+        const fact = sizeState.byId.get(row.id)
+        if (fact !== undefined) facts.set(row.id, fact)
+      }
+    }
+    if (options.cacheOnly === true || options.legacy === true) return facts
+    const missing = rows.filter((row) => !facts.has(row.id))
+    if (missing.length === 0) return facts
+    const store = persistence()
+    if (store === undefined || typeof store.locate !== 'function') return facts
+    const found = await readLogFactsBatch(
+      store,
+      missing.map((row) => ({ id: row.id, cwd: row.cwd })),
+    )
+    for (const [id, fact] of found) facts.set(id, fact)
+    return facts
+  }
+
+  /** The workspace descriptor the Client renders as a group header. */
+  const workspaceDescriptor = (workspace) =>
+    workspace === undefined
+      ? null
+      : {
+          id: workspace.id,
+          title: workspace.title,
+          path: workspace.path,
+          status: workspace.status ?? 'unknown',
+        }
+
+  /** First-paint counts for every workspace, never a session row. */
+  const overview = async (options = {}) => {
+    const catalog = await catalogFor({
+      includeSubagents: flagOf(options.includeSubagents),
+      signal: options.signal,
+    })
+    return buildOverview(catalog)
+  }
+
+  /** One workspace's (or the ungrouped bucket's) paged, branch-aware rows. */
+  const sessions = async (params = {}) => {
+    const workspaceId = workspaceSelector(params.workspaceId)
+    const tab = choiceOf(params.tab, TABS, 'all', 'tab')
+    const sort = choiceOf(params.sort, SORTS, 'updated', 'sort')
+    const includeBlank = flagOf(params.blank)
+    const includeSubagents = flagOf(params.subagents)
+    const withSizes = flagOf(params.sizes, true)
+    const catalog = await catalogFor({ includeSubagents, signal: params.signal })
+    if (workspaceId !== UNGROUPED && !catalog.workspaceById.has(workspaceId)) {
+      throw new SessionMngError('workspace-not-found', `unknown workspace "${workspaceId}"`, 404)
+    }
+    let sizeOf
+    if (sort === 'size') {
+      const snapshot = await ensureSizes(params.signal)
+      sizeOf = (id) => snapshot.byId.get(id)?.sizeBytes ?? 0
+    }
+    const page = buildPage(catalog, {
+      workspaceId,
+      tab,
+      query: params.query,
+      includeBlank,
+      sort,
+      sizeOf,
+      offset: params.offset,
+      limit: params.limit,
+      limitMax: config.pageLimitMax,
+    })
+    const titlesPending = await applyTitles(page.rows, params.signal)
+    const facts = await factsFor(page.rows, {
+      sizes: withSizes,
+      legacy: catalog.source === 'legacy',
+    })
+    return {
+      generatedAt: catalog.generatedAt,
+      source: catalog.source,
+      workspaceId,
+      workspace: workspaceDescriptor(page.workspace),
+      total: page.total,
+      offset: page.offset,
+      limit: page.limit,
+      hasMore: page.hasMore,
+      titlesPending,
+      rows: decorateRows(page.rows, facts),
+    }
+  }
+
+  /** Cross-workspace title/path/id search, one bounded page per hit group. */
+  const search = async (params = {}) => {
+    const query = typeof params.query === 'string' ? params.query.trim() : ''
+    if (query === '') throw new SessionMngError('bad-request', 'query must be a non-empty string', 400)
+    if (query.length > 500) throw new SessionMngError('bad-request', 'query must be at most 500 characters', 400)
+    const tab = choiceOf(params.tab, TABS, 'all', 'tab')
+    const sort = choiceOf(params.sort, SORTS, 'updated', 'sort')
+    const includeBlank = flagOf(params.blank)
+    const includeSubagents = flagOf(params.subagents)
+    const withSizes = flagOf(params.sizes, true)
+    const catalog = await catalogFor({ includeSubagents, signal: params.signal })
+    let sizeOf
+    if (sort === 'size') {
+      const snapshot = await ensureSizes(params.signal)
+      sizeOf = (id) => snapshot.byId.get(id)?.sizeBytes ?? 0
+    }
+    const { groups, total } = buildSearchGroups(catalog, {
+      query,
+      tab,
+      includeBlank,
+      sort,
+      sizeOf,
+      limit: params.limitPerGroup,
+      limitMax: config.pageLimitMax,
+    })
+    const decorated = []
+    for (const group of groups) {
+      // Search may span every workspace: sizes come from the warm snapshot only,
+      // never from a stat per hit row across all groups.
+      const facts = await factsFor(group.rows, {
+        sizes: withSizes,
+        cacheOnly: true,
+        legacy: catalog.source === 'legacy',
+      })
+      decorated.push({
+        workspaceId: group.workspaceId,
+        workspace: workspaceDescriptor(group.workspace),
+        total: group.total,
+        hasMore: group.hasMore,
+        rows: decorateRows(group.rows, facts),
+      })
+    }
+    return { generatedAt: catalog.generatedAt, source: catalog.source, query, total, groups: decorated }
+  }
+
+  /** One session's detail row, including relations and the action flags. */
+  const session = async (params = {}) => {
+    const id = normalizeId(params.id)
+    const catalog = await catalogFor({
+      includeSubagents: flagOf(params.subagents, true),
+      extraIds: [id],
+      signal: params.signal,
+    })
+    const detail = buildDetail(catalog, id)
+    if (detail === undefined) throw new SessionMngError('not-found', `unknown session "${id}"`, 404)
+    await applyTitles([detail.row], params.signal)
+    const facts = await factsFor([detail.row], {
+      sizes: flagOf(params.sizes, true),
+      legacy: catalog.source === 'legacy',
+    })
+    return {
+      generatedAt: catalog.generatedAt,
+      source: catalog.source,
+      row: decorateRows([detail.row], facts)[0],
+      capabilities: detail.capabilities,
+      limits: detail.limits,
+    }
+  }
+
+  /** The blank-session id lists behind the two Settings-page cleanup buttons. */
+  const blanks = async (params = {}) => {
+    const catalog = await catalogFor({ includeSubagents: flagOf(params.subagents), signal: params.signal })
+    return { generatedAt: catalog.generatedAt, source: catalog.source, ...buildBlanks(catalog) }
+  }
+
+  /**
+   * Aggregated sizes for one workspace, the ungrouped bucket, or the store.
+   *
+   * The aggregation walks the catalog's visible rows, exactly like `/overview`
+   * and `/sessions`: hidden subagents are excluded unless `subagents=1`, rows
+   * this process deleted are already filtered, and blank rows still count. That
+   * keeps `total.bytes` equal to the row Σ a 0.1.x `/state` reported for the
+   * same subagent switch instead of silently adding every persisted agent log.
+   */
+  const sizesReport = async (params = {}) => {
+    const raw = typeof params.workspaceId === 'string' ? params.workspaceId.trim() : ''
+    const scope = raw === '' ? 'all' : raw
+    const catalog = await catalogFor({ includeSubagents: flagOf(params.subagents), signal: params.signal })
+    if (scope !== 'all' && scope !== UNGROUPED && !catalog.workspaceById.has(scope)) {
+      throw new SessionMngError('workspace-not-found', `unknown workspace "${scope}"`, 404)
+    }
+    const snapshot = await ensureSizes(params.signal)
+    const buckets = new Map(
+      catalog.workspaces.map((workspace) => [
+        workspace.id,
+        { id: workspace.id, title: workspace.title, path: workspace.path, bytes: 0, count: 0 },
+      ]),
+    )
+    const ungrouped = { bytes: 0, count: 0 }
+    let totalBytes = 0
+    let totalCount = 0
+    for (const row of catalog.rows) {
+      const fact = snapshot.byId.get(row.id)
+      const bytes = Number.isFinite(fact?.sizeBytes) ? fact.sizeBytes : 0
+      const bucket = (row.workspaceId === null ? undefined : buckets.get(row.workspaceId)) ?? ungrouped
+      bucket.bytes += bytes
+      bucket.count += 1
+      totalBytes += bytes
+      totalCount += 1
+    }
+    const workspaces = scope === 'all' ? [...buckets.values()] : scope === UNGROUPED ? [] : [buckets.get(scope)]
+    const total =
+      scope === 'all'
+        ? { bytes: totalBytes, count: totalCount }
+        : scope === UNGROUPED
+          ? { bytes: ungrouped.bytes, count: ungrouped.count }
+          : { bytes: buckets.get(scope).bytes, count: buckets.get(scope).count }
+    return {
+      generatedAt: Date.now(),
+      source: 'scan',
+      workspaceId: scope,
+      scannedAt: snapshot.at,
+      cached: snapshot.cached === true,
+      expiresAt: snapshot.at + config.sizesTtlMs,
+      total,
+      workspaces,
+      ungrouped,
     }
   }
 
@@ -902,5 +1450,11 @@ export function createService(ctx, config) {
     deletePreview,
     remove,
     move,
+    overview,
+    sessions,
+    search,
+    session,
+    blanks,
+    sizes: sizesReport,
   }
 }