@opendatalabs/personal-server-ts-server 0.0.1-canary.016adf9 → 0.0.1-canary.052d47e

package/dist/bootstrap.js

@@ -2,48 +2,118 @@ import { mkdir } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { privateKeyToAccount } from "viem/accounts";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
-import { DEFAULT_ROOT_PATH, resolveRootPath, } from "@opendatalabs/personal-server-ts-core/config";
-import { createLogger, } from "@opendatalabs/personal-server-ts-core/logger";
-import { initializeDatabase, createIndexManager, } from "@opendatalabs/personal-server-ts-core/storage/index";
-import { createGatewayClient } from "@opendatalabs/personal-server-ts-core/gateway";
-import { createAccessLogWriter } from "@opendatalabs/personal-server-ts-core/logging/access-log";
-import { createAccessLogReader } from "@opendatalabs/personal-server-ts-core/logging/access-reader";
-import { deriveMasterKey, recoverServerOwner, loadOrCreateServerAccount, } from "@opendatalabs/personal-server-ts-core/keys";
-import { createServerSigner, createRequestSigner, } from "@opendatalabs/personal-server-ts-core/signing";
-import { createSyncCursor, createSyncManager, } from "@opendatalabs/personal-server-ts-core/sync";
-import { createVanaStorageAdapter } from "@opendatalabs/personal-server-ts-core/storage/adapters";
+import { DEFAULT_ROOT_PATH, resolveRootPath } from "./config/index.js";
+import { createLogger } from "./logger/index.js";
+import { initializeDatabase } from "./storage/index-schema.js";
+import { createIndexManager, } from "./storage/index-manager.js";
+import { createGatewayClient, NodeECIESProvider, } from "@opendatalabs/vana-sdk/node";
+import { createAccessLogWriter } from "./logging/access-log.js";
+import { createAccessLogReader } from "./logging/access-reader.js";
+import { deriveMasterKey, recoverServerOwner, } from "@opendatalabs/vana-sdk/node";
+import { loadOrCreateServerAccount } from "./keys/server-account.js";
+import { createRequestSigner, createServerSigner, } from "@opendatalabs/personal-server-ts-core/signing";
+import { createGatewayLineageClient, } from "@opendatalabs/personal-server-ts-core/lineage";
+import { createSyncCursor } from "./sync-cursor.js";
+import { createGatewayDataPointFeed, createGatewayDeleteDataPort, createScopeDeletionTracker, createSyncManager, } from "@opendatalabs/personal-server-ts-core/sync";
+import { createVanaSyncStorageAdapter, resolveVanaStorageEndpoint, } from "@opendatalabs/personal-server-ts-core/storage/adapters";
+import { createFilePendingBlobDeletionStore } from "./pending-blob-deletions.js";
 import { createApp } from "./app.js";
 import { generateDevToken } from "./dev-token.js";
+import { migrateLocalState } from "./migrations/local-state.js";
+import { createTokenStore } from "./token-store.js";
 import { TunnelManager, ensureFrpcBinary } from "./tunnel/index.js";
