@sleep2agi/agent-network 2.3.0-preview.13 → 2.3.0-preview.131

package/dist/src/codex-lifecycle-preflight.d.ts

@@ -0,0 +1,77 @@
+import type { ReceiptCheck } from "./codex-lifecycle-receipt";
+export interface RolloutFact {
+    readonly path: string;
+    readonly inode: number | bigint;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+}
+export interface ProcessFact {
+    readonly pid: number;
+    readonly cwd: string | null;
+    /** 子进程实际环境里的 CODEX_HOME(不是 wrapper 继承的那份 —— wrapper 环境不能作承重证据)。 */
+    readonly codexHome: string | null;
+    /** 子进程实际环境里 CommHub token 的短指纹;null = 没读到或该进程不该持有。 */
+    readonly tokenFingerprint: string | null;
+    /** 子进程环境里的 ANET_NODE_MARKER(copresence-identity 的身份 uuid);null = 没有。 */
+    readonly markerUuid: string | null;
+    readonly argv: readonly string[];
+}
+export interface PreflightFacts {
+    readonly alias: string;
+    readonly configNodeId: string | null;
+    /** hub 名册按 alias 精确查到的 node_id;null = hub 不可达或没这个 alias。 */
+    readonly hubNodeId: string | null;
+    readonly home: {
+        readonly dir: string;
+        readonly dirMode: number | null;
+        readonly authMode: number | null;
+        readonly authBytes: number | null;
+        readonly configTokenFingerprint: string | null;
+        readonly envFileTokenFingerprint: string | null;
+    };
+    readonly workdir: {
+        readonly configProjectDir: string | null;
+        readonly tuiCwd: string | null;
+        readonly tuiArgvDir: string | null;
+        readonly bridgeProjectDir: string | null;
+        readonly statusBarDir: string | null;
+    };
+    readonly session: {
+        readonly threadId: string | null;
+        /** CODEX_HOME 里文件名以 <threadId>.jsonl 结尾的 rollout 全集。 */
+        readonly rolloutMatches: readonly RolloutFact[];
+    };
+    readonly port: {
+        readonly port: number | null;
+        readonly owner: ProcessFact | null;
+    };
+    readonly topology: {
+        /** copresence-identity.json 里的身份 uuid;null = 没有 marker 文件。 */
+        readonly markerUuid: string | null;
+        /** marker 里记的 pid(采集时的观测提示,**不是**身份来源)与现在 tmux pane 的 pid。 */
+        readonly recorded: Readonly<Record<"appsrv" | "bridge" | "tui", number | null>>;
+        readonly live: Readonly<Record<"appsrv" | "bridge" | "tui", number | null>>;
+        /** 每个 tmux 段下带环境的子进程各自的 ANET_NODE_MARKER。 */
+        readonly liveMarkers: Readonly<Record<"appsrv" | "bridge" | "tui", readonly (string | null)[]>>;
+        /** 每个 tmux 段下带环境的子进程各自的 CODEX_HOME(realpath)。 */
+        readonly liveHomes: Readonly<Record<"appsrv" | "bridge" | "tui", readonly (string | null)[]>>;
+    };
+    readonly goal: {
+        readonly state: "active" | "stalled" | "paused" | "achieved" | "none" | "unknown";
+    };
+    readonly children: readonly ProcessFact[];
+    readonly expectedTokenFingerprint: string | null;
+}
+export declare function checkIdentity(f: PreflightFacts): ReceiptCheck;
+export declare function checkHome(f: PreflightFacts): ReceiptCheck;
+export declare function checkWorkdir(f: PreflightFacts): ReceiptCheck;
+export declare function checkSession(f: PreflightFacts): ReceiptCheck;
+export declare function rolloutSnapshot(f: PreflightFacts): ReceiptCheck;
+export declare function compareRollout(before: RolloutFact, after: RolloutFact | null): ReceiptCheck;
+export declare function checkPortOwner(f: PreflightFacts): ReceiptCheck;
+export declare function checkChildEnv(f: PreflightFacts): ReceiptCheck;
+export declare function checkGoalState(f: PreflightFacts): ReceiptCheck;
+export declare function checkTopology(f: PreflightFacts): ReceiptCheck;
+export declare function evaluateCodexPreflight(f: PreflightFacts): ReceiptCheck[];
+/** verify = preflight + 子进程环境 + 跨节点身份验收(identity_attested 由调用方注入;PR-A 里没有探针时给 unknown)。 */
+export declare function evaluateCodexVerify(f: PreflightFacts, identityAttested: ReceiptCheck): ReceiptCheck[];

