@sleep2agi/agent-network 2.3.0-preview.18 → 2.3.0-preview.180

package/dist/src/codex-copresence-rollout-guard.d.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "child_process";
+import { type FirstLineRead } from "./codex-rollout-history-guard";
+export interface CopresenceRolloutGuardInput {
+    codexHome: string;
+    /** Threads this start may resume (recorded thread, pending candidate). Empty entries are skipped. */
+    threadIds: Array<string | undefined | null>;
+    /** The binary as the launch names it (probeVersion should run it the way the launch does). */
+    codexBin: string;
+    displayName: string;
+    probeVersion?: (bin: string) => string | null;
+    resolveRollout?: (codexHome: string, threadId: string) => string | null;
+    readFirstLine?: (path: string) => FirstLineRead;
+}
+export interface CopresenceRolloutGuardResult {
+    /** Non-null = refuse to start; print these lines. */
+    block: string[] | null;
+    /** Could-not-tell notes; print and continue. */
+    warnings: string[];
+}
+/**
+ * `codex --version` run through the SAME shell preamble the launch uses, so the
+ * probe sees the binary the launch will run: the launch command itself is never
+ * rewritten. The co-presence panes run `bash -lc "… exec <codexBin> app-server"`
+ * (login-shell PATH); external app-server panes run `bash -c "<source .env>; …;
+ * <codexBin> app-server"` (the workspace .env may set PATH). `script` must end in
+ * `exec <codexBin> --version`. Only a codex-identifying line counts; anything
+ * else (or any failure) is null = unknown, which never blocks.
+ */
+export declare function probeCodexVersionViaShell(script: string, opts: {
+    loginShell: boolean;
+    env?: NodeJS.ProcessEnv;
+    run?: typeof spawnSync;
+}): string | null;
+/** The co-presence app-server pane's preamble (CODEX_HOME, then exec the binary), ending in `--version`. */
+export declare function copresenceVersionProbeScript(codexHome: string, codexBin: string): string;
+export declare function copresenceRolloutGuard(input: CopresenceRolloutGuardInput): CopresenceRolloutGuardResult;

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

@@ -0,0 +1,17 @@
+import { type CodexRecoveryVerification } from "./codex-copresence-recovery";
+export declare const SAFE_CODEX_THREAD_ID: RegExp;
+export declare function defaultWebSocketCtor(maxPayload: number): Promise<any>;
+/** Minimal JSON-RPC client used only while bringing up a co-presence app-server. */
+export declare function createCodexCopresenceThread(ws: string, timeoutMs: number, resumeThreadId?: string, model?: string, 
+/** forkFirst (board #738): `thread/fork` the recorded thread, then resume the NEW thread. */
+options?: {
+    webSocketCtor?: any;
+    rolloutBytes?: number | null;
+    forkFirst?: boolean;
+    modelProvider?: string;
+}): Promise<{
+    threadId: string;
+    verification?: CodexRecoveryVerification;
+    freshDeferred: boolean;
+    resumedModel?: string;
+}>;

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-copresence-yolo.d.ts

@@ -0,0 +1,16 @@
+/** API `flags.*` shape (client #815 / codexSdkYoloFlags). */
+export declare const CODEX_COPRESENCE_YOLO_FLAGS: Readonly<{
+    approvalPolicy: "never";
+    sandboxMode: "danger-full-access";
+    skipGitRepoCheck: true;
+}>;
+/** Top-level Codex `config.toml` keys for the same posture. */
+export declare const CODEX_COPRESENCE_YOLO_TOML: Readonly<{
+    approval_policy: "never";
+    sandbox_mode: "danger-full-access";
+}>;
+/** Fill missing yolo flags when a co-presence codex-app-server node is created. */
+export declare function applyCodexCopresenceFlagDefaults(flags: Record<string, unknown>): void;
+export declare function mergeCopresenceYoloIntoToml(existing: string): string;
+/** Persist co-presence yolo posture under `<nodeDir>/codex-home/config.toml`. */
+export declare function writeCopresenceYoloToCodexHome(codexHome: string): void;

