@sleep2agi/agent-network 2.3.0-preview.14 → 2.3.0-preview.140

package/dist/src/codex-auth-fingerprint.d.ts

@@ -0,0 +1,211 @@
+/** Per-node record, written into the node dir next to the other state files. */
+export declare const CODEX_AUTH_FINGERPRINT_FILE = ".codex-auth-fingerprint.json";
+/**
+ * Host-wide index of the same records — the read side's source of truth.
+ *
+ * Under `~/.anet/` because that is already this repo's host-scoped state
+ * directory (global config lives there) and it does not move with `cwd`, which
+ * is the entire point: the nodes that need to see each other are in different
+ * workspaces.
+ */
+export declare function codexFingerprintIndexDir(home?: string): string;
+/**
+ * Index filename for a node.
+ *
+ * 🔴 Derived from the node's DIRECTORY, never its alias. Aliases are not unique
+ *    across workspaces — the reference fleet runs a node beside its own `2号`
+ *    twin, and nothing stops two workspaces from using one name — so an
+ *    alias-keyed file would let one node silently overwrite another's record,
+ *    re-creating the very blindness this index fixes. A directory cannot be two
+ *    nodes.
+ *
+ * 🔴 And derived from the directory rather than from `node_id`, even though the
+ *    CLI has one handy: agent-node's `NODE_ID` can be empty (older configs), so
+ *    a node_id key would need a fallback — and then the same node would write
+ *    one filename from one launch path and a different one from the other,
+ *    leaving two records that look like two nodes sharing a credential. One
+ *    deterministic key from an input both call sites already have is worth more
+ *    than a prettier name. `node_id` is still recorded, for humans.
+ */
+export declare function codexFingerprintIndexFile(nodeDir: string): string;
+/** Length of the stored fingerprint. Collisions at 8 hex are ~1 in 4 billion;
+ *  a false "these two share a login" warning costs a second look, while the
+ *  value staying short keeps it obviously non-reversible in logs. */
+export declare const FINGERPRINT_LENGTH = 8;
+/** Access tokens measured on the reference fleet: `exp - iat` was exactly this,
+ *  on 29 of 29 samples, with no jitter. Used only to phrase "how long until the
+ *  shared copy dies" when we have an `exp` but no `iat`. */
+export declare const ACCESS_TOKEN_LIFETIME_SECONDS = 864000;
+/** Past this, a published record's age is shown beside the alias. It does not
+ *  suppress the warning: a node that has not started in a week still holds the
+ *  shared credential. See the liveness note on `checkCodexCredentialSharing`. */
+export declare const STALE_RECORD_NOTICE_MS: number;
+export interface CodexAuthFingerprintRecord {
+    readonly schema_version: 1 | 2 | 3;
+    readonly alias: string;
+    /** sha256(refresh_token) truncated — never the token. */
+    readonly fingerprint: string;
+    readonly written_at: string;
+    /** v2: when this copy's ACCESS token expires, ISO-8601, or null if unreadable.
+     *  A timestamp, not a credential. Two nodes holding one copied file share this
+     *  instant exactly — which is how "they stop together" becomes observable. */
+    readonly access_expires_at?: string | null;
+    /** v2: the CODEX_HOME this record was read from. Distinguishes "two copies of
+     *  one credential" from "two nodes pointed at one directory", which need
+     *  different fixes. */
+    readonly codex_home?: string | null;
+    /** v3: the node directory this record describes, canonical. Three jobs: it is
+     *  the identity used to de-duplicate the index against the sibling scan and to
+     *  exclude self; and it is the liveness test — if this directory is gone, the
+     *  node is gone and the record must not accuse anyone. */
+    readonly node_dir?: string;
+    /** v3: recorded for humans reading the index by hand. Never the key: it can be
+     *  absent, and a key that is sometimes absent produces two records per node. */
+    readonly node_id?: string | null;
+}
+/**
+ * Hash the refresh token out of an auth.json body.
+ *
+ * Accepts both shapes seen in the wild: the current codex layout nests it
+ * under `tokens` (`{auth_mode, tokens:{id_token, access_token, refresh_token,
+ * account_id}, last_refresh}`), and older/plain bodies put `refresh_token` at
+ * the top level. Anything else — unparsable, absent, empty, non-string —
+ * returns null, because "we cannot tell" must not be reported as "no
+ * collision".
+ */
+export declare function fingerprintRefreshToken(authJsonText: string): string | null;
+/**
+ * When this copy's access token expires, read out of the JWT's own payload.
+ *
+ * The signature is NOT verified and nothing here authenticates: we are reading
+ * a timestamp the token states about itself, the same way `jwt.io` would. A
+ * token that is not a JWT, or carries no numeric `exp`, yields null — unknown
+ * stays unknown.
+ */
+export declare function accessTokenExpiry(authJsonText: string): Date | null;
+export interface NodeFingerprint {
+    readonly alias: string;
+    /** null when the node has no auth.json, or one we could not read. */
+    readonly fingerprint: string | null;
+    /** When the record was written; used to say how stale a claim is. */
+    readonly writtenAt?: string | null;
+    /** When this copy's access token expires, if we could read it. */
+    readonly accessExpiresAt?: Date | null;
+    /** The CODEX_HOME this fingerprint came from, if known. */
+    readonly codexHome?: string | null;
+    /** Canonical node directory — identity for de-duplication and self-exclusion. */
+    readonly nodeDir?: string | null;
+}
+/**
+ * Other nodes holding the same credential chain as `self`.
+ *
+ * Records with no fingerprint are skipped rather than grouped: "unknown" is
+ * not a match.
+ *
+ * 🔴 Self is excluded by node DIRECTORY when both sides carry one, and only
+ *    falls back to alias for pre-v3 records. Once the read side is host-wide,
+ *    alias stops being an identity: two workspaces may each hold a node called
+ *    the same thing, and excluding by name would hide a genuine collision
+ *    between them — the exact failure this index was added to fix.
+ */
+export declare function collidingNodes(records: readonly NodeFingerprint[], self: NodeFingerprint): NodeFingerprint[];
+/**
+ * The warning an operator sees at start. Returns [] when nothing collides —
+ * callers print exactly what they get, so silence is representable and the
+ * "no collision" path cannot accidentally print a scary empty banner.
+ *
+ * Deliberately a warning and never a refusal: every node on a host shares one
+ * login today, so refusing to start would take the whole box down at once
+ * over a condition that is survivable until the next refresh.
+ *
+ * 🔴 Two outcomes, and the wrong one is actively misleading. The default text
+ *    ("whichever node refreshes first keeps working") assumes refresh WORKS.
+ *    On a host that cannot reach the OAuth token endpoint — egress blocked, or
+ *    a proxy that allowlists the model API and 403s everything else — nobody
+ *    refreshes, and the nodes holding one copy do not degrade one at a time:
+ *    they stop together the moment the shared access token expires. Field case:
+ *    three nodes whose auth.json files were byte-identical, carrying one access
+ *    token, all expired at the same instant.
+ *
+ *    We do NOT probe the network to tell these apart — a start path is the wrong
+ *    place to open a socket, and a probe would answer for this moment rather
+ *    than for the window that matters. We branch on evidence already in the
+ *    file: an access token whose `exp` has passed is a copy that demonstrably
+ *    stopped being refreshed, which is the observable the field case exhibits.
+ *    When `exp` is still in the future we cannot prove reachability either way,
+ *    and the default wording is the right one to print.
+ */
+export declare function sharedCredentialWarningLines(self: NodeFingerprint, colliding: readonly NodeFingerprint[], now?: Date): string[];
+/**
+ * Two different things both read as "codex cannot refresh", and they need
+ * opposite remedies. Telling them apart is the whole value of this mapping:
+ * treating a transport failure as a rotation conflict sends an operator to
+ * copy someone else's auth.json, which is precisely how a shared-credential
+ * chain gets created.
+ */
+export type CodexRefreshFailureKind = 
+/** Someone else spent this refresh token first. */
+"rotation-conflict"
+/** The token endpoint is unreachable — nobody's token is rotating. */
+ | "token-endpoint-unreachable";
+export interface CodexRefreshFailure {
+    readonly kind: CodexRefreshFailureKind;
+    readonly lines: string[];
+}
+/**
+ * Name what actually went wrong with a codex refresh, and say what to do.
+ *
+ * Returns null for anything else, so callers fall through to whatever they
+ * printed before — an unrelated error must pass through unchanged.
+ *
+ * Order matters: a reuse rejection is a server answer and is checked first; a
+ * transport failure means no answer arrived at all.
+ */
+export declare function describeCodexRefreshFailure(text: string, colliding?: readonly NodeFingerprint[]): CodexRefreshFailure | null;
+export interface CodexCredentialSharingCheck {
+    /** This node's own directory — where its record is written. */
+    readonly nodeDir: string;
+    /** Shown to the operator; also how a node recognises its own record. */
+    readonly alias: string;
+    /** The CODEX_HOME whose auth.json this node will actually use. */
+    readonly codexHome: string;
+    /** Recorded for humans reading the index; never used as a key. Optional
+     *  because agent-node's can be empty on older configs. */
+    readonly nodeId?: string | null;
+    /** Where the warning goes. Defaults to stderr. */
+    readonly say?: (message: string) => void;
+    /** Injected for tests; production passes nothing. */
+    readonly now?: Date;
+    /** Injected for tests; production uses the real host index under `~/.anet`. */
+    readonly indexDir?: string;
+}
+/**
+ * The whole operation: read this node's credential, publish an 8-hex record,
+ * read what the *other* nodes published, and warn if any of them is on the
+ * same chain. Returns the colliding nodes so a caller can name them again if
+ * codex later fails to refresh.
+ *
+ * 🔴 Reads the neighbours' published fingerprint files, never their
+ *    credentials. A guard against credential sharing must not itself become a
+ *    reason to open every node's auth.json.
+ *
+ * 🔴 Always recomputes. The fingerprint changes every time codex refreshes in
+ *    place, so a stale record is a wrong answer; both call paths may run for
+ *    one node in sequence, and whichever runs last must leave the current
+ *    value, never an older one.
+ *
+ * 🔴 Liveness is EXISTENCE, not age. An index record outlives the node that
+ *    wrote it, and a stale one accusing a node that no longer exists is worse
+ *    than silence — it teaches operators to ignore the warning. So a record
+ *    whose `node_dir` is gone is dropped and its index entry deleted.
+ *    Age deliberately does NOT filter: on the reference fleet two of the three
+ *    nodes in the worst-affected group were not running at all, and six of 29
+ *    credential files had not been touched in days, while still holding the
+ *    shared copy. An age cutoff would have hidden precisely the collisions
+ *    worth reporting. Age is surfaced in the warning instead, so the operator
+ *    can judge how old the claim is.
+ *
+ * Never throws and never refuses: observability must not be the reason a node
+ * will not start.
+ */
+export declare function checkCodexCredentialSharing(opts: CodexCredentialSharingCheck): NodeFingerprint[];

