@sleep2agi/agent-network 2.3.0-preview.9 → 2.3.0-preview.90

package/dist/src/copresence-identity.d.ts

@@ -0,0 +1,339 @@
+export interface SessionInfo {
+    tmux: string;
+    pid: number;
+    pgid: number;
+    starttime_jiffies: number;
+}
+export interface CopresenceMarker {
+    marker: string;
+    boot_id: string;
+    started_at_epoch_ms: number;
+    owner_uid: number;
+    sessions: {
+        appsrv?: SessionInfo;
+        bridge?: SessionInfo;
+        tui?: SessionInfo;
+    };
+}
+export type RefuseCause = "MISSING" | "SYMLINK" | "NOT_REGULAR" | "WRONG_MODE" | "OWNER_MISMATCH" | "PARSE_ERROR" | "SCHEMA_INVALID" | "STALE_BOOT_ID" | "PLATFORM_UNSUPPORTED";
+export type ReadMarkerResult = {
+    kind: "ok";
+    marker: CopresenceMarker;
+} | {
+    kind: "refuse";
+    cause: RefuseCause;
+    detail: string;
+};
+export interface ProcStat {
+    pgid: number;
+    starttime_jiffies: number;
+    ppid: number;
+}
+/**
+ * Injectable primitive for /proc access. Real impl reads the filesystem;
+ * unit tests inject a mock so /proc-based logic is deterministically testable.
+ *
+ * Contract:
+ *   - listAllPids: read /proc directory and return numeric-name entries.
+ *     Throws on unrecoverable errors (permission denied on /proc itself).
+ *   - readEnviron: read /proc/<pid>/environ as a raw string. Returns null
+ *     if the pid has vanished (ENOENT) — that's a normal race, not a failure.
+ *     Throws for permission errors etc.
+ *   - readStat: read /proc/<pid>/stat and extract (pgid, starttime, ppid).
+ *     Returns null on ENOENT (pid gone). Throws on other errors.
+ */
+export interface ProcessEnumerator {
+    listAllPids(): number[];
+    readEnviron(pid: number): string | null;
+    readStat(pid: number): ProcStat | null;
+    /**
+     * REAL uid of the process itself (`Uid:` line of /proc/<pid>/status,
+     * field 0). Used by the environ-EACCES discriminator to tell
+     * "other-user process (expected EACCES)" from "our own process we could
+     * not inspect (must be accounted for)".
+     *
+     * MUST NOT be implemented as `statSync('/proc/<pid>/environ').uid`.
+     * A process that called prctl(PR_SET_DUMPABLE, 0) keeps its real uid but
+     * its /proc/<pid>/{environ,mem,...} nodes flip to root:root 0400 (see
+     * proc(5) / kernel `task_dump_owner`). Deriving ownership from the
+     * environ inode therefore reports uid 0 for our OWN non-dumpable
+     * children, which made them invisible to the scan: not in `hits`, not in
+     * the unreadable list, so teardown reported success and deleted the
+     * marker while the orphan lived on (Defect A).
+     *
+     * Returns null if the pid is gone (ENOENT) or if even /proc/<pid>/status
+     * is blocked (hidepid / LSM) — in that case the process cannot be ours
+     * to reason about and is skipped.
+     */
+    readOwnerUid(pid: number): number | null;
+    /**
+     * Single-character process state from /proc/<pid>/status (R/S/D/Z/T/...).
+     * `Z` means zombie — mm freed, environ returns EACCES even to owner, but
+     * the pid is going away shortly. Skip zombies during environ scan.
+     * Returns null if the pid is gone (ENOENT).
+     */
+    readState(pid: number): string | null;
+}
+/**
+ * Injectable primitive for sending signals. Real impl uses process.kill;
+ * tests inject a mock.
+ */
+export interface KillPrimitive {
+    killPgroup(pgid: number, signal: "TERM" | "KILL"): void;
+    /** Returns true if ANY process in the pgroup is still alive. */
+    pgroupAlive(pgid: number): boolean;
+}
+export declare function markerFilePath(nodesDir: string, nodeId: string): string;
+export declare function readBootId(): string;
+/**
+ * Write the marker file atomically.
+ *
+ * IMPORTANT (Blocker 1 fix): the uuid parameter is the SINGLE SOURCE OF
+ * TRUTH. Caller is expected to inject this same uuid into every tmux
+ * session's ANET_NODE_MARKER env var. writeMarker does NOT generate its
+ * own uuid — that was the exact bug in 9f2ec282.
+ */
+export declare function writeMarker(nodesDir: string, nodeId: string, uuid: string, sessions: CopresenceMarker["sessions"]): CopresenceMarker;
+/**
+ * Read the marker file with structured fail-closed refuses.
+ *
+ * Never throws for expected refuse causes. Only throws if the OS itself
+ * is broken (e.g. EIO). Malformed JSON, wrong types, null bodies etc.
+ * all return { kind: "refuse", cause, detail }.
+ */
+export declare function readMarker(nodesDir: string, nodeId: string): ReadMarkerResult;
+export declare function removeMarker(nodesDir: string, nodeId: string): void;
+export declare function realEnumerator(): ProcessEnumerator;
+export declare function realKiller(): KillPrimitive;
+/**
+ * Scan /proc for all pids whose environ contains ANET_NODE_MARKER=<uuid>.
+ * This is the authoritative identity source — NOT the marker file's stored
+ * pids, which may be stale (main died, workers survived under new pgids).
+ *
+ * Bytes format of /proc/PID/environ: NUL-separated key=value pairs.
+ *
+ * Blocker 1 fix (independent audit 92d53c8f, 2026-07-29): /proc/<pid>/environ
+ * is 0400 owner-only. Blindly reading it will hit EACCES on every other-user
+ * process (pid 1 is systemd/root → guaranteed EACCES). The naive fix — wrap
+ * in try/catch and continue — would silently miss marker-carrying processes
+ * whose environ we can't read for some other reason, recreating Defect A
+ * ("nothing killed but report success"). Right fix:
+ *
+ *   1. Try readEnviron.
+ *   2. On EACCES, discriminate via readOwnerUid + readState:
+ *      - Owner uid != ours     → EXPECTED skip (can't be one of our procs).
+ *      - Own uid, state = Z    → EXPECTED skip (zombie, mm freed).
+ *      - Own uid, not zombie   → FAIL-CLOSED (unexplained EACCES on our own
+ *                                live process is a real problem, must throw).
+ */
+export interface ScanResult {
+    /** Pids whose environ we successfully read and matched the marker uuid. */
+    hits: number[];
+    /**
+     * Own-uid, live, environ-unreadable pids that are PLAUSIBLY PART OF THE
+     * COPRESENCE TREE (invariant 11 scope test). These might be marker-
+     * carrying without us being able to prove it, so the reap flow REFUSES
+     * marker removal while this list is non-empty — defense against Defect A
+     * (silently missing a marker-carrying process, then deleting the marker
+     * as if teardown had succeeded).
+     */
+    unreadableOwnUid: number[];
+    /**
+     * Own-uid, live, environ-unreadable pids that failed the scope test:
+     * their pgid belongs to no marker-carrying group and their ppid chain
+     * reaches no marker carrier / validated marker-file session pid.
+     *
+     * INFORMATIONAL ONLY — never fail-closed. A machine routinely has such
+     * processes (a same-uid process whose primary GID differs from ours fails
+     * the kernel's __ptrace_may_access gid check and EACCESes on environ even
+     * though its real uid matches). v2 lumped these into unreadableOwnUid,
+     * which made reapMarkerGroups structurally unable to return success on
+     * any such host.
+     *
+     * KNOWN RESIDUAL GAP (stated rather than papered over): a marker-carrying
+     * process that is BOTH non-dumpable (environ unreadable) AND fully
+     * detached (setsid'd into its own pgroup with ppid=1, no live recorded
+     * session pid above it) lands here and is therefore not reaped and does
+     * not block marker removal. Nothing in /proc exposes the environment of a
+     * non-dumpable task to a non-root reader, so no scope widening can
+     * recover it — only running teardown as root could. Widening scope to
+     * "every same-uid unreadable process" is NOT an acceptable trade: that is
+     * exactly the v2 behaviour that made teardown never succeed. The
+     * realistic copresence shape (child of a recorded pane pid, or sharing a
+     * marker carrier's pgroup) IS covered — see the real-/proc test.
+     */
+    unreadableOutOfScope: number[];
+}
+/**
+ * Marker-file session records used to anchor the invariant-11 scope test.
+ * Each entry must be re-validated (pid alive AND same starttime) before it
+ * is trusted — see validateAnchors.
+ */
+export interface ScanAnchors {
+    sessions?: Array<{
+        pid: number;
+        starttime_jiffies: number;
+    }>;
+}
+export declare function anchorsFromMarker(marker: CopresenceMarker): ScanAnchors;
+/**
+ * Invariant 11 scope test: is `pid` plausibly part of the copresence tree?
+ *
+ * True when the pid IS an anchor, when its pgid belongs to a marker-carrying
+ * group (or a validated anchor's group), or when walking its ppid chain
+ * reaches an anchor / marker carrier / a pid inside a relevant pgroup.
+ *
+ * Everything else is out of scope and must not participate in a fail-closed
+ * decision, no matter how unreadable it is.
+ */
+export declare function isInCopresenceScope(enumer: ProcessEnumerator, pid: number, relevantPids: Set<number>, relevantPgids: Set<number>): boolean;
+export declare function scanEnvironForMarker(enumer: ProcessEnumerator, markerUuid: string): number[];
+export declare function scanEnvironForMarkerFull(enumer: ProcessEnumerator, markerUuid: string, anchors?: ScanAnchors): ScanResult;
+export declare function groupPidsByPgid(enumer: ProcessEnumerator, pids: number[]): Map<number, number[]>;
+export type HomogeneityResult = {
+    ok: true;
+    members: number[];
+} | {
+    ok: false;
+    cause: "FOREIGN_MEMBER" | "ENUM_ERROR" | "EMPTY_GROUP";
+    foreignPids: number[];
+    unreadablePids: number[];
+    detail: string;
+};
+/**
+ * Verify that EVERY live member of `pgid` carries the marker.
+ *
+ * Blocker 2 fix: enumeration errors surface as ENUM_ERROR (fail-closed),
+ * never as an empty-list judged "safe". Any unreadable member also
+ * fails-closed. Empty group (no live members at all) also refuses — killing
+ * an empty pgroup can't be right and empty-list judged "ok" recreates the
+ * exact defect shape (independent audit 92d53c8f finding #6).
+ *
+ * Blocker 2 second half (zombie): a zombie same-uid process's environ
+ * returns EACCES even to owner (mm freed), but stat still exists with
+ * original pgid. Without discrimination, the zombie would be treated as
+ * "unreadable member" → ENUM_ERROR → entire group SKIPPED. Since re-verify
+ * happens post-SIGTERM (when zombies are most numerous), teardown would
+ * never escalate. Fix: apply the same owner-uid + state=Z discriminator as
+ * scanEnvironForMarker.
+ *
+ * Algorithm:
+ *   1. Enumerate all pids on the system.
+ *   2. Filter to pids whose /proc/PID/stat pgid == target pgid.
+ *   3. For each such pid, check its environ with EACCES discrimination:
+ *      - Other-user EACCES  → skip (can't be ours anyway).
+ *      - Own-uid zombie     → skip (expected, dying).
+ *      - Own-uid live EACCES → truly unreadable → fail-closed.
+ *      - Missing marker     → foreign member → fail-closed.
+ */
+export declare function verifyGroupHomogeneity(enumer: ProcessEnumerator, pgid: number, markerUuid: string): HomogeneityResult;
+/**
+ * Walk the caller's ancestry (self → PPID → grandparent → ...) and check
+ * whether any ancestor carries the target marker. If yes → caller is
+ * running inside the copresence tree we're about to kill, and would take
+ * itself down.
+ */
+export declare function callerCarriesMarker(enumer: ProcessEnumerator, markerUuid: string): {
+    self: boolean;
+    ancestorPid?: number;
+};
+export type ReapResult = {
+    kind: "success";
+    killedPgids: number[];
+    residualPids: number[];
+    unreadableOwnUid?: number[];
+} | {
+    kind: "failed";
+    killedPgids: number[];
+    residualPids: number[];
+    skippedGroups: Array<{
+        pgid: number;
+        reason: string;
+    }>;
+    detail: string;
+    unreadableOwnUid?: number[];
+};
+export interface ReapOptions {
+    graceMs: number;
+    logger: (msg: string) => void;
+    /**
+     * Sleep primitive (grace period). Real code uses setTimeout; tests inject
+     * a fast/deterministic sleep so grace paths are actually covered. Prior
+     * impl was a busy-wait `while (Date.now() < end) {}` — audit 92d53c8f
+     * finding #3 flagged that as pinning one CPU core for graceMs and blocking
+     * the event loop; test coverage missed it because tests passed graceMs=0.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Invariant-11 scope anchors, normally `anchorsFromMarker(marker)`.
+     *
+     * Without them the only anchors are the marker carriers the scan itself
+     * found, so a marker-carrying process we cannot READ (non-dumpable) but
+     * whose parent IS a recorded session pid would be judged out of scope and
+     * silently dropped. Passing the marker's recorded session pids closes that
+     * hole; each one is re-validated (alive + same starttime) before it can
+     * widen scope, so a stale/recycled pid cannot.
+     */
+    anchors?: ScanAnchors;
+}
+/**
+ * Full reap flow with TOCTOU re-verification.
+ *
+ * Sequence:
+ *   1. Environ scan for marker → get all live pids carrying it.
+ *   2. Group by current PGID.
+ *   3. For each group: verify homogeneity. Skip on foreign/unreadable.
+ *   4. For each verified group: send SIGTERM to pgroup.
+ *   5. Wait grace.
+ *   6. Re-verify each group (marker still there, no new foreign) before SIGKILL.
+ *   7. Send SIGKILL to any group still alive.
+ *   8. Post-rescan: if any marker-carrying pid alive → preserve marker.
+ */
+export declare function reapMarkerGroups(enumer: ProcessEnumerator, killer: KillPrimitive, markerUuid: string, opts: ReapOptions): Promise<ReapResult>;
+export interface PrepareStartDeps {
+    /** Usually () => readMarker(nodesDir, nodeId). */
+    readMarker(): ReadMarkerResult;
+    /** Usually (uuid, anchors) => reapMarkerGroups(realEnumerator(), realKiller(), uuid, {...anchors}). */
+    reap(uuid: string, anchors: ScanAnchors): Promise<ReapResult>;
+    /** Usually () => removeMarker(nodesDir, nodeId). */
+    removeMarker(): void;
+    /** Usually (uuid, sessions) => writeMarker(nodesDir, nodeId, uuid, sessions). */
+    writeMarker(uuid: string, sessions: CopresenceMarker["sessions"]): void;
+    logger(msg: string): void;
+}
+export type PrepareStartResult = {
+    kind: "ok";
+    reclaimedUuid?: string;
+} | {
+    kind: "blocked";
+    cause: "STALE_TREE_ALIVE" | "UNUSABLE_MARKER";
+    detail: string;
+    remedy: string;
+};
+/**
+ * Everything that must happen BEFORE the first `tmux new-session` of a
+ * copresence start. Extracted out of cli.ts so both blockers below are
+ * actually reachable by tests — the audit's point that the two fatal
+ * defects of the previous rounds both lived in an untested cli.ts seam.
+ *
+ * Blocker 5 — marker-before-tmux ordering.
+ *   v2 wrote the marker only after the app-server had bound its port, i.e.
+ *   after a 25s wait and after several `process.exit(1)` paths. A start that
+ *   died in that window left a live, marker-carrying tmux session behind
+ *   with NO marker file on disk: the exact unreclaimable-ghost this feature
+ *   exists to prevent. The marker is now written here, before any session is
+ *   created, with an empty `sessions` object — reap identity has always been
+ *   the environ uuid, never the recorded pids, so an empty sessions object
+ *   loses nothing but observability hints (which the start path fills in
+ *   later, best-effort).
+ *
+ * Blocker 6 — never overwrite a preserved marker.
+ *   A failed stop deliberately PRESERVES the marker so the next stop can
+ *   retry idempotently. v2's start then overwrote it with a fresh uuid while
+ *   only killing tmux sessions BY NAME, so the still-running subprocesses of
+ *   the previous instance became permanently unreclaimable: their uuid was
+ *   gone from disk forever. Now the old identity is reaped FIRST; if that
+ *   reap does not fully succeed we refuse to start rather than destroy the
+ *   only handle on those processes.
+ */
+export declare function prepareIdentityForStart(newUuid: string, deps: PrepareStartDeps): Promise<PrepareStartResult>;

