@parall/daemon 1.34.0 → 1.36.0

package/dist/browser-pod.js

@@ -0,0 +1,765 @@
+#!/usr/bin/env node
+/**
+ * `parall-browser-pod` — the V2 hosted-browser pod entrypoint.
+ *
+ * This is the production replacement for the Go echo-stub (server/cmd/browser-stub):
+ * a single-profile pod that runs the REAL browser stack (Chromium under Xvfb +
+ * bb-browser, started lazily by BrowserProfileManager) and registers to the Clip
+ * Service hub as the "browser" provider for exactly ONE profile.
+ *
+ * It is deliberately NOT the daemon supervisor. The daemon (`index.ts`) is a
+ * Machine: it authenticates with a 90-day `mck_`, polls `/machines/me/*`, and
+ * supervises per-agent subprocesses. A hosted browser pod has none of that — it
+ * is platform infrastructure with a short-lived, controller-minted platform
+ * assignment token (`pba_`) scoped to `(org_id, profile_id, pod_id)`, and serves
+ * a single profile until its lease is released. Per the V2 design (§3.3, §6) this
+ * is an **image/entrypoint-level** slim mode: it reuses the shared clip-runtime
+ * building blocks (ClipProvider / ClipProcessManager / BrowserProfileManager)
+ * without deleting anything from the shared package, so the BYOC daemon path and
+ * its `mck_` identity are untouched.
+ *
+ * Contract (mirrors server/cmd/browser-stub/main.go, the reference implementation):
+ *
+ *   Env (injected by browser-profile-controller's pod spec):
+ *     PRLL_ASSIGNMENT_TOKEN  the pba_ platform assignment token (required)
+ *     PRLL_CLIP_RPC          in-cluster clip-service URL, e.g. http://clip-service:8095 (required)
+ *     PRLL_PROFILE_ID        the profile this pod serves (required)
+ *     PRLL_POD_ID            this pod's name → provider_name; must match the token's pod_id (required)
+ *     PRLL_ORG_ID            owning org (logging only; the hub derives org from the token)
+ *     PRLL_HEALTH_PORT       liveness/readiness listen port (default 8080)
+ *     PRLL_BROWSER_STATE_DIR root for on-disk browser state (default $HOME/.parall-agent)
+ *
+ *   Health (the contract the controller's K8s probes consume):
+ *     GET /livez  -> 200 always (process is alive; a liveness restart trigger).
+ *     GET /readyz -> 200 only while registered to the hub AND not draining, else 503.
+ *       Readiness is ROUTE-readiness, not mere liveness: a started-but-not-yet-
+ *       registered (or disconnected, or token/lease-invalidated) pod reads
+ *       NotReady, so the controller never treats pod existence as routable. The
+ *       hub fences the ProviderStream on the pba_ token + live lease, so loss of
+ *       either drops the registration → isConnected() → false → NotReady.
+ *
+ *   Shutdown (SIGTERM, on pod deletion / lease release): fail readiness FIRST so
+ *   K8s/controller stop routing, THEN tear down the ProviderStream (hub
+ *   unregisters) and the bb-browser daemon — all within terminationGracePeriod.
+ *   The authoritative lease state transition (lease -> released, quota freed) is
+ *   still owned by the controller/api-server, never inferred from the pod exiting.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createLogger } from '@parall/agent-core';
+import { BrowserProfileManager } from './clip-runtime/browser-profile-manager.js';
+import { BrowserStateStore } from './clip-runtime/browser-state-store.js';
+import { ClipProvider } from './clip-runtime/clip-provider.js';
+import { ClipProcessManager } from './clip-runtime/process-manager.js';
+/**
+ * Platform assignment token prefix (SSOT: server/pkg/platformauth/token.go). A
+ * hosted browser pod authenticates ONLY with a controller-minted `pba_` token —
+ * never an `mck_` (Machine) or `agk_` (agent) key. We fail fast on the wrong
+ * prefix, symmetric with the daemon's `mck_` guard in config.ts, to catch a
+ * misconfigured pod spec before it opens a doomed session loop.
+ */
+const ASSIGNMENT_TOKEN_PREFIX = 'pba_';
+const DEFAULT_HEALTH_PORT = 8080;
+/** Default cadence for periodic S3 checkpoints while the pod runs (design §3.2). */
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 60_000;
+/** Parse a TCP port from env, falling back when absent or out of the 1–65535 range. */
+function parsePort(value, fallback) {
+    if (!value)
+        return fallback;
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : fallback;
+}
+/**
+ * Resolve and validate the pod's runtime config from the environment. Throws on
+ * any missing required var (fail-fast: a pod missing its token / clip-rpc /
+ * profile / pod id can never register, so we crash now instead of starting a
+ * doomed reconnect loop).
+ */
+export function resolveBrowserPodConfig(env = process.env) {
+    const assignmentToken = env.PRLL_ASSIGNMENT_TOKEN?.trim() || '';
+    const clipRpcUrl = env.PRLL_CLIP_RPC?.trim() || '';
+    const profileId = env.PRLL_PROFILE_ID?.trim() || '';
+    const podId = env.PRLL_POD_ID?.trim() || '';
+    const orgId = env.PRLL_ORG_ID?.trim() || '';
+    const missing = [];
+    if (!assignmentToken)
+        missing.push('PRLL_ASSIGNMENT_TOKEN');
+    if (!clipRpcUrl)
+        missing.push('PRLL_CLIP_RPC');
+    if (!profileId)
+        missing.push('PRLL_PROFILE_ID');
+    if (!podId)
+        missing.push('PRLL_POD_ID');
+    if (missing.length > 0) {
+        throw new Error(`browser-pod: missing required env: ${missing.join(', ')}`);
+    }
+    if (!assignmentToken.startsWith(ASSIGNMENT_TOKEN_PREFIX)) {
+        throw new Error(`browser-pod: PRLL_ASSIGNMENT_TOKEN is not a platform assignment token ` +
+            `(expected "${ASSIGNMENT_TOKEN_PREFIX}" prefix). Hosted browser pods authenticate ` +
+            `with a controller-minted assignment token, never an mck_/agk_ key.`);
+    }
+    const home = env.HOME?.trim() || os.homedir();
+    const stateDir = env.PRLL_BROWSER_STATE_DIR?.trim() || path.join(home, '.parall-agent');
+    const homeDir = path.join(stateDir, 'bb-browser');
+    return {
+        assignmentToken,
+        clipRpcUrl,
+        profileId,
+        podId,
+        orgId,
+        healthPort: parsePort(env.PRLL_HEALTH_PORT, DEFAULT_HEALTH_PORT),
+        stateDir,
+        homeDir,
+    };
+}
+/**
+ * Resolve a warm pod's identity-less config. Unlike resolveBrowserPodConfig this
+ * requires PRLL_POOL_TOKEN (not PRLL_ASSIGNMENT_TOKEN) and NO profile/org — those
+ * arrive later via /assign. PRLL_CLIP_RPC is injected at pool creation (stable per
+ * cluster) so the assigned path needs no extra wiring.
+ */
+export function resolvePoolPodConfig(env = process.env) {
+    const poolToken = env.PRLL_POOL_TOKEN?.trim() || '';
+    const podId = env.PRLL_POD_ID?.trim() || '';
+    const clipRpcUrl = env.PRLL_CLIP_RPC?.trim() || '';
+    const missing = [];
+    if (!poolToken)
+        missing.push('PRLL_POOL_TOKEN');
+    if (!podId)
+        missing.push('PRLL_POD_ID');
+    if (!clipRpcUrl)
+        missing.push('PRLL_CLIP_RPC');
+    if (missing.length > 0) {
+        throw new Error(`browser-pod (pool): missing required env: ${missing.join(', ')}`);
+    }
+    if (!poolToken.startsWith(ASSIGNMENT_TOKEN_PREFIX)) {
+        throw new Error(`browser-pod (pool): PRLL_POOL_TOKEN is not a platform token (expected "${ASSIGNMENT_TOKEN_PREFIX}" prefix).`);
+    }
+    return {
+        poolToken,
+        podId,
+        clipRpcUrl,
+        healthPort: parsePort(env.PRLL_HEALTH_PORT, DEFAULT_HEALTH_PORT),
+    };
+}
+/**
+ * Validate + normalize an /assign body (already JSON-parsed). Rejects a missing /
+ * non-pba_ assignment token, a missing profile/lease, and PARTIAL S3 creds (a
+ * half-set would build a misconfigured S3 client — worse than stateless). State is
+ * optional (stateless profile); when present it must be complete.
+ */
+export function parseAssignRequest(body) {
+    if (typeof body !== 'object' || body === null) {
+        return { ok: false, error: 'body must be a JSON object' };
+    }
+    const b = body;
+    const str = (v) => (typeof v === 'string' ? v.trim() : '');
+    const assignmentToken = str(b.assignment_token);
+    const profileId = str(b.profile_id);
+    const orgId = str(b.org_id);
+    const leaseId = str(b.lease_id);
+    const generation = typeof b.generation === 'number' && Number.isFinite(b.generation) ? b.generation : 0;
+    if (!assignmentToken)
+        return { ok: false, error: 'assignment_token required' };
+    if (!assignmentToken.startsWith(ASSIGNMENT_TOKEN_PREFIX)) {
+        return { ok: false, error: `assignment_token must be a "${ASSIGNMENT_TOKEN_PREFIX}" token` };
+    }
+    if (!profileId)
+        return { ok: false, error: 'profile_id required' };
+    if (!leaseId)
+        return { ok: false, error: 'lease_id required' };
+    let state;
+    if (b.state !== undefined && b.state !== null) {
+        if (typeof b.state !== 'object')
+            return { ok: false, error: 'state must be an object' };
+        const s = b.state;
+        const bucket = str(s.bucket);
+        const accessKeyId = str(s.access_key_id);
+        const secretAccessKey = str(s.secret_access_key);
+        const sessionToken = str(s.session_token);
+        if (!bucket || !accessKeyId || !secretAccessKey || !sessionToken) {
+            return {
+                ok: false,
+                error: 'state requires bucket + access_key_id + secret_access_key + session_token',
+            };
+        }
+        state = {
+            bucket,
+            region: str(s.region),
+            endpoint: str(s.endpoint) || undefined,
+            accessKeyId,
+            secretAccessKey,
+            sessionToken,
+        };
+    }
+    return { ok: true, value: { assignmentToken, profileId, orgId, leaseId, generation, state } };
+}
+/**
+ * Apply an /assign payload to `env` (process.env in prod) so the assigned path
+ * reads identity + S3 creds EXACTLY as the controller injects them into a cold
+ * pod's spec. The AWS_* creds must land in process.env: the S3 client
+ * (browser-state-store buildS3Client) reads the default AWS provider chain.
+ */
+export function applyAssignmentEnv(env, req) {
+    env.PRLL_ASSIGNMENT_TOKEN = req.assignmentToken;
+    env.PRLL_PROFILE_ID = req.profileId;
+    if (req.orgId)
+        env.PRLL_ORG_ID = req.orgId;
+    if (req.state) {
+        env.AWS_ACCESS_KEY_ID = req.state.accessKeyId;
+        env.AWS_SECRET_ACCESS_KEY = req.state.secretAccessKey;
+        env.AWS_SESSION_TOKEN = req.state.sessionToken;
+        if (req.state.region)
+            env.AWS_REGION = req.state.region;
+        env.PRLL_BROWSER_STATE_BUCKET = req.state.bucket;
+        env.PRLL_STATE_GENERATION = String(req.generation);
+        if (req.state.endpoint)
+            env.PRLL_BROWSER_STATE_ENDPOINT = req.state.endpoint;
+    }
+}
+/** Constant-time bearer comparison against the injected pool token. The pod cannot
+ *  verify the JWT signature (no shared secret), so it string-compares the bearer to
+ *  its own PRLL_POOL_TOKEN — the controller reads that same value back from the pod
+ *  spec when it POSTs /assign. */
+function poolTokenMatches(bearer, expected) {
+    if (!bearer)
+        return false;
+    const a = Buffer.from(bearer);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+function errString(err) {
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}
+/**
+ * Build the warm pod's /assign controller. The cardinal rules:
+ *   - auth: bearer MUST equal the pool token (constant-time).
+ *   - single-assignment: a warm pod serves ONE profile for life — a repeat for the
+ *     same lease is idempotent (200), a different lease is a conflict (409). The
+ *     lease is claimed SYNCHRONOUSLY so a duplicate/concurrent POST conflicts.
+ *   - eventual readiness: identity is applied then the real runtime is started in
+ *     the BACKGROUND (hydrate + connect take seconds); /readyz is the gate, exactly
+ *     as a cold pod whose Create returns fast and becomes Ready later.
+ * `startRuntime` is injected so the assign flow is testable without a real hub.
+ */
+export function createPoolAssign(opts) {
+    let runtime = null;
+    let leaseId = null;
+    const handler = async (bearer, body) => {
+        if (!poolTokenMatches(bearer, opts.poolToken)) {
+            return { status: 401, message: 'unauthorized' };
+        }
+        const parsed = parseAssignRequest(body);
+        if (!parsed.ok)
+            return { status: 400, message: parsed.error };
+        const req = parsed.value;
+        if (leaseId !== null) {
+            if (leaseId === req.leaseId)
+                return { status: 200, message: 'already assigned (idempotent)' };
+            return { status: 409, message: 'pod already assigned to a different lease' };
+        }
+        leaseId = req.leaseId; // claim synchronously: a duplicate/concurrent POST now conflicts
+        applyAssignmentEnv(opts.env, req);
+        opts.log.info(`assigned: profile=${req.profileId} lease=${req.leaseId} gen=${req.generation} state=${req.state ? 'on' : 'off'}`);
+        void (async () => {
+            try {
+                runtime = await opts.startRuntime(opts.env);
+                opts.log.info(`runtime started for lease=${req.leaseId}`);
+            }
+            catch (err) {
+                opts.log.error(`runtime start failed for lease=${req.leaseId}: ${errString(err)} — /readyz stays 503; controller releases on the registration deadline`);
+            }
+        })();
+        return { status: 200, message: 'assignment accepted' };
+    };
+    return {
+        handler,
+        isReady: () => runtime?.isReady() ?? false,
+        drain: async () => {
+            if (runtime)
+                await runtime.drain();
+        },
+        assignedLeaseId: () => leaseId,
+    };
+}
+/**
+ * BrowserPodRuntime owns the pod's readiness state and the ordered teardown. It
+ * is deliberately decoupled from the concrete ClipProvider / BrowserProfileManager
+ * (only the narrow PodProvider / PodBrowser surfaces) so the readiness gate and
+ * drain ORDER are unit-testable without a real browser or hub.
+ */
+export class BrowserPodRuntime {
+    provider;
+    browser;
+    log;
+    checkpointer;
+    checkpointIntervalMs;
+    draining = false;
+    drainPromise = null;
+    checkpointTimer = null;
+    constructor(provider, browser, log, 
+    // Optional S3 state checkpointer (PR4). Absent => stateless pod (no
+    // hydrate/checkpoint); the drain order then matches the pre-PR4 contract.
+    checkpointer, checkpointIntervalMs = DEFAULT_CHECKPOINT_INTERVAL_MS) {
+        this.provider = provider;
+        this.browser = browser;
+        this.log = log;
+        this.checkpointer = checkpointer;
+        this.checkpointIntervalMs = checkpointIntervalMs;
+    }
+    /**
+     * Route-readiness: registered to the hub AND not draining. `draining` is checked
+     * first so the readiness gate flips false the instant a drain begins — before
+     * the (async) ProviderStream teardown completes. The hub fences the stream on
+     * the pba_ token + live lease, so isConnected() already encodes "token/lease
+     * still valid".
+     */
+    isReady() {
+        return !this.draining && this.provider.isConnected();
+    }
+    /** Open the ProviderStream, register as the "browser" provider, and start the
+     *  periodic checkpoint loop (if a checkpointer was supplied). */
+    async start() {
+        await this.provider.connect();
+        this.startCheckpointLoop();
+    }
+    /** Periodic S3 checkpoints while serving. Best-effort: a checkpoint error is
+     *  logged but never throws (it must not kill the pod); the timer is unref'd so it
+     *  never keeps the process alive on its own. */
+    startCheckpointLoop() {
+        if (!this.checkpointer || this.checkpointIntervalMs <= 0)
+            return;
+        const cp = this.checkpointer;
+        this.checkpointTimer = setInterval(() => {
+            if (this.draining)
+                return;
+            void cp.checkpointPeriodic().catch((err) => {
+                this.log.warn(`periodic checkpoint error: ${String(err)}`);
+            });
+        }, this.checkpointIntervalMs);
+        this.checkpointTimer.unref?.();
+    }
+    /**
+     * Graceful drain (SIGTERM / lease release): fail readiness FIRST, stop the
+     * periodic checkpoint loop, then tear down the hub stream and the browser, and
+     * finally take ONE last checkpoint AFTER bb-browser is stopped (a consistent
+     * snapshot of the settled state — design §3.2). Idempotent — a second SIGTERM
+     * joins the first.
+     */
+    async drain() {
+        if (this.drainPromise)
+            return this.drainPromise;
+        this.draining = true; // readiness -> false BEFORE we close the stream
+        this.log.info('draining (readiness -> false)');
+        if (this.checkpointTimer) {
+            clearInterval(this.checkpointTimer);
+            this.checkpointTimer = null;
+        }
+        this.drainPromise = (async () => {
+            try {
+                await this.provider.disconnect();
+            }
+            catch (err) {
+                this.log.warn(`provider disconnect during drain failed: ${String(err)}`);
+            }
+            try {
+                await this.browser.stop();
+            }
+            catch (err) {
+                this.log.warn(`browser stop during drain failed: ${String(err)}`);
+            }
+            // Final checkpoint AFTER bb-browser has torn down — Chromium has flushed and
+            // released its files, so the snapshot is consistent. A failure here is bounded
+            // loss (the delta since the last successful checkpoint), logged below —
+            // durability is best-effort + on-close, with no controller-side verify/repair
+            // (design §3.2 "simplified durability").
+            if (this.checkpointer) {
+                try {
+                    await this.checkpointer.checkpointFinal();
+                }
+                catch (err) {
+                    this.log.error(`final checkpoint during drain failed: ${String(err)}`);
+                }
+            }
+        })();
+        return this.drainPromise;
+    }
+}
+/**
+ * Create the liveness/readiness HTTP server. `/livez` is mere process liveness;
+ * `/readyz` is route-readiness driven by `isReady`. Mirrors the Go stub's health
+ * contract so the controller's probes are runtime-agnostic.
+ */
+export function createHealthServer(opts) {
+    const server = http.createServer((req, res) => {
+        const url = req.url ?? '';
+        if (url === '/livez') {
+            res.writeHead(opts.isLive() ? 200 : 503).end();
+            return;
+        }
+        if (url === '/readyz') {
+            res.writeHead(opts.isReady() ? 200 : 503).end();
+            return;
+        }
+        if (opts.onAssign && url === '/assign' && req.method === 'POST') {
+            handleAssignRequest(req, res, opts.onAssign, opts.log);
+            return;
+        }
+        res.writeHead(404).end();
+    });
+    // Bound header read so a slow/half-open probe connection can't pin a slot.
+    server.headersTimeout = 5_000;
+    server.requestTimeout = 10_000;
+    return server;
+}
+/** Cap the /assign body — the payload is a small JSON blob (token + creds); a
+ *  larger body is malformed/hostile and must not buffer unbounded. */
+const MAX_ASSIGN_BODY_BYTES = 64 * 1024;
+/** Read + JSON-parse a bounded POST /assign body, dispatch to the handler, and
+ *  write its outcome. All failures map to an HTTP status (never crash the server). */
+function handleAssignRequest(req, res, onAssign, log) {
+    const chunks = [];
+    let size = 0;
+    let aborted = false;
+    const fail = (status) => {
+        if (aborted)
+            return;
+        aborted = true;
+        res.writeHead(status).end();
+    };
+    req.on('data', (c) => {
+        if (aborted)
+            return;
+        size += c.length;
+        if (size > MAX_ASSIGN_BODY_BYTES) {
+            fail(413);
+            req.destroy();
+            return;
+        }
+        chunks.push(c);
+    });
+    req.on('error', () => fail(400));
+    req.on('end', () => {
+        if (aborted)
+            return;
+        let body;
+        try {
+            body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+        }
+        catch {
+            res
+                .writeHead(400, { 'content-type': 'application/json' })
+                .end(JSON.stringify({ ok: false, error: 'invalid JSON' }));
+            return;
+        }
+        void onAssign(bearerFromHeader(req.headers.authorization), body)
+            .then((outcome) => {
+            res.writeHead(outcome.status, { 'content-type': 'application/json' }).end(JSON.stringify({
+                ok: outcome.status >= 200 && outcome.status < 300,
+                message: outcome.message,
+            }));
+        })
+            .catch((err) => {
+            log.error(`/assign handler error: ${errString(err)}`);
+            res
+                .writeHead(500, { 'content-type': 'application/json' })
+                .end(JSON.stringify({ ok: false }));
+        });
+    });
+}
+/** Strip a leading "Bearer " from an Authorization header (case-sensitive scheme,
+ *  matching the hub). Returns the raw credential, or undefined when absent. */
+function bearerFromHeader(authorization) {
+    if (!authorization)
+        return undefined;
+    return authorization.startsWith('Bearer ') ? authorization.slice(7) : authorization;
+}
+/**
+ * Build the S3 state store from env, or return null (stateless pod) ONLY when no
+ * bucket is configured (the feature is off). When a bucket IS set, state was
+ * REQUESTED, so the org id (part of the S3 key + the pod's STS prefix scope) and the
+ * activation generation (the single-writer fence) are required: a missing/invalid
+ * value is a controller-injection misconfiguration and FAILS CLOSED (throws) rather
+ * than silently registering a non-persisted profile — silent stateless serving when
+ * state was configured is data loss. The thrown error propagates to pod startup, so
+ * the pod never reaches readiness and the controller releases it on the deadline.
+ */
+export function buildStateStore(config, env, log) {
+    const bucket = env.PRLL_BROWSER_STATE_BUCKET?.trim();
+    if (!bucket)
+        return null; // no bucket = intentionally stateless
+    if (!config.orgId) {
+        throw new Error(`browser state enabled (bucket=${bucket}) but PRLL_ORG_ID is empty — refusing to run a non-persisted profile (fail closed)`);
+    }
+    const genRaw = env.PRLL_STATE_GENERATION?.trim();
+    if (!genRaw) {
+        // Missing: never silently default to generation 0 — that would un-fence the pod
+        // (gen 0 is the lowest, so any real pod clobbers it). State configured but invalid
+        // = refuse to run BEFORE the provider opens (this throw propagates to startup).
+        throw new Error(`browser state enabled (bucket=${bucket}) but PRLL_STATE_GENERATION is unset — refusing to run a non-persisted profile (fail closed)`);
+    }
+    const gen = Number(genRaw);
+    if (!Number.isSafeInteger(gen) || gen < 0) {
+        throw new Error(`browser state enabled (bucket=${bucket}) but PRLL_STATE_GENERATION="${genRaw}" is not a non-negative safe integer — refusing to run a non-persisted profile (fail closed)`);
+    }
+    return new BrowserStateStore({
+        bucket,
+        region: env.AWS_REGION?.trim() || env.PRLL_BROWSER_STATE_REGION?.trim() || '',
+        endpoint: env.PRLL_BROWSER_STATE_ENDPOINT?.trim() || undefined,
+        orgId: config.orgId,
+        profileId: config.profileId,
+        generation: gen,
+        homeDir: config.homeDir,
+        log,
+    });
+}
+/** Resolve the periodic checkpoint cadence (ms) from env, clamped to ≥1s. */
+export function resolveCheckpointIntervalMs(env) {
+    const raw = env.PRLL_BROWSER_STATE_CHECKPOINT_INTERVAL_MS?.trim();
+    if (!raw)
+        return DEFAULT_CHECKPOINT_INTERVAL_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1_000 ? n : DEFAULT_CHECKPOINT_INTERVAL_MS;
+}
+/**
+ * Whether it is SAFE to checkpoint after a hydrate. Checkpoint ONLY when the prior
+ * snapshot was loaded (hydrated) or there was genuinely none (a new profile —
+ * head returned null, so no flags set). If a snapshot EXISTED but could not be
+ * loaded (checksum mismatch, or a download/extract/HEAD error), checkpointing must
+ * be disabled: an empty homeDir would otherwise overwrite the good state, and the
+ * generation fence permits it (this pod's gen is legitimately higher than the
+ * snapshot's). Returns false in that case so the pod runs checkpoint-less, leaving
+ * the existing snapshot untouched rather than clobbering it (simplified durability:
+ * the prior state is preserved in place — there is no controller-side repair).
+ */
+export function shouldCheckpointAfterHydrate(result) {
+    return !(result.checksumMismatch === true || result.error !== undefined);
+}
+/** Adapt a BrowserStateStore to the narrow PodStateCheckpointer the runtime drives. */
+function makeCheckpointer(store) {
+    return {
+        checkpointPeriodic: async () => {
+            await store.checkpoint({ final: false });
+        },
+        checkpointFinal: async () => {
+            await store.checkpoint({ final: true });
+        },
+    };
+}
+/**
+ * Wire the real clip-runtime stack for a hosted browser pod from a resolved config
+ * and return the {@link BrowserPodRuntime} — WITHOUT creating the health server,
+ * binding a port, or parking on a signal. Splitting this out lets the warm-pool
+ * path (runPoolPod) reuse the EXACT assigned-pod wiring after a `/assign` arrives,
+ * while keeping a single control/health server bound on healthPort (the pool path
+ * already owns it). hydrate() runs here — before the provider opens — because
+ * bb-browser launches lazily on first invoke, so the snapshot must be on disk first.
+ */
+export async function preparePodRuntime(config, env, log) {
+    // Real browser runtime — starts bb-browser + Chromium lazily on first invoke,
+    // ensures the single profile's account, persists under homeDir (BB_BROWSER_HOME).
+    const browser = new BrowserProfileManager({ homeDir: config.homeDir, log });
+    // The process manager hosts no installable clips in pod mode — its only job is
+    // to advertise the synthetic "browser" capability (getProviderClips appends it
+    // because a BrowserProfileManager is present) and route inbound browser invokes
+    // to bb-browser. The clip/data dirs are required but unused (no subprocess).
+    const clipManager = new ClipProcessManager({
+        clipsDir: path.join(config.stateDir, 'clips'),
+        dataDir: path.join(config.stateDir, 'clip-data'),
+        browserProfileManager: browser,
+    });
+    // Hosted live-viewer handler (design §3.4): clip-service relays viewer commands
+    // down the ProviderStream and the pod replies over it. Serialize them — they
+    // mutate the single profile's bb-viewer streamer + account state, so a client
+    // retrying stream.start must not interleave with the in-flight one (the BYOC
+    // supervisor serializes per profile for the same reason). One pod = one
+    // profile, so a single chain suffices.
+    let viewerChain = Promise.resolve();
+    const onViewerCommand = (cmd) => {
+        const run = viewerChain
+            .catch(() => { }) // keep the chain moving past a prior failure
+            .then(() => browser.handleViewerCommand(cmd.profileId, cmd.sessionId, cmd.command, cmd.input, cmd.turn));
+        viewerChain = run.catch(() => { });
+        return run;
+    };
+    // ClipProvider passes authKey straight through as the ProviderStream bearer —
+    // it does not assume mck_ — so the pba_ assignment token authenticates the pod.
+    // providerName is cosmetic for routing (the hub keys the session by the token's
+    // profile_id), but we use the pod id so logs/registration map to this pod.
+    const provider = new ClipProvider({
+        serviceUrl: config.clipRpcUrl,
+        authKey: config.assignmentToken,
+        orgId: config.orgId,
+        providerName: config.podId,
+        clipManager,
+        log,
+        onViewerCommand,
+    });
+    // S3 state externalization (PR4, design §3.2). Disabled (stateless pod) when no
+    // bucket is configured. HYDRATE here — before the provider opens and any invoke
+    // can land — because bb-browser launches lazily on first invoke, so the snapshot
+    // must already be on disk. hydrate() never throws (a read failure → fresh start).
+    const stateStore = buildStateStore(config, env, log);
+    let checkpointer;
+    if (stateStore) {
+        const result = await stateStore.hydrate();
+        // Data-loss guard: only attach a checkpointer when it is safe to overwrite the
+        // snapshot (we loaded it, or there was genuinely none). If a snapshot existed
+        // but could not be hydrated, run checkpoint-less to preserve it — see
+        // shouldCheckpointAfterHydrate.
+        if (shouldCheckpointAfterHydrate(result)) {
+            checkpointer = makeCheckpointer(stateStore);
+        }
+        else {
+            log.error('browser-state: prior snapshot present but un-hydratable — running WITHOUT checkpoint to preserve the existing snapshot in place');
+        }
+    }
+    else {
+        log.info('browser state externalization disabled (no PRLL_BROWSER_STATE_BUCKET) — running stateless');
+    }
+    return new BrowserPodRuntime(provider, browser, log, checkpointer, resolveCheckpointIntervalMs(env));
+}
+/**
+ * Wire the real clip-runtime stack for a hosted browser pod and run until the
+ * abort signal fires (SIGTERM). Returns after the ordered drain completes. This is
+ * the ASSIGNED path: PRLL_ASSIGNMENT_TOKEN + profile are already in env (the
+ * controller's cold-create pod spec). The warm-pool path (runPoolPod) reaches the
+ * same runtime via preparePodRuntime once a `/assign` delivers the identity.
+ */
+export async function runBrowserPod(env, signal, log) {
+    const config = resolveBrowserPodConfig(env);
+    log.info(`starting: profile=${config.profileId} pod=${config.podId} ` +
+        `org=${config.orgId || '(unset)'} clip_rpc=${config.clipRpcUrl} health_port=${config.healthPort}`);
+    const runtime = await preparePodRuntime(config, env, log);
+    const health = createHealthServer({
+        isLive: () => true,
+        isReady: () => runtime.isReady(),
+        log,
+    });
+    await new Promise((resolve, reject) => {
+        health.once('error', reject);
+        health.listen(config.healthPort, () => {
+            health.removeListener('error', reject);
+            log.info(`health server listening on :${config.healthPort}`);
+            resolve();
+        });
+    });
+    try {
+        await runtime.start();
+        log.info('provider stream opened — awaiting hub registration');
+        // Run until SIGTERM. ClipProvider keeps the stream alive (heartbeat +
+        // reconnect) internally; we just park here until told to drain.
+        await new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            signal.addEventListener('abort', () => resolve(), { once: true });
+        });
+    }
+    finally {
+        await runtime.drain();
+        await new Promise((resolve) => health.close(() => resolve()));
+        log.info('shut down');
+    }
+}
+/**
+ * Run a WARM pod: bind ONE control/health server (livez/readyz/assign) on
+ * healthPort and park — no Chromium, no profile, no hub registration — until a
+ * `POST /assign` delivers an identity, at which point the pod transitions into the
+ * exact assigned-pod runtime (preparePodRuntime, hydrating S3 like a cold pod). On
+ * SIGTERM, drain the started runtime (if any) then close the server. The single
+ * server is the reason runPoolPod reuses preparePodRuntime rather than runBrowserPod
+ * (which would bind its own health port).
+ */
+export async function runPoolPod(env, signal, log) {
+    const pool = resolvePoolPodConfig(env);
+    log.info(`pool mode: pod=${pool.podId} clip_rpc=${pool.clipRpcUrl} health_port=${pool.healthPort} — awaiting /assign`);
+    const assign = createPoolAssign({
+        poolToken: pool.poolToken,
+        env,
+        log,
+        // The assigned path, unchanged: env now carries the identity + S3 creds, so
+        // resolveBrowserPodConfig + preparePodRuntime behave exactly as a cold pod.
+        startRuntime: async (e) => {
+            const config = resolveBrowserPodConfig(e);
+            log.info(`pool→assigned: profile=${config.profileId} pod=${config.podId} org=${config.orgId || '(unset)'}`);
+            const runtime = await preparePodRuntime(config, e, log);
+            await runtime.start();
+            return runtime;
+        },
+    });
+    const control = createHealthServer({
+        isLive: () => true,
+        isReady: () => assign.isReady(),
+        log,
+        onAssign: assign.handler,
+    });
+    await new Promise((resolve, reject) => {
+        control.once('error', reject);
+        control.listen(pool.healthPort, () => {
+            control.removeListener('error', reject);
+            log.info(`pool control server listening on :${pool.healthPort}`);
+            resolve();
+        });
+    });
+    try {
+        await new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            signal.addEventListener('abort', () => resolve(), { once: true });
+        });
+    }
+    finally {
+        await assign.drain();
+        await new Promise((resolve) => control.close(() => resolve()));
+        log.info('pool pod shut down');
+    }
+}
+/** Process entrypoint: wire SIGINT/SIGTERM → abort, then run the pod to drain.
+ *  Mode is selected by which token is present: PRLL_ASSIGNMENT_TOKEN → assigned
+ *  (cold-create), else PRLL_POOL_TOKEN → warm pool. The controller's pod spec
+ *  injects exactly one. */
+async function main() {
+    const log = createLogger('browser-pod');
+    const abort = new AbortController();
+    const onSignal = (sig) => {
+        log.info(`received ${sig} — initiating shutdown`);
+        abort.abort();
+    };
+    process.on('SIGINT', () => onSignal('SIGINT'));
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+    try {
+        if (process.env.PRLL_ASSIGNMENT_TOKEN?.trim()) {
+            await runBrowserPod(process.env, abort.signal, log);
+        }
+        else if (process.env.PRLL_POOL_TOKEN?.trim()) {
+            await runPoolPod(process.env, abort.signal, log);
+        }
+        else {
+            throw new Error('browser-pod: set PRLL_ASSIGNMENT_TOKEN (assigned pod) or PRLL_POOL_TOKEN (warm pool pod)');
+        }
+    }
+    catch (err) {
+        log.error(`fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+        process.exitCode = 1;
+    }
+}
+// Run only when invoked as the entrypoint (bundled bin), not when imported by a
+// test. We are the entry iff import.meta.url points at the same file as argv[1].
+// CRUCIAL: resolve argv[1] through realpathSync first. The container runs this via
+// the npm `parall-browser-pod` bin, which is a SYMLINK — Node sets argv[1] to the
+// symlink path but resolves import.meta.url to the real file, so a raw comparison is
+// always false and main() never runs (the pod then exits 0 immediately, doing
+// nothing). realpathSync collapses the symlink so the entry check holds; when this
+// module is merely imported (tests) argv[1] is the test runner, so it stays false.
+const entry = process.argv[1];
+if (entry && import.meta.url === pathToFileURL(realpathSync(entry)).href) {
+    void main();
+}