@sleep2agi/agent-network 2.3.0-preview.14 → 2.3.0-preview.141

package/dist/src/outbound-attachments.d.ts

@@ -0,0 +1,60 @@
+/** One attachment as the Hub stores it. `file_id` comes from commhub_upload_file. */
+export interface OutboundAttachment {
+    type: "file";
+    file_id: string;
+    name?: string;
+    mime?: string;
+    size?: number;
+}
+export type NormalizeResult = {
+    ok: true;
+    attachments: OutboundAttachment[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize caller-supplied attachments into what the Hub expects.
+ *
+ * Absent input is not an error and yields no `attachments` key at all — a call
+ * without attachments must produce a byte-identical request to before this
+ * existed, or every existing reply changes behaviour the day this ships.
+ */
+/** 2026-09-15 —— LLM 常把数组参数当成 JSON 字符串传(外部团队节点 真机:attachments 是 "[{...}]" 字符串,回复 ok:true 但 hub 里没有附件)。
+ *  字符串先 parse;parse 不出来是错误,不是「没有附件」。 */
+export declare function coerceAttachmentsArg(input: unknown): unknown;
+export declare function normalizeOutboundAttachments(input: unknown): NormalizeResult;
+/**
+ * Spread into a Hub request body. Empty → `{}`, so a call with no attachments
+ * is unchanged from before this module existed.
+ */
+export declare function attachmentsField(attachments: readonly OutboundAttachment[]): Record<string, unknown>;
+/** `send_task` carries them under `meta`, not at the top level. */
+export declare function attachmentsMeta(attachments: readonly OutboundAttachment[], existingMeta?: unknown): Record<string, unknown>;
+/** Shared wording for the two tool schemas, so they cannot drift apart. */
+export declare const ATTACHMENTS_SCHEMA: {
+    type: "array";
+    description: string;
+    items: {
+        type: "object";
+        properties: {
+            file_id: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            mime: {
+                type: string;
+                description: string;
+            };
+            size: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/src/outbound-tool-names.d.ts

@@ -0,0 +1 @@
+export declare const OUTBOUND_TOOL_NAMES: Set<string>;

package/dist/src/owned-roots.d.ts

@@ -0,0 +1,58 @@
+export type OwnedRootRole = "agent";
+export interface OwnedRoot {
+    pid: number;
+    birth: string;
+    role: OwnedRootRole;
+}
+/** 🔴 #1438 — 发现阶段(`ps`)与后续 `/proc/<pid>/stat` 读之间,pid 可能被回收。
+ *  为让 resolveOwnedRoots 能识别「pid 相同、进程不同」,发现阶段必须在
+ *  **同一次 `ps` 快照**里同时取 pid 与一个稳定的启动时刻签名(lstart),
+ *  并把这个签名一路带进来做比对。同一次 ps 内的 pid 与 lstart 无 TOCTOU。 */
+export interface OwnedRootCandidate {
+    pid: number;
+    /** 发现时刻的 `ps -o lstart=` 字符串(24 字符定宽),用于识别 pid 回收。 */
+    discoveredBirth: string;
+}
+export interface OwnedRootProbes {
+    /** 进程这一代的出生时刻(以「存储格式」返回,通常是 /proc/stat starttime jiffies);
+     *  读不到返回 null(可能已退出,也可能无权限)。用于写进 lifecycle 记录。 */
+    birth(pid: number): string | null;
+    /** 🔴 只有**确证**进程不存在时返回 true。无权限等一律视为存在。 */
+    vanished(pid: number): boolean;
+    /** 🔴 #1438 — 返回**当前**pid 的 lstart 签名,和发现阶段同格式。
+     *  用来识别 pid 回收:发现时是 A、现在读回来是 B ⇒ pid 已被复用。
+     *  读不到返回 null(进程已退出,或读 ps 失败)。 */
+    currentBirthSignature(pid: number): string | null;
+}
+/** 把 `ps` 发现的 (pid, birth) 候选冻结成 owned roots。
+ *
+ * · currentBirthSignature 与 discoveredBirth **相等** ⇒ 同一代,收下
+ * · currentBirthSignature 与 discoveredBirth **不等** ⇒ 🔴 #1438 pid 已被复用,
+ *     现在这个 pid 属于另一个进程 B。**跳过**(而不是收下 B 当我们的节点):
+ *     stop 的目的是让 A 没了;B 是无关进程,不能因为它恰好占了 A 的 pid 就被杀。
+ * · currentBirthSignature 为 null、**确证已消失**   ⇒ 跳过(stop 想要的结果)
+ * · currentBirthSignature 为 null、进程仍在        ⇒ throw(权限等真问题)
+ */
+export declare function resolveOwnedRoots(candidates: OwnedRootCandidate[], probes: OwnedRootProbes): OwnedRoot[];
+/** 🔴 正向判定「进程确实没了」,而不是「读失败就假设没了」。
+ *
+ * `kill(pid, 0)` 不送信号,只做存在性与权限探测:
+ *   · ESRCH  ⇒ 确证不存在
+ *   · EPERM  ⇒ 存在,只是不属于本用户
+ *   · 其他   ⇒ 保守当作存在(判据只在**确证**时放行)
+ */
+export declare function processVanished(pid: number, kill?: (p: number, s: number) => void): boolean;
+/** 🔴 #1458 — kill 前的 pid 回收保护:发现阶段捕获的 discoveredBirth 与
+ *  **当前**probeCurrentSignature(pid) 相等 ⇒ 同一代,可以信号。
+ *
+ *  · currentSig === discoveredBirth ⇒ true(同代,可 kill)
+ *  · currentSig !== discoveredBirth ⇒ false(pid 被回收,现在这个 pid 是另一
+ *    个进程 B。**不要 kill** —— B 与我们要 stop 的 agent 无关)
+ *  · currentSig === null            ⇒ false(pid 已消失或读不到;caller 判
+ *    是消失就该 skip,权限问题应额外处理但不该 kill 未知对象)
+ *
+ *  与 resolveOwnedRoots 内嵌的同款比较**在语义上一致**,但在**时间点上不同**:
+ *    resolveOwnedRoots 用于「冻结」时刻(装进 lifecycle owner)
+ *    isSameIncarnation 用于「发信号」前那一瞬(rename 的 kill 循环)
+ *  两个时刻中间可能又有窗口,所以这个检查要**离 process.kill 越近越好**。 */
+export declare function isSameIncarnation(pid: number, discoveredBirth: string, probeCurrentSignature: (pid: number) => string | null): boolean;

package/dist/src/owner-env-file.d.ts

@@ -0,0 +1,2 @@
+/** Load a reviewed owner-only env file without following a planted link. */
+export declare function loadOwnerOnlyEnvFile(path: string | undefined, env?: NodeJS.ProcessEnv): void;

package/dist/src/package-mode-preflight.d.ts

@@ -0,0 +1,41 @@
+export interface UmaskVerdict {
+    /** Will a freshly npm-extracted payload fail the (mode & 0o022) === 0 check? */
+    willProduceUnsafeModes: boolean;
+    /** Octal umask string as an operator would type it. */
+    umaskOctal: string;
+    /** Which write bits this umask fails to mask off. */
+    leaks: Array<"group" | "other">;
+}
+/**
+ * Read a umask value the way the package check will experience it.
+ *
+ * A umask bit SET means "withhold this permission". So group-write is withheld
+ * only when 0o020 is set in the umask; umask 0002 withholds other-write and
+ * nothing else, which is exactly the failing case.
+ */
+export declare function judgeUmask(umask: number): UmaskVerdict;
+/**
+ * One line for `anet doctor`, or null when there is nothing to say.
+ *
+ * 🔴 Windows gets a different sentence, not the same one. There, umask is always
+ *    0000 and this fires on every machine, while both remedies it names —
+ *    `umask 0022` and `chmod -R` — do not exist. The conclusion is still true
+ *    (opencode-cli will refuse), but for another reason entirely: its check is
+ *    `if (runtimeUid === undefined) return false`, and Windows has no getuid.
+ *    An always-on warning whose fix cannot be typed teaches people to ignore
+ *    the warnings that can be.
+ */
+export declare function describeUmaskRisk(verdict: UmaskVerdict, platform?: NodeJS.Platform): string | null;
+export interface ExtractedPayload {
+    path: string;
+    uid: number;
+    mode: number;
+}
+/**
+ * Which already-extracted payloads would be rejected right now.
+ *
+ * Reports facts about copies that exist on disk; it never fetches. An empty
+ * result means "nothing extracted yet", which is not the same as "safe" — the
+ * umask verdict is what speaks to the next fetch.
+ */
+export declare function rejectedPayloads(payloads: ExtractedPayload[], processUid: number): ExtractedPayload[];

package/dist/src/posix-codex-copresence.d.ts

@@ -0,0 +1,35 @@
+export type ProcRow = {
+    pid: number;
+    ppid: number;
+    start: string;
+};
+export declare function ownedConnectionFromSnapshot(rootPid: number, beforeStart: string | null, afterStart: string | null, rows: ProcRow[], socketOwners: ReadonlyMap<number, ReadonlySet<string>>, establishedInodes: ReadonlySet<string>, unread?: boolean): boolean;
+/** Fail-closed attribution of an exact loopback connection to a managed POSIX TUI tree. */
+export declare function probePosixOwnedLoopbackConnection(rootPid: number, port: number, platform?: NodeJS.Platform): boolean;
+/**
+ * #2255 (2026-10-02) —— 一次探不到 ≠ 没连上。`anet node start` 等到 TUI 画出 banner(「OpenAI Codex」)就只探一次:
+ * 实测真 codex 0.155.1 先画 banner(~170 ms)、后建 ws(~221 ms),假 TUI 同样先打印后连接。空闲机器上 400 ms 的
+ * 「等画出来」恰好把这几十毫秒盖住;CI runner / 忙的机器上盖不住,启动就以「managed TUI tree has no attributable
+ * connection」失败 —— 会话其实好好的。Windows 那条路径一直是轮询(TUI_HEALTH_MS 内反复探),这里对齐。
+ *
+ * 每 intervalMs 探一次,直到:探到(connected)/ TUI 退了(tui-exited,不再白等)/ 到点(deadline)。
+ * 判据本身不变:仍是 probePosixOwnedLoopbackConnection 的 fail-closed 归属,只是不再只给一次机会。
+ */
+/** 与 Windows 路径的 TUI_HEALTH_MS 同一个预算(cli.ts):TUI 活着却 25 s 都没连上,才判失败。 */
+export declare const POSIX_TUI_ATTRIBUTION_MS = 25000;
+export type PosixAttributionResult = {
+    outcome: "connected" | "tui-exited" | "deadline";
+    probes: number;
+    waitedMs: number;
+};
+export declare function waitForPosixOwnedLoopbackConnection(opts: {
+    rootPid: number;
+    port: number;
+    deadlineMs: number;
+    intervalMs?: number;
+    /** TUI 还在不在(pid 还活着、而且还是同一个进程)。不在就别等了。 */
+    alive: () => boolean;
+    probe?: (rootPid: number, port: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<PosixAttributionResult>;

package/dist/src/posix-modes.d.ts

@@ -0,0 +1,36 @@
+export declare function posixFileModes(platform?: NodeJS.Platform): boolean;
+/** chmod where the platform has modes; a no-op where it does not. */
+export declare function chmodIfPosix(path: string, mode: number): void;
+/** fchmod where the platform has modes; a no-op where it does not. */
+export declare function fchmodIfPosix(fd: number, mode: number): void;
+/**
+ * Whether a stat's mode may be judged at all.
+ *
+ * Windows synthesises mode bits, so `(mode & 0o022) !== 0` is true for ordinary
+ * files there and every POSIX-shaped safety check reads as "unsafe". A check
+ * that can only ever return one answer is not a check.
+ */
+export declare function modeIsJudgeable(platform?: NodeJS.Platform): boolean;
+/**
+ * fsync a DIRECTORY handle, where the platform supports it.
+ *
+ * The durability barrier after an atomic rename: on POSIX, fsyncing the parent
+ * makes the rename itself survive a crash, not just the file's bytes. Windows
+ * has no equivalent — FlushFileBuffers works on files, and on a directory
+ * handle it fails:
+ *
+ *     [anet] FATAL: Error: EPERM: operation not permitted, fsync
+ *         at fsyncSync (node:fs:1285:11)
+ *
+ * which is `anet start <node>` dying on its first private-state write. Reported
+ * from the Windows box while it was running the previous fix, i.e. this is the
+ * next call in the same family, not a regression of that one.
+ *
+ * 🔴 Note what is NOT skipped: the fsync of the temp FILE before the rename.
+ *    That one works on Windows and carries the bytes. What is skipped is only
+ *    the parent-directory barrier, which the platform does not offer at all —
+ *    NTFS journals the rename's metadata itself. Skipping an operation the OS
+ *    cannot perform is not a weakened guarantee; crashing instead of writing
+ *    the file is a much larger one.
+ */
+export declare function fsyncDirectoryIfSupported(fd: number): void;

package/dist/src/primary-network.d.ts

@@ -0,0 +1,23 @@
+export interface PrimaryNetworkResponse {
+    ok?: boolean;
+    current_network?: unknown;
+    networks?: unknown;
+}
+export type PrimaryNetworkFetch = (input: string, init: {
+    headers: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<PrimaryNetworkResponse>;
+}>;
+export declare class PrimaryNetworkResolutionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Resolve the authenticated user's active network from the server's explicit
+ * `/api/auth/me.current_network` field.
+ *
+ * Do not fall back to a network name or list position: both are presentation
+ * details, and guessing either can silently run a command in the wrong network.
+ */
+export declare function resolvePrimaryNetwork(hub: string, headers: Record<string, string>, fetchImpl?: PrimaryNetworkFetch): Promise<string>;

package/dist/src/private-state.d.ts

@@ -0,0 +1,10 @@
+export declare function ensurePrivateDirectory(path: string): void;
+/**
+ * Write secret-bearing state without ever publishing an umask-derived file.
+ * The 0600 temporary file is complete and fsynced before the atomic rename,
+ * so replacing a legacy 0644/0664 target also repairs it with no chmod gap.
+ */
+export declare function atomicWritePrivateFile(path: string, body: string): void;
+export declare function atomicWritePrivateJson(path: string, value: unknown): void;
+/** Repair a legacy umask-derived private file before reading its secret. */
+export declare function repairPrivateFilePermissions(path: string): void;

package/dist/src/process-telemetry.d.ts

@@ -0,0 +1,12 @@
+export interface ProcessTelemetry {
+    rss_bytes: number;
+    rss_mb: number;
+    cpu_pct: number | null;
+    uptime_seconds: number;
+    in_flight_count: number;
+}
+export declare function incrementInFlight(): void;
+export declare function decrementInFlight(): void;
+export declare function getInFlightCount(): number;
+export declare function getProcessTelemetry(): ProcessTelemetry;
+export declare function _resetProcessTelemetry(): void;

package/dist/src/profile-serialize.d.ts

@@ -0,0 +1 @@
+export declare function serializeProfileForConfigJson(normalized: Record<string, any>, profile: Record<string, any>): Record<string, any>;

package/dist/src/project-key.d.ts

@@ -0,0 +1 @@
+export declare function encodeCwd(cwd: string): string;

package/dist/src/reply-local-links.d.ts

@@ -0,0 +1,47 @@
+/**
+ * claude-code-cli 节点(node-server 通道)回复里的「本机文件链接」→ 自动上传成附件。
+ * 与 agent-node 的 runtime/reply-file-links.ts 同一形状(两个包不能互相 import,各放一份纯逻辑)。
+ * 2026-09-15 真机:外部团队节点 两条带 pptx 的回复到 hub 时附件为空,人只看到「点卡片下载」四个字。
+ */
+export declare const REPLY_LOCAL_LINK_MAX = 6;
+export interface LocalLink {
+    readonly raw: string;
+    readonly label: string;
+    readonly path: string;
+}
+/** 只认 markdown 链接且目标像本机绝对路径(`/…` 或 `file:///…`);http(s)、/api/files/… 不算。 */
+export declare function findLocalLinks(text: string): LocalLink[];
+export interface UploadedRef {
+    file_id: string;
+    name: string;
+    mime?: string;
+    size?: number;
+}
+/** 上传成功的链接目标改成 /api/files/<id>(客户端按附件卡片渲染),失败的在标签后注明原因;返回 attachments 数组。 */
+export declare function rewriteLocalLinks(text: string, results: ReadonlyArray<{
+    link: LocalLink;
+    uploaded?: UploadedRef;
+    reason?: string;
+}>): {
+    text: string;
+    attachments: Array<{
+        type: "file";
+        file_id: string;
+        name?: string;
+        mime?: string;
+        size?: number;
+    }>;
+};
+/** 端到端(上传函数注入,失败抛错即可):没有本机链接时原样返回、零副作用。 */
+export declare function attachLocalLinks(text: string, upload: (path: string) => Promise<UploadedRef>): Promise<{
+    text: string;
+    attachments: Array<{
+        type: "file";
+        file_id: string;
+        name?: string;
+        mime?: string;
+        size?: number;
+    }>;
+    uploaded: number;
+    failed: number;
+}>;

package/dist/src/reply-originator.d.ts

@@ -0,0 +1,20 @@
+export type ReplyAliasDecision = 
+/** 把 alias 显式发出去 */
+{
+    readonly kind: "known";
+    readonly alias: string;
+}
+/** 省略 alias，交给 hub 从 in_reply_to 推导 */
+ | {
+    readonly kind: "derive";
+}
+/** 没有 task_id 可推导：保持历史行为，发给 hub */
+ | {
+    readonly kind: "hub";
+    readonly alias: "hub";
+};
+export declare function decideReplyAlias(taskId: string | null | undefined, lookup: (taskId: string) => string | undefined): ReplyAliasDecision;
+/** 把决策摊成 send_reply 的参数片段。`derive` 时**不含** alias 键。 */
+export declare function replyAliasArgs(d: ReplyAliasDecision): {
+    alias?: string;
+};

package/dist/src/resume-runtime-infer.d.ts

@@ -0,0 +1,18 @@
+export interface ResumeRuntimeInput {
+    /** raw --resume value; "true" means the flag was present with no value */
+    resume?: string;
+    /** whether --resume-latest was passed */
+    resumeLatest?: boolean;
+    /** an already-resolved session id, if any (skips inference) */
+    session?: string;
+    /** normalized --runtime, or empty/undefined when the user passed none */
+    explicitRuntime?: string;
+}
+export interface ResumeRuntimeResult {
+    /** runtime to force onto opts when it was left to default */
+    inferredRuntime?: string;
+    /** set when an explicit non-cli runtime conflicts with --resume */
+    conflictError?: string;
+}
+export declare const CLAUDE_CODE_CLI = "claude-code-cli";
+export declare function resolveRuntimeForResume(input: ResumeRuntimeInput): ResumeRuntimeResult;

package/dist/src/rules-file.d.ts

@@ -0,0 +1,53 @@
+export declare const RULES_FILE_MAX_BYTES: number;
+export type RulesFileName = "CLAUDE.md" | "AGENTS.md";
+/** claude 节点读 CLAUDE.md，其余运行时（codex / grok / opencode / codex-app-server）读 AGENTS.md。 */
+export declare function rulesFileNameForRuntime(runtime: string | null | undefined): RulesFileName;
+/**
+ * 唯一的路径来源。输入里没有任何调用方可控的路径成分；结果再用 dirname
+ * 反查一遍，防止将来有人给 workDir 传进带 `..` 的东西。
+ */
+export declare function resolveRulesFilePath(workDir: string, runtime: string | null | undefined): string;
+export interface RulesFileReadResult {
+    file_name: RulesFileName;
+    exists: boolean;
+    content: string;
+}
+export declare function readRulesFile(workDir: string, runtime: string | null | undefined): Promise<RulesFileReadResult>;
+export interface RulesFileWriteResult {
+    file_name: RulesFileName;
+    bytes: number;
+}
+/** 临时文件 + rename，写一半掉电不会留下半个规则文件。 */
+export declare function writeRulesFile(workDir: string, runtime: string | null | undefined, content: unknown): Promise<RulesFileWriteResult>;
+export interface RulesFileRequest {
+    request_id: string;
+    /** read/write = 规则文件;skills_list/skill_read = 只读技能(node-skills.ts),content 是技能名;
+     *  files_list/file_read = 只读项目文件夹(node-files.ts),content 是相对工作目录的路径;
+     *  logs_tail = 只读本节点运行日志(node-logs.ts),content 是过滤参数 JSON(没有路径)。 */
+    op: "read" | "write" | "skills_list" | "skill_read" | "files_list" | "file_read" | "logs_tail";
+    content?: string;
+}
+export interface ProcessRulesFileDeps {
+    callCommHub: (method: string, params: Record<string, unknown>) => Promise<any>;
+    runtime: string | null | undefined;
+    workDir: string;
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+    /** 技能根目录用;缺省取 os.homedir() / process.env.CODEX_HOME。 */
+    home?: string;
+    codexHome?: string;
+    /** logs_tail 用:读本进程自己的日志并脱敏(agent-node 的 runtime/node-logs.ts,由 cli.ts 注入)。
+     *  参数是 hub 转来的过滤 JSON;没有路径。缺省(例如 claude-code 通道进程)时 logs_tail 回 failed。 */
+    logsTail?: (rawParams: string | undefined) => Promise<{
+        files: string[];
+        lines: unknown[];
+        matched: number;
+    }>;
+}
+/** 一次门铃最多处理这么多条，防止 hub 侧异常堆积把节点拖进死循环。 */
+export declare const RULES_FILE_MAX_PER_DOORBELL = 8;
+/**
+ * 门铃处理器：拉 pending 请求直到空，每条 ack done / failed。
+ * 返回处理条数（测试用）。
+ */
+export declare function processRulesFileRequests(deps: ProcessRulesFileDeps): Promise<number>;

package/dist/src/secret-shell-guidance.d.ts

@@ -0,0 +1,4 @@
+export declare function formatSecretAssignment(platform: string, name: string, value: string): string;
+export declare function secretPersistenceHeading(platform: string): string;
+export declare function secretShellAction(platform: string): "set" | "export";
+export declare function formatSecretLoadCommand(platform: string, name: string, dotenvPath: string): string;

package/dist/src/session-status-class.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `anet status` 的会话状态分类。
+ *
+ * 🔴 为什么单独成文件:原先它是 statusCommand 里的一个闭包,没有任何测试碰得到它 ——
+ *    而它决定了运维看到的那三个数字。一个把「卡住」算成「在干活」的分类器,
+ *    和一个正确的分类器,在输出上长得一模一样(都是一个数)。
+ *
+ * 🔴 改了什么:`blocked` / `error` 原先被折进 `working`。
+ *    它们的含义是**需要人看一眼**,不是**正在推进**。
+ *    运维看到「5 working」会认为一切正常,而其中可能有几个卡了很久 ——
+ *    #1548 已经证明 `blocked` 是一个**没有出口**的状态:
+ *    只有 report_completion 能把它拉回 idle,所以一个 agent 可以永远停在那里。
+ *
+ * `waiting_input` 保留在 working 里:它是一个**进行中的回合**在等人,
+ * 与 blocked/error 不同 —— 那是回合本身出了问题。
+ */
+export type SessionClass = "idle" | "working" | "attention" | "offline";
+export declare function classifySessionStatus(raw: unknown): SessionClass;
+/**
+ * `anet status` 顶部那三/四个数字。
+ *
+ * 🔴 为什么它必须和上面的分类器用同一套判据(#1625):
+ *    原先 `cli.ts` 是 `statusRes.summary || sessions.reduce(…)`,而
+ *    `/api/status` **总是**返回 summary ⇒ 右边那支从不执行,屏幕上的数字
+ *    来自**服务端**一份还停在 #1548 之前的分类(它把 `blocked`/`error`
+ *    折进 `working`)。于是一个 blocked 节点同时出现在 `working` 和
+ *    `needs attention` 两格里,四个数加起来比总数多一个。
+ *
+ * 🔴 为什么本地算是安全的:`/api/status` 只加 `addNetworkScope`,没有任何
+ *    状态/别名过滤,而它的 summary 就是从**同一个 sessions 数组** reduce 出来的
+ *    —— 两者范围逐字相同。(这一点对 MCP 的 `get_all_status` **不成立**:
+ *    那边 summary 走独立的 `GROUP BY status` 查询、无视 filter,所以别照搬。)
+ *
+ * 🔴 `attention` 必须显式初始化为 0。原来的累加器只有
+ *    `{idle, working, offline, total}`,`acc["attention"]++` 会得到 **NaN**,
+ *    而 `summary.attention ?? attention.length` 里的 `??` **不接 NaN**,
+ *    屏幕会印 `NaN needs attention`。那一支从不执行,所以从没人见过。
+ */
+export type SessionSummary = {
+    idle: number;
+    working: number;
+    attention: number;
+    offline: number;
+    total: number;
+};
+export declare function summarizeSessions(sessions: Array<{
+    status?: unknown;
+}>): SessionSummary;

package/dist/src/sibling-agent-node.d.ts

@@ -0,0 +1,23 @@
+export interface SiblingAgentNode {
+    /** 直接可 `node <entrypoint>` 的文件。 */
+    entrypoint: string;
+    packageDir: string;
+    version: string | null;
+}
+export interface SiblingFs {
+    exists(path: string): boolean;
+    readJson(path: string): unknown;
+    /**
+     * #1832 —— npm -g / --prefix 布局下 process.argv[1] 是 `<prefix>/bin/anet` 符号链接,真实文件在
+     * `<prefix>/lib/node_modules/@sleep2agi/agent-network/…`;不解析就从 `<prefix>/bin` 往上找不到
+     * node_modules,旁边的 agent-node 永远命不中。可选:不提供或抛错时按传入路径原样找。
+     */
+    realpath?(path: string): string;
+}
+/** 入口路径先走 realpath(符号链接 → 真实文件);失败(不存在 / 无权限)退回原路径。 */
+export declare function resolveCliEntry(cliEntry: string, fs: SiblingFs): string;
+/** 从 anet 入口文件路径往上,返回最近的 `…/node_modules` 目录;找不到返回 null。 */
+export declare function nearestNodeModules(cliEntry: string): string | null;
+/** package.json 的 bin 可以是字符串或 { name: path };只认名为 agent-node 的那条。 */
+export declare function binEntryFromPackageJson(pkg: unknown): string | null;
+export declare function siblingAgentNodeEntrypoint(cliEntry: string, fs: SiblingFs): SiblingAgentNode | null;

package/dist/src/stale-socket.d.ts

@@ -0,0 +1,118 @@
+export interface StaleSocketProbes {
+    /** 读 /proc/net/unix 全文;读不到就 throw(调用方按 fail-closed 处理)。 */
+    procNetUnix(): string;
+    /** 路径不存在返回 null。 */
+    lstat(path: string): {
+        dev: number;
+        ino: number;
+        uid: number;
+        isSocket: boolean;
+    } | null;
+    unlink(path: string): void;
+    /** 当前进程 uid —— 只回收自己拥有的 socket。 */
+    currentUid(): number;
+}
+export interface ReapScope {
+    /**
+     * 只允许回收这个目录**之下**的路径。
+     * 🔴 这一格防的不是文件系统竞态,是**被污染的 identity**:socket 路径来自
+     *    profile,如果 profile 被写坏成 `/run/systemd/private` 之类,前面所有
+     *    "无监听者"检查都会照常通过,然后 unlink 掉一个不属于这个节点的东西。
+     *    删除不可逆,所以范围校验必须在**所有**其它检查之前。
+     */
+    allowedRoot: string;
+}
+export type ReapOutcome = 
+/** 路径已经不在了 —— 正常的成功拆卸,无事可做。 */
+{
+    kind: "absent";
+}
+/** 确认无人引用,已删除。 */
+ | {
+    kind: "removed";
+}
+/** /proc/net/unix 里仍能找到这个路径 ⇒ 有人在用,**不删**,调用方应判红。 */
+ | {
+    kind: "in-use";
+}
+/** /proc/net/unix 读不到 ⇒ fail-closed,不删。 */
+ | {
+    kind: "unreadable";
+    detail: string;
+}
+/** 检查与删除之间文件身份变了(dev/ino/uid),或已不是 socket ⇒ 不删。 */
+ | {
+    kind: "changed";
+}
+/** 路径不在该节点自己的 runtime 目录之下 ⇒ 一律不删。 */
+ | {
+    kind: "out-of-scope";
+    detail: string;
+};
+/**
+ * `/proc/net/unix` 的每一行以路径结尾(没有绑定路径的行就没有这一列)。
+ * 这里只问「这个路径出现过没有」,不解释 flags/type/state。
+ */
+export declare function unixSocketPathInUse(procNetUnix: string, path: string): boolean;
+/**
+ * 属主进程**已被证明消失之后**,回收一个陈旧的 socket 路径名。
+ * 任何一种不确定都不删 —— 删文件不可逆,而留下一个 socket 只是让 stop 判红,
+ * 那正是本函数之前的行为。
+ */
+export declare function reapStaleSocket(path: string, probes: StaleSocketProbes, scope: ReapScope): ReapOutcome;
+/**
+ * 从「本次 stop 看到的残留路径」里挑出**允许回收**的那些。
+ *
+ * 🔴 判据是「与重新算出来的规范路径**完全相等**」,不是前缀、不是包含。
+ *    profile 里存的 socket 路径是**被写坏就会跟着坏**的数据;
+ *    grokCopresenceSocketPaths 是纯函数,同样的 nodeId + home 永远算出同一个值。
+ *    所以这里不问「这条路径看起来对不对」,只问「它是不是我自己算出来的那两个之一」。
+ *    ——一个被污染的 profile 因此一条都带不进来。
+ */
+export declare function planReapableSockets(canonical: {
+    leaderSocket: string;
+    attachSocket: string;
+}, residualPaths: readonly (string | undefined)[]): string[];
+export interface CanonicalSocketProfile {
+    node_id?: string;
+    grokLeaderSocket?: string;
+    grokAttachSocket?: string;
+}
+export type CanonicalSocketsOutcome = {
+    kind: "ok";
+    leaderSocket: string;
+    attachSocket: string;
+}
+/** profile 里没有 node_id —— 算不出来,不动手。 */
+ | {
+    kind: "no-node-id";
+}
+/** 重新算出来的与 profile 存的不一致 —— profile 被写坏、HOME 变了、或**调用方喂错了 id**。 */
+ | {
+    kind: "mismatch";
+    recomputedLeader: string;
+    storedLeader: string;
+}
+/** 路径算不出来(grokCopresenceSocketPaths 抛错)—— 不动手,但也不该把 stop 整个弄失败。 */
+ | {
+    kind: "uncomputable";
+    detail: string;
+};
+/**
+ * 从 profile 推出规范 socket 路径,并**与 profile 里存的那份交叉校验**。
+ *
+ * 🔴 这个交叉校验是一次真实缺陷催生的,不是补全性写的:
+ *    我第一版在 cli.ts 里写的是 `grokCopresenceSocketPaths(resolved.id)`,而
+ *    `resolveNodeRef` 返回的 `id` 是**目录名(别名)**,socket 路径却是
+ *    `anet node create` 用 **node_id** 算的。两者哈希不同 ⇒ 算出的路径永远对不上 ⇒
+ *    可回收集合恒为空 ⇒ **一条都回收不了,而且完全静默**(循环体一次都不进)。
+ *    12 轮验收里 4 次红、0 次回收,红话与修复前逐字相同 —— 从外面看,
+ *    「守卫拒绝了一切」和「这个修复不存在」是同一个样子。
+ *
+ *    所以判据不能只是「算一个路径出来」,必须是「算出来的和存着的对得上」。
+ *    对不上就说出来,别静默跳过。
+ */
+export declare function canonicalSocketsForProfile(profile: CanonicalSocketProfile, compute: (nodeId: string) => {
+    leaderSocket: string;
+    attachSocket: string;
+}): CanonicalSocketsOutcome;