@sleep2agi/agent-network 2.3.0-preview.15 → 2.3.0-preview.150

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

@@ -0,0 +1,88 @@
+/**
+ * #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 记 n/a,#535:单节点不阻塞)。 */
+    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;
+}
+/** #535 — shared with the CLI's verify/canary so every verb says the same thing. */
+export declare const SINGLE_NODE_UNATTESTED_DETAIL = "not applicable: no --probe-from <peer> given (single node) \u2014 cross-node nonce attestation skipped; pass --probe-from <alias> to attest";
+/** 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-menu.d.ts

@@ -0,0 +1,99 @@
+export type CodexKind = "co-presence" | "codex-sdk";
+export interface CodexMenuNode {
+    id: string;
+    alias: string;
+    profile: Record<string, any> | null;
+}
+export interface CodexNodeRow {
+    id: string;
+    alias: string;
+    kind: CodexKind;
+    /** "running" | "stopped" | "partial 1/3" … */
+    state: string;
+    running: boolean;
+    loggedIn: boolean;
+    /** Where the login lives: the node's own CODEX_HOME, or the host's ~/.codex. */
+    loginWhere: "node" | "host";
+    /** Absolute CODEX_HOME for `codex login`; null = codex's own default (~/.codex). */
+    codexHome: string | null;
+    threadId: string | null;
+    model: string;
+    modelIsDefault: boolean;
+}
+export interface CollectEnv {
+    nodesDir: string;
+    /** $HOME — only used to locate the host's ~/.codex/auth.json. */
+    home: string;
+    /** The environment a start would inherit (CODEX_HOME); defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** Exact tmux session names on the server anet uses (empty when none). */
+    tmuxSessions?: () => Set<string>;
+    pidAlive?: (pid: number) => boolean;
+}
+export declare function realTmuxSessions(): Set<string>;
+export declare function realPidAlive(pid: number): boolean;
+/** Only codex nodes: co-presence (codex-app-server) and codex-sdk. */
+export declare function collectCodexRows(nodes: CodexMenuNode[], env: CollectEnv): CodexNodeRow[];
+export declare function renderCodexTable(rows: CodexNodeRow[], cwd: string): string;
+export declare const CODEX_CHEAT_SHEET: string;
+export type MenuAction = "start" | "stop" | "restart" | "verify" | "login" | "continue" | "pick" | "model" | "copy" | "delete";
+export declare const MENU_ACTIONS: {
+    key: MenuAction;
+    label: string;
+}[];
+export interface PlannedCommand {
+    /** argv[0] is "anet" (re-invoke this CLI) or "codex". */
+    argv: string[];
+    /** Extra env for the child (only CODEX_HOME for login). */
+    env?: Record<string, string>;
+    /** Shown before the confirm prompt, after the command. */
+    note?: string;
+    /** Shown after the command succeeded. */
+    after?: string;
+}
+export declare function displayQuote(v: string): string;
+export declare function commandLine(cmd: PlannedCommand): string;
+export interface ActionInput {
+    model?: string;
+    newName?: string;
+    workdir?: string;
+}
+/** #528 — not about an existing node: turn a codex conversation started outside anet into a new one. */
+export declare const ADOPT_KEY = "a";
+export declare function planAdopt(newName: string): PlannedCommand;
+export declare function planAction(row: CodexNodeRow, action: MenuAction, input?: ActionInput): PlannedCommand;
+export interface MenuIO {
+    write(s: string): void;
+    /** Resolves to the next line, or null at end of input. */
+    readLine(prompt: string): Promise<string | null>;
+}
+export type Runner = (cmd: PlannedCommand) => Promise<number>;
+export declare function pick(io: MenuIO, prompt: string, max: number, allowAdopt?: boolean): Promise<number | "adopt" | null>;
+/** Returns the process exit code. Runs at most one command. */
+export declare function codexMenu(rows: CodexNodeRow[], io: MenuIO, run: Runner, ctx: {
+    cwd: string;
+}): Promise<number>;
+/** The action step for one codex node. #561: `anet node` (all runtimes) hands codex nodes off to this. */
+export declare function codexNodeActions(row: CodexNodeRow, io: MenuIO, run: Runner, ctx: {
+    cwd: string;
+}): Promise<number>;
+/** Ask for a model id; null (and a message) when none / not a plain id. Shared with node-menu.ts (#561). */
+export declare function askModel(io: MenuIO, current: string): Promise<string | null>;
+/**
+ * Print the exact command, then ask: y/N, or (typedName) the node's name. Run it only then.
+ * The one gate both menus go through (#532 codex, #561 every runtime).
+ */
+export declare function confirmAndRun(io: MenuIO, run: Runner, cmd: PlannedCommand, row: {
+    alias: string;
+}, typedName: boolean): Promise<number>;
+/** A line queue over one readline: scripted input that arrives in one chunk is not lost between prompts. */
+export declare function readlineIO(): MenuIO & {
+    close(): void;
+};
+export declare function realRunner(beforeRun: () => void): Runner;
+/** Entry from cli.ts (`anet node codex` with no arguments). Returns the exit code. */
+export declare function runCodexMenu(nodes: CodexMenuNode[], opts: {
+    nodesDir: string;
+    home: string;
+    cwd?: string;
+}): Promise<number>;

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-node-login.d.ts