package/dist/src/codex-copresence-bridge-log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * #535 (audit P1-2) — keep the codex co-presence bridge's last words.
+ *
+ * The bridge (piece ②) runs in its own tmux session. When it failed, that
+ * session exited, and the launcher still printed
+ *   Debug: tmux attach -t '=<alias>-桥'
+ * which pointed at nothing. The audit only found the real cause
+ * (`exact paired package identity validation failed: … unsafe ownership or
+ * mode`) by re-running the bridge command by hand.
+ *
+ * Its stdout/stderr now also go to `<node dir>/codex-bridge.log`, and a failed
+ * start prints the tail of that file plus the path. Same idea as the OpenCode
+ * twin (copresence-bridge.log), with two differences:
+ *   - the file is NOT under logs/: `anet logs` shows the reverse-sorted first
+ *     `*.log` there, and a name like this sorts above agent-node's dated logs,
+ *     so it would hide them;
+ *   - the copy is capped (the bridge runs for days and agent-node already
+ *     writes its own dated log). Past the cap the remainder is drained, never
+ *     refused: a reader that stopped reading would SIGPIPE `tee` and with it
+ *     the bridge's stdout.
+ */
+export declare const CODEX_BRIDGE_LOG_NAME = "codex-bridge.log";
+export declare const CODEX_BRIDGE_LOG_CAP_BYTES: number;
+export declare const CODEX_BRIDGE_TAIL_LINES = 20;
+/**
+ * A bash statement that sends the rest of the script's stdout+stderr to the
+ * pane AND to the log (whole lines, up to about CAP bytes, flushed line by line). `quotedLogPath` must already be
+ * shell-quoted. The parent `exec`s anet next, so anet's pid is still the pane's
+ * process; `tee`/`awk` inherit the session's ANET_NODE_MARKER and are
+ * reaped with it on stop.
+ */
+export declare function codexBridgeTeeCommand(quotedLogPath: string, capBytes?: number): string;
+/** Last `n` non-empty lines, with trailing whitespace trimmed. */
+export declare function tailLines(text: string, n?: number): string[];
+export interface BridgeFailureInput {
+    readonly bridgeAlive: boolean;
+    readonly attachCommand: string;
+    readonly logPath: string;
+    readonly logText: string;
+    readonly waitedSeconds: number;
+    readonly cleanupCommand: string;
+}
+/** What the launcher prints when the bridge did not report ready. */
+export declare function bridgeLaunchFailureLines(i: BridgeFailureInput): string[];

