@sleep2agi/agent-network 2.3.0-preview.11 → 2.3.0-preview.110

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;

package/dist/src/grok-attach-client.d.ts

@@ -0,0 +1,129 @@
+import type { Duplex } from "node:stream";
+export declare const GROK_ATTACH_PROTOCOL = "anet-grok-copresence-attach";
+export declare const GROK_ATTACH_PROTOCOL_VERSION = 1;
+export declare const GROK_ATTACH_DEFAULT_MAX_FRAME_BYTES: number;
+export declare const GROK_ATTACH_DEFAULT_MAX_BUFFER_BYTES: number;
+export declare const GROK_ATTACH_DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+export declare const GROK_ATTACH_DEFAULT_CLOSE_TIMEOUT_MS = 1000;
+export type GrokAttachJsonValue = null | boolean | number | string | GrokAttachJsonValue[] | {
+    [key: string]: GrokAttachJsonValue;
+};
+export interface GrokAttachHelloFrame {
+    type: "hello";
+    protocol: typeof GROK_ATTACH_PROTOCOL;
+    version: typeof GROK_ATTACH_PROTOCOL_VERSION;
+    alias: string;
+    sessionId: string;
+    [key: string]: unknown;
+}
+export interface GrokAttachOutputFrame {
+    type: "output";
+    data: string;
+    encoding: "base64";
+}
+export interface GrokAttachStatusFrame {
+    type: "status";
+    status: GrokAttachJsonValue;
+}
+export interface GrokAttachErrorFrame {
+    type: "error";
+    code: string;
+    message: string;
+    fatal: boolean;
+}
+export interface GrokAttachDetachFrame {
+    type: "detach";
+}
+export type GrokAttachServerFrame = GrokAttachHelloFrame | GrokAttachOutputFrame | GrokAttachStatusFrame | GrokAttachErrorFrame | GrokAttachDetachFrame;
+export interface GrokAttachInputFrame {
+    type: "input";
+    data: string;
+    encoding: "base64";
+}
+export interface GrokAttachResizeFrame {
+    type: "resize";
+    cols: number;
+    rows: number;
+}
+/** Asks the node to switch models (issue #879); allowed on control connections. */
+export interface GrokAttachSetModelFrame {
+    type: "set-model";
+    model: string;
+}
+export type GrokAttachClientFrame = GrokAttachInputFrame | GrokAttachResizeFrame | GrokAttachSetModelFrame | GrokAttachDetachFrame;
+export interface GrokAttachInputSource {
+    on(event: "data", listener: (chunk: unknown) => void): unknown;
+    on(event: "end", listener: () => void): unknown;
+    off?(event: "data" | "end", listener: (...args: any[]) => void): unknown;
+    removeListener?(event: "data" | "end", listener: (...args: any[]) => void): unknown;
+    pause?(): unknown;
+    resume?(): unknown;
+}
+export interface GrokAttachOutputSink {
+    write(chunk: Uint8Array): boolean | void;
+    columns?: number;
+    rows?: number;
+    once?(event: "drain", listener: () => void): unknown;
+}
+export interface GrokAttachSignalSource {
+    on(event: "SIGWINCH", listener: () => void): unknown;
+    off?(event: "SIGWINCH", listener: () => void): unknown;
+    removeListener?(event: "SIGWINCH", listener: () => void): unknown;
+}
+export interface GrokAttachSocketStat {
+    uid: number;
+    isSocket(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface GrokAttachDependencies {
+    lstat?: (socketPath: string) => Promise<GrokAttachSocketStat>;
+    getuid?: () => number | undefined;
+    connect?: (socketPath: string) => Duplex;
+}
+export interface GrokAttachClientOptions {
+    socketPath: string;
+    input: GrokAttachInputSource;
+    output: GrokAttachOutputSink;
+    signalSource?: GrokAttachSignalSource;
+    terminalSize?: () => {
+        cols: number | undefined;
+        rows: number | undefined;
+    };
+    maxFrameBytes?: number;
+    maxBufferBytes?: number;
+    handshakeTimeoutMs?: number;
+    closeTimeoutMs?: number;
+    detachOnInputEnd?: boolean;
+    onHello?: (frame: GrokAttachHelloFrame) => void;
+    onStatus?: (frame: GrokAttachStatusFrame) => void;
+    onError?: (error: Error, frame?: GrokAttachErrorFrame) => void;
+    onDetach?: (frame: GrokAttachDetachFrame) => void;
+    dependencies?: GrokAttachDependencies;
+}
+export type GrokAttachCloseReason = "local-detach" | "input-end" | "remote-detach" | "socket-close" | "socket-error" | "protocol-error";
+export interface GrokAttachCloseInfo {
+    reason: GrokAttachCloseReason;
+    error?: Error;
+}
+export interface GrokAttachSession {
+    readonly socketPath: string;
+    readonly closed: Promise<GrokAttachCloseInfo>;
+    detach(): void;
+    resize(cols?: number, rows?: number): void;
+    /**
+     * Ask the node to switch models (issue #879).
+     *
+     * The outcome does not come back from this call — it arrives as a `status`
+     * frame carrying `modelSwitch`, because the node may accept, refuse
+     * (busy / unchanged / invalid), or fail while re-spawning. Callers read it
+     * through `onStatus`.
+     */
+    setModel(model: string): void;
+}
+export declare class GrokAttachRemoteError extends Error {
+    readonly code: string;
+    readonly fatal: boolean;
+    constructor(frame: GrokAttachErrorFrame);
+}
+export declare function validateGrokAttachSocket(socketPath: string, dependencies?: GrokAttachDependencies): Promise<void>;
+export declare function connectGrokAttach(options: GrokAttachClientOptions): Promise<GrokAttachSession>;

package/dist/src/grok-build-drift.d.ts

@@ -0,0 +1,15 @@
+/** 从一段日志文本里取出**最后一次**出现的 grok 版本串。
+ *  🔴 取最后一次，不是第一次：日志按时间追加，最后一次才是这个进程最近一次
+ *     启动时用的那个。取第一次会在日志轮转/多次重启后指向历史。 */
+export declare function parseGrokBuildFromLog(text: string): string | undefined;
+/** 从 `grok --version` 的输出里取版本串（同一形状）。 */
+export declare function parseGrokBuildFromVersionOutput(out: string): string | undefined;
+export type GrokBuildDriftKind = "match" | "drift" | "unknown-current" | "unknown-started";
+export interface GrokBuildDrift {
+    readonly kind: GrokBuildDriftKind;
+    readonly started?: string;
+    readonly current?: string;
+    /** 一句人读的话。四种 kind 四句不同的话 —— 含糊化等于把这一格的功能删掉。 */
+    readonly line: string;
+}
+export declare function describeGrokBuildDrift(started: string | undefined, current: string | undefined): GrokBuildDrift;

package/dist/src/grok-copresence-disclosure.d.ts

@@ -0,0 +1,11 @@
+export type GrokCopresenceSessionDisclosure = "configured" | "new" | "resume";
+export type GrokCopresenceDisclosure = {
+    profile: "commhub-only" | "x-search" | "repo-read" | "invalid";
+    lines: readonly string[];
+};
+/**
+ * Describe only the exact tool profiles accepted by the pinned Grok TUI
+ * runtime. This is deliberately exact: a near-miss must never be presented as
+ * either reviewed capability set.
+ */
+export declare function grokCopresenceDisclosure(tools: unknown, session?: GrokCopresenceSessionDisclosure): GrokCopresenceDisclosure;

package/dist/src/grok-copresence-orchestration.d.ts

@@ -0,0 +1,75 @@
+/** tmux session names. The attachable TUI owns the bare alias so that
+ *  `tmux attach -t '=<alias>'` lands a human on the TUI, matching the codex
+ *  lane exactly — an operator should not have to remember which runtime a node
+ *  uses in order to know where to attach. */
+export declare function grokCopresenceSessions(displayName: string): {
+    node: string;
+    tui: string;
+};
+export type GrokAttachSocketState = "missing" | "not_a_socket" | "ready";
+/** Readiness is "the attach socket exists AND is a socket", never "the child
+ *  process started". A grok leader that dies during startup leaves either no
+ *  socket at all or a stale regular file from an aborted run; both used to read
+ *  as ready because nothing looked. */
+export declare function grokAttachSocketState(entry: {
+    isSocket(): boolean;
+} | null | undefined): GrokAttachSocketState;
+/** Set on the node child so that `anet node start` inside the tmux session does
+ *  not re-enter this orchestration and fork bomb. The codex lane guards on the
+ *  same variable (cli.ts: `process.env.ANET_COPRESENCE_BRIDGE !== "1"`); using a
+ *  second name would leave two guards that must be kept in sync by hand. */
+export declare const GROK_COPRESENCE_CHILD_ENV = "ANET_COPRESENCE_BRIDGE";
+export interface GrokCopresenceDiagnosis {
+    readonly ok: boolean;
+    readonly lines: readonly string[];
+    /** #1768 —— 非阻断提示:平台能跑,但 agent-node 的能力表说它少了内核层保证。
+     *  ok=true 时也可能非空;调用方打印它,不退出。 */
+    readonly notices: readonly string[];
+}
+/** One block naming every reason this node cannot run the shared TUI, not one
+ *  exit per reason. A node that is both the wrong runtime AND missing its
+ *  attach socket should learn both in one run. */
+/** Platforms whose PTY / IPC / isolation primitives the grok co-presence lane
+ *  has actually been validated on. agent-node refuses anywhere else, and it does
+ *  so only after the node has been created and started once:
+ *
+ *    [agent-node] grok-build-cli co-presence 无法在 darwin 上运行，缺少：
+ *                 平台 darwin 尚未验证过共存所需的 PTY / IPC / 隔离原语
+ *
+ *  Learned the expensive way on a Mac mini: install anet, install agent-node,
+ *  create the node, start it — and only then find out the platform is refused.
+ *  A one-command launcher that lets someone get that far has not saved them
+ *  anything, so say it in the same breath as every other gap. */
+export declare const GROK_COPRESENCE_PLATFORMS: readonly NodeJS.Platform[];
+/** 能跑但没有内核层强制的平台 —— agent-node 启动时逐条打印 reducedGuarantees,这里只提前说一句。 */
+export declare const GROK_COPRESENCE_REDUCED_GUARANTEE_PLATFORMS: readonly NodeJS.Platform[];
+export declare function diagnoseGrokCopresence(input: {
+    runtime: string;
+    displayName: string;
+    grokCopresence?: boolean;
+    grokAttachSocket?: string;
+    platform?: NodeJS.Platform;
+}): GrokCopresenceDiagnosis;
+/** True when a plain `anet node start <name>` (no flag) should bring the shared
+ *  TUI up by itself.
+ *
+ * 🔴 Deliberately NOT keyed on `grokCopresence`. That field is set to true at
+ *    CREATE time for every grok-build-cli node, so reading it here would silently
+ *    change what `anet node start` does for every grok node that already exists —
+ *    they would stop running in the foreground and fork into tmux, unasked. Caught
+ *    exactly that way: a start without the flag entered the orchestration.
+ *
+ *    The codex lane looks the same but is not: `codexCopresence` is written only
+ *    when the operator passes the flag. So grok needs its own record of the
+ *    operator's choice, and `grokCopresenceAuto` is it. */
+export declare function grokCopresenceRequested(flagPassed: boolean, profile: {
+    runtime?: unknown;
+    grokCopresence?: unknown;
+    grokCopresenceAuto?: unknown;
+}): boolean;
+/** Record the operator's opt-in so the NEXT start needs no flag — and only then.
+ *  Never infer it from `grokCopresence`, which create sets by default. */
+export declare function shouldPersistGrokCopresence(flagPassed: boolean, profile: {
+    runtime?: unknown;
+    grokCopresenceAuto?: unknown;
+}): boolean;

package/dist/src/grok-copresence-profile.d.ts

@@ -0,0 +1,65 @@
+export declare const GROK_UNIX_SOCKET_PATH_MAX_BYTES = 100;
+export declare const GROK_COPRESENCE_CAPABILITY_MARKER = "ANET_CAPABILITY_GROK_COPRESENCE_V2";
+export declare const GROK_PREVIEW_RESOLVER_INHERITED_ENV_KEYS: readonly ["PATH", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "TZ"];
+export declare const GROK_AGENT_NODE_INHERITED_ENV_KEYS: readonly ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "SHELL", "USER", "LOGNAME", "TERM", "COLORTERM", "NO_COLOR"];
+export declare const GROK_AGENT_NODE_OPTIONAL_ENV_KEYS: readonly ["GROK_BINARY", "GROK_HOME", "FLOCK_BINARY", "SETPRIV_BINARY", "UNSHARE_BINARY", "GROK_CLI_TIMEOUT_MS", "GROK_HANDSHAKE_TIMEOUT_MS", "LOG_LEVEL", "ANET_GOAL_TICK_MS", "COMMHUB_MAX_GOALS_PER_NODE"];
+/** Exact environment for the long-lived agent-node parent of the Grok TUI. */
+export declare function buildGrokAgentNodeEnv(parentEnv: NodeJS.ProcessEnv): Record<string, string>;
+export declare function grokPreviewResolverConfigPaths(home: string): {
+    directory: string;
+    userConfig: string;
+    globalConfig: string;
+};
+/**
+ * npm rejects loading the same file as both user and global config. Prepare
+ * two distinct, empty, owner-only files without following a final symlink so
+ * the resolver cannot inherit a user's ordinary npmrc credentials.
+ */
+export declare function prepareGrokPreviewResolverConfigs(home: string): void;
+/** Exact environment for the short-lived npm resolver and capability probe. */
+export declare function buildGrokPreviewResolverEnv(parentEnv: NodeJS.ProcessEnv, home: string): Record<string, string>;
+/** Old headless-only agent-node builds already advertised grok-build-cli. */
+export declare function agentNodeHelpSupportsGrokCopresence(help: string): boolean;
+export interface GrokCopresenceProfileFields {
+    grokCopresence: boolean;
+    grokLeaderSocket?: string;
+    grokAttachSocket?: string;
+}
+export interface GrokSocketPathOptions {
+    cwd?: string;
+    home?: string;
+    xdgRuntimeDir?: string;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Allocate deterministic Unix socket paths without creating anything.
+ *
+ * Grok's workspace sandbox does not admit an otherwise owner-controlled
+ * XDG_RUNTIME_DIR such as /run/user/<uid>. Keep the primary sockets under the
+ * node's owner-bound state home, which the runtime already admits, and use a
+ * short private tmp path only when the Unix socket length limit requires it.
+ * The runtime owns directory creation and permissions; `anet node create`
+ * only persists the identity of the two sockets.
+ */
+export declare function grokCopresenceSocketPaths(nodeId: string, options?: GrokSocketPathOptions): {
+    leaderSocket: string;
+    attachSocket: string;
+};
+export type GrokAttachTarget = {
+    ok: true;
+    socketPath: string;
+} | {
+    ok: false;
+    reason: "not_grok_build_cli" | "headless" | "missing_attach_socket";
+};
+/**
+ * `anet grok attach` eligibility. The CLI is the only human join path;
+ * this is the shipped decision so tests can drive it without a TTY.
+ */
+export declare function resolveGrokAttachTarget(input: {
+    runtime: string;
+    grokCopresence?: unknown;
+    grokAttachSocket?: unknown;
+}): GrokAttachTarget;
+export declare function grokBuildCliCreationFields(runtime: string, nodeId: string, headless?: boolean, options?: GrokSocketPathOptions): GrokCopresenceProfileFields | Record<string, never>;

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

@@ -0,0 +1,14 @@
+export interface HostTelemetry {
+    hostname: string;
+    ip: string | null;
+    cpu_load_1min: number | null;
+    cpu_cores: number | null;
+    mem_total_gb: number | null;
+    mem_used_gb: number | null;
+    mem_avail_gb: number | null;
+    disk_total_gb: number | null;
+    disk_used_gb: number | null;
+    disk_avail_gb: number | null;
+}
+export declare function getHostTelemetry(): HostTelemetry;
+export declare function _clearHostTelemetryCache(): void;

package/dist/src/hub-health-timeout.d.ts

@@ -0,0 +1,4 @@
+export declare const LOOPBACK_HUB_HEALTH_TIMEOUT_MS = 2000;
+export declare const REMOTE_HUB_HEALTH_TIMEOUT_MS = 10000;
+export declare const HUB_HEALTH_TIMEOUT_ENV = "ANET_HUB_HEALTH_TIMEOUT_MS";
+export declare function hubHealthTimeoutMs(hub: string, env?: NodeJS.ProcessEnv): number;

package/dist/src/hub-time-display.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 把 hub 的 TEXT 时间戳显示给人看。
+ *
+ * 🔴 原先是**原样打印**:
+ *
+ *     updated:  2026-08-31 00:20:11
+ *
+ * 那是 UTC,**没有任何时区标记**。同一时刻本地是 `08:22:41 CST` ——
+ * 于是一个 **2 分钟前**刚心跳过的节点,在 UTC+8 的用户眼里像是 **8 小时前**的。
+ *
+ * 这不是假想:2026-08-31 我自己就这么读错过一次,据此差点报出「舰队心跳陈旧
+ * 8.3 小时」。**CLI 在主动制造这个误读。**
+ *
+ * 所以显示两样东西:
+ *   - **相对时长**(人真正想知道的那个)
+ *   - 绝对值,并**显式标 UTC**(便于和日志、issue 里的时间对齐)
+ */
+export declare function formatHubTime(raw: unknown, nowMs?: number): string;
+/** 人读的时长。负数(时钟偏差/未来时间)如实说,不折成 0。 */
+export declare function formatAgo(deltaMs: number): string;

package/dist/src/hub-version-skew.d.ts

@@ -0,0 +1,19 @@
+/**
+ * #1595 —— `anet doctor` 原先只印 hub 自报的版本:
+ *
+ *   ✅ CommHub reachable (http://127.0.0.1:9200 v0.9.0-preview.38)
+ *
+ * 读的人**看不到自己这台 CLI 钉的是哪个**。实测(2026-08-31):生产 hub 在
+ * `.38`,而 `anet hub start` 的 `PINNED_SERVER_VERSION` 是 `.44` —— 两个数
+ * 差 6 个版本,而屏幕上只有一个。今天有一整条排查(agent→用户消息为什么
+ * 验不了端到端)就卡在这个差上:`.44` 之前 `send_desktop_message` 是
+ * fire-and-forget 且仍返回 `ok:true`,所以在 `.38` 上拿到的 `ok:true`
+ * 不是「用户看到了」的证据。
+ *
+ * 🔴 **只并排摆出两个数,不判断谁对、不给阈值、不发警告。**
+ *    hub 比 CLI 的 pin 老或新都可能完全合理 —— 连的是别人运维的 hub、
+ *    本机 hub 还没重启、或者故意钉在旧版。给一个猜出来的「应该一致」
+ *    判据,会在这些正常情况下变成误报,而一个会误报的检查第一周就会被关掉。
+ *    让读的人自己看见差在哪,是这一格能诚实做到的全部。
+ */
+export declare function formatHubVersionDetail(hubUrl: string, hubVersion: unknown, pinnedVersion: string): string;

package/dist/src/im/correlation-store.d.ts

@@ -0,0 +1,34 @@
+import type { IMCorrelationStore, IMTaskCorrelation } from "./types";
+export interface JsonIMCorrelationStoreOptions {
+    now?: () => number;
+    /** How long idempotency keys remain valid. Defaults to 24h. */
+    seenTtlMs?: number;
+    /** How long terminal correlations remain queryable. Defaults to 24h. */
+    terminalTtlMs?: number;
+}
+/**
+ * Small durable store for RFC-020 §2.9④ / §4.4 correlation state.
+ *
+ * The first gateway PR needs this as a standalone data structure before the
+ * bridge is rewired: idempotency keys survive process restart, and task replies
+ * can be routed back to their originating IM conversation.
+ */
+export declare class JsonIMCorrelationStore implements IMCorrelationStore {
+    private readonly path;
+    private readonly now;
+    private readonly seenTtlMs;
+    private readonly terminalTtlMs;
+    constructor(path: string, options?: JsonIMCorrelationStoreOptions);
+    hasSeen(idempotencyKey: string): Promise<string | null>;
+    recordSeen(idempotencyKey: string, taskId: string): Promise<void>;
+    getCorrelation(taskId: string): Promise<IMTaskCorrelation | null>;
+    putCorrelation(taskId: string, correlation: IMTaskCorrelation): Promise<void>;
+    updateStatus(taskId: string, status: IMTaskCorrelation["status"]): Promise<void>;
+    gc(now: number): Promise<{
+        removed: number;
+    }>;
+    private isExpired;
+    private load;
+    private save;
+}
+export declare function createJsonIMCorrelationStore(path: string, options?: JsonIMCorrelationStoreOptions): IMCorrelationStore;