package/dist/src/codex-external-appserver.d.ts

@@ -0,0 +1,130 @@
+export declare const EXTERNAL_APPSERVER_LAYOUT = "external-appserver";
+export declare const READYZ_TIMEOUT_MS = 30000;
+export interface ExternalAppserverProfile {
+    runtime?: string;
+    codexAppServerUrl?: string;
+    codexThreadId?: string;
+    codexProjectDir?: string;
+    codexCopresence?: boolean;
+    codexLaunchLayout?: string;
+    codexBin?: string;
+    codexHome?: string;
+    model?: string;
+    env?: Record<string, unknown>;
+}
+export interface ExternalAppserverSessions {
+    appsrv: string;
+    tui: string;
+    bridge: string;
+}
+export declare function externalAppserverSessions(alias: string): ExternalAppserverSessions;
+/** Bridge first, so nothing is left attached to a server that is going away. */
+export declare function externalAppserverStopOrder(alias: string): string[];
+/**
+ * Does this start/stop/restart take the external-app-server lane?
+ * `runtime` is the already-normalized runtime name.
+ */
+export declare function externalAppserverRequested(flagPassed: boolean, profile: ExternalAppserverProfile, runtime: string): boolean;
+export interface ExternalAppserverPlan {
+    alias: string;
+    nodeDir: string;
+    configPath: string;
+    workspaceDir: string;
+    url: string;
+    host: string;
+    port: number;
+    readyzUrl: string;
+    projectDir: string;
+    /** True when config.codexProjectDir was empty and the workspace was used instead. */
+    projectDirFromWorkspace: boolean;
+    threadId: string;
+    model: string;
+    codexHome: string;
+    codexBin: string;
+    /** Start the `<alias>-tui` session (codexCopresence && codexThreadId). */
+    tui: boolean;
+    sessions: ExternalAppserverSessions;
+}
+export declare function planExternalAppserverNode(input: {
+    alias: string;
+    nodeDir: string;
+    workspaceDir: string;
+    profile: ExternalAppserverProfile;
+}): {
+    ok: true;
+    plan: ExternalAppserverPlan;
+} | {
+    ok: false;
+    error: string;
+};
+/** Names from `wanted` that exist in `existing` — compared as whole strings, never by tmux target rules. */
+export declare function sessionsAlreadyPresent(existing: readonly string[], wanted: readonly string[]): string[];
+/** `{id, name}` rows whose name equals one of `names` exactly, in the order of `names`. */
+export declare function exactSessionRows(rows: readonly {
+    id: string;
+    name: string;
+}[], names: readonly string[]): {
+    id: string;
+    name: string;
+}[];
+/**
+ * Read the node token from config.json INSIDE the session shell, into the env.
+ * The value never appears in tmux's argv, the pane's start command, or any
+ * process's /proc/<pid>/cmdline — only the config path does.
+ */
+export declare function tokenInSessionSnippet(configPath: string, jsRuntime: string): string;
+/** Same token handoff, via the standalone binary's internal argv (it is not `node -e`). */
+export declare function standaloneBinTokenSnippet(configPath: string, anetBin: string): string;
+export declare function appserverShellCommand(plan: ExternalAppserverPlan, jsRuntime: string, mode?: "js-eval" | "standalone-bin"): string;
+/**
+ * Board #734 — `codex --version` with the app-server pane's exact preamble (workspace
+ * .env sourced the same way, same CODEX_HOME), run with `bash -c` like the pane, so the
+ * version probe sees the binary appserverShellCommand will run.
+ */
+export declare function versionProbeShellCommand(plan: ExternalAppserverPlan): string;
+export declare function tuiShellCommand(plan: ExternalAppserverPlan): string;
+export declare function bridgeShellCommand(plan: ExternalAppserverPlan, launch: {
+    command: string;
+    argsPrefix: readonly string[];
+}): string;
+export declare function bridgeLogPath(plan: {
+    nodeDir: string;
+}): string;
+/**
+ * tmux `-c` for the product-started bridge (`anet node start` and
+ * `restart --bridge-only`). The node directory arrives as `--config` and
+ * `--log-dir`; agent-node derives NODE_DIR from that absolute config.
+ * Codex's app-server and TUI are separate sessions and pin the project
+ * with `-C` plus `CODEX_HOME`, so this directory is not their project.
+ * A hand-started agent-node never calls this and keeps the person's cwd.
+ */
+export declare function externalAppserverBridgeCwd(plan: Pick<ExternalAppserverPlan, "workspaceDir" | "nodeDir">): string;
+export type ResumedVerdict = {
+    state: "match";
+    seen: string;
+} | {
+    state: "mismatch";
+    seen: string;
+} | {
+    state: "new-thread";
+    seen: string;
+} | {
+    state: "not-seen";
+} | {
+    state: "no-thread-configured";
+};
+/**
+ * Did the bridge resume the configured thread? Reads only the log text written
+ * since this start. agent-node prints `[codex-app-server] resumed thread <12 chars>…`
+ * or `created thread <12 chars>…` (a silent new session). Registration alone
+ * proves nothing about which thread the node is on.
+ */
+export declare function resumedThreadVerdict(logText: string, threadId: string): ResumedVerdict;
+/** True when something is already bound to host:port (a listen attempt fails). */
+export declare function portBusy(host: string, port: number): Promise<boolean>;
+/** Poll `/readyz` until it answers 200 or `timeoutMs` passes. */
+export declare function waitForReadyz(url: string, timeoutMs?: number, intervalMs?: number): Promise<{
+    ok: boolean;
+    status: number;
+    waitedMs: number;
+}>;

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