@@ -0,0 +1,98 @@
+export type CodexLoginKind = "chatgpt" | "api-key" | "none" | "unreadable";
+export interface CodexLoginFacts {
+    readonly loggedIn: boolean;
+    readonly kind: CodexLoginKind;
+    /** #1918 refresh-chain fingerprint (8 hex) — what actually collides. */
+    readonly loginFingerprint: string | null;
+    /** #1856 account fingerprint (sha256(account_id), 16 hex). */
+    readonly accountFingerprint: string | null;
+    /** `email` claim of the id_token, when present. Not a credential. */
+    readonly email: string | null;
+}
+/** What an auth.json says about a login — without ever returning a token. */
+export declare function codexLoginFactsFromText(text: string | null): CodexLoginFacts;
+export declare function codexLoginFactsOfHome(codexHome: string): CodexLoginFacts;
+export interface NodeConfigLike {
+    runtime?: unknown;
+    codexCopresence?: unknown;
+    codexHome?: unknown;
+    env?: unknown;
+    alias?: unknown;
+    node_name?: unknown;
+    name?: unknown;
+}
+/** A node whose runtime runs codex. */
+export declare function isCodexNodeConfig(cfg: NodeConfigLike | null | undefined): boolean;
+export type EffectiveCodexHomeSource = "config.codexHome" | "node-codex-home" | "config.env" | "environment" | "default";
+/**
+ * The CODEX_HOME this node's codex process will get — the same decision
+ * `applyNodeCodexHome` makes on start: the node's own value; otherwise an
+ * inherited CODEX_HOME unless it is another node's codex-home; otherwise
+ * codex's default `~/.codex`.
+ */
+export declare function effectiveCodexHome(nodeDir: string, cfg: NodeConfigLike | null, env: Record<string, string | undefined>, home: string): {
+    codexHome: string;
+    source: EffectiveCodexHomeSource;
+};
+export interface LoginNextStepInput {
+    readonly alias: string;
+    readonly codexHome: string;
+    /** Does the codex-home directory exist yet? codex 0.133 refuses a CODEX_HOME that does not. */
+    readonly homeExists: boolean;
+    /** e.g. `anet node start <alias>`; printed as what comes after the login. */
+    readonly then?: string;
+}
+/**
+ * The one next step for a codex node without a login. Plain text, no token,
+ * nothing executed. `--device-auth` is in `codex login --help` of the pinned
+ * codex (agent-node depends on @openai/codex ^0.133; checked on 0.133.0).
+ */
+export declare function codexLoginNextStepLines(i: LoginNextStepInput): string[];
+export interface CreateLoginGapInput {
+    readonly nodeDir: string;
+    readonly config: NodeConfigLike | null;
+    readonly env: Record<string, string | undefined>;
+    readonly home: string;
+    /**
+     * For a co-presence node whose own codex-home has no login: would its first
+     * start be allowed to stage the host login (#514 gate says "ok")? Injected so
+     * this stays a pure decision; the CLI passes evaluateCodexLoginStaging.
+     */
+    readonly hostLoginWouldBeStaged: (hostAuthPath: string) => boolean;
+}
+/** null = the node will have a usable login; otherwise the CODEX_HOME to log in. */
+export declare function codexCreateLoginGap(i: CreateLoginGapInput): {
+    codexHome: string;
+    homeExists: boolean;
+} | null;
+export interface CodexLoginStatusRow {
+    alias: string;
+    node_id: string | null;
+    runtime: string;
+    copresence: boolean;
+    codex_home: string;
+    codex_home_source: EffectiveCodexHomeSource;
+    logged_in: boolean;
+    login_kind: CodexLoginKind;
+    /** #1918 refresh-chain fingerprint (8 hex). */
+    login_fingerprint: string | null;
+    /** #1856 account fingerprint (16 hex). */
+    account_fingerprint: string | null;
+    email: string | null;
+    /** Other nodes holding the SAME refresh chain — they log each other out. */
+    shared_with: string[];
+    /** Other nodes logged in to the same account with their OWN login — fine. */
+    same_account_as: string[];
+}
+export interface LoginStatusOptions {
+    /** `<workspace>/.anet/nodes` */
+    readonly nodesRoot: string;
+    readonly env: Record<string, string | undefined>;
+    readonly home: string;
+    /** Host index of published fingerprints (#1918); default under `home`. */
+    readonly indexDir?: string;
+}
+/** One row per codex node under `nodesRoot`. Read-only. */
+export declare function codexNodeLoginStatus(o: LoginStatusOptions): CodexLoginStatusRow[];
+/** Human table. Never contains a token: rows carry none. */
+export declare function formatCodexLoginStatus(rows: readonly CodexLoginStatusRow[], workspace: string): string[];

