@sleep2agi/commhub-server 0.9.0-preview.219 → 0.9.0-preview.220

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/package.json +1 -1
  2. package/src/agent-acl-slice3-http.test.ts +388 -1
  3. package/src/config-apply-validate.test.ts +68 -0
  4. package/src/config-apply-validate.ts +69 -0
  5. package/src/cors-origins.test.ts +40 -0
  6. package/src/create-node-network-id.test.ts +12 -0
  7. package/src/department-heads-http.test.ts +20 -0
  8. package/src/departments-agent-count.test.ts +3 -0
  9. package/src/etag-of.test.ts +57 -0
  10. package/src/event-loop-lag.ts +20 -0
  11. package/src/health-anon-readers.ts +59 -0
  12. package/src/health-host-disk-2756.test.ts +23 -1
  13. package/src/health-redaction.test.ts +1063 -0
  14. package/src/hub-catalog-read-http.test.ts +79 -0
  15. package/src/hub-provider-config.test.ts +17 -0
  16. package/src/hub-provider-config.ts +19 -0
  17. package/src/license-state.test.ts +56 -0
  18. package/src/license-state.ts +48 -0
  19. package/src/list-host-supervisors.test.ts +10 -0
  20. package/src/mcp-projects-events-http.test.ts +3 -0
  21. package/src/mcp-write-network-resolution.test.ts +3 -0
  22. package/src/node-caller-identity-http.test.ts +9 -1
  23. package/src/node-health-dispatch-http.test.ts +58 -2
  24. package/src/node-health-guard.ts +16 -0
  25. package/src/node-skills-transport.test.ts +3 -0
  26. package/src/opencode-v2-catalog.ts +4 -0
  27. package/src/redact-tokens.test.ts +22 -1
  28. package/src/redact-tokens.ts +4 -1
  29. package/src/rejection-counters.test.ts +72 -0
  30. package/src/rejection-counters.ts +173 -0
  31. package/src/requirement-events-http.test.ts +27 -0
  32. package/src/route-callers-http.test.ts +1 -1
  33. package/src/serve-error.test.ts +35 -0
  34. package/src/serve-error.ts +33 -4
  35. package/src/server.ts +913 -17
  36. package/src/shared/probe-host-allowlist-drift.test.ts +45 -0
  37. package/src/skillhub-http.test.ts +35 -1
  38. package/src/status-read-cache.ts +8 -1
  39. package/src/task-late-reply-http.test.ts +7 -0
  40. package/src/task-rejection-log.ts +10 -1
  41. package/src/tmux-allowlist.test.ts +48 -0
  42. package/src/tool-audience.ts +10 -3
  43. package/src/tools.ts +99 -15
package/src/server.ts CHANGED
@@ -1,4 +1,6 @@
1
- import { statfsSync } from "node:fs";
1
+ import { existsSync, statfsSync } from "node:fs";
2
+ import { execFileSync } from "node:child_process";
3
+ import { dirname, join } from "node:path";
2
4
  import { homedir } from "node:os";
3
5
  import { hostSupervisorIdentityRows } from "./host-supervisor-identity.js";
4
6
  import { buildServeErrorResponse } from "./serve-error.js";
@@ -104,7 +106,7 @@ import { listTaskLateReplies } from "./task-late-replies.js";
104
106
  import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
105
107
  import { startDueReminderTimer } from "./requirement-due-reminders.js";
106
108
  import { handleRequirementsRequest } from "./requirements.js";
107
- import { readHubProviders } from "./hub-provider-config.js";
109
+ import { readHubProviders, putHubProvider } from "./hub-provider-config.js";
108
110
  import { requestNodeSecrets, getScopedSecrets } from "./scoped-secrets.js";
109
111
  import { readEnvTransportLog } from "./env-transport-gate.js";
110
112
  import { enforceImpactOf, normalizePeerAllowlist, normalizeToolAllowlist, restAllowlistVerdict, restRouteLabel } from "./node-permissions.js";
@@ -117,6 +119,8 @@ import { handleSideThreadHttpRequest } from "./side-thread-http.js";
117
119
  import { createProductionSideThreadTransport } from "./side-thread-production.js";
118
120
  import { parseHubTimestamp } from "./hub-timestamp";
119
121
  import { logTaskRejection } from "./task-rejection-log.js";
122
+ import { taskRejectionCounters } from "./rejection-counters.js";
123
+ import { legacyLicenseField, licenseStateOf } from "./license-state.js";
120
124
  import { AVATAR_FIELD, avatarUrl, inspectAvatarImage, isMultipart, isValidAvatarVersion, MAX_AVATAR_BYTES, MAX_AVATAR_STORAGE_BYTES } from "./user-avatar-image.js";
121
125
 
122
126
  const PORT = resolvePort(process.env.PORT);
@@ -130,7 +134,7 @@ const SECURITY_LABEL = DEV_OPEN ? "⚠️ DEV OPEN MODE" : "🔒 secured";
130
134
  const TMUX_ALLOWLIST = new Set(
131
135
  (process.env.COMMHUB_TMUX_ALLOWLIST || "")
132
136
  .split(",")
133
- .map((s) => s.trim())
137
+ .map((s) => normalizeRequestIp(s))
134
138
  .filter(Boolean)
135
139
  );
136
140
  let masterTokenDeprecationLogged = false;
@@ -316,6 +320,27 @@ function streamOwnerNodeId(alias: string, networkId: string): string | null {
316
320
  return rows.length === 1 ? rows[0].node_id : null;
317
321
  }
318
322
 
323
+ /**
324
+ * 2026-10-31 —— 把 IPv4-mapped IPv6 折回 IPv4:`::ffff:1.2.3.4` ⇒ `1.2.3.4`。
325
+ *
326
+ * 为什么必须折:allowlist 是人手写的(通常写 IPv4),而 socket 地址在双栈监听下
327
+ * 常常是 `::ffff:` 形式 ⇒ 同一台机器在两个字符串下被判成两回事。
328
+ * 这属于「两个生产者、不同字符串」那一族:判据一样,字面不同 ⇒ 永远不相等。
329
+ * 方向是**少给**(不匹配 ⇒ 拒绝),所以它是 fail-closed 的静默锁死,而不是越权。
330
+ */
331
+ export function normalizeRequestIp(ip: string): string {
332
+ const s = (ip || "").trim().toLowerCase();
333
+ const m = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(s);
334
+ return m ? m[1] : s;
335
+ }
336
+
337
+ /** 允许清单判定(纯函数,供测试直接钉方向):空清单 = 只允许本机。 */
338
+ export function ipAllowedBy(ip: string, allowlist: ReadonlySet<string>): boolean {
339
+ const n = normalizeRequestIp(ip);
340
+ if (isLocalhostIP(n) || isLocalhostIP((ip || "").trim().toLowerCase())) return true;
341
+ return allowlist.has(n);
342
+ }
343
+
319
344
  function isLocalhostIP(ip: string): boolean {
320
345
  return ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1" || ip === "localhost";
321
346
  }