package/dist/src/copresence-startup-diagnosis.d.ts

@@ -0,0 +1,17 @@
+export interface CopresenceStartupFailure {
+    /** 等的那个 attach launcher 路径。 */
+    attachScript: string;
+    /** bridge 输出的落盘文件（可能还不存在——bridge 可能压根没起来）。 */
+    bridgeLog: string;
+    /** 节点自己的日志目录。 */
+    nodeLogDir: string;
+    /** 判定失败的那一刻，bridge 的 tmux 会话还在不在。 */
+    bridgeAlive: boolean;
+    /** 等了多少秒。 */
+    waitedSeconds: number;
+    /** 落盘日志的尾巴（读不到就给空串）。 */
+    logTail: string;
+    /** tmux pane 的尾巴；会话已死时必然是空。 */
+    paneTail: string;
+}
+export declare function describeCopresenceStartupFailure(f: CopresenceStartupFailure): string[];

package/dist/src/daemon-capability-display.d.ts

@@ -0,0 +1,110 @@
+/** hub `/api/host-supervisors` 里与本主题相关的那几格。全部可缺席。 */
+export type DaemonCapabilityRow = {
+    readonly alias?: string;
+    readonly online?: boolean;
+    /** hub 侧的最后一次心跳(ISO 串或 epoch ms)。缺席则年龄无法计算。 */
+    readonly last_seen_at?: string | number | null;
+    readonly can_create_nodes?: boolean;
+    readonly create_nodes_blocked_reason?: string;
+    /** #1545 —— 上面那一格是**这份 report 发出前多少毫秒**测的。 */
+    readonly create_capability_observed_ms_ago?: number;
+};
+export type CapabilityView = 
+/** hub 上根本没有这一格 —— 旧 daemon(agent-node ≤ 2.5.0-preview.54)不上报。 */
+{
+    readonly kind: "never-reported";
+    readonly line: string;
+}
+/** 报了 ready/blocked,且知道是多久以前测的。 */
+ | {
+    readonly kind: "ready" | "blocked";
+    readonly ageMs: number;
+    readonly line: string;
+    readonly fix?: CapabilityFix;
+}
+/** 报了 ready/blocked,但**不知道是什么时候测的**(旧 daemon 开机只算一次)。 */
+ | {
+    readonly kind: "ready-age-unknown" | "blocked-age-unknown";
+    readonly line: string;
+    readonly fix?: CapabilityFix;
+};
+/** 🔴 修法**按 code 给,不按上游的 detail 给**。
+ *
+ *  上游 `unsafePathHelp()` 生成的 `Fix:` 那半带完整机器路径,而它**按设计不上报**
+ *  (那条会一路走到 Dashboard,「哪台机器的哪个路径缺什么」本身就是一张地图)。
+ *  所以跨机器读到的只有 code,这里给的必然是**不含机器路径的通用修法**。
+ *
+ *  🔴 四类的修法完全不同,混成一句会让人修错方向 —— 2026-08-28 有人一天里撞到
+ *     其中两类,看到的是同一条错误,第一反应跑去建 /etc/anet-daemon/path.conf,
+ *     而那次实际只要 chmod。
+ *
+ *  想要**带真实路径的那一份**,只能在那台机器上看它自己的 daemon 日志 ——
+ *  下面每条都会把人指过去。 */
+export type CapabilityFix = {
+    /** 人读的一句话:这一类是什么、为什么会这样。 */
+    readonly explain: string;
+    /** 🔴 **可以整行粘进终端**的命令,或 null(这一类没有单条命令能修)。
+     *
+     *  分成两格而不是拼成一句,是因为拼起来之后**没有一条能通过 `bash -n`** ——
+     *  中文说明和括号注释会被 shell 当成语法。#1521 修过完全同一个形状:
+     *  当时 anet_bin_source 的 Fix 串 `bash -n` rc=2(`$( )` 里的 `\"` 是语法错),
+     *  用户粘进去只看到 `syntax error near unexpected token '('`。
+     *  **一条"看起来是命令"的说明,比没有命令更糟。** */
+    readonly command: string | null;
+};
+/** 把毫秒渲染成人读的相对时间。**不做四舍五入到"刚刚"** ——
+ *  这一格存在的意义就是分辨新鲜和陈旧,含糊化等于把它的功能删掉。 */
+export declare function formatAge(ms: number): string;
+export declare function describeCapability(row: DaemonCapabilityRow, nowMs: number): CapabilityView;
+/** 取 `/api/host-supervisors` 失败时的**原因**。以前这五种共用一个 `null`。 */
+export type CapabilityFetchFailure = {
+    readonly why: "no-hub";
+} | {
+    readonly why: "unauthorized";
+    readonly status: number;
+} | {
+    readonly why: "http";
+    readonly status: number;
+} | {
+    readonly why: "bad-body";
+} | {
+    readonly why: "unreachable";
+    readonly detail?: string;
+};
+/** 每一种都必须说出**两件事**:到底是什么挡住了,以及下一步该敲什么。
+ *  尾巴统一带上「本地清单不需要网络」—— 那是这条命令没有整个失败的原因,
+ *  用户看到「查不到」时最先怕的就是"上面那些是不是也不可信了"。 */
+export declare function describeFetchFailure(f: CapabilityFetchFailure): string;
+/**
+ * `create_node` 被拒时 hub 返回的形状(`server/src/tools.ts` 的
+ * `daemon_cannot_create_nodes` 分支)。
+ *
+ * 🔴 它和 `DaemonCapabilityRow` **不是同一个形状**,所以单独一个入口 ——
+ *    在调用方做一次字段映射,等于开出**第二个理解这些字段含义的地方**。
+ */
+export type CreateRejectionPayload = {
+    readonly error?: string;
+    readonly blocked_reason?: string;
+    /** 🔴 已经是**到现在为止**的绝对年龄(hub 在拒绝时把心跳那一段补上了)。
+     *  null = 补不出来 —— 见 `capability_age`。 */
+    readonly capability_observed_ms_ago?: number | null;
+    readonly capability_age?: string;
+};
+/**
+ * 把拒绝载荷渲染成人能读的一段。不是这类拒绝就返回 null,调用方走它原来的通用文案。
+ *
+ * 🔴 **这里没有第二份年龄公式。** `describeCapability` 里那段
+ * `(now − last_seen_at) + observed` 是给「列 daemon」那条路用的;
+ * 拒绝这条路上,**hub 已经算好了绝对年龄**(它手里有心跳时间)。
+ * 所以这里只做格式化,复用同一个 `formatAge`。
+ * 两份年龄算法一旦并排存在,出现分歧时不会有任何东西红。
+ *
+ * 🔴 **没有新增第六种 kind**,这是刻意的:
+ *   `kind` 是**呈现分桶**(禁不禁用、什么色调),不是完整语义。
+ *   「daemon 没报年龄」和「hub 没有它的心跳时间」在 UI 上要的处理**完全一样**
+ *   (都是 blocked、都给不出年龄),差别在**说哪句话** —— 那放在 `line` 里。
+ *   反过来,给共享联合加第六个值,会让所有既有消费者的映射多一个
+ *   它们没写过的分支,而**落进 default 的那一支通常是"看起来最正常"的那个**。
+ *   区分没有丢:两种 unknown 的 `line` 逐字不同,并有测试钉住。
+ */
+export declare function describeCreateRejection(payload: CreateRejectionPayload): CapabilityView | null;

