dsh-group-status 0.2.2 → 0.3.0

package/lib/types/client/facets.js

@@ -0,0 +1,209 @@
+/** 本协议文件的协议版本。provider 必须原样填这个常量。 */
+export const GROUP_STATUS_FACET_PROTOCOL_VERSION = 1;
+/** tone 之间的优先级（越大越紧急），用于多层合并时取更高档。 */
+export const FACET_TONE_RANK = Object.freeze({
+    info: 0, warn: 1, error: 2,
+});
+/**
+ * 同 id 冲突时**由来源决胜，与注册顺序无关**。
+ *
+ * 宿主不保证插件 apply 的先后。过渡期内"本插件代 provider 写的适配器"与"provider
+ * 自己注册的 facet"会撞同一个 id：若靠顺序决胜，同一份部署今天显示、明天不显示。
+ * `provider` 恒胜 `legacy`：所有者一接入，代管方立刻让位，且不重复计数。迁移因此
+ * 不需要协商发布顺序。
+ */
+export const FACET_ORIGIN_RANK = Object.freeze({
+    legacy: 0, provider: 1,
+});
+/** 一个 facet 的来源；缺省按 `provider`（最保守的假设：别人主动注册就是所有者）。 */
+export function facetOrigin(facet) {
+    return facet.origin === 'legacy' ? 'legacy' : 'provider';
+}
+// #25③：此处原有 `const TONE_ORDER = ['info','warn','error']`，与对外导出的
+// `FACET_TONE_RANK` 是同一个事实的两份实现，且只有 `defaultMergeFold` 一个使用者。
+// 现已统一到 `FACET_TONE_RANK`（见该函数），私有那份删除。
+/**
+ * 检查一个 facet 是否符合协议 v1。
+ * @returns 拒绝原因；`undefined` 表示可用。
+ */
+export function facetRejection(facet) {
+    if (typeof facet !== 'object' || facet === null)
+        return 'not-an-object';
+    const candidate = facet;
+    if (candidate.protocol !== GROUP_STATUS_FACET_PROTOCOL_VERSION)
+        return 'protocol-mismatch';
+    if (typeof candidate.id !== 'string' || candidate.id === '')
+        return 'missing-id';
+    if (typeof candidate.subscribe !== 'function'
+        || typeof candidate.getSnapshot !== 'function'
+        || typeof candidate.fold !== 'function')
+        return 'missing-methods';
+    return undefined;
+}
+/**
+ * 缺省折果合并：数量相加、色档取更紧急的一档、脉冲取或。
+ *
+ * ⚠️ 它**不**合并 `data`（本插件不知道 `data` 是什么）。需要合并原始事实的 facet
+ * 必须自己实现 {@link GroupStatusFacet.merge}。
+ */
+export function defaultMergeFold(a, b) {
+    // #25③：读对外导出的 `FACET_TONE_RANK`，不再另持一份私有 `TONE_ORDER`。两份表的顺序
+    // 逐项相同（`{info:0,warn:1,error:2}` 与 `['info','warn','error']` 的下标一致），所以对
+    // 合法色档这是**零行为变更**；收口的是「同一个事实两份实现」本身。
+    //
+    // ⚠️ `?? -1` **不是防御性冗余，是负载性的，别顺手删**。`facetRejection` 只校验
+    // protocol / id / 三个方法，**不校验 `fold()` 返回的 `tone`** —— 那是跨插件边界，坏
+    // provider 交回一个非法档位是真能到达这里的。旧的 `TONE_ORDER.indexOf(非法值)` 得到
+    // `-1`，于是另一侧的合法档位必胜（`2 > -1`）；而 `FACET_TONE_RANK[非法值]` 得到
+    // `undefined`，任何比较都是 `false`，非法档位就会被**传播出去**。少了这个 `?? -1`，
+    // 本次重构会在坏输入下静默改变结果。
+    const toneA = FACET_TONE_RANK[a.tone] ?? -1;
+    const toneB = FACET_TONE_RANK[b.tone] ?? -1;
+    return {
+        count: a.count + b.count,
+        tone: toneB > toneA ? b.tone : a.tone,
+        pulse: a.pulse || b.pulse,
+    };
+}
+/** 创建一张登记表面（测试用；生产走模块级单例 {@link registry}）。 */
+export function createFacetRegistry() {
+    const entries = new Map();
+    const listeners = new Set();
+    let sequence = 0;
+    let sorted = [];
+    const resort = () => {
+        sorted = [...entries.values()].sort((x, y) => {
+            // 排序键 = (有没有声明 order, order, 注册序号)。
+            // 没声明 order 的来源一律排在**所有声明过的之后**，彼此按注册先后：陌生新来者
+            // 不该插到既有状态前面抢视觉位置，而两两之间又没有可比的新排序键。
+            const declaredX = x.facet.order !== undefined;
+            const declaredY = y.facet.order !== undefined;
+            if (declaredX !== declaredY)
+                return declaredX ? -1 : 1;
+            if (declaredX && declaredY)
+                return x.facet.order - y.facet.order;
+            return x.sequence - y.sequence;
+        });
+    };
+    let notifying = false;
+    let pending = false;
+    /**
+     * 通知订阅者，并把**重入合并成一轮补跑**。
+     *
+     * 订阅者在自己的回调里登记/注销 facet 是完全合法的（消费方常在收到变更后立即
+     * 补登记一个派生来源）。直接递归会有两个问题：嵌套深度由订阅者数量决定（两个互相
+     * 触发的订阅者就是无界递归），而且中间那轮通知看到的登记面是**改到一半**的。
+     * 所以内层调用只置脏标志，外层跑完一轮后再补一轮，直到没有新的改动 —— 每个订阅者
+     * 都看得到最终状态，递归深度恒为 1。
+     */
+    const notify = () => {
+        if (notifying) {
+            pending = true;
+            return;
+        }
+        notifying = true;
+        try {
+            do {
+                pending = false;
+                // 复制一份再遍历：订阅者可能在回调里退订自己。
+                for (const listener of [...listeners]) {
+                    try {
+                        listener();
+                    }
+                    catch {
+                        /* 单个订阅者异常不影响其余订阅者 */
+                    }
+                }
+            } while (pending);
+        }
+        finally {
+            notifying = false;
+            pending = false;
+        }
+    };
+    return {
+        register: (facet) => {
+            const reason = facetRejection(facet);
+            const id = typeof facet?.id === 'string' ? facet.id : '';
+            if (reason !== undefined)
+                return { ok: false, id, reason };
+            const existing = entries.get(id);
+            const nextRank = FACET_ORIGIN_RANK[facetOrigin(facet)];
+            if (existing !== undefined && FACET_ORIGIN_RANK[facetOrigin(existing.facet)] > nextRank) {
+                // 同 id 上站着更高来源的登记（状态所有者已经自己接入），低的一边让位。
+                return { ok: false, id, reason: 'superseded' };
+            }
+            sequence += 1;
+            // 同来源重复登记直接覆盖：provider 热替换实现不必先注销再登记。
+            entries.set(id, { facet, sequence });
+            resort();
+            notify();
+            return { ok: true, id };
+        },
+        remove: (id, facet) => {
+            const current = entries.get(id);
+            if (current === undefined)
+                return false;
+            if (facet !== undefined && current.facet !== facet)
+                return false;
+            entries.delete(id);
+            resort();
+            notify();
+            return true;
+        },
+        list: () => sorted,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/**
+ * 生产用的模块级单例登记表面。
+ *
+ * 与 {@link createFacetRegistry} 分开，是为了让测试能对着一张干净的表断言协议行为，
+ * 而不会被别的用例或别的插件登记的 facet 污染。
+ */
+export const registry = createFacetRegistry();
+/**
+ * 本插件 client 入口对外的登记函数（provider 侧唯一需要认识的符号）。
+ *
+ * @param facet - 待登记的 facet。
+ * @returns 注销函数；**注册失败时返回一个空操作**，同时把原因写进 console——
+ *   返回值形状保持稳定，provider 的 dispose 路径不必区分成败。
+ */
+export function registerGroupStatusFacet(facet) {
+    const result = registry.register(facet);
+    if (!result.ok) {
+        // 过渡期适配器被状态所有者顶掉是**预期结果**，不是错误：报一条 warn 会让人以为
+        // 徽标坏了。除此之外的每一次失败都必须可见，否则"注册了却没显示"无从诊断。
+        if (!(result.reason === 'superseded' && facetOrigin(facet) === 'legacy'))
+            reportRejection(result);
+        return () => undefined;
+    }
+    // 只摘"还是自己"的那一份：同 id 已被后来的实现替换时，旧 dispose 不该动新登记。
+    return () => {
+        registry.remove(result.id, facet);
+    };
+}
+/**
+ * 把注册失败写成一条可诊断的日志。
+ *
+ * 刻意不抛错：状态显示是增强功能，一个插件协议填错不该把宿主界面渲染打断；
+ * 但也不静默——"注册了却没显示"必须能查出原因。
+ */
+function reportRejection(rejection) {
+    const detail = rejection.reason === 'protocol-mismatch'
+        ? `本插件只接受 protocol: ${GROUP_STATUS_FACET_PROTOCOL_VERSION}`
+        : rejection.reason === 'missing-methods'
+            ? 'subscribe / getSnapshot / fold 三个方法必须齐备'
+            : rejection.reason === 'missing-id'
+                ? "id 必须是非空字符串，建议 '<包名>.<状态名>'"
+                : rejection.reason === 'superseded'
+                    ? '同 id 上已有更高来源的登记；两个不同插件用了同一个 id，请各自换名'
+                    : 'facet 必须是一个对象';
+    console.warn(`dsh-group-status: 拒绝登记状态 facet "${rejection.id}"（${rejection.reason}）：${detail}`);
+}
+//# sourceMappingURL=facets.js.map

package/lib/types/client/facets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facets.js","sourceRoot":"","sources":["../../../src/client/facets.ts"],"names":[],"mappings":"AA0DA,qCAAqC;AACrC,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,CAAA;AAKpD,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAwC,MAAM,CAAC,MAAM,CAAC;IAChF,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;CAC3B,CAAC,CAAA;AA6GF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA0C,MAAM,CAAC,MAAM,CAAC;IACpF,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB,CAAC,CAAA;AAEF,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,KAAwC;IAClE,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAA;AAC1D,CAAC;AAiCD,gEAAgE;AAChE,8DAA8D;AAC9D,wCAAwC;AAExC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,eAAe,CAAA;IACvE,MAAM,SAAS,GAAG,KAAkC,CAAA;IACpD,IAAI,SAAS,CAAC,QAAQ,KAAK,mCAAmC;QAAE,OAAO,mBAAmB,CAAA;IAC1F,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAA;IAChF,IACE,OAAO,SAAS,CAAC,SAAS,KAAK,UAAU;WACtC,OAAO,SAAS,CAAC,WAAW,KAAK,UAAU;WAC3C,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU;QACvC,OAAO,iBAAiB,CAAA;IAC1B,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,CAAe;IAC/D,6DAA6D;IAC7D,wEAAwE;IACxE,qCAAqC;IACrC,EAAE;IACF,yDAAyD;IACzD,gEAAgE;IAChE,4DAA4D;IAC5D,0DAA0D;IAC1D,2DAA2D;IAC3D,oBAAoB;IACpB,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3C,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;QACxB,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACrC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK;KAC1B,CAAA;AACH,CAAC;AA8BD,+CAA+C;AAC/C,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAA;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,IAAI,MAAM,GAA+B,EAAE,CAAA;IAE3C,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC3C,oCAAoC;YACpC,8CAA8C;YAC9C,mCAAmC;YACnC,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAA;YAC7C,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAA;YAC7C,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YACtD,IAAI,SAAS,IAAI,SAAS;gBAAE,OAAQ,CAAC,CAAC,KAAK,CAAC,KAAgB,GAAI,CAAC,CAAC,KAAK,CAAC,KAAgB,CAAA;YACxF,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAA;QAChC,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,IAAI,OAAO,GAAG,KAAK,CAAA;IAEnB;;;;;;;;OAQG;IACH,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,GAAG,IAAI,CAAA;YACd,OAAM;QACR,CAAC;QACD,SAAS,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC;YACH,GAAG,CAAC;gBACF,OAAO,GAAG,KAAK,CAAA;gBACf,yBAAyB;gBACzB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;oBACtC,IAAI,CAAC;wBACH,QAAQ,EAAE,CAAA;oBACZ,CAAC;oBAAC,MAAM,CAAC;wBACP,qBAAqB;oBACvB,CAAC;gBACH,CAAC;YACH,CAAC,QAAQ,OAAO,EAAC;QACnB,CAAC;gBAAS,CAAC;YACT,SAAS,GAAG,KAAK,CAAA;YACjB,OAAO,GAAG,KAAK,CAAA;QACjB,CAAC;IACH,CAAC,CAAA;IAED,OAAO;QACL,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;YAClB,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;YACpC,MAAM,EAAE,GAAG,OAAO,KAAK,EAAE,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;YACxD,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAA;YAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAChC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;YACtD,IAAI,QAAQ,KAAK,SAAS,IAAI,iBAAiB,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;gBACxF,uCAAuC;gBACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;YAChD,CAAC;YACD,QAAQ,IAAI,CAAC,CAAA;YACb,sCAAsC;YACtC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;YACpC,MAAM,EAAE,CAAA;YACR,MAAM,EAAE,CAAA;YACR,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;QACzB,CAAC;QACD,MAAM,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC/B,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAA;YACvC,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK;gBAAE,OAAO,KAAK,CAAA;YAChE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAClB,MAAM,EAAE,CAAA;YACR,MAAM,EAAE,CAAA;YACR,OAAO,IAAI,CAAA;QACb,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM;QAClB,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE;YACtB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC5B,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAkB,mBAAmB,EAAE,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAe;IACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IACvC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,8CAA8C;QAC9C,wCAAwC;QACxC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,YAAY,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;YAAE,eAAe,CAAC,MAAM,CAAC,CAAA;QACjG,OAAO,GAAG,EAAE,CAAC,SAAS,CAAA;IACxB,CAAC;IACD,iDAAiD;IACjD,OAAO,GAAG,EAAE;QACV,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;IACnC,CAAC,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,SAAiD;IACxE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,KAAK,mBAAmB;QACrD,CAAC,CAAC,oBAAoB,mCAAmC,EAAE;QAC3D,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,iBAAiB;YACtC,CAAC,CAAC,yCAAyC;YAC3C,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,YAAY;gBACjC,CAAC,CAAC,6BAA6B;gBAC/B,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,YAAY;oBACjC,CAAC,CAAC,sCAAsC;oBACxC,CAAC,CAAC,eAAe,CAAA;IACzB,OAAO,CAAC,IAAI,CAAC,mCAAmC,SAAS,CAAC,EAAE,KAAK,SAAS,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC,CAAA;AACjG,CAAC"}

package/lib/types/client/group-status.d.ts

@@ -5,30 +5,19 @@
  * vendored file only needs one import line and one field assignment to wire
  * the badge aggregation in. Everything fork-specific lives here.
  *
+ * ## 本模块不认识任何具体状态源
+ *
+ * 它只统计宿主自己的行级事实（进行中 / 待审批 / 计划待审 / 等待回答 / 已完成 /
+ * 子智能体）；外部状态一律经 `./facets.ts` 的协议折成 {@link FacetFold}。
+ *
+ * 这不是洁癖：此前这里为定时任务与等待评审各写了一组具名字段和一套查表，于是提供方
+ * 新增字段时本插件的本地类型一无所知，信息**静默丢失**（不报错、测试也不红，见
+ * CHANGELOG 0.2.3 第一条）。把语义留在拥有它的那一侧，这类漂移才结构上不可能发生。
+ *
  * @module
  */
-import type { SessionNode } from './tree.ts';
-/**
- * One session's waiting-review fact, as published by dsh-gitea-dispatch's
- * `useWaitingSummary()` (issue: dsh-gitea-dispatch#16).
- */
-export interface WaitingReviewSummaryEntry {
-    readonly prNumber: number;
-    readonly state: 'waiting' | 'overdue';
-}
-/** Session id → that session's waiting-review fact (no entry = not waiting). */
-export type WaitingReviewSummaryMap = ReadonlyMap<string, WaitingReviewSummaryEntry>;
-/**
- * One session's schedule fact, as published by dsh-later's `useScheduleSummary()`.
- */
-export interface ScheduleSummaryEntry {
-    readonly count: number;
-    readonly pausedCount: number;
-    readonly nextAt?: number;
-    readonly state: 'scheduled' | 'urgent' | 'overdue';
-}
-/** Session id → that session's schedule fact (no entry = no scheduled tasks). */
-export type ScheduleSummaryMap = ReadonlyMap<string, ScheduleSummaryEntry>;
+import type { AnyFacet, AnyFacetFold, RegisteredFacet } from './facets.ts';
+import type { GroupNode, SessionNode } from './tree.ts';
 /**
  * Aggregated live-session counts for one group, computed over all members so a
  * folded folder row can hint at hidden activity.
@@ -46,33 +35,38 @@ export interface GroupLiveStatus {
     done: number;
     /** Running direct children across members. */
     subagents: number;
-    /** Members with scheduled tasks (from dsh-later). */
-    scheduledSessions: number;
-    /** Total scheduled tasks across members (including paused). */
-    scheduledCount: number;
-    /** Highest-priority schedule state: overdue > urgent > scheduled. */
-    scheduleState: 'scheduled' | 'urgent' | 'overdue' | undefined;
-    /** Members waiting for CI review of their PR (from dsh-gitea-dispatch). */
-    waitingReviewCount: number;
-    /** Highest-priority waiting state across members: overdue > waiting. */
-    waitingReviewState: 'waiting' | 'overdue' | undefined;
+    /**
+     * 外部状态源的折果，按 facet id 索引，只含**有贡献**的来源（`count > 0`）。
+     *
+     * 这里刻意没有 `scheduled*` / `waitingReview*` 这类具名字段：徽标一旦为某个来源开
+     * 一个字段，就等于把别人家的语义焊进自己的类型，新增来源就得改本插件。
+     * `FacetFold.data` 的形状只有该来源自己读。
+     */
+    facets: ReadonlyMap<string, FacetEntry>;
+}
+/**
+ * 一个来源在**这一组**上的折果，连同它自己的 facet。
+ *
+ * 带上 facet 是为了让渲染（文案、图标、脉冲）与多层合并（`facet.merge`）都不必再回
+ * 登记面查表——也就不需要任何模块级状态。
+ */
+export interface FacetEntry {
+    facet: AnyFacet;
+    fold: AnyFacetFold;
 }
 /**
  * Zero-valued sentinel for {@link GroupLiveStatus}.
  *
- * Used when a group is expanded (badge is hidden, so aggregation is wasted
- * work) or when no cross-plugin data is available. Kept as a frozen constant
- * so the reference is stable across renders — `Object.is` comparisons in
- * React selectors never trigger spurious re-renders on it.
+ * Used when a group has nothing to report. Kept as a frozen constant so the
+ * reference is stable across renders — `Object.is` comparisons in React selectors
+ * never trigger spurious re-renders on it.
  */
 export declare const EMPTY_LIVE_STATUS: GroupLiveStatus;
 /**
- * Merge two {@link GroupLiveStatus} objects by summing counters and taking the
- * highest-priority state (overdue > urgent > scheduled for schedule; overdue > waiting
- * for waiting-review).
+ * 合并两份分组折果：本插件自己的计数相加，外部状态来源**按 facet 各自合并**。
  *
- * Used for multi-level aggregation: when a parent group is collapsed, its badge
- * must reflect all descendant sessions, not just direct members.
+ * 用于多层聚合：折叠的父文件夹要覆盖整棵子树，而子树里每一层都已各自折过一遍。
+ * `FacetFold.data` 怎么合归该 facet 自己决定，本模块从不解释。
  */
 export declare function mergeLiveStatus(a: GroupLiveStatus, b: GroupLiveStatus): GroupLiveStatus;
 /**
@@ -80,10 +74,68 @@ export declare function mergeLiveStatus(a: GroupLiveStatus, b: GroupLiveStatus):
  * hidden live sessions. Mirrors the session-row status priority (pending
  * outranks running outranks completed) at the counting level; labels resolve with
  * locale at render time.
+ *
  * @param nodes - member rows of the group.
- * @param sessionIds - the same members' Session ids (schedule and waiting facts are keyed by id).
- * @param waitingReviewSummary - dsh-gitea-dispatch waiting map, when that plugin is loaded.
- * @param scheduleSummary - dsh-later schedule map, when that plugin is loaded.
+ * @param sessionIds - the same members' Session ids (facets address their own data by id).
+ * @param facets - the registered status sources to fold over this group.
+ * @param now - one clock reading for the whole pass, so sibling facets cannot disagree
+ *   about which deadlines are still ahead.
+ */
+export declare function summarizeGroupStatus(nodes: readonly SessionNode[], sessionIds: readonly string[], facets?: readonly RegisteredFacet[], now?: number): GroupLiveStatus;
+/**
+ * Measure each group's own members, as the input to {@link aggregateGroupStatuses}.
+ *
+ * Every group is measured, expanded ones included. A folder row shows no badge while
+ * it is expanded, but its sessions still need attention and a collapsed ancestor must
+ * keep counting them — so expansion is a rendering fact, never an input to the
+ * aggregation. Short-circuiting expanded groups to `EMPTY_LIVE_STATUS` (the shape this
+ * had before the tree-wide aggregator existed, harmless while nothing aggregated) makes
+ * every collapsed parent undercount by the size of its expanded descendants.
+ *
+ * @param groups - derived groups, each with its member rows already populated.
+ * @param facets - registered sources, already filtered by the visibility settings.
+ * @param now - one clock reading shared by every group in the pass.
+ */
+export declare function directStatusesForGroups(groups: readonly {
+    key: string;
+    sessions: readonly SessionNode[];
+}[], facets?: readonly RegisteredFacet[], now?: number): Map<string, GroupLiveStatus>;
+/**
+ * Fold every group's DIRECT status up the workspace tree, so a collapsed folder
+ * counts every descendant session. A group's own row shows no badge while it is
+ * expanded, but its sessions still need attention and its collapsed ancestor must
+ * keep counting them — so the walk never depends on a group's expanded state.
+ *
+ * @param direct - each group's own-member status, keyed by group key.
+ * @param childrenByParent - the rendered tree: parent key (`undefined` = roots) → children.
+ * @returns aggregated status per group key: own members plus the whole subtree.
+ */
+export declare function aggregateGroupStatuses(direct: ReadonlyMap<string, GroupLiveStatus>, childrenByParent: ReadonlyMap<string | undefined, readonly {
+    key: string;
+}[]>): Map<string, GroupLiveStatus>;
+/**
+ * A group row whose badge input is resolved: its own members plus its whole subtree.
+ *
+ * `GroupNode.liveStatus` is optional only because upstream never fills it — this
+ * package's aggregator is the sole producer. Typing a rendered row as
+ * `StatusedGroupNode` is what turns "a row that skipped the aggregator" into a compile
+ * error instead of a folder that silently lost its badge, which is how the PR #10
+ * regression reached main.
+ */
+export interface StatusedGroupNode extends GroupNode {
+    liveStatus: GroupLiveStatus;
+}
+/**
+ * Attach each group's subtree-wide status, in derivation order. This is the producer
+ * the sidebar renders from.
+ *
+ * Expanded groups carry their status too: their own row draws no badge (a decision
+ * inside `groupLiveBadge`), but a collapsed ancestor still has to count them, so
+ * expansion never suppresses the measurement.
+ *
+ * @param groups - derived rows, in the order they render.
+ * @param direct - each group's own-member status, from {@link directStatusesForGroups}.
+ * @param childrenByParent - the rendered tree: parent key (`undefined` = roots) → children.
  */
-export declare function summarizeGroupStatus(nodes: readonly SessionNode[], sessionIds: readonly string[], waitingReviewSummary?: WaitingReviewSummaryMap, scheduleSummary?: ScheduleSummaryMap): GroupLiveStatus;
+export declare function withAggregatedStatus(groups: readonly GroupNode[], direct: ReadonlyMap<string, GroupLiveStatus>, childrenByParent: ReadonlyMap<string | undefined, readonly GroupNode[]>): StatusedGroupNode[];
 //# sourceMappingURL=group-status.d.ts.map

package/lib/types/client/group-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-status.d.ts","sourceRoot":"","sources":["../../../src/client/group-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAI5C;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;CACtC;AAED,gFAAgF;AAChF,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;CACnD;AAED,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;AAI1E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,aAAa,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAA;IAC7D,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wEAAwE;IACxE,kBAAkB,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;CACtD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAIX,CAAA;AAErB;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,eAAe,CA0BvF;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,oBAAoB,CAAC,EAAE,uBAAuB,EAC9C,eAAe,CAAC,EAAE,kBAAkB,GACnC,eAAe,CAgEjB"}
+{"version":3,"file":"group-status.d.ts","sourceRoot":"","sources":["../../../src/client/group-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAIvD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,QAAQ,CAAA;IACf,IAAI,EAAE,YAAY,CAAA;CACnB;AAKD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAGX,CAAA;AAErB;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,eAAe,CAUvF;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,GAAE,SAAS,eAAe,EAAO,EACvC,GAAG,GAAE,MAAmB,GACvB,eAAe,CA6CjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,EAAE,EACpE,MAAM,GAAE,SAAS,eAAe,EAAO,EACvC,GAAG,GAAE,MAAmB,GACvB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC5C,gBAAgB,EAAE,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,GAC5E,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAwB9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD,UAAU,EAAE,eAAe,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC5C,gBAAgB,EAAE,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,SAAS,SAAS,EAAE,CAAC,GACtE,iBAAiB,EAAE,CAKrB"}