@@ -0,0 +1,52 @@
+export declare const FORK_RECOVERY_STATE_FILE = "codex-fork-recovery.json";
+export declare const FORK_RECOVERY_SNAPSHOT_DIR = "rollout-snapshots";
+export interface ForkRecoveryOptions {
+    /** --fork-on-resume-failure was passed. */
+    enabled: boolean;
+    /** Correlates a mapping with one Hub start request; never grants confirmation. */
+    requestId?: string;
+    /** --yes was passed (required when there is no terminal to ask). */
+    yes: boolean;
+    /** A human can answer a prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** The recorded thread this start tried to resume. */
+    threadId: string | undefined;
+    codexHome: string;
+    /** <nodes dir>/<node id> — config.json lives here. */
+    nodeDir: string;
+    /** Display name, for messages. */
+    node: string;
+    /** Ask a y/N question; resolves true only for an explicit yes. */
+    confirm: (prompt: string) => Promise<boolean>;
+    now?: () => Date;
+    log?: (line: string) => void;
+}
+export interface ForkMapping {
+    requestId?: string;
+    oldThreadId: string;
+    newThreadId: string;
+    originalRollout: string;
+    snapshot: string;
+    sha256: string;
+    at: string;
+}
+/** Keep this opaque: the Hub owns ID generation, not the CLI. */
+export declare function parseForkRecoveryRequestId(value: string | undefined): string | undefined;
+export declare function sha256OfFile(path: string): string;
+/** The rollout codex named in the error (when it exists), else the shared resolver's pick. */
+export declare function rolloutForMissingOrdinal(message: string, codexHome: string, threadId: string): string | null;
+/** Copy (never move) the rollout into <nodeDir>/rollout-snapshots/ and drop every write bit. */
+export declare function snapshotRollout(original: string, nodeDir: string, now: Date): {
+    path: string;
+    sha256: string;
+};
+export declare function recordForkMapping(nodeDir: string, entry: ForkMapping): string;
+export declare function forkConfirmationText(node: string, threadId: string, original: string): string[];
+/**
+ * Resume as before; on the "missing an ordinal" failure, and only with the flag and a
+ * human's yes, fork instead. `start(false)` resumes the recorded thread; `start(true)`
+ * forks it and resumes the fork. Every other outcome re-throws the original error.
+ */
+export declare function resumeOrForkOnMissingOrdinal<T extends {
+    threadId: string;
+}>(start: (forkFirst: boolean) => Promise<T>, o: ForkRecoveryOptions): Promise<T>;

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