package/dist/src/daemon-capability-display.js

@@ -0,0 +1,21 @@
+var J=Object.freeze({anet_bin_identity:{explain:"该路径不是 anet 的包内 bin(若设过 ANET_BIN_ABS,先 unset 再重装)",command:"npm i -g @sleep2agi/agent-network"},anet_bin_source:{explain:"pin 没有可信来源。在该机器上写信任根 —— 两段都要 sudo,少一个 && 就会断链",command:`sudo install -d -m 755 /etc/anet-daemon && printf 'ANET_BIN_ABS=%s
+' "$(command -v anet)" | sudo tee /etc/anet-daemon/path.conf`},anet_bin_permission:{explain:"该二进制 group/other 可写。一行就能修",command:'chmod go-w "$(command -v anet)"'},anet_bin_shape:{explain:"pin 的路径形态不合法(相对路径,或路径里含软链)。取它的 realpath 重新写进 path.conf",command:'readlink -f "$(command -v anet)"'},anet_bin_unknown:{explain:"daemon 没能给出类别(例如安装后二进制被换过、校验和不符)。只能看该机器的 daemon 日志取原文",command:null},anet_bin_pin_unresolved:{explain:"旧版 daemon(agent-node 2.5.0-preview.40 及更早)只报这一个笼统原因。升级该机器的 agent-node 并重启 daemon 后才能拿到具体类别",command:null}});function G(c){if(!Number.isFinite(c)||c<0)return"?";if(c<1000)return`${Math.round(c)}ms 前`;let j=Math.floor(c/1000);if(j<60)return`${j}s 前`;let k=Math.floor(j/60);if(k<60)return`${k}m 前`;let u=Math.floor(k/60);if(u<24)return`${u}h 前`;return`${Math.floor(u/24)}d 前`}function P(c){if(typeof c==="number"&&Number.isFinite(c))return c;if(typeof c==="string"){let j=Date.parse(c);if(Number.isFinite(j))return j}return}function Q(c,j){if(typeof c.can_create_nodes!=="boolean")return{kind:"never-reported",line:`创建能力:未知 —— 这台 daemon 没报过这一格。
+`+"    (agent-node 版本早于 preview.55;升级后必须重启 daemon 才生效)"};let k=P(c.last_seen_at),u=c.create_capability_observed_ms_ago,q=k!==void 0&&typeof u==="number"&&Number.isFinite(u)?Math.max(0,j-k)+u:void 0;if(c.can_create_nodes){if(q===void 0)return{kind:"ready-age-unknown",line:`创建能力:可用
+`+"    ⚠ 不知道是什么时候测的 —— 该版本开机只算一次。重启它,或升级。"};return{kind:"ready",ageMs:q,line:`创建能力:可用(${G(q)}测)`}}let C=c.create_nodes_blocked_reason||"anet_bin_unknown",z=J[C]??{explain:`未知原因代码 ${C} —— 本 CLI 可能比那台机器的 anet 旧,升级本机 anet 或看它的 daemon 日志`,command:null},K=`完整原文只在那台机器的 daemon 日志里。
+    (它带真实机器路径,按设计不上报)`,H=[`    原因:${z.explain}`,z.command?`    修法(可整行粘贴):${z.command}`:"    修法:没有单条命令能修,见上。",`    ${K}`].join(`
+`);if(q===void 0)return{kind:"blocked-age-unknown",line:`创建能力:**不可用**(${C})
+    ⚠ 不知道是什么时候测的 —— 该 daemon 版本开机只算一次,之后不再重测。
+${H}`,fix:z};return{kind:"blocked",ageMs:q,line:`创建能力:**不可用**(${C},${G(q)}测)
+${H}`,fix:z}}function T(c){switch(c.why){case"no-hub":return`创建能力:查不到 —— 本机还没配 hub 地址。
+`+"    跑 anet init,或这次带上 --hub <url>"+`
+    (本地清单不需要网络,上面那些信息仍然有效)`;case"unauthorized":return`创建能力:查不到 —— hub 拒绝了本机的身份(HTTP ${c.status})。
+`+"    hub 是通的,要修的是**凭据**不是网络:跑 anet login"+`
+    (本地清单不需要网络,上面那些信息仍然有效)`;case"http":return`创建能力:查不到 —— hub 返回 HTTP ${c.status}。
+`+"    hub 在,但这个接口没给出结果;看 hub 日志"+`
+    (本地清单不需要网络,上面那些信息仍然有效)`;case"bad-body":return`创建能力:查不到 —— hub 的应答读不懂。
+`+"    多半是 hub 比本机 CLI 旧,升级 hub 或降本机 anet"+`
+    (本地清单不需要网络,上面那些信息仍然有效)`;case"unreachable":return"创建能力:查不到 —— 连不上 hub"+(c.detail?`(${c.detail})`:"")+"。"+`
+    (本地清单不需要网络,上面那些信息仍然有效)`}}function U(c){if(c?.error!=="daemon_cannot_create_nodes")return null;let j=c.blocked_reason||"anet_bin_unknown",k=J[j]??{explain:`未知原因代码 ${j} —— 本端可能比那台机器的 anet 旧,升级本端或看它的 daemon 日志`,command:null},u="完整原文(含真实路径)只在那台机器的 daemon 日志里 —— 它带机器路径,按设计不上报。",D=[`原因:${k.explain}`,k.command?`修法(可整行粘贴):${k.command}`:"修法:没有单条命令能修,见上。",u].join(`
+`),q=c.capability_observed_ms_ago;if(c.capability_age==="known"&&typeof q==="number"&&Number.isFinite(q)&&q>=0)return{kind:"blocked",ageMs:q,line:`这台 daemon 报告它现在**建不了节点**(${j},${G(q)}测)
+${D}`,fix:k};let z=c.capability_age==="unknown_no_heartbeat_time"?"**它报了这个判断,但 hub 这边没有它的心跳时间**,所以算不出是多久以前的 —— 先看这台 daemon 是否还在线,别急着升级它":"**不知道是多久以前测的** —— 该 daemon 版本在开机时算一次就不再重测,这个结论可能早就过期了。重启或升级它";return{kind:"blocked-age-unknown",line:`这台 daemon 报告它现在**建不了节点**(${j});${z}
+${D}`,fix:k}}export{G as formatAge,T as describeFetchFailure,U as describeCreateRejection,Q as describeCapability};

