@evomap/evolver-proxy 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/private/adapterLoader.d.ts

@@ -1,5 +1,6 @@
-import type { hub as hubNs } from '@evomap/evolver-core';
+import { hub as hubNs } from '@evomap/evolver-core';
 import type { HelloResult, HeartbeatOptions, HeartbeatResult } from '../lifecycle/manager.js';
+import { type PrivateAccountAssetHub, type PrivateCompatibilityFetch } from './accountAssetCompatibility.js';
 export type PrivateHubWithLifecycle = hubNs.HubCapability & {
     hello(opts: {
         rotate: boolean;
@@ -7,6 +8,7 @@ export type PrivateHubWithLifecycle = hubNs.HubCapability & {
     }): Promise<HelloResult>;
     heartbeat(opts?: HeartbeatOptions): Promise<HeartbeatResult>;
 };
+export type PrivateProxyHub = PrivateHubWithLifecycle & PrivateAccountAssetHub;
 interface PrivateSsoExchange {
     identity: () => {
         subject: string;
@@ -27,11 +29,21 @@ export interface ConnectPrivateHubOptions {
     senderId: () => string | undefined;
     env?: Record<string, string | undefined>;
     now?: () => number;
+    /** One-shot invitation token (evoinv_…) — preferred over the SSO bearer for token_required hubs. */
+    invitationToken?: string;
+    /** Ready credential from the standard Private Hub onboarding store. */
+    nodeSecret?: string;
+    fetchFn?: PrivateCompatibilityFetch;
 }
 type DynamicImporter = (specifier: string) => Promise<unknown>;
 export interface PrivateProxyHubRuntime {
-    hub: PrivateHubWithLifecycle;
+    hub: PrivateProxyHub;
     auth: hubNs.AuthProvider;
+    /** Enrollment-aware lifecycle entrypoint. Ready node_secret credentials must not re-run hello. */
+    hello(opts: {
+        rotate: boolean;
+        evolverVersion?: string;
+    }): Promise<HelloResult>;
 }
 export interface ConnectPrivateProxyHubOptions {
     hubUrl: string;
@@ -39,8 +51,13 @@ export interface ConnectPrivateProxyHubOptions {
     env: Record<string, string | undefined>;
     now?: () => number;
     importer?: DynamicImporter;
+    fetchFn?: PrivateCompatibilityFetch;
 }
 export declare function resolvePrivateEnterpriseToken(env: Record<string, string | undefined>): string | undefined;
+/** One-shot invitation token (evoinv_…), matching the hub's official onboarding script (A2A_INVITATION_TOKEN).
+ *  Preferred over the enterprise token for the default token_required enrollment mode. */
+export declare function resolvePrivateInvitationToken(env: Record<string, string | undefined>): string | undefined;
+export declare function resolvePrivateNodeSecret(env: Record<string, string | undefined>): string | undefined;
 export declare function resolvePrivateEnterpriseSubject(env: Record<string, string | undefined>): string;
 export declare function connectPrivateProxyHub(opts: ConnectPrivateProxyHubOptions): Promise<PrivateProxyHubRuntime>;
 export {};

package/dist/private/adapterLoader.js

@@ -1,14 +1,29 @@
+import { hub as hubNs } from '@evomap/evolver-core';
+import { withPrivateAccountAssetCompatibility, } from './accountAssetCompatibility.js';
 const DEFAULT_PRIVATE_ADAPTER_MODULE = '@evomap/evolver-adapter-private';
 export function resolvePrivateEnterpriseToken(env) {
     return firstEnv(env, 'EVOMAP_ENTERPRISE_TOKEN', 'EVOMAP_PRIVATE_HUB_TOKEN', 'PHUB_ENTERPRISE_TOKEN', 'PRIVATE_HUB_ENTERPRISE_TOKEN');
 }
+/** One-shot invitation token (evoinv_…), matching the hub's official onboarding script (A2A_INVITATION_TOKEN).
+ *  Preferred over the enterprise token for the default token_required enrollment mode. */
+export function resolvePrivateInvitationToken(env) {
+    return firstEnv(env, 'A2A_INVITATION_TOKEN');
+}
+export function resolvePrivateNodeSecret(env) {
+    return firstEnv(env, 'EVOMAP_NODE_SECRET', 'A2A_NODE_SECRET');
+}
 export function resolvePrivateEnterpriseSubject(env) {
     return firstEnv(env, 'EVOMAP_ENTERPRISE_SUBJECT', 'EVOMAP_PRIVATE_SUBJECT', 'PHUB_ENTERPRISE_SUBJECT', 'USER') ?? 'evolver-proxy';
 }
 export async function connectPrivateProxyHub(opts) {
+    const invitationToken = resolvePrivateInvitationToken(opts.env);
     const token = resolvePrivateEnterpriseToken(opts.env);
-    if (!token) {
-        throw new Error('EVOMAP_HUB_MODE=private 需要 EVOMAP_ENTERPRISE_TOKEN（也兼容 EVOMAP_PRIVATE_HUB_TOKEN / PHUB_ENTERPRISE_TOKEN）');
+    const nodeSecret = resolvePrivateNodeSecret(opts.env);
+    if (nodeSecret && !isNodeSecret(nodeSecret)) {
+        throw new Error('Private Hub node_secret 必须是 64 位十六进制字符串');
+    }
+    if (!token && !invitationToken && !nodeSecret) {
+        throw new Error('EVOMAP_HUB_MODE=private 需要 A2A_NODE_SECRET / EVOMAP_NODE_SECRET、A2A_INVITATION_TOKEN 或 EVOMAP_ENTERPRISE_TOKEN');
     }
     const moduleName = opts.env['EVOMAP_PRIVATE_ADAPTER_MODULE']?.trim() || DEFAULT_PRIVATE_ADAPTER_MODULE;
     const connectPrivateHub = await loadConnectPrivateHub(moduleName, opts.importer ?? ((specifier) => import(specifier)));
@@ -21,12 +36,33 @@ export async function connectPrivateProxyHub(opts) {
         now,
         sso: {
             identity: () => ({ subject }),
-            exchange: async () => ({ token }),
+            exchange: async () => ({ token: token ?? nodeSecret ?? '' }),
             now,
         },
+        ...(nodeSecret ? { nodeSecret } : {}),
+        ...(!nodeSecret && invitationToken ? { invitationToken } : {}),
+        ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}),
     });
     assertPrivateLifecycle(hub, moduleName);
-    return { hub, auth };
+    if (nodeSecret)
+        await adoptReadyNodeSecret(auth, nodeSecret);
+    if (!hub.agentDirectory) {
+        hub.agentDirectory = hubNs.unsupportedAgentDirectoryCapability('private_hub_agent_directory_not_supported');
+    }
+    const compatibleHub = withPrivateAccountAssetCompatibility(hub, {
+        baseUrl: opts.hubUrl,
+        auth,
+        senderId: opts.senderId,
+        env: opts.env,
+        ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}),
+    });
+    return {
+        hub: compatibleHub,
+        auth,
+        hello: nodeSecret
+            ? async (helloOpts) => await helloWithReadyPrivateCredential(compatibleHub, auth, nodeSecret, opts.senderId, helloOpts)
+            : (helloOpts) => compatibleHub.hello(helloOpts),
+    };
 }
 async function loadConnectPrivateHub(moduleName, importer) {
     let loaded;
@@ -49,6 +85,44 @@ function assertPrivateLifecycle(hub, moduleName) {
         throw new Error(`${moduleName} 的 hub 缺少 hello/heartbeat lifecycle 方法，无法接入 evolver-proxy`);
     }
 }