@@ -0,0 +1,88 @@
+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]>;
+}
+/**
+ * 一个 /proc 里的 NUL 分隔块(environ / cmdline)的**原始字节** → JS 字符串,逐条按 UTF-8 解码。
+ *
+ * 🔴 #448 回归:曾经是 `readFileSync(…, "latin1")`,每个字节变成一个 U+00xx。期望值是 JS 字符串
+ *    (UTF-8 路径解码来的),于是**任何非 ASCII 路径**(如 `.anet/nodes/测试节点/codex-home`)
+ *    读出来都是 `æµè¯…` 这种乱码、永远不相等 → fail closed → 该节点每个任务都被拒。
+ *
+ * 某一条不是合法 UTF-8 时,不做有损替换(U+FFFD 可能碰巧和期望值里的 U+FFFD 相等):
+ * 把 `=` 之后的部分换成 INVALID_UTF8_MARK + 原字节的 latin1 —— 以一个孤立代理项开头,
+ * 而合法 UTF-8 解码出来的字符串绝不含孤立代理项,所以它**不可能**等于任何真实路径(fail closed)。
+ */
+export declare const INVALID_UTF8_MARK = "\uDFFF";
+export declare function decodeProcNulBlock(bytes: Uint8Array): string;
+/** 合法 UTF-8 解码不出孤立代理项;含孤立代理项的值(INVALID_UTF8_MARK)不能拿来和任何东西比相等。 */
+export declare function hasLoneSurrogate(s: string): boolean;
+/** 读 /proc/<pid>/<file>(environ / cmdline)并逐条按 UTF-8 解码;读不到返回 null。 */
+export declare function readProcNulBlock(pid: number, file: "environ" | "cmdline"): string | null;
+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;

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