+import { createNodeDataStorage } from "./storage/node-data-storage.js";
+import { createSqliteQuestionStore } from "./storage/question-store.js";
+import { computeQuestion, createOpenAiCompatibleInferenceProvider, createPhalaE2eeEncryption, createRecomputeScheduler, } from "@opendatalabs/personal-server-ts-core/derivatives";
+import { executeJob } from "./jobs/worker.js";
+const TRAILING_SLASHES = /\/+$/;
+const DEFAULT_LOCAL_APPROVAL_PORT = 34127;
+function resolveLocalApprovalPort(serverPort) {
+    const raw = process.env.LOCAL_AUTH_PORT;
+    if (raw !== undefined) {
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) &&
+            parsed >= 1 &&
+            parsed <= 65535 &&
+            parsed !== serverPort) {
+            return parsed;
+        }
+    }
+    const adjacentPort = serverPort + 1;
+    if (adjacentPort <= 65535) {
+        return adjacentPort;
+    }
+    return DEFAULT_LOCAL_APPROVAL_PORT;
+}
 export async function createServer(config, options) {
     const logger = createLogger(config.logging);
     const startedAt = new Date();
+    const isEnclave = options?.profile === "enclave";
+    if (isEnclave && process.env.VANA_OWNER_PRIVATE_KEY) {
+        throw new Error("VANA_OWNER_PRIVATE_KEY is forbidden in enclave profile");
+    }
     const storageRoot = resolveRootPath(options?.rootPath ?? options?.serverDir ?? DEFAULT_ROOT_PATH);
     const dataDir = options?.dataDir ?? join(storageRoot, "data");
     const indexPath = join(storageRoot, "index.db");
     const configPath = join(storageRoot, "config.json");
+    const syncCursorPath = join(storageRoot, "sync-cursor.json");
+    const pendingBlobDeletionsPath = join(storageRoot, "pending-blob-deletions.json");
+    const tokensPath = join(storageRoot, "tokens.json");
     await mkdir(storageRoot, { recursive: true });
     await mkdir(dataDir, { recursive: true });
     const db = initializeDatabase(indexPath);
+    await migrateLocalState({
+        storageRoot,
+        dataDir,
+        configPath,
+        syncCursorPath,
+        tokensPath,
+        db,
+        logger,
+    });
     const indexManager = createIndexManager(db);
     const hierarchyOptions = { dataDir };
-    const gatewayClient = createGatewayClient(config.gateway.url);
+    const dataStorage = createNodeDataStorage({ indexManager, hierarchyOptions });
+    const gatewayClient = options?.gatewayClient ?? createGatewayClient(config.gateway.url);
+    // X402 payment enforcement on data reads. When config.payment.enabled is
+    // true, GET /v1/data/:scope requires builders to supply a signed X-PAYMENT
+    // header on every read; the server forwards to gateway.payForOperation.
+    // See packages/core/src/payment/x402.ts. Off-by-default for development
+    // and test setups where signing payment per read is friction.
+    if (config.payment.enabled) {
+        logger.info("X402 payment enforcement enabled on data reads");
+    }
     // Derive server owner from VANA_MASTER_KEY_SIGNATURE env var
-    const masterKeySignature = process.env.VANA_MASTER_KEY_SIGNATURE;
+    const masterKeySignature = options?.ownerSignature ??
+        process.env.VANA_MASTER_KEY_SIGNATURE;
+    const ownerPrivateKey = process.env.VANA_OWNER_PRIVATE_KEY;
+    const ownerTunnelSigner = ownerPrivateKey
+        ? privateKeyToAccount(ownerPrivateKey.startsWith("0x")
+            ? ownerPrivateKey
+            : `0x${ownerPrivateKey}`)
+        : null;
     let serverOwner;
     let serverAccount;
     let serverSigner;
     let identity;
     if (masterKeySignature) {
-        serverOwner = await recoverServerOwner(masterKeySignature);
+        const recoveredServerOwner = await recoverServerOwner(masterKeySignature);
+        serverOwner = recoveredServerOwner;
         deriveMasterKey(masterKeySignature); // validate signature format
         logger.info({ owner: serverOwner }, "Server owner derived from master key");
-        // Load or create server keypair from disk
+        if (ownerTunnelSigner &&
+            ownerTunnelSigner.address.toLowerCase() !==
+                recoveredServerOwner.toLowerCase()) {
+            throw new Error("VANA_OWNER_PRIVATE_KEY does not match VANA_MASTER_KEY_SIGNATURE owner");
+        }
+        // Enclaves receive public identity only; standard mode owns its key file.
         const keyPath = join(storageRoot, "key.json");
-        serverAccount = loadOrCreateServerAccount(keyPath);
-        logger.info({ owner: serverOwner, serverAddress: serverAccount.address }, "Server signing account loaded");
+        serverAccount =
+            options?.serverAccount ?? loadOrCreateServerAccount(keyPath);
+        logger.info({ owner: serverOwner, serverAddress: serverAccount.address }, "Server account loaded");
         serverSigner = createServerSigner(serverAccount, {
             chainId: config.gateway.chainId,
             contracts: config.gateway.contracts,
@@ -58,9 +128,33 @@ export async function createServer(config, options) {
     else {
         logger.warn("VANA_MASTER_KEY_SIGNATURE not set — owner-restricted endpoints will return 500");
     }
+    // Resolve PS_ACCESS_TOKEN for cloud control-plane / bootstrap auth.
+    // This is not the per-login CLI session token returned to users.
+    let accessToken = process.env.PS_ACCESS_TOKEN;
+    if (!accessToken && process.env.CLOUD_MODE === "true") {
+        try {
+            const metadataRes = await fetch("http://metadata.google.internal/computeMetadata/v1/instance/attributes/ps-access-token", {
+                headers: { "Metadata-Flavor": "Google" },
+                signal: AbortSignal.timeout(2000),
+            });
+            if (metadataRes.ok) {
+                const token = (await metadataRes.text()).trim();
+                if (token.length > 0) {
+                    accessToken = token;
+                    logger.info("PS control-plane token loaded from instance metadata");
+                }
+            }
+        }
+        catch {
+            logger.debug("Could not read PS control-plane token from instance metadata");
+        }
+    }
+    if (accessToken) {
+        logger.info("PS_ACCESS_TOKEN configured — control-plane bearer auth enabled");
+    }
     // Download frpc binary eagerly (auth-independent) so it's ready when the user signs in
     let frpcBinaryPath = "";
-    if (config.tunnel.enabled) {
+    if (config.tunnel.enabled && !isEnclave) {
         try {
             frpcBinaryPath = await ensureFrpcBinary(storageRoot, {
                 log: (msg) => logger.info(msg),
@@ -70,45 +164,181 @@ export async function createServer(config, options) {
             logger.warn({ err }, "Failed to download frpc binary - tunnel disabled");
         }
     }
+    // Derivative data: the gateway lineage client signs lineage reads with the
+    // server key (the gateway treats a registered server as the owner's) and
+    // registers derivatives with their lineage. Needs the server account.
+    // The one server-key request signer: lineage reads, and the inference
+    // relay calls below, authenticate to the gateway with the same scheme.
+    const requestSigner = serverAccount && !isEnclave
+        ? createRequestSigner(serverAccount)
+        : undefined;
+    const lineageGateway = requestSigner
+        ? createGatewayLineageClient({
+            gatewayUrl: config.gateway.url,
+            requestSigner,
+        })
+        : undefined;
     // --- Sync engine setup ---
     let syncManager = null;
+    // Deletion-aware registry view. Independent of sync: the data route uses
+    // it to answer 410 for scopes the owner deleted even when sync is off.
+    const dataPointFeed = options?.dataPointFeed ??
+        createGatewayDataPointFeed({ gatewayUrl: config.gateway.url });
+    // Read-side memory of tombstones, shared by the sync workers (which feed
+    // it) and the data route (which consults it on every read).
+    const scopeDeletions = createScopeDeletionTracker({
+        feed: dataPointFeed,
+        serverOwner,
+        logger,
+    });
+    // --- Derivative compute (question -> derivative) ---
+    // The scheduler exists before the sync manager so downloads can mark
+    // questions stale; it reaches the sync manager lazily to upload results.
+    const questionStore = createSqliteQuestionStore(db);
+    const inferenceBaseUrl = process.env.INFERENCE_BASE_URL ?? config.inference.baseUrl;
+    // E2EE to the Phala gateway is on unless config or INFERENCE_E2EE=false
+    // turns it off (local development against a provider without ACI).
+    const inferenceE2ee = process.env.INFERENCE_E2EE !== undefined
+        ? process.env.INFERENCE_E2EE !== "false"
+        : config.inference.e2ee;
+    // Local development only: production relays hold the provider key. A key
+    // means the base URL is a provider, not the relay, so nothing is signed.
+    const inferenceApiKey = process.env.INFERENCE_API_KEY;
+    // The Vana inference relay only forwards requests signed by the owner or
+    // by one of the owner's active registered servers; this is the same
+    // server-key signer the lineage reads use.
+    const inferenceSigner = inferenceApiKey ? undefined : requestSigner;
+    const inferenceProvider = options?.inferenceProvider ??
+        createOpenAiCompatibleInferenceProvider({
+            baseUrl: inferenceBaseUrl,
+            model: process.env.INFERENCE_MODEL ?? config.inference.model,
+            apiKey: inferenceApiKey,
+            requestSigner: inferenceSigner,
+            encryption: inferenceE2ee
+                ? createPhalaE2eeEncryption({
+                    baseUrl: inferenceBaseUrl,
+                    requestSigner: inferenceSigner,
+                    logger,
+                })
+                : undefined,
+        });
+    if (!inferenceE2ee) {
+        logger.warn({ baseUrl: inferenceBaseUrl }, "Inference E2EE is disabled: prompts and answers travel as plaintext over TLS");
+    }
+    const derivativeScheduler = createRecomputeScheduler({
+        store: questionStore,
+        debounceMs: config.inference.recomputeDebounceMs,
+        serverOwner,
+        logger,
+        compute: (questionId) => computeQuestion(questionId, {
+            // A -> B -> C: a question reading this derived scope recomputes.
+            onDerivedWritten: (event) => derivativeScheduler.markSourceChanged(event.scope, {
+                lineageSources: event.lineageSources,
+            }),
+            storage: dataStorage,
+            store: questionStore,
+            provider: inferenceProvider,
+            serverOwner,
+            maxSourceItems: config.inference.maxSourceItems,
+            syncManager: {
+                notifyNewData: () => syncManager?.notifyNewData(),
+            },
+            scopeDeletions,
+            writePolicyPorts: {
+                authSessionVerifier: gatewayClient,
+                grantVerifier: gatewayClient,
+            },
+            logger,
+        }),
+    });
+    const derivativeCompute = {
+        store: questionStore,
+        scheduler: derivativeScheduler,
+    };
     if (config.sync.enabled &&
         masterKeySignature &&
         serverOwner &&
         serverAccount &&
         serverSigner) {
         const masterKey = deriveMasterKey(masterKeySignature);
-        const vanaConfig = config.storage.config.vana ?? {
-            apiUrl: "https://storage.vana.com",
-        };
-        const requestSigner = createRequestSigner(serverAccount);
-        const storageAdapter = createVanaStorageAdapter({
-            apiUrl: vanaConfig.apiUrl,
-            ownerAddress: serverOwner,
-            signer: requestSigner,
+        const storageAdapter = createVanaSyncStorageAdapter({
+            config,
+            serverOwner,
+            serverAccount,
+            reads: isEnclave ? "public" : "signed",
+        });
+        const cursor = createSyncCursor(syncCursorPath, {
+            legacyConfigPath: configPath,
         });
-        const cursor = createSyncCursor(configPath);
         const uploadDeps = {
-            indexManager,
-            hierarchyOptions,
+            storage: dataStorage,
             storageAdapter,
             gateway: gatewayClient,
             signer: serverSigner,
             masterKey,
             serverOwner,
             logger,
+            lineageGateway,
+            dataPointFeed,
+            scopeDeletions,
         };
         const downloadDeps = {
-            indexManager,
-            hierarchyOptions,
+            storage: dataStorage,
             storageAdapter,
             gateway: gatewayClient,
             cursor,
             masterKey,
             serverOwner,
             logger,
+            dataPointFeed,
+            scopeDeletions,
+            onDataPointIndexed: (event) => derivativeScheduler.markSourceChanged(event.scope, {
+                lineageSources: event.lineageSources,
+            }),
         };
-        syncManager = createSyncManager(uploadDeps, downloadDeps);
+        // Durable deletion: gateway tombstone signed with the same server
+        // account + AddData signer uploads use, storage DELETE authorised with
+        // the same Web3Signed signer the storage provider uploads with.
+        const deleteData = isEnclave
+            ? null
+            : createGatewayDeleteDataPort({
+                gatewayUrl: config.gateway.url,
+                dataPointFeed,
+                serverOwner,
+                signer: serverSigner,
+                storage: {
+                    endpoint: resolveVanaStorageEndpoint(config),
+                    chainId: config.gateway.chainId,
+                    signMessage: (message) => serverAccount.signMessage(message),
+                },
+            });
+        const pendingBlobDeletions = createFilePendingBlobDeletionStore(pendingBlobDeletionsPath);
+        syncManager = createSyncManager(uploadDeps, downloadDeps, {
+            deleteData,
+            pendingBlobDeletions,
+            transferMode: isEnclave ? "download-only" : "upload-download",
+            async canSync() {
+                try {
+                    const serverInfo = await gatewayClient.getServer(serverAccount.address);
+                    identity.serverId = serverInfo?.id ?? null;
+                    if (serverInfo?.id)
+                        return { ok: true };
+                    return {
+                        ok: false,
+                        reason: "unregistered",
+                        message: "Register this Personal Server before syncing.",
+                    };
+                }
+                catch (err) {
+                    logger.warn({ err }, "Could not verify server registration for sync");
+                    return {
+                        ok: false,
+                        reason: "registration_check_failed",
+                        message: "Could not verify server registration before syncing.",
+                    };
+                }
+            },
+        });
         syncManager.start();
         logger.info("Sync engine started");
     }
@@ -120,11 +350,51 @@ export async function createServer(config, options) {
     const accessLogWriter = createAccessLogWriter(logsDir);
     const accessLogReader = createAccessLogReader(logsDir);
     // Generate ephemeral dev token when devUi is enabled
-    const devToken = config.devUi.enabled ? generateDevToken() : undefined;
+    const devToken = config.devUi.enabled && !isEnclave ? generateDevToken() : undefined;
+    // Token store for /auth/device flow (self-hosted CLI auth)
+    const tokenStore = createTokenStore(tokensPath, logger);
+    const cloudMode = process.env.CLOUD_MODE === "true";
+    const localApprovalPort = cloudMode || isEnclave
+        ? undefined
+        : resolveLocalApprovalPort(config.server.port);
     // Mutable origin — starts with config value, updated when tunnel connects
     let effectiveOrigin = config.server.origin;
+    let effectiveLocalApprovalOrigin;
     // Mutable tunnelManager — set when tunnel starts in background
     let tunnelManager;
+    // Registration can land after boot (desktop signing exchange or the
+    // /ui/api registration route); the tunnel connect is gated on it, so the
+    // route needs a way to trigger the deferred connect. Assigned inside
+    // startBackgroundServices once the tunnel is reserved.
+    let notifyServerRegistered = () => { };
+    let registrationPollTimer = null;
+    // Set by cleanup(). A poll iteration that is mid-flight when cleanup runs
+    // holds no timer handle, so clearing the timer alone cannot stop it — and
+    // a reserved-but-never-connected TunnelManager would happily spawn frpc
+    // from an orphaned poll after shutdown. Every deferred path checks this.
+    let backgroundClosed = false;
+    const clearRegistrationPoll = () => {
+        if (registrationPollTimer) {
+            clearTimeout(registrationPollTimer);
+            registrationPollTimer = null;
+        }
+    };
+    const ecies = new NodeECIESProvider();
+    const jobWorker = isEnclave && serverOwner && serverAccount
+        ? (envelope) => executeJob(envelope, {
+            serverOwner,
+            serverAddress: serverAccount.address,
+            serverPublicKey: serverAccount.publicKey,
+            authAudience: config.gateway.url.replace(TRAILING_SLASHES, ""),
+            gateway: gatewayClient,
+            gatewayConfig: config.gateway,
+            storage: dataStorage,
+            ecies,
+            logger,
+            accessLogWriter,
+            scopeDeletions,
+        })
+        : undefined;
     const app = createApp({
         logger,
         version: pkg.version,
@@ -132,18 +402,40 @@ export async function createServer(config, options) {
         indexManager,
         hierarchyOptions,
         serverOrigin: () => effectiveOrigin,
+        localApprovalOrigin: () => effectiveLocalApprovalOrigin,
         serverOwner,
         identity,
         gateway: gatewayClient,
+        gatewayConfig: config.gateway,
+        paymentEnabled: config.payment.enabled,
+        gatewayUrl: config.gateway.url,
+        lineageGateway,
+        derivativeCompute,
+        config,
         accessLogWriter,
         accessLogReader,
+        readFulfillmentReporter: options?.readFulfillmentReporter,
+        dataStorage,
+        scopeDeletions,
+        cloudMode,
         devToken,
+        ownerSignature: masterKeySignature,
+        ownerPrivateKey,
+        accessToken,
+        tokenStore,
         configPath,
         syncManager,
         serverSigner,
         getTunnelStatus: () => tunnelManager?.getStatus() ?? null,
+        mcpOAuthApprovalUrl: options?.mcpOAuthApprovalUrl,
+        onServerRegistered: (serverId) => notifyServerRegistered(serverId),
+        profile: options?.profile,
+        jobWorker,
     });
     const cleanup = async () => {
+        backgroundClosed = true;
+        clearRegistrationPoll();
+        derivativeScheduler.stop();
         if (tunnelManager) {
             await tunnelManager.stop();
         }
@@ -165,8 +457,20 @@ export async function createServer(config, options) {
         syncManager,
         tunnelManager,
         tunnelUrl: undefined,
+        isServerRegistered: () => Boolean(identity?.serverId),
+        localApprovalPort,
+        getLocalApprovalOrigin: () => effectiveLocalApprovalOrigin,
+        setLocalApprovalOrigin: (origin) => {
+            effectiveLocalApprovalOrigin = origin;
+        },
         devToken,
         startBackgroundServices: async () => {
+            // Replay questions a previous run left pending or stale: nothing
+            // else reschedules them after a restart (registration and source
+            // changes only cover new activity).
+            if (!isEnclave) {
+                derivativeScheduler.start();
+            }
             // --- Gateway registration check (slow: HTTP call) ---
             if (serverAccount && identity) {
                 try {
@@ -187,33 +491,124 @@ export async function createServer(config, options) {
                 }
             }
             // --- Tunnel setup (slow: subprocess wait) ---
-            if (config.tunnel.enabled &&
+            if (!isEnclave &&
+                config.tunnel.enabled &&
                 serverOwner &&
                 serverAccount &&
                 frpcBinaryPath) {
                 tunnelManager = new TunnelManager(storageRoot);
                 context.tunnelManager = tunnelManager;
                 const runId = randomUUID();
+                let tunnelConnectStarted = false;
+                const connectTunnel = async () => {
+                    const manager = tunnelManager;
+                    if (!manager || tunnelConnectStarted || backgroundClosed) {
+                        return;
+                    }
+                    tunnelConnectStarted = true;
+                    try {
+                        const url = await manager.connect();
+                        const tunnelStatus = manager.getStatus();
+                        if (tunnelStatus.status === "connected") {
+                            logger.info({ tunnelUrl: url }, "Tunnel established");
+                        }
+                        else {
+                            logger.warn({ tunnelUrl: url, warning: tunnelStatus.warning }, "Tunnel URL reserved; waiting for tunnel connection");
+                        }
+                    }
+                    catch (err) {
+                        logger.warn({ err }, "Tunnel failed to connect - server running in local-only mode");
+                        tunnelManager = undefined;
+                        context.tunnelManager = undefined;
+                        // Local-only mode must keep the local audience/URL: leaving the
+                        // public URL as effectiveOrigin would reject local Web3Signed
+                        // callers against an origin that will never route.
+                        effectiveOrigin = config.server.origin;
+                        context.tunnelUrl = undefined;
+                    }
+                };
+                // Poll fallback for registrations the route callback can't see
+                // (e.g. desktop registers with the gateway directly and the sidecar
+                // only observes it via a gateway lookup).
+                const scheduleRegistrationPoll = () => {
+                    const pollStartedAt = Date.now();
+                    const poll = async () => {
+                        registrationPollTimer = null;
+                        if (backgroundClosed) {
+                            return;
+                        }
+                        try {
+                            const serverInfo = await gatewayClient.getServer(serverAccount.address);
+                            if (serverInfo?.id) {
+                                if (identity) {
+                                    identity.serverId = serverInfo.id;
+                                }
+                                logger.info("Server registration detected — starting tunnel");
+                                await connectTunnel();
+                                return;
+                            }
+                        }
+                        catch {
+                            // Gateway unreachable — keep polling.
+                        }
+                        if (backgroundClosed) {
+                            return;
+                        }
+                        const interval = Date.now() - pollStartedAt < 2 * 60_000 ? 5_000 : 30_000;
+                        registrationPollTimer = setTimeout(() => void poll(), interval);
+                        registrationPollTimer.unref?.();
+                    };
+                    registrationPollTimer = setTimeout(() => void poll(), 5_000);
+                    registrationPollTimer.unref?.();
+                };
+                notifyServerRegistered = (serverId) => {
+                    if (backgroundClosed) {
+                        return;
+                    }
+                    if (serverId) {
+                        if (identity) {
+                            identity.serverId = serverId;
+                        }
+                        // Only a confirmed serverId stops the poll: on a null result the
+                        // poll keeps running so identity/health converge once the
+                        // gateway lookup sees the registration.
+                        clearRegistrationPoll();
+                    }
+                    void connectTunnel();
+                };
                 try {
-                    const url = await tunnelManager.start({
+                    // Reserve the public URL without dialing the relay: the URL is
+                    // what registration needs, and dialing before the registration
+                    // lands poisons the relay's delegation cache (BUI-611).
+                    const url = tunnelManager.reserve({
                         walletAddress: serverAccount.address,
                         ownerAddress: serverOwner,
                         serverKeypair: serverAccount,
+                        tunnelSigner: ownerTunnelSigner
+                            ? {
+                                signMessage: (message) => ownerTunnelSigner.signMessage({ message }),
+                            }
+                            : undefined,
                         runId,
                         serverAddr: config.tunnel.serverAddr,
                         serverPort: config.tunnel.serverPort,
                         localPort: config.server.port,
                     }, frpcBinaryPath);
-                    logger.info({ tunnelUrl: url }, "Tunnel established");
                     context.tunnelUrl = url;
+                    // The public URL is the audience clients sign against, so adopt it
+                    // as the effective origin as soon as it's known (matches the
+                    // unity-surfaces #583 sidecar patch).
                     effectiveOrigin = url;
-                    if (!identity?.serverId) {
-                        logger.warn("Tunnel started but server is not registered with gateway — tunnel will not route traffic. Run: npm run register-server");
-                        tunnelManager.setVerified(false, "Server not registered with gateway");
+                    if (identity?.serverId) {
+                        await connectTunnel();
+                    }
+                    else {
+                        logger.info({ tunnelUrl: url }, "Tunnel start deferred until server registration — register to enable routing");
+                        scheduleRegistrationPoll();
                     }
                 }
                 catch (err) {
-                    logger.warn({ err }, "Tunnel failed to connect - server running in local-only mode");
+                    logger.warn({ err }, "Tunnel failed to start - server running in local-only mode");
                     tunnelManager = undefined;
                     context.tunnelManager = undefined;
                 }