package/dist/src/daemon-runtime-path-preflight.d.ts

@@ -0,0 +1,22 @@
+/** 一个 runtime 依赖的外部二进制,以及它**有据可查**的安装位置。 */
+export type RuntimeBinaryHint = {
+    /** 哪些 runtime 名需要这个二进制 */
+    readonly runtimes: readonly string[];
+    /** 在 PATH 上查的裸名 */
+    readonly binary: string;
+    /** 官方安装位置(相对 $HOME) */
+    readonly homeRelativeDir: string;
+    /** 🔴 这一条的出处 —— 没有出处就不许进这张表 */
+    readonly evidence: string;
+};
+export declare const RUNTIME_BINARY_HINTS: readonly RuntimeBinaryHint[];
+export type PathPreflightInput = {
+    /** 这台 daemon 声称支持的 runtime */
+    readonly runtimes: readonly string[];
+    /** 二进制在 daemon 的 PATH 上能不能找到 */
+    readonly resolvesOnPath: (binary: string) => boolean;
+    /** 二进制在那个已知位置存不存在 */
+    readonly existsInHomeDir: (homeRelativeDir: string, binary: string) => boolean;
+};
+/** 返回要打给用户的警告。**没问题时返回空数组** —— 空是常态,不是失败。 */
+export declare function daemonPathWarnings(input: PathPreflightInput): string[];