package/dist/src/codex-copresence-login-gate.d.ts

@@ -0,0 +1,16 @@
+export type CodexHomeLoginState = "logged-in" | "needs-login" | "unknown";
+export interface CodexHomeLoginVerdict {
+    readonly state: CodexHomeLoginState;
+    /** One phrase for the operator: why this state. No secrets. */
+    readonly reason: string;
+}
+/** The node's verdict. auth.json is judged by the #529 helper; see the header for the two fail-open cases. */
+export declare function codexHomeLoginState(codexHome: string, env?: Record<string, string | undefined>): CodexHomeLoginVerdict;
+/** Exit code for `needs-login`: distinct from 1 (failed) so scripts can tell "do something" from "broken". */
+export declare const NEEDS_LOGIN_EXIT_CODE = 3;
+/** What the launcher prints instead of "✅ 就绪": a state line, then the #529 next step. Nothing executed. */
+export declare function describeCodexNeedsLogin(i: {
+    alias: string;
+    codexHome: string;
+    reason: string;
+}): string[];

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

@@ -0,0 +1,23 @@
+/**
+ * #512 — which model a codex co-presence start runs on, and why.
+ *
+ * Order: explicit `--model` flag > the node's own config (`model` in
+ * .anet/nodes/<id>/config.json, written by `anet node create --model` /
+ * `anet node edit --model`) > DEFAULT_CODEX_MODEL.
+ *
+ * The bug this replaces: the start path computed `opts.model || DEFAULT`
+ * where `opts.model` was ONLY the CLI flag, so every start that did not
+ * repeat `--model` — the plain `anet node start <name>`, the boot sweep, and
+ * `anet node codex start|restart|resume` (which re-invoke `node start`
+ * without `--model`) — silently put the node on the default.
+ *
+ * One resolved value feeds all three pieces (app-server `-c model=`, the
+ * thread/resume `model` override, TUI `-m`), so they cannot disagree.
+ */
+export type CodexModelSource = "flag" | "node-config" | "default";
+export interface ResolvedCodexModel {
+    model: string;
+    source: CodexModelSource;
+}
+export declare function resolveCodexCopresenceModel(flagModel: unknown, nodeConfigModel: unknown, fallback?: string): ResolvedCodexModel;
+export declare function describeCodexModelSource(r: ResolvedCodexModel): string;

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

