@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/cli/serve/index.js

@@ -1,25 +1,26 @@
 import path from 'node:path';
+import { cancel, isCancel, select } from '@clack/prompts';
 import chokidar from 'chokidar';
-import { compileAll } from '../../builder/compile/compile-sequence.js';
+import { compileAll, compileCompanyMetadataFromRepo, compileCompanyPart, runtimePackageSource, runtimePackageVersion, } from '../../builder/compile/compile-sequence.js';
 import { withCompanyImportGraph } from '../../builder/company-import-graph.js';
-import { findTsModule } from '../../builder/paths.js';
-import { listSequenceIds, loadSequenceCaseContextView, loadSequenceFunctions } from '../../builder/load.js';
+import { findTsModule, requireCompanyResolveModule, requireResolveModule } from '../../builder/paths.js';
+import { listSequenceIds, loadCompanyWebhook, loadSequenceCaseOrchestrator, WEBHOOK_MODULE, loadCompanyResolver, loadSequenceResolver, loadSequenceEvents, loadSequenceFunctions, } from '../../builder/load.js';
+import { loadSchedules } from '../../builder/schedules.js';
+import { ORCHESTRATOR_CONTACTS_FUNCTION, ORCHESTRATOR_FUNCTION } from '../../core/case-orchestrator/types.js';
+import { WEBHOOK_RECEIVED_FUNCTION } from '../../core/functions/events.js';
+import { COMPANY_RESOLVE_FUNCTION, RESOLVE_FUNCTION } from '../../core/party/types.js';
+import { COMPANY_SCOPE } from '../../builder/types.js';
 import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
+import { formatRuntimeVersion } from '../../fn-context/rpc/request-id.js';
 import { encodeOverlayMessage, OVERLAY_REPLACED_CLOSE_CODE, parseOverlayMessage, } from '../../dev-overlay/protocol.js';
-const DEFAULT_BACKEND_URL = 'http://127.0.0.1:8100';
-function env(name) {
-    const value = process.env[name];
-    return value && value.length > 0 ? value : undefined;
-}
+import { getLogger } from '../../logger.js';
+import { listServeEnvironments, loadCachedServeAuthorization, resolveBackendUrl, ServeAuthorizationRejectedError, } from '../auth/auth.js';
+import { forgetServeAuthorization, loginServe } from '../auth/serve-login.js';
+import { toHttpUrl, toWsUrl } from '../auth/backend-url.js';
+import { progressIndicator } from '../auth/progress.js';
+const logger = getLogger(['runtime', 'overlay']);
 export function overlayWebSocketUrl(raw) {
-    const url = new URL(raw);
-    if (url.protocol === 'http:')
-        url.protocol = 'ws:';
-    else if (url.protocol === 'https:')
-        url.protocol = 'wss:';
-    else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
-        throw new Error(`unsupported backend url: ${raw}`);
-    }
+    const url = toWsUrl(raw);
     const path = url.pathname.replace(/\/$/, '');
     if (path === '')
         url.pathname = '/overlay';
@@ -27,15 +28,33 @@ export function overlayWebSocketUrl(raw) {
     url.hash = '';
     return url.toString();
 }