@@ -326,7 +351,7 @@ function isLocalhostIP(ip: string): boolean {
326
351
  const normalizeRuntime = normalizeSessionRuntime;
327
352
 
328
353
  function isTmuxAllowedIP(ip: string): boolean {
329
- return isLocalhostIP(ip) || TMUX_ALLOWLIST.has(ip);
354
+ return ipAllowedBy(ip, TMUX_ALLOWLIST);
330
355
  }
331
356
 
332
357
  // 节点令牌(ntok_ / 邀请码令牌,api_tokens.network_id 非空)是一个节点在一个网络里的身份。
@@ -865,11 +890,17 @@ const TaskSchema = z.object({
865
890
  force: z.boolean().optional(),
866
891
  });
867
892
 
868
- /** #460 — `{ degraded: [{ layer, label, reason }] }` when the node's fresh health says a layer is down, else `{}`. */
869
- function degradedField(networkId: string | null | undefined, alias: string): { degraded?: Array<{ layer: string; label: string; reason: string }> } {
893
+ /**
894
+ * #460 — `{ degraded: [{ layer, label, reason, origin }] }` when the node's fresh health says a layer is down, else `{}`.
895
+ *
896
+ * `origin` 必带(2026-10-31):`reason` 有两个生产者 —— 节点上报的摘要,与 Hub 合成的
897
+ * `"unreachable"`。少了这一格,「节点说自己不可达」与「Hub 问不到节点」在响应里同形,
898
+ * 而上游可以原样声明那个字面量,所以改名或拆 catch 都不构成判别力。
899
+ */
900
+ function degradedField(networkId: string | null | undefined, alias: string): { degraded?: Array<{ layer: string; label: string; reason: string; origin: "node" | "hub" }> } {
870
901
  const h = readNodeHealth(networkId ?? "default", alias);
871
902
  const layers = degradedLayers(h?.health);
872
- return layers.length ? { degraded: layers.map(l => ({ layer: l.layer, label: l.label, reason: l.reason })) } : {};
903
+ return layers.length ? { degraded: layers.map(l => ({ layer: l.layer, label: l.label, reason: l.reason, origin: l.origin })) } : {};
873
904
  }
874
905
 
875
906
  const BroadcastSchema = z.object({
@@ -879,9 +910,25 @@ const BroadcastSchema = z.object({
879
910
  });
880
911
 
881
912
  // ── HTTP Server (Bun native) ────────────────────────
882
- const CORS_ORIGINS = process.env.COMMHUB_CORS_ORIGINS
883
- ? process.env.COMMHUB_CORS_ORIGINS.split(",").map((s) => s.trim())
884
- : ["http://localhost:3000", "http://localhost:3001"];
913
+ /**
914
+ * 2026-10-31 —— **「设了空」与「没设」是两件事**。
915
+ *
916
+ * `if (process.env.X)` 把两者都判假:于是 `COMMHUB_CORS_ORIGINS=`(运维想「一个都不许」)
917
+ * 会悄悄回退到 localhost 默认值 —— 而那是**更松**的一侧。
918
+ * `'X' in process.env` 才区分得开。
919
+ *
920
+ * ⇒ 口径:未设 ⇒ 开发默认(localhost 两个端口);设了但为空 ⇒ **空清单**(谁都不许)。
921
+ * 这是「空必须落在更严的一侧」在本字段上的具体落点:
922
+ * 这个字段的**最松值**不是空,而是 `*`;所以空不能被读成「用默认」。
923
+ */
924
+ export function parseCorsOrigins(raw: string | undefined): string[] {
925
+ if (raw === undefined) return ["http://localhost:3000", "http://localhost:3001"];
926
+ return raw.split(",").map((s) => s.trim()).filter(Boolean); // 空串 / 全逗号 ⇒ 空清单(更严)
927
+ }
928
+
929
+ const CORS_ORIGINS = parseCorsOrigins(
930
+ "COMMHUB_CORS_ORIGINS" in process.env ? (process.env.COMMHUB_CORS_ORIGINS ?? "") : undefined,
931
+ );
885
932
 
886
933
  function corsHeaders(req: Request): Record<string, string> {
887
934
  const origin = req.headers.get("Origin") || "";
@@ -898,6 +945,664 @@ function corsHeaders(req: Request): Record<string, string> {
898
945
  };
899
946
  }
900
947
 
948
+ /**
949
+ * 2026-10-31 —— `/health` 的**匿名投影白名单**。
950
+ *
951
+ * 🔴 为什么是白名单而不是「逐个字段加鉴权门」:
952
+ * 原来的默认值是「加到 body 就自动匿名可见」,于是每加一个字段都要**记得**收进鉴权门。
953
+ * 而今晚我加了四次字段,四次都没想到 —— 因为**默认值不要求你想**。
954
+ * ⇒ 改成:全量字段默认属于**鉴权投影**;匿名投影只给这里显式列出的键。
955
+ * ⇒ 于是「忘了想」的结果是**少给**,不是泄露。
956
+ *
957
+ * 判据:安全相关的默认值必须落在「少给」那一侧。
958
+ *
959
+ * 加新字段时的三问(缺第二问就等于没问):
960
+ * ① 谁能读(匿名 / 鉴权 / 内部)
961
+ * ② 知道它之后,读者能做什么以前做不到的事
962
+ * ③ 默认投哪一档(答案是「鉴权」,除非在这里显式加一行)
963
+ */
964
+ export const PUBLIC_HEALTH_KEYS: ReadonlySet<string> = new Set([
965
+ // 存活/版本:外部 watchdog 与运维只靠这些判断「活没活」
966
+ "ok", "status", "status_reasons", "version", "version_role", "api_version", "transport", "uptime", "startedAt",
967
+ // 规模与健康度聚合(不含拓扑明细)
968
+ "sessions_count", "sse_connections", "mcp_inflight", "mcp_inflight_peak",
969
+ // 事件循环停顿是**一个对象**(event_loop: {max_gap_ms, recent_stalls,…}),
970
+ // 不是我原先以为的三个顶层键 —— 死条目测试当场抓到了这一点。
971
+ "event_loop",
972
+ // 访问模式与安全档位(不含任何凭据/路径)
973
+ "auth", "security", "tmux", "v3_auth", "multi_network",
974
+ // 授权类型只需要「是什么」,不需要行内容
975
+ "license", "license_state",
976
+ // 容量与能力位(dashboard 上传代理要在开流前读)
977
+ "limits", "capabilities",
978
+ // 探针回显:只有带 X-Probe-Nonce 时才出现,本身不含敏感信息
979
+ "probe_nonce", "served_at",
980
+ // 值得匿名披露的「有没有」,不是「是什么」
981
+ "build_identified",
982
+ ]);
983
+
984
+ /**
985
+ * 2026-10-31 —— **三分类必须是字段上的标签,不是一张文档里的表。**
986
+ *
987
+ * 原来「凭证类要慎给」只写在注释里 ⇒ 下一个人加 requestId 时,他看到的是「一个无害的字符串」。
988
+ * ⇒ 现在每个字段**必填**一档,且匿名暴露的合法性由这一档决定:
989
+ *
990
+ * landmark 告诉你「精确在哪」(进程身份 / 提交 / 启动时刻 / 自报与内核是否打架)
991
+ * ⇒ 一律不进匿名响应
992
+ * gauge 聚合量或粗标签(计数、档位、能力位)
993
+ * ⇒ **可以**匿名,但必须写清聚合到什么粒度
994
+ * credential 用途是「与内部对上账」的值
995
+ * ⇒ 不进匿名响应,**除非**它是请求方自己带来的(caller_supplied)
996
+ * 因为那时它不构成「读者本来拿不到的信息」
997
+ *
998
+ * 🔴 判据(来自复核):
999
+ * · 凭证类的判据不是「可不可预测」,而是「拿到它与内部对上账能做什么」——
1000
+ * 随机 uuid 的 trace id 也一样可关联 ⇒ 随机性解决伪造,解决不了关联。
1001
+ * · **一个分类只有在它成为字段上的必填标签时才可检查**;写在文档里的分类,只是写给愿意读的人。
1002
+ */
1003
+ export type HealthFieldClass = "landmark" | "gauge" | "credential";
1004
+
1005
+ /**
1006
+ * 2026-10-31 —— gauge 的**粒度词表改成封闭枚举**,而且必须区分
1007
+ * **电平(level)** 与 **累积(cumulative)**。
1008
+ *
1009
+ * 起因:一次复核里同一个文件四行四种语义,而其中一行(`under_oom`)是**电平**,
1010
+ * 被当成计数器用 ⇒「用它判断有没有 OOM 过」恒为否 —— 一个结构上必然为否的读数。
1011
+ *
1012
+ * ⇒ 一个电平不能算速率;一个累积不能算「现在怎么样」。
1013
+ * 两者在 JSON 里都是数字,**只有字段名或元数据能把它们分开**。
1014
+ */
1015
+ export type HealthGranularity =
1016
+ | "level" // 读的那一刻的值(会上下波动)
1017
+ | "cumulative" // 自某个起点累计(只增;起点必须另有字段)
1018
+ | "instant" // 某个时刻戳
1019
+ | "label" // 枚举/字符串(描述性:可以为常量)
1020
+ | "boolean"
1021
+ /**
1022
+ * 2026-10-31 —— **verdict:一个关于对错的判定**。
1023
+ *
1024
+ * 与 label 的差别只有一条,但它是致命的:
1025
+ * label 是描述("streamable-http"),为常量无害 —— 它回答「这是什么」
1026
+ * verdict 是判定("ok"/"degraded"),若另一支不可观测,它就不是判定而是装饰
1027
+ *
1028
+ * 起因:一次复核提出给 /health 加 `ptyWsAttached`,而 attach 在 listen 回调里
1029
+ * **无条件**执行 ⇒ true 恒成立、false 不可观测 ⇒ 这个字段永远只有一个读数。
1030
+ * ⇒ 判据:一个判定的另一支若在当前部署形态下不可达,这个字段就没有判别力。
1031
+ * verdict 档必须写 `verdict_other_branch`(怎么让它响),写不出即为缺口。
1032
+ */
1033
+ | "verdict";
1034
+
1035
+ export interface HealthFieldMeta {
1036
+ class: HealthFieldClass;
1037
+ /**
1038
+ * granularity: "verdict" 必填 —— **另一支怎么才能读到**。
1039
+ * 写不出「怎么让它响」就说明这个判定只会有一种取值。
1040
+ */
1041
+ verdict_other_branch?: string;
1042
+ /**
1043
+ * 2026-10-31 —— **仲裁字段**(外部复核那条「每个问题一个权威字段 + 一个仲裁字段」)。
1044
+ *
1045
+ * 一个 verdict 只说结论,不解释结论怎么来的;当它被判错时,读者需要第二个字段去仲裁。
1046
+ * 例如 `status` 被读成 "ok",到底是「真的没问题」还是「检查没跑」—— 只有 `status_reasons` 能回答。
1047
+ * ⇒ verdict 类字段必须声明仲裁字段;测试断言它真的在载荷里(存在即可,可为 null)。
1048
+ */
1049
+ arbiter?: string;
1050
+ /**
1051
+ * 2026-10-31 —— **身份三分类**(外部复核那条:产物属性 / 调用属性 / 声明)。
1052
+ *
1053
+ * artifact 换调用方式不变(例:产物里注入的 commit)⇒ 它是「运行的是什么」的权威
1054
+ * call 换 cwd / 命令行就变(例:运行时读 RELEASE_COMMIT)⇒ 它描述「怎么被启动的」
1055
+ * declaration 写它的人影响不了它在跑什么(例:version)⇒ 它是标签,不是事实
1056
+ * ⇒ 三类混在一起且不标注,就是「六个身份」的根。
1057
+ * 每个问题**恰好一个** artifact 类权威;若存在 call 类覆盖,必须能被看出来(root_kind)。
1058
+ */
1059
+ identity_class?: "artifact" | "call" | "declaration";
1060
+ /**
1061
+ * 单向字段必填 —— 另一支**在任何部署里都不会出现**的原因。
1062
+ * 与 verdict_other_branch 是同一件事的两面:
1063
+ * 前者答「我没有实现那一支」,后者答「我实现了,但你要怎样才看得到」。
1064
+ */
1065
+ constant_by_design?: string;
1066
+ /** gauge 必填:粒度(封闭枚举,见 HealthGranularity) */
1067
+ granularity?: HealthGranularity;
1068
+ /** credential 专用:该值由请求方带来(回显),因此不构成额外泄露 */
1069
+ caller_supplied?: true;
1070
+ /**
1071
+ * 2026-10-31 —— credential 类的**可对账性**,把「读法之争」变成取值。
1072
+ *
1073
+ * echo_only 值由请求方带来,服务端只是回显 ⇒ 不构成读者本来拿不到的信息
1074
+ * server_generated 由我们生成/持有 ⇒ 拿到它就能与内部对上账 ⇒ **永不可匿名**
1075
+ *
1076
+ * 原来的做法是在注释里写「若按最严读法……」——那是把决定权交给读法。
1077
+ * 现在两种读法都是字段的取值,谁要严就断言 joinability !== "echo_only" 不许进匿名。
1078
+ */
1079
+ joinability?: "echo_only" | "server_generated";
1080
+ /**
1081
+ * 2026-10-31 —— 是不是**启动快照**(启动时刻定值、之后不再变)。
1082
+ *
1083
+ * 这一类字段有一个单向盲区:它们只会**漏报**,不会误报——
1084
+ * 读初始快照的判据把「后来才有的」读成「从来没有」,
1085
+ * 而结果与「真的没有」在读数上完全一致。
1086
+ * ⇒ 所以分类必须写出**谁不算**:`served_at` 长得一模一样,而它的全部价值在于会变。
1087
+ * 只写「什么算」的分类,对形似字段没有抵抗力。
1088
+ */
1089
+ frozen_at_boot?: true;
1090
+ /** 为什么把它放这一档(只在有争议的字段上写) */
1091
+ why?: string;
1092
+ }
1093
+
1094
+ export const HEALTH_FIELD_META: Readonly<Record<string, HealthFieldMeta>> = {
1095
+ // ── gauge:聚合 / 粗标签 ─────────────────────────────────────────────
1096
+ ok: {
1097
+ class: "gauge",
1098
+ granularity: "boolean",
1099
+ constant_by_design: "200 是 watchdog 契约下的承诺 ⇒ 这一支只有 true;非 200 时读者根本拿不到这个字段(另一支在传输层,不在载荷里)",
1100
+ },
1101
+ version: {
1102
+ class: "gauge",
1103
+ granularity: "label",
1104
+ why: "粗粒度版本号;精确字节身份由 git_commit 承担,而它不匿名",
1105
+ identity_class: "declaration",
1106
+ },
1107
+ version_role: {
1108
+ class: "gauge",
1109
+ granularity: "label",
1110
+ why: "把「version 是部署标签不是指纹」写进载荷 —— 读者不会去查它数的是什么",
1111
+ constant_by_design: "本字段是那句话本身;另一支(version 当指纹)是错误用法,不是另一个取值",
1112
+ },
1113
+ api_version: { class: "gauge", granularity: "label", constant_by_design: "本进程只实现 v3;若将来并存两代,这里才会出现第二个取值" },
1114
+ transport: { class: "gauge", granularity: "label", constant_by_design: "本进程只实现 streamable-http(另一支 SSE-only 是历史形态,已不接受配置)" },
1115
+ uptime: { class: "gauge", granularity: "cumulative" },
1116
+ startedAt: { frozen_at_boot: true, class: "gauge", granularity: "instant", why: "窗口起点;去掉它,event_loop 里的 stall 计数就没有分母时刻戳" },
1117
+ sessions_count: { class: "gauge", granularity: "level" },
1118
+ sse_connections: { class: "gauge", granularity: "level" },
1119
+ mcp_inflight: { class: "gauge", granularity: "level" },
1120
+ mcp_inflight_peak: { class: "gauge", granularity: "cumulative" },
1121
+ event_loop: { class: "gauge", granularity: "cumulative" },
1122
+ auth: { class: "gauge", granularity: "label" },
1123
+ security: { class: "gauge", granularity: "label" },
1124
+ tmux: { class: "gauge", granularity: "label" },
1125
+ v3_auth: { class: "gauge", granularity: "label", constant_by_design: "编译期能力,没有开关;false 只可能出现在老版本服务端上 —— 要读它请读 version" },
1126
+ multi_network: { class: "gauge", granularity: "label", constant_by_design: "同上:多网络是数据模型能力,不是运行时开关 ⇒ 单网络部署里它也是 true" },
1127
+ license: { class: "gauge", granularity: "label" },
1128
+ license_state: {
1129
+ class: "gauge",
1130
+ granularity: "verdict",
1131
+ arbiter: "license",
1132
+ verdict_other_branch: "absent:删掉 license 行;unknown:让查询抛错(表被锁/被改名)—— 两者形状不同,这正是它存在的理由",
1133
+ },
1134
+ limits: { class: "gauge", granularity: "label" },
1135
+ capabilities: { class: "gauge", granularity: "label" },
1136
+ // ⚠️ 例外:**形似启动快照,但会变** —— 它的全部价值在于变,标成快照会毁掉它。
1137
+ served_at: { class: "gauge", granularity: "instant" },
1138
+ build_identified: {
1139
+ class: "gauge",
1140
+ granularity: "verdict",
1141
+ arbiter: "build_identity_note",
1142
+ why: "只说「有没有构建标识」,不说「是什么」",
1143
+ verdict_other_branch: "false:从 npm 包(非 git 工作树)启动,包内没有 .git ⇒ 拿不到 commit ⇒ 这是最常见的生产形态,不是异常",
1144
+ },
1145
+ alert_baselines: { class: "gauge", granularity: "cumulative" },
1146
+ broadcast: { class: "gauge", granularity: "level" },
1147
+ host_disk: { class: "gauge", granularity: "level" },
1148
+ counters: { class: "gauge", granularity: "cumulative", why: "按 status:code 分桶、封顶 64;聚合量,但当前只给鉴权读者" },
1149
+ epoch_agreement: {
1150
+ class: "gauge",
1151
+ granularity: "verdict",
1152
+ arbiter: "epoch_delta_ms",
1153
+ why: "内核与自报是否一致;是「一致/不一致」这个结论,不是具体时刻",
1154
+ verdict_other_branch: "disagree:宿主时钟被改过(NTP 大步进 / 手工 date / 虚拟机恢复快照)⇒ 差值超出误差界;unknown:/proc 不可读",
1155
+ },
1156
+ epoch_delta_ms: { class: "gauge", granularity: "level" },
1157
+ clk_tck_assumed: { class: "gauge", granularity: "label" },
1158
+ clk_tck_estimate: {
1159
+ class: "gauge",
1160
+ granularity: "level",
1161
+ why: "**未应用阈值**的原始估计;有它才能分辨「守卫被挂起打回」与「估计器本身有偏置」",
1162
+ },
1163
+ host_uptime_s: {
1164
+ class: "gauge",
1165
+ granularity: "cumulative",
1166
+ why: "**机器**已开机秒数(与进程 uptime 是两个量);守卫的可检出下限以它为基准,没有它这个阈值不可验",
1167
+ },
1168
+ clk_tck_assumed_reason: {
1169
+ class: "gauge",
1170
+ granularity: "verdict",
1171
+ arbiter: "clk_tck_estimate",
1172
+ why: "退回 assumed 的原因;三支挤在同一个值里时,「设备不支持」与「真的挂起过」同形",
1173
+ verdict_other_branch: "rel_error_above_1pct:宿主挂起(uptime 涨、jiffies 不涨)超过 1% —— 本机实测已出现",
1174
+ },
1175
+ clk_tck_delta: { class: "gauge", granularity: "level", why: "derived − 100;confirmed 也要报差多少" },
1176
+ kernel_started_at_error_ms: {
1177
+ class: "gauge",
1178
+ granularity: "level",
1179
+ why: "启动时刻误差界,**含地板**(btime 整秒 ±500ms + jiffies 10ms);地板不会因为尺子变准而消失",
1180
+ },
1181
+ clk_tck_guard_min_suspend_s: {
1182
+ class: "gauge",
1183
+ granularity: "level",
1184
+ why: "1% 相对偏差 = 多长的挂起 ⇒ 这是这个守卫**抓得住的最小异常**(134 天的机器约 32 小时)",
1185
+ },
1186
+ suspend_total_s: {
1187
+ class: "gauge",
1188
+ granularity: "cumulative",
1189
+ why: "推导的前提(累计挂起);有了它 derived 带前提,没有它前提在读数之外",
1190
+ },
1191
+ clk_tck_source: {
1192
+ class: "gauge",
1193
+ granularity: "verdict",
1194
+ arbiter: "clk_tck_delta",
1195
+ why: "assumed/derived/confirmed —— 一个叫 assumed 的字段必须有一条「它是否成立」的判定",
1196
+ verdict_other_branch: "derived/assumed:非 x86 宿主(USER_HZ≠100)、/proc 不可读、或容器里 auxv 被剥 ⇒ 三档都在真实部署里出现过",
1197
+ },
1198
+
1199
+ // ── landmark:精确位置/身份 ──────────────────────────────────────────
1200
+ git_commit: {
1201
+ frozen_at_boot: true,
1202
+ class: "landmark",
1203
+ why: "精确告诉外部这是哪一版代码(本仓公开)⇒ 等于指路到已知问题清单",
1204
+ identity_class: "artifact",
1205
+ },
1206
+ git_dirty: { class: "landmark" },
1207
+ status: {
1208
+ class: "gauge",
1209
+ granularity: "verdict",
1210
+ arbiter: "status_reasons",
1211
+ verdict_other_branch: "degraded:让 DB 读不到(chmod/移走 db 文件)或让 license 查询失败 ⇒ status_reasons 同时非空",
1212
+ },
1213
+ status_reasons: { class: "gauge", granularity: "level" },
1214
+ git_identity_root: {
1215
+ class: "landmark",
1216
+ identity_class: "call",
1217
+ why: "commit 是从**模块目录**(制品所在处)读的,还是退回 **cwd** 读的;后者会把启动目录里另一个仓库的身份报成本包的身份",
1218
+ },
1219
+ build_identity_note: {
1220
+ class: "landmark",
1221
+ why: "解释 git_commit 为什么为空;没有它,「没有」与「读不到」同形",
1222
+ },
1223
+ // 逐会话明细 = 拓扑 ⇒ 只需「有几个」,不需要「哪几个」(与 #473 的审计同一条)
1224
+ sse_sessions: { class: "landmark", why: "按键列出连接 = 网络 id + 别名,正是 #473 那个泄露面" },
1225
+ pid: { frozen_at_boot: true, class: "landmark" },
1226
+ boot_id: { frozen_at_boot: true, class: "landmark" },
1227
+ proc_start_ticks: { frozen_at_boot: true, class: "landmark" },
1228
+ kernel_started_at: { frozen_at_boot: true, class: "landmark", why: "内核口径的精确启动时刻 ⇒ 可与外部日志对账" },
1229
+ kernel_started_at_note: { class: "landmark" },
1230
+
1231
+ // ── credential ─────────────────────────────────────────────────────
1232
+ probe_nonce: {
1233
+ class: "credential",
1234
+ caller_supplied: true,
1235
+ joinability: "echo_only",
1236
+ why: "用途是「证明这一次」,且值由请求方自带 ⇒ 不构成读者本来拿不到的信息",
1237
+ },
1238
+ };
1239
+
1240
+ /**
1241
+ * 匿名可见的充要条件(可执行):
1242
+ * gauge,或 credential 且 caller_supplied。
1243
+ * ⇒ landmark 永不匿名;我们**生成**的 credential 永不匿名。
1244
+ */
1245
+ export function mayBePublic(meta: HealthFieldMeta | undefined): boolean {
1246
+ if (!meta) return false;
1247
+ if (meta.class === "gauge") return true;
1248
+ // credential 只有「回显」这一种可匿名;服务端生成的一律不可 —— 与 caller_supplied 同向,互为冗余。
1249
+ return meta.class === "credential"
1250
+ && meta.caller_supplied === true
1251
+ && meta.joinability === "echo_only";
1252
+ }
1253
+
1254
+ /** 匿名投影:只保留白名单里的键。逐键复制,绝不返回原对象的引用。 */
1255
+ export function projectPublicHealth(body: Record<string, unknown>): Record<string, unknown> {
1256
+ const out: Record<string, unknown> = {};
1257
+ for (const key of Object.keys(body)) {
1258
+ if (PUBLIC_HEALTH_KEYS.has(key)) out[key] = body[key];
1259
+ }
1260
+ return out;
1261
+ }
1262
+
1263
+ /**
1264
+ * 2026-10-31 —— `/health` 的「这一次」回显位。
1265
+ *
1266
+ * 读 `X-Probe-Nonce`,只接受 1–64 个 `[A-Za-z0-9._-]`。
1267
+ * 非法/超长一律**当作没带**(不裁剪、不转义、不回显):
1268
+ * 半接受会造出一个「看起来回显了、其实被改过」的值,比不回显更糟。
1269
+ *
1270
+ * 为什么用请求方给的值而不是自己生成:我们要证的是
1271
+ * 「这个响应是收到**这个**请求之后生成的」,
1272
+ * 所以 nonce 必须由调用方在**发请求之前**定下来,否则它只能证明「有个服务在答」。
1273
+ */
1274
+ function probeNonceOf(req: Request): string | null {
1275
+ const raw = req.headers.get("X-Probe-Nonce");
1276
+ if (!raw) return null;
1277
+ return /^[A-Za-z0-9._-]{1,64}$/.test(raw) ? raw : null;
1278
+ }
1279
+
1280
+ /**
1281
+ * 2026-10-31 —— 让「结论的站位」可验。
1282
+ *
1283
+ * 今晚反复踩到同一件事:一句话写着 `prod@18445bf4`,而线上其实跑 e230677f。
1284
+ * **标签可以随手写;要让标签可验,就得有一个由系统自己产生、外部可读的值。**
1285
+ * 这个字段就是那个值:`/health` 由进程自己报出它所在源码树的 commit。
1286
+ *
1287
+ * 🔴 取不到就是 **null**,绝不回退成 version 或任何“看起来像值”的东西 ——
1288
+ * 一个未验的断言标了“未验”仍然有用;标成事实会污染整张表。
1289
+ * npm 安装形态没有 .git ⇒ 恒为 null,这是**设计**,不是缺陷。
1290
+ *
1291
+ * 只在启动时算一次(boot_* 语义):git commit 不可能在进程生命周期内变化,
1292
+ * 所以它满足「变更周期 ⊇ 进程生命周期」,可以绑进程边界。
1293
+ */
1294
+ function detectBootGitIdentity(): {
1295
+ commit: string | null;
1296
+ /** 只有 commit 非空时才有意义;commit 为空时必须是 null(**不是 false**)。 */
1297
+ dirty: boolean | null;
1298
+ /** commit 为空时说明**为什么**空 —— 没有它,「没有」与「读不到」同形。 */
1299
+ reason: "not_a_git_checkout" | "git_unavailable" | "unexpected_rev_parse_output" | null;
1300
+ /**
1301
+ * 2026-10-31 —— **这个 commit 是从哪个根读出来的**(外部复核那条:
1302
+ * 「release 读的是 cwd 而不是可执行文件目录 ⇒ 它标识部署动作,不标识运行内容」)。
1303
+ *
1304
+ * 我们优先用模块目录(= 制品所在处),只在拿不到时退回 cwd。
1305
+ * 但**没有字段说明用了哪个**时,「读到的是制品身份」与「读到的是启动目录里某个别的仓库」
1306
+ * 在载荷上完全同形 —— 后者会把一台跑着旧包的机器报成新提交。
1307
+ * ⇒ 加一格 root_kind 作仲裁;cwd 那一支必须能被看出来。
1308
+ */
1309
+ root_kind: "module_dir" | "cwd";
1310
+ } {
1311
+ const moduleDir = (import.meta as { dir?: string }).dir;
1312
+ const start = moduleDir ?? process.cwd();
1313
+ const rootKind: "module_dir" | "cwd" = moduleDir ? "module_dir" : "cwd";
1314
+ let dir = start;
1315
+ for (let i = 0; i < 6; i += 1) {
1316
+ if (existsSync(join(dir, ".git"))) {
1317
+ try {
1318
+ const out = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], {
1319
+ stdio: ["ignore", "pipe", "ignore"],
1320
+ timeout: 1500,
1321
+ }).toString().trim();
1322
+ if (!/^[0-9a-f]{40}$/.test(out)) {
1323
+ return { commit: null, dirty: null, reason: "unexpected_rev_parse_output", root_kind: rootKind };
1324
+ }
1325
+ // 2026-10-31 —— dirty 位不能省:commit sha 单独一个字段,
1326
+ // 无法区分「干净树构建」与「脏树构建」,于是 vantage 依然可能把一个
1327
+ // 非提交的值当成提交。dirty 一旦为 true,这个读数只能写 prod@自称。
1328
+ let dirty = false;
1329
+ try {
1330
+ const st = execFileSync("git", ["-C", dir, "status", "--porcelain"], {
1331
+ stdio: ["ignore", "pipe", "ignore"],
1332
+ timeout: 1500,
1333
+ }).toString();
1334
+ dirty = st.trim().length > 0;
1335
+ } catch {
1336
+ dirty = true; // 读不到状态 ⇒ 保守认定为脏(不许把“不知道”当干净)
1337
+ }
1338
+ return { commit: out, dirty, reason: null, root_kind: rootKind };
1339
+ } catch {
1340
+ return { commit: null, dirty: null, reason: "git_unavailable", root_kind: rootKind };
1341
+ }
1342
+ }
1343
+ const parent = dirname(dir);
1344
+ if (parent === dir) break;
1345
+ dir = parent;
1346
+ }
1347
+ return { commit: null, dirty: null, reason: "not_a_git_checkout", root_kind: rootKind };
1348
+ }
1349
+
1350
+ const BOOT_GIT = detectBootGitIdentity();
1351
+
1352
+ /**
1353
+ * 2026-10-31 —— 内核口径的「本进程何时开始」。
1354
+ *
1355
+ * `startedAt` 是**自报**的(`Date.now() - uptime`),可被伪造、也可被同一进程复用。
1356
+ * 内核侧有两条独立信息:`/proc/stat` 的 `btime`(开机时刻)与 `/proc/self/stat` 第 22 字段
1357
+ * (开机后的 clock ticks)。→ 启动时刻 = btime + ticks/CLK_TCK。
1358
+ *
1359
+ * 🔴 2026-10-31 修订(原设计是反的):原来「换算值与 startedAt 差 >10s ⇒ 不发布」,
1360
+ * 等于让**自报字段否决内核读数** —— 而 startedAt 恰恰是可被伪造/可被替换的那一侧。
1361
+ * 今晚刚立的规则是:判据用内核三元组(boot_id, pid, proc_start_ticks),
1362
+ * 自报值只用于**展示/对账**,两者不一致是一条**独立告警**,不是「变 null」。
1363
+ *
1364
+ * ⇒ 现在的分法:
1365
+ * · 判据:boot_id / pid / proc_start_ticks —— 无条件发布,不含单位假设(不需要 CLK_TCK)
1366
+ * · 展示:kernel_started_at —— 只要 btime+ticks 可得就发布,但**永远带 agreement 标记**
1367
+ * · 不一致:epoch_agreement=disagree + epoch_delta_ms ⇒ 单独可读,不被折成 unknown
1368
+ * · 换算依赖 CLK_TCK=100 这个假设 ⇒ 显式给 clk_tck_assumed,读者可自行折算
1369
+ * 10s 只用来**分类** agreement,不再是发布的闸门。
1370
+ */
1371
+ /** 换算 ticks 时假设的 CLK_TCK:假设本身要**显式**出现在读数里,而不是藏在代码里。 */
1372
+ const CLK_TCK_ASSUMED = 100;
1373
+
1374
+ /**
1375
+ * 2026-10-31 —— 一个叫 assumed 的字段,必须有一条「它是否成立」的判定。
1376
+ *
1377
+ * 否则它只是一个被记录下来的数:换内核(USER_HZ 不是 100 的架构)之后它会**静默变错**,
1378
+ * 而字段名里的 "assumed" 没有任何东西去校它。
1379
+ *
1380
+ * 推导方式(不依赖 sysconf,Node 没暴露):
1381
+ * /proc/stat 里所有 cpu 行之和 = 自启动以来的总 jiffies
1382
+ * CLK_TCK ≈ 总 jiffies / (uptime 秒 × CPU 数)
1383
+ * ⇒ 与 assumed 相等 ⇒ source="confirmed";不等 ⇒ 用推导值,source="derived";
1384
+ * 两者都拿不到 ⇒ 退回 assumed,source="assumed"。
1385
+ */
1386
+ function clkTck(): {
1387
+ value: number;
1388
+ source: "confirmed" | "derived" | "assumed";
1389
+ /** derived − 100;只在算得出推导值时非 null(**这是「差多少」,不是「等不等」**)。 */
1390
+ delta?: number | null;
1391
+ /**
1392
+ * 2026-10-31 —— **未应用任何阈值**的原始估计(tick/s,两位小数)。
1393
+ *
1394
+ * 为什么要它:本机实测 estimate=99.35、而 suspend_total_s=0 ⇒
1395
+ * 「守卫被 1% 阈值打回 assumed」这件事**不是挂起造成的,是估计器本身的偏置**。
1396
+ * 没有这一格时,那句话说不出来 —— 只能看到 assumed,看不到为什么。
1397
+ */
1398
+ estimate?: number | null;
1399
+ /** 该差值隐含的启动时刻误差(毫秒);**含地板**,见下。 */
1400
+ errorMs?: number | null;
1401
+ /** 1% 相对偏差对应多长的挂起(秒)—— 这就是这个守卫**抓得住的最小异常**。 */
1402
+ guardMinSuspendS?: number | null;
1403
+ /**
1404
+ * 2026-10-31 —— 退回 assumed 的**原因**。
1405
+ * 原来三支(读不到 / 算出来不可能 / 偏差过大)都返回同一个 `{value:100, source:"assumed"}`,
1406
+ * 于是「设备不支持」与「这台机器真的挂起了 32 分钟」在读数上完全一样。
1407
+ */
1408
+ assumedReason?: "stat_unreadable" | "derived_out_of_range" | "rel_error_above_1pct";
1409
+ } {
1410
+ try {
1411
+ const fs = require("node:fs") as typeof import("node:fs");
1412
+ const os = require("node:os") as typeof import("node:os");
1413
+ let jiffies = 0;
1414
+ // 2026-10-31 —— **这里曾经是 Python 的 splitlines()**:JS 没有这个方法 ⇒ TypeError ⇒
1415
+ // 被本函数的 catch 吞掉 ⇒ 永远 return { value: 100, source: "assumed" }。
1416
+ // ⇒ 整条推导是死代码:clk_tck_delta / kernel_started_at_error_ms 恒为 null,
1417
+ // 而「恒为 null」在报告里与「这台机器刚好是 100」同形。
1418
+ // 外部复核指出的两件事(误差界没地板、1% 守卫抓不到一小时挂起)都作用在这条死路径上。
1419
+ // ⇒ 现在改成 split,并在 catch 里带上原因,不再把「算不出」与「刚好等于 100」压成同一个值。
1420
+ for (const line of fs.readFileSync("/proc/stat", "utf8").split(/\r?\n/)) {
1421
+ // ⚠️ `cpu\d*` 会**同时**匹配聚合行 `cpu` 与每核行 `cpu0..cpuN` ⇒ 全部计两遍,
1422
+ // 除以 cpus 只除一次 ⇒ 推导值翻倍(本机实测 199 而非 100)⇒ delta=99 ⇒ 被 1% 阈值打成 assumed。
1423
+ // ⇒ 只数每核行(`cpu\d+`);聚合行等于各核之和,再数一次就是重复计。
1424
+ if (!/^cpu\d+\s/.test(line)) continue;
1425
+ const parts = line.trim().split(/\s+/).slice(1).map(Number);
1426
+ if (parts.every((n) => Number.isFinite(n))) jiffies += parts.reduce((a, b) => a + b, 0);
1427
+ }
1428
+ const uptime = os.uptime();
1429
+ const cpus = Math.max(1, os.cpus().length);
1430
+ if (!Number.isFinite(jiffies) || jiffies <= 0 || !Number.isFinite(uptime) || uptime <= 0) {
1431
+ return { value: CLK_TCK_ASSUMED, source: "assumed", assumedReason: "stat_unreadable" };
1432
+ }
1433
+ const derived = Math.round(jiffies / (uptime * cpus));
1434
+ if (!Number.isFinite(derived) || derived < 1 || derived > 100_000) {
1435
+ return { value: CLK_TCK_ASSUMED, source: "assumed", assumedReason: "derived_out_of_range" };
1436
+ }
1437
+ // 2026-10-31 —— 「相等」在浮点比较里需要容差,而容差是新的魔数。
1438
+ // ⇒ 不做二选一,而是**报差值 + 误差界**:
1439
+ // delta = derived − 100(以 tick/s 为单位);它隐含的启动时刻误差 ≈ uptime × |delta| / value。
1440
+ // 差值大到不可能是舍入(>1%)⇒ 假设已坏(典型成因:机器挂起过 —— jiffies 不涨而 uptime 涨)
1441
+ // ⇒ 退回 assumed,并把原因写进偏差值里,而不是继续报 derived。
1442
+ const estimate = Math.round((jiffies / (uptime * cpus)) * 100) / 100;
1443
+ const delta = derived - CLK_TCK_ASSUMED;
1444
+ const relErr = Math.abs(delta) / Math.max(1, derived);
1445
+ // 这两项**无论退不退回都要发布**:它们是「尺子的分辨率」与「守卫的检出下限」,
1446
+ // 退回 assumed 只说明「我不信这个值」,不说明这两件事没发生。
1447
+ const RULER_FLOOR_MS = 500 + 10;
1448
+ const errorMs = RULER_FLOOR_MS + Math.round((uptime * Math.abs(delta) / Math.max(1, derived)) * 1000);
1449
+ const guardMinSuspendS = Math.round(0.01 * uptime);
1450
+ if (relErr > 0.01) {
1451
+ return {
1452
+ value: CLK_TCK_ASSUMED, source: "assumed", assumedReason: "rel_error_above_1pct",
1453
+ delta, errorMs, guardMinSuspendS, estimate,
1454
+ };
1455
+ }
1456
+ // 2026-10-31 —— 误差界必须有**地板**。
1457
+ // uptime×|delta|/value 只覆盖「尺子自己的舍入」,delta=0 时它报 0;
1458
+ // 而 btime 是**整秒**(±500ms)、/proc/stat 的 jiffies 是 10ms 量化。
1459
+ // ⇒ 这两项不会因为尺子变准而消失 ⇒ 误差界的最小值是「尺子之外的误差之和」,不是 0。
1460
+ // (外部复核原话:一个误差界在「尺子最准」时报 0,说明它只覆盖了尺子的误差。)
1461
+ return {
1462
+ value: derived,
1463
+ source: Math.abs(delta) < 0.5 ? "confirmed" : "derived",
1464
+ delta,
1465
+ errorMs,
1466
+ estimate,
1467
+ // 2026-10-31 —— 阈值决定了它抓得住多大的异常:relErr ≈ 挂起时长 / uptime ⇒ 1% ⇒ 挂起 ≥ 1% uptime。
1468
+ // 134 天的机器 ⇒ ≈ 32 小时才触发 ⇒ 一小时的挂起读成「没有挂起」(derived 与 confirmed 只差一个容差)。
1469
+ // ⇒ 把这个量级印出来,读者才知道自己手里的 derived 意味着「没发生」还是「太小没看见」。
1470
+ guardMinSuspendS,
1471
+ };
1472
+ } catch {
1473
+ return { value: CLK_TCK_ASSUMED, source: "assumed", assumedReason: "stat_unreadable" };
1474
+ }
1475
+ }
1476
+
1477
+ const CLK_TCK = clkTck();
1478
+ const CLK_TCK_DELTA = CLK_TCK.delta ?? null;
1479
+ const CLK_TCK_ERROR_MS = CLK_TCK.errorMs ?? null;
1480
+ const CLK_TCK_GUARD_MIN_SUSPEND_S = CLK_TCK.guardMinSuspendS ?? null;
1481
+ const CLK_TCK_ASSUMED_REASON = CLK_TCK.assumedReason ?? null;
1482
+ const CLK_TCK_ESTIMATE = CLK_TCK.estimate ?? null;
1483
+ /** 机器 uptime(秒)。与 `uptime`(进程)分开报:守卫的阈值以这台机器为量纲。 */
1484
+ const HOST_UPTIME_S = (() => {
1485
+ try {
1486
+ const u = (require("node:os") as typeof import("node:os")).uptime();
1487
+ return Number.isFinite(u) ? Math.round(u) : null;
1488
+ } catch { return null; }
1489
+ })();
1490
+ /** agreement 的**分类**阈值(不是发布闸门):超过它就算「内核与自报对不上」。 */
1491
+ const EPOCH_AGREEMENT_MS = 10_000;
1492
+
1493
+ function detectKernelStart(startedAtIso: string): {
1494
+ boot_id: string | null;
1495
+ pid: number;
1496
+ proc_start_ticks: number | null;
1497
+ kernel_started_at: string | null;
1498
+ kernel_started_at_note: string | null;
1499
+ clk_tck_assumed: number;
1500
+ clk_tck_source: "confirmed" | "derived" | "assumed";
1501
+ epoch_agreement: "agree" | "disagree" | "unknown";
1502
+ epoch_delta_ms: number | null;
1503
+ /**
1504
+ * 2026-10-31 —— 把**推导的前提**做成读数。
1505
+ * 推导「kernel_started_at = btime + ticks/CLK_TCK」依赖「这台机器没挂起过」,
1506
+ * 而挂起留下的唯一痕迹就是:(now − btime) 与 /proc/uptime 的差。
1507
+ * ⇒ 有了它,derived 带着前提;没有它,前提在读数之外,推导的正确性只是没被推翻过。
1508
+ */
1509
+ suspend_total_s: number | null;
1510
+ } {
1511
+ const pid = process.pid;
1512
+ let bootId: string | null = null;
1513
+ try {
1514
+ const raw = require("node:fs").readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
1515
+ if (/^[0-9a-f-]{16,64}$/i.test(raw)) bootId = raw;
1516
+ } catch { /* 非 Linux 或不可读 ⇒ null */ }
1517
+
1518
+ let ticks: number | null = null;
1519
+ try {
1520
+ const stat = require("node:fs").readFileSync("/proc/self/stat", "utf8");
1521
+ const close = stat.lastIndexOf(")");
1522
+ if (close >= 0) {
1523
+ const rest = stat.slice(close + 1).trim().split(/\s+/);
1524
+ const n = Number(rest[19]); // 第 22 字段(`')' 之后` 从 state 起算 ⇒ 索引 19)
1525
+ if (Number.isFinite(n)) ticks = n;
1526
+ }
1527
+ } catch { /* null */ }
1528
+
1529
+ let btime: number | null = null;
1530
+ try {
1531
+ const stat = require("node:fs").readFileSync("/proc/stat", "utf8");
1532
+ const m = /^btime\s+(\d+)/m.exec(stat);
1533
+ if (m) btime = Number(m[1]);
1534
+ } catch { /* null */ }
1535
+
1536
+ if (ticks === null || btime === null) {
1537
+ return {
1538
+ boot_id: bootId, pid, proc_start_ticks: ticks,
1539
+ kernel_started_at: null,
1540
+ kernel_started_at_note: "proc_btime_or_ticks_unavailable",
1541
+ clk_tck_assumed: CLK_TCK.value,
1542
+ clk_tck_source: CLK_TCK.source,
1543
+ epoch_agreement: "unknown",
1544
+ epoch_delta_ms: null,
1545
+ suspend_total_s: null,
1546
+ };
1547
+ }
1548
+ const candidateMs = (btime + ticks / CLK_TCK.value) * 1000;
1549
+ const selfMs = Date.parse(startedAtIso);
1550
+ // 自报值解析不了 ⇒ 只影响 agreement,不影响内核读数的发布
1551
+ const delta = Number.isFinite(selfMs) ? candidateMs - selfMs : null;
1552
+ const agreement: "agree" | "disagree" | "unknown" =
1553
+ delta === null ? "unknown" : Math.abs(delta) <= EPOCH_AGREEMENT_MS ? "agree" : "disagree";
1554
+ return {
1555
+ boot_id: bootId,
1556
+ pid,
1557
+ proc_start_ticks: ticks,
1558
+ kernel_started_at: new Date(candidateMs).toISOString(),
1559
+ kernel_started_at_note: null,
1560
+ clk_tck_assumed: CLK_TCK.value,
1561
+ clk_tck_source: CLK_TCK.source,
1562
+ epoch_agreement: agreement,
1563
+ epoch_delta_ms: delta === null ? null : Math.round(delta),
1564
+ suspend_total_s: suspendTotalSeconds(btime),
1565
+ };
1566
+ }
1567
+
1568
+ /**
1569
+ * 累计挂起时长(秒)= 墙钟自开机以来 − /proc/uptime。
1570
+ *
1571
+ * btime 是开机时刻的**墙钟**(挂起期间照走),而 /proc/uptime 统计的是**不挂起**的时长
1572
+ * ⇒ 两者之差就是累计挂起。取不到(非 Linux / 读失败)⇒ null,不给 0。
1573
+ * 「0 秒挂起」与「不知道挂没挂起」在读数上必须不同:前者是推导的前提成立,后者是前提未知。
1574
+ */
1575
+ function suspendTotalSeconds(btime: number | null): number | null {
1576
+ if (btime === null) return null;
1577
+ try {
1578
+ const os = require("node:os") as typeof import("node:os");
1579
+ const uptime = os.uptime();
1580
+ if (!Number.isFinite(uptime)) return null;
1581
+ const wall = Date.now() / 1000 - btime;
1582
+ const diff = wall - uptime;
1583
+ // btime 是整秒 ⇒ |diff| < 1s 的读数就是 0(不是负挂起);明显为负 ⇒ 时钟不可信 ⇒ null
1584
+ if (!Number.isFinite(diff) || diff < -5) return null;
1585
+ return Math.max(0, Math.round(diff));
1586
+ } catch {
1587
+ return null;
1588
+ }
1589
+ }
1590
+
1591
+ const BOOT_GIT_COMMIT = BOOT_GIT.commit;
1592
+
1593
+ /**
1594
+ * 2026-10-31 —— 窗口起点**在 boot 时算一次**,不要每次请求重算。
1595
+ *
1596
+ * 原来它是 per-request 的 `new Date(Date.now() - uptime*1000)`:毫秒舍入会让两次读数
1597
+ * 差 1ms ⇒ 而「flapping 判据」正是拿两次读数的 startedAt 比较 ⇒ **同一进程会被读成重启过**。
1598
+ * 一个用于证明“它没重启”的字段,自己每次都在变,是本末倒置。
1599
+ *
1600
+ * 稳定之后它才满足那条判据:`S2 === S1 ⇒ 没重启`。
1601
+ */
1602
+ const startedAtIso = new Date(Date.now() - Math.floor(process.uptime() * 1000)).toISOString();
1603
+
1604
+ const BOOT_KERNEL_START = detectKernelStart(startedAtIso);
1605
+
901
1606
  function withCors(req: Request, res: Response): Response {
902
1607
  const headers = corsHeaders(req);
903
1608
  for (const [k, v] of Object.entries(headers)) {
@@ -2234,7 +2939,7 @@ return Bun.serve({
2234
2939
  return {
2235
2940
  node_id: n.node_id, alias: n.alias, display_name: n.display_name, owner_user_id: n.owner_user_id,
2236
2941
  status: session?.status ?? "offline", last_seen_at: session?.last_seen_at ?? null,
2237
- health: h?.health ?? null, degraded: degradedLayers(h?.health).map((l) => ({ layer: l.layer, label: l.label, reason: l.reason })),
2942
+ health: h?.health ?? null, degraded: degradedLayers(h?.health).map((l) => ({ layer: l.layer, label: l.label, reason: l.reason, origin: l.origin })),
2238
2943
  };
2239
2944
  });
2240
2945
  return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, nodes }));
@@ -2705,9 +3410,26 @@ return Bun.serve({
2705
3410
  // dashboard user proxies with the logged-in user's utok_ so
2706
3411
  // their own network's aliases surface; strangers' networks do
2707
3412
  // not
2708
- const count = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions");
3413
+ // 2026-10-31 —— 「200 那一格」原来没有任何 body 判据:ok 恒 true。
3414
+ // 于是「活着但降级」与「一切正常」在读数上同形(与 counters.releases 同族)。
3415
+ // ⇒ 这里记录读库是否成功,供下面的 status 使用;不改变 200 这个 HTTP 承诺。
3416
+ let dbReadable = true;
3417
+ let count: { cnt: number } | undefined;
3418
+ try {
3419
+ count = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions");
3420
+ } catch {
3421
+ dbReadable = false;
3422
+ }
2709
3423
  const sse = getSSEStats();
2710
- const license = db.get<any>("SELECT type, expires_at FROM licenses LIMIT 1");
3424
+ // 2026-10-31 —— 查询失败不再拖垮整个 /health(它有 500 兜底,但健康端点不该因附属数据挂掉),
3425
+ // 并且让「查失败」与「没有 license 行」在读数上可分(见 license-state.ts)。
3426
+ let license: any = null;
3427
+ let licenseQueryFailed = false;
3428
+ try {
3429
+ license = db.get<any>("SELECT type, expires_at FROM licenses LIMIT 1");
3430
+ } catch {
3431
+ licenseQueryFailed = true;
3432
+ }
2711
3433
 
2712
3434
  // Non-fatal auth probe (no 401 — /health must stay 200 anonymous).
2713
3435
  const healthAuth = resolveRequestAuth(req);
@@ -2773,12 +3495,27 @@ return Bun.serve({
2773
3495
  // scopedSessions undefined → sse_sessions field omitted entirely
2774
3496
  // (watchdog + arbitrary internet strangers see aggregates only).
2775
3497
 
3498
+ const statusReasons: string[] = [];
3499
+ if (!dbReadable) statusReasons.push("db_unreadable");
3500
+ if (licenseQueryFailed) statusReasons.push("license_unreadable");
2776
3501
  const body: Record<string, unknown> = {
2777
3502
  ok: true,
3503
+ // 200 是**承诺**(watchdog 契约),不等于「健康」。健康与否放在 body 里:
3504
+ status: statusReasons.length === 0 ? "ok" : "degraded",
3505
+ status_reasons: statusReasons,
2778
3506
  version: SERVER_VERSION,
3507
+ // 2026-10-31 —— **version 是部署标签,不是代码指纹**(生产实例:4 分钟内 version 变、
3508
+ // buildCommit 一字未变,同 commit 重新打包)。
3509
+ // ⇒ 任何以 version 为键的巡检/回滚检测都会假跳或永远不跳。
3510
+ // ⇒ 这里把它的角色写进载荷本身,因为**读者不会去查它数的是什么**。
3511
+ // 判据:监控/告警/对账只认 buildCommit(本字段鉴权可见);version 只用于人读。
3512
+ version_role: "deployment_label",
2779
3513
  api_version: "v3",
2780
3514
  transport: "streamable-http",
2781
- sessions_count: count?.cnt ?? 0,
3515
+ // 2026-10-31 —— 读库失败时给 null,不给 0。
3516
+ // 「0 个会话」与「读不到」在读数上同形,而 0 是一个合法值 ⇒ 它会被当成事实。
3517
+ // 兄弟字段 status_reasons 里已有 db_unreadable,两者一起读才构成完整读数。
3518
+ sessions_count: count?.cnt ?? null,
2782
3519
  sse_connections: sse.total,
2783
3520
  // #2363 —— MCP 在飞数(只观测)。RSS 与它成正比(≈1.2–1.4 MB/条),
2784
3521
  // 而 `sse_connections` 只反映长连接,看不到“同秒打进来的一批请求”。
@@ -2801,14 +3538,72 @@ return Bun.serve({
2801
3538
  // 上一轮清理(85%)之后它只用了一天多就涨回去 10 个点,靠人「偶尔看一眼」
2802
3539
  // 必然会漏。Hub 的 DB、日志、运行时目录都写在这块盘上,写满即生产停摆,
2803
3540
  // 所以这个数字应该和 sessions/stalls 一样随手可见。
2804
- host_disk: hostDiskState(),
3541
+ host_disk: redactHomeInPath(hostDiskState()),
2805
3542
  auth: DEV_OPEN ? "dev-open" : "user-token",
2806
3543
  security: DEV_OPEN ? "dev-open" : "secured",
2807
3544
  tmux: TMUX_ENABLED ? "enabled" : "disabled",
2808
3545
  v3_auth: true,
2809
3546
  multi_network: true,
2810
- license: license?.type || "none",
3547
+ // 兼容字段:语义不精确("none" 同时表示「没有行」「type 为空」「查失败」),勿用于判据。
3548
+ license: legacyLicenseField(license),
3549
+ // 判据请用这个三态:known / absent / unknown(reason)
3550
+ license_state: licenseStateOf(license, licenseQueryFailed),
2811
3551
  uptime: Math.floor(process.uptime()),
3552
+ // 2026-10-31 —— 把窗口起点显式暴露。
3553
+ // 同一响应里的 stall_count / last_stall_at / recent_stalls 以及各 …last_error_at
3554
+ // 的观测窗口都只是 [startedAt, now],重启即归零。
3555
+ // 只给 uptime 时读者要自己换算,实际使用中经常被忽略 ⇒
3556
+ // “stall_count: 0”于是被读成“从未卡顿”。给出绝对时刻让窗口可被外部计算。
3557
+ startedAt: startedAtIso,
3558
+ // 2026-10-31 —— 「站位」要可验,但**可读性必须与敏感性配对**。
3559
+ //
3560
+ // /health 是**匿名**端点(watchdog 契约)。commit sha 对匿名读者等于
3561
+ // 「精确告诉外部这是哪一版代码」——本仓是公开仓 ⇒ 等于把已知问题清单指给外人。
3562
+ // ⇒ 匿名只回答「有没有构建标识」,**不给是什么**;完整值只给已鉴权者。
3563
+ // 与 SSE 明细同一条规则:匿名给聚合、鉴权给明细。
3564
+ build_identified: BOOT_GIT_COMMIT !== null,
3565
+ // 2026-10-31 —— 常驻的 served_at:让「窗口」有两个时刻戳,而不是只有一个起点。
3566
+ //
3567
+ // 没有它,读者算速率只能拿**自己的**时钟去减 since ⇒ 偷偷假设了「我的钟和他的钟一致」。
3568
+ // 而计数器是这台机器上的累计值 ⇒ 窗口的两端必须在**同一个时钟域**里。
3569
+ // 判据:凡是速率/窗口类字段,分子分母各要自己的时刻戳;**被声明的那个永远不算**。
3570
+ served_at: new Date().toISOString(),
3571
+ // 2026-10-31 —— 内核口径的进程身份:**这一组是判据**(不含单位假设、不会被自报值否决)。
3572
+ // 「进程在自报时间上撒谎」不再表现为 null,而是 epoch_agreement=disagree + 差值。
3573
+ boot_id: BOOT_KERNEL_START.boot_id,
3574
+ pid: BOOT_KERNEL_START.pid,
3575
+ proc_start_ticks: BOOT_KERNEL_START.proc_start_ticks,
3576
+ kernel_started_at: BOOT_KERNEL_START.kernel_started_at,
3577
+ kernel_started_at_note: BOOT_KERNEL_START.kernel_started_at_note,
3578
+ // 判据是上面三元组;这两个只是把「内核 vs 自报」的分歧**显式化**,
3579
+ // 而不是像原来那样把它折进一个 null(null 会让「算不出来」和「两边打架」同形)。
3580
+ clk_tck_assumed: BOOT_KERNEL_START.clk_tck_assumed,
3581
+ clk_tck_source: BOOT_KERNEL_START.clk_tck_source,
3582
+ // 2026-10-31 —— confirmed 必须报「差多少」并给误差界,否则它会被读成「精确」,
3583
+ // 而它只是「在一个没写出来的容差内」。
3584
+ clk_tck_delta: CLK_TCK_DELTA,
3585
+ kernel_started_at_error_ms: CLK_TCK_ERROR_MS,
3586
+ clk_tck_guard_min_suspend_s: CLK_TCK_GUARD_MIN_SUSPEND_S,
3587
+ clk_tck_assumed_reason: CLK_TCK_ASSUMED_REASON,
3588
+ clk_tck_estimate: CLK_TCK_ESTIMATE,
3589
+ host_uptime_s: HOST_UPTIME_S,
3590
+ suspend_total_s: BOOT_KERNEL_START.suspend_total_s,
3591
+ epoch_agreement: BOOT_KERNEL_START.epoch_agreement,
3592
+ epoch_delta_ms: BOOT_KERNEL_START.epoch_delta_ms,
3593
+ // 🔴 这一对**属于鉴权投影**(不在 PUBLIC_HEALTH_KEYS 里):
3594
+ // commit sha 对匿名读者 = 精确告诉外部这是哪一版代码(本仓公开)。
3595
+ // 与 git_commit 成对:dirty=true ⇒ 只能写 prod@自称,不能写 prod@<sha>。
3596
+ git_commit: BOOT_GIT_COMMIT,
3597
+ git_dirty: BOOT_GIT.commit ? BOOT_GIT.dirty : null,
3598
+ // 2026-10-31 —— 每个可为 null 的字段都要有一个**能解释它的兄弟字段**。
3599
+ // 没有它时,「不是 git 树」「git 不可用」「rev-parse 输出异常」三种成因同形。
3600
+ build_identity_note: BOOT_GIT.reason,
3601
+ git_identity_root: BOOT_GIT.root_kind,
3602
+ // 2026-10-31 —— 拒绝原因计数(与那条日志同一位置 +1,不会漏记)。
3603
+ // 🔴 必须带窗口:计数器随进程重启归零,而「归零」与「没有发生」在读数上同值。
3604
+ // 所以它和 startedAt 一起读 —— 窗口 = [startedAt, now]。
3605
+ // (历史教训:拿累计值除以 uptime 当速率 ⇒ 分母与分子不独立 ⇒ 刚重启必假阳性。)
3606
+ counters: { since: startedAtIso, task_rejections: taskRejectionCounters() },
2812
3607
  // #496 — public, stable capability data. Dashboard upload proxies
2813
3608
  // need the Hub's real limits before opening a streaming request;
2814
3609
  // duplicating these constants client-side creates a silent
@@ -2824,7 +3619,62 @@ return Bun.serve({
2824
3619
  capabilities: HUB_HEALTH_CAPABILITIES,
2825
3620
  };
2826
3621
  if (scopedSessions !== undefined) body.sse_sessions = scopedSessions;
2827
- return withCors(req, Response.json(body));
3622
+
3623
+ // 🔴 投影放在**最外层**:先构全量,再决定给谁。
3624
+ // 这样新字段默认落在鉴权侧;只有显式写进 PUBLIC_HEALTH_KEYS 的才匿名可见。
3625
+ // 🔴 白名单只作用于**匿名**读者。
3626
+ // 任何已鉴权调用者(成员 token / master / admin / dev-open)拿到全量 ——
3627
+ // 否则会把「成员可见的 sse_sessions」误伤成匿名投影(我曾这么错过一次)。
3628
+ // 安全边界在「有没有身份」,不在「身份多高」。
3629
+ // 注意:投影必须调用在**所有字段写完之后**(探针字段是后加的),
3630
+ // 所以这里只做一个惰性函数,而不是提前算好一个快照。
3631
+ const isAnonymous = !healthAuth && !healthIsMaster && !healthIsDevOpen;
3632
+ const shape = (b: Record<string, unknown>) => (isAnonymous ? projectPublicHealth(b) : b);
3633
+ // 2026-10-31 —— 「这一次」的判据(探针回显)。
3634
+ //
3635
+ // /health 恒 200,于是「200」只证明*某处*有个 200:证不了是这台机器、这个进程,
3636
+ // 更证不了**是这个请求**。缓存层、前面的代理、上一次运行留下的响应,
3637
+ // 都会给出同一个 200 —— 而且失败不会产生空值,它产生的是**上一次的值**。
3638
+ //
3639
+ // 请求方带一个随机 nonce(`X-Probe-Nonce`),我们原样回显:
3640
+ // 响应体里出现这个 nonce ⇔ 这个响应是在**收到这个请求之后**生成的。
3641
+ // 这比 `startedAt` 强一格:startedAt 证明「某个实例在答」,nonce 证明「这一次」,
3642
+ // 因为缓存不可能为一个**新的** nonce 生成响应。
3643
+ //
3644
+ // 🔴 只在带该头时追加两个键,默认响应体逐字节不变(那边有键集断言钉着)。
3645
+ const probeNonce = probeNonceOf(req);
3646
+ if (probeNonce) {
3647
+ body.probe_nonce = probeNonce;
3648
+ // `served_at` 现在是**常驻**字段(见 base body):它给的是这个响应生成时的服务端时刻,
3649
+ // 与 counters.since / startedAt 同一时钟域 ⇒ 窗口两端可比。
3650
+ // 但它仍然**不证明新鲜**:证明“这一次”的是 probe_nonce(缓存不可能为新 nonce 生成响应)。
3651
+ // 2026-10-31 —— 「三件套」的第③件:把 nonce 写进**响应之外**的地方。
3652
+ // ① body code 住在响应里(层标识)
3653
+ // ② probe_nonce 住在响应里(本次标识)
3654
+ // ③ 这一行日志 住在响应之外 ⇒ 中间层能伪造响应,伪造不了服务端日志
3655
+ // 判据:探针发 nonce(一次性、不复用)⇒ 响应回显 ⇒
3656
+ // `grep -c "probe nonce=<value>" <hub log>` 必须为 **1**。
3657
+ // == 1 ⇒ 这次请求真的到了这个进程;
3658
+ // == 0 ⇒ 响应是别处伪造/伪造不了的日志缺失;
3659
+ // > 1 ⇒ 有人在复用同一个 nonce(重试没换)⇒ 那次读数不可信(见下)。
3660
+ // 🔴 nonce 必须一次性:重试要生成新的。复用会让缓存返回上一次的响应,
3661
+ // 而那响应里恰好有同一个 nonce ⇒ 会被读成“新鲜”。上面那条 ==1 正是拦它的。
3662
+ // 只在带该头时打印,所以日志量与探针次数同阶,不随请求速率增长。
3663
+ console.log(`[health] probe nonce=${probeNonce}`);
3664
+ }
3665
+ // 2026-10-31 —— **单一出口**。
3666
+ // 之前是两个 return 各自记得调 shape()(匿名投影)—— 而「必须在所有字段写完之后执行」
3667
+ // 的变换,多出口 × 惰性 = 迟早漏:下一个人加第三条出口(比如 degraded 分支)就会裸奔。
3668
+ // ⇒ 收敛成一个 return,投影与 header 都在这里做完。
3669
+ const healthRes = Response.json(shape(body));
3670
+ // 2026-10-31 —— **一律不可缓存**,不只是带 nonce 的那一份。
3671
+ //
3672
+ // 原来只有 probe_nonce 存在时才设 no-store。而 /health 的每个字段都是「此刻的读数」:
3673
+ // 一旦某层做协商缓存返回 304,`startedAt` 会冻结而 `counters` 照涨 ——
3674
+ // **那正是 flapping 的假阳性形状**(看起来像「刚重启过」)。
3675
+ // ⇒ 探针还必须显式断言 200 而非 304(见 health-redaction 的对应用例)。
3676
+ healthRes.headers.set("Cache-Control", "no-store");
3677
+ return withCors(req, healthRes);
2828
3678
  }
2829
3679
 
2830
3680
  // ── All REST /api endpoints require auth (if token configured) ──
@@ -3350,6 +4200,37 @@ return Bun.serve({
3350
4200
  }
3351
4201
  return withCors(req, Response.json({ ...providers, network_id: networkId }));
3352
4202
  }
4203
+ // 2026-10-31 —— **写侧也必须有 HTTP 面**,否则「第一行」只能由会用 MCP 的人录入。
4204
+ //
4205
+ // 现状:读有 REST(/api/providers),写只有 MCP(provider 工具 action=hub_put)
4206
+ // ⇒ 客户端能显示「还没有 provider」,却没有任何办法把它变成「有」;
4207
+ // 而这一步恰好是「可选模型」的唯一阻塞。
4208
+ // 这里不复制校验逻辑:直接调用**同一个** putHubProvider,
4209
+ // 权限(owner)与校验(revision、模型名、baseUrl)都保持不变。
4210
+ if (url.pathname === "/api/providers" && req.method === "PUT") {
4211
+ if (!restAuth) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
4212
+ if (restAuth.networkId) return userTokenRequired(req);
4213
+ const networkId = singleNetworkId(restScope);
4214
+ if (!networkId) return withCors(req, Response.json({ ok: false, error: "network_id_required" }, { status: 400 }));
4215
+ const role = restAuth.userId ? getUserNetworkRole(restAuth.userId, networkId) : null;
4216
+ if (!isAdmin && role !== "owner" && role !== "admin") {
4217
+ return withCors(req, Response.json({ ok: false, error: "permission_denied", message: "network owner/admin only" }, { status: 403 }));
4218
+ }
4219
+ let body: any = null;
4220
+ try { body = await req.json(); } catch { return withCors(req, Response.json({ ok: false, error: "invalid_json" }, { status: 400 })); }
4221
+ const revision = Number.isSafeInteger(body?.revision) ? body.revision : NaN;
4222
+ if (!Number.isSafeInteger(revision)) {
4223
+ return withCors(req, Response.json({ ok: false, error: "invalid_revision", hint: "传 0 表示新建;后续传回读到的 revision" }, { status: 400 }));
4224
+ }
4225
+ const saved = putHubProvider({ userId: restAuth.userId ?? null, isNode: false, networkId }, revision, body?.provider);
4226
+ if (!saved.ok) {
4227
+ const status = saved.error === "provider_owner_required" ? 403
4228
+ : saved.error === "hub_provider_revision_conflict" ? 409
4229
+ : saved.error === "provider_access_denied" ? 403 : 400;
4230
+ return withCors(req, Response.json(saved, { status }));
4231
+ }
4232
+ return withCors(req, Response.json({ ...saved, network_id: networkId }));
4233
+ }
3353
4234
 
3354
4235
  // ── #1510: the log-only view of the secret transport gate ──
3355
4236
  //
@@ -6302,6 +7183,21 @@ export function startHub(opts?: { port?: number; hostname?: string }): ReturnTyp
6302
7183
  * 为什么不在这里做告警:告警需要阈值与通知渠道,属于运维策略;这里只提供**可观测**。
6303
7184
  * 客户端/巡检脚本按 `used_pct > 90` 自己决定要不要叫。
6304
7185
  */
7186
+ /**
7187
+ * `/health` 是**免鉴权**端点,而 host_disk.path 是数据库所在目录 ——
7188
+ * 在常见部署里就是 `$HOME/.commhub/`,等于把用户名公开出去。
7189
+ * 形状(挂载点)是运维需要的信息,**具体家目录名不是**。
7190
+ * 只在响应层做替换:hostDiskState() 仍返回真实路径(测试与 statfs 要用)。
7191
+ */
7192
+ export function redactHomeInPath<T extends { path: string } | null>(d: T): T {
7193
+ if (!d) return d;
7194
+ const home = process.env.HOME || homedir();
7195
+ if (!home || home === "/") return d;
7196
+ return d.path === home || d.path.startsWith(home + "/")
7197
+ ? { ...d, path: "~" + d.path.slice(home.length) }
7198
+ : d;
7199
+ }
7200
+
6305
7201
  export function hostDiskState(): { path: string; total_gb: number; used_gb: number; avail_gb: number; used_pct: number } | null {
6306
7202
  try {
6307
7203
  // 探针打在**数据库实际所在目录**上,而不是写死 `/`:多挂载点主机也能对得上。