package/dist/src/daemon-runtime-staleness.d.ts

@@ -0,0 +1,13 @@
+/**
+ * daemon 的 `runtimes_supported` 是**写配置那一刻**的支持集快照，之后不会自愈。
+ *
+ * 🔴 这不是假想的：#1298 (2026-08-28) 把新建 daemon 的默认清单从 3 个放开到
+ *    `SUPPORTED_RUNTIME_NAMES` 全体，但**它只改了写入路径**。在那之前 init 过的
+ *    daemon，配置里仍然只有那 3 个，而且没有任何东西会说出这件事 ——
+ *    用户在客户端「选服务器」里看到某台机器少几个 runtime，
+ *    既不知道为什么，也不知道该做什么。
+ *
+ * 判据从**分发处**取（`SUPPORTED_RUNTIME_NAMES`），不在这里手写一份清单：
+ * 抄一份就意味着它会再漂一次（同 #1728 的教训）。
+ */
+export declare function describeStaleRuntimeSupport(declared: readonly string[] | undefined | null, supported: readonly string[], nameHint?: string): string | null;

package/dist/src/dashboard-managed-process.d.ts

@@ -0,0 +1,35 @@
+export type DashboardLaunchSource = "npx" | "global";
+export interface DashboardLaunchRecord {
+    schema: 1;
+    port: number;
+    listener_pid: number;
+    listener_birth: string;
+    source: DashboardLaunchSource;
+    source_key: string;
+    recorded_at: string;
+}
+export type DashboardListenerDecision = {
+    action: "start";
+} | {
+    action: "already_running";
+    pid: number;
+} | {
+    action: "terminate_owned_stale";
+    pid: number;
+    reason: "unhealthy" | "version_changed";
+} | {
+    action: "refuse";
+    reason: string;
+};
+export declare function isDashboardProcessCommand(command: string): boolean;
+export declare function decideDashboardListener(input: {
+    port: number;
+    listenerPids: number[];
+    record: DashboardLaunchRecord | null;
+    listenerBirth: string | null;
+    listenerCommand: string | null;
+    desiredSource: DashboardLaunchSource;
+    desiredSourceKey: string;
+    healthy: boolean;
+}): DashboardListenerDecision;
+export declare function parseDashboardLaunchRecord(value: unknown): DashboardLaunchRecord | null;

