@parall/daemon 1.36.0 → 1.37.0

package/dist/clip-runtime/browser-profile-pool.js

@@ -0,0 +1,581 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import * as path from 'node:path';
+import { BrowserProfileManager, } from './browser-profile-manager.js';
+/**
+ * BrowserProfilePool — true per-profile isolation for the BYOC daemon supervisor.
+ *
+ * WHY THIS EXISTS. A single bb-browser/Chromium shared across profiles isolates
+ * only at the bb-browser "account" (CDP BrowserContext) level. That is real for
+ * cookies/storage, but bb-browser's COMMAND routing is account-blind: any command
+ * issued without an explicit tabId falls through to a single GLOBAL current tab
+ * (cdp.currentTargetId, else targets[0]) regardless of the `account` field
+ * (bb-browser-pro daemon.js ensurePageTarget). So when the global current tab
+ * belongs to profile A, a command meant for profile B executes in A's context —
+ * e.g. logging into a second account overwrites the first, and two profiles can
+ * never hold two different sessions at once (reproduced on a real Chrome).
+ *
+ * THE FIX. Give every profile its OWN bb-browser daemon + Chromium + on-disk home
+ * (`<baseHomeDir>/<profileId>`). Each Chromium then hosts exactly one profile, so
+ * there is no cross-profile global tab to leak into — isolation is enforced by the
+ * OS process + user-data-dir boundary, not by remembering to scope every command.
+ * The pool owns one {@link BrowserProfileManager} per profile and routes by
+ * profileId; an idle (stopped) profile holds no Chromium, so cost scales with the
+ * number of CONCURRENTLY-OPEN profiles, not the number that ever existed.
+ *
+ * NOT used by the hosted browser pod (`browser-pod.ts`): a pod serves exactly one
+ * profile, so it keeps using a single BrowserProfileManager directly (and its
+ * BrowserStateStore snapshots that manager's flat homeDir to S3 — the pool's
+ * per-profile nesting would break that). The pool is supervisor-only.
+ *
+ * OWNERSHIP. The pool is a per-profile runtime REGISTRY + the per-profile mutex
+ * (create / stop / list-active / invoke / viewer, serialized via `enqueue()`). The
+ * DESIRED-STATE coordinator is the supervisor: the server (clip-service) is the
+ * SSOT for which profiles should be live, and `DaemonSupervisor.reconcileBrowserProfiles`
+ * converges the local registry to it (open/ensure desired, stop the rest via
+ * `activeProfileIds()`). The pool keeps one bit of lifecycle policy — the `stopped`
+ * fence — because invoke (hub channel) and viewer funnel through it and must reject
+ * a stale command without a server round-trip.
+ */
+export class BrowserProfilePool {
+    opts;
+    managers = new Map();
+    // Per-profile op queue. Hub browser invokes arrive through ClipProcessManager,
+    // NOT the supervisor's per-profile lifecycle queue, so without this an invoke
+    // could interleave with a stop/reset that is disposing the same profile's
+    // runtime — racing a reset's wipe. Every op for a profileId runs serially;
+    // different profiles stay parallel.
+    opChains = new Map();
+    // Desired-state fence: profiles explicitly stopped/reset (desired = down).
+    // Serialization alone orders ops but does not stop a LATE invoke (authorized
+    // before the stop, arriving after it on the independent hub channel) from
+    // re-spawning a Chromium for a stopped profile and flipping it back to
+    // running. An invoke OR viewer command for a fenced profile is rejected until
+    // an explicit open/ensureRuntime (lifecycle/reconcile) revives it — a stale
+    // viewer command must not resurrect a profile the server already stopped. The
+    // full reconcile also fences profiles the server no longer lists as live.
+    stopped = new Set();
+    // Monotonic per-profile counter bumped every time the profile is fenced (stop /
+    // reset / reconcile release / pre-fence). A revive (open / ensureRuntime)
+    // captures this at ENQUEUE time and, when it finally runs, refuses to clear the
+    // fence if a newer stop was observed since — so a stale open/ensure queued
+    // before a stop (e.g. a reconnect reconcile racing a stop) can't un-fence the
+    // profile and let a late hub invoke spawn a transient Chromium. Last-write-wins.
+    stopSeq = new Map();
+    // Last lifecycle_generation observed for a profile (from a lifecycle event / reconcile
+    // snapshot). A hub invoke CAPTURES this at the pool entry (enqueue) so its `running`
+    // report carries the generation it was issued under — a later stop bumps the server's
+    // generation, so that captured (older) generation is then rejected as stale (PR #1650).
+    generations = new Map();
+    // The generation of the op CURRENTLY running for a profile, set at op start (the value
+    // captured at enqueue) and read by the manager-report wrapper so manager-driven status
+    // reports carry it. Per-profile ops are serialized, so this is stable for the op's
+    // duration — it is NOT a live read of `generations` (which a concurrent stop would move).
+    opGeneration = new Map();
+    // Set by stop() and NEVER reset (stop() is terminal — the supervisor discards
+    // the pool afterward). manager() refuses to create/return a runtime while true,
+    // so no queued or late op can spawn a manager that escapes teardown (the maps
+    // are cleared mid-stop and a queued op's closure may run after stop() returns).
+    stopping = false;
+    constructor(opts) {
+        this.opts = opts;
+        mkdirSync(this.opts.baseHomeDir, { recursive: true });
+    }
+    // All per-profile entrypoints go through enqueue() — it both serializes against
+    // concurrent lifecycle ops and turns a synchronous reject from manager() (e.g.
+    // an unsafe profile id) into a rejected promise, honoring the BrowserInvoker
+    // `Promise<…>` contract.
+    /** Inbound hub browser invoke for a profile — routed to that profile's own daemon. */
+    invoke(request) {
+        // Capture the profile's generation at the POOL ENTRY (enqueue), not when the op
+        // runs: if a stop arrives while this invoke waits in the queue, its captured
+        // (older) generation makes the server reject the `running` report as stale.
+        const generation = this.generations.get(request.profileId);
+        return this.enqueue(request.profileId, () => this.runWithGeneration(request.profileId, generation, () => {
+            // Reject a late invoke for a profile that was explicitly stopped/reset — do
+            // not resurrect it (see the `stopped` fence). An explicit open / ensureRuntime
+            // / viewer takeover clears the fence first. NOTE: a hub invoke reaches the pool
+            // directly while a lifecycle open may still be in the supervisor queue, so an
+            // invoke racing an in-flight open can hit the fence and be rejected here even
+            // though that open will clear it on its next turn — the rejection is transient
+            // (the hub retries next cycle), not a lost command.
+            if (this.stopped.has(request.profileId)) {
+                throw new Error(`browser profile ${request.profileId} is stopped; open it before invoking`);
+            }
+            // Pin account === profileId at the pool boundary. Each profile has its OWN
+            // Chromium hosting exactly one bb-browser account (the profileId), so a
+            // mismatched `account` in the request must never reach the manager — it would
+            // address a non-existent account and bb-browser's account-blind routing would
+            // fall through to the global current tab (the very leak this pool fixes).
+            return this.manager(request.profileId).invoke({ ...request, account: request.profileId });
+        }));
+    }
+    // Set opGeneration for the duration of a serialized op so manager-driven status
+    // reports carry the captured generation, then clear it. `gen` is captured at enqueue
+    // (invoke) or passed from the lifecycle event / reconcile snapshot (open/ensure/stop/
+    // reset). Per-profile ops are serialized, so opGeneration is stable for the op.
+    async runWithGeneration(profileId, gen, fn) {
+        if (gen !== undefined)
+            this.opGeneration.set(profileId, gen);
+        try {
+            return await fn();
+        }
+        finally {
+            if (gen !== undefined)
+                this.opGeneration.delete(profileId);
+        }
+    }
+    /**
+     * Reconcile-time: ensure the profile's runtime (account + tab) is live. If
+     * `sinceSeq` (the fence generation observed when this op was enqueued) is given
+     * and a newer stop has been observed since, skip — a stale reconcile/open queued
+     * before a stop must not un-fence and revive a profile about to be torn down
+     * (the pending stop wins; last-write-wins).
+     */
+    ensureRuntime(profileId, sinceSeq, generation, opts = {}) {
+        return this.enqueue(profileId, () => this.runWithGeneration(profileId, generation, async () => {
+            if (this.isStaleRevive(profileId, sinceSeq))
+                return;
+            if (generation !== undefined)
+                this.generations.set(profileId, generation);
+            this.stopped.delete(profileId); // reconcile = server desires it running
+            // forceStatusReport: pending-row reconnect recovery must re-ACK `running` even if
+            // the dedup marker already says running (else the server stays stuck at pending).
+            await this.manager(profileId).ensureRuntime(profileId, opts);
+        }));
+    }
+    /** Lifecycle `open` — open (or reuse) the profile's start tab. `sinceSeq`: see ensureRuntime. */
+    openProfile(profileId, startUrl, sinceSeq, generation) {
+        return this.enqueue(profileId, () => this.runWithGeneration(profileId, generation, async () => {
+            if (this.isStaleRevive(profileId, sinceSeq))
+                return;
+            if (generation !== undefined)
+                this.generations.set(profileId, generation);
+            this.stopped.delete(profileId); // explicit open revives a stopped profile
+            await this.manager(profileId).openProfile(profileId, startUrl);
+        }));
+    }
+    /** True if a newer stop was observed after this revive captured `sinceSeq`. */
+    isStaleRevive(profileId, sinceSeq) {
+        if (sinceSeq === undefined || this.stopSeqOf(profileId) === sinceSeq)
+            return false;
+        this.opts.log.info(`browser profile ${profileId}: skipping stale revive (newer stop observed since enqueue)`);
+        return true;
+    }
+    /** Live-viewer control command for a profile — routed to its own daemon/streamer. */
+    handleViewerCommand(profileId, sessionId, command, input, turn) {
+        return this.enqueue(profileId, () => {
+            // Reject viewer commands on a fenced (stopped/reset) profile. A stale
+            // command — queued to the machine before the stop, delivered after — is
+            // indistinguishable from a fresh takeover here, and the server has already
+            // moved the profile to stopped; reviving it would resurrect a Chromium with
+            // the server still reading stopped. A real takeover goes through an explicit
+            // lifecycle reopen (open), which clears the fence and updates server status.
+            if (this.stopped.has(profileId)) {
+                throw new Error(`browser profile ${profileId} is stopped; reopen it before viewing`);
+            }
+            return this.manager(profileId).handleViewerCommand(profileId, sessionId, command, input, turn);
+        });
+    }
+    /**
+     * Lifecycle `stop` (explicit, owner-driven) — stop the profile's viewer + tear
+     * down its bb-browser daemon and Chromium to free the resources (an idle profile
+     * must not keep a browser running). Confirms `stopped` back to the server: the
+     * stop API already set the server row to `stopped`, and this report keeps the
+     * daemon authoritative over the actual runtime state (the no-runtime case still
+     * confirms). For reconcile-driven cleanup of profiles the server no longer owns
+     * here, use {@link releaseRuntime} — it must NOT report.
+     */
+    stopProfile(profileId, generation) {
+        return this.enqueue(profileId, () => this.runWithGeneration(profileId, generation, async () => {
+            // Already fenced by the WS pre-fence (fence() bumped the generation for this
+            // event); only ensure the fence here — do NOT bump again, or a newer open
+            // that captured its seq AFTER the pre-fence would look stale and be dropped.
+            this.stopped.add(profileId);
+            if (generation !== undefined)
+                this.generations.set(profileId, generation);
+            const manager = this.managers.get(profileId);
+            if (!manager) {
+                // Direct report (no manager wrapper to inject the generation) — pass it.
+                this.opts.reportStatus?.(profileId, 'stopped', undefined, generation);
+                return;
+            }
+            try {
+                await manager.stopProfile(profileId); // reports `stopped` (via wrapper), kills viewer
+            }
+            finally {
+                await this.dispose(profileId, manager); // release the bb-browser daemon + Chromium
+            }
+        }));
+    }
+    /**
+     * Reconcile teardown (negative convergence) — release a local runtime the server
+     * no longer lists as live on this machine (stopped / deleted / reassigned).
+     * Fences + disposes like a stop, but does NOT report status: here the server is
+     * the desired-state SSOT, so a daemon-side `stopped` push is semantically wrong
+     * (for a profile reassigned to another machine it isn't ours to report — the
+     * server's machine-binding check rejects it as 404 anyway) and only emits
+     * spurious calls. Local-only cleanup.
+     */
+    releaseRuntime(profileId) {
+        return this.enqueue(profileId, async () => {
+            // Pre-fenced by the reconcile at enqueue (fence() bumped the generation);
+            // only ensure the fence here — don't bump, or a reopen requested after the
+            // reconcile decision but before this runs would be dropped as stale.
+            this.stopped.add(profileId);
+            const manager = this.managers.get(profileId);
+            if (manager)
+                await this.dispose(profileId, manager);
+        });
+    }
+    /**
+     * Synchronously fence a profile (reject late invoke/viewer until an explicit
+     * reopen) WITHOUT tearing anything down. The supervisor calls this the moment a
+     * stop/reset lifecycle event is received, before the queued stop/reset op runs:
+     * a hub invoke — which bypasses the supervisor queue and hits {@link invoke}
+     * directly — authorized just before the server row flipped to `stopped` could
+     * otherwise arrive in that window and spawn a transient Chromium the stop then
+     * immediately tears down. Fencing now rejects it instead. An in-flight invoke
+     * already past the fence check is unaffected (the queued stop serializes behind
+     * it); open/ensure clears the fence. Idempotent; no-op once stopping.
+     */
+    fence(profileId) {
+        if (this.stopping)
+            return;
+        this.stopped.add(profileId);
+        // SINGLE generation-bump point. Every path that decides to stop/reset/release
+        // a profile calls fence() the moment it OBSERVES the intent (WS event receipt /
+        // reconcile enqueue) — synchronously, before queuing the teardown op — so a
+        // revive (open/ensureRuntime) that captures the generation afterward sees the
+        // new value and isn't dropped as stale. Queued teardown ops only ensure the
+        // fence (stopped.add); they never bump, or a reopen requested between observe
+        // and execute would be stranded at stopped.
+        this.stopSeq.set(profileId, (this.stopSeq.get(profileId) ?? 0) + 1);
+    }
+    /** The current fence generation for a profile — captured by a revive at enqueue. */
+    stopSeqOf(profileId) {
+        return this.stopSeq.get(profileId) ?? 0;
+    }
+    /**
+     * Lifecycle `reset` — wipe the profile's persisted state (cookies, localStorage,
+     * IndexedDB, cache) for a clean slate. Removes BOTH the per-profile home AND any
+     * unmigrated legacy flat cookie file — a reset done before the profile's first
+     * post-upgrade open would otherwise leave the legacy file in place, and the lazy
+     * migration would re-import the old login on the next open, silently undoing the
+     * reset. Done AFTER the daemon is stopped so Chromium has released its files.
+     * Isolated by construction — it can never touch another profile's state.
+     * Fail-closed: if the wipe fails (e.g. Chromium still holds a file, or a
+     * permission error), report `error` and throw rather than report `stopped` —
+     * a reset that left state on disk must not be marked clean, since the next open
+     * could restore the old login. Reports `stopped` only on a confirmed wipe.
+     */
+    resetProfile(profileId, generation, resetGeneration) {
+        return this.enqueue(profileId, () => this.runWithGeneration(profileId, generation, async () => {
+            if (generation !== undefined)
+                this.generations.set(profileId, generation);
+            try {
+                // Wipe + record the applied reset_generation (so a reconnect won't re-wipe).
+                await this.doResetWipe(profileId, resetGeneration);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                this.opts.reportStatus?.(profileId, 'error', message, generation);
+                throw err;
+            }
+            this.opts.reportStatus?.(profileId, 'stopped', undefined, generation);
+        }));
+    }
+    /**
+     * Apply a reset the daemon hasn't yet (caught on reconnect when the server's
+     * reset_generation is newer than this daemon's recorded one). Same wipe as
+     * resetProfile but WITHOUT a status report — the caller drives desired state (an
+     * open/ensure reports running for a still-desired profile; a stopped profile is
+     * left stopped). Must run BEFORE any open/ensure for the profile so a reopen starts
+     * from clean state, never the old cookies (the supervisor enqueues it first).
+     */
+    applyResetWipe(profileId, resetGeneration) {
+        return this.enqueue(profileId, () => this.doResetWipe(profileId, resetGeneration));
+    }
+    // Core reset wipe (runs inside an enqueue closure): fence, dispose the runtime, wipe
+    // the home, THEN record the applied reset_generation — strictly in that order, so the
+    // sidecar is written only after a successful wipe (a crash in between just re-wipes,
+    // idempotent). removeProfileState throws on failure → reset_generation NOT recorded.
+    async doResetWipe(profileId, resetGeneration) {
+        this.stopped.add(profileId); // fence late invokes until an explicit reopen
+        const manager = this.managers.get(profileId);
+        if (manager)
+            await this.dispose(profileId, manager);
+        this.removeProfileState(profileId);
+        if (resetGeneration !== undefined)
+            this.writeResetGeneration(profileId, resetGeneration);
+    }
+    /**
+     * Reconnect cleanup for a profile the server no longer lists AT ALL (deleted or
+     * reassigned away): dispose any runtime and wipe the per-profile home — the old host
+     * must not keep its cookies/storage. NO status report (the server is the SSOT and the
+     * row is gone there); fences too. Idempotent (a wiped home simply isn't found again).
+     */
+    wipeAbsent(profileId) {
+        return this.enqueue(profileId, async () => {
+            this.stopped.add(profileId);
+            const manager = this.managers.get(profileId);
+            if (manager)
+                await this.dispose(profileId, manager);
+            this.removeProfileState(profileId);
+        });
+    }
+    /**
+     * Tear down every profile's daemon (supervisor shutdown). TERMINAL: the
+     * supervisor discards the pool after this, so `stopping` stays set forever —
+     * manager() refuses any further op. Drain outstanding per-profile chains BEFORE
+     * clearing the maps, so a queued op whose `prev` settles only after stop()
+     * returns can't slip through manager() and recreate a runtime (orphaning a
+     * Chromium past shutdown); `stopping` is the backstop if one still races in.
+     */
+    async stop() {
+        this.stopping = true;
+        await Promise.allSettled([...this.opChains.values()]);
+        const managers = [...this.managers.values()];
+        this.managers.clear();
+        this.opChains.clear();
+        this.stopped.clear();
+        // allSettled (not all): one manager's stop() throwing must not skip tearing
+        // down the rest — every Chromium has to be released. (Bounded: each stop()
+        // awaits waitForChildExit, which has a hard cap.)
+        await Promise.allSettled(managers.map((m) => m.stop()));
+    }
+    /**
+     * Registry view: profile ids that currently hold a live local runtime. The
+     * supervisor (the desired-state coordinator) diffs this against the server's
+     * desired-live set on full reconcile and stops the extras via stopProfile() —
+     * the convergence policy lives there, not here; the pool only owns runtime
+     * lifecycle mechanics.
+     */
+    activeProfileIds() {
+        return [...this.managers.keys()];
+    }
+    /**
+     * Run `op` after every prior operation for this profile settles — a per-profile
+     * serialization so invoke / open / stop / reset / viewer never interleave for
+     * one profile (different profiles still run in parallel). Bounded: bb-browser
+     * commands time out (~30s), so a stop never waits forever behind a hung invoke.
+     * Also normalizes a synchronous throw from `op` into a rejected promise.
+     *
+     * QUEUE CONTRACT. This is the FINAL per-profile mutex — EVERY pool entrypoint
+     * (invoke, open, ensure, stop, reset, viewer) goes through it, so it alone
+     * guarantees per-profile mutual exclusion. The supervisor's separate
+     * `enqueueBrowserProfileOp` is a higher-level ORDERING layer for the ops it
+     * originates (WS lifecycle/viewer events + reconcile), not a second mutex. Hub
+     * invokes arrive from the clip runtime and do NOT pass through the supervisor
+     * queue — only this one. So: do not assume "all profile ops share one queue";
+     * they share THIS one.
+     */
+    enqueue(profileId, op) {
+        // Reject new work once teardown has begun, so a stop-time invoke/open/viewer
+        // never queues or spawns a runtime (the manager() guard backstops any op
+        // already queued whose closure runs after the maps are cleared).
+        if (this.stopping) {
+            return Promise.reject(new Error('browser profile pool is stopping'));
+        }
+        const prev = this.opChains.get(profileId) ?? Promise.resolve();
+        const run = prev.then(op, op); // run op whether the prior op fulfilled or rejected
+        this.opChains.set(profileId, run);
+        void run
+            .catch(() => { })
+            .finally(() => {
+            if (this.opChains.get(profileId) === run)
+                this.opChains.delete(profileId);
+        });
+        return run;
+    }
+    /**
+     * Get (or lazily create) the dedicated manager for a profile. Synchronous so the
+     * get-or-create is atomic — the bb-browser daemon itself starts lazily on first
+     * command, not here.
+     */
+    manager(profileId) {
+        if (!profileId)
+            throw new Error('browser profile id is required');
+        // During teardown, refuse any op so it can't spawn/use a manager that would
+        // escape stop() (which clears the maps mid-flight). See `stopping`.
+        if (this.stopping)
+            throw new Error('browser profile pool is stopping');
+        let manager = this.managers.get(profileId);
+        if (manager)
+            return manager;
+        this.migrateFlatProfileState(profileId);
+        const create = this.opts.createManager ?? ((opts) => new BrowserProfileManager(opts));
+        manager = create({
+            homeDir: this.profileHome(profileId),
+            log: this.opts.log,
+            // The manager reports with 3 args; inject the current op's generation so the
+            // server can fence stale reports. opGeneration is set for the duration of each
+            // serialized op (see runWithGeneration), so this reads THIS op's captured
+            // generation, not a live value a concurrent stop could have moved.
+            reportStatus: (id, status, errorMsg) => this.opts.reportStatus?.(id, status, errorMsg, this.opGeneration.get(id)),
+            // Thread the per-profile outbound proxy resolver through to this profile's own
+            // manager, so each isolated Chromium binds its own egress proxy at
+            // account_create (the resolver is keyed by profileId === account).
+            resolveProxy: this.opts.resolveProxy,
+        });
+        this.managers.set(profileId, manager);
+        return manager;
+    }
+    /** Stop a manager and drop it from the map (identity-checked so a concurrent
+     *  recreate during the async stop is never evicted). */
+    async dispose(profileId, manager) {
+        try {
+            await manager.stop();
+        }
+        finally {
+            if (this.managers.get(profileId) === manager)
+                this.managers.delete(profileId);
+        }
+    }
+    profileHome(profileId) {
+        return path.join(this.opts.baseHomeDir, sanitizeProfileId(profileId));
+    }
+    /** Legacy shared-layout cookie file for a profile (pre per-profile homes). */
+    legacyAccountFile(profileId) {
+        return path.join(this.opts.baseHomeDir, 'accounts', `${sanitizeProfileId(profileId)}.json`);
+    }
+    /**
+     * Remove every on-disk trace of a profile: its per-profile home AND any
+     * unmigrated legacy flat cookie file — otherwise a later open would re-import
+     * the legacy cookies (see resetProfile). Throws if any target could not be
+     * removed so the caller can fail the reset closed rather than report a clean
+     * slate while state survives on disk.
+     */
+    removeProfileState(profileId) {
+        const failures = [];
+        for (const target of [this.profileHome(profileId), this.legacyAccountFile(profileId)]) {
+            try {
+                rmSync(target, { recursive: true, force: true });
+            }
+            catch (err) {
+                failures.push(`${target}: ${String(err)}`);
+            }
+        }
+        if (failures.length > 0) {
+            throw new Error(`could not remove profile state for ${profileId} — ${failures.join('; ')}`);
+        }
+    }
+    // --- per-profile reset sidecar: the last reset_generation this daemon APPLIED ---
+    // A tiny JSON file inside the profile home, so removeProfileState() clears it with
+    // the rest of the state. On reconnect the reconcile compares the server's
+    // reset_generation to this value: a newer server value means a reset was missed
+    // while offline → wipe. Missing/corrupt reads as 0 (so any server reset wins).
+    metaFile(profileId) {
+        return path.join(this.profileHome(profileId), '.parall-profile-meta.json');
+    }
+    /** The reset_generation this daemon has applied for the profile (0 if unknown). */
+    appliedResetGeneration(profileId) {
+        try {
+            const parsed = JSON.parse(readFileSync(this.metaFile(profileId), 'utf8'));
+            const gen = parsed.reset_generation;
+            return typeof gen === 'number' && Number.isFinite(gen) ? gen : 0;
+        }
+        catch {
+            return 0; // missing or corrupt → treat as never-applied (re-wipe if server is newer)
+        }
+    }
+    // Record the applied reset_generation atomically (temp file + rename). Called ONLY
+    // after a successful wipe, so a crash before the rename just leaves the daemon to
+    // re-wipe on the next reconcile (idempotent) rather than skipping a real reset.
+    writeResetGeneration(profileId, generation) {
+        const home = this.profileHome(profileId);
+        mkdirSync(home, { recursive: true });
+        const tmp = path.join(home, `.parall-profile-meta.json.tmp-${process.pid}`);
+        writeFileSync(tmp, JSON.stringify({ reset_generation: generation }));
+        renameSync(tmp, this.metaFile(profileId));
+    }
+    /**
+     * Profile ids that have ANY local state on this host — the reconcile's inventory for
+     * finding deleted/reassigned profiles whose residue must be wiped. Union of the two
+     * storage layouts this pool owns:
+     *   - per-profile home dirs      `<baseHomeDir>/brp_*`
+     *   - legacy flat account files  `<baseHomeDir>/accounts/brp_*.json` (pre per-profile
+     *     homes; a profile deleted before its first post-upgrade reopen has ONLY this file
+     *     and no home dir, so home-only enumeration would miss its login residue)
+     * Only names passing the strict brp_ check are returned, and the two layouts are
+     * deduped, so reconnect cleanup never touches the `accounts/` dir itself, a hidden
+     * dir, `legacy.json`, or any non-profile entry. removeProfileState wipes both layouts.
+     */
+    localStateProfileIds() {
+        const ids = new Set();
+        try {
+            for (const e of readdirSync(this.opts.baseHomeDir, { withFileTypes: true })) {
+                if (e.isDirectory() && isSafeProfileId(e.name))
+                    ids.add(e.name);
+            }
+        }
+        catch {
+            // baseHomeDir missing → no per-profile home state
+        }
+        try {
+            const accountsDir = path.join(this.opts.baseHomeDir, 'accounts');
+            for (const e of readdirSync(accountsDir, { withFileTypes: true })) {
+                if (!e.isFile() || !e.name.endsWith('.json'))
+                    continue;
+                const id = e.name.slice(0, -'.json'.length);
+                if (isSafeProfileId(id))
+                    ids.add(id);
+            }
+        }
+        catch {
+            // no legacy accounts/ dir → no flat account state
+        }
+        return [...ids];
+    }
+    /**
+     * One-time, lazy migration from the legacy shared layout. Before per-profile
+     * homes, all profiles shared one bb-browser home and bb-browser persisted each
+     * profile's cookies to `<baseHomeDir>/accounts/<profileId>.json` (account name =
+     * profileId). Move that file into the profile's own `accounts/` dir on first use
+     * so existing cookie logins survive the upgrade instead of forcing a re-login.
+     * Only cookies are migrated — the shared `chrome-data/` was a single comingled
+     * Chromium profile that cannot be split per profile, and bb-browser never
+     * persisted localStorage/IndexedDB across restarts anyway.
+     */
+    migrateFlatProfileState(profileId) {
+        const legacy = this.legacyAccountFile(profileId);
+        if (!existsSync(legacy))
+            return;
+        const destDir = path.join(this.profileHome(profileId), 'accounts');
+        const dest = path.join(destDir, path.basename(legacy));
+        if (existsSync(dest))
+            return; // already migrated (or a fresh per-profile file exists)
+        try {
+            mkdirSync(destDir, { recursive: true });
+            renameSync(legacy, dest);
+            this.opts.log.info(`[bb-browser] migrated cookie state for ${profileId} to per-profile home`);
+        }
+        catch (err) {
+            // error-level (not warn): a visible data-loss event — the profile's
+            // pre-upgrade login is lost and it starts fresh (re-login required). Stays
+            // fail-open (the profile still works); we do NOT reportStatus('error'), which
+            // has no "running-but-degraded" state and would wrongly block a working
+            // profile — the operator-visible signal is this log.
+            this.opts.log.error(`[bb-browser] cookie-state migration FAILED for ${profileId}; profile will start without its prior login (re-login required): ${String(err)}`);
+        }
+    }
+}
+/**
+ * Validate a profile id as the real browser-profile form (`brp_` + nanoid,
+ * alphabet `[A-Za-z0-9_-]`) and return it unchanged. Require the `brp_` prefix, not
+ * just a safe charset: a bare safe name like `accounts` would make
+ * `profileHome('accounts')` collide with the legacy flat `<baseHomeDir>/accounts`
+ * cookie dir, and folding (e.g. `a/b` → `a_b`) could alias two distinct ids onto
+ * one home while `managers` keys them separately — both silently collapse the very
+ * isolation this pool exists to enforce. Anything else is **rejected, not
+ * rewritten** (empty / `.` / `..` / path separators / reserved names all fail).
+ */
+/** True for a server-generated browser profile id (`brp_` + nanoid alphabet). */
+function isSafeProfileId(id) {
+    return /^brp_[A-Za-z0-9_-]+$/.test(id);
+}
+function sanitizeProfileId(profileId) {
+    if (!isSafeProfileId(profileId)) {
+        throw new Error(`unsafe browser profile id: ${JSON.stringify(profileId)}`);
+    }
+    return profileId;
+}

