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

package/dist/daemon/proxyDaemon.d.ts

@@ -56,6 +56,8 @@ export interface ProxyDaemonDeps {
         dir: string;
         env?: NodeJS.ProcessEnv;
     };
+    /** V1 collaboration task operations are synchronous; tests may shorten the Hub timeout. */
+    collaborationOperationTimeoutMs?: number;
 }
 export interface ProxyTickReport {
     outbound: OutboundResult;
@@ -118,6 +120,7 @@ export declare class ProxyDaemon {
     private readonly reuseResultReporter;
     private readonly validator;
     private readonly atp;
+    private readonly collaborationFacade;
     private ipc;
     private readonly now;
     private readonly random;

package/dist/daemon/proxyDaemon.js

@@ -6,6 +6,7 @@ import { executeForceUpdate } from '../selfUpdate/executor.js';
 import { reportPendingSelfUpdateLastUpdate, reportSelfUpdateLastUpdate } from '../selfUpdate/lastUpdate.js';
 import { backfillProxyTraceUploads } from '../llm/traceBackfill.js';
 import { hubAuthFailureHint } from './selectHub.js';
+import { CollaborationFacade } from './collaborationFacade.js';
 export const DEFAULT_IPC_PORT = 19820;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const MAX_PROXY_TICK_ERROR_LENGTH = 2_000;
@@ -28,6 +29,7 @@ export class ProxyDaemon {
     reuseResultReporter;
     validator;
     atp;
+    collaborationFacade;
     ipc;
     now;
     random;
@@ -93,9 +95,20 @@ export class ProxyDaemon {
             pumpHandlers: ['core'], // proxy 出站归 SyncEngine, 不在此双 claim
             ...(deps.lockPath ? { lockPath: deps.lockPath } : {}),
         });
+        this.collaborationFacade = new CollaborationFacade({
+            store: this.store,
+            hub: hubToUse,
+            now: this.now,
+            notifyOutbound: () => this.notifyNewOutbound(),
+            ...(deps.runtimeNamespace ? { runtimeNamespace: deps.runtimeNamespace } : {}),
+            ...(deps.collaborationOperationTimeoutMs !== undefined ? { operationTimeoutMs: deps.collaborationOperationTimeoutMs } : {}),
+        });
         this.sync = new SyncEngine({
             store: this.store, hub: hubToUse, proxyHandler, now: this.now,
             ...(deps.runtimeNamespace ? { runtimeNamespace: deps.runtimeNamespace } : {}),
+            onOutboundSucceeded: (envelope, result) => this.collaborationFacade.handleOutboundSucceeded(envelope, result),
+            onOutboundTerminal: (envelope, error) => this.collaborationFacade.handleOutboundTerminal(envelope, error),
+            normalizeInboundEnvelope: (envelope) => this.collaborationFacade.normalizeInboundEnvelope(envelope),
             ...(deps.traceBackfill ? { onOutboundFlushed: () => { this.drainProxyTraceBackfill(); } } : {}),
         });
         this.lifecycle = new LifecycleManager({
@@ -555,6 +568,8 @@ export class ProxyDaemon {
         return Number.isFinite(n) && n > 0 ? n : null;
     }
     async handleProxyRoute(ctx) {
+        if (await this.collaborationFacade.handle(ctx))
+            return true;
         const handledAtp = await this.handleAtpRoute(ctx);
         if (handledAtp)
             return true;
@@ -711,6 +726,60 @@ export class ProxyDaemon {
             ctx.json(200, { ...distill, queued: submission !== null, submission });
             return true;
         }
+        if (ctx.route === 'POST /agent/search') {
+            const body = asRecord(await ctx.readJson());
+            const directory = this.deps.hub.agentDirectory ?? hubNs.unsupportedAgentDirectoryCapability();
+            const parsed = parseAgentSearchRequest(body);
+            if (!parsed.ok) {
+                respondAgentDirectory(ctx, parsed);
+                return true;
+            }
+            const result = await directory.search(parsed.value);
+            respondAgentDirectory(ctx, result);
+            return true;
+        }
+        if (ctx.route === 'POST /agent/profile') {
+            const body = asRecord(await ctx.readJson());
+            const directory = this.deps.hub.agentDirectory ?? hubNs.unsupportedAgentDirectoryCapability();
+            let agentId;
+            let timeoutMs;
+            try {
+                agentId = hubNs.normalizeAgentId(typeof body['agent_id'] === 'string' ? body['agent_id'] : '');
+                timeoutMs = hubNs.normalizeAgentDirectoryTimeout(typeof body['timeout_ms'] === 'number' ? body['timeout_ms'] : undefined);
+            }
+            catch (error) {
+                respondAgentDirectory(ctx, invalidAgentDirectoryRequest(error));
+                return true;
+            }
+            const result = await directory.getProfile(agentId, { timeoutMs });
+            respondAgentDirectory(ctx, result);
+            return true;
+        }
+        if (ctx.route === 'POST /agent/discover') {
+            const body = asRecord(await ctx.readJson());
+            const directory = this.deps.hub.agentDirectory ?? hubNs.unsupportedAgentDirectoryCapability();
+            let request;
+            try {
+                request = hubNs.normalizeAgentTaskDiscoveryRequest({
+                    title: typeof body['title'] === 'string' ? body['title'] : '',
+                    ...(typeof body['description'] === 'string' ? { description: body['description'] } : {}),
+                    ...(Array.isArray(body['signals']) ? { signals: body['signals'] } : {}),
+                    ...(typeof body['availability'] === 'string' ? { availability: body['availability'] } : {}),
+                    ...(typeof body['sort'] === 'string' ? { sort: body['sort'] } : {}),
+                    ...(typeof body['order'] === 'string' ? { order: body['order'] } : {}),
+                    ...(typeof body['cursor'] === 'string' ? { cursor: body['cursor'] } : {}),
+                    ...(typeof body['limit'] === 'number' ? { limit: body['limit'] } : {}),
+                    ...(typeof body['timeout_ms'] === 'number' ? { timeoutMs: body['timeout_ms'] } : {}),
+                });
+            }
+            catch (error) {
+                respondAgentDirectory(ctx, invalidAgentDirectoryRequest(error));
+                return true;
+            }
+            const result = await directory.discoverForTask(request);
+            respondAgentDirectory(ctx, result);
+            return true;
+        }
     }
     async searchAssets(query) {
         const limit = Math.max(1, Math.min(Number(query.limit ?? 5), 25));
@@ -862,6 +931,48 @@ function assetKind(value) {
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
+function respondAgentDirectory(ctx, result) {
+    if (result.ok) {
+        ctx.json(200, result);
+        return;
+    }
+    const status = {
+        invalid_request: 400,
+        permission_denied: 403,
+        capability_unavailable: 501,
+        invalid_response: 502,
+        hub_unavailable: 503,
+        timeout: 504,
+    }[result.error.code];
+    ctx.json(status, result);
+}
+function parseAgentSearchRequest(body) {
+    try {
+        return { ok: true, value: hubNs.normalizeAgentSearchRequest({
+                ...(typeof body['query'] === 'string' ? { query: body['query'] } : {}),
+                ...(Array.isArray(body['signals']) ? { signals: body['signals'] } : {}),
+                ...(typeof body['availability'] === 'string' ? { availability: body['availability'] } : {}),
+                ...(typeof body['sort'] === 'string' ? { sort: body['sort'] } : {}),
+                ...(typeof body['order'] === 'string' ? { order: body['order'] } : {}),
+                ...(typeof body['cursor'] === 'string' ? { cursor: body['cursor'] } : {}),
+                ...(typeof body['limit'] === 'number' ? { limit: body['limit'] } : {}),
+                ...(typeof body['timeout_ms'] === 'number' ? { timeoutMs: body['timeout_ms'] } : {}),
+            }) };
+    }
+    catch (error) {
+        return invalidAgentDirectoryRequest(error);
+    }
+}
+function invalidAgentDirectoryRequest(error) {
+    return {
+        ok: false,
+        error: {
+            code: 'invalid_request',
+            retryable: false,
+            message: error instanceof Error ? error.message.slice(0, 120) : 'invalid_request',
+        },
+    };
+}
 function stringBody(body, key) {
     const v = body[key];
     return typeof v === 'string' && v.length > 0 ? v : undefined;

package/dist/daemon/selectHub.js

@@ -1,3 +1,4 @@
+import { resolveHubUrl as resolvePublicHubUrl } from '@evomap/evolver-adapter-public';
 /** 据 EVOMAP_HUB_MODE 选 hub 实现(public|private). 缺省 public. bin 据此挂对应 adapter. */
 export function resolveHubMode(env) {
     const m = (env['EVOMAP_HUB_MODE'] ?? 'public').toLowerCase();
@@ -6,7 +7,22 @@ export function resolveHubMode(env) {
     return m;
 }
 export function resolveHubUrl(env) {
-    return env['EVOMAP_HUB_URL'] ?? 'https://dev.evomap.ai';
+    if ((env['EVOMAP_HUB_MODE'] ?? 'public').toLowerCase() === 'private')
+        return resolvePrivateHubUrl(env);
+    return resolvePublicHubUrl(env);
+}
+function resolvePrivateHubUrl(env) {
+    return trimmed(env['EVOMAP_HUB_URL'])
+        ?? trimmed(env['A2A_HUB_URL'])
+        ?? trimmed(env['EVOLVER_DEFAULT_HUB_URL'])
+        ?? resolvePublicHubUrl({});
+}
+function trimmed(value) {
+    const v = value?.trim();
+    if (!v)
+        return undefined;
+    const normalized = v.replace(/\/+$/, '');
+    return normalized || undefined;
 }
 /**
  * Actionable hint for a hub AUTH failure (401/403), tailored to the hub's error code so it does NOT misdirect

package/dist/llm/traceControl.js

@@ -1,7 +1,7 @@
 import { verify } from 'node:crypto';
 export const DEFAULT_TRACE_CONFIG_SIGNING_PUBLIC_KEY = [
     '-----BEGIN PUBLIC KEY-----',
-    'MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA7kJvWUP3HC4FJPQtkh74',
+    'MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA7kJvWUP3HC4FJPQtkh74', // gitleaks:allow -- public verification key, not a credential.
     'y75h9Rzc2NSZC9e4fiIWdax4iv+yWeMeIHGNsMr7YI8Ws7ck1BimJWt026gwRW8I',
     'c2A7h97oZQ0Z0zFcjEZ8FpYFSu++Yz/dGrARAV7uCQg289jvo89F5fWNdX2k+lTH',
     'hBoBm0G71vkiAYlbQEjq1xm1WzYf8CVXmbr+J1z+ydQf9jczcFL79u3eQZhIPs3R',

package/dist/private/adapterLoader.d.ts

@@ -1,4 +1,4 @@
-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';
 export type PrivateHubWithLifecycle = hubNs.HubCapability & {
     hello(opts: {
@@ -27,6 +27,8 @@ 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;
 }
 type DynamicImporter = (specifier: string) => Promise<unknown>;
 export interface PrivateProxyHubRuntime {
@@ -41,6 +43,9 @@ export interface ConnectPrivateProxyHubOptions {
     importer?: DynamicImporter;
 }
 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 resolvePrivateEnterpriseSubject(env: Record<string, string | undefined>): string;
 export declare function connectPrivateProxyHub(opts: ConnectPrivateProxyHubOptions): Promise<PrivateProxyHubRuntime>;
 export {};

package/dist/private/adapterLoader.js

@@ -1,14 +1,21 @@
+import { hub as hubNs } from '@evomap/evolver-core';
 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 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）');
+    if (!token && !invitationToken) {
+        throw new Error('EVOMAP_HUB_MODE=private 需要 A2A_INVITATION_TOKEN（推荐，对齐 PrivateHub onboarding）或 EVOMAP_ENTERPRISE_TOKEN（也兼容 EVOMAP_PRIVATE_HUB_TOKEN / PHUB_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,11 +28,15 @@ export async function connectPrivateProxyHub(opts) {
         now,
         sso: {
             identity: () => ({ subject }),
-            exchange: async () => ({ token }),
+            exchange: async () => ({ token: token ?? '' }),
             now,
         },
+        ...(invitationToken ? { invitationToken } : {}),
     });
     assertPrivateLifecycle(hub, moduleName);
+    if (!hub.agentDirectory) {
+        hub.agentDirectory = hubNs.unsupportedAgentDirectoryCapability('private_hub_agent_directory_not_supported');
+    }
     return { hub, auth };
 }
 async function loadConnectPrivateHub(moduleName, importer) {

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;