package/dist/src/display-width.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 终端里的**显示列宽** —— CJK 字符占 2 列,而 `String.length` / `padEnd` 只数码元。
+ *
+ * 🔴 这份知识仓里本来就有,但它只活在**一个测试文件**里
+ * (`daemon-capability-display.test.ts` 的 `displayWidth`,2026-08-30 由 macOS 真机
+ * 上「合成首行约 99 列、80 列终端折行且折点落在句子中间」催生)。
+ * 生产代码没有它,于是所有用 `padEnd` 对齐的表在中文别名下都是歪的。
+ *
+ * 实测(2026-08-31,`anet node ls` 对着一支全中文别名的军团):
+ *
+ *   NAME                 RUNTIME        STATUS
+ *   ──────────────────── ────────────── ────────
+ *   通信工程马                claude-code-cli idle      ← RUNTIME 列起点
+ *   通信IM马                claude-code-cli idle       ← 不一样
+ *   通信SDK牛               codex-sdk      idle        ← 又不一样
+ *
+ * `通信工程马`.length 是 5,`padEnd(20)` 补 15 个空格 —— 但它渲染出来是 10 列,
+ * 于是这一行实际占 25 列而不是 20。**别名里 CJK 越多,歪得越远。**
+ */
+export declare function displayWidth(s: unknown): number;
+/**
+ * 按**显示列**右补空格。已经不短于目标宽度时原样返回(与 `padEnd` 一致,不截断)。
+ *
+ * 🔴 不截断是有意的:截断会引出「截到一半的宽字符」这个新问题,
+ *    而调用方要的只是对齐。**一个修对齐的改动不该顺手引入截断语义。**
+ */
+export declare function padDisplayEnd(s: unknown, width: number): string;