package/dist/src/codex-lifecycle-receipt.d.ts

@@ -0,0 +1,44 @@
+export type CheckStatus = "pass" | "fail" | "unknown";
+export interface ReceiptCheck {
+    readonly key: string;
+    readonly status: CheckStatus;
+    /** 一句人话:pass 说核到了什么,fail 说差在哪,unknown 说为什么量不到。 */
+    readonly detail: string;
+    /** 可复核的证据(路径、inode、字节数、短指纹……);不得含凭据。 */
+    readonly evidence?: Readonly<Record<string, unknown>>;
+}
+export type LifecycleVerb = "preflight" | "verify" | "start" | "restart" | "resume" | "fork" | "account-install" | "rollback";
+export interface LifecycleReceipt {
+    readonly format: "anet-codex-lifecycle-receipt/1";
+    readonly id: string;
+    readonly verb: LifecycleVerb;
+    readonly alias: string;
+    readonly nodeId: string | null;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly verdict: "PASS" | "FAIL";
+    /** FAIL 时阻塞的 check key(fail 与 unknown 都算)。 */
+    readonly blocking: readonly string[];
+    readonly checks: readonly ReceiptCheck[];
+}
+/** 每个动词要求哪些 check 必须 pass。preflight 只读,不要求 identity_attested(那是 verify 的活)。 */
+export declare const REQUIRED_CHECKS: Readonly<Record<LifecycleVerb, readonly string[]>>;
+export declare function shortFingerprint(value: string | undefined | null, length?: number): string | null;
+export declare function redactReceipt<T>(value: T, key?: string): T;
+export declare const INFORMATIONAL_PREFIXES: readonly string[];
+export declare function receiptVerdict(verb: LifecycleVerb, checks: readonly ReceiptCheck[]): {
+    verdict: "PASS" | "FAIL";
+    blocking: string[];
+};
+export declare function buildReceipt(opts: {
+    verb: LifecycleVerb;
+    alias: string;
+    nodeId: string | null;
+    startedAt: Date;
+    finishedAt?: Date;
+    checks: readonly ReceiptCheck[];
+}): LifecycleReceipt;
+/** receipts 落在节点目录下 receipts/<id>.json,0600,先写临时文件再 rename(原子)。返回绝对路径。 */
+export declare function writeReceipt(nodeDir: string, receipt: LifecycleReceipt): string;
+/** 终端摘要:一行一 check,PASS/FAIL 在最后;不打印 evidence 里的长值。 */
+export declare function formatReceiptSummary(receipt: LifecycleReceipt): string;

package/dist/src/codex-lifecycle-restart.d.ts