+function overlayRpcUrl(raw) {
+    const url = toHttpUrl(raw);
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/trpc`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
 /** `sequences/<id>/…` → sequence id */
 function sequenceIdFromPath(repoRoot, file) {
     const rel = path.relative(repoRoot, file);
     const match = /^sequences[/\\]([^/\\]+)(?:[/\\]|$)/.exec(rel);
     return match?.[1] ?? null;
 }
-function isSchemaPath(repoRoot, file) {
-    const rel = path.relative(repoRoot, file);
-    return rel === 'schema.ts' || rel.startsWith(`schema${path.sep}`) || rel.startsWith('schema/');
+/** Not the repository's code: dependencies, git, and what compiling writes. */
+export function isIgnoredServePath(repoRoot, file) {
+    const parts = path.relative(repoRoot, file).split(/[/\\]/);
+    return parts.some((part) => part === 'node_modules' || part === '__gen' || part === 'build' || part === 'dist' || part.startsWith('.'));
+}
+/**
+ * What a changed file recompiles (22-sequence-as-business-unit §6): a file of one sequence, that
+ * sequence; anything else (`schema/`, `resolve.ts`, shared code) can reach every sequence, so all.
+ */
+export function reloadScopeForPath(repoRoot, file) {
+    if (isIgnoredServePath(repoRoot, file))
+        return null;
+    const sequenceId = sequenceIdFromPath(repoRoot, file);
+    return sequenceId ? { sequenceId } : 'all';
 }
 async function loadOne(repoRoot, sequenceId, generation) {
     return withCompanyImportGraph(repoRoot, async () => {
@@ -52,54 +71,148 @@ async function loadOne(repoRoot, sequenceId, generation) {
         if (!functionsPath) {
             throw new Error(`No functions module for sequence ${sequenceId}`);
         }
-        const functions = await loadSequenceFunctions(functionsPath);
-        const viewPath = findTsModule(sequenceDir, 'view');
-        const view = viewPath ? await loadSequenceCaseContextView(viewPath) : undefined;
-        return { build: compiled.build, functions, view, generation };
+        const caseOrchestratorPath = findTsModule(sequenceDir, 'orchestrator');
+        const authored = await loadSequenceFunctions(functionsPath);
+        const functions = {
+            ...authored,
+            [RESOLVE_FUNCTION]: await loadSequenceResolver(requireResolveModule(sequenceDir, sequenceId)),
+            ...(caseOrchestratorPath ? await caseOrchestratorFunctions(caseOrchestratorPath) : {}),
+            // The jobs of its schedules.ts run here too while serving (25 §6.4).
+            ...(await loadSchedules(sequenceDir, `sequences/${sequenceId}/schedules.ts`))?.functions,
+        };
+        const eventsPath = findTsModule(sequenceDir, 'events');
+        const events = eventsPath ? await loadSequenceEvents(eventsPath) : {};
+        return { build: compiled.build, functions, events, generation };
     });
 }
+export async function loadCompany(repoRoot) {
+    return withCompanyImportGraph(repoRoot, async () => {
+        const webhookPath = findTsModule(repoRoot, WEBHOOK_MODULE);
+        return {
+            part: await compileCompanyPart(repoRoot, { includeCode: false }),
+            companyMetadata: await compileCompanyMetadataFromRepo(repoRoot),
+            functions: {
+                [COMPANY_RESOLVE_FUNCTION]: await loadCompanyResolver(requireCompanyResolveModule(repoRoot)),
+                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: await loadCompanyWebhook(webhookPath) } : {}),
+                ...(await loadSchedules(repoRoot, 'schedules.ts'))?.functions,
+            },
+        };
+    });
+}
+/** orchestrator.ts's two functions, as the build names them. */
+async function caseOrchestratorFunctions(path) {
+    const { orchestrator, contacts } = await loadSequenceCaseOrchestrator(path);
+    return {
+        [ORCHESTRATOR_FUNCTION]: { kind: 'orchestrator', main: orchestrator },
+        [ORCHESTRATOR_CONTACTS_FUNCTION]: { kind: 'orchestrator', main: contacts },
+    };
+}
+/** The repository's sequences, compiled; a listed sequence missing from the repository is left out. */
 async function loadSequences(repoRoot, sequenceIds, generation) {
     return withCompanyImportGraph(repoRoot, async () => {
+        const present = new Set(listSequenceIds(repoRoot));
         const out = new Map();
         for (const sequenceId of sequenceIds) {
-            out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
+            if (present.has(sequenceId))
+                out.set(sequenceId, await loadOne(repoRoot, sequenceId, generation));
         }
         return out;
     });
 }
+/**
+ * The changes waiting to be reloaded. A reload that fails keeps its scope (`fail`) for the next one,
+ * which a new file change starts (no retry on its own: the failure is in the code until it is
+ * edited); it is cleared only once a reload of it loads.
+ */
+export class ReloadQueue {
+    pending = { all: false, ids: new Set() };
+    failed = { all: false, ids: new Set() };
+    add(scope) {
+        if (scope === 'all')
+            this.pending.all = true;
+        else
+            this.pending.ids.add(scope.sequenceId);
+    }
+    /** Something changed since the last reload. */
+    hasChanges() {
+        return this.pending.all || this.pending.ids.size > 0;
+    }
+    /** The next reload: the new changes plus what failed before. */
+    take() {
+        const all = this.pending.all || this.failed.all;
+        const job = { all, ids: all ? new Set() : new Set([...this.failed.ids, ...this.pending.ids]) };
+        this.pending = { all: false, ids: new Set() };
+        this.failed = { all: false, ids: new Set() };
+        return job;
+    }
+    fail(job) {
+        this.failed = { all: this.failed.all || job.all, ids: new Set([...this.failed.ids, ...job.ids]) };
+    }
+}
+/**
+ * The state after a reload (`all`: the whole repository; else the sequences `ids` names), built
+ * aside: if any part fails to load it throws and the current state stays whole, never new company
+ * code with old sequences.
+ */
+export async function reloadServeState(repoRoot, current, job, generation) {
+    // Recompiling everything also picks up sequence directories added or removed since.
+    const ids = job.all ? listSequenceIds(repoRoot) : [...job.ids];
+    // The company's code is outside `sequences/`, so only a recompile of everything reaches it.
+    const company = job.all ? await loadCompany(repoRoot) : current.company;
+    const loaded = await loadSequences(repoRoot, ids, generation);
+    const sequences = job.all ? new Map() : new Map(current.sequences);
+    for (const id of ids) {
+        const next = loaded.get(id);
+        if (next)
+            sequences.set(id, next);
+        else
+            sequences.delete(id);
+    }
+    return { company, sequences };
+}
 function send(ws, message) {
     ws.send(encodeOverlayMessage(message));
 }
 function logField(label, value) {
-    console.log(`  ${label.padEnd(10)} ${value}`);
+    logger.info(label, value);
 }
-async function handleExecute(loaded, message) {
+async function handleExecute(loaded, message, rpcUrl) {
+    const data = message.data
+        ? {
+            ...message.data,
+            config: { ...message.data.config, backendUrl: rpcUrl },
+        }
+        : undefined;
     const host = createSourceComputeHost({
         functions: loaded.functions,
-        caseContextView: loaded.view,
-        data: message.data,
+        events: loaded.events,
+        data: data,
         runToken: message.runToken,
-        runtimeVersion: loaded.build.runtimeVersion ?? loaded.build.engineVersion,
-        runtimeSource: loaded.build.runtimeSource ?? 'npm',
+        runtimeVersion: loaded.runtimeVersion,
+        runtimeSource: loaded.runtimeSource,
         getRequestId: () => message.logRequestId,
         getTags: () => message.logTags,
     });
     try {
-        return await host.execute(message.name, message.args);
+        return await host.execute(message.name, message.invocation);
     }
     finally {
         host.dispose();
     }
 }
-function pushOverlays(ws, sequences) {
-    for (const [sequenceId, loaded] of sequences) {
-        send(ws, {
-            type: 'overlay',
-            sequenceId,
-            generation: loaded.generation,
-            build: loaded.build,
-        });
-    }
+/**
+ * Push the local company build: the company's functions and every loaded sequence, as one overlay.
+ * With no sequence left it is still pushed, so the environment drops the ones it had (22 §11).
+ */
+export function pushOverlay(ws, company, sequences, generation) {
+    const build = {
+        company: company.part,
+        sequences: Object.fromEntries([...sequences].map(([sequenceId, sequence]) => [sequenceId, sequence.build])),
+    };
+    send(ws, { type: 'overlay', generation, build, companyMetadata: company.companyMetadata });
+}
+function closeDetail(event) {
+    return event.reason ? `${event.code} ${event.reason}` : String(event.code);
 }
 function waitOpen(ws) {
     return new Promise((resolve, reject) => {
@@ -107,8 +220,27 @@ function waitOpen(ws) {
             resolve();
             return;
         }
-        ws.addEventListener('open', () => resolve(), { once: true });
-        ws.addEventListener('error', () => reject(new Error('websocket error')), { once: true });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        const onOpen = () => finish(() => resolve());
+        const onClose = (event) => finish(() => reject(new Error(`websocket closed ${closeDetail(event)}`)));
+        const onError = () => {
+            setTimeout(() => finish(() => reject(new Error('websocket error'))), 250);
+        };
+        const cleanup = () => {
+            ws.removeEventListener('open', onOpen);
+            ws.removeEventListener('close', onClose);
+            ws.removeEventListener('error', onError);
+        };
+        ws.addEventListener('open', onOpen);
+        ws.addEventListener('close', onClose);
+        ws.addEventListener('error', onError);
     });
 }
 class OverlayReplacedError extends Error {
@@ -117,6 +249,36 @@ class OverlayReplacedError extends Error {
         this.name = 'OverlayReplacedError';
     }
 }
+/** Transient: an infra hiccup, or a lease that was just replaced. Retry with backoff. */
+class OverlayUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverlayUnavailableError';
+    }
+}
+/** Permanent: the request itself is invalid (missing or unknown environment, prod). Fatal. */
+class OverlayRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverlayRequestError';
+    }
+}
+export function toOverlayError(message) {
+    switch (message.code) {
+        case 'authorization':
+            return new ServeAuthorizationRejectedError(message.error);
+        case 'request':
+            return new OverlayRequestError(message.error);
+        case 'unavailable':
+            return new OverlayUnavailableError(message.error);
+        default: {
+            // The wire format is not type-checked: a code this CLI doesn't know is a protocol bug, so
+            // stop and say so instead of reconnecting forever on an `undefined` error.
+            const unknown = message.code;
+            return new OverlayRequestError(`unknown auth.error code ${JSON.stringify(unknown)}: ${message.error}`);
+        }
+    }
+}
 function waitAuthOk(ws) {
     return new Promise((resolve, reject) => {
         const onMessage = (event) => {
@@ -134,7 +296,7 @@ function waitAuthOk(ws) {
                 }
                 if (message.type === 'auth.error') {
                     cleanup();
-                    reject(new Error(message.error));
+                    reject(toOverlayError(message));
                 }
             }
             catch (error) {
@@ -146,7 +308,7 @@ function waitAuthOk(ws) {
             cleanup();
             reject(event.code === OVERLAY_REPLACED_CLOSE_CODE
                 ? new OverlayReplacedError()
-                : new Error('websocket closed before auth.ok'));
+                : new Error(`websocket closed before auth.ok ${closeDetail(event)}`));
         };
         const cleanup = () => {
             ws.removeEventListener('message', onMessage);
@@ -156,7 +318,7 @@ function waitAuthOk(ws) {
         ws.addEventListener('close', onClose);
     });
 }
-function attachExecuteHandler(ws, sequences) {
+function attachExecuteHandler(ws, find, rpcUrl) {
     ws.addEventListener('message', (event) => {
         void (async () => {
             let message;
@@ -164,57 +326,88 @@ function attachExecuteHandler(ws, sequences) {
                 message = parseOverlayMessage(String(event.data));
             }
             catch (error) {
-                console.error('bad server message:', error instanceof Error ? error.message : error);
+                logger.error('bad server message', error);
                 return;
             }
             if (message.type !== 'execute')
                 return;
-            const call = `${message.sequenceId} ${message.name}`;
-            const loaded = sequences.get(message.sequenceId);
+            const loaded = find(message.sequenceId);
             if (!loaded) {
                 const error = `unknown sequence ${message.sequenceId}`;
-                console.error(`execute ${call} failed: ${error}`);
                 send(ws, {
                     type: 'execute.result',
                     requestId: message.requestId,
                     ok: false,
                     error,
                 });
+                logger.error('execute failed', { sequenceId: message.sequenceId, name: message.name, error });
                 return;
             }
             const started = Date.now();
-            console.log(`execute ${call}`);
+            let result;
             try {
-                const result = await handleExecute(loaded, message);
-                console.log(`execute ${call} ok ${Date.now() - started}ms`);
-                send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
+                result = await handleExecute(loaded, message, rpcUrl);
             }
             catch (error) {
                 const text = error instanceof Error ? error.message : String(error);
-                console.error(`execute ${call} failed: ${text}`);
                 send(ws, {
                     type: 'execute.result',
                     requestId: message.requestId,
                     ok: false,
                     error: text,
                 });
+                logger.error('execute failed', {
+                    sequenceId: message.sequenceId,
+                    name: message.name,
+                    durationMs: Date.now() - started,
+                    error: text,
+                });
+                return;
             }
+            send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
+            logger.info('execute ok', {
+                sequenceId: message.sequenceId,
+                name: message.name,
+                durationMs: Date.now() - started,
+            });
         })();
     });
 }
+function attachNoticeHandler(ws) {
+    ws.addEventListener('message', (event) => {
+        let message;
+        try {
+            message = parseOverlayMessage(String(event.data));
+        }
+        catch {
+            return;
+        }
+        if (message.type !== 'notice')
+            return;
+        if (message.details.length > 0)
+            logger.warn(message.message, message.details);
+        else
+            logger.warn(message.message);
+    });
+}
 function waitSessionEnd(ws) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         if (ws.readyState === WebSocket.CLOSED) {
-            resolve('closed');
+            resolve({ closed: 'already closed' });
             return;
         }
         const onMessage = (event) => {
             try {
                 const message = parseOverlayMessage(String(event.data));
                 if (message.type === 'replaced') {
+                    logger.warn('another serve took the environment');
                     cleanup();
                     resolve('replaced');
                 }
+                else if (message.type === 'auth.error') {
+                    cleanup();
+                    reject(toOverlayError(message));
+                }
             }
             catch {
                 return;
@@ -222,7 +415,7 @@ function waitSessionEnd(ws) {
         };
         const onClose = (event) => {
             cleanup();
-            resolve(event.code === OVERLAY_REPLACED_CLOSE_CODE ? 'replaced' : 'closed');
+            resolve(event.code === OVERLAY_REPLACED_CLOSE_CODE ? 'replaced' : { closed: closeDetail(event) });
         };
         const cleanup = () => {
             ws.removeEventListener('message', onMessage);
@@ -232,30 +425,128 @@ function waitSessionEnd(ws) {
         ws.addEventListener('close', onClose);
     });
 }
+function exitOnCancel() {
+    cancel('Cancelled.');
+    process.exit(1);
+}
+/**
+ * Only prompt when there's an actual person at a terminal to answer — a CI runner, a piped/
+ * redirected stdin, or any other non-interactive invocation must keep failing fast on a missing
+ * flag instead of hanging on a readline prompt with undefined behavior off a real TTY.
+ */
+function requireInteractiveOrThrow(flag) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error(`${flag} is required (not running in an interactive terminal to prompt for it)`);
+    }
+}
+/** The token's non-prod environments. A rejected token surfaces as `ServeAuthorizationRejectedError`. */
+async function fetchEnvironments(backendUrl, authorization) {
+    const progress = progressIndicator();
+    const company = authorization.companyName ? ` in ${authorization.companyName}` : '';
+    progress.start(`Fetching environments${company}…`);
+    let environments;
+    try {
+        environments = await listServeEnvironments(backendUrl, authorization.token);
+    }
+    catch (error) {
+        if (error instanceof ServeAuthorizationRejectedError) {
+            progress.error('Login was rejected by the backend.');
+            throw error;
+        }
+        progress.error('Could not fetch environments.');
+        throw new Error(`Could not list environments: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    progress.stop(`Found ${environments.length} environment${environments.length === 1 ? '' : 's'}${company}.`);
+    return environments;
+}
+/**
+ * Login plus the company's environments. Listing them doubles as checking the cached token against
+ * the backend: it can be unexpired locally yet rejected (revoked, re-keyed, access removed), and
+ * then it is dropped for a fresh browser login. Rejections after startup stop serve instead.
+ */
+async function authorizeWithEnvironments(backendUrl, openBrowser) {
+    const cached = await loadCachedServeAuthorization(backendUrl);
+    if (cached) {
+        logger.info('using cached serve authorization');
+        try {
+            return { authorization: cached, environments: await fetchEnvironments(backendUrl, cached) };
+        }
+        catch (error) {
+            if (!(error instanceof ServeAuthorizationRejectedError))
+                throw error;
+            logger.warn('cached serve authorization is no longer valid; authorizing again', { error: error.message });
+            await forgetServeAuthorization(backendUrl, cached);
+        }
+    }
+    const authorization = await loginServe(backendUrl, { openBrowser });
+    return { authorization, environments: await fetchEnvironments(backendUrl, authorization) };
+}
+/** Prompts for one non-prod environment when `--environment` was not given. Shows id and name. */
+async function promptForEnvironment(environments) {
+    if (environments.length === 0) {
+        throw new Error('No non-prod environments available for this company.');
+    }
+    const picked = await select({
+        message: 'Which environment should Local Serve overlay?',
+        options: environments.map((environment) => ({
+            value: environment.id,
+            label: environment.name,
+            hint: environment.id,
+        })),
+    });
+    if (isCancel(picked))
+        exitOnCancel();
+    return picked;
+}
 export async function runServe(repoRoot, options = {}) {
-    const companyId = options.companyId ?? env('SUPERPANEL_SDK_COMPANY_ID');
-    const apiKey = options.apiKey ?? env('SUPERPANEL_SDK_API_KEY');
-    if (!companyId)
-        throw new Error('SUPERPANEL_SDK_COMPANY_ID or --company is required');
-    if (!apiKey)
-        throw new Error('SUPERPANEL_SDK_API_KEY or --api-key is required');
-    const backendUrl = options.url ?? env('SUPERPANEL_SDK_BACKEND_URL') ?? DEFAULT_BACKEND_URL;
-    const url = overlayWebSocketUrl(backendUrl);
-    const sequenceIds = options.sequenceIds ?? listSequenceIds(repoRoot);
-    if (sequenceIds.length === 0) {
-        throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')}`);
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    // A non-interactive caller cannot answer the prompt. Check this before authorization so a CI job
+    // with a missing flag fails instead of waiting on a browser-based device-auth flow.
+    let environment = options.environment?.trim();
+    if (!environment)
+        requireInteractiveOrThrow('--environment <id>');
+    if (listSequenceIds(repoRoot).length === 0) {
+        throw new Error(`No sequences found under ${path.join(repoRoot, 'sequences')}`);
     }
+    // Login is the first interactive step: the environment prompt needs the company-scoped token.
+    const { authorization, environments } = await authorizeWithEnvironments(backendUrl, options.openBrowser !== false);
+    if (!environment)
+        environment = await promptForEnvironment(environments);
+    // The whole repository serves the environment (22 §6): every sequence, and only these.
     let generation = 1;
-    const sequences = await loadSequences(repoRoot, sequenceIds, generation);
+    let company = await loadCompany(repoRoot);
+    let sequences = await loadSequences(repoRoot, listSequenceIds(repoRoot), generation);
+    const runtimeSource = runtimePackageSource(repoRoot);
+    const find = (scope) => {
+        if (scope === COMPANY_SCOPE) {
+            return { functions: company.functions, events: {}, runtimeVersion: runtimePackageVersion(), runtimeSource };
+        }
+        const loaded = sequences.get(scope);
+        return loaded
+            ? {
+                functions: loaded.functions,
+                events: loaded.events,
+                runtimeVersion: loaded.build.engineVersion,
+                runtimeSource: loaded.build.runtimeSource,
+            }
+            : undefined;
+    };
+    const url = overlayWebSocketUrl(backendUrl);
+    const rpcUrl = overlayRpcUrl(backendUrl);
     let socket = null;
-    const names = [...sequences.keys()];
-    console.log('Local overlay');
-    logField('company', companyId);
-    logField('sequences', names.join(', '));
+    const firstBuild = sequences.values().next().value?.build;
+    logger.info('Local overlay');
+    logField('user', authorization.user.email);
+    logField('company', authorization.companyId);
+    logField('environment', environment);
+    logField('sequences', [...sequences.keys()].join(', '));
+    if (firstBuild) {
+        logField('runtime', formatRuntimeVersion(firstBuild.engineVersion, firstBuild.runtimeSource));
+    }
     logField('backend', backendUrl);
     logField('websocket', url);
     let timer;
-    let pending = { all: false, ids: new Set() };
+    const queue = new ReloadQueue();
     let flushing = false;
     const flush = () => {
         if (flushing)
@@ -263,54 +554,51 @@ export async function runServe(repoRoot, options = {}) {
         flushing = true;
         void (async () => {
             try {
-                while (pending.all || pending.ids.size > 0) {
-                    const job = pending;
-                    pending = { all: false, ids: new Set() };
+                while (queue.hasChanges()) {
+                    const job = queue.take();
                     generation += 1;
-                    const ids = job.all ? sequenceIds : [...job.ids];
-                    const next = await loadSequences(repoRoot, ids, generation);
-                    if (job.all)
-                        sequences.clear();
-                    for (const [id, loaded] of next)
-                        sequences.set(id, loaded);
+                    // Swapped in only whole: a failed reload leaves the code that runs (and is pushed) as it was.
+                    let next;
+                    try {
+                        next = await reloadServeState(repoRoot, { company, sequences }, job, generation);
+                    }
+                    catch (error) {
+                        // Kept for the next change: fixing one sequence then also reloads what this one covered.
+                        queue.fail(job);
+                        logger.error('reload failed', error);
+                        continue;
+                    }
+                    company = next.company;
+                    sequences = next.sequences;
                     if (socket && socket.readyState === WebSocket.OPEN) {
-                        pushOverlays(socket, sequences);
-                        console.log(`reloaded sequences ${ids.join(', ')}`);
+                        pushOverlay(socket, company, sequences, generation);
+                        logger.info('reloaded sequences', job.all ? 'all' : [...job.ids]);
                     }
                 }
             }
             catch (error) {
-                console.error('reload failed:', error instanceof Error ? error.message : error);
+                logger.error('reload failed', error);
             }
             finally {
                 flushing = false;
-                if (pending.all || pending.ids.size > 0)
+                if (queue.hasChanges())
                     flush();
             }
         })();
     };
     chokidar
-        .watch([path.join(repoRoot, 'schema'), path.join(repoRoot, 'schema.ts'), path.join(repoRoot, 'sequences')], {
+        .watch(repoRoot, {
         ignoreInitial: true,
-        ignored: (p) => p.includes(`${path.sep}__gen${path.sep}`) || p.includes(`${path.sep}build${path.sep}`),
+        ignored: (p) => isIgnoredServePath(repoRoot, p),
     })
         .on('all', (event, file) => {
         if (!file)
             return;
-        if (file.includes(`${path.sep}__gen${path.sep}`))
-            return;
-        if (file.includes(`${path.sep}build${path.sep}`))
-            return;
-        const rel = path.relative(repoRoot, file);
-        const schemaHit = isSchemaPath(repoRoot, file);
-        const sequenceId = sequenceIdFromPath(repoRoot, file);
-        if (!schemaHit && !sequenceId)
+        const scope = reloadScopeForPath(repoRoot, file);
+        if (!scope)
             return;
-        console.log(`changed ${rel}`);
-        if (schemaHit)
-            pending.all = true;
-        else if (sequenceId)
-            pending.ids.add(sequenceId);
+        logger.info('changed', path.relative(repoRoot, file));
+        queue.add(scope);
         clearTimeout(timer);
         timer = setTimeout(flush, 100);
     });
@@ -321,26 +609,35 @@ export async function runServe(repoRoot, options = {}) {
         try {
             await waitOpen(ws);
             const authOk = waitAuthOk(ws);
-            send(ws, {
-                type: 'auth',
-                apiKey,
-                companyId,
-                names: [...sequences.keys()],
-            });
+            send(ws, { type: 'auth', token: authorization.token, environment });
             await authOk;
-            attachExecuteHandler(ws, sequences);
-            pushOverlays(ws, sequences);
+            attachExecuteHandler(ws, find, rpcUrl);
+            attachNoticeHandler(ws);
+            pushOverlay(ws, company, sequences, generation);
             delayMs = 500;
-            console.log(`connected  overlay ${url}`);
+            logger.info('connected', { url });
             const end = await waitSessionEnd(ws);
             if (end === 'replaced')
                 throw new OverlayReplacedError();
-            console.log('disconnected  retrying');
+            logger.warn('disconnected; retrying', { detail: end.closed });
         }
         catch (error) {
             if (error instanceof OverlayReplacedError)
                 throw error;
-            console.error('connection failed:', error instanceof Error ? error.message : error);
+            if (error instanceof OverlayRequestError)
+                throw error;
+            if (error instanceof ServeAuthorizationRejectedError) {
+                // Mid-session the identity is fixed: stop rather than log in again, and drop the cached
+                // token so the user's next `serve` starts with a fresh login.
+                await forgetServeAuthorization(backendUrl, authorization);
+                throw new Error(`Serve authorization was rejected (${error.message}). Run serve again to log in.`);
+            }
+            if (error instanceof OverlayUnavailableError) {
+                logger.warn('serve is temporarily unavailable; retrying', { error: error.message });
+            }
+            else {
+                logger.error('connection failed', error);
+            }
             if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
                 ws.close();
             }