package/dist/src/doctor-node-count.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `anet doctor` 原先对「本机配置了几个节点」的判定是:
+ *
+ *   check("Nodes configured", ids.length > 0, `${ids.length} node(s)`);
+ *
+ * 于是 **0 个节点 → ❌**。而一个刚装好、还没建节点的人跑 `anet doctor`,
+ * 看到的是:
+ *
+ *   ❌ Nodes configured — 0 node(s)
+ *   Result: 9 ok, 3 warnings, 2 errors
+ *
+ * 🔴 「还没有节点」是**全新安装的预期状态**,不是故障。把它报成 error,
+ *    等于在新用户的第一次诊断里制造一个假警报 —— 而这条命令存在的意义
+ *    正是告诉他「你这台机器现在好不好」。
+ *
+ * 🔴 但也不能反过来直接判成「一切正常」:同一个 0 对一个**本来有节点**的人
+ *    意味着配置目录不见了。doctor 手上只有一个数字,**分不出这两种现实**。
+ *    所以这里既不报错也不报好 —— 把两种都说出来,让读的人自己对号,
+ *    并给出各自的下一步。
+ */
+export type NodeCountLine = {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    info: string;
+};
+export declare function nodeCountLine(count: number): NodeCountLine;

package/dist/src/environ-alias.d.ts

@@ -0,0 +1,14 @@
+/** Parse the environ blob (NUL-separated key=val) and return the
+ *  COMMHUB_ALIAS value if present, else null. Exported for testing. */
+export declare function parseEnvironAlias(environBlob: string): string | null;
+/** Read /proc/<pid>/environ and return the COMMHUB_ALIAS value.
+ *  Any file-read error (not-a-Linux, permission denied, race with
+ *  process exit) returns null — caller must not fail-closed on that
+ *  (the process is stale/gone/inaccessible, not our problem). */
+export declare function readEnvironAlias(pid: number): string | null;
+/** Scan /proc for pids whose COMMHUB_ALIAS env matches any of the
+ *  target aliases. Linux-only (procfs); returns null on non-Linux or
+ *  when /proc is unreadable — caller MUST fail-closed on null per
+ *  the same #180 R2 fail-closed contract as findNodeProcessesByAlias.
+ *  Self-pid + init (PID 1) are excluded. */
+export declare function findEnvironAliasMatches(aliases: Iterable<string>, selfPid: number): number[] | null;