@@ -0,0 +1,104 @@
+import type { ReceiptCheck } from "./codex-lifecycle-receipt.js";
+import type { RestartOutcome } from "./codex-lifecycle-restart.js";
+export declare const SOURCE_KIND = "codex-login-profile";
+/** `--source` 只接受 `codex-login:<profile-id>`。路径、`env:`、`-`(stdin)、绝对/相对路径都拒绝,错误里说清为什么。 */
+export declare function parseSourceRef(raw: string): {
+    kind: typeof SOURCE_KIND;
+    profileId: string;
+};
+export declare function shortHash(value: string, length?: number): string;
+/** host_id:machine-id(有则用)+ hostname 的不可逆摘要;registry entry 绑定它,拷到别的机器就不认。 */
+export declare function hostIdOf(machineId: string | null, hostname: string): string;
+export interface ChatgptAuthShape {
+    auth_mode?: unknown;
+    tokens?: {
+        account_id?: unknown;
+    } | null;
+    OPENAI_API_KEY?: unknown;
+}
+/** 只认 ChatGPT 登录:auth_mode=chatgpt 且 tokens.account_id 是 36 位 uuid;指纹 = sha256(account_id) 前 16 位。 */
+export declare function accountFingerprint(auth: ChatgptAuthShape): string;
+export interface RegistryEntry {
+    schema_version: 1;
+    profile_id: string;
+    provider: "openai-chatgpt";
+    host_id: string;
+    /** 由 registry 目录解析的相对引用;从不是绝对路径。 */
+    credential_ref: string;
+    account_fingerprint: string;
+    created_at: string;
+    last_model_probe_at: string | null;
+    last_model_probe_status: ProbeStatus | null;
+    revoked: boolean;
+    disabled: boolean;
+}
+export interface Registry {
+    schema_version: 1;
+    host_id: string;
+    profiles: Record<string, RegistryEntry>;
+}
+export type ProbeStatus = "ok" | "auth" | "quota" | "model" | "unknown";
+export declare function credentialRefFor(profileId: string): string;
+export declare function credentialPath(registryDir: string, entry: RegistryEntry): string;
+export declare function readRegistry(registryDir: string, hostId: string): Registry;
+export declare function writeRegistry(registryDir: string, reg: Registry): void;
+/** 解析一个 profile:必须存在、未 revoked/disabled、host_id 一致、凭据文件在且 0600。返回凭据路径(只在进程内用,不进 receipt)。 */
+export declare function resolveProfile(registryDir: string, reg: Registry, profileId: string, hostId: string): {
+    entry: RegistryEntry;
+    credentialFile: string;
+};
+/** 把一次 fresh 模型请求的结果归类;归不进已知类的一律 unknown(unknown 也 STOP,不猜)。 */
+export declare function classifyProbe(exitCode: number | null, stdout: string, stderr: string, expected?: string): ProbeStatus;
+export declare function backupRefFor(receiptId: string): string;
+/** rollback 只认 `receipt:<id>`,且只在该节点的 receipts/ 目录里解析;调用方不能另指文件。 */
+export declare function backupPathFor(nodeDir: string, backupRef: string): string;
+export interface InstallActions {
+    /** 目标节点 before 核对:返回 fail 的 key(空 = 可继续)。 */
+    preflightBlocks(): Promise<string[]>;
+    /** 目标当前 auth 指纹(没有 auth.json → null)。 */
+    currentFingerprint(): Promise<string | null>;
+    /** 在隔离 staging HOME 里用该 profile 发一次 fresh 模型请求。 */
+    probe(): Promise<{
+        status: ProbeStatus;
+        detail: string;
+    }>;
+    /** 备份目标 auth.json → backup_ref(0600)。 */
+    backup(): Promise<{
+        backupRef: string;
+    }>;
+    /** 把 profile 凭据装进目标 CODEX_HOME(0600,原子)。 */
+    install(): Promise<void>;
+    /** 完整重启(PR-B 状态机),返回其 outcome。 */
+    restart(): Promise<RestartOutcome>;
+    /** 从 backup_ref 恢复 auth.json。 */
+    restore(backupRef: string): Promise<void>;
+    /** 探针在 registry 里的回写(时间 + 状态)。 */
+    recordProbe(status: ProbeStatus): Promise<void>;
+}
+export interface InstallInput {
+    profileId: string;
+    sourceFingerprint: string;
+}
+export interface InstallOutcome {
+    checks: ReceiptCheck[];
+    stoppedAt: string;
+    rolledBack: boolean;
+    backupRef: string | null;
+}
+/**
+ * account install 状态机:preflight → fresh 探针(401/quota/模型不兼容/unknown 都 STOP,目标一字未动)→ 备份 → 安装 →
+ * 完整重启(含 verify)→ 目标指纹 == 源指纹。安装后任一步失败 → 恢复备份 + 再重启一次(回滚),receipt 记两段。
+ */
+export declare function runAccountInstall(input: InstallInput, a: InstallActions): Promise<InstallOutcome>;
+export interface RollbackActions {
+    /** 读原 install receipt;返回它的 backup_ref 与当时的 target_previous_fingerprint。 */
+    readInstallReceipt(): Promise<{
+        backupRef: string;
+        targetPreviousFingerprint: string | null;
+    } | null>;
+    backupExists(backupRef: string): Promise<boolean>;
+    restore(backupRef: string): Promise<void>;
+    restart(): Promise<RestartOutcome>;
+    currentFingerprint(): Promise<string | null>;
+}
+export declare function runRollback(a: RollbackActions): Promise<InstallOutcome>;

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