@@ -0,0 +1,86 @@
+/**
+ * #1856 PR-B — `anet node codex start|restart|resume` 的确定性状态机。
+ *
+ * 零 LLM:每一步是「读事实 → 判 → 动作 → 写 receipt check」,顺序固定;所有副作用都经 `RestartActions`
+ * 注入,所以这个文件可以在纯单测里跑完整个流程(含失败与回滚分支)。
+ *
+ * 停:Bridge → TUI → App Server(反向于依赖:先断任务入口,再让 TUI 把 rollout 刷完,最后放掉端口)。
+ * 起:交给 `anet node start <alias> --copresence --tui-first`(App Server → 端口就绪 → exact-session
+ *     TUI 完全恢复 → Bridge),再用 preflight/verify 复核 —— 起的顺序由启动器保证,这里只验证结果。
+ * 任一步 fail → 不再往下;若已停掉进程则尝试一次「回滚」= 按原配置再起一次;仍失败就留在已停状态,
+ * receipt 记录到哪一步、为什么,exit 2。绝不猜、绝不 fallback 到别的线程。
+ */
+import type { ReceiptCheck } from "./codex-lifecycle-receipt.js";
+import type { RolloutFact } from "./codex-lifecycle-preflight.js";
+export type RestartVerb = "start" | "restart" | "resume";
+export type GoalState = "active" | "paused" | "stalled" | "achieved" | "none" | "unknown";
+export type CopresenceRole = "bridge" | "tui" | "appsrv";
+export interface GateResult {
+    /** 该阶段所有 check(preflight 或 verify 的输出)。 */
+    readonly checks: readonly ReceiptCheck[];
+    /** 该阶段 rollout 快照(session_exact 通过时才有)。 */
+    readonly rollout: RolloutFact | null;
+    /** 端口占用者(null = 空闲)。 */
+    readonly port: {
+        readonly port: number | null;
+        readonly ownerPid: number | null;
+        readonly ownerIsOurs: boolean | null;
+    };
+}
+export interface RestartActions {
+    /** 只读核对(PR-A 的 preflight;`after` 阶段可带 identity_attested 变 verify)。 */
+    gate(phase: "before" | "after"): Promise<GateResult>;
+    /** goals.json 的状态摘要 + 内容指纹(unknown = 读不到/不认识的 schema)。 */
+    goalState(): Promise<{
+        state: GoalState;
+        fingerprint: string | null;
+    }>;
+    /** 三个 tmux 会话谁还活着。 */
+    liveSessions(): Promise<Readonly<Record<CopresenceRole, boolean>>>;
+    /** 杀掉一个角色的 tmux 会话并等它消失;ok=false 时 detail 说为什么。 */
+    stopSession(role: CopresenceRole): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** 等 rollout 文件字节数稳定(TUI 退出后大 rollout 还在刷盘);返回最终快照。 */
+    waitRolloutSettled(before: RolloutFact | null): Promise<RolloutFact | null>;
+    /** 等端口空闲;超时仍被占用时给出占用者 pid 与「是不是我们自己的 app-server」。 */
+    waitPortFree(): Promise<{
+        free: boolean;
+        ownerPid: number | null;
+        ownerIsOurs: boolean | null;
+    }>;
+    /** 对已核实属于本节点的残留 pid 发 TERM(定向,绝不 pkill -f)。 */
+    termOwnedPid(pid: number): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** 跑启动器(`anet node start --copresence --tui-first`);ok=false 时 detail 是它的尾部输出。 */
+    start(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** hub 上该 node_id 是否在超时内回到 online/idle。 */
+    waitHubOnline(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** 跨节点 nonce 探针;未配置时返回 undefined(check 记 unknown)。 */
+    nonceProbe?: () => Promise<{
+        ok: boolean;
+        detail: string;
+        evidence?: Record<string, unknown>;
+    }>;
+}
+export interface RestartOutcome {
+    readonly verb: RestartVerb;
+    readonly checks: readonly ReceiptCheck[];
+    /** 走到哪一步停下(PASS 时 = "done")。 */
+    readonly stoppedAt: string;
+    readonly rolledBack: boolean;
+}
+/** before 阶段的门:required 里不许有 fail;unknown 允许(要重启的节点常常就是缺了一截进程)。 */
+export declare function beforeGateBlocks(checks: readonly ReceiptCheck[]): string[];
+/** 三个角色按依赖反向停;返回 stop_order check(顺序本身就是证据)。 */
+export declare function orderedStop(actions: RestartActions, live: Readonly<Record<CopresenceRole, boolean>>): Promise<ReceiptCheck>;
+export declare function runCodexRestart(verb: RestartVerb, actions: RestartActions): Promise<RestartOutcome>;

package/dist/src/codex-login-share-guard.d.ts

@@ -0,0 +1,146 @@
+/** The explicit, documented-as-unsafe override. Spelled once so help, messages and tests agree. */
+export declare const ALLOW_SHARED_CODEX_LOGIN_FLAG = "--allow-shared-codex-login";
+/** Per-node record of where the node's codex credential came from. */
+export declare const CODEX_AUTH_ORIGIN_FILE = ".codex-auth-origin.json";
+/** Host-index filename for a node's origin record: same directory-derived key as
+ *  #1918's record, different suffix, so neither overwrites the other. */
+export declare function codexOriginIndexFile(nodeDir: string): string;
+export type CodexLoginSource = {
+    kind: "host";
+    path: string;
+} | {
+    kind: "fork";
+    sourceAlias: string;
+} | {
+    kind: "account";
+    profileId: string;
+};
+export interface CodexLoginHolder {
+    readonly alias: string;
+    /** Canonical node directory — the identity. */
+    readonly nodeDir: string;
+    /** "current": its last published fingerprint; "origin": the credential it was given. */
+    readonly via: "current" | "origin";
+}
+/**
+ * Fingerprint of an auth.json on disk, or null when there is none or it carries
+ * no refresh token (an API-key login does not rotate, so sharing it is not this
+ * failure). The text is hashed and dropped; nothing here returns or logs it.
+ */
+export declare function codexLoginFingerprintOfFile(authJsonPath: string): string | null;
+export interface FindHoldersOptions {
+    readonly fingerprint: string;
+    /** The node being given the credential — excluded from the result. */
+    readonly selfNodeDir: string;
+    /** Injected for tests; production uses the host index under ~/.anet. */
+    readonly indexDir?: string;
+    /** `.anet/nodes` roots to scan besides the host index. Default: the parent of selfNodeDir. */
+    readonly siblingRoots?: readonly string[];
+}
+/**
+ * Every OTHER node on this host whose published fingerprint, or recorded
+ * credential origin, equals `fingerprint`. Read-only: it never deletes, never
+ * writes, and never opens another node's auth.json.
+ *
+ * A record whose node directory no longer exists describes a node that is
+ * gone and is ignored (#1918's liveness rule: existence, not age).
+ */
+export declare function findCodexLoginHolders(opts: FindHoldersOptions): CodexLoginHolder[];
+export interface StagingDecisionInput {
+    /** The node that would receive the credential. */
+    readonly alias: string;
+    /** Its codex-home — named in the fix instruction. */
+    readonly targetCodexHome: string;
+    /** Fingerprint of the credential about to be handed over; null = not a rotating login. */
+    readonly fingerprint: string | null;
+    readonly holders: readonly CodexLoginHolder[];
+    readonly source: CodexLoginSource;
+    readonly allowShared: boolean;
+    /** Extra "how to fix" line for this command (e.g. fork's --no-codex-login). */
+    readonly extraFix?: readonly string[];
+}
+export type StagingDecision = {
+    readonly kind: "ok";
+    readonly lines: string[];
+} | {
+    readonly kind: "refuse";
+    readonly lines: string[];
+} | {
+    readonly kind: "override";
+    readonly lines: string[];
+};
+/**
+ * Decide whether handing this credential to this node is allowed, and the exact
+ * text to print. Pure — the callers own the I/O and the exit code (1, per #2321).
+ */
+export declare function decideCodexLoginStaging(i: StagingDecisionInput): StagingDecision;
+export interface RecordOriginOptions {
+    readonly nodeDir: string;
+    readonly alias: string;
+    readonly fingerprint: string;
+    readonly source: CodexLoginSource;
+    readonly indexDir?: string;
+    readonly now?: Date;
+}
+/**
+ * Record which credential a node was handed (8-hex fingerprint + where from).
+ * Best effort: a failure is returned as a message, never thrown — a node must
+ * not fail to start because bookkeeping failed.
+ */
+export declare function recordCodexLoginOrigin(o: RecordOriginOptions): string | null;
+export interface SharedLoginGroup {
+    /** 8-hex refresh fingerprint — not a credential. */
+    readonly fingerprint: string;
+    readonly aliases: string[];
+}
+/**
+ * For `anet doctor`: groups of ≥2 live nodes whose CURRENT published
+ * fingerprint is the same. Read-only; aliases only.
+ */
+export declare function sharedCodexLoginGroups(opts?: {
+    indexDir?: string;
+    nodeRoots?: readonly string[];
+}): SharedLoginGroup[];
+export interface EvaluateStagingOptions {
+    /** The node that would receive the credential (may not exist yet, e.g. a fork target). */
+    readonly nodeDir: string;
+    readonly alias: string;
+    readonly targetCodexHome: string;
+    /** The auth.json about to be copied. Read only to hash it. */
+    readonly sourceAuthPath: string;
+    readonly source: CodexLoginSource;
+    readonly allowShared: boolean;
+    readonly extraFix?: readonly string[];
+    /** Holders known without any record — a fork's source node always holds its own login. */
+    readonly knownHolders?: readonly CodexLoginHolder[];
+    readonly indexDir?: string;
+    readonly siblingRoots?: readonly string[];
+}
+export type EvaluatedStaging = StagingDecision & {
+    readonly fingerprint: string | null;
+    readonly holders: readonly CodexLoginHolder[];
+};
+/**
+ * Fingerprint → holders → decision, in one call, for every staging path.
+ * Writes nothing; the caller records the origin once the credential has
+ * actually been handed over (see recordCodexLoginOrigin).
+ */
+export declare function evaluateCodexLoginStaging(o: EvaluateStagingOptions): EvaluatedStaging;
+/**
+ * `anet node codex fork --no-codex-login` deliberately leaves the target without
+ * a credential, and home_isolated would fail on exactly that. The caller runs
+ * the real check with the credential treated as present (so every OTHER rule —
+ * directory mode, CommHub token, env-file token — is still evaluated) and passes
+ * the result here: a pass is re-worded to say what is still owed, a failure
+ * stays the failure it is.
+ */
+export declare function homeCheckPendingOwnLogin<C extends {
+    status: string;
+    detail: string;
+}>(checkAssumingLogin: C, codexHome: string): C;
+/** The step of a host stage plan that newly hands a node a login: auth.json where the node has none.
+ *  A "host-newer" re-stage is an existing node and is not gated (it still gets the #1918 warning). */
+export declare function newLoginStep<T extends {
+    name: string;
+    reason: string;
+}>(plan: readonly T[]): T | undefined;

package/dist/src/codex-model-default.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_CODEX_MODEL = "gpt-5.6-sol";
+export declare const CODEX_MODEL_CHOICES: ReadonlyArray<{
+    readonly id: string;
+    readonly default?: boolean;
+}>;
+export declare function defaultCodexModelForRuntime(runtime: string): string | undefined;

package/dist/src/codex-tui-client-health.d.ts

@@ -0,0 +1,30 @@
+export declare function bridgeClientHealthReceipt(remote: string, threadId: string): string;
+export interface MigratedCodexPendingThread {
+    version: 1;
+    threadId: string;
+    serverUrl: string;
+    marker: string;
+}
+/**
+ * Move a crash-window deferred candidate onto the launcher's new owned
+ * app-server generation. The old URL is an authority supplied by the same
+ * private node config, not by the pending object itself; every mismatch is a
+ * hard stop so restart never guesses or adopts a second thread.
+ */
+export declare function migrateCodexPendingThread(value: unknown, oldServerUrl: unknown, expectedOldMarker: unknown, newServerUrl: string, newMarker: string): MigratedCodexPendingThread;
+export declare function requirePromotedCodexPendingThread(value: unknown, pendingThreadId: string): string;
+/**
+ * argv for the human TUI attached to the co-presence app-server.
+ *
+ * #505 — the permission override is only passed on the FRESH path. On
+ * `resume --remote <ws> <thread>` codex 0.155.1 exits immediately with
+ *   "Error: Permission overrides are not supported when resuming a remote task."
+ * (anet then reports "TUI tmux session exited during startup"). Measured in
+ * Docker against a real app-server + real thread: 0.155.1 rejects
+ * resume + --dangerously-bypass-approvals-and-sandbox and accepts it fresh
+ * (TUI up, "permissions: YOLO mode"); 0.133.0 (agent-node's pin) accepts both.
+ * Nothing is lost by dropping it on resume: the app-server itself is started
+ * with `-c approval_policy=… -c sandbox_mode=…` from the same posture.
+ */
+export declare function codexTuiLaunchArgs(remote: string, model: string, threadId?: string, dangerFullAccess?: boolean): string[];
+export declare function assertPendingServerQuiesced(serverUrl: unknown, isListening: (port: number) => boolean | Promise<boolean>): Promise<void>;

package/dist/src/commhub-response.d.ts

@@ -0,0 +1 @@
+export declare function parseCommhubToolResult(json: any): any;

package/dist/src/controlled-upload.d.ts

@@ -0,0 +1,83 @@
+/**
+ * #693 — token-bound node controlled local file → Hub /api/upload bridge.
+ *
+ * Security boundary (hard gates):
+ *  1. Cross-host: bytes travel over HTTP multipart; Hub never reads agent FS.
+ *  2. Identity: caller supplies the node's bearer token; ntok binds network.
+ *  3. Path safety: realpath + allowlisted roots; reject NUL, symlink, traversal.
+ *  4. Size ≤ 12 MiB enforced with same-fd fstat + bounded read (no full slurp).
+ *  5. Hub /api/upload is the sole write surface (atomic on hub side).
+ *
+ * Adversarial add-only (#694 DO-NOT-MERGE fixes):
+ *  - TOCTOU: open O_NOFOLLOW → fstat(fd) → read(fd) only; no re-open by path.
+ *  - Bounded read: never allocate/read past CONTROLLED_UPLOAD_MAX_BYTES.
+ *  - NUL guard is live and reachable before any fs call.
+ */
+/** Mirrors server/src/uploads.ts MAX_UPLOAD_BYTES. */
+export declare const CONTROLLED_UPLOAD_MAX_BYTES: number;
+/** Chunk size for bounded streaming read from a single fd. */
+export declare const CONTROLLED_UPLOAD_READ_CHUNK: number;
+export type ControlledUploadErrorCode = "path_required" | "path_nul" | "path_not_found" | "path_untrusted" | "path_symlink" | "path_not_regular" | "path_empty" | "payload_too_large" | "read_failed" | "auth_required" | "hub_url_required" | "upload_failed" | "bad_response" | "missing_file_id";
+export type ControlledUploadFail = {
+    ok: false;
+    error: ControlledUploadErrorCode;
+    message: string;
+};
+export type ControlledUploadOk = {
+    ok: true;
+    file_id: string;
+    name: string;
+    mime: string;
+    size: number;
+    url?: string;
+};
+export type ControlledUploadResult = ControlledUploadOk | ControlledUploadFail;
+export interface ControlledUploadDeps {
+    hubUrl: string;
+    authToken: string;
+    allowedRoots?: string[];
+    alias?: string;
+    nodeDir?: string;
+    fetch?: typeof fetch;
+    home?: string;
+}
+/** Normalize a client filename: basename only, strip controls, cap 255. */
+export declare function normalizeUploadName(input: string | undefined | null, fallback?: string): string;
+export declare function defaultControlledUploadRoots(opts?: {
+    home?: string;
+    alias?: string;
+    nodeDir?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): string[];
+/** True iff canonicalPath is strictly inside one of the allowlisted roots. */
+export declare function isPathInsideAllowedRoots(canonicalPath: string, allowedRoots: string[]): boolean;
+/**
+ * Resolve a user-supplied path to a canonical path under an allowlisted root.
+ * Does not open the file for reading — open+fstat+read is a separate same-fd step.
+ */
+export declare function resolveControlledUploadPath(rawPath: string, allowedRoots: string[]): {
+    ok: true;
+    canonicalPath: string;
+} | ControlledUploadFail;
+export type ControlledFileBytes = {
+    ok: true;
+    bytes: Buffer;
+    size: number;
+    canonicalPath: string;
+} | ControlledUploadFail;
+/**
+ * Open → fstat(fd) → bounded read(fd) on the **same fd** (TOCTOU hard gate).
+ * Uses O_NOFOLLOW when available so a symlink swap at open is rejected.
+ * Never uses path-based readFileSync after the initial open.
+ */
+export declare function openFstatBoundedReadControlledFile(canonicalPath: string, allowedRoots: string[], maxBytes?: number): ControlledFileBytes;
+/**
+ * Upload a controlled local file to Hub POST /api/upload.
+ * Returns file_id + metadata for send_reply attachments.
+ * Never falls back to sending a raw path to the Hub.
+ */
+export declare function uploadControlledLocalFile(rawPath: string, deps: ControlledUploadDeps, opts?: {
+    name?: string;
+    mime?: string;
+}): Promise<ControlledUploadResult>;

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

@@ -0,0 +1,22 @@
+export interface CopresenceDep {
+    readonly name: string;
+    readonly present: boolean;
+    /** Exact command for this platform, or null when we cannot name one. */
+    readonly install: string | null;
+    readonly why: string;
+}
+export type CommandProbe = (cmd: string) => boolean;
+/** Which agent binary this co-presence lane is built on. */
+export type CopresenceAgent = "codex" | "grok";
+export declare function copresenceDeps(probe: CommandProbe, platform?: NodeJS.Platform, agent?: CopresenceAgent): CopresenceDep[];
+export declare function missingCopresenceDeps(probe: CommandProbe, platform?: NodeJS.Platform, agent?: CopresenceAgent): CopresenceDep[];
+/** One block naming every gap and how to close it — never one gap at a time. */
+export declare function describeMissingDeps(missing: readonly CopresenceDep[], displayName: string): string;
+/**
+ * May we start this hub ourselves?
+ *
+ * Only a loopback hub. A remote URL that refuses the connection is somebody
+ * else's service — spawning a local one would silently point the node at a
+ * DIFFERENT hub than its profile names, which is worse than failing.
+ */
+export declare function isLoopbackHub(hubUrl: string): boolean;