package/dist/src/codex-pending-thread-restart.d.ts

@@ -0,0 +1,55 @@
+/**
+ * #602 — what `anet node start` does with a `codexPendingThread` it finds in
+ * the node config before launching a new co-presence generation.
+ *
+ * The candidate is written by the bridge when the TUI opens a thread that has
+ * not had a conversation yet (codex only writes a rollout on the first turn).
+ * It is bound to the identity marker of the generation that saw it, so a
+ * restart after a crash can carry it over to the next generation without
+ * guessing (`migrateCodexPendingThread`).
+ *
+ * A clean `anet node stop` reaps that generation and removes its marker, but
+ * the candidate stays in the config. Before #602 the next start then refused
+ * for good: "pending Codex thread is not bound to the exact private
+ * previous-generation marker" — every node whose TUI was never used could be
+ * stopped once and never started again.
+ *
+ * A candidate whose marker file is gone AND whose thread has no rollout under
+ * this node's CODEX_HOME holds nothing: codex never persisted the thread, its
+ * app-server generation is gone, and no app-server can resume it. Dropping it
+ * adopts nothing and loses nothing; the new generation starts a fresh thread
+ * exactly like a first start. Everything else keeps the old fail-closed
+ * answer — in particular a candidate whose thread HAS a rollout while the
+ * marker that bound it is gone is never adopted, because nothing proves the
+ * binding was ours.
+ */
+export type PendingThreadAtStart = {
+    kind: "none";
+} | {
+    kind: "migrate";
+    oldMarker: string;
+} | {
+    kind: "drop-unmaterialized";
+    threadId: string;
+} | {
+    kind: "refuse";
+    reason: string;
+};
+export type PendingMarkerFact = {
+    kind: "ok";
+    marker: string;
+} | {
+    kind: "missing";
+} | {
+    kind: "unreadable";
+    cause: string;
+};
+/** Rollout files for exactly this thread id (suffix match, no prefix guessing), or `null` if the search itself failed. */
+export type RolloutLookup = (threadId: string) => string[] | null;
+export declare function decidePendingThreadAtStart(pending: unknown, marker: PendingMarkerFact, rollouts: RolloutLookup): PendingThreadAtStart;
+/**
+ * Every `*-<threadId>.jsonl` under `<codexHome>/sessions` and
+ * `<codexHome>/archived_sessions`. A missing directory is "no rollouts"; any
+ * other read error makes the whole lookup `null` (the caller then refuses).
+ */
+export declare function findThreadRollouts(codexHome: string, threadId: string): string[] | null;

package/dist/src/codex-resume.d.ts