package/dist/clip-runtime/index.d.ts

@@ -4,6 +4,7 @@ export { type IpcMessage, type IpcManifest, type ListClipInfo, type ListCommandI
 export { type ClipConfig, type ManifestCache, type CommandDetail, type ClipJson, } from './manifest.js';
 export { ClipProvider, type ClipProviderOptions } from './clip-provider.js';
 export { HubClient, HubCommandError, type HubClientOptions, type ClipBinding, } from './hub-client.js';
-export { BrowserProfileManager } from './browser-profile-manager.js';
+export { BrowserProfileManager, type BrowserInvoker, type BrowserInvokeRequest, type BrowserProxyConfig, } from './browser-profile-manager.js';
+export { BrowserProfilePool, type BrowserProfilePoolOptions } from './browser-profile-pool.js';
 export { installClip, removeClip, parseSource, type InstallOptions, type InstallResult, } from './clip-installer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/clip-runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,SAAS,EACT,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,SAAS,EACT,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC/F,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/clip-runtime/index.js

@@ -3,5 +3,6 @@ export { ClipProcess, ClipCommandError, } from './process.js';
 export { MessageType, NdjsonReader, NdjsonWriter, } from './ipc.js';
 export { ClipProvider } from './clip-provider.js';
 export { HubClient, HubCommandError, } from './hub-client.js';
-export { BrowserProfileManager } from './browser-profile-manager.js';
+export { BrowserProfileManager, } from './browser-profile-manager.js';
+export { BrowserProfilePool } from './browser-profile-pool.js';
 export { installClip, removeClip, parseSource, } from './clip-installer.js';

package/dist/clip-runtime/process-manager.d.ts

@@ -1,6 +1,6 @@
 import { type ClipInvokeContext, type ClipProcessStatus } from './process.js';
 import type { ClipConfig, ManifestCache } from './manifest.js';
-import type { BrowserProfileManager } from './browser-profile-manager.js';
+import type { BrowserInvoker } from './browser-profile-manager.js';
 import { type HubClient } from './hub-client.js';
 export interface ClipProcessManagerOptions {
     bunPath?: string;
@@ -10,9 +10,11 @@ export interface ClipProcessManagerOptions {
      * Host-side browser runtime. Present only on daemons that can host a
      * BrowserProfile; drives inbound hub browser InvokeCommands. The execution
      * side never calls this directly — nested browser invokes go out through the
-     * hub (see hubClient).
+     * hub (see hubClient). Typed as the narrow {@link BrowserInvoker} so either a
+     * single BrowserProfileManager (hosted browser pod) or a BrowserProfilePool
+     * (BYOC supervisor, one bb-browser per profile) can back it.
      */
-    browserProfileManager?: BrowserProfileManager;
+    browserProfileManager?: BrowserInvoker;
     /**
      * Lazily-supplied hub client used by the execution side to resolve a
      * dependency binding (GetBindings) and forward the dependency invoke

package/dist/clip-runtime/process-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/process-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/process-manager.ts"],"names":[],"mappings":"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"}