+async function adoptReadyNodeSecret(auth, nodeSecret) {
+    const candidate = auth;
+    if (typeof candidate.adoptNodeSecret === 'function') {
+        candidate.adoptNodeSecret.call(auth, nodeSecret);
+    }
+    if (!await authenticatesWithNodeSecret(auth, nodeSecret)) {
+        throw new Error('private Hub adapter cannot activate the configured node_secret');
+    }
+}
+async function helloWithReadyPrivateCredential(hub, auth, nodeSecret, senderId, opts) {
+    if (await authenticatesWithNodeSecret(auth, nodeSecret))
+        return readyPrivateHello(senderId);
+    return await hub.hello(opts);
+}
+async function authenticatesWithNodeSecret(auth, nodeSecret) {
+    const signed = await auth.authenticate({ method: 'GET', path: '/a2a/assets/published-by-me' });
+    const authorization = headerValue(signed.headers, 'authorization');
+    const bodySecret = signed.bodyFields?.['node_secret'];
+    return authorization === `Bearer ${nodeSecret}` || bodySecret === nodeSecret;
+}
+function headerValue(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return value;
+    }
+    return undefined;
+}
+function trimmedSenderId(senderId) {
+    return senderId()?.trim() || undefined;
+}
+function readyPrivateHello(senderId) {
+    const nodeId = trimmedSenderId(senderId);
+    return { ok: true, ...(nodeId ? { nodeId } : {}) };
+}
+function isNodeSecret(value) {
+    return /^[a-f0-9]{64}$/i.test(value);
+}
 function firstEnv(env, ...keys) {
     for (const key of keys) {
         const value = env[key]?.trim();

package/dist/router/messagesRoute.d.ts

@@ -112,6 +112,19 @@ export interface MessagesResponse {
 }
 export declare function captureTraceMetadata(value: unknown, env?: NodeJS.ProcessEnv): unknown;
 export declare function resolveTierModels(env?: NodeJS.ProcessEnv): Partial<Record<Tier, string>>;
+export type TierConfigWarningReason = 'missing_tier_models' | 'duplicate_tier_models' | 'all_tier_models_same';
+export interface TierConfigWarning {
+    event: 'router_config_warning';
+    reason: TierConfigWarningReason;
+    message: string;
+    configured_tiers: Tier[];
+    missing_tiers?: Tier[];
+    duplicate_models?: Array<{
+        model: string;
+        tiers: Tier[];
+    }>;
+}
+export declare function detectTierModelConfigWarnings(models: Partial<Record<Tier, string>>): TierConfigWarning[];
 interface ClaudeId {
     family: string;
     major: number;

package/dist/router/messagesRoute.js

@@ -34,6 +34,58 @@ export function resolveTierModels(env = process.env) {
         out.expensive = env['EVOMAP_MODEL_EXPENSIVE'];
     return out;
 }
+const TIER_ORDER = ['cheap', 'mid', 'expensive'];
+export function detectTierModelConfigWarnings(models) {
+    const configuredTiers = TIER_ORDER.filter((tier) => {
+        const model = models[tier];
+        return typeof model === 'string' && model.length > 0;
+    });
+    if (configuredTiers.length === 0)
+        return [];
+    const warnings = [];
+    const missingTiers = TIER_ORDER.filter((tier) => !configuredTiers.includes(tier));
+    if (missingTiers.length > 0) {
+        warnings.push({
+            event: 'router_config_warning',
+            reason: 'missing_tier_models',
+            message: 'Router tier config is partial; unset tiers will pass the client model through.',
+            configured_tiers: configuredTiers,
+            missing_tiers: missingTiers,
+        });
+    }
+    const byModel = new Map();
+    for (const tier of configuredTiers) {
+        const model = models[tier];
+        if (!model)
+            continue;
+        byModel.set(model, [...(byModel.get(model) ?? []), tier]);
+    }
+    const duplicateModels = Array.from(byModel.entries())
+        .filter(([, tiers]) => tiers.length > 1)
+        .map(([model, tiers]) => ({ model, tiers }));
+    const allSame = configuredTiers.length === TIER_ORDER.length
+        && duplicateModels.length === 1
+        && duplicateModels[0].tiers.length === TIER_ORDER.length;
+    if (allSame) {
+        warnings.push({
+            event: 'router_config_warning',
+            reason: 'all_tier_models_same',
+            message: 'All router tiers resolve to the same model; routing will still run but cannot change cost/latency tiers.',
+            configured_tiers: configuredTiers,
+            duplicate_models: duplicateModels,
+        });
+    }
+    else if (duplicateModels.length > 0) {
+        warnings.push({
+            event: 'router_config_warning',
+            reason: 'duplicate_tier_models',
+            message: 'Multiple router tiers resolve to the same model; routing will still run but tier separation is degraded.',
+            configured_tiers: configuredTiers,
+            duplicate_models: duplicateModels,
+        });
+    }
+    return warnings;
+}
 export function parseClaudeId(modelId) {
     if (typeof modelId !== 'string')
         return null;
@@ -386,6 +438,10 @@ export function buildMessagesHandler(opts) {
     const log = opts.logger ?? console;
     const env = opts.env ?? process.env;
     const enabled = typeof opts.routerEnabled === 'boolean' ? opts.routerEnabled : env['EVOMAP_ROUTER_ENABLED'] === '1';
+    if (enabled) {
+        for (const warning of detectTierModelConfigWarnings(resolveTierModels(env)))
+            log.warn?.(j(warning));
+    }
     // Native body capture defaults to v1-compatible full trace mode. Operators that need metadata-only rows must
     // explicitly disable it (a compliance decision; see bodyCapture.ts and docs/trace-body-capture.md).
     const captureBodies = captureBodiesEnabled(env);

package/dist/selfUpdate/executor.d.ts

@@ -1,8 +1,9 @@
 import { ops } from '@evomap/evolver-core';
 import { type SelfUpdateFailureCode } from './failureCodes.js';
+import type { DurableSelfUpdateSession } from './transaction.js';
 type DownloadedArtifact = ops.DownloadedArtifact;
 /** Structured outcome codes — reported to telemetry; the hub sees WHY an update did/didn't apply. */
-export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'already_in_progress' | 'disabled';
+export type SelfUpdateOutcome = 'applied' | 'noop' | 'rejected_decision' | 'rejected_verification' | 'download_failed' | 'replace_failed' | 'restart_failed' | 'rollback_failed' | 'already_in_progress' | 'disabled';
 export interface SelfUpdateResult {
     outcome: SelfUpdateOutcome;
     reason: string;
@@ -13,13 +14,15 @@ export interface SelfUpdateResult {
     /**
      * Which download path produced the staged binary: `'binary'` is the normal
      * precompiled-asset happy path, `'tarball'` means the binary download failed
-     * and Channel 1b (release `.tar.gz`) fallback was used. The verifyManifest
+     * and Channel 1b (release `.tar.gz`) fallback was used. The selected-artifact
      * gate ran in BOTH cases, so apply-semantics are identical, but "tarball
      * used in production" is a useful CDN/rate-limit signal for the hub.
      * Persisted into `last_update.json` (lastUpdate.LastUpdatePayload.applied_via)
      * on success so the hub can observe the channel directly.
      */
     appliedVia?: 'binary' | 'tarball';
+    /** Durable installs are not successful until the relaunched daemon completes startup health checks. */
+    confirmationPending?: true;
 }
 /** The hub's force_update directive (inbound message payload). */
 export interface ForceUpdateDirective {
@@ -36,7 +39,7 @@ export interface ForceUpdateDirective {
 export interface DownloadResult {
     /** Where the new version was staged (e.g. a tmp dir). Passed to atomicReplace on success. */
     stagedPath: string;
-    /** The downloaded artifacts (bytes or precomputed sha256) for verifyManifest. */
+    /** Exactly one selected artifact (bytes or precomputed sha256) for verification. */
     artifacts: readonly DownloadedArtifact[];
     /**
      * Which channel actually produced the staged bytes — defaults to `'binary'`
@@ -63,8 +66,10 @@ export interface SelfUpdateDeps {
     download: (targetVersion: string, directive: ForceUpdateDirective) => Promise<DownloadResult>;
     /** Atomically replace the install tree with the staged path (preserving node_modules/.env/etc). Throws on fail. */
     atomicReplace: (stagedPath: string) => Promise<void>;
+    /** Optional durable transaction: cross-process lock + journal + backup + recovery-aware install. */
+    beginTransaction?: (targetVersion: string) => Promise<DurableSelfUpdateSession>;
     /** Signal a restart so the supervisor relaunches the new version. v1 convention: process.exit(78). */
-    restart: () => void;
+    restart: () => void | Promise<void>;
     /** Optional Ed25519 public key (PEM / raw base64). When set, an unsigned/badly-signed manifest is REJECTED. */
     publicKey?: string;
     /** Best-effort telemetry sink for the structured outcome (never throws into the update path). */
@@ -80,7 +85,7 @@ export declare function _resetSelfUpdateMutex(): void;
  *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
  *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
  *  4. download the staged release.
- *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
+ *  5. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
  *  6. atomicReplace, then restart(). Only reached after verification passed.
  *
  * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running

package/dist/selfUpdate/executor.js

@@ -4,7 +4,8 @@
 // shells out or touches a real install tree by accident.
 //
 // THE HARD GATE (verify-before-apply, non-negotiable): after download and BEFORE any filesystem write or restart,
-// the executor calls the PURE core verifyManifest. If verification fails — bad sha256, missing/invalid signature
+// the executor calls the PURE core verifySelectedManifestArtifact. If verification fails — bad sha256,
+// missing/invalid signature
 // when a key is configured, anything — the executor writes NOTHING, restarts NOTHING, and returns a structured
 // failure. The old version stays intact and runnable. A compromised hub cannot turn this channel into fleet RCE.
 //
@@ -12,7 +13,7 @@
 // once. The second caller short-circuits with `already_in_progress` and performs no I/O.
 import { ops } from '@evomap/evolver-core';
 import { SELF_UPDATE_FAILURE_CODES, classifySelfUpdateError, codeForDecisionReject, } from './failureCodes.js';
-const { decideUpdate, verifyManifest } = ops;
+const { decideUpdate, verifySelectedManifestArtifact } = ops;
 // Process-level mutex. Module scope is correct: there is one daemon per process, and v1's _forceUpdateInFlight had
 // the same lifetime. Guards against two force_update envelopes (or a heartbeat-driven + mailbox-driven trigger)
 // racing the same upgrade and replacing files twice / double-restarting.
@@ -38,7 +39,7 @@ function report(deps, result) {
  *  2. decideUpdate (pure): reject bad manifests, NOOP when already satisfied (no download, no restart).
  *  3. mutex: exactly one execution; concurrent callers get `already_in_progress` and touch no disk.
  *  4. download the staged release.
- *  5. verifyManifest (pure) — THE GATE. Fail → no write, no restart, `rejected_verification`.
+ *  5. verifySelectedManifestArtifact (pure) — THE GATE. Fail → no write, no restart.
  *  6. atomicReplace, then restart(). Only reached after verification passed.
  *
  * Never throws: every failure becomes a structured SelfUpdateResult so the daemon can report it and keep running
@@ -103,13 +104,29 @@ export async function executeForceUpdate(directive, deps) {
     }
     inFlight = true;
     const targetVersion = decision.targetVersion ?? manifest?.version ?? '';
+    let transaction;
     try {
+        if (deps.beginTransaction) {
+            try {
+                transaction = await deps.beginTransaction(targetVersion);
+            }
+            catch (err) {
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED);
+                return report(deps, {
+                    outcome: classified.failureCode === SELF_UPDATE_FAILURE_CODES.UPDATE_LOCKED ? 'already_in_progress' : 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+        }
         // 4. Download the staged release.
         let dl;
         try {
             dl = await deps.download(targetVersion, effectiveDirective);
         }
         catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED).catch(() => { });
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED);
             return report(deps, {
                 outcome: 'download_failed',
@@ -118,9 +135,25 @@ export async function executeForceUpdate(directive, deps) {
                 targetVersion,
             });
         }
+        if (transaction) {
+            try {
+                dl = await transaction.adoptDownloaded(dl);
+            }
+            catch (err) {
+                await transaction.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
+                const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
+                return report(deps, {
+                    outcome: 'replace_failed',
+                    reason: classified.detail,
+                    failureCode: classified.failureCode,
+                    targetVersion,
+                });
+            }
+        }
         // 5. THE GATE: verify the downloaded bytes against the (optionally signed) manifest BEFORE any write.
-        const verification = verifyManifest(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
+        const verification = verifySelectedManifestArtifact(manifest, dl.artifacts, ...(deps.publicKey ? [deps.publicKey] : []));
         if (!verification.ok) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REJECTED_VERIFICATION).catch(() => { });
             // Verification failed → write NOTHING, restart NOTHING. Old version stays intact and runnable.
             return report(deps, {
                 outcome: 'rejected_verification',
@@ -129,9 +162,25 @@ export async function executeForceUpdate(directive, deps) {
                 targetVersion,
             });
         }
+        try {
+            await transaction?.markVerified(dl.artifacts);
+        }
+        catch (err) {
+            await transaction?.abort(SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED).catch(() => { });
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.REPLACE_FAILED);
+            return report(deps, {
+                outcome: 'replace_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         // 6. Verified. Atomic replace, then signal restart. A replace failure leaves the old version intact.
         try {
-            await deps.atomicReplace(dl.stagedPath);
+            if (transaction)
+                await transaction.install();
+            else
+                await deps.atomicReplace(dl.stagedPath);
         }
         catch (err) {
             const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.COPY_FAILED);
@@ -147,12 +196,38 @@ export async function executeForceUpdate(directive, deps) {
             reason: 'verified_and_replaced',
             targetVersion,
             appliedVia: dl.appliedVia ?? 'binary',
+            ...(transaction ? { confirmationPending: true } : {}),
         };
         report(deps, result);
-        deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
+        try {
+            await transaction?.markRestartRequested();
+            await deps.restart(); // v1 convention: exit(78) → supervisor relaunches the new version.
+        }
+        catch (err) {
+            const classified = classifySelfUpdateError(err, SELF_UPDATE_FAILURE_CODES.RESTART_FAILED);
+            try {
+                await transaction?.rollback(classified.failureCode);
+            }
+            catch (rollbackError) {
+                const rollback = classifySelfUpdateError(rollbackError, SELF_UPDATE_FAILURE_CODES.ROLLBACK_FAILED);
+                return report(deps, {
+                    outcome: 'rollback_failed',
+                    reason: rollback.detail,
+                    failureCode: rollback.failureCode,
+                    targetVersion,
+                });
+            }
+            return report(deps, {
+                outcome: 'restart_failed',
+                reason: classified.detail,
+                failureCode: classified.failureCode,
+                targetVersion,
+            });
+        }
         return result;
     }
     finally {
+        await transaction?.release().catch(() => { });
         // Released so a later legitimate update (after a failed attempt) can proceed. On the success path the process
         // is exiting anyway; releasing is harmless and keeps the mutex honest if restart() is a test fake that returns.
         inFlight = false;

package/dist/selfUpdate/failureCodes.d.ts

@@ -17,6 +17,12 @@ export declare const SELF_UPDATE_FAILURE_CODES: Readonly<{
     readonly FALLBACK_DOWNLOAD_FAILED: "fallback_download_failed";
     readonly FALLBACK_EXTRACT_FAILED: "fallback_extract_failed";
     readonly FALLBACK_MISSING_BINARY: "fallback_missing_binary";
+    readonly UPDATE_LOCKED: "update_locked";
+    readonly RECOVERY_REQUIRED: "recovery_required";
+    readonly UNSAFE_UPDATE_PATH: "unsafe_update_path";
+    readonly RESTART_FAILED: "restart_failed";
+    readonly READ_BACK_FAILED: "read_back_failed";
+    readonly ROLLBACK_FAILED: "rollback_failed";
 }>;
 export type SelfUpdateFailureCode = typeof SELF_UPDATE_FAILURE_CODES[keyof typeof SELF_UPDATE_FAILURE_CODES];
 export interface ClassifiedSelfUpdateError {

package/dist/selfUpdate/failureCodes.js

@@ -22,6 +22,12 @@ export const SELF_UPDATE_FAILURE_CODES = Object.freeze({
     FALLBACK_DOWNLOAD_FAILED: 'fallback_download_failed',
     FALLBACK_EXTRACT_FAILED: 'fallback_extract_failed',
     FALLBACK_MISSING_BINARY: 'fallback_missing_binary',
+    UPDATE_LOCKED: 'update_locked',
+    RECOVERY_REQUIRED: 'recovery_required',
+    UNSAFE_UPDATE_PATH: 'unsafe_update_path',
+    RESTART_FAILED: 'restart_failed',
+    READ_BACK_FAILED: 'read_back_failed',
+    ROLLBACK_FAILED: 'rollback_failed',
 });
 export class SelfUpdateFailureError extends Error {
     failureCode;

package/dist/selfUpdate/index.d.ts

@@ -2,4 +2,7 @@ export * from './executor.js';
 export * from './version.js';
 export * from './policy.js';
 export * from './releaseBinary.js';
-export * from './failureCodes.js';
+export * from './transaction.js';
+export * from './failureCodes.js';
+export * from './unixController.js';
+export * from './windowsController.js';

package/dist/selfUpdate/index.js

@@ -2,4 +2,7 @@ export * from './executor.js';
 export * from './version.js';
 export * from './policy.js';
 export * from './releaseBinary.js';
-export * from './failureCodes.js';
+export * from './transaction.js';
+export * from './failureCodes.js';
+export * from './unixController.js';
+export * from './windowsController.js';

package/dist/selfUpdate/lastUpdate.d.ts

@@ -1,5 +1,6 @@
 import { mailbox } from '@evomap/evolver-core';
 import type { ForceUpdateDirective, SelfUpdateResult } from './executor.js';
+import type { SelfUpdateRecoveryResult } from './transaction.js';
 type MailboxStore = mailbox.MailboxStore;
 type LastUpdateStatus = 'success' | 'failed' | 'skipped' | 'pending';
 export interface LastUpdatePayload {
@@ -12,7 +13,7 @@ export interface LastUpdatePayload {
     /**
      * Which download channel produced the bytes that got applied: `'binary'` is
      * the precompiled-asset happy path, `'tarball'` means Channel 1b fallback
-     * (release `.tar.gz`) was used. Persisted on success so the hub can see
+     * (release `.tar.gz`) was used. Persisted while confirmation is pending and on success so the hub can see
      * "primary CDN is degraded — fallback carrying production" without having
      * to mine telemetry. Absent on non-success or when the executor predates
      * the appliedVia field.
@@ -36,6 +37,7 @@ export declare function reportPendingSelfUpdateLastUpdate(store: MailboxStore, d
     fromVersion: string;
     now?: number;
 }): boolean;
+export declare function finalizeSelfUpdateRecoveryLastUpdate(store: MailboxStore, recovery: SelfUpdateRecoveryResult, now?: number): boolean;
 export declare function lastUpdateFromSelfUpdateResult(directive: ForceUpdateDirective, result: SelfUpdateResult, opts: {
     fromVersion: string;
     now: number;

package/dist/selfUpdate/lastUpdate.js

@@ -86,6 +86,37 @@ export function reportPendingSelfUpdateLastUpdate(store, directive, opts = { fro
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     }, now);
 }
+export function finalizeSelfUpdateRecoveryLastUpdate(store, recovery, now = Date.now()) {
+    if (recovery.outcome !== 'confirmed'
+        && recovery.outcome !== 'rolled_back'
+        && recovery.outcome !== 'blocked')
+        return false;
+    const toVersion = concreteVersion(recovery.targetVersion);
+    const fromVersion = concreteVersion(recovery.fromVersion);
+    if (!toVersion)
+        return false;
+    const current = readPendingLastUpdate(store, now);
+    if (current && current.to_version !== toVersion)
+        return false;
+    const common = {
+        to_version: toVersion,
+        finished_at: Math.max(now, FINISHED_AT_MIN_MS),
+        ...(current?.directive_id ? { directive_id: current.directive_id } : {}),
+        ...(current?.from_version ? { from_version: current.from_version } : fromVersion ? { from_version: fromVersion } : {}),
+    };
+    if (recovery.outcome === 'confirmed') {
+        return writeLastUpdate(store, {
+            ...common,
+            status: 'success',
+            ...(current?.applied_via ? { applied_via: current.applied_via } : {}),
+        }, now);
+    }
+    return writeLastUpdate(store, {
+        ...common,
+        status: 'failed',
+        error: clampString(hubNs.redactString(`${recovery.failureCode ?? 'self_update_recovery_failed'}: ${recovery.outcome}`), LAST_UPDATE_ERROR_MAX),
+    }, now);
+}
 export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     if (result.outcome === 'already_in_progress' || result.outcome === 'disabled')
         return undefined;
@@ -94,11 +125,11 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
         return undefined;
     const base = {
         to_version: toVersion,
-        status: statusForOutcome(result.outcome),
+        status: statusForResult(result),
         finished_at: Math.max(opts.now, FINISHED_AT_MIN_MS),
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     };
-    if (base.status === 'success') {
+    if (base.status === 'success' || base.status === 'pending') {
         return {
             ...base,
             from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
@@ -114,10 +145,10 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     }
     return base;
 }
-function statusForOutcome(outcome) {
-    if (outcome === 'applied')
-        return 'success';
-    if (outcome === 'noop')
+function statusForResult(result) {
+    if (result.outcome === 'applied')
+        return result.confirmationPending ? 'pending' : 'success';
+    if (result.outcome === 'noop')
         return 'skipped';
     return 'failed';
 }

package/dist/selfUpdate/releaseBinary.d.ts

@@ -11,8 +11,18 @@ export interface ReleaseBinaryOptions {
     targetPath?: string;
     processExecPath?: string;
     requireSignedManifest?: boolean;
+    maxPrimaryBinaryBytes?: number;
     maxExtractedTarballBytes?: number;
 }
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export declare const MAX_PRIMARY_BINARY_BYTES: number;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export declare const MAX_RELEASE_METADATA_BYTES: number;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered