@evomap/evolver-proxy 2.0.0-beta.0

package/dist/daemon/selectHub.d.ts

@@ -0,0 +1,16 @@
+export type HubMode = 'public' | 'private';
+/** 据 EVOMAP_HUB_MODE 选 hub 实现(public|private). 缺省 public. bin 据此挂对应 adapter. */
+export declare function resolveHubMode(env: Record<string, string | undefined>): HubMode;
+export declare function resolveHubUrl(env: Record<string, string | undefined>): string;
+/**
+ * Actionable hint for a hub AUTH failure (401/403), tailored to the hub's error code so it does NOT misdirect
+ * (#314). In the default PUBLIC mode the proxy DOES send a node_secret for a registered public node, so a 401 has
+ * two distinct causes that need opposite remedies:
+ *  - `a2a_auth_required`: the hub demanded a credential the public adapter never sends. Since public mode already
+ *    sends node_secret, this points at a self-hosted PRIVATE hub. Remedy: switch to private mode.
+ *  - any other auth error (credential rejected/invalid): the node_secret WAS sent but rejected, i.e. a public-hub
+ *    credential problem (expired/revoked). Remedy: re-register the node. Private mode is only a secondary guess.
+ * Returns '' in PRIVATE mode (a 401 there is a token/credential problem with its own startup errors).
+ * Pure and non-throwing (unlike resolveHubMode), so it is safe to call on the error path.
+ */
+export declare function hubAuthFailureHint(env: Record<string, string | undefined>, errorText?: string): string;

package/dist/daemon/selectHub.js

@@ -0,0 +1,30 @@
+/** 据 EVOMAP_HUB_MODE 选 hub 实现(public|private). 缺省 public. bin 据此挂对应 adapter. */
+export function resolveHubMode(env) {
+    const m = (env['EVOMAP_HUB_MODE'] ?? 'public').toLowerCase();
+    if (m !== 'public' && m !== 'private')
+        throw new Error(`EVOMAP_HUB_MODE 非法: ${m}(public|private)`);
+    return m;
+}
+export function resolveHubUrl(env) {
+    return env['EVOMAP_HUB_URL'] ?? 'https://dev.evomap.ai';
+}
+/**
+ * Actionable hint for a hub AUTH failure (401/403), tailored to the hub's error code so it does NOT misdirect
+ * (#314). In the default PUBLIC mode the proxy DOES send a node_secret for a registered public node, so a 401 has
+ * two distinct causes that need opposite remedies:
+ *  - `a2a_auth_required`: the hub demanded a credential the public adapter never sends. Since public mode already
+ *    sends node_secret, this points at a self-hosted PRIVATE hub. Remedy: switch to private mode.
+ *  - any other auth error (credential rejected/invalid): the node_secret WAS sent but rejected, i.e. a public-hub
+ *    credential problem (expired/revoked). Remedy: re-register the node. Private mode is only a secondary guess.
+ * Returns '' in PRIVATE mode (a 401 there is a token/credential problem with its own startup errors).
+ * Pure and non-throwing (unlike resolveHubMode), so it is safe to call on the error path.
+ */
+export function hubAuthFailureHint(env, errorText = '') {
+    const mode = (env['EVOMAP_HUB_MODE'] ?? 'public').toLowerCase();
+    if (mode === 'private')
+        return '';
+    if (/a2a_auth_required/i.test(errorText)) {
+        return 'the hub required an auth credential the public adapter does not send, which points to a private hub. Set EVOMAP_HUB_MODE=private and provide the private adapter (@evomap/evolver-adapter-private, or point EVOMAP_PRIVATE_ADAPTER_MODULE at a local build) plus an enterprise token (EVOMAP_ENTERPRISE_TOKEN).';
+    }
+    return 'the hub rejected the node credential. If this is a private hub, set EVOMAP_HUB_MODE=private with the private adapter and an enterprise token; otherwise the public node secret may be expired or revoked, so re-register the node.';
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const PACKAGE = "@evomap/evolver-proxy";
+export * from './sync/engine.js';
+export * from './lifecycle/manager.js';
+export * from './daemon/proxyDaemon.js';
+export * from './lifecycle/deployGuard.js';
+export * from './router/index.js';
+export * from './llm/index.js';
+export * from './selfUpdate/index.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export const PACKAGE = '@evomap/evolver-proxy';
+export * from './sync/engine.js';
+export * from './lifecycle/manager.js';
+export * from './daemon/proxyDaemon.js';
+export * from './lifecycle/deployGuard.js';
+export * from './router/index.js';
+export * from './llm/index.js';
+export * from './selfUpdate/index.js';

package/dist/lifecycle/deployGuard.d.ts

@@ -0,0 +1,46 @@
+import { mailbox, shadow as shadow_ } from '@evomap/evolver-core';
+type MailboxStore = mailbox.MailboxStore;
+type ShadowMode = shadow_.ShadowMode;
+export interface DeployLockInfo {
+    version: string;
+    pid: number;
+    at: number;
+}
+/**
+ * .evolver.lock 幂等(M8-3, v1.81 教训): 同 version 重试部署 = 可重入(不重复 apply);
+ * 不同 version 持锁中 = 拒(防并发半失败); 过期锁(超 staleMs)= 接管.
+ */
+export declare function acquireDeployLock(lockPath: string, version: string, pid: number, now: number, staleMs?: number): {
+    acquired: boolean;
+    reentrant: boolean;
+    existing?: DeployLockInfo;
+};
+export declare function releaseDeployLock(lockPath: string): void;
+export interface PreStopResult {
+    safe: boolean;
+    issues: string[];
+    inFlight: number;
+    shadowPinned: boolean;
+}
+/**
+ * 停机前状态冻结检查(M8-3, 配 daemon 闸2 drain). enforce 下 in_flight 消息=潜在孤儿(丢进化证据)→ issue;
+ * **shadow 下 in_flight 是故意留的(complete no-op), 不算孤儿**(gotcha: 区分 shadow-pinned vs 真孤儿)。
+ */
+export declare function preStopChecks(opts: {
+    store: MailboxStore;
+    shadowMode: ShadowMode;
+    lastWriteAt: number;
+    now: number;
+    maxStaleMs?: number;
+}): PreStopResult;
+export interface DeployEnvInput {
+    gitUserName?: string;
+    gitUserEmail?: string;
+    lockfilesAligned: boolean;
+}
+/** 部署 fail-fast(M8-3, v1.81 教训): git identity 配齐 + npm·bun lockfile 对齐, 否则拒部署防半失败. */
+export declare function verifyDeployEnv(c: DeployEnvInput): {
+    ok: boolean;
+    failures: string[];
+};
+export {};

package/dist/lifecycle/deployGuard.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mailbox, shadow as shadow_ } from '@evomap/evolver-core';
+/**
+ * .evolver.lock 幂等(M8-3, v1.81 教训): 同 version 重试部署 = 可重入(不重复 apply);
+ * 不同 version 持锁中 = 拒(防并发半失败); 过期锁(超 staleMs)= 接管.
+ */
+export function acquireDeployLock(lockPath, version, pid, now, staleMs = 10 * 60_000) {
+    if (existsSync(lockPath)) {
+        try {
+            const info = JSON.parse(readFileSync(lockPath, 'utf8'));
+            if (info.version === version)
+                return { acquired: true, reentrant: true, existing: info }; // 同版本重试
+            if (now - info.at < staleMs)
+                return { acquired: false, reentrant: false, existing: info }; // 他版本持锁中
+            // 过期 → 接管
+        }
+        catch { /* 坏锁文件 → 接管 */ }
+    }
+    mkdirSync(dirname(lockPath), { recursive: true });
+    writeFileSync(lockPath, JSON.stringify({ version, pid, at: now }));
+    return { acquired: true, reentrant: false };
+}
+export function releaseDeployLock(lockPath) { try {
+    rmSync(lockPath);
+}
+catch { /* ignore */ } }
+/**
+ * 停机前状态冻结检查(M8-3, 配 daemon 闸2 drain). enforce 下 in_flight 消息=潜在孤儿(丢进化证据)→ issue;
+ * **shadow 下 in_flight 是故意留的(complete no-op), 不算孤儿**(gotcha: 区分 shadow-pinned vs 真孤儿)。
+ */
+export function preStopChecks(opts) {
+    const issues = [];
+    const inFlight = opts.store.countByStatus('in_flight');
+    const shadowPinned = opts.shadowMode === 'shadow';
+    if (!shadowPinned && inFlight > 0)
+        issues.push(`${inFlight} 条 in_flight 消息未完成(潜在孤儿, 须 drain 后再停)`);
+    const stale = opts.now - opts.lastWriteAt;
+    if (opts.maxStaleMs !== undefined && stale > opts.maxStaleMs)
+        issues.push(`root_events 已 ${Math.round(stale / 1000)}s 无写入(疑挂死)`);
+    return { safe: issues.length === 0, issues, inFlight, shadowPinned };
+}
+/** 部署 fail-fast(M8-3, v1.81 教训): git identity 配齐 + npm·bun lockfile 对齐, 否则拒部署防半失败. */
+export function verifyDeployEnv(c) {
+    const failures = [];
+    if (!c.gitUserName)
+        failures.push('git user.name 未配');
+    if (!c.gitUserEmail)
+        failures.push('git user.email 未配');
+    if (!c.lockfilesAligned)
+        failures.push('npm·bun lockfile 不对齐');
+    return { ok: failures.length === 0, failures };
+}

package/dist/lifecycle/legacyNodeId.d.ts

@@ -0,0 +1,96 @@
+export interface LegacyNodeIdCandidateOptions {
+    /** Test seam for platform-independent home probing; production uses os.homedir(). */
+    homeDir?: string;
+    /** Test seam for source/dist/package-layout probing; production uses this module dir. */
+    moduleDir?: string;
+    /** Test seam for override-aware evomap home; production resolves env overrides at call time. */
+    evomapHomeDir?: string;
+    /** Test seam for the EVOMAP_DIR root; production reads process.env['EVOMAP_DIR'] at call time. */
+    evomapDir?: string;
+}
+/**
+ * Legacy node_id file locations, in priority order. Mirror of v1
+ * `_loadPersistedNodeId`:
+ *
+ *  0. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
+ *     anti-abuse code write under (`recipeHomeCandidates` puts EVOMAP_DIR ahead
+ *     of EVOLVER_HOME/EVOMAP_HOME). `resolveEvomapHome` never consults EVOMAP_DIR,
+ *     so a deployment that pivots on it would otherwise send no node_id on hello
+ *     and let the hub mint a duplicate. Probed FIRST and ADDITIVELY (the
+ *     EVOLVER_HOME/EVOMAP_HOME candidates below are kept), so setting EVOMAP_DIR
+ *     never hides an id that lives under one of the home overrides. Deduped.
+ *  1. `<evomapHome>/node_id` — the override-aware home file. `resolveEvomapHome()`
+ *     honours EVOLVER_HOME (matching v1 `getEvomapDir`) and ADDITIONALLY
+ *     EVOMAP_HOME after dropping blank/relative overrides. It wins first so a
+ *     home relocated via EVOLVER_HOME reads the file the v1 writer put there —
+ *     the lesson of v1 #120, which routed the reader through the same helper as
+ *     the writer.
+ *  2. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
+ *     `getEvomapDir` = `EVOLVER_HOME || ~/.evomap` and ignores EVOMAP_HOME
+ *     entirely, so unless EVOLVER_HOME was set a v1 file always physically lands
+ *     here. We probe it explicitly so a v2 install that sets only EVOMAP_HOME
+ *     (which steers candidate 1 away from `~/.evomap`) still recovers the v1
+ *     identity instead of letting the hub mint a duplicate orphan node. Deduped
+ *     against candidate 1 for the common no-override case where they coincide.
+ *  3. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
+ *     back to when `~/.evomap/` isn't writable (read-only $HOME in
+ *     containers / restricted CI). Kept first for parity with the old v2
+ *     candidate.
+ *  4. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
+ *     root fallback. In v2's multi-package layout the proxy code lives below
+ *     `packages/evolver-proxy`, so only checking the proxy package root misses
+ *     a file written at the install/workspace root.
+ *
+ * Resolved on every call rather than cached at module load: env and `homedir()`
+ * are read at call time, so caching would freeze the home path and silently
+ * ignore a later EVOLVER_HOME/EVOMAP_HOME change (this is also how the tests
+ * point it at a tmp dir). The install-root paths use a bounded package.json walk
+ * from the module dir so source and dist layouts both work.
+ */
+export declare function legacyNodeIdCandidates(opts?: LegacyNodeIdCandidateOptions): string[];
+export interface ReadLegacyNodeIdOptions extends LegacyNodeIdCandidateOptions {
+    /** Override the candidate file list (tests inject tmp paths). */
+    candidates?: string[];
+}
+/**
+ * Recover a node_id persisted by the legacy v1 GEP path. Returns the first
+ * candidate file whose trimmed contents match NODE_ID_RE, else `undefined`.
+ *
+ * Why this exists (PORT v1 #117): v2 resolves the wire node_id as
+ * `store.node_id ?? EVOMAP_NODE_ID/A2A_NODE_ID`. When BOTH are empty the
+ * `/a2a/hello` payload carries no `node_id` and the hub MINTS A FRESH A2ANode,
+ * which the lifecycle manager then persists. So any install whose mailbox
+ * store was created (or wiped) after a v1 `~/.evomap/node_id` already existed —
+ * an upgrade from a pre-lifecycle version, or a partial recovery flow —
+ * silently registers a brand-new node under the same owner on the very next
+ * daemon boot, abandoning the original record (with its stake / reputation /
+ * aliases) as an orphan in the web UI. Reading the legacy file between the
+ * store/env lookup and the hub mint keeps both code paths agreeing on a single
+ * identity.
+ */
+export declare function readLegacyNodeId(opts?: ReadLegacyNodeIdOptions): string | undefined;
+export interface ResolveProxyNodeIdOptions {
+    /** Persisted store value (`store.getState('node_id')`). */
+    storedNodeId: string | undefined;
+    /** Operator env override (`EVOMAP_NODE_ID` / `A2A_NODE_ID`). */
+    configuredNodeId: string | undefined;
+    /** Legacy-file reader seam (defaults to {@link readLegacyNodeId}). */
+    readLegacy?: () => string | undefined;
+}
+/**
+ * Resolve the node_id the proxy presents on the wire, in priority order:
+ * persisted store value → operator env override → recovered legacy file →
+ * `undefined` (the hub mints a fresh id on hello). An explicit env override
+ * outranks the legacy file because the operator set it deliberately.
+ *
+ * The legacy read only fires while the store is unprimed AND no env override
+ * is set — the first-boot window before a successful hello persists an id.
+ * Already-registered nodes short-circuit on the store value and never touch
+ * the filesystem.
+ *
+ * Empty / whitespace store and env values are normalised to `undefined` first:
+ * `??` alone treats `''` as a present value, so a blank `EVOMAP_NODE_ID=` (or a
+ * store cleared to `''`) would otherwise suppress legacy recovery and put a
+ * blank id on the wire — the exact orphan-node failure this module prevents.
+ */
+export declare function resolveProxyNodeId(opts: ResolveProxyNodeIdOptions): string | undefined;