@@ -0,0 +1,20 @@
+/**
+ * #1856 PR-E — `anet node codex canary <alias>...`:批量只读体检,**顺序跑、第一个 FAIL 即停**。
+ * 批量重启 / 换账号之前先 canary;后面的节点一个都不碰,汇总里明确写"未跑"。纯逻辑,verify 由调用方注入。
+ */
+export interface CanaryNodeResult {
+    readonly alias: string;
+    readonly verdict: "PASS" | "FAIL";
+    readonly blocking: readonly string[];
+    readonly receiptPath: string | null;
+    readonly ms: number;
+}
+export interface CanarySummary {
+    readonly verdict: "PASS" | "FAIL";
+    readonly ran: readonly CanaryNodeResult[];
+    /** 因前面 FAIL 而没跑的节点(顺序保留)。 */
+    readonly skipped: readonly string[];
+    readonly stoppedAt: string | null;
+}
+export declare function runCanary(aliases: readonly string[], verifyOne: (alias: string) => Promise<Omit<CanaryNodeResult, "alias" | "ms">>, now?: () => number): Promise<CanarySummary>;
+export declare function formatCanarySummary(s: CanarySummary): string;

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

@@ -0,0 +1,53 @@
+import type { PreflightFacts, ProcessFact, RolloutFact } from "./codex-lifecycle-preflight";
+export interface FactPrimitives {
+    /** tmux pane pid of a session, or null when the session is not running. */
+    tmuxPanePid(session: string): number | null;
+    /** all pids (Linux /proc); [] elsewhere */
+    listPids(): number[];
+    procStatPpid(pid: number): number | null;
+    procCwd(pid: number): string | null;
+    procArgv(pid: number): string[] | null;
+    procEnviron(pid: number): Record<string, string> | null;
+    /** pid listening on a loopback TCP port, or null (free / unknown) */
+    listeningPid(port: number): number | null;
+    /** hub roster: alias → node_id, or null when unreachable */
+    hubNodeIdFor(alias: string): Promise<string | null>;
+}
+export declare function realPrimitives(opts: {
+    hub: string;
+    token: string;
+    networkId?: string;
+}): FactPrimitives;
+export declare function envFileTokenFingerprint(codexHome: string): string | null;
+/** rollout-*-<threadId>.jsonl under CODEX_HOME/sessions/**;精确后缀匹配,不做前缀/最近猜测。 */
+export declare function findRollouts(codexHome: string, threadId: string | null): RolloutFact[];
+/** 从 pane pid 往下找子孙进程(含自身),按 pid 升序。 */
+export declare function descendants(prim: FactPrimitives, rootPid: number): number[];
+export declare function processFact(prim: FactPrimitives, pid: number): ProcessFact;
+export interface GatherInput {
+    alias: string;
+    nodeId: string | null;
+    nodeDir: string;
+    codexHome: string;
+    configToken: string | null;
+    codexProjectDir: string | null;
+    codexThreadId: string | null;
+    codexAppServerUrl: string | null;
+    sessions: {
+        appsrv: string;
+        bridge: string;
+        tui: string;
+    };
+    recordedPids: {
+        appsrv: number | null;
+        bridge: number | null;
+        tui: number | null;
+    };
+    markerUuid: string | null;
+}
+/** ⑨ goals.json → 状态摘要 + 内容指纹。没有文件 = none(没派过目标);有文件但 schema 不认识/读不到 = unknown(restart 必须 STOP)。 */
+export declare function goalsFileState(nodeDir: string): {
+    state: "active" | "stalled" | "paused" | "achieved" | "none" | "unknown";
+    fingerprint: string | null;
+};
+export declare function gatherCodexFacts(prim: FactPrimitives, input: GatherInput): Promise<PreflightFacts>;

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

