@sleep2agi/agent-network 2.3.0-preview.4 → 2.3.0-preview.41

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/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,115 @@
+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;
+}
+export type GrokAttachClientFrame = GrokAttachInputFrame | GrokAttachResizeFrame | 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;
+}
+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;

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