@@ -0,0 +1,65 @@
+export interface CodexHomeInheritedFile {
+    readonly name: string;
+    readonly mode: number;
+    /** Why a node needs it — printed when staged, so the action is legible. */
+    readonly because: string;
+}
+export declare const CODEX_HOME_INHERITED_FILES: readonly CodexHomeInheritedFile[];
+export interface StatLike {
+    readonly mtimeMs: number;
+}
+export type StatFn = (path: string) => StatLike | null;
+export interface CodexHomeStageStep {
+    readonly name: string;
+    readonly src: string;
+    readonly dst: string;
+    readonly mode: number;
+    readonly reason: "missing" | "host-newer";
+    readonly because: string;
+}
+/**
+ * What to copy from the host CODEX_HOME into the node's, right now.
+ *
+ * Pure: takes the stat function so the ordering rules are testable without a
+ * filesystem. A node file that is NEWER than the host's is left alone — codex
+ * refreshes its own copy in place, and clobbering it would throw away a fresher
+ * token than the one we hold.
+ */
+export declare function codexHomeStagePlan(hostHome: string, nodeHome: string, stat: StatFn, join: (a: string, b: string) => string, files?: readonly CodexHomeInheritedFile[]): CodexHomeStageStep[];
+export type CodexTuiBlocker = "sign-in" | "update-prompt" | "trust-prompt";
+export type CodexTuiPaneState = CodexTuiBlocker | "not-painted" | "usable";
+/**
+ * Classify the TUI, from two different reads of the same pane.
+ *
+ * They answer different questions and need different tmux flags — the same
+ * distinction `waitForTmuxPaneText` documents one screenful up:
+ *
+ *   onScreen  (capture-pane, no -S)  → "is it sitting on a prompt right now"
+ *             A prompt that was already answered stays in scrollback forever,
+ *             so reading history here would report a fixed node as blocked.
+ *
+ *   everSeen  (capture-pane -S -N)   → "did the TUI ever paint"
+ *             The banner is printed once and scrolls away — an MCP error burst
+ *             was enough to push it off screen in under a minute — so reading
+ *             only the current screen here would report a working node as dead.
+ *
+ * 🔴 And "the pane has text" answers neither. An earlier version of this used
+ * "≥3 non-empty lines ⇒ ready" and passed a node parked on the sign-in page.
+ * Measured timeline for that start:
+ *
+ *     t≈3s   22 non-empty lines   ← launcher output, TUI not up yet
+ *     t≈6s    0 non-empty lines   ← codex clears the screen and takes over
+ *     t≈9s   10 non-empty lines   ← the sign-in page finally paints
+ *
+ * The rule fired at t≈3s, six seconds before the thing it was meant to catch
+ * existed.
+ */
+export declare function codexTuiPaneState(onScreen: string, everSeen?: string): CodexTuiPaneState;
+/**
+ * What the operator should read when a node came up but cannot work. Names the
+ * blocker AND where to look — a launcher that only says "not ready" sends
+ * someone hunting through three tmux sessions.
+ */
+export declare function describeCodexTuiBlocker(blocker: CodexTuiBlocker, displayName: string, tuiSession: string): string;
+/** The TUI never painted at all — a distinct failure from being blocked. */
+export declare function describeCodexTuiNotPainted(displayName: string, tuiSession: string, waitedMs: number): string;