package/dist/lifecycle/legacyNodeId.js

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Hub nodeId shape; mirror of v1 `src/gep/a2aProtocol.js` NODE_ID_RE so a
+ * malformed legacy file can never feed garbage onto the hello wire.
+ */
+const NODE_ID_RE = /^node_[a-f0-9]{12,32}$/;
+const PROXY_PACKAGE_NAME = '@evomap/evolver-proxy';
+const OUTER_INSTALL_PACKAGE_NAMES = new Set(['@evomap/evolver', 'evolver-v2']);
+const MAX_PACKAGE_ROOT_DEPTH = 8;
+const _moduleDir = dirname(fileURLToPath(import.meta.url));
+function cleanAbsolutePath(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return isAbsolute(trimmed) ? trimmed : undefined;
+}
+function resolveEvomapHome(opts, fallbackHomeDir) {
+    return cleanAbsolutePath(opts.evomapHomeDir)
+        ?? cleanAbsolutePath(process.env['EVOLVER_HOME'])
+        ?? cleanAbsolutePath(process.env['EVOMAP_HOME'])
+        ?? (fallbackHomeDir === undefined ? undefined : join(fallbackHomeDir, '.evomap'));
+}
+function packageNameAt(dir) {
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.name === 'string' ? pkg.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function installRootNodeIdCandidates(moduleDir) {
+    const candidates = [];
+    let dir = moduleDir;
+    let sawProxyPackage = false;
+    for (let depth = 0; depth < MAX_PACKAGE_ROOT_DEPTH; depth += 1) {
+        const name = packageNameAt(dir);
+        if (name !== undefined) {
+            if (name === PROXY_PACKAGE_NAME)
+                sawProxyPackage = true;
+            if (name === PROXY_PACKAGE_NAME || (sawProxyPackage && OUTER_INSTALL_PACKAGE_NAMES.has(name))) {
+                candidates.push(join(dir, '.evomap_node_id'));
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return candidates;
+}
+/**
+ * Legacy node_id file locations, in priority order. Mirror of v1
+ * `_loadPersistedNodeId`:
+ *
+ *  0. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
+ *     anti-abuse code write under (`recipeHomeCandidates` puts EVOMAP_DIR ahead
+ *     of EVOLVER_HOME/EVOMAP_HOME). `resolveEvomapHome` never consults EVOMAP_DIR,
+ *     so a deployment that pivots on it would otherwise send no node_id on hello
+ *     and let the hub mint a duplicate. Probed FIRST and ADDITIVELY (the
+ *     EVOLVER_HOME/EVOMAP_HOME candidates below are kept), so setting EVOMAP_DIR
+ *     never hides an id that lives under one of the home overrides. Deduped.
+ *  1. `<evomapHome>/node_id` — the override-aware home file. `resolveEvomapHome()`
+ *     honours EVOLVER_HOME (matching v1 `getEvomapDir`) and ADDITIONALLY
+ *     EVOMAP_HOME after dropping blank/relative overrides. It wins first so a
+ *     home relocated via EVOLVER_HOME reads the file the v1 writer put there —
+ *     the lesson of v1 #120, which routed the reader through the same helper as
+ *     the writer.
+ *  2. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
+ *     `getEvomapDir` = `EVOLVER_HOME || ~/.evomap` and ignores EVOMAP_HOME
+ *     entirely, so unless EVOLVER_HOME was set a v1 file always physically lands
+ *     here. We probe it explicitly so a v2 install that sets only EVOMAP_HOME
+ *     (which steers candidate 1 away from `~/.evomap`) still recovers the v1
+ *     identity instead of letting the hub mint a duplicate orphan node. Deduped
+ *     against candidate 1 for the common no-override case where they coincide.
+ *  3. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
+ *     back to when `~/.evomap/` isn't writable (read-only $HOME in
+ *     containers / restricted CI). Kept first for parity with the old v2
+ *     candidate.
+ *  4. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
+ *     root fallback. In v2's multi-package layout the proxy code lives below
+ *     `packages/evolver-proxy`, so only checking the proxy package root misses
+ *     a file written at the install/workspace root.
+ *
+ * Resolved on every call rather than cached at module load: env and `homedir()`
+ * are read at call time, so caching would freeze the home path and silently
+ * ignore a later EVOLVER_HOME/EVOMAP_HOME change (this is also how the tests
+ * point it at a tmp dir). The install-root paths use a bounded package.json walk
+ * from the module dir so source and dist layouts both work.
+ */
+export function legacyNodeIdCandidates(opts = {}) {
+    const home = cleanAbsolutePath(opts.homeDir) ?? cleanAbsolutePath(homedir());
+    const moduleDir = opts.moduleDir ?? _moduleDir;
+    const evomapHome = resolveEvomapHome(opts, home);
+    const evomapDir = cleanAbsolutePath(opts.evomapDir) ?? cleanAbsolutePath(process.env['EVOMAP_DIR']);
+    return [
+        ...new Set([
+            ...(evomapDir === undefined ? [] : [join(evomapDir, 'node_id')]),
+            ...(evomapHome === undefined ? [] : [join(evomapHome, 'node_id')]),
+            ...(home === undefined ? [] : [join(home, '.evomap', 'node_id')]),
+            ...installRootNodeIdCandidates(moduleDir),
+        ]),
+    ];
+}
+/**
+ * Recover a node_id persisted by the legacy v1 GEP path. Returns the first
+ * candidate file whose trimmed contents match NODE_ID_RE, else `undefined`.
+ *
+ * Why this exists (PORT v1 #117): v2 resolves the wire node_id as
+ * `store.node_id ?? EVOMAP_NODE_ID/A2A_NODE_ID`. When BOTH are empty the
+ * `/a2a/hello` payload carries no `node_id` and the hub MINTS A FRESH A2ANode,
+ * which the lifecycle manager then persists. So any install whose mailbox
+ * store was created (or wiped) after a v1 `~/.evomap/node_id` already existed —
+ * an upgrade from a pre-lifecycle version, or a partial recovery flow —
+ * silently registers a brand-new node under the same owner on the very next
+ * daemon boot, abandoning the original record (with its stake / reputation /
+ * aliases) as an orphan in the web UI. Reading the legacy file between the
+ * store/env lookup and the hub mint keeps both code paths agreeing on a single
+ * identity.
+ */
+export function readLegacyNodeId(opts = {}) {
+    const candidates = opts.candidates ?? legacyNodeIdCandidates(opts);
+    for (const file of candidates) {
+        try {
+            if (!existsSync(file))
+                continue;
+            const raw = readFileSync(file, 'utf8').trim();
+            if (NODE_ID_RE.test(raw))
+                return raw;
+        }
+        catch {
+            // Unreadable / racing writer — try the next location.
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the node_id the proxy presents on the wire, in priority order:
+ * persisted store value → operator env override → recovered legacy file →
+ * `undefined` (the hub mints a fresh id on hello). An explicit env override
+ * outranks the legacy file because the operator set it deliberately.
+ *
+ * The legacy read only fires while the store is unprimed AND no env override
+ * is set — the first-boot window before a successful hello persists an id.
+ * Already-registered nodes short-circuit on the store value and never touch
+ * the filesystem.
+ *
+ * Empty / whitespace store and env values are normalised to `undefined` first:
+ * `??` alone treats `''` as a present value, so a blank `EVOMAP_NODE_ID=` (or a
+ * store cleared to `''`) would otherwise suppress legacy recovery and put a
+ * blank id on the wire — the exact orphan-node failure this module prevents.
+ */
+export function resolveProxyNodeId(opts) {
+    const stored = opts.storedNodeId?.trim() || undefined;
+    const configured = opts.configuredNodeId?.trim() || undefined;
+    return stored ?? configured ?? (opts.readLegacy ?? readLegacyNodeId)();
+}

package/dist/lifecycle/manager.d.ts

@@ -0,0 +1,106 @@
+import { mailbox, hub as hubNs } from '@evomap/evolver-core';
+import type { ForceUpdateDirective } from '../selfUpdate/executor.js';
+import { type LastUpdateAck, type LastUpdatePayload } from '../selfUpdate/lastUpdate.js';
+type MailboxStore = mailbox.MailboxStore;
+type AuthProvider = hubNs.AuthProvider;
+export type HelloLifecycleMode = 'legacy' | 'enterprise_token';
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 360000;
+export declare const MIN_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const HEARTBEAT_BACKOFF_CAP_MS: number;
+export declare const MAX_REAUTH_ATTEMPTS = 2;
+export declare const REAUTH_BACKOFF_BASE_MS: number;
+export declare const REAUTH_BACKOFF_MAX_MS: number;
+export declare const HUB_UNREACHABLE_BACKOFF_MS = 60000;
+export declare const HUB_UNREACHABLE_BACKOFF_MAX_MS: number;
+export declare const MIN_HUB_UNREACHABLE_RETRY_MS = 1000;
+export declare const MAX_LAST_ERROR_LENGTH = 1000;
+export interface HelloResult {
+    ok: boolean;
+    authError?: boolean;
+    nodeId?: string;
+    rateLimitUntilMs?: number;
+    error?: string;
+    details?: unknown;
+    retryAfterMs?: number;
+    status?: string;
+    httpStatus?: number;
+    secretDiverged?: boolean;
+}
+export interface HeartbeatOptions {
+    evolverVersion?: string;
+    lastUpdate?: LastUpdatePayload;
+}
+export interface HeartbeatResult {
+    ok: boolean;
+    authError?: boolean;
+    error?: string;
+    details?: unknown;
+    retryAfterMs?: number;
+    status?: string;
+    httpStatus?: number;
+    lastUpdateAck?: LastUpdateAck;
+    forceUpdate?: ForceUpdateDirective;
+}
+export interface HeartbeatTickResult {
+    ok: boolean;
+    reauthed: boolean;
+    error?: string;
+}
+export interface LifecycleDeps {
+    store: MailboxStore;
+    auth: AuthProvider;
+    /**
+     * 注入: 真实 /a2a/hello 调用(adapter 实现, M6-6); rotate=true 时请求轮换 secret.
+     * evolverVersion 传入当前节点版本, adapter 在 hello/heartbeat wire 体里上报(hub 观测 fleet 版本分布, #108).
+     */
+    hello: (opts: {
+        rotate: boolean;
+        evolverVersion?: string;
+    }) => Promise<HelloResult>;
+    /** 注入: 真实 heartbeat 调用. evolverVersion=当前节点版本, 由 adapter 写进 heartbeat payload 供 hub 观测. */
+    heartbeat: (opts?: HeartbeatOptions) => Promise<HeartbeatResult>;
+    /** Optional heartbeat-discovered force_update hook; ProxyDaemon owns the actual self-update deps. */
+    onForceUpdateDirective?: (directive: ForceUpdateDirective, source: 'heartbeat_200' | 'heartbeat_426') => Promise<void> | void;
+    now: () => number;
+    heartbeatIntervalMs?: number;
+    /** 当前 evolver 版本(proxy getCurrentVersion 读 package.json); 随 hello/heartbeat 上报, hub 据此推 force_update. */
+    evolverVersion?: string;
+    /** enterprise-token private mode keeps hello as verify/register only and never asks for node_secret rotation. */
+    helloMode?: HelloLifecycleMode;
+}
+/**
+ * LifecycleManager(M6-3): hello/heartbeat/reauth 状态机, 移植 v1 lifecycle/manager.js.
+ * node_secret 解析下沉到 HubCapability.auth(M6-5 LegacyAuthShim 双轨); 本层只管:
+ * 注册(hello, 持久化 node_id)、心跳节奏、403/401→auth.rotate() 退避(30m→4h, MAX 2 次)、hello 限流尊重.
+ * 纯逻辑注入 now/hello/heartbeat → 对 FakeHubCapability 确定性测.
+ */
+export declare class LifecycleManager {
+    private readonly deps;
+    private reauthInProgress;
+    constructor(deps: LifecycleDeps);
+    get nodeId(): string | undefined;
+    /** 当前上报版本(供 force_update 决策 / hub fleet 观测). */
+    get version(): string | undefined;
+    /** 注册. 尊重 hub hello 限流窗口; 成功持久化 node_id + 清 reauth 退避. 随报当前版本(hub 观测 fleet). */
+    doHello(rotate?: boolean): Promise<HelloResult>;
+    /** 心跳. authError → 触发 reauth 状态机. 随心跳上报当前版本(hub 观测 fleet, #108). */
+    doHeartbeat(): Promise<HeartbeatTickResult>;
+    nextHeartbeatDelay(consecutiveFailures?: number): number;
+    private heartbeatFailureBackoffDelay;
+    private recordHeartbeatException;
+    /**
+     * 403/401 重认证. 指数退避 30m→4h, 超 MAX_REAUTH_ATTEMPTS 长退避;
+     * auth.rotate() 成功后重 hello(rotate) 再注册. 退避状态持久化(进程重启不复位).
+     */
+    reauthenticate(): Promise<boolean>;
+    private setBackoff;
+    private hubUnreachableWaitMs;
+    private recordHubUnreachable;
+    private clearLegacyNodeSecretVersion;
+    private verifyReauthHeartbeat;
+    private heartbeatOptions;
+    private callHello;
+    private handleLastUpdateAck;
+    private maybeTriggerForceUpdate;
+}
+export {};