@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/preview/dev-server.d.ts

@@ -0,0 +1,68 @@
+import { EventEmitter } from 'node:events';
+import type { PreviewServer } from '../contract/index.js';
+/**
+ * Supervisor for one cezar-owned dev server (#781, spec 2026-10-02-live-preview-v1): spawn the
+ * registered command in its own process group, TCP-probe until the port answers, and kill the
+ * whole group on stop so a command that forks (`npm` -> `node` -> `vite`) frees its port.
+ */
+export declare const PREVIEW_PORT_WAIT_MS: number;
+export declare const PREVIEW_PROBE_MS = 2000;
+export type DevServerState = 'starting' | 'up' | 'stalled' | 'exited' | 'stopped';
+export type DevServerStopReason = 'user' | 'idle' | 'release';
+/** Does anything answer on `port`? Vite resolves `localhost` to `::1` on some hosts, so both loopbacks count. */
+export declare function probePort(port: number): Promise<boolean>;
+/** Keep the last 1 MiB once the log passes 5 MiB. The child holds the file open in append mode, so it keeps writing at the end. */
+export declare function trimLog(path: string): void;
+export declare class DevServer extends EventEmitter {
+    state: DevServerState;
+    exitCode?: number;
+    attempts: number;
+    stopReason?: DevServerStopReason;
+    private readonly server;
+    private readonly worktreePath;
+    private readonly dir;
+    private readonly probeMs;
+    private readonly waitMs;
+    private child?;
+    private childExited?;
+    private probeTimer?;
+    private waitTimer?;
+    private logTimer?;
+    private probing;
+    private stopping?;
+    constructor(opts: {
+        server: PreviewServer;
+        worktreePath: string;
+        dir: string;
+        probeMs?: number;
+        waitMs?: number;
+    });
+    private get pidPath();
+    private get logPath();
+    start(): void;
+    /** The owner pressed "keep waiting" on a stalled server: probe again for another full window. */
+    keepWaiting(): void;
+    stop(reason: DevServerStopReason): Promise<void>;
+    logTail(lines?: number): string[];
+    private terminate;
+    private beginWaiting;
+    private endWaiting;
+    private probeOnce;
+    /** A terminal state: the process is gone, so timers and (unless its group is still being reaped) the pid record go with it. */
+    private finish;
+    /** Only our own record: a Start again on the same port may already have written its successor's. */
+    private removeRecord;
+    private setState;
+}
+/**
+ * Boot sweep: a crashed cezar leaves pid records behind, `<port>.pid.json` for each dev server and
+ * `chromium.pid.json` for the task's browser. Kill only when the recorded pid is still the process
+ * we started (an exactly matching start token), so a reused pid is never hit; a missing or
+ * unreadable token means skip. A dev server's whole group goes; Chromium shares cezar's group, so
+ * only its pid is signalled.
+ * The record goes either way, except one `keep` claims: a server or browser the live host still runs.
+ * Returns how many processes were killed.
+ */
+export declare function sweepPreviewLeftovers(dataDir: string, opts?: {
+    keep?: ((runId: string, what: number | 'browser') => boolean) | undefined;
+}): Promise<number>;

package/dist/preview/dev-server.js