package/dist/src/codex-copresence-profile.d.ts

@@ -0,0 +1,125 @@
+export interface CodexCopresenceProfileFields {
+    readonly runtime?: string;
+    readonly codexCopresence?: boolean;
+    readonly codexCopresenceFullAccess?: boolean;
+    readonly flags?: Record<string, unknown>;
+    /** Absolute project directory to launch the codex TUI in. Passed as
+     *  `-C <dir>` to `codex resume`. Also cross-checked against hub-reported
+     *  `session.project_dir` in Phase 4.3. */
+    readonly codexProjectDir?: string;
+    /** Which launch adapter to use in Phase 3.2. `"codex-standard"` = stock
+     *  `codex app-server` + `codex resume`; `"codex-custom-wrapper"` = partner-team-class
+     *  custom LLM API wrapper (hosted tool / compaction / image-output compat).
+     *  Unknown / absent → Phase 0 fail-closed (unknown adapters must not fall
+     *  through to a default that might not fit the node's real topology). */
+    readonly codexLaunchAdapter?: "codex-standard" | "codex-custom-wrapper";
+    /** Alias of the peer that will verify this node's identity in Phase 6.
+     *  Peer MUST be (a) registered in the same network, (b) online at resume
+     *  time, (c) not this node itself. Identity attestation uses a fresh
+     *  Hub outbound `send_task` from THIS node's Bridge to <codexProbePeer>
+     *  carrying a nonce; peer echoes the nonce back; CLI cross-checks Hub's
+     *  recorded `from_name / from_node_id / to_name / to_node_id`.
+     *
+     *  🔴 self-loop is deliberately not accepted here — it cannot prove
+     *  cross-node routing closure (design v7 Phase 6 = D, per the partner team
+     *  06cfb29a). Single-node users cannot run `anet node resume` in
+     *  this initial cut; tracked at #1527. */
+    readonly codexProbePeer?: string;
+}
+/** #1521 — the three fields `anet node resume <alias>` will require on a
+ *  codex-copresence node once the resume dispatcher lands (#1528, Draft).
+ *  In this PR, only shape-level enumeration exists (see
+ *  `missingCodexResumeFields` below); no CLI code reads that enumeration
+ *  and the operator-facing remediation flow is deliberately deferred
+ *  along with its real caller. */
+export type CodexResumeRequiredField = "codexProjectDir" | "codexLaunchAdapter" | "codexProbePeer";
+export declare const CODEX_RESUME_REQUIRED_FIELDS: readonly CodexResumeRequiredField[];
+/** Enumerate which of the three resume-required fields are absent /
+ *  wrong-shaped on this profile. Returns [] when all three are present
+ *  and well-shaped.
+ *
+ *  🔴 SHAPE-ONLY validation:
+ *    - codexProjectDir : string starting with `/`. This is a CHEAP typo
+ *      filter, NOT the security gate. Phase 0 (in #1528) MUST additionally
+ *      `realpath`/canonicalize + reject NUL, `/`, and any untrusted target
+ *      before passing this value to `codex resume -C <dir>` (per the partner team
+ *      4bab8196: "startsWith('/') 不是最终安全门").
+ *    - codexLaunchAdapter : enum membership.
+ *    - codexProbePeer : Hub exact-alias lookup, so value MUST equal its own
+ *      trim. Values with leading/trailing whitespace would fail Hub lookup
+ *      100% of the time; rejecting them at the shape layer is a witnessed-red
+ *      canary rather than a permissive pass-through (per the partner team 048d0061 R2:
+ *      "不要 pin 一个必然在 Hub exact lookup 阶段失败的 well-shaped 值").
+ *      Liveness (registered + online + non-self) is a separate hub-side
+ *      check in Phase 0.
+ *
+ *  Deliberately NOT included: an operator-facing diagnostic helper. An
+ *  earlier draft included `codexResumeMissingConfigHint` that referenced
+ *  a `anet node config apply` verb which does not exist in the tree —
+ *  外部团队 4bab8196 blocked it as the exact "存在 ≠ 会执行" antipattern.
+ *  The diagnostic lands with its real caller in a later PR that either
+ *  (a) implements `anet node config apply` first, or (b) reworks the
+ *  diagnostic to reference existing commands only. */
+export declare function missingCodexResumeFields(profile: CodexCopresenceProfileFields): CodexResumeRequiredField[];
+export declare const CODEX_COPRESENCE_RUNTIME = "codex-app-server";
+/**
+ * Should this `anet node start` bring up the co-presence stack?
+ *
+ * The flag still works for a one-off; the profile field is what makes the
+ * second start a single command.
+ */
+export declare function codexCopresenceRequested(flagPassed: boolean, profile: CodexCopresenceProfileFields): boolean;
+/**
+ * True when a plain `anet node start` just became enough for this node — i.e.
+ * the flag was passed and the profile had not recorded it yet. Callers persist
+ * `codexCopresence: true` and tell the user they can drop the flag.
+ */
+export declare function shouldPersistCodexCopresence(flagPassed: boolean, profile: CodexCopresenceProfileFields): boolean;
+export interface CodexCopresencePosture {
+    readonly sandboxMode: "danger-full-access" | "read-only";
+    readonly approvalPolicy: "never" | "on-request";
+    /** Set when the node asked for full access and is NOT getting it. */
+    readonly downgradeNotice?: string;
+    /** Set when a remembered grant (not this invocation's flag) opened it up. */
+    readonly grantedFromProfile: boolean;
+}
+/**
+ * Resolve the sandbox the co-presence app-server runs under.
+ *
+ * Precedence: this invocation's flag → a grant already recorded on the profile
+ * → read-only. `flags.sandboxMode` alone never opens the sandbox; it only
+ * decides whether staying closed is worth telling the user about.
+ */
+export declare function codexCopresencePosture(dangerFlagPassed: boolean, profile: CodexCopresenceProfileFields, displayName?: string): CodexCopresencePosture;
+/** True when an explicit grant should be written to the profile for next time. */
+export declare function shouldPersistCodexFullAccess(dangerFlagPassed: boolean, profile: CodexCopresenceProfileFields): boolean;
+/**
+ * What `anet node create --runtime codex-app-server` should record, so that a
+ * later `anet node start <name>` is a single command with no flag.
+ *
+ * Shape copied from opencode, which already does exactly this at create time:
+ *
+ *   ...(runtime === "opencode-cli"
+ *     ? { opencodeMode: opts.mode === "copresence" || opts.copresence === "true"
+ *         ? "copresence" : "headless" }
+ *     : {}),
+ *
+ * Deliberately NOT keyed on which alias the operator typed. `codex-tui`,
+ * `codex-appserver` and `codex-app-server` are documented as aliases of one
+ * runtime (agent-node/src/cli.ts); giving one of them a different default would
+ * quietly break that contract, and "I typed the short name" is not a reliable
+ * statement of intent. Opting in stays explicit, exactly as it is for opencode.
+ */
+export declare function codexCopresenceCreateFields(normalizedRuntime: string | undefined, copresenceOpt: string | boolean | undefined): {
+    codexCopresence?: true;
+};
+/**
+ * One line at create time for a node that will start headless.
+ *
+ * NOT keyed on which alias the operator typed: by the time create builds the
+ * profile, `opts.runtime` has already been normalized to `codex-app-server`, so
+ * `codex-tui` is simply not recoverable here — a hint that tried to read it
+ * would never fire. (It didn't; that is how this was found.) Keying on the
+ * runtime instead also keeps the aliases true synonyms.
+ */
+export declare function codexCopresenceCreateHint(normalizedRuntime: string | undefined, copresenceOpt: string | boolean | undefined, displayName: string): string | undefined;

