@sleep2agi/agent-network 2.3.0-preview.11 → 2.3.0-preview.111

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,43 @@
+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;
+export declare function resumeAndVerifyCodexThread(threadId: string, request: (method: string, params: Record<string, unknown>) => Promise<unknown>): Promise<CodexRecoveryVerification>;
+/** 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-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;

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

@@ -0,0 +1,77 @@
+import type { ReceiptCheck } from "./codex-lifecycle-receipt";
+export interface RolloutFact {
+    readonly path: string;
+    readonly inode: number | bigint;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+}
+export interface ProcessFact {
+    readonly pid: number;
+    readonly cwd: string | null;
+    /** 子进程实际环境里的 CODEX_HOME(不是 wrapper 继承的那份 —— wrapper 环境不能作承重证据)。 */
+    readonly codexHome: string | null;
+    /** 子进程实际环境里 CommHub token 的短指纹;null = 没读到或该进程不该持有。 */
+    readonly tokenFingerprint: string | null;
+    /** 子进程环境里的 ANET_NODE_MARKER(copresence-identity 的身份 uuid);null = 没有。 */
+    readonly markerUuid: string | null;
+    readonly argv: readonly string[];
+}
+export interface PreflightFacts {
+    readonly alias: string;
+    readonly configNodeId: string | null;
+    /** hub 名册按 alias 精确查到的 node_id;null = hub 不可达或没这个 alias。 */
+    readonly hubNodeId: string | null;
+    readonly home: {
+        readonly dir: string;
+        readonly dirMode: number | null;
+        readonly authMode: number | null;
+        readonly authBytes: number | null;
+        readonly configTokenFingerprint: string | null;
+        readonly envFileTokenFingerprint: string | null;
+    };
+    readonly workdir: {
+        readonly configProjectDir: string | null;
+        readonly tuiCwd: string | null;
+        readonly tuiArgvDir: string | null;
+        readonly bridgeProjectDir: string | null;
+        readonly statusBarDir: string | null;
+    };
+    readonly session: {
+        readonly threadId: string | null;
+        /** CODEX_HOME 里文件名以 <threadId>.jsonl 结尾的 rollout 全集。 */
+        readonly rolloutMatches: readonly RolloutFact[];
+    };
+    readonly port: {
+        readonly port: number | null;
+        readonly owner: ProcessFact | null;
+    };
+    readonly topology: {
+        /** copresence-identity.json 里的身份 uuid;null = 没有 marker 文件。 */
+        readonly markerUuid: string | null;
+        /** marker 里记的 pid(采集时的观测提示,**不是**身份来源)与现在 tmux pane 的 pid。 */
+        readonly recorded: Readonly<Record<"appsrv" | "bridge" | "tui", number | null>>;
+        readonly live: Readonly<Record<"appsrv" | "bridge" | "tui", number | null>>;
+        /** 每个 tmux 段下带环境的子进程各自的 ANET_NODE_MARKER。 */
+        readonly liveMarkers: Readonly<Record<"appsrv" | "bridge" | "tui", readonly (string | null)[]>>;
+        /** 每个 tmux 段下带环境的子进程各自的 CODEX_HOME(realpath)。 */
+        readonly liveHomes: Readonly<Record<"appsrv" | "bridge" | "tui", readonly (string | null)[]>>;
+    };
+    readonly goal: {
+        readonly state: "active" | "stalled" | "paused" | "achieved" | "none" | "unknown";
+    };
+    readonly children: readonly ProcessFact[];
+    readonly expectedTokenFingerprint: string | null;
+}
+export declare function checkIdentity(f: PreflightFacts): ReceiptCheck;
+export declare function checkHome(f: PreflightFacts): ReceiptCheck;
+export declare function checkWorkdir(f: PreflightFacts): ReceiptCheck;
+export declare function checkSession(f: PreflightFacts): ReceiptCheck;
+export declare function rolloutSnapshot(f: PreflightFacts): ReceiptCheck;
+export declare function compareRollout(before: RolloutFact, after: RolloutFact | null): ReceiptCheck;
+export declare function checkPortOwner(f: PreflightFacts): ReceiptCheck;
+export declare function checkChildEnv(f: PreflightFacts): ReceiptCheck;
+export declare function checkGoalState(f: PreflightFacts): ReceiptCheck;
+export declare function checkTopology(f: PreflightFacts): ReceiptCheck;
+export declare function evaluateCodexPreflight(f: PreflightFacts): ReceiptCheck[];
+/** verify = preflight + 子进程环境 + 跨节点身份验收(identity_attested 由调用方注入;PR-A 里没有探针时给 unknown)。 */
+export declare function evaluateCodexVerify(f: PreflightFacts, identityAttested: ReceiptCheck): ReceiptCheck[];

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

@@ -0,0 +1,44 @@
+export type CheckStatus = "pass" | "fail" | "unknown";
+export interface ReceiptCheck {
+    readonly key: string;
+    readonly status: CheckStatus;
+    /** 一句人话:pass 说核到了什么,fail 说差在哪,unknown 说为什么量不到。 */
+    readonly detail: string;
+    /** 可复核的证据(路径、inode、字节数、短指纹……);不得含凭据。 */
+    readonly evidence?: Readonly<Record<string, unknown>>;
+}
+export type LifecycleVerb = "preflight" | "verify" | "start" | "restart" | "resume" | "fork" | "account-install" | "rollback";
+export interface LifecycleReceipt {
+    readonly format: "anet-codex-lifecycle-receipt/1";
+    readonly id: string;
+    readonly verb: LifecycleVerb;
+    readonly alias: string;
+    readonly nodeId: string | null;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly verdict: "PASS" | "FAIL";
+    /** FAIL 时阻塞的 check key(fail 与 unknown 都算)。 */
+    readonly blocking: readonly string[];
+    readonly checks: readonly ReceiptCheck[];
+}
+/** 每个动词要求哪些 check 必须 pass。preflight 只读,不要求 identity_attested(那是 verify 的活)。 */
+export declare const REQUIRED_CHECKS: Readonly<Record<LifecycleVerb, readonly string[]>>;
+export declare function shortFingerprint(value: string | undefined | null, length?: number): string | null;
+export declare function redactReceipt<T>(value: T, key?: string): T;
+export declare const INFORMATIONAL_PREFIXES: readonly string[];
+export declare function receiptVerdict(verb: LifecycleVerb, checks: readonly ReceiptCheck[]): {
+    verdict: "PASS" | "FAIL";
+    blocking: string[];
+};
+export declare function buildReceipt(opts: {
+    verb: LifecycleVerb;
+    alias: string;
+    nodeId: string | null;
+    startedAt: Date;
+    finishedAt?: Date;
+    checks: readonly ReceiptCheck[];
+}): LifecycleReceipt;
+/** receipts 落在节点目录下 receipts/<id>.json,0600,先写临时文件再 rename(原子)。返回绝对路径。 */
+export declare function writeReceipt(nodeDir: string, receipt: LifecycleReceipt): string;
+/** 终端摘要:一行一 check,PASS/FAIL 在最后;不打印 evidence 里的长值。 */
+export declare function formatReceiptSummary(receipt: LifecycleReceipt): string;

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

@@ -0,0 +1,86 @@
+/**
+ * #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 记 unknown)。 */
+    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;
+}
+/** 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>;