@@ -0,0 +1,318 @@
+import { productName } from '../home/display.js';
+import { spawn, spawnSync } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, truncateSync, appendFileSync, writeFileSync, fstatSync } from 'node:fs';
+import { Socket } from 'node:net';
+import { join, resolve } from 'node:path';
+import { buildCommandEnv } from '../core/agent-env.js';
+import { processStartToken, recordedProcessLive } from '../delegation/process-liveness.js';
+import { spawnDetached, stopGroup } from '../detached-process.js';
+import { CHROMIUM_PID_FILE } from './chromium.js';
+/**
+ * Supervisor for one cezar-owned dev server (#781, spec 2026-10-02-live-preview-v1): spawn the
+ * registered command in its own process group, TCP-probe until the port answers, and kill the
+ * whole group on stop so a command that forks (`npm` -> `node` -> `vite`) frees its port.
+ */
+export const PREVIEW_PORT_WAIT_MS = 2 * 60_000;
+export const PREVIEW_PROBE_MS = 2_000;
+const PROBE_CONNECT_MS = 500;
+const KILL_GRACE_MS = 5_000;
+/** How long a SIGKILLed group gets to disappear before the stop resolves anyway. */
+const KILL_SETTLE_MS = 2_000;
+const LOG_TRIM_ABOVE = 5 * 1024 * 1024;
+const LOG_KEEP = 1024 * 1024;
+const LOG_CHECK_MS = 60_000;
+const TAIL_READ = 64 * 1024;
+function connects(host, port) {
+    return new Promise(resolveConnect => {
+        const socket = new Socket();
+        const done = (up) => { socket.destroy(); resolveConnect(up); };
+        socket.setTimeout(PROBE_CONNECT_MS);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+        socket.connect(port, host);
+    });
+}
+/** Does anything answer on `port`? Vite resolves `localhost` to `::1` on some hosts, so both loopbacks count. */
+export async function probePort(port) {
+    return (await connects('127.0.0.1', port)) || (await connects('::1', port));
+}
+const sleep = (ms) => new Promise(resolveSleep => setTimeout(resolveSleep, ms));
+/** SIGTERM one process, SIGKILL it if it is still there after the grace period. */
+async function terminatePid(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return;
+    }
+    const alive = () => { try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (alive() && Date.now() < deadline)
+        await sleep(50);
+    if (alive()) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* gone meanwhile */ }
+    }
+}
+/** SIGTERM the group, SIGKILL whatever is still there after the grace period. SIGKILL is delivered,
+ *  not done: until the kernel tears the processes down they still hold their sockets, so the stop
+ *  resolves once no member runs, and "stopped" means the port is free. On Windows, the leader's tree. */
+async function terminateGroup(leader) {
+    await stopGroup(leader, { graceMs: KILL_GRACE_MS, killWaitMs: KILL_SETTLE_MS });
+}
+/** Windows, once the shell leader exited on its own: `taskkill` the tree at its pid, as cezar did
+ *  before the detached-process helper. By then the pid names no process, or one that reused it;
+ *  a Job Object per started server replaces this (hearsay-tools/cezarion#1876). */
+function endExitedLeaderTree(pid) {
+    spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, timeout: 5_000 });
+    return Promise.resolve();
+}
+/** Keep the last 1 MiB once the log passes 5 MiB. The child holds the file open in append mode, so it keeps writing at the end. */
+export function trimLog(path) {
+    try {
+        if (statSync(path).size <= LOG_TRIM_ABOVE)
+            return;
+        const fd = openSync(path, 'r');
+        const tail = Buffer.alloc(LOG_KEEP);
+        try {
+            readSync(fd, tail, 0, LOG_KEEP, fstatSync(fd).size - LOG_KEEP);
+        }
+        finally {
+            closeSync(fd);
+        }
+        truncateSync(path, 0);
+        appendFileSync(path, tail);
+    }
+    catch { /* a log we cannot trim only grows */ }
+}
+function readTail(path, lines) {
+    try {
+        const fd = openSync(path, 'r');
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, TAIL_READ);
+            const buffer = Buffer.alloc(length);
+            readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString('utf8').split('\n').filter(line => line.trim()).slice(-lines);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+}
+export class DevServer extends EventEmitter {
+    state = 'starting';
+    exitCode;
+    attempts = 0;
+    stopReason;
+    server;
+    worktreePath;
+    dir;
+    probeMs;
+    waitMs;
+    child;
+    childExited;
+    probeTimer;
+    waitTimer;
+    logTimer;
+    probing = false;
+    stopping;
+    constructor(opts) {
+        super();
+        this.server = opts.server;
+        this.worktreePath = opts.worktreePath;
+        this.dir = opts.dir;
+        this.probeMs = opts.probeMs ?? PREVIEW_PROBE_MS;
+        this.waitMs = opts.waitMs ?? PREVIEW_PORT_WAIT_MS;
+    }
+    get pidPath() { return join(this.dir, `${this.server.port}.pid.json`); }
+    get logPath() { return join(this.dir, `${this.server.port}.log`); }
+    start() {
+        if (this.child)
+            return;
+        mkdirSync(this.dir, { recursive: true });
+        // One log per start: after Start again, 5.8 must show this run's failure, not the last one's tail.
+        writeFileSync(this.logPath, '', { mode: 0o600 });
+        const logFd = openSync(this.logPath, 'a');
+        const cwd = resolve(this.worktreePath, this.server.cwd ?? '.');
+        // stdin is closed: nobody can answer a prompt from the cockpit, so one fails fast into `exited` with its log.
+        // The command is the agent's and runs outside its sandbox: it gets the curated env, never cezar's secrets (#427).
+        const env = buildCommandEnv();
+        const child = process.platform === 'win32'
+            ? spawn(this.server.command, { cwd, env, shell: true, windowsHide: true, stdio: ['ignore', logFd, logFd] })
+            : spawnDetached('/bin/sh', ['-c', this.server.command], { cwd, env, stdio: ['ignore', logFd, logFd] });
+        closeSync(logFd);
+        this.child = child;
+        this.childExited = new Promise(resolveExit => {
+            child.once('error', error => {
+                try {
+                    appendFileSync(this.logPath, `${productName('cezar')} could not start the command: ${error.message}\n`);
+                }
+                catch { /* log is best effort */ }
+                resolveExit();
+                this.finish('exited');
+            });
+            child.once('exit', (code) => {
+                resolveExit();
+                if (code !== null)
+                    this.exitCode = code;
+                const pid = child.pid;
+                if (this.stopping || pid === undefined)
+                    return this.finish(this.stopping ? 'stopped' : 'exited');
+                // A leader that dies on its own can leave a forked server holding the port. Reap the group
+                // the way a stop does (SIGKILL after the grace period, so a holder that ignores SIGTERM goes
+                // too), and keep the pid record until the group is gone: `stop()` awaits the same cleanup.
+                this.finish('exited', { keepRecord: true });
+                const cleanup = process.platform === 'win32' ? endExitedLeaderTree(pid) : terminateGroup({ pid, child });
+                this.stopping = cleanup.finally(() => this.removeRecord(pid));
+            });
+        });
+        if (child.pid !== undefined) {
+            writeFileSync(this.pidPath, JSON.stringify({ pid: child.pid, pgid: child.pid, startToken: processStartToken(child.pid) }), { mode: 0o600 });
+            this.beginWaiting();
+            this.logTimer = setInterval(() => trimLog(this.logPath), LOG_CHECK_MS);
+            this.logTimer.unref();
+        }
+    }
+    /** The owner pressed "keep waiting" on a stalled server: probe again for another full window. */
+    keepWaiting() {
+        if (this.state !== 'stalled')
+            return;
+        this.setState('starting');
+        this.beginWaiting();
+    }
+    stop(reason) {
+        if (this.stopping)
+            return this.stopping;
+        if (this.state === 'exited' || this.state === 'stopped')
+            return Promise.resolve();
+        this.stopping ??= this.terminate(reason);
+        return this.stopping;
+    }
+    logTail(lines = 4) {
+        return readTail(this.logPath, lines);
+    }
+    async terminate(reason) {
+        this.stopReason = reason;
+        const child = this.child;
+        if (child?.pid === undefined) {
+            this.finish('stopped');
+            return;
+        }
+        await terminateGroup({ pid: child.pid, child });
+        await this.childExited;
+        this.finish('stopped');
+    }
+    beginWaiting() {
+        this.endWaiting();
+        this.probeTimer = setInterval(() => { void this.probeOnce(); }, this.probeMs);
+        this.waitTimer = setTimeout(() => {
+            if (this.state !== 'starting')
+                return;
+            this.endWaiting();
+            this.setState('stalled');
+        }, this.waitMs);
+    }
+    endWaiting() {
+        clearInterval(this.probeTimer);
+        clearTimeout(this.waitTimer);
+        this.probeTimer = this.waitTimer = undefined;
+    }
+    async probeOnce() {
+        if (this.probing || this.state !== 'starting')
+            return;
+        this.probing = true;
+        this.attempts += 1;
+        this.emit('attempt', this.attempts);
+        const up = await probePort(this.server.port);
+        this.probing = false;
+        if (up && this.state === 'starting') {
+            this.endWaiting();
+            this.setState('up');
+        }
+    }
+    /** A terminal state: the process is gone, so timers and (unless its group is still being reaped) the pid record go with it. */
+    finish(state, opts = {}) {
+        if (this.state === 'exited' || this.state === 'stopped')
+            return;
+        this.endWaiting();
+        clearInterval(this.logTimer);
+        if (!opts.keepRecord && this.child?.pid !== undefined)
+            this.removeRecord(this.child.pid);
+        this.setState(state);
+    }
+    /** Only our own record: a Start again on the same port may already have written its successor's. */
+    removeRecord(pid) {
+        try {
+            if (JSON.parse(readFileSync(this.pidPath, 'utf8')).pid !== pid)
+                return;
+        }
+        catch { /* missing or unreadable: nothing of ours to keep */ }
+        rmSync(this.pidPath, { force: true });
+    }
+    setState(state) {
+        this.state = state;
+        this.emit('state', state);
+    }
+}
+/**
+ * Boot sweep: a crashed cezar leaves pid records behind, `<port>.pid.json` for each dev server and
+ * `chromium.pid.json` for the task's browser. Kill only when the recorded pid is still the process
+ * we started (an exactly matching start token), so a reused pid is never hit; a missing or
+ * unreadable token means skip. A dev server's whole group goes; Chromium shares cezar's group, so
+ * only its pid is signalled.
+ * The record goes either way, except one `keep` claims: a server or browser the live host still runs.
+ * Returns how many processes were killed.
+ */
+export async function sweepPreviewLeftovers(dataDir, opts = {}) {
+    const root = join(dataDir, 'preview');
+    if (!existsSync(root))
+        return 0;
+    const kills = [];
+    for (const run of readdirSync(root, { withFileTypes: true })) {
+        if (!run.isDirectory())
+            continue;
+        for (const file of readdirSync(join(root, run.name))) {
+            if (!file.endsWith('.pid.json'))
+                continue;
+            const what = file === CHROMIUM_PID_FILE ? 'browser' : Number(file.slice(0, -'.pid.json'.length));
+            if (opts.keep?.(run.name, what))
+                continue;
+            const path = join(root, run.name, file);
+            let record;
+            try {
+                record = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch { /* unreadable: nothing to kill */ }
+            rmSync(path, { force: true });
+            const { pid, pgid, startToken } = (record ?? {});
+            if (typeof pid !== 'number' || typeof startToken !== 'string')
+                continue;
+            // A dev server leads its own group. The token verifies the pid only, so a record naming
+            // another group is not one cezar wrote, and that group is never signalled.
+            if (what !== 'browser' && pgid !== pid)
+                continue;
+            // `recordedProcessLive` answers "alive" on any uncertainty; a kill needs an exact token match,
+            // so a record without a token, or a pid whose token cannot be read now, is skipped.
+            if (!recordedProcessLive({ pid, startToken }) || processStartToken(pid) !== startToken)
+                continue;
+            kills.push(what === 'browser' ? terminatePid(pid) : terminateGroup({ pid, start: startToken }));
+        }
+    }
+    await Promise.all(kills);
+    return kills.length;
+}
+//# sourceMappingURL=dev-server.js.map

package/dist/preview/dev-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server.js","sourceRoot":"","sources":["../../src/preview/dev-server.ts"],"names":[],"mappings":"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"}

package/dist/preview/host.d.ts

@@ -0,0 +1,215 @@
+import type { Home } from '../home/home.ts';
+import type { PreviewStopRequest, PreviewStopResult, PreviewClientMessage, PreviewQuality, PreviewServer } from '../contract/index.js';
+import type { RunStore } from '../runs/store.ts';
+import { ChromiumMissingError, type BrowserExit, type BrowserHandle } from './browser-launch.ts';
+import { AgentCdpLink, type AgentClient } from './cdp-proxy.ts';
+import { DevServer, type DevServerState } from './dev-server.ts';
+import { type PreviewHostLike } from './registration.ts';
+import { type Viewer } from './session.ts';
+/**
+ * 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 declare const PREVIEW_SERVER_IDLE_MS: number;
+export declare const PREVIEW_BROWSER_IDLE_MS: number;
+export type RunContext = {
+    runId: string;
+    title: string;
+    worktreePath: string;
+    dataDir: string;
+    store: Pick<RunStore, 'getRun' | 'appendEvent'> & Partial<Pick<RunStore, 'writeRefusal'>>;
+};
+export type PreviewTarget = {
+    port: number;
+} | {
+    url: string;
+} | {
+    agent: true;
+};
+export { ChromiumMissingError, type BrowserExit, type BrowserHandle };
+/**
+ * One agent session's right to drive its run's browser (hearsay-tools/cezarion#784). The token is
+ * the secret in `CEZ_PREVIEW_CDP_URL`; `revoke` (the session's tool capability ending) closes every
+ * socket it opened. `context` is read at each connection: undefined (no worktree) refuses it.
+ */
+export type AgentGrant = {
+    token: string;
+    revoke(): void;
+};
+/** Why an agent connection was refused, for the proxy route's close reason. */
+export type AgentRefusal = {
+    refused: string;
+};
+/** What the host uses of a `DevServer`: its state, its controls and its two events. */
+export type DevServerLike = Pick<DevServer, 'state' | 'attempts' | 'exitCode' | 'stopReason' | 'start' | 'stop' | 'keepWaiting' | 'logTail'> & {
+    on(event: 'state', listener: (state: DevServerState) => void): unknown;
+    on(event: 'attempt', listener: (attempts: number) => void): unknown;
+};
+export type PreviewHostDeps = {
+    home: Home;
+    probe?: (port: number) => Promise<boolean>;
+    createServer?: (opts: {
+        server: PreviewServer;
+        worktreePath: string;
+        dir: string;
+    }) => DevServerLike;
+    launchBrowser?: (profileDir: string) => Promise<BrowserHandle>;
+    download?: (opts: {
+        signal: AbortSignal;
+        onProgress(received: number, total: number): void;
+    }) => Promise<string>;
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    arch?: string;
+    /** /etc/os-release, for the install command. */
+    osRelease?: () => string;
+};
+export declare class PreviewHost implements PreviewHostLike {
+    private readonly stopping;
+    private readonly entries;
+    private readonly grants;
+    private readonly deps;
+    /** Chromium lands in one shared cache, so there is one download for the whole host. */
+    private download?;
+    constructor(deps: PreviewHostDeps);
+    /**
+     * 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.
+     */
+    open(ctx: RunContext, viewer: Viewer, target: PreviewTarget, options?: {
+        viewerId?: string | undefined;
+        resume?: boolean | undefined;
+        quality?: PreviewQuality | undefined;
+        dpr?: number | undefined;
+    }): Promise<void>;
+    private openUrl;
+    private openPort;
+    /** The owner's approval, also reused by stopPreview after checking the saved approval. */
+    run(runId: string, port: number): Promise<void>;
+    /**
+     * 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.
+     */
+    replaced(runId: string, port: number): Promise<void>;
+    /** Stops a cezar-owned server. An adopted one is not cezar's to stop: refused with `false`. */
+    stop(runId: string, port: number, reason: 'user' | 'idle'): Promise<boolean>;
+    /** Whether the stop was overtaken by the run's release or an aborted request. */
+    private stopAborted;
+    /** Reuse only the approval attached to this exact owned process, including after a crash. */
+    private approvalHolds;
+    /** Starts the stopped server again over its still-valid approval: the port can change hands in between, so every guard is re-checked. */
+    private restartAfterStop;
+    /** Reuse only the approval attached to this exact owned process, including after a crash. */
+    stopPreview(runId: string, request: PreviewStopRequest, signal?: AbortSignal): Promise<PreviewStopResult>;
+    private stopServer;
+    keepWaiting(runId: string, port: number): void;
+    /** The socket closed. The last viewer leaving starts both idle timers. */
+    detach(runId: string, viewer: Viewer): void;
+    /** Agent restarts without a viewer need a bound even after the previous idle timer fired. */
+    private armServerIdle;
+    /** Every message a connected pane sends, already validated against the contract. */
+    handle(ctx: RunContext, viewer: Viewer, msg: PreviewClientMessage): Promise<void>;
+    /** A new agent session's right to drive `runId`'s browser through the CDP proxy (hearsay-tools/cezarion#784): nothing starts until it connects. */
+    grantAgent(runId: string, context: () => RunContext | undefined): AgentGrant;
+    /** Whether `token` names a live grant: the proxy route refuses the upgrade before the handshake otherwise. */
+    hasAgentGrant(token: string): boolean;
+    /**
+     * An agent opened the proxy socket. Its connection is demand: the run's Chromium starts when none
+     * runs, and no idle timer runs while it stays. A browser that failed stays failed until the
+     * owner's Retry, so a page that crashes Chromium cannot loop through the agent either.
+     */
+    connectAgent(token: string, client: AgentClient): Promise<AgentCdpLink | AgentRefusal>;
+    /**
+     * 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.
+     */
+    release(runId: string, opts?: {
+        deleteProfile?: boolean;
+        dataDir?: string;
+    }): Promise<void>;
+    /** The task whose cezar-owned dev server holds `port`. Adopted ports belong to nobody. */
+    portOwner(port: number): {
+        runId: string;
+        title: string;
+    } | undefined;
+    /** Whether this host runs the dev server `<runId>/<port>.pid.json` records: the sweep spares it. */
+    ownsServer(runId: string, port: number): boolean;
+    /** Whether an agent is connected to the run's browser now: its crash marker is this process's. */
+    hasAgents(runId: string): boolean;
+    /** Whether this host runs the run's Chromium (`<runId>/chromium.pid.json`): the sweep spares it. */
+    ownsBrowser(runId: string): boolean;
+    probe(port: number): Promise<boolean>;
+    /** cezar shuts down: every run is released and every pane closed. */
+    close(): Promise<void>;
+    private agentLeft;
+    /** The last viewer or agent left: the idle timers start, as `detach` starts them for a pane. */
+    private armIdleWithoutDemand;
+    private closeAgents;
+    /** The pane asked for the agent's page: shown as it is, never navigated. */
+    private showAgentPage;
+    private leaveAgentPage;
+    /** An agent's command made `targetId` its own: the pane follows it when that is a page. */
+    private agentTargeted;
+    /** Streams the agent's page: the home session cezar has, or a session of cezar's own on another page, dropped when the agent closes it. */
+    private followAgentPage;
+    /** The pane shows cezar's own page. It cleared its stage for this open, so an unchanged stream restarts to announce itself. */
+    private showHome;
+    /** The agent's page closed while the pane looked elsewhere: cezar's own page stands in for it. */
+    private agentPageGone;
+    /** A session of cezar's own on `targetId`, carrying the page's current URL. */
+    private openPageSession;
+    /** The agent closed the page the pane followed: the pane shows cezar's own page again. */
+    private followedGone;
+    private dropFollowed;
+    /**
+     * Makes `session` the one the pane streams, with its URL. The viewer is attached only on a change:
+     * `claim` already attached it to the current session, and a second attach restarts its screencast.
+     */
+    private streamFrom;
+    /** A resumed pane whose run another tab took since: that tab keeps it. */
+    private heldByAnotherTab;
+    private entryFor;
+    /** One viewer per run: a second one takes over, and the first is told by whom. */
+    private claim;
+    /** Tells the pane `port-held` when another task's cezar-owned server holds `server.port`. */
+    private heldByOther;
+    private registration;
+    private runDir;
+    private onServerState;
+    /** `preview.server-state`, on transitions only. A run already deleted takes no events. */
+    private recordState;
+    /** The pane's view of a cezar-owned server that is not streaming. */
+    private report;
+    /** Where a server's page reopens: the page the owner was last on when it is this server's, else the registered root. */
+    private serverPage;
+    /**
+     * 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`.
+     */
+    private showServer;
+    /** Browser, then page, then the first frame (which the session announces as `streaming`). */
+    private show;
+    private ensureSession;
+    private launch;
+    private launchFailed;
+    /** Chromium died under us: say so with the server's state, and wait for the owner's Retry. */
+    private browserExited;
+    private retryBrowser;
+    private serverUp;
+    private missingState;
+    private startDownload;
+    /** `first` watches before the download starts, so no progress report is lost. */
+    private beginDownload;
+    private closeBrowser;
+    /** The browser is going: no page of it is home, followed or the agent's any more. */
+    private forgetPages;
+    private clearIdle;
+    private releaseEntry;
+    private tell;
+}