package/dist/src/codex-copresence-recovery.d.ts

@@ -0,0 +1,58 @@
+export interface CodexRecoveryVerification {
+    method: "thread/start" | "thread/resume";
+    threadId: string;
+    verifiedAt: string;
+    historyTurnCount: number;
+    historyFingerprint: string;
+}
+export interface CodexRecoveryBackup {
+    backupDir: string;
+    createdAt: string;
+    stateFiles: string[];
+}
+/** Transaction boundary shared by Windows and POSIX cutovers: the snapshot
+ * cannot begin until every authoritative state writer has quiesced. */
+export declare function quiesceThenSnapshot<T>(quiesce: () => Promise<void>, snapshot: () => T): Promise<T>;
+/** A stored thread is never considered resumed until app-server reads the
+ * exact thread back with persisted history. This is deliberately stricter
+ * than accepting a successful thread/resume RPC response. */
+export declare function verifyCodexThreadHistory(method: "thread/start" | "thread/resume", expectedThreadId: string, readResult: unknown, now?: Date): CodexRecoveryVerification;
+/**
+ * #512 — `model` is the node's resolved model. It MUST ride on thread/resume:
+ * measured on codex 0.155 (Docker), a resume without it puts the thread back on
+ * the model recorded in the rollout's last turn_context and ignores the
+ * app-server's `-c model=`. This launcher is the first client to load the
+ * thread, and once loaded, later resumes without a model (the bridge's) keep
+ * whatever the first one set — so this is the request that decides the model
+ * for every subsequent turn: the configured model wins over the thread's
+ * recorded one.
+ *
+ * Returns the model the app-server reports for the resumed thread (if any) so
+ * the caller can say which model the session is actually on.
+ */
+export declare function resumeAndVerifyCodexThread(threadId: string, request: (method: string, params: Record<string, unknown>) => Promise<unknown>, model?: string): Promise<CodexRecoveryVerification & {
+    resumedModel?: string;
+}>;
+/** Private, node-local recovery point. config-recovery.json is deliberately
+ * redacted non-credential audit/recovery metadata, not an identity backup.
+ * Identity recovery relies on leaving the original node config and CODEX_HOME
+ * in place. Credentials are never copied into this snapshot. */
+export declare function backupCodexRecoveryState(opts: {
+    nodeDir: string;
+    codexHome: string;
+    now?: Date;
+}): CodexRecoveryBackup;
+export declare function codexTopologyAudit(profile: Record<string, any>, nodeDir: string, cwd: string): {
+    launchMode: string;
+    cwd: string;
+    codexHome: string;
+    remote: any;
+    threadId: any;
+    model: any;
+    flags: any;
+    lastRecoveryVerification: any;
+    lastRecoveryBackup: {
+        createdAt: any;
+        stateFiles: any;
+    } | null;
+};

