@wjarka/cezarion 0.15.1 → 0.16.0

package/dist/preview/host.js

@@ -0,0 +1,681 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { connectCdp } from './cdp.js';
+import { ChromiumError, downloadChromium, downloadTarget, installCommand, launchChromium, resolveChromium } from './chromium.js';
+import { DevServer, probePort } from './dev-server.js';
+import { previewStopResult } from './registration.js';
+import { PreviewSession } from './session.js';
+import { normalizePreviewUrl } from './url.js';
+/**
+ * The workspace-wide preview host (#781, spec 2026-10-02-live-preview-v1): one per server process,
+ * because ports are host-global. Keyed by run id, it owns every cezar-started dev server and every
+ * task's Chromium, and every exit in the spec's lifecycle table: idle timers, release on worktree
+ * removal or run deletion, and shutdown. It starts commands only on owner approval or agent reuse of that unchanged approval.
+ */
+export const PREVIEW_SERVER_IDLE_MS = 15 * 60_000;
+export const PREVIEW_BROWSER_IDLE_MS = 2 * 60_000;
+const PROFILE_RELEASE_WAIT_MS = 5_000;
+const PROGRESS_EVERY_MS = 250;
+const STDERR_TAIL_CHARS = 4096;
+/** No Chromium anywhere `resolveChromium` looks: the pane offers the download or the OS command. */
+export class ChromiumMissingError extends Error {
+}
+const live = (server) => server !== undefined && server !== 'adopted' && server.state !== 'exited' && server.state !== 'stopped';
+const owned = (server) => server !== undefined && server !== 'adopted';
+const serverUrl = (server) => `http://localhost:${server.port}${server.path ?? '/'}`;
+function sameOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+const targetsSchema = z.array(z.object({ type: z.string(), webSocketDebuggerUrl: z.string().optional() }).passthrough());
+/** A closed browser's exit, bounded: a profile is deleted only once Chromium let go of it. */
+async function waitForExit(browser) {
+    let timer;
+    await Promise.race([browser.exited, new Promise(resolve => (timer = setTimeout(resolve, PROFILE_RELEASE_WAIT_MS)))]);
+    clearTimeout(timer);
+}
+/** resolve → launch → the page target's CDP socket. */
+async function launchBrowser(profileDir, env) {
+    const bin = resolveChromium(undefined, env);
+    if (!bin)
+        throw new ChromiumMissingError('No Chromium found');
+    const { proc, port } = await launchChromium(bin, profileDir, env);
+    let tail = '';
+    proc.stderr?.on('data', (chunk) => {
+        tail = (tail + chunk.toString('utf8')).slice(-STDERR_TAIL_CHARS);
+    });
+    const exited = new Promise(resolve => proc.once('exit', (_code, signal) => resolve({ ...(signal ? { signal } : {}), stderrTail: tail })));
+    try {
+        const targets = targetsSchema.parse(await (await fetch(`http://127.0.0.1:${port}/json/list`)).json());
+        const page = targets.find(target => target.type === 'page' && target.webSocketDebuggerUrl);
+        if (!page?.webSocketDebuggerUrl)
+            throw new ChromiumError('exited', tail, 'Chromium opened no page');
+        const cdp = await connectCdp(page.webSocketDebuggerUrl);
+        return { cdp, exited, close: () => { cdp.close(); proc.kill(); } };
+    }
+    catch (error) {
+        proc.kill('SIGKILL');
+        throw error;
+    }
+}
+function readOsRelease() {
+    try {
+        return readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export class PreviewHost {
+    stopping = new Map();
+    entries = new Map();
+    deps;
+    /** Chromium lands in one shared cache, so there is one download for the whole host. */
+    download;
+    constructor(deps = {}) {
+        const env = deps.env ?? process.env;
+        this.deps = {
+            probe: deps.probe ?? probePort,
+            createServer: deps.createServer ?? (opts => new DevServer(opts)),
+            launchBrowser: deps.launchBrowser ?? (profileDir => launchBrowser(profileDir, env)),
+            download: deps.download ?? (opts => downloadChromium(opts)),
+            osRelease: deps.osRelease ?? readOsRelease,
+            env,
+            platform: deps.platform ?? process.platform,
+            arch: deps.arch ?? process.arch,
+        };
+    }
+    /**
+     * A pane asks for a server or a URL. A registered port is probed again now: answering is
+     * adopted and streamed, silent asks for approval. Nothing here spawns a command.
+     */
+    async open(ctx, viewer, target) {
+        const entry = this.entryFor(ctx);
+        if (entry.released)
+            return;
+        this.claim(entry, viewer);
+        // Whatever this open shows, a show still waiting on Chromium for an older target is stale.
+        entry.targetGen += 1;
+        if ('url' in target) {
+            let url;
+            try {
+                url = normalizePreviewUrl(target.url);
+            }
+            catch {
+                return;
+            }
+            entry.port = undefined;
+            return this.show(entry, url, false);
+        }
+        const server = this.registration(entry, target.port);
+        if (!server) {
+            entry.port = undefined;
+            return this.show(entry, `http://localhost:${target.port}/`, false);
+        }
+        entry.port = server.port;
+        const current = entry.servers.get(server.port);
+        // A terminal state can precede process-group teardown. Keep its owned identity until stop settles.
+        if (live(current) || (owned(current) && this.stopping.has(current)))
+            return this.report(entry, server.port, current);
+        // Another task's server would answer the probe: streaming it here would show that task's app.
+        if (this.heldByOther(entry, server))
+            return;
+        const answering = await this.deps.probe(server.port).catch(() => false);
+        if (this.entries.get(ctx.runId) !== entry || entry.viewer !== viewer || entry.port !== server.port || entry.servers.get(server.port) !== current)
+            return;
+        if (owned(current) && this.stopping.has(current))
+            return this.report(entry, server.port, current);
+        if (answering) {
+            entry.servers.set(server.port, 'adopted');
+            return this.showServer(entry, server, true, true);
+        }
+        if (current === 'adopted')
+            entry.servers.delete(server.port);
+        // A server cezar ran and lost says so, with its log; Start again is the same approval.
+        if (owned(current))
+            return this.report(entry, server.port, current);
+        this.tell(entry, { t: 'state', stage: 'needs-approval', server, wasRunning: current === 'adopted' || server.answeredAtRegistration });
+    }
+    /** The owner's approval, also reused by stopPreview after checking the saved approval. */
+    async run(runId, port) {
+        const entry = this.entries.get(runId);
+        const server = entry && this.registration(entry, port);
+        if (!entry || entry.released || !server || live(entry.servers.get(port)))
+            return;
+        const previous = entry.servers.get(port);
+        if (owned(previous) && this.stopping.has(previous))
+            return;
+        if (this.heldByOther(entry, server))
+            return;
+        const dev = this.deps.createServer({ server, worktreePath: entry.ctx.worktreePath, dir: this.runDir(entry.ctx) });
+        entry.servers.set(port, dev);
+        entry.approvals.set(port, { ...server });
+        entry.startedAt.set(port, new Date().toISOString());
+        entry.port = port;
+        dev.on('state', (state) => this.onServerState(entry, port, dev, state));
+        // Attempts reach the pane only; the event log records transitions.
+        dev.on('attempt', () => {
+            if (entry.servers.get(port) === dev && dev.state === 'starting')
+                this.report(entry, port, dev);
+        });
+        // A DevServer is born `starting` without emitting it, so the host records that transition.
+        this.recordState(entry, port, 'starting', dev);
+        this.report(entry, port, dev);
+        dev.start();
+        this.armServerIdle(entry);
+    }
+    /**
+     * The agent re-registered `port` with a different command, cwd or path. A server cezar runs
+     * from the old registration stops, an adoption is forgotten, and a pane on that port is asked
+     * to approve the new command: nothing runs it until the owner does.
+     */
+    async replaced(runId, port) {
+        const entry = this.entries.get(runId);
+        if (!entry)
+            return;
+        const current = entry.servers.get(port);
+        entry.approvals.delete(port);
+        // Keep the old process reachable until teardown finishes: release must await it too.
+        if (owned(current))
+            await this.stopServer(current, 'release');
+        if (entry.servers.get(port) === current)
+            entry.servers.delete(port);
+        const server = this.registration(entry, port);
+        if (server && entry.viewer && entry.port === port) {
+            this.tell(entry, { t: 'state', stage: 'needs-approval', server, wasRunning: false });
+        }
+    }
+    /** Stops a cezar-owned server. An adopted one is not cezar's to stop: refused with `false`. */
+    async stop(runId, port, reason) {
+        const dev = this.entries.get(runId)?.servers.get(port);
+        if (!live(dev))
+            return false;
+        await this.stopServer(dev, reason);
+        return true;
+    }
+    /** Reuse only the approval attached to this exact owned process, including after a crash. */
+    async stopPreview(runId, request, signal) {
+        const { port, restart } = request;
+        const owner = this.portOwner(port);
+        if (owner && owner.runId !== runId)
+            return previewStopResult('port_held');
+        const entry = this.entries.get(runId);
+        const server = entry && this.registration(entry, port);
+        if (signal?.aborted || entry?.released)
+            return previewStopResult('unavailable');
+        if (!entry)
+            return previewStopResult('approval_required');
+        if (!server)
+            return previewStopResult('not_registered');
+        const dev = entry.servers.get(port);
+        if (dev === 'adopted')
+            return previewStopResult('adopted');
+        const approval = entry.approvals.get(port);
+        const approved = () => {
+            const current = this.registration(entry, port);
+            return !!approval && entry.approvals.get(port) === approval && !!current
+                && current.command === approval.command && current.cwd === approval.cwd && current.path === approval.path;
+        };
+        if (!owned(dev))
+            return previewStopResult('approval_required');
+        await this.stopServer(dev, 'user');
+        if (signal?.aborted || entry.released || this.entries.get(runId) !== entry)
+            return previewStopResult('unavailable');
+        if (!restart)
+            return previewStopResult('stopped');
+        if (!approved())
+            return previewStopResult('approval_required');
+        // Another process can take the port after stop/crash. Never adopt it or spawn over it.
+        const answering = await this.deps.probe(port);
+        if (signal?.aborted || entry.released || this.entries.get(runId) !== entry)
+            return previewStopResult('unavailable');
+        if (!approved())
+            return previewStopResult('approval_required');
+        if (entry.servers.get(port) !== dev)
+            return previewStopResult('unavailable');
+        const holder = this.portOwner(port);
+        if (holder && holder.runId !== runId)
+            return previewStopResult('port_held');
+        if (answering)
+            return previewStopResult('port_in_use');
+        await this.run(runId, port);
+        return previewStopResult('restarted');
+    }
+    stopServer(dev, reason) {
+        const pending = this.stopping.get(dev);
+        if (pending)
+            return pending;
+        const stop = dev.stop(reason).finally(() => { this.stopping.delete(dev); });
+        this.stopping.set(dev, stop);
+        return stop;
+    }
+    keepWaiting(runId, port) {
+        const dev = this.entries.get(runId)?.servers.get(port);
+        if (live(dev))
+            dev.keepWaiting();
+    }
+    /** The socket closed. The last viewer leaving starts both idle timers. */
+    detach(runId, viewer) {
+        const entry = this.entries.get(runId);
+        if (!entry || entry.viewer !== viewer)
+            return;
+        entry.viewer = undefined;
+        entry.session?.detach(viewer);
+        this.clearIdle(entry);
+        entry.idleTimers.browser = setTimeout(() => this.closeBrowser(entry), PREVIEW_BROWSER_IDLE_MS);
+        this.armServerIdle(entry);
+    }
+    /** Agent restarts without a viewer need a bound even after the previous idle timer fired. */
+    armServerIdle(entry) {
+        if (entry.viewer || entry.released || entry.idleTimers.server)
+            return;
+        entry.idleTimers.server = setTimeout(() => {
+            entry.idleTimers.server = undefined;
+            for (const server of entry.servers.values())
+                if (live(server))
+                    void this.stopServer(server, 'idle');
+        }, PREVIEW_SERVER_IDLE_MS);
+    }
+    /** Every message a connected pane sends, already validated against the contract. */
+    async handle(ctx, viewer, msg) {
+        if (msg.t === 'open')
+            return this.open(ctx, viewer, msg.target);
+        const entry = this.entries.get(ctx.runId);
+        if (!entry || entry.viewer !== viewer)
+            return;
+        switch (msg.t) {
+            case 'run': return this.run(ctx.runId, msg.port);
+            case 'stop':
+                await this.stop(ctx.runId, msg.port, 'user');
+                return;
+            case 'keepWaiting': return this.keepWaiting(ctx.runId, msg.port);
+            case 'retryBrowser': return this.retryBrowser(entry);
+            case 'download': return this.startDownload(entry);
+            case 'cancelDownload':
+                this.download?.controller.abort();
+                return;
+            case 'ping':
+                viewer.send({ t: 'pong', ts: msg.ts });
+                return;
+            default:
+                // A refused URL or a CDP call on a page that just went away changes nothing for the pane.
+                await entry.session?.handle(msg).catch(() => { });
+        }
+    }
+    /**
+     * The run's worktree is going, or the run itself: stop its servers, close its browser, tell the
+     * pane. The profile survives unless `deleteProfile` (run deletion), which removes the whole
+     * `<dataDir>/preview/<runId>/`. `dataDir` covers a run this process never opened.
+     */
+    async release(runId, opts = {}) {
+        const entry = this.entries.get(runId);
+        if (entry)
+            await this.releaseEntry(entry, true, opts.deleteProfile === true);
+        const dataDir = opts.dataDir ?? entry?.ctx.dataDir;
+        if (opts.deleteProfile && dataDir) {
+            try {
+                // Chromium may still be flushing the profile as it exits.
+                rmSync(join(dataDir, 'preview', runId), { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+            }
+            catch { /* a profile we cannot delete is left behind, never a failed run deletion */ }
+        }
+    }
+    /** The task whose cezar-owned dev server holds `port`. Adopted ports belong to nobody. */
+    portOwner(port) {
+        for (const entry of this.entries.values()) {
+            const server = entry.servers.get(port);
+            if (live(server) || (owned(server) && this.stopping.has(server)))
+                return { runId: entry.ctx.runId, title: entry.ctx.title };
+        }
+        return undefined;
+    }
+    /** Whether this host runs the dev server `<runId>/<port>.pid.json` records: the sweep spares it. */
+    ownsServer(runId, port) {
+        return live(this.entries.get(runId)?.servers.get(port));
+    }
+    /** Whether this host runs the run's Chromium (`<runId>/chromium.pid.json`): the sweep spares it. */
+    ownsBrowser(runId) {
+        const entry = this.entries.get(runId);
+        return entry !== undefined && (entry.browser !== undefined || entry.launching !== undefined);
+    }
+    probe(port) {
+        return this.deps.probe(port);
+    }
+    /** cezar shuts down: every run is released and every pane closed. */
+    async close() {
+        this.download?.controller.abort();
+        await Promise.all([...this.entries.values()].map(entry => this.releaseEntry(entry, false, false)));
+    }
+    entryFor(ctx) {
+        const existing = this.entries.get(ctx.runId);
+        if (existing) {
+            existing.ctx = ctx;
+            return existing;
+        }
+        const entry = { ctx, servers: new Map(), startedAt: new Map(), approvals: new Map(), browserGen: 0, targetGen: 0, adopted: false, idleTimers: {}, released: false };
+        this.entries.set(ctx.runId, entry);
+        return entry;
+    }
+    /** One viewer per run: a second one takes over, and the first is told by whom. */
+    claim(entry, viewer) {
+        this.clearIdle(entry);
+        const previous = entry.viewer;
+        if (previous === viewer)
+            return;
+        if (previous) {
+            entry.session?.detach(previous);
+            previous.send({ t: 'replaced', by: viewer.userAgent });
+            previous.close(4001, 'replaced');
+        }
+        entry.viewer = viewer;
+        entry.session?.attach(viewer);
+    }
+    /** Tells the pane `port-held` when another task's cezar-owned server holds `server.port`. */
+    heldByOther(entry, server) {
+        const owner = this.portOwner(server.port);
+        if (!owner || owner.runId === entry.ctx.runId)
+            return false;
+        if (entry.servers.get(server.port) === 'adopted')
+            entry.servers.delete(server.port);
+        this.tell(entry, { t: 'state', stage: 'port-held', server, ownerTitle: owner.title });
+        return true;
+    }
+    registration(entry, port) {
+        return entry.ctx.store.getRun(entry.ctx.runId)?.previewServers?.find(server => server.port === port);
+    }
+    runDir(ctx) {
+        return join(ctx.dataDir, 'preview', ctx.runId);
+    }
+    onServerState(entry, port, dev, state) {
+        if (entry.servers.get(port) !== dev)
+            return;
+        this.recordState(entry, port, state, dev);
+        if (entry.port !== port || entry.released)
+            return;
+        const server = this.registration(entry, port);
+        // Chromium starts for a pane that is open, never for nobody.
+        if (state === 'up') {
+            // A (re)started server: load the page again, at the one the owner was last on (5.9).
+            if (server && entry.viewer)
+                void this.showServer(entry, server, false, false);
+        }
+        else {
+            this.report(entry, port, dev);
+        }
+    }
+    /** `preview.server-state`, on transitions only. A run already deleted takes no events. */
+    recordState(entry, port, state, dev) {
+        const { runId, store } = entry.ctx;
+        if (!store.getRun(runId))
+            return;
+        const reason = dev.stopReason;
+        store.appendEvent(runId, {
+            type: 'preview.server-state',
+            port,
+            state,
+            ...(state === 'exited' && dev.exitCode !== undefined ? { exitCode: dev.exitCode } : {}),
+            ...(state === 'stopped' && (reason === 'user' || reason === 'idle') ? { reason } : {}),
+        });
+    }
+    /** The pane's view of a cezar-owned server that is not streaming. */
+    report(entry, port, dev) {
+        const server = this.registration(entry, port);
+        if (!server || entry.port !== port)
+            return;
+        const logTail = () => dev.logTail().join('\n');
+        switch (dev.state) {
+            case 'starting':
+                return this.tell(entry, { t: 'state', stage: 'server-starting', server, attempt: dev.attempts, startedAt: entry.startedAt.get(port) ?? new Date().toISOString(), logTail: dev.logTail() });
+            case 'stalled':
+                return this.tell(entry, { t: 'state', stage: 'server-stalled', server, logTail: logTail() });
+            case 'exited':
+                return this.tell(entry, { t: 'state', stage: 'server-exited', server, exitCode: dev.exitCode ?? null, logTail: logTail() });
+            case 'stopped':
+                return this.tell(entry, {
+                    t: 'state',
+                    stage: 'server-stopped',
+                    server,
+                    reason: dev.stopReason === 'idle' ? 'idle' : 'user',
+                    lastUrl: entry.session?.url ?? entry.lastUrl ?? serverUrl(server),
+                });
+            case 'up':
+                if (entry.viewer)
+                    void this.showServer(entry, server, false, true);
+                return;
+        }
+    }
+    /** Where a server's page reopens: the page the owner was last on when it is this server's, else the registered root. */
+    serverPage(entry, server) {
+        const root = serverUrl(server);
+        const last = entry.session?.url ?? entry.lastUrl;
+        return last && sameOrigin(last, root) ? last : root;
+    }
+    /**
+     * Streams a registered server. With `resume`, a live page already on that server is kept as it
+     * is: a reconnect, a takeover or a reopen inside the browser idle window must not throw the owner
+     * back to the root and lose their form state. Re-attaching restarts the screencast, so the first
+     * frame still announces `streaming`.
+     */
+    async showServer(entry, server, adopted, resume) {
+        const url = this.serverPage(entry, server);
+        const { session, viewer } = entry;
+        if (resume && session?.url && viewer && !entry.browserFailure && sameOrigin(session.url, url)) {
+            entry.adopted = adopted;
+            entry.lastUrl = session.url;
+            session.attach(viewer);
+            return;
+        }
+        return this.show(entry, url, adopted);
+    }
+    /** Browser, then page, then the first frame (which the session announces as `streaming`). */
+    async show(entry, url, adopted) {
+        // While Chromium is down, the URL it last showed is the one Retry reopens.
+        if (entry.browserFailure)
+            return this.tell(entry, entry.browserFailure);
+        entry.lastUrl = url;
+        entry.adopted = adopted;
+        const generation = ++entry.targetGen;
+        const session = await this.ensureSession(entry);
+        if (!session || entry.targetGen !== generation)
+            return;
+        this.tell(entry, { t: 'state', stage: 'loading', step: 'page' });
+        await session.navigate(url).catch(() => { });
+        this.tell(entry, { t: 'state', stage: 'loading', step: 'frame' });
+    }
+    ensureSession(entry) {
+        if (entry.session)
+            return Promise.resolve(entry.session);
+        if (entry.browserFailure) {
+            this.tell(entry, entry.browserFailure);
+            return Promise.resolve(undefined);
+        }
+        entry.launching ??= this.launch(entry).finally(() => {
+            entry.launching = undefined;
+        });
+        return entry.launching;
+    }
+    async launch(entry) {
+        const generation = entry.browserGen;
+        this.tell(entry, { t: 'state', stage: 'loading', step: 'browser' });
+        let browser;
+        try {
+            browser = await this.deps.launchBrowser(join(this.runDir(entry.ctx), 'profile'));
+        }
+        catch (error) {
+            this.launchFailed(entry, error);
+            return undefined;
+        }
+        let session;
+        try {
+            session = await PreviewSession.create(browser.cdp, {
+                onFirstFrame: viewer => viewer.send({ t: 'state', stage: 'streaming', adopted: entry.adopted }),
+            });
+        }
+        catch (error) {
+            browser.close();
+            this.launchFailed(entry, error);
+            return undefined;
+        }
+        if (entry.released || entry.browserGen !== generation) {
+            session.close();
+            browser.close();
+            // A release waiting on this launch deletes the profile next: the browser must be gone first.
+            if (entry.released)
+                await waitForExit(browser);
+            return undefined;
+        }
+        entry.browser = browser;
+        entry.session = session;
+        if (entry.viewer)
+            session.attach(entry.viewer);
+        void browser.exited.then(exit => this.browserExited(entry, browser, exit));
+        return session;
+    }
+    launchFailed(entry, error) {
+        // `not-installed`: the binary vanished between resolution and spawn. Same pane as none at all.
+        if (error instanceof ChromiumMissingError || (error instanceof ChromiumError && error.kind === 'not-installed')) {
+            return this.tell(entry, this.missingState());
+        }
+        if (error instanceof ChromiumError && error.kind === 'sandbox') {
+            entry.browserFailure = { t: 'state', stage: 'sandbox-failed', stderrTail: error.stderrTail };
+            return this.tell(entry, entry.browserFailure);
+        }
+        // A timeout or an early exit says why first: Chromium's own stderr is often unrelated noise.
+        const stderrTail = error instanceof ChromiumError
+            ? [error.message, error.stderrTail].filter(Boolean).join('\n')
+            : error instanceof Error ? error.message : String(error);
+        entry.browserFailure = { t: 'state', stage: 'browser-exited', stderrTail, serverUp: this.serverUp(entry) };
+        this.tell(entry, entry.browserFailure);
+    }
+    /** Chromium died under us: say so with the server's state, and wait for the owner's Retry. */
+    browserExited(entry, browser, exit) {
+        if (entry.browser !== browser)
+            return;
+        entry.lastUrl = entry.session?.url ?? entry.lastUrl;
+        entry.session = entry.browser = undefined;
+        entry.browserFailure = {
+            t: 'state',
+            stage: 'browser-exited',
+            ...(exit.signal ? { signal: exit.signal } : {}),
+            stderrTail: exit.stderrTail,
+            serverUp: this.serverUp(entry),
+        };
+        this.tell(entry, entry.browserFailure);
+    }
+    async retryBrowser(entry) {
+        entry.browserFailure = undefined;
+        if (entry.lastUrl)
+            return this.show(entry, entry.lastUrl, entry.adopted);
+        await this.ensureSession(entry);
+    }
+    serverUp(entry) {
+        const server = entry.port === undefined ? undefined : entry.servers.get(entry.port);
+        return server === 'adopted' || server?.state === 'up';
+    }
+    missingState() {
+        return {
+            t: 'state',
+            stage: 'chromium-missing',
+            installCommand: installCommand(this.deps.platform, this.deps.osRelease()),
+            canDownload: downloadTarget(this.deps.platform, this.deps.arch) !== undefined,
+        };
+    }
+    async startDownload(entry) {
+        this.tell(entry, { t: 'state', stage: 'downloading', received: 0, total: 0 });
+        const download = this.download ?? this.beginDownload(entry);
+        download.watchers.add(entry);
+        try {
+            await download.promise;
+        }
+        catch (error) {
+            if (entry.released)
+                return;
+            this.tell(entry, download.controller.signal.aborted
+                ? this.missingState()
+                : { t: 'state', stage: 'download-failed', error: error instanceof Error ? error.message : String(error), installCommand: installCommand(this.deps.platform, this.deps.osRelease()) });
+            return;
+        }
+        if (entry.released)
+            return;
+        if (entry.lastUrl)
+            await this.show(entry, entry.lastUrl, entry.adopted);
+        else
+            await this.ensureSession(entry);
+    }
+    /** `first` watches before the download starts, so no progress report is lost. */
+    beginDownload(first) {
+        const controller = new AbortController();
+        const watchers = new Set([first]);
+        let last = 0;
+        const download = { controller, watchers, promise: Promise.resolve('') };
+        this.download = download;
+        download.promise = this.deps.download({
+            signal: controller.signal,
+            onProgress: (received, total) => {
+                const now = Date.now();
+                if (now - last < PROGRESS_EVERY_MS && received < total)
+                    return;
+                last = now;
+                for (const watcher of watchers)
+                    this.tell(watcher, { t: 'downloadProgress', received, total });
+            },
+        });
+        void download.promise.catch(() => { }).finally(() => {
+            if (this.download === download)
+                this.download = undefined;
+        });
+        return download;
+    }
+    closeBrowser(entry) {
+        const { browser, session } = entry;
+        entry.browserGen += 1;
+        // The page the owner was on outlives the browser: 5.9 shows it, and Start again reopens it.
+        entry.lastUrl = session?.url ?? entry.lastUrl;
+        entry.browser = entry.session = undefined;
+        session?.close();
+        browser?.close();
+        return browser;
+    }
+    clearIdle(entry) {
+        clearTimeout(entry.idleTimers.server);
+        clearTimeout(entry.idleTimers.browser);
+        entry.idleTimers = {};
+    }
+    async releaseEntry(entry, notify, awaitBrowserExit) {
+        entry.released = true;
+        // Retain ownership while stopping so no run can reuse this port during teardown.
+        this.clearIdle(entry);
+        this.download?.watchers.delete(entry);
+        // A launch in flight has no browser on the entry yet; it sees `released` and closes its own.
+        const launching = entry.launching;
+        const browser = this.closeBrowser(entry);
+        const stops = [...entry.servers.values()].filter(owned).map(server => this.stopServer(server, 'release'));
+        await Promise.all(stops);
+        if (this.entries.get(entry.ctx.runId) === entry)
+            this.entries.delete(entry.ctx.runId);
+        if (awaitBrowserExit) {
+            if (browser)
+                await waitForExit(browser);
+            if (launching)
+                await launching.catch(() => undefined);
+        }
+        const viewer = entry.viewer;
+        entry.viewer = undefined;
+        if (!viewer)
+            return;
+        if (notify)
+            viewer.send({ t: 'state', stage: 'worktree-removed' });
+        else
+            viewer.close(1001, 'cezar is shutting down');
+    }
+    tell(entry, msg) {
+        if (!entry.released)
+            entry.viewer?.send(msg);
+    }
+}
+//# sourceMappingURL=host.js.map