@@ -0,0 +1,91 @@
+import type { ReceiptCheck } from "./codex-lifecycle-receipt.js";
+/** Codex 的 thread id 是 UUIDv7(时间有序);fork 出的新 id 也按 v7 生成,便于按文件名/id 排序时落在源之后。 */
+export declare function uuidV7(nowMs: number, rand: Uint8Array): string;
+/** codex 的 rollout 路径:sessions/YYYY/MM/DD/rollout-YYYY-MM-DDTHH-MM-SS-<id>.jsonl(UTC)。 */
+export declare function forkRolloutPath(codexHome: string, now: Date, threadId: string): string;
+/** CODEX_HOME 里哪些文件随 fork 走。显式白名单;env 文件(含源节点 CommHub token)、历史、sqlite、缓存一律不带。 */
+export declare const FORK_HOME_COPY: readonly {
+    name: string;
+    required: boolean;
+    mode: number;
+}[];
+export declare const FORK_HOME_NEVER_COPY: readonly string[];
+export interface RolloutRewriteResult {
+    readonly lines: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    /** 源 thread id 改写次数(定长,不改字节数)。 */
+    readonly replacements: number;
+    /** `"cwd":"<源目录>"` 改写次数(session_meta + 每个 turn_context 都带;改成新 workdir,字节数按长度差变化)。 */
+    readonly cwdReplacements: number;
+    /** = bytesIn + cwdReplacements × (新 cwd 编码长度 − 旧 cwd 编码长度);fork_isolation 用它核对复制没有丢字节。 */
+    readonly expectedBytesOut: number;
+}
+/**
+ * 流式复制 rollout 并把源 thread id 逐处改成新 id(两者定长 36 字符 → 字节数不变,可作 fork_isolation 的证据)。
+ * 第一行校验失败时目标文件不存在(先读第一行再开写)。
+ */
+export declare function rewriteRollout(src: string, dst: string, oldId: string, newId: string, cwd?: {
+    from: string;
+    to: string;
+}): Promise<RolloutRewriteResult>;
+export interface ForkSides {
+    readonly source: {
+        nodeId: string | null;
+        homeReal: string | null;
+        threadId: string | null;
+        alias: string;
+        rolloutInode: number | bigint | null;
+        rolloutBytes: number | null;
+    };
+    readonly target: {
+        nodeId: string | null;
+        homeReal: string | null;
+        threadId: string | null;
+        alias: string;
+        rolloutInode: number | bigint | null;
+        rolloutBytes: number | null;
+        envFilePresent: boolean;
+    };
+    readonly rewrite: RolloutRewriteResult | null;
+}
+/** fork_isolation:身份 / HOME / thread / rollout 文件 / tmux 名五处都不同,且 rollout 是等长复制、没带 token 文件。 */
+export declare function checkForkIsolation(s: ForkSides): ReceiptCheck;
+/** gap 1 — `--workdir` used to have to pre-exist. Create it (recursively) when missing; still refuse a path that exists
+ * but is not a directory. Returns whether this call created it, so the receipt can say so. */
+export declare function ensureForkWorkdir(path: string): {
+    created: boolean;
+};
+/**
+ * gap 2 — codex records trust per workspace as `[projects."<abs path>"]` tables in config.toml. A copied config still
+ * names the **source** workspace, so the target keeps trusting (and, in the TUI, offering) the wrong directory.
+ * Rewrite only the table headers whose quoted path equals `from`, to `to`; every other line is left byte-identical.
+ * If a `[projects."<to>"]` table already exists, the source table is dropped instead of duplicated (TOML forbids
+ * defining a table twice). Line-aware on purpose: no global substitution of the path string elsewhere in the file.
+ */
+export declare function rewriteTrustedProjects(toml: string, from: string, to: string): {
+    text: string;
+    rewritten: number;
+    dropped: number;
+};
+/**
+ * gap 3 — the last `turn_context` in a rollout names the model (and provider) the source ran on; codex resumes with
+ * that unless the target config says otherwise. Read it from the tail of the file (rollouts reach hundreds of MB;
+ * never load the whole thing) so `fork --model` can warn when the override differs.
+ */
+export declare function readLastTurnContextModel(rolloutPath: string, tailBytes?: number): {
+    model: string | null;
+    provider: string | null;
+};
+/** What the fork receipt records for the #1951 gaps, as one informational check (never blocks; `port` is the
+ * loopback port pre-assigned for the app-server, first start uses it as its preferred port and re-probes if taken). */
+export interface ForkGapFacts {
+    readonly workdir_created: boolean;
+    readonly trusted_rewritten: number;
+    readonly trusted_dropped: number;
+    readonly model_override: string | null;
+    readonly source_last_model: string | null;
+    readonly port: number | null;
+    readonly agents_md_carried: boolean;
+}
+export declare function forkGapsCheck(f: ForkGapFacts): ReceiptCheck;