@sleep2agi/agent-network 2.3.0-preview.7 → 2.3.0-preview.71

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

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

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

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

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

@@ -0,0 +1,58 @@
+/** hub `/api/host-supervisors` 里与本主题相关的那几格。全部可缺席。 */
+export type DaemonCapabilityRow = {
+    readonly alias?: string;
+    readonly online?: boolean;
+    /** hub 侧的最后一次心跳(ISO 串或 epoch ms)。缺席则年龄无法计算。 */
+    readonly last_seen_at?: string | number | null;
+    readonly can_create_nodes?: boolean;
+    readonly create_nodes_blocked_reason?: string;
+    /** #1545 —— 上面那一格是**这份 report 发出前多少毫秒**测的。 */
+    readonly create_capability_observed_ms_ago?: number;
+};
+export type CapabilityView = 
+/** hub 上根本没有这一格 —— 旧 daemon(preview.55 之前)不上报。 */
+{
+    readonly kind: "never-reported";
+    readonly line: string;
+}
+/** 报了 ready/blocked,且知道是多久以前测的。 */
+ | {
+    readonly kind: "ready" | "blocked";
+    readonly ageMs: number;
+    readonly line: string;
+    readonly fix?: CapabilityFix;
+}
+/** 报了 ready/blocked,但**不知道是什么时候测的**(旧 daemon 开机只算一次)。 */
+ | {
+    readonly kind: "ready-age-unknown" | "blocked-age-unknown";
+    readonly line: string;
+    readonly fix?: CapabilityFix;
+};
+/** 🔴 修法**按 code 给,不按上游的 detail 给**。
+ *
+ *  上游 `unsafePathHelp()` 生成的 `Fix:` 那半带完整机器路径,而它**按设计不上报**
+ *  (那条会一路走到 Dashboard,「哪台机器的哪个路径缺什么」本身就是一张地图)。
+ *  所以跨机器读到的只有 code,这里给的必然是**不含机器路径的通用修法**。
+ *
+ *  🔴 四类的修法完全不同,混成一句会让人修错方向 —— 2026-08-28 有人一天里撞到
+ *     其中两类,看到的是同一条错误,第一反应跑去建 /etc/anet-daemon/path.conf,
+ *     而那次实际只要 chmod。
+ *
+ *  想要**带真实路径的那一份**,只能在那台机器上看它自己的 daemon 日志 ——
+ *  下面每条都会把人指过去。 */
+export type CapabilityFix = {
+    /** 人读的一句话:这一类是什么、为什么会这样。 */
+    readonly explain: string;
+    /** 🔴 **可以整行粘进终端**的命令,或 null(这一类没有单条命令能修)。
+     *
+     *  分成两格而不是拼成一句,是因为拼起来之后**没有一条能通过 `bash -n`** ——
+     *  中文说明和括号注释会被 shell 当成语法。#1521 修过完全同一个形状:
+     *  当时 anet_bin_source 的 Fix 串 `bash -n` rc=2(`$( )` 里的 `\"` 是语法错),
+     *  用户粘进去只看到 `syntax error near unexpected token '('`。
+     *  **一条"看起来是命令"的说明,比没有命令更糟。** */
+    readonly command: string | null;
+};
+/** 把毫秒渲染成人读的相对时间。**不做四舍五入到"刚刚"** ——
+ *  这一格存在的意义就是分辨新鲜和陈旧,含糊化等于把它的功能删掉。 */
+export declare function formatAge(ms: number): string;
+export declare function describeCapability(row: DaemonCapabilityRow, nowMs: number): CapabilityView;

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

@@ -0,0 +1,9 @@
+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(preview.40 及更早)只报这一个笼统原因。升级该机器的 agent-node 后才能拿到具体类别",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 q=Math.floor(j/60);if(q<60)return`${q}m 前`;let k=Math.floor(q/60);if(k<24)return`${k}h 前`;return`${Math.floor(k/24)}d 前`}function K(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;升级它才能看到)"};let q=K(c.last_seen_at),k=c.create_capability_observed_ms_ago,u=q!==void 0&&typeof k==="number"&&Number.isFinite(k)?Math.max(0,j-q)+k:void 0;if(c.can_create_nodes){if(u===void 0)return{kind:"ready-age-unknown",line:`创建能力:可用
+`+"    ⚠ 不知道是什么时候测的 —— 该版本开机只算一次。重启它,或升级。"};return{kind:"ready",ageMs:u,line:`创建能力:可用(${G(u)}测)`}}let C=c.create_nodes_blocked_reason||"anet_bin_unknown",z=J[C]??{explain:`未知原因代码 ${C} —— 本 CLI 可能比那台机器的 anet 旧,升级本机 anet 或看它的 daemon 日志`,command:null},H=`完整原文只在那台机器的 daemon 日志里。
+    (它带真实机器路径,按设计不上报)`,D=[`    原因:${z.explain}`,z.command?`    修法(可整行粘贴):${z.command}`:"    修法:没有单条命令能修,见上。",`    ${H}`].join(`
+`);if(u===void 0)return{kind:"blocked-age-unknown",line:`创建能力:**不可用**(${C})
+    ⚠ 不知道是什么时候测的 —— 该 daemon 版本开机只算一次,之后不再重测。
+${D}`,fix:z};return{kind:"blocked",ageMs:u,line:`创建能力:**不可用**(${C},${G(u)}测)
+${D}`,fix:z}}export{G as formatAge,Q as describeCapability};

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/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-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;