package/dist/src/codex-copresence-thread.d.ts

@@ -0,0 +1,13 @@
+export type CopresenceThreadPlan = {
+    method: "thread/resume";
+    params: {
+        threadId: string;
+    };
+    bootstrap: false;
+} | {
+    method: "thread/start";
+    params: Record<string, never>;
+    bootstrap: true;
+};
+/** Restarting a node must preserve its conversation; only a virgin node starts one. */
+export declare function copresenceThreadPlan(storedThreadId?: string): CopresenceThreadPlan;

package/dist/src/codex-home-enforce.d.ts

@@ -0,0 +1,71 @@
+export type CodexHomeSource = "config.codexHome" | "node-codex-home" | "config.env" | "none";
+export interface CodexHomeResolution {
+    /** null = 这台节点没有专属 CODEX_HOME(普通 codex 节点用 codex 自己的默认 ~/.codex)。 */
+    codexHome: string | null;
+    source: CodexHomeSource;
+}
+export interface ResolveNodeCodexHomeInput {
+    nodeDir: string;
+    /** 节点 config.json 的内容(只读其中三格:codexHome / codexCopresence / env.CODEX_HOME)。 */
+    config: Record<string, unknown> | null | undefined;
+    exists?: (path: string) => boolean;
+}
+/**
+ * 本节点的 CODEX_HOME,只由节点自己的配置/目录决定。优先级:
+ *   ① config.codexHome(`--codex-home` 显式指定后持久化的那一格)
+ *   ② <nodeDir>/codex-home(共存节点,或目录已经存在)
+ *   ③ config.env.CODEX_HOME(节点 profile 自己写的,字面字符串)
+ *   ④ 没有 → null
+ * **进程环境从不参与**:那正是本模块要挡掉的来源。
+ */
+export declare function resolveNodeCodexHome(input: ResolveNodeCodexHomeInput): CodexHomeResolution;
+export declare function looksLikeAnetNodeCodexHome(path: string): boolean;
+export interface ApplyCodexHomeResult {
+    /** 实际交给子进程的值(undefined = 不设,交给 codex 默认)。 */
+    codexHome: string | undefined;
+    /** 给人看的一行;没有需要说的时候为 null。 */
+    note: string | null;
+}
+/**
+ * 把解析结果写进一份**将要交给子进程**的 env(原地修改并返回结论)。
+ * - 有专属值 → 强制写入,覆盖任何继承来的值。
+ * - 没有专属值、而继承来的值是**别的 anet 节点**的 codex-home → 删掉(那绝不是本节点的)。
+ * - 没有专属值、继承来的是运维自己 export 的普通路径 → 保留(不改变普通 codex 节点的既有行为),
+ *   并说一句它来自环境。
+ */
+export declare function applyNodeCodexHome(env: Record<string, string | undefined>, resolution: CodexHomeResolution): ApplyCodexHomeResult;
+export interface ProcReader {
+    /** /proc/<pid>/environ 的原始内容;读不到返回 null。 */
+    environ(pid: number): string | null;
+    /** 所有进程的 [pid, ppid];读不到返回 []。 */
+    parents(): Array<[number, number]>;
+}
+export declare const linuxProcReader: ProcReader;
+/** 环境块里某个变量的值:undefined = 环境读不到;null = 读到了但没有这个变量。 */
+export declare function envVarFromEnviron(environ: string | null, name: string): string | null | undefined;
+export declare function descendantPids(rootPid: number, parents: Array<[number, number]>): number[];
+export type CodexHomeVerdict = {
+    ok: true;
+    checked: number[];
+    skipped?: string;
+} | {
+    ok: false;
+    pid: number;
+    actual: string | null;
+    expected: string;
+    message: string;
+};
+/**
+ * 读 rootPid 及其全部后代的 /proc/<pid>/environ:
+ *   - rootPid 自己的 CODEX_HOME 必须**正好等于** expected(缺失也算不符);
+ *   - 后代里凡是带 CODEX_HOME 的,也必须等于 expected(某个后代自己 unset 掉不算错)。
+ * 不是 Linux、或 rootPid 的环境根本读不到(进程已退出/权限)→ ok:true + skipped,由调用方决定怎么说。
+ * 🔴 读不到 ≠ 核对通过:skipped 必须被调用方打印出来,不能当绿。
+ */
+export declare function verifyProcessTreeCodexHome(opts: {
+    rootPid: number;
+    expected: string;
+    label: string;
+    platform?: string;
+    reader?: ProcReader;
+}): CodexHomeVerdict;