@sleep2agi/agent-network 2.3.0-preview.18 → 2.3.0-preview.180

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/shared/opencode-borrowed-launch-health.d.ts

@@ -0,0 +1,29 @@
+export declare const BORROWED_LAUNCH_HEALTH = "opencode-borrowed-v1-launch.json";
+export declare function hasBorrowedV1Intent(dir: string, config: any): boolean;
+/** Read-only preflight. Runtime admission still validates the independent Host,
+ * binary, original credentials, native directory/session and cooperative lease. */
+export declare function readBorrowedLaunchConfig(configPath: string, cwd?: string): {
+    selection: any;
+    alias: any;
+    model: any;
+    stamp: number[];
+};
+export declare function publishBorrowedLaunchHealth(configPath: string, nonce: string): () => void;
+export declare function inspectBorrowedLaunchHealth(configPath: string, launchedAt: number, nonce?: string): {
+    ok: true;
+    bridgePid: number;
+    reason?: undefined;
+} | {
+    ok: false;
+    reason: string;
+    bridgePid?: undefined;
+};
+export declare function waitForBorrowedLaunchHealth(configPath: string, launchedAt: number, deadline: number, nonce?: string): Promise<{
+    ok: true;
+    bridgePid: number;
+    reason?: undefined;
+} | {
+    ok: false;
+    reason: string;
+    bridgePid?: undefined;
+}>;

package/dist/src/shared/provider-collection.d.ts

@@ -0,0 +1,9 @@
+export type ProviderCollection = {
+    node_id: string;
+    alias: string;
+    node_revision: string;
+    provider_id: string;
+    auth_id: string;
+    label: string;
+};
+export declare function validProviderCollection(v: any): v is ProviderCollection;

package/dist/src/shared/provider-initialization.d.ts

@@ -0,0 +1,7 @@
+export type ProviderInitialization = {
+    revision: number;
+    provider_id: string;
+    auth_id: string;
+    model: string;
+};
+export declare function validProviderInitialization(value: any): value is ProviderInitialization;

package/dist/src/shared/reserved-env.d.ts

@@ -0,0 +1,3 @@
+export declare const RESERVED_ENV_KEYS_EXACT: Set<string>;
+export declare const RESERVED_ENV_PREFIXES: ReadonlyArray<string>;
+export declare function isReservedEnvKey(k: string): boolean;

package/dist/src/shared/scoped-secret-contract.d.ts

@@ -0,0 +1 @@
+export declare const validScopedSecretKey: (key: unknown) => key is string;

package/dist/src/shared/scoped-secret-env.d.ts

@@ -0,0 +1,3 @@
+export declare function scopedSecretJson(path: string): any;
+export declare function readIndependentNodeEnv(nodeDir: string): Record<string, string>;
+export declare function readScopedNodeEnv(nodeDir: string): Record<string, string>;

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;

