dsh-sessions-manager 3.6.1 → 3.7.0

package/src/lineage.js

@@ -8,13 +8,11 @@
 //   - fork branch: header.parentSession set without the subagent origin
 //   - empty: the log holds only the generation header
 //
-// The backend list snapshot carries NO eventCount, so the size test below is
-// only a cheap PRE-FILTER: since 0.1.3 it can no longer decide emptiness by
-// itself (bigger headers + a constant lifecycle-metadata frame push every
-// new log past the old baseline). The authoritative verdict comes from
-// refineEmptyLineage in index.js — an event-type scan (see below). Keep the
-// size test: it flags candidates cheaply and its false positives get
-// corrected by the precise pass.
+// v3.7.0 (T1)：体积法**不再对外发布任何空白结论**——它历史上就有假阳性
+// （长 cwd 抬高阈值把有内容的小日志标空 → 侧栏误隐藏，误隐藏严格重于误闪现）。
+// isEmptyLogSize 降级为纯参考实现（阈值单测仍锁着）；空白与否现在只有三个来源：
+// 解码精判的成功结论（true/false）、精判解码上限之外的日志（false = 必有内容）、
+// 以及未知（null，交后台 refine 队列判定）。见 index.js refineEmpty.
 
 const EMPTY_BASE = 190
 
@@ -60,10 +58,11 @@ export function isEmptyEventTypes(types) {
   return true
 }
 
