@dijkspicy/opencode-stats-reporter 0.1.3 → 0.1.5

package/contrib/opencode-session-reporter/README.md

@@ -65,7 +65,7 @@ config.json 不存在、JSON 非法、字段缺失或 URL 非法时一律静默
 {
   "schema_version": 1,
   "install_id": "0b3f7e6a-....",
-  "reporter": { "client": "opencode", "version": "0.1.3" },
+  "reporter": { "client": "opencode", "version": "0.1.5" },
   "sessions": [
     {
       "session_id": "ses_...",
@@ -81,13 +81,15 @@ config.json 不存在、JSON 非法、字段缺失或 URL 非法时一律静默
       "session_created_at": 1759000000000,
       "session_title": "每30s自动刷新功能",
       "session_directory": "/opt/projects/BlueRegionUsage",
+      "parent_session_id": "ses_...",
+      "root_session_id": "ses_...",
       "last_activity_at": 1759003600123
     }
   ]
 }
 ```
 
-`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。`session_title` / `session_directory` 取自**同一次** `session.get` 调用（不新增 API 请求），取不到时为 `null`（不是空字符串）。载荷中**不存在** consumer/identity 类字段。
+`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。`session_title` / `session_directory` / `parent_session_id`（取自 `session.get` 的 `parentID`）复用**同一次** `session.get` 调用（不新增 API 请求），取不到时为 `null`（不是空字符串）。`root_session_id` 为沿 `parentID` 回溯到的顶层祖先（深度上限 20、防环；祖先已删除/报错时以最近一次验证成功的会话为根；自身即顶层时等于 `session_id`）。载荷中**不存在** consumer/identity 类字段。
 
 ## 测试
 

package/contrib/opencode-session-reporter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-reporter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "description": "opencode 客户端插件：在会话空闲时聚合各会话（含子代理会话）的 token 用量快照，经有界队列 + 指数退避非阻塞上报；载荷不含消费者身份字段。",

package/contrib/opencode-session-reporter/reporter.test.ts

@@ -78,7 +78,7 @@ const makeClient = (
   messages: Record<string, UsageMessage[]>,
   children: Record<string, string[]> = {},
   /** session.get 的返回元数据；不传则 client 不含 session.get */
-  meta?: { created?: number | null; title?: string | null; directory?: string | null; throws?: boolean },
+  meta?: { created?: number | null; title?: string | null; directory?: string | null; parentID?: string | null; throws?: boolean },
 ): ReporterClient => ({
   session: {
     messages: async (args: { path: { id: string } }) => ({ data: messages[args.path.id] ?? [] }),
@@ -92,7 +92,12 @@ const makeClient = (
                 throw new Error("boom: session.get failed")
               }
             : async () => ({
-                data: { time: { created: meta.created ?? 1_700_000_000_000 }, title: meta.title ?? null, directory: meta.directory ?? null },
+                data: {
+                  time: { created: meta.created ?? 1_700_000_000_000 },
+                  title: meta.title ?? null,
+                  directory: meta.directory ?? null,
+                  parentID: meta.parentID ?? null,
+                },
               }),
         }
       : {}),
@@ -137,6 +142,8 @@ const snap = (sessionID: string, over: Partial<SessionSnapshot> = {}): SessionSn
     session_created_at: null,
     session_title: null,
     session_directory: null,
+    parent_session_id: null,
+    root_session_id: null,
     last_activity_at: 1_000 + snapSeq,
     ...over,
   }
@@ -149,7 +156,9 @@ const SESSION_KEYS = [
   "last_activity_at",
   "message_count",
   "model",
+  "parent_session_id",
   "revision",
+  "root_session_id",
   "session_created_at",
   "session_directory",
   "session_id",
@@ -554,6 +563,181 @@ await runTest("session.get 不存在 → 三个元数据字段均为 null", asyn
   assertEqual(snapshot!.session_created_at, null, "created → null")
 })
 
+/** 辅助：用给定 client 采集，返回指定会话快照的 root_session_id */
+const collectAndRootOf = async (client: ReporterClient, trigger: string, want?: string): Promise<string | null> => {
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession(trigger)
+  const snap = core.queue.drainAll().find((s) => s.session_id === (want ?? trigger))
+  return snap ? snap.root_session_id : null
+}
+
+await runTest("session.get 返回 parentID → 快照/载荷带上 parent_session_id；顶层会话 root 等于自身", async () => {
+  // 顶层会话：无 parentID
+  const topClient = makeClient(
+    { ses_top: [assistantMessage()] },
+    {},
+    { parentID: null, title: "顶层任务", directory: "/opt/x" },
+  )
+  const { core } = makeCore(topClient, { endpoint: "http://e" })
+  await core.collectSession("ses_top")
+  const topSnap = core.queue.drainAll().find((s) => s.session_id === "ses_top")
+  assert(!!topSnap, "应产出快照")
+  assertEqual(topSnap!.parent_session_id, null, "顶层无父")
+  assertEqual(topSnap!.root_session_id, "ses_top", "自身即顶层 → root 等于 session_id")
+
+  // 带父会话的子会话 → 载荷验证
+  const childClient = makeClient({ ses_c: [assistantMessage()] }, { ses_p: ["ses_c"] }, { parentID: "ses_p" })
+  const { fetchFn, calls } = makeFetch("ok")
+  const q = createQueue(50)
+  const core2 = makeCore(childClient, { endpoint: "http://e", queue: q, fetchFn }).core
+  await core2.collectSession("ses_c")
+  const childSnap = q.drainAll().find((s) => s.session_id === "ses_c")
+  assert(!!childSnap, "子会话应产出快照")
+  assertEqual(childSnap!.parent_session_id, "ses_p", "快照 parent_session_id")
+  assertEqual(childSnap!.root_session_id, "ses_p", "root 解析为已验证的顶层")
+
+  q.push(childSnap!)
+  const core3 = makeCore(makeClient({}), { endpoint: "http://e", queue: q, fetchFn }).core
+  await core3.flushOnce()
+  const body = JSON.parse(calls[0]!.init.body ?? "{}")
+  assertEqual(body.sessions[0].parent_session_id, "ses_p", "载荷 parent_session_id")
+  assertEqual(body.sessions[0].root_session_id, "ses_p", "载荷 root_session_id")
+})
+
+await runTest("子会话触发采集时能上溯到根：root_session_id 等于顶层 id", async () => {
+  // 结构：ses_top（顶层） → ses_mid → ses_leaf
+  const client = makeClient(
+    { ses_top: [assistantMessage()], ses_mid: [assistantMessage()], ses_leaf: [assistantMessage()] },
+    { ses_top: ["ses_mid"], ses_mid: ["ses_leaf"] },
+  )
+  const getCalls: string[] = []
+  client.session.get = (async (args: { path: { id: string } }) => {
+    getCalls.push(args.path.id)
+    const parentID = args.path.id === "ses_top" ? null : args.path.id === "ses_mid" ? "ses_top" : "ses_mid"
+    return { data: { time: { created: 1 }, title: `t-${args.path.id}`, directory: "/d", parentID } }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_leaf") // 由最深层子会话触发
+
+  const drained = core.queue.drainAll()
+  const leaf = drained.find((s) => s.session_id === "ses_leaf")
+  const mid = drained.find((s) => s.session_id === "ses_mid")
+  const top = drained.find((s) => s.session_id === "ses_top")
+  assert(!!leaf && !!mid && !!top, "从根开始应连带采集整棵树")
+  assertEqual(leaf!.root_session_id, "ses_top", "leaf root")
+  assertEqual(leaf!.parent_session_id, "ses_mid", "leaf parent")
+  assertEqual(mid!.root_session_id, "ses_top", "mid root")
+  assertEqual(top!.root_session_id, "ses_top", "top root 等于自身")
+  assertEqual(top!.parent_session_id, null, "top 无父")
+  assert(getCalls.includes("ses_top") && getCalls.includes("ses_mid") && getCalls.includes("ses_leaf"), "回溯与采集覆盖全链")
+})
+
+await runTest("同一子会话由不同入口触发，root_session_id 一致", async () => {
+  const parentOf = (id: string) => (id === "ses_top" ? null : "ses_top")
+  const buildClient = () => {
+    const client = makeClient(
+      { ses_top: [assistantMessage()], ses_child: [assistantMessage()] },
+      { ses_top: ["ses_child"] },
+    )
+    client.session.get = (async (args: { path: { id: string } }) => ({
+      data: { time: { created: 1 }, title: null, directory: null, parentID: parentOf(args.path.id) },
+    })) as typeof client.session.get
+    return client
+  }
+
+  // 入口一：子会话自身的空闲信号；入口二：顶层会话的空闲信号
+  const rootFromChild = await collectAndRootOf(buildClient(), "ses_child", "ses_child")
+  const rootFromTop = await collectAndRootOf(buildClient(), "ses_top", "ses_child")
+  assertEqual(rootFromChild, "ses_top", "子会话入口 → root=顶层")
+  assertEqual(rootFromTop, "ses_top", "顶层入口 → 子会话 root=顶层")
+  assertEqual(rootFromChild, rootFromTop, "两个入口解析出的 root 一致")
+})
+
+await runTest("祖先缺失（get 抛错）→ 以最近验证成功的会话为根，不崩溃不丢快照", async () => {
+  // 链：ses_child → ses_ghost（已删除，get 抛错）
+  const client = makeClient({ ses_child: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_ghost") throw new Error("deleted session")
+    return {
+      data: {
+        time: { created: 1 },
+        title: null,
+        directory: null,
+        parentID: args.path.id === "ses_child" ? "ses_ghost" : null,
+      },
+    }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_child")
+  const child = core.queue.drainAll().find((s) => s.session_id === "ses_child")
+  assert(!!child, "主流程不崩溃，快照仍产生")
+  assertEqual(child!.root_session_id, "ses_child", "以最近验证成功的会话为根")
+  assertEqual(child!.parent_session_id, "ses_ghost", "直接父保留（即使其已删除）")
+})
+
+await runTest("血缘完全不可解析（get 全抛错）→ 血缘为 null，退化为从传入 id 采集", async () => {
+  const client = makeClient({ ses_x: [assistantMessage()] }, {}, { throws: true })
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_x")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_x")
+  assert(!!snap, "不崩溃，快照仍产生")
+  assertEqual(snap!.root_session_id, null, "root 不可知 → null")
+  assertEqual(snap!.parent_session_id, null, "parent 不可知 → null")
+})
+
+await runTest("祖先已删除（get 返回 data 缺失）→ 回溯就地停止，root 为最近验证成功的会话", async () => {
+  // 链：ses_leaf → ses_mid（已删除，get 返回 data: undefined） → ses_root（实际不可达）
+  const client = makeClient({ ses_leaf: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_mid") return { data: undefined }
+    if (args.path.id === "ses_leaf")
+      return { data: { time: { created: 1 }, title: null, directory: null, parentID: "ses_mid" } }
+    return { data: { time: { created: 1 }, title: null, directory: null, parentID: null } }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_leaf")
+  const leaf = core.queue.drainAll().find((s) => s.session_id === "ses_leaf")
+  assert(!!leaf, "主流程不崩溃，快照仍产生")
+  assertEqual(leaf!.root_session_id, "ses_leaf", "root 应为最近真正取到元数据的 leaf")
+  assert(leaf!.root_session_id !== "ses_mid", "root 不得指向已删除的幽灵会话")
+  assertEqual(leaf!.parent_session_id, "ses_mid", "直接父保留（即使其已删除）")
+})
+
+await runTest("起始节点自身已删除（data 缺失）→ 血缘 null，退化为从传入 id 采集", async () => {
+  const client = makeClient({ ses_ghost: [assistantMessage()] })
+  client.session.get = (async () => ({ data: undefined })) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_ghost")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_ghost")
+  assert(!!snap, "不崩溃；messages 仍可用时快照照常产出")
+  assertEqual(snap!.root_session_id, null, "血缘不可知 → null")
+  assertEqual(snap!.parent_session_id, null, "parent 不可知 → null")
+  assertEqual(snap!.session_title, null, "title 不可知 → null")
+  assertEqual(snap!.session_directory, null, "directory 不可知 → null")
+})
+
+await runTest("存在但字段缺失（无 parentID/time）→ 视为存在的顶层，不误判为已删除", async () => {
+  const client = makeClient({ ses_min: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_min") return { data: { id: "ses_min", title: "T", directory: "/d" } }
+    return { data: undefined }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_min")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_min")
+  assert(!!snap, "应产出快照")
+  assertEqual(snap!.root_session_id, "ses_min", "存在的顶层 → root 等于自身")
+  assertEqual(snap!.parent_session_id, null, "无 parentID → null")
+  assertEqual(snap!.session_title, "T", "title 正常带上")
+  assertEqual(snap!.session_directory, "/d", "directory 正常带上")
+  assertEqual(snap!.session_created_at, null, "无 time → created 为 null")
+})
+
 // ---------------------------------------------------------------------------
 // 汇总
 // ---------------------------------------------------------------------------

package/contrib/opencode-session-reporter/session-usage-reporter.ts

@@ -5,6 +5,9 @@
  * - 在会话空闲（bus 事件 `session.idle`，或 `session.status` 且 `status.type === "idle"`）时，
  *   读取该会话及其全部后代子会话的「已完成」助手消息 token 用量，按会话各自聚合为快照。
  * - 父会话快照绝不并入子会话用量；每个会话（含子代理会话）都是独立记录。
+ * - 血缘字段：parent_session_id = 直接父会话（session.get 的 parentID）；root_session_id = 沿
+ *   parentID 回溯到的顶层祖先（自身即顶层时等于 session_id）。祖先查不到（已删除/报错）时
+ *   就地停止，以最近一次验证成功的会话为根；完全不可解析时血缘为 null。
  * - token 口径原样分列上报（input / output / reasoning / cache.read / cache.write），
  *   不在客户端做任何相加或换算（`output` 不含 reasoning，`input` 不含 cache.read）。
  * - hook 只触发后台采集并入队，绝不等待网络；由后台 flush 统一 POST 到解析出的上报端点
@@ -43,7 +46,7 @@ import { dirname, join } from "node:path"
 // ---------------------------------------------------------------------------
 
 const SCHEMA_VERSION = 1
-const PLUGIN_VERSION = "0.1.3"
+const PLUGIN_VERSION = "0.1.5"
 /** 队列容量：最多积压 500 条会话快照，溢出丢最旧 */
 const QUEUE_CAP = 500
 /** 单次上报请求超时（AbortSignal.timeout） */
@@ -57,6 +60,8 @@ const FLUSH_DEBOUNCE_MS = 250
 const DISPOSE_BUDGET_MS = 3_000
 /** 子会话递归深度上限（防御环/异常数据） */
 const MAX_SESSION_DEPTH = 32
+/** 血缘回溯（向上找顶层祖先）深度上限（防御环/异常数据） */
+const MAX_ANCESTOR_DEPTH = 20
 
 const INSTALL_ID_STATE_FILE = () => join(homedir(), ".local", "state", "opencode-session-reporter", "install_id")
 
@@ -113,6 +118,8 @@ export type SessionSnapshot = {
   session_created_at: number | null
   session_title: string | null
   session_directory: string | null
+  parent_session_id: string | null
+  root_session_id: string | null
   last_activity_at: number | null
 }
 
@@ -148,6 +155,14 @@ export type ReporterClient = {
   }
 }
 
+/** 一次 session.get 能取到的会话元数据；null 表示本次调用失败 / 不可用（get 缺失、抛错、会话已删除） */
+export type SessionMeta = {
+  created: number | null
+  title: string | null
+  directory: string | null
+  parentID: string | null
+}
+
 /** 可注入的定时器（测试用手动调度器替换，避免真实 setTimeout） */
 export type ReporterScheduler = (fn: () => void, delayMs: number) => () => void
 
@@ -260,6 +275,8 @@ const aggregateSessionImpl = (sessionID: string, messages: readonly UsageMessage
     session_created_at: null, // 由采集层补充
     session_title: null, // 由采集层补充（session.get）
     session_directory: null, // 由采集层补充（session.get）
+    parent_session_id: null, // 由采集层补充（session.get 的 parentID）
+    root_session_id: null, // 由采集层补充（血缘回溯解析出的顶层祖先）
     last_activity_at: lastActivity,
   }
 }
@@ -517,52 +534,61 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     return ids
   }
 
-  const readSessionMeta = async (
-    sessionID: string,
-  ): Promise<{ created: number | null; title: string | null; directory: string | null }> => {
+  const fetchSessionMeta = async (sessionID: string): Promise<SessionMeta | null> => {
     try {
       const getSession = options.client.session.get
-      if (typeof getSession !== "function") return { created: null, title: null, directory: null }
+      if (typeof getSession !== "function") return null
       const response = await getSession.call(options.client.session, { path: { id: sessionID }, query: query() })
       const data = (
         response as
-          | { data?: { time?: { created?: unknown }; title?: unknown; directory?: unknown } }
+          | { data?: { time?: { created?: unknown }; title?: unknown; directory?: unknown; parentID?: unknown } }
           | undefined
       )?.data
-      const created = data?.time?.created
-      const title = data?.title
-      const directory = data?.directory
+      // 「取不到会话」（data 缺失 / null / 非对象，典型为会话已删除）必须与
+      // 「取到了但某些字段缺失」区分开：前者返回 null，血缘回溯据此就地停止，
+      // 不得把该会话当作已验证的祖先（否则 root 会指向幽灵会话）。
+      if (!data || typeof data !== "object" || Array.isArray(data)) return null
+      const created = data.time?.created
+      const parentID = data.parentID
       return {
         created: typeof created === "number" ? created : null,
-        title: typeof title === "string" && title ? title : null,
-        directory: typeof directory === "string" && directory ? directory : null,
+        title: typeof data.title === "string" && data.title ? data.title : null,
+        directory: typeof data.directory === "string" && data.directory ? data.directory : null,
+        parentID: typeof parentID === "string" && parentID ? parentID : null,
       }
     } catch {
-      // session.get 抛错 / 形状异常：元数据缺省为 null，绝不影响采集主流程
-      return { created: null, title: null, directory: null }
+      // session.get 抛错 / 形状异常：元数据不可用（null），绝不影响采集主流程
+      return null
     }
   }
 
-  /** 递归聚合会话及其后代；每个会话独立成快照，父快照不含子用量 */
+  /**
+   * 递归聚合会话及其后代；每个会话独立成快照，父快照不含子用量。
+   * rootSessionID 为血缘回溯解析出的顶层祖先（不可解析时为 null）；metaGet 为单次采集运行内的
+   * 元数据缓存读取器（血缘回溯与递归采集共用同一次 session.get 结果，不新增 API 请求）。
+   */
   const collectRecursive = async (
     sessionID: string,
     out: SessionSnapshot[],
     visited: Set<string>,
     depth: number,
+    rootSessionID: string | null,
+    metaGet: (id: string) => Promise<SessionMeta | null>,
   ): Promise<void> => {
     if (!sessionID || visited.has(sessionID) || depth > MAX_SESSION_DEPTH || visited.size >= QUEUE_CAP) return
     visited.add(sessionID)
     const snapshot = aggregateSessionImpl(sessionID, await readMessages(sessionID))
     if (snapshot) {
-      // 复用同一次 session.get：created / title / directory 一并取得，不新增 API 请求
-      const meta = await readSessionMeta(sessionID)
-      snapshot.session_created_at = meta.created
-      snapshot.session_title = meta.title
-      snapshot.session_directory = meta.directory
+      const meta = await metaGet(sessionID)
+      snapshot.session_created_at = meta?.created ?? null
+      snapshot.session_title = meta?.title ?? null
+      snapshot.session_directory = meta?.directory ?? null
+      snapshot.parent_session_id = meta?.parentID ?? null
+      snapshot.root_session_id = rootSessionID
       out.push(snapshot)
     }
     for (const childID of await readChildIDs(sessionID)) {
-      await collectRecursive(childID, out, visited, depth + 1)
+      await collectRecursive(childID, out, visited, depth + 1, rootSessionID, metaGet)
     }
   }
 
@@ -571,8 +597,37 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     if (inFlight.has(sessionID)) return // 同一会话采集中：跳过，下次空闲信号再采
     inFlight.add(sessionID)
     try {
+      // 单次采集运行内的元数据缓存：血缘回溯与递归采集共用同一次 session.get 结果。
+      // 顶层会话的常见路径（get 一次、无 parent）不产生任何额外 API 请求。
+      const metaCache = new Map<string, SessionMeta | null>()
+      const metaGet = async (id: string): Promise<SessionMeta | null> => {
+        if (metaCache.has(id)) return metaCache.get(id) ?? null
+        const meta = await fetchSessionMeta(id)
+        metaCache.set(id, meta)
+        return meta
+      }
+
+      // 1) 血缘回溯：从触发会话沿 parentID 向上找顶层祖先。
+      //    边界：深度上限 MAX_ANCESTOR_DEPTH、visitedAncestors 防环（含自父）；
+      //    祖先查不到（已删除 / get 抛错 / 不可用）就地停止，以「最近一次验证成功的会话」为根；
+      //    起始节点自身查不到 → 根不可知（null），退化为从传入 id 开始采集。
+      const visitedAncestors = new Set<string>([sessionID])
+      let current = sessionID
+      let verifiedRoot: string | null = null
+      for (let depth = 0; depth < MAX_ANCESTOR_DEPTH; depth++) {
+        const meta = await metaGet(current)
+        if (!meta) break // 查不到：就地停止
+        verifiedRoot = current
+        const parentID = meta.parentID
+        if (!parentID || visitedAncestors.has(parentID)) break // 到顶 / 环 / 自父
+        visitedAncestors.add(parentID)
+        current = parentID
+      }
+
+      // 2) 从根开始递归采集（同一次空闲信号能连带刷新所有兄弟会话）
+      const startID = verifiedRoot ?? sessionID
       const out: SessionSnapshot[] = []
-      await collectRecursive(sessionID, out, new Set(), 0)
+      await collectRecursive(startID, out, new Set(), 0, verifiedRoot, metaGet)
       for (const snapshot of out) queue.push(snapshot)
       if (out.length > 0) scheduleFlush()
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dijkspicy/opencode-stats-reporter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "本地一体化 MaaS 用量看板：托管静态面板、反代用量接口、本地存储会话用量",
   "type": "module",
   "main": "./contrib/opencode-session-reporter/plugin-server.ts",

package/panel/css/style.css

@@ -562,6 +562,34 @@ body {
   .sess-dir { max-width: 120px; }
 }
 
+/* 任务分组：顶层会话行充当组头（徽标 + 组间留白），子会话缩进并以左侧竖线挂在任务下 */
+#session-table tr.sess-task > td { padding-top: 14px; }
+tr.sess-task .sess-title-line { display: flex; align-items: center; gap: 6px; }
+.sess-task-badge {
+  flex: none;
+  padding: 0 7px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--text-secondary);
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 16px;
+}
+#session-table tr.sess-child .sess-cell { position: relative; padding-left: 30px; }
+#session-table tr.sess-child .sess-cell::before {
+  content: "";
+  position: absolute;
+  left: 14px;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--border);
+}
+
+/* 根会话不在已加载结果中时的合成组头：只声明归属，不虚构任务名 */
+tr.sess-orphan-head > td { font-size: 11px; color: var(--text-secondary); padding-top: 14px; }
+#session-table tbody tr.sess-orphan-head:hover { background: transparent; }
+
 /* 会话 ID：默认弱化（有标题时），等宽头尾截断，完整值在 title，点击进详情 */
 .sess-id-btn {
   display: inline-block;

package/panel/index.html

@@ -296,7 +296,7 @@
           <table id="session-table" class="session-table">
             <thead>
               <tr>
-                <th title="优先显示会话标题，无标题时显示会话 ID；下方小字为会话所属项目目录，悬浮可看完整路径">会话</th>
+                <th title="同一顶层任务的会话归为一组：顶层会话标「任务」，子会话缩进挂在其下；组按最近活动排序，根会话不在当前结果时以灰字注明">会话</th>
                 <th>模型</th>
                 <th>代理</th>
                 <th class="num" title="输入总量 = 输入 + 缓存读 + 缓存写">输入总量</th>

package/panel/js/sessions.js

@@ -2,7 +2,7 @@
  * 会话视图：客户端上报的会话级 token 用量
  * 数据源：/v1/sessions*（客户端上报，可能延迟/遗漏，非网关权威数据）
  * token 口径（已实测验证）：输入总量 = 输入 + 缓存读 + 缓存写；输出总量 = 输出 + 推理（推理单列，不并入输出）
- * 结构：来源声明 → 用量对账（网关权威总量 − 会话上报合计 = 未归属用量）→ 会话列表（窗口/模型/代理筛选 + 游标分页）→ 会话详情
+ * 结构：来源声明 → 用量对账（网关权威总量 − 会话上报合计 = 未归属用量）→ 会话列表（按顶层任务分组 + 窗口/模型/代理筛选 + 游标分页）→ 会话详情
  * 由 app.js 初始化：BRU.sessions.init({ getCfg, getPeriod, getModelCatalog, onUnauthorized })，并经 BRU.sessions.load() 触发拉取
  */
 (function () {
@@ -190,10 +190,57 @@
   }
 
   // ---------- 会话列表 ----------
+  /**
+   * 按顶层任务组织页内呈现（不改变拉取与游标逻辑，服务端排序保持 last_activity_at 倒序）：
+   * - root_session_id 为空或等于自身 → 独立任务行（契约：顶层会话 root 等于自身；旧数据为 null 时同样按顶层处理）
+   * - 子会话按 root_session_id 归组；根已加载则根行充当组头，根不在已加载行中则落合成组头（orphanHeadRow）
+   * - 组间按组内最近活动倒序；组内根在前，子会话保持服务端返回顺序（即最近活动倒序）
+   */
   function renderRows() {
     var tbody = el.tbody;
     tbody.innerHTML = '';
-    st.rows.forEach(function (r) { tbody.appendChild(sessionRow(r)); });
+    buildGroups(st.rows).forEach(function (g) {
+      if (g.rootRow) tbody.appendChild(sessionRow(g.rootRow, 'task'));
+      else tbody.appendChild(orphanHeadRow(g.key));
+      g.children.forEach(function (r) { tbody.appendChild(sessionRow(r, 'child')); });
+    });
+  }
+
+  function buildGroups(rows) {
+    var map = {};
+    var list = [];
+    function group(key, idx) {
+      if (!map[key]) { map[key] = { key: key, rootRow: null, children: [], newest: -Infinity, idx: idx }; list.push(map[key]); }
+      return map[key];
+    }
+    rows.forEach(function (r, i) {
+      var sid = nonEmpty(r.session_id);
+      var rootId = nonEmpty(r.root_session_id);
+      var isTop = !sid || !rootId || rootId === sid;
+      var g = group(isTop ? (sid || '\u0000' + i) : rootId, i);
+      if (isTop) g.rootRow = r;
+      else g.children.push(r);
+      var act = Number(r.last_activity_at);
+      if (isFinite(act) && act > g.newest) g.newest = act;
+    });
+    list.sort(function (a, b) { return b.newest - a.newest || a.idx - b.idx; });
+    return list;
+  }
+
+  /** 根会话不在已加载行中（分页未到 / 窗口或筛选未含根 / 旧数据）时的合成组头：只声明归属，不虚构任务名 */
+  function orphanHeadRow(rootId) {
+    var tr = document.createElement('tr');
+    tr.className = 'sess-orphan-head';
+    var c = document.createElement('td');
+    c.colSpan = 10;
+    c.textContent = '所属顶层会话不在当前列表 · ';
+    var id = document.createElement('span');
+    id.className = 'mono';
+    id.textContent = shortId(rootId);
+    id.title = rootId + '\n根会话 ID（未在当前结果中）';
+    c.appendChild(id);
+    tr.appendChild(c);
+    return tr;
   }
 
   /** 空值守卫：非字符串或空白串返回 null，避免把 null/undefined/空串渲染到页面 */
@@ -214,6 +261,16 @@
     return '…/' + parts.slice(-2).join('/');
   }
 
+  /**
+   * 子代理会话标题尾部「 (@xxx subagent)」与「代理」列信息重复，展示时去掉；完整原标题始终保留在悬浮。
+   * 仅在后缀中的代理名与该行 agent 字段一致时才去（不一致说明后缀另有含义，原样保留）。
+   */
+  function displayTitle(title, agent) {
+    var m = title.match(/\s*\(@([^\s()]+) subagent\)$/);
+    if (m && agent && m[1] === agent) return title.slice(0, m.index).replace(/\s+$/, '');
+    return title;
+  }
+
   /** 会话 ID 按钮：等宽展示（头尾截断），完整值放 title，点击进详情；primary = 无标题时作为降级主标识 */
   function idButton(sid, primary) {
     var b = document.createElement('button');
@@ -229,9 +286,12 @@
    * 首列「会话」：两行结构
    *   主行：会话标题（加粗）；无标题时降级为会话 ID（等宽、高亮、可点）
    *   次行：项目目录（末两级压缩，悬浮显全路径）· 会话 ID（弱化；ID 已作主标识时不重复）
+   * role：task = 顶层任务行（带「任务」徽标，作为组头）；child = 子会话（CSS 缩进 + 挂线）；其余 = 独立行
    */
-  function sessionRow(r) {
+  function sessionRow(r, role) {
     var tr = document.createElement('tr');
+    if (role === 'task') tr.className = 'sess-task';
+    else if (role === 'child') tr.className = 'sess-child';
     var title = nonEmpty(r.session_title);
     var dir = nonEmpty(r.session_directory);
     var sid = nonEmpty(r.session_id) || '--';
@@ -241,10 +301,16 @@
 
     var line1 = document.createElement('div');
     line1.className = 'sess-title-line';
+    if (role === 'task') {
+      var badge = document.createElement('span');
+      badge.className = 'sess-task-badge';
+      badge.textContent = '任务';
+      line1.appendChild(badge);
+    }
     if (title) {
       var t = document.createElement('span');
       t.className = 'sess-title';
-      t.textContent = title;
+      t.textContent = displayTitle(title, nonEmpty(r.agent));
       t.title = title + '\n点击查看详情';
       t.addEventListener('click', function () { openDetail(sid); });
       line1.appendChild(t);
@@ -381,6 +447,8 @@
     body.appendChild(group('会话信息', [
       item('会话标题', nonEmpty(d.session_title) || '--'),
       item('项目目录', nonEmpty(d.session_directory) || '--', true),
+      item('根会话', nonEmpty(d.root_session_id) || '--', true),
+      item('父会话', nonEmpty(d.parent_session_id) || '--', true),
       item('模型', d.model || '--'),
       item('代理', d.agent || '--'),
       item('安装标识', d.install_id || '--', true),

package/src/session-api.js

@@ -73,6 +73,7 @@ export function listSessions(store, consumer, params) {
     model: params.get("model") || undefined,
     agent: params.get("agent") || undefined,
     installId: params.get("install_id") || undefined,
+    rootSessionId: params.get("root_session_id") || undefined,
     limit,
     cursor: cursorRaw ? decodeCursor(cursorRaw) : null,
   })

package/src/store.js

@@ -31,6 +31,8 @@ CREATE TABLE IF NOT EXISTS session_usage (
   last_reported_at      INTEGER NOT NULL,
   session_title         TEXT,
   session_directory     TEXT,
+  parent_session_id     TEXT,
+  root_session_id       TEXT,
   PRIMARY KEY (consumer_id, install_id, session_id)
 );
 CREATE INDEX IF NOT EXISTS idx_su_consumer_activity ON session_usage(consumer_id, last_activity_at DESC);
@@ -93,6 +95,8 @@ export function sanitizeRecord(raw) {
     client_session_header: str(raw.client_session_header),
     session_title: str(raw.session_title, 300),
     session_directory: str(raw.session_directory, 512),
+    parent_session_id: str(raw.parent_session_id, 200),
+    root_session_id: str(raw.root_session_id, 200),
   }
 }
 
@@ -125,7 +129,12 @@ export class Store {
     const existing = new Set(
       this.db.prepare("PRAGMA table_info(session_usage)").all().map((r) => r.name),
     )
-    for (const [name, type] of [["session_title", "TEXT"], ["session_directory", "TEXT"]]) {
+    for (const [name, type] of [
+      ["session_title", "TEXT"],
+      ["session_directory", "TEXT"],
+      ["parent_session_id", "TEXT"],
+      ["root_session_id", "TEXT"],
+    ]) {
       if (!existing.has(name)) {
         this.db.exec(`ALTER TABLE session_usage ADD COLUMN ${name} ${type}`)
       }
@@ -149,19 +158,22 @@ export class Store {
     let accepted = 0
     let skipped = 0
     const find = this.db.prepare(
-      "SELECT revision, last_activity_at FROM session_usage WHERE consumer_id=? AND install_id=? AND session_id=?",
+      "SELECT revision, last_activity_at, session_title, session_directory, parent_session_id, root_session_id FROM session_usage WHERE consumer_id=? AND install_id=? AND session_id=?",
+    )
+    const backfill = this.db.prepare(
+      "UPDATE session_usage SET session_title=?, session_directory=?, parent_session_id=?, root_session_id=?, last_reported_at=? WHERE consumer_id=? AND install_id=? AND session_id=?",
     )
     const insert = this.db.prepare(`INSERT INTO session_usage
       (consumer_id, install_id, session_id, source, schema_version, reporter_version, client_session_header,
        model, agent, tokens_input, tokens_output, tokens_reasoning, tokens_cache_read, tokens_cache_write,
        cost, message_count, revision, session_created_at, last_activity_at, client_reported_at,
-       first_seen_at, last_reported_at, session_title, session_directory)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+       first_seen_at, last_reported_at, session_title, session_directory, parent_session_id, root_session_id)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
     const update = this.db.prepare(`UPDATE session_usage SET
       source=?, schema_version=?, reporter_version=?, client_session_header=?, model=?, agent=?,
       tokens_input=?, tokens_output=?, tokens_reasoning=?, tokens_cache_read=?, tokens_cache_write=?,
       cost=?, message_count=?, revision=?, session_created_at=?, last_activity_at=?, client_reported_at=?,
-      last_reported_at=?, session_title=?, session_directory=?
+      last_reported_at=?, session_title=?, session_directory=?, parent_session_id=?, root_session_id=?
       WHERE consumer_id=? AND install_id=? AND session_id=?`)
 
     for (const r of records) {
@@ -173,7 +185,7 @@ export class Store {
           consumerId, r.install_id, r.session_id, source, schemaVersion, reporterVersion, r.client_session_header,
           r.model, r.agent, r.tokens_input, r.tokens_output, r.tokens_reasoning, r.tokens_cache_read, r.tokens_cache_write,
           r.cost, r.message_count, r.revision, r.session_created_at, r.last_activity_at, r.client_reported_at, ts, ts,
-          r.session_title, r.session_directory,
+          r.session_title, r.session_directory, r.parent_session_id, r.root_session_id,
         )
       } else if (r.revision > prev.revision || (r.revision === prev.revision && r.last_activity_at > prev.last_activity_at)) {
         status = "upserted"
@@ -181,22 +193,39 @@ export class Store {
           source, schemaVersion, reporterVersion, r.client_session_header, r.model, r.agent,
           r.tokens_input, r.tokens_output, r.tokens_reasoning, r.tokens_cache_read, r.tokens_cache_write,
           r.cost, r.message_count, r.revision, r.session_created_at, r.last_activity_at, r.client_reported_at, ts,
-          r.session_title, r.session_directory,
+          r.session_title, r.session_directory, r.parent_session_id, r.root_session_id,
           consumerId, r.install_id, r.session_id,
         )
       } else if (r.revision === prev.revision && r.last_activity_at === prev.last_activity_at) {
-        status = "unchanged"
+        // 单调守卫内（revision 与活动时间均未推进）：仅当元数据（含血缘）变化时做「窄更新」回填，
+        // 只写 session_title / session_directory / parent_session_id / root_session_id / last_reported_at，
+        // 不触碰 token 类字段、revision、last_activity_at、source、reporter_version 等计量与守卫字段。
+        const metaChanged =
+          (r.session_title ?? null) !== (prev.session_title ?? null) ||
+          (r.session_directory ?? null) !== (prev.session_directory ?? null) ||
+          (r.parent_session_id ?? null) !== (prev.parent_session_id ?? null) ||
+          (r.root_session_id ?? null) !== (prev.root_session_id ?? null)
+        if (metaChanged) {
+          status = "backfilled"
+          backfill.run(
+            r.session_title ?? null, r.session_directory ?? null,
+            r.parent_session_id ?? null, r.root_session_id ?? null,
+            ts, consumerId, r.install_id, r.session_id,
+          )
+        } else {
+          status = "unchanged"
+        }
       } else {
         status = "stale"
       }
-      if (status === "upserted" || status === "unchanged") accepted += 1
+      if (status === "upserted" || status === "unchanged" || status === "backfilled") accepted += 1
       else skipped += 1
       results.push({ session_id: r.session_id, install_id: r.install_id, status })
     }
     return { accepted, skipped, results }
   }
 
-  listSessions(consumerId, { window, model, agent, installId, limit = 50, cursor = null } = {}) {
+  listSessions(consumerId, { window, model, agent, installId, rootSessionId, limit = 50, cursor = null } = {}) {
     const where = ["consumer_id=?"]
     const args = [consumerId]
     const start = windowStartMs(window)
@@ -216,6 +245,11 @@ export class Store {
       where.push("install_id=?")
       args.push(installId)
     }
+    if (rootSessionId) {
+      // 按顶层任务筛选：同一 root 下的全部会话（含根自身）
+      where.push("root_session_id=?")
+      args.push(rootSessionId)
+    }
     if (cursor) {
       where.push("(last_activity_at < ? OR (last_activity_at = ? AND session_id < ?))")
       args.push(cursor[0], cursor[0], cursor[1])