package/dist/src/standalone-bin.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure helpers for the standalone `anet` executable (`bun build --compile`).
+ *
+ * npm/node keeps today's behavior: these functions are identity transforms
+ * when `stamp.standalone` is false. The compiled binary sets the stamp at
+ * build time (`scripts/build-anet-bin.mjs`) and routes Hub / agent-node
+ * through internal argv (`__hub` / `__node`) because `process.execPath` is
+ * the `anet` binary itself, not bun or node.
+ */
+import { STANDALONE_BUILD_STAMP, type StandaloneBuildStamp, type StandalonePackageVersions } from "./standalone-build-stamp";
+export type { StandaloneBuildStamp, StandalonePackageVersions };
+export { STANDALONE_BUILD_STAMP };
+/** Internal argv. Not user-facing commands; the unified entry strips them. */
+export declare const STANDALONE_HUB_ARG = "__hub";
+export declare const STANDALONE_NODE_ARG = "__node";
+export declare const STANDALONE_PRINT_CONFIG_TOKEN_ARG = "__print-config-token";
+export type StandaloneDispatchKind = "cli" | "hub" | "node" | "print-config-token";
+export interface StandaloneDispatch {
+    kind: StandaloneDispatchKind;
+    /** Args after the internal selector. CLI kind keeps the full user argv. */
+    argv: string[];
+}
+export interface DetectedPackageLike {
+    name: string;
+    displayName: string;
+    version: string | null;
+    state: "ok" | "unknown" | "not-installed";
+    source?: string;
+}
+/**
+ * True when `arg` is the script slot bun/node inserts at argv[1]
+ * (`bun bin/anet-bin.ts`, or a compiled binary's `/$bunfs/...` path).
+ * A user argument that merely ends in `.ts` is not a script slot.
+ */
+export declare function isBundlerScriptSlot(arg: string): boolean;
+/** User args, whether argv is Node-shaped (script at [1]) or a raw executable. */
+export declare function standaloneUserArgs(argv: readonly string[]): string[];
+export declare function dispatchStandalone(userArgs: readonly string[]): StandaloneDispatch;
+/**
+ * `cli.ts`, `commhub.ts`, and `agent-node`'s CLI all read `process.argv.slice(2)`.
+ * Force that shape so the same entries work under bun, node, and `bun build --compile`
+ * (compiled argv may or may not keep a virtual script path at [1]).
+ */
+export declare function nodeStyleArgv(execPath: string, userArgs: readonly string[]): string[];
+export declare function isStandaloneBuild(stamp: StandaloneBuildStamp): boolean;
+export declare function anetVersionFromStamp(stamp: StandaloneBuildStamp): string | null;
+export declare function standaloneBundleVersion(stamp: StandaloneBuildStamp): string | null;
+/** Bytes of the `anet --version` header. No bundle line unless the stamp has one. */
+export declare function formatAnetVersionBanner(anetVersion: string, bundle: string | null): string;
+export declare function standaloneNodeServerJs(stamp: StandaloneBuildStamp): string | null;
+export declare function applyStandaloneDetectedVersions<T extends {
+    anet: {
+        version: string;
+    };
+    agentNode: DetectedPackageLike;
+    commhubServer: DetectedPackageLike;
+    bun?: DetectedPackageLike;
+}>(versions: T, stamp: StandaloneBuildStamp): T;
+export interface CliReinvokeInput {
+    standalone: boolean;
+    execArgv: readonly string[];
+    /** `process.argv[1]` for npm/node. Ignored when `standalone` is true. */
+    scriptPath: string;
+    cliArgs: readonly string[];
+    /** Match call sites that already forward `process.execArgv` (tsx loaders). */
+    includeExecArgv: boolean;
+}
+/**
+ * Argv after `process.execPath` when re-invoking this CLI.
+ * npm/node: `[script, ...cliArgs]` or `[...execArgv, script, ...cliArgs]`.
+ * standalone: just `cliArgs` — the binary is already `anet`.
+ */
+export declare function cliReinvokeArgs(input: CliReinvokeInput): string[];
+export declare function cliReinvokeShell(input: CliReinvokeInput & {
+    execPath: string;
+    quote: (value: string) => string;
+}): string;
+export interface StandaloneHubLaunchInput {
+    /** `--version` / `--hub-version` value, or null when the user did not pass one. */
+    explicitVersion: string | null;
+    port: string;
+    host: string;
+    devOpen: boolean;
+}
+export type StandaloneHubLaunch = {
+    ok: true;
+    version: string;
+    origin: string;
+    warnings: string[];
+    args: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Argv for the embedded Hub. The standalone binary cannot `bunx` a registry
+ * package; a requested version other than the embedded one is refused.
+ */
+export declare function standaloneHubLaunch(stamp: StandaloneBuildStamp, input: StandaloneHubLaunchInput): StandaloneHubLaunch;
+/** Argv after `process.execPath` when launching the embedded agent-node. */
+export declare function standaloneNodeArgs(agentArgs: readonly string[]): string[];

package/dist/src/standalone-build-stamp.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build stamp for the standalone `anet` executable.
+ *
+ * The committed value is inactive. `scripts/build-anet-bin.mjs` rewrites this
+ * file only for the duration of `bun build --compile`, then restores it.
+ * npm/node runs of `bin/cli.ts` must keep seeing `standalone: false`.
+ *
+ * Versions are read from each package's package.json at binary-build time.
+ * Do not hard-code release versions here — those constants belong to the
+ * packages (and to the in-flight release that owns them).
+ */
+export interface StandalonePackageVersions {
+    /** `@sleep2agi/agent-network` package.json version. */
+    anet: string;
+    /** `@sleep2agi/agent-node` package.json version. */
+    agentNode: string;
+    /** `@sleep2agi/commhub-server` package.json version. */
+    commhubServer: string;
+    /** Release label of this executable (`cli-bin-v<bundle>`). */
+    bundle: string;
+}
+export interface StandaloneBuildStamp {
+    standalone: boolean;
+    versions: StandalonePackageVersions | null;
+    /**
+     * Prebundled `.anet/node-server.js` payload (target node, version marker
+     * already stamped). Null outside the standalone binary. The compiled
+     * executable has no real package layout, so the CLI cannot find
+     * `node-server.js` via `import.meta.url`.
+     */
+    nodeServerJs: string | null;
+}
+export declare const STANDALONE_BUILD_STAMP: StandaloneBuildStamp;

package/dist/src/start-resource-gate.d.ts

@@ -0,0 +1,146 @@
+export declare const START_GATE_DEFAULT_MIN_MEM_MB = 4096;
+export declare const START_GATE_DEFAULT_MEM_FRACTION = 0.15;
+export declare const START_GATE_DEFAULT_MAX_LOAD_PER_CPU = 4;
+export declare const START_GATE_DEFAULT_MAX_WAIT_SEC = 600;
+export declare const START_GATE_DEFAULT_MAX_CONCURRENT = 2;
+export declare const START_GATE_SINGLE_LANE_CONCURRENT = 1;
+export declare const START_GATE_RECHECK_MS = 15000;
+/** Jitter added to each re-check while still inside the max wait: uniform [0, RECHECK_JITTER_MS). */
+export declare const START_GATE_RECHECK_JITTER_MS = 5000;
+export declare const START_GATE_WAITING_MEMORY_STATUS = "\u7B49\u5F85\u5185\u5B58";
+export declare const START_GATE_WAITING_LOAD_STATUS = "\u7B49\u5F85\u8D1F\u8F7D";
+export declare const START_GATE_WAITING_BOTH_STATUS = "\u7B49\u5F85\u5185\u5B58\u548C\u8D1F\u8F7D";
+export declare const START_GATE_WAITING_PROBE_STATUS = "\u7B49\u5F85\u8D44\u6E90\u63A2\u6D4B";
+/** #686 compatibility alias for callers that used the original memory-only status. */
+export declare const START_GATE_WAITING_STATUS = "\u7B49\u5F85\u5185\u5B58";
+export declare const START_GATE_SINGLE_LANE_STATUS = "\u5DF2\u8D85\u65F6\uFF0C\u6309\u5355\u8DEF\u653E\u884C";
+/** Logged when one waiter atomically replaces a stuck lease. The wait cap must not admit without this. */
+export declare const START_GATE_TAKEOVER_STATUS = "\u63A5\u7BA1\u5361\u6B7B\u79DF\u7EA6";
+/** Startup leases older than this are not live. ANET_START_LEASE_TTL_SEC overrides it. */
+export declare const START_GATE_LEASE_TTL_MS: number;
+/** A healthy holder renews well before the default lease expiry. */
+export declare const START_GATE_LEASE_HEARTBEAT_MS = 30000;
+/** An empty or unreadable lock younger than this is still being published, not dead. */
+export declare const START_GATE_LOCK_STALE_MS = 30000;
+/**
+ * A live matching lock is an orphan when the monotonic timestamp stored in
+ * the lock is older than this. Legacy locks with no stamp still use wall
+ * mtime, which a clock step can age out. The critical section only renames
+ * and writes a few files, so a live holder past this window is stuck.
+ */
+export declare const START_GATE_LOCK_ORPHAN_MS = 60000;
+export interface StartGateDeps {
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    /** Returns file contents, or null when unreadable. */
+    readFile?: (path: string) => string | null;
+    cpuCount?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+    log?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    /** Hub/task text. Errors are swallowed so a report failure cannot block a start. */
+    report?: (text: string) => void;
+    /** Host lease directory. Tests must inject this; the default is ~/.anet/run/start-slots. */
+    slotsDir?: string;
+    /** Lease key. Alias is not unique across workspaces; pass the node id. */
+    nodeId?: string;
+    /** Pid written into the lease. Default: this process. */
+    holderPid?: number;
+    /** ESRCH = dead, EPERM = alive. Injected so tests never signal a real pid. */
+    isPidAlive?: (pid: number) => boolean;
+    /** /proc/<pid>/stat field 22. null means unknown — do not treat that as a mismatch. */
+    readProcessStartTicks?: (pid: number) => string | null;
+    /** Override the 15s re-check. With jitterMs 0 the single-lane retry uses this as-is. */
+    recheckMs?: number;
+    /** Override the 0–5s jitter span. 0 keeps the sleep exactly recheckMs. */
+    jitterMs?: number;
+    /** Lease lifetime. Default 10 minutes, or ANET_START_LEASE_TTL_SEC. */
+    leaseTtlMs?: number;
+    /** @internal deterministic short-TTL seam. Defaults to min(30s, TTL/3). */
+    leaseHeartbeatMs?: number;
+    /** Empty/unreadable locks younger than this are held, not dead. */
+    lockStaleMs?: number;
+    /** A live matching lock older than this is an orphan. Default 60s. */
+    lockOrphanMs?: number;
+    /**
+     * Monotonic milliseconds shared by every process on this host.
+     * Default reads /proc/uptime. null means unknown: a stamped lock is kept.
+     */
+    monotonicNow?: () => number | null;
+}
+export type StartGateOutcome = "disabled" | "unsupported" | "ok" | "waited" | "single-lane";
+export interface StartGateResult {
+    outcome: StartGateOutcome;
+    waitedMs: number;
+    checks: number;
+    /** Always callable and idempotent. Drops the lease only if this call created it. */
+    release: () => void;
+}
+export interface HostSample {
+    /** Effective free MiB: min(MemAvailable, cgroup free) when a real cgroup limit exists. */
+    memAvailableMb: number;
+    /** /proc MemAvailable, before the cgroup min. */
+    procAvailableMb: number;
+    /** Cgroup free MiB, or null when there is no real limit. */
+    cgroupFreeMb: number | null;
+    /** Cgroup limit MiB, or null when there is no real limit. The floor uses this, not the host alone. */
+    cgroupLimitMb: number | null;
+    /** 0 when MemTotal could not be read (the floor then falls back to 4096). */
+    memTotalMb: number;
+    load1: number;
+    cpuCount: number;
+}
+export interface StartGateStatusSnapshot {
+    status: string;
+    task?: string;
+}
+/** True only for blocked text owned by this gate, including single-lane wait. */
+export declare function isStartGateBlockedStatus(task: string | undefined): boolean;
+/**
+ * Once admission returns, restore the pre-gate status only if the live status
+ * is still ours. A concurrent task/status update must win over stale restore.
+ */
+export declare function startGateStatusToRestore(live: StartGateStatusSnapshot, previous: StartGateStatusSnapshot): StartGateStatusSnapshot | null;
+/** MemAvailable in MiB from /proc/meminfo text, or null. */
+export declare function parseMemAvailableMb(meminfo: string): number | null;
+/** MemTotal in MiB from /proc/meminfo text, or null. */
+export declare function parseMemTotalMb(meminfo: string): number | null;
+/** 1-minute load average from /proc/loadavg text, or null. */
+export declare function parseLoad1(loadavg: string): number | null;
+/**
+ * Field 22 of /proc/<pid>/stat (starttime, clock ticks since boot).
+ * The comm field is in parentheses and may contain spaces; everything after the
+ * last ")" is field 3 onward, so field 22 is index 19 of that tail.
+ */
+export declare function parseProcStartTicks(statText: string): string | null;
+/**
+ * Default free-memory floor. A fixed 4 GiB is too high for a small machine
+ * or a small container, so the floor is min(4 GiB, 15% of the effective total).
+ * The effective total is min(MemTotal, cgroup limit) when a real cgroup limit
+ * exists — a container must not be judged against the host's MemTotal.
+ * Missing/invalid numbers fall back to 4 GiB. ANET_START_MIN_MEM_MB replaces
+ * this when set.
+ */
+export declare function defaultStartMinMemMb(memTotalMb: number, cgroupLimitMb?: number | null): number;
+/** Reasons the host is too busy to start, empty when it is fine. */
+export declare function startGateReasons(s: HostSample, minMemMb: number, maxLoadPerCpu: number): string[];
+/** User-facing blocked status. Keep this structured instead of parsing the diagnostic reasons. */
+export declare function startGateWaitingStatus(s: HostSample | null, minMemMb: number, maxLoadPerCpu: number): string | null;
+/**
+ * Free MiB inside a real cgroup limit, or null when the limit is missing/unlimited.
+ * `memory.current` counts page cache; inactive_file (v1: total_inactive_file) is subtracted.
+ * statText null keeps the old arithmetic so existing fixtures stay valid.
+ */
+export declare function cgroupFreeMb(maxText: string, currentText: string, memTotalMb: number, statText?: string | null, v1?: boolean): number | null;
+/** Real cgroup limit in MiB, or null when the limit is missing/unlimited. */
+export declare function cgroupLimitMb(maxText: string, memTotalMb: number): number | null;
+/**
+ * Block until this host may start one heavy process.
+ * Returns a release() the caller must invoke once that process is up or has failed.
+ * Never throws (except when the injected sleep rejects — tests use that to stop a wait).
+ */
+export declare function waitForStartResources(label: string, deps?: StartGateDeps): Promise<StartGateResult>;
+/** Run `fn` while holding one start lease. Release runs on success and on failure. */
+export declare function withHeavyStartAdmission<T>(label: string, deps: StartGateDeps, fn: () => Promise<T>): Promise<T>;

package/dist/src/stopped-receipt.d.ts

@@ -0,0 +1,8 @@
+/** Capture BEFORE asynchronous manual start. Successful start supersedes only
+ * this exact receipt, without unlinking it: check-then-unlink would race another
+ * process writing a new stop. A late certificate can never supersede that new
+ * receipt, even if its JSON is identical (inode/ctime are part of identity). */
+export declare function stoppedReceiptAtStart(nodeDir: string, nodeId: unknown): () => void;
+/** Missing stop => runnable. Unreadable/unsafe/legacy stop => stay stopped.
+ * Keep the fleet boot probe's wire format in sync (Docker parity test). */
+export declare function isHubStopped(nodeDir: string, nodeId: unknown): boolean;

package/dist/src/subcommand-redirect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `anet daemon <sub>` 认不出子命令时，原先只走 `suggestSimilar`，而它的候选集
+ * 是 `["init","start","restart","up","list"]` —— **全是会改变状态的命令**。
+ *
+ * 🔴 实测（用仓里那个 `suggestSimilar` 本身跑的，不是推的）：
+ *
+ *      anet daemon rm     → 建议 "up"      想删,被指去「创建 + 启动」
+ *      anet daemon state  → 建议 "start"   想看状态,被指去「启动」
+ *      anet daemon stat   → 建议 "start"   同上
+ *      anet daemon stop   → 建议 null      (levenshtein("stop","start") = 3)
+ *
+ * 一个「你是不是想 X」的提示，把只读/销毁意图导向一个会动世界的命令，
+ * 比不给提示更贵。
+ *
+ * 而这些动作**本来就有**：daemon 就是一个 role=host_supervisor 的 agent-node，
+ * `anet daemon restart` 内部调的正是 `anet node stop` 用的那个 stopCommand()。
+ * 缺的从来不是功能，是**可发现性**。
+ */
+/** 这些是 `anet daemon` 自己的子命令 —— 它们**会改变状态**，所以任何
+ *  只读/销毁意图都不该被导向它们。测试用它做对照。 */
+export declare const DAEMON_STATE_CHANGING: readonly ["init", "start", "restart", "up"];
+export declare const PROJECT_STATE_CHANGING: readonly ["up", "restart"];
+export declare const NODE_STATE_CHANGING: readonly ["create", "start", "restart", "resume", "rename", "loop"];
+export declare const daemonSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;
+export declare const projectSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;
+export declare const nodeSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;

package/dist/src/task-trace.d.ts

@@ -0,0 +1,33 @@
+export type TaskTraceTransport = "mcp_http" | "sdk_mcp_proxy" | "channel_mcp_proxy";
+export type TaskTraceStatus = "sending" | "delivered" | "failed" | "acked" | "started" | "replied" | "expired";
+export interface TaskTraceEvent {
+    event: string;
+    from_alias: string;
+    to_alias: string;
+    task_id: string | null;
+    parent_task_id: string | null;
+    network_id: string | null;
+    transport: TaskTraceTransport;
+    status: TaskTraceStatus;
+    duration_ms: number;
+    lifecycle_tracking: "tracked" | "not_tracked";
+    error_code?: string;
+    error_message?: string;
+}
+export declare function safeTaskTraceError(value: unknown): string;
+export declare function renderTaskTrace(event: TaskTraceEvent, json?: boolean): string;
+export declare function taskTraceEvent(input: Omit<TaskTraceEvent, "event">): TaskTraceEvent;
+export interface SendTaskTraceInput {
+    fromAlias: string;
+    toAlias: string;
+    parentTaskId: string | null;
+    networkId: string | null;
+    transport: TaskTraceTransport;
+    lifecycleTracking: "tracked" | "not_tracked";
+}
+export interface SendTaskTraceDependencies {
+    send: () => Promise<any>;
+    log: (line: string) => void;
+    now?: () => number;
+}
+export declare function sendTaskWithTrace(input: SendTaskTraceInput, dependencies: SendTaskTraceDependencies): Promise<any>;

package/dist/src/tmux-attach.d.ts

@@ -0,0 +1,11 @@
+export type TmuxSession = {
+    id: string;
+    name: string;
+};
+/** argv for `execTmux`: `-u list-sessions -F '#{session_id}|ANETSEP|#{session_name}'` (#533). */
+export declare const SESSION_LIST_ARGS: readonly string[];
+/** Parse SESSION_LIST_ARGS output (legacy `id\tname` rows still accepted). */
+export declare function parseTmuxSessions(output: string): TmuxSession[];
+/** Resolve by exact decoded session name, then attach by tmux's opaque ID.
+ * This avoids tmux target prefix matching and works for Unicode names. */
+export declare function findExactTmuxSession(output: string, expectedName: string): TmuxSession | null;