-// Returns a lineage record, or null when the session is an ordinary
-// top-level, non-empty session (the overwhelmingly common case — keeps the
-// sidebar-state payload small).
-export function classifyLineage(header, sizeBytes) {
+// Structural lineage only (T1): a record is produced when the session is a
+// subagent or a fork branch; `empty` is published as null (= not yet judged)
+// and refined in the background. Ordinary top-level sessions return null —
+// they only ever gain an entry once a real decode says empty:true.
+export function classifyLineage(header) {
   if (!header || typeof header !== 'object') return null
   const origin = header.origin === 'subagent' ? 'subagent' : null
   const parentSession = typeof header.parentSession === 'string' && header.parentSession
@@ -72,7 +71,12 @@ export function classifyLineage(header, sizeBytes) {
   const delegationDepth = Number.isSafeInteger(header.delegationDepth) && header.delegationDepth > 0
     ? header.delegationDepth
     : 0
-  const empty = isEmptyLogSize(sizeBytes, header.cwd)
-  if (!origin && !parentSession && !empty) return null
-  return { origin, parentSession, delegationDepth, empty }
+  if (!origin && !parentSession) return null
+  return { origin, parentSession, delegationDepth, empty: null }
+}
+
+// 空白精判候选：压缩体积在解码上限内的小日志。sizeBytes 缺失（legacy 列表
+// 快照没有该观测）时返回 false —— 与历史行为一致：legacy 世代空白判定不生效。
+export function emptyScanCandidate(sizeBytes) {
+  return Number.isFinite(sizeBytes) && sizeBytes <= EMPTY_DECODE_LIMIT
 }

package/src/move-notices.js

@@ -0,0 +1,129 @@
+// move-notices.js — 排队移动「后台终局」的持久通知（3.7.0 T2）。
+//
+// 背景（UX 黑洞）：排队移动发起时有诚实的「已排队」提示，但**后台完成/最终放弃**
+// 原先只 console.warn——用户合上页面就永远不知道结果。本模块把每次终局落成一条
+// 独立通知，经 sidebar-state 带出、client 弹出、ack 后清除。
+//
+// 为什么是独立文件而不是 pending-moves.json 加字段：排队的两个终局（成功 remove、
+// 放弃 bumpAttempts→dropped）都会把条目从 items 里删掉——挂在条目上的字段与载体
+// 同生共死，恰恰在两个目标场景里都观察不到。独立文件另外两点好处：pending-moves
+// 的 items 形状与 schemaVersion 保持 1 不动（旧 host 读新文件不可见，回滚零影响）；
+// 通知的生命周期（服务端保留到 ack + 7 天 TTL + 20 条截断）与队列互不干扰。
+//
+// 投递语义：**留在服务端直到 client ack**——pop 式投递会被「toast 没弹用户就关了
+// 页面」直接丢通知。同浏览器多 tab 的即时去重靠 client 的 localStorage 已见集合，
+// ack 只是尽力清理（ack 失败无害，TTL 兜底）。
+//
+// 写入沿用本仓库索引的既定纪律：schemaVersion + 串行 mutation + 原子写（tmp →
+// rename）+ 0600 + 防御式归一化（坏数据逐条丢弃，坏文件当空集合）。
+import { readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const SCHEMA_VERSION = 1
+// env 在 create 时读取而非模块加载时冻结（测试动态导入的既定模式；生产单实例两可）。
+export const MAX_NOTICES = 20
+export const NOTICE_MAX_AGE_MS = 7 * 24 * 3600 * 1000
+const KINDS = new Set(['moved', 'abandoned'])
+
+function isSafeId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 200
+}
+function str(v, max) {
+  return typeof v === 'string' && v ? v.slice(0, max) : null
+}
+
+export function normalizeNotice(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  if (!KINDS.has(raw.kind) || !isSafeId(raw.sessionId)) return null
+  const at = Number.isFinite(raw.at) && raw.at > 0 ? Math.floor(raw.at) : 0
+  if (!at) return null
+  const sessionId = String(raw.sessionId)
+  return {
+    id: str(raw.id, 400) || `${sessionId}:${raw.kind}:${at}`,
+    kind: raw.kind,
+    sessionId,
+    targetPath: str(raw.targetPath, 500),
+    attempts: Number.isSafeInteger(raw.attempts) && raw.attempts >= 0 ? raw.attempts : null,
+    reason: str(raw.reason, 300),
+    at,
+  }
+}
+
+function normalizeStore(raw) {
+  const source = raw && Array.isArray(raw.items) ? raw.items : []
+  const seen = new Set()
+  const items = []
+  for (const entry of source) {
+    const n = normalizeNotice(entry)
+    if (!n || seen.has(n.id)) continue
+    seen.add(n.id)
+    items.push(n)
+  }
+  items.sort((a, b) => a.at - b.at)
+  const trimmed = items.length > MAX_NOTICES ? items.slice(items.length - MAX_NOTICES) : items
+  return { schemaVersion: SCHEMA_VERSION, items: trimmed }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.dir] 通知文件所在目录（测试注入临时目录）
+ */
+export function createMoveNoticeStore(options = {}) {
+  const dir = options.dir
+    || process.env.DSH_SESSIONS_MANAGER_PENDING_DIR
+    || process.env.DSH_SESSIONS_MANAGER_STAR_DIR
+    || join(homedir(), '.dsh', 'sessions-manager')
+  const indexPath = options.indexPath || join(dir, 'move-notices.json')
+  let mutation = Promise.resolve()
+
+  function read() {
+    try {
+      return normalizeStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch (e) {
+      return normalizeStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.move-notices-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  return {
+    indexPath,
+    // 终局落一条通知；同 id（会话+类型+时刻）幂等去重。
+    append: (notice) => mutate((store) => {
+      const n = normalizeNotice(notice)
+      if (!n) return null
+      if (store.items.some((x) => x.id === n.id)) return n
+      store.items.push(n)
+      return n
+    }),
+    // 只读列出未过期、未 ack 的通知（按时间升序）。过期项在下次写入时随归一化清掉。
+    async list() {
+      const now = Date.now()
+      return read().items.filter((n) => now - n.at <= NOTICE_MAX_AGE_MS)
+    },
+    ack: (ids) => mutate((store) => {
+      const drop = new Set((Array.isArray(ids) ? ids : []).filter((v) => typeof v === 'string' && v.length <= 400).map(String))
+      const before = store.items.length
+      store.items = store.items.filter((n) => !drop.has(n.id))
+      return before - store.items.length
+    }),
+  }
+}

package/src/saved-filters.js

@@ -0,0 +1,208 @@
+// Durable "saved filters" store (schema v1).
+//
+// Same discipline as src/star-index.js / src/tag-index.js: version field,
+// per-entry defensive normalize, atomic write (tmp + rename at 0o600) and a
+// single chained mutation queue. Filter payloads are OPAQUE JSON: the host
+// never interprets them (the UI round-trips its own chip state); we only
+// bound the serialized size so a corrupt entry can never bloat the state
+// file. Lives in the plugin state directory next to tags.json.
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// v1 is the first saved-filters schema. Unlike tags.json (which starts at v4
+// to dodge star's v3) this document lives in its own file and can begin
+// counting from 1.
+export const FILTER_SCHEMA_VERSION = 1
+
+// Caps: ≤20 saved filters, ≤40 code points per name (Array.from counting),
+// ≤2048 characters of serialized JSON per payload.
+export const MAX_FILTERS = 20
+export const MAX_FILTER_NAME = 40
+export const MAX_FILTER_JSON = 2048
+
+// Same state directory (and same env override) as the star / tag indexes.
+const DEFAULT_FILTER_DIR = join(homedir(), '.dsh', 'sessions-manager')
+
+const FILTER_ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789'
+
+function randomSuffix() {
+  const bytes = randomBytes(8)
+  let out = ''
+  for (const b of bytes) out += FILTER_ID_ALPHABET[b % FILTER_ID_ALPHABET.length]
+  return out
+}
+
+function isSafeFilterId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 64 && !/[\\/\0]/.test(value)
+}
+
+function filterError(message, status, code) {
+  const error = new Error(message)
+  error.status = status
+  if (code) error.code = code
+  throw error
+}
+
+function normalizeFilterName(value) {
+  if (typeof value !== 'string') return null
+  const name = value.trim()
+  if (!name || /[\\/\0]/.test(name)) return null
+  if (Array.from(name).length > MAX_FILTER_NAME) return null
+  return name
+}
+
+function nameKey(name) {
+  return name.toLocaleLowerCase()
+}
+
+// Serialize an opaque payload, or null when it cannot be stored (not JSON at
+// all — e.g. undefined/functions — or beyond the size cap).
+function normalizeFiltersPayload(value) {
+  let serialized
+  try {
+    serialized = JSON.stringify(value)
+  } catch {
+    return null
+  }
+  if (typeof serialized !== 'string' || serialized.length > MAX_FILTER_JSON) return null
+  try {
+    return JSON.parse(serialized)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Coerce anything on disk (or nothing at all) into a valid v1 store.
+ * A dirty entry (bad id/name, unserializable or oversize payload, duplicate
+ * id / casefold-duplicate name) is dropped whole, never partially repaired.
+ */
+export function normalizeFilterStore(raw) {
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null
+  const items = []
+  const ids = new Set()
+  const names = new Set()
+  for (const item of (source && Array.isArray(source.items) ? source.items : [])) {
+    if (!item || typeof item !== 'object') continue
+    if (!isSafeFilterId(item.id) || ids.has(item.id)) continue
+    const name = normalizeFilterName(item.name)
+    if (name === null) continue
+    const key = nameKey(name)
+    if (names.has(key)) continue
+    const filters = normalizeFiltersPayload(item.filters)
+    if (filters === null) continue
+    ids.add(item.id)
+    names.add(key)
+    const createdAt = Number.isFinite(Number(item.createdAt)) ? Number(item.createdAt) : 0
+    items.push({ id: item.id, name, filters, createdAt })
+    if (items.length >= MAX_FILTERS) break
+  }
+  return { schemaVersion: FILTER_SCHEMA_VERSION, items }
+}
+
+/**
+ * Open the saved-filters store.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Directory holding the store (tests inject a temp dir).
+ * @param {string} [options.indexPath] - Full store path, overriding `dir`.
+ */
+export function createSavedFilters(options = {}) {
+  const dir = options.dir || process.env.DSH_SESSIONS_MANAGER_STAR_DIR || DEFAULT_FILTER_DIR
+  const indexPath = options.indexPath || join(dir, 'saved-filters.json')
+  let mutation = Promise.resolve()
+
+  async function read() {
+    try {
+      return normalizeFilterStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch {
+      return normalizeFilterStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.saved-filters-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeFilterStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  // Serialize read-modify-write cycles (same chain semantics as the star index).
+  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
+  }
+
+  function newFilterId(store) {
+    for (let i = 0; i < 16; i++) {
+      const id = `f_${randomSuffix()}`
+      if (!store.items.some((t) => t.id === id)) return id
+    }
+    return filterError('无法生成筛选 id（随机碰撞异常）', 500, 'DSM_FILTER_ID_COLLISION')
+  }
+
+  /**
+   * Save a named filter. `filters` is stored verbatim (opaque to the host).
+   * @param {string} rawName
+   * @param {*} filters
+   * @returns {Promise<{id, name, filters, createdAt}>}
+   * @throws 400 DSM_FILTER_NAME_INVALID | 400 DSM_FILTER_INVALID
+   *         | 400 DSM_FILTER_TOO_LARGE | 409 DSM_FILTER_EXISTS | 409 DSM_FILTER_LIMIT
+   */
+  async function save(rawName, filters) {
+    const name = normalizeFilterName(rawName)
+    if (name === null) filterError(`筛选名无效（非空、不含斜杠、不超过 ${MAX_FILTER_NAME} 个字符）`, 400, 'DSM_FILTER_NAME_INVALID')
+    // Bound the opaque payload before it can ever reach disk, with honest
+    // codes for "not JSON at all" vs. "oversize".
+    let serialized
+    try {
+      serialized = JSON.stringify(filters)
+    } catch {
+      serialized = undefined
+    }
+    if (typeof serialized !== 'string') filterError('筛选条件必须是可 JSON 序列化的数据', 400, 'DSM_FILTER_INVALID')
+    if (serialized === 'null') filterError('筛选条件不能为 null', 400, 'DSM_FILTER_INVALID')
+    if (serialized.length > MAX_FILTER_JSON) filterError(`筛选条件过大（序列化后最多 ${MAX_FILTER_JSON} 字符）`, 400, 'DSM_FILTER_TOO_LARGE')
+    const payload = JSON.parse(serialized)
+    const key = nameKey(name)
+    return mutate((store) => {
+      if (store.items.some((t) => nameKey(t.name) === key)) filterError('同名筛选已存在', 409, 'DSM_FILTER_EXISTS')
+      if (store.items.length >= MAX_FILTERS) filterError(`保存的筛选已达上限（${MAX_FILTERS}）`, 409, 'DSM_FILTER_LIMIT')
+      const item = { id: newFilterId(store), name, filters: payload, createdAt: Date.now() }
+      store.items.push(item)
+      return item
+    })
+  }
+
+  /**
+   * Delete saved filters by id (unknown ids are ignored).
+   * @param {string[]} ids
+   * @returns {Promise<number>} how many items were actually removed.
+   */
+  function remove(ids) {
+    const wanted = new Set((Array.isArray(ids) ? ids : []).filter(isSafeFilterId).map(String))
+    return mutate((store) => {
+      const before = store.items.length
+      store.items = store.items.filter((t) => !wanted.has(t.id))
+      return before - store.items.length
+    })
+  }
+
+  /**
+   * @returns {Promise<Array<{id, name, filters, createdAt}>>}
+   */
+  async function list() {
+    const store = await read()
+    return store.items
+  }
+
+  return { read, write, mutate, list, save, remove, indexPath, dir }
+}