@@ -0,0 +1,89 @@
+import { type ExternalThread } from "./codex-adopt";
+import { type CollectEnv, type CodexMenuNode } from "./codex-menu";
+export type CodexResumeKind = "co-presence" | "codex-sdk";
+export interface CodexResumeFacts {
+    readonly alias: string;
+    readonly kind: CodexResumeKind;
+    /** "running" | "stopped" | "partial 1/3" (codex-menu's row.state). */
+    readonly state: string;
+    readonly running: boolean;
+    /** The CODEX_HOME the node's codex runs with (its own, or the host ~/.codex for a codex-sdk node). */
+    readonly codexHome: string;
+    readonly homeExists: boolean;
+    /** true = codex's default ~/.codex (no CODEX_HOME needed to log it in). */
+    readonly homeIsHost: boolean;
+    readonly loggedIn: boolean;
+    /** codexThreadId (co-presence) / session (codex-sdk) from the node config. */
+    readonly recordedThread: string | null;
+    /** Every rollout under `<codexHome>/sessions`, newest first. */
+    readonly threads: readonly ExternalThread[];
+}
+export interface CodexResumeRequest {
+    /** --thread <id|unique prefix> (also --session <id>, the old spelling). */
+    readonly thread?: string | null;
+    readonly pick?: boolean;
+    /** stdin and stdout are both a terminal. */
+    readonly tty: boolean;
+}
+export type CodexResumeDecision = 
+/** Nothing was done. `lines[0]` is the reason with the fix; exit with `code`. */
+{
+    readonly kind: "refuse";
+    readonly code: number;
+    readonly lines: readonly string[];
+}
+/** --pick without a terminal: the list plus a copy-paste command. Nothing was done. */
+ | {
+    readonly kind: "list";
+    readonly code: number;
+    readonly lines: readonly string[];
+}
+/** --pick in a terminal: show `lines`, ask for a number in 1..`choices.length`. */
+ | {
+    readonly kind: "ask";
+    readonly lines: readonly string[];
+    readonly choices: readonly string[];
+}
+/** Already running on exactly that thread — attach instead (exit 0). */
+ | {
+    readonly kind: "already";
+    readonly lines: readonly string[];
+}
+/** Go: record `threadId` (when `changed`) and start the node. */
+ | {
+    readonly kind: "resume";
+    readonly threadId: string;
+    readonly changed: boolean;
+    readonly rolloutPath: string;
+};
+/** How many threads the picker numbers; older ones are reachable with --thread. */
+export declare const PICK_LIMIT = 20;
+export declare function freshStartCommand(f: Pick<CodexResumeFacts, "alias" | "kind">): string;
+export declare function codexLoginCommand(f: Pick<CodexResumeFacts, "codexHome" | "homeIsHost">): string;
+/** Numbered rows: time (UTC, as codex wrote it), short id, first user line. The recorded thread is marked. */
+export declare function formatNodeThreadList(threads: readonly ExternalThread[], recorded: string | null, limit?: number): string[];
+export declare function resumeCommandFor(alias: string, threadId: string): string;
+/** The whole decision. Order: request shape → home → which thread → login → process state. */
+export declare function decideCodexResume(f: CodexResumeFacts, req: CodexResumeRequest): CodexResumeDecision;
+/** A typed answer to the picker: a number from the list; empty / q = cancel. */
+export declare function parsePickAnswer(answer: string | null, choices: readonly string[]): {
+    kind: "ok";
+    threadId: string;
+} | {
+    kind: "cancel";
+} | {
+    kind: "bad";
+    message: string;
+};
+/**
+ * `anet node codex resume` records the thread in config before its state
+ * machine runs. If the run stops before anything was touched, the old value
+ * goes back — the config must not name a thread the node is not running (#531 §5).
+ */
+export declare function resumeConfigShouldRollBack(stoppedAt: string): boolean;
+/**
+ * The facts for one node, from the same helpers the codex menu uses
+ * (collectCodexRows: kind / state / login; effectiveCodexHome: which home).
+ * Read-only. null = not a codex node.
+ */
+export declare function gatherCodexResumeFacts(node: CodexMenuNode, env: CollectEnv): CodexResumeFacts | null;

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;