@parall/daemon 1.35.0 → 1.36.0

package/dist/clip-runtime/browser-state-store.d.ts

@@ -0,0 +1,157 @@
+/**
+ * browser-state-store.ts — S3 externalization of a hosted browser profile's
+ * bb-browser state (design hosted-browser-multitenant §3.2, PR4).
+ *
+ * A hosted browser pod is ephemeral: its Chromium user-data dir (BB_BROWSER_HOME /
+ * `homeDir`, where cookies / localStorage / IndexedDB persist) lives on a pod
+ * `emptyDir` that vanishes on restart. To make the profile durable across pod
+ * restarts we snapshot that dir to S3, so a pod HYDRATES on start and CHECKPOINTS
+ * periodically + on drain. Layout (SSOT shared with the Go controller's
+ * state_store.go): `s3://{bucket}/browser-state/{org_id}/{profile_id}/state.tgz`.
+ *
+ * Correctness under pod churn (the hard part):
+ *   - Integrity: each object carries a sha256 + the generation in metadata. Hydrate
+ *     verifies the checksum; a mismatch is treated as "no state" (start fresh),
+ *     never a crash.
+ *   - Fencing (anti-clobber): a stale/fenced pod (older activation generation) must
+ *     NOT overwrite a newer pod's state. checkpoint() reads the current object's
+ *     generation; if it is newer than ours we abort. The write is additionally a
+ *     conditional PUT (IfMatch on the read ETag / IfNoneMatch on create) so a CAS
+ *     race fails closed (412 → abort).
+ *
+ * Graceful degradation: with no bucket configured (feature not provisioned) the
+ * store is DISABLED — hydrate/checkpoint are no-ops and the pod runs stateless.
+ * Read/credential failures never crash the pod; they degrade to "fresh start" on
+ * hydrate and "checkpoint failed" (logged) on write. Durability is best-effort +
+ * on-close (design §3.2 "simplified durability"): a failed checkpoint is bounded
+ * loss (the delta since the last successful checkpoint), logged at the pod — there
+ * is no controller-side final-checkpoint verify or auto-repair.
+ *
+ * This module is imported ONLY by the browser-pod entrypoint, so @aws-sdk/client-s3
+ * lands only in the parall-browser-pod bundle, never the BYOC daemon bundle.
+ */
+export interface BrowserStateLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** buildStateKey is the SSOT key layout, mirrored by the Go controller. */
+export declare function buildStateKey(orgId: string, profileId: string): string;
+/** Thrown by a StateBackend.put when a conditional write precondition fails (S3
+ *  412). The store treats it as "lost the CAS race" and aborts the checkpoint. */
+export declare class PreconditionFailedError extends Error {
+    constructor(message?: string);
+}
+export interface HeadResult {
+    etag: string;
+    metadata: Record<string, string>;
+}
+/**
+ * StateBackend is the narrow object-store surface the store needs, so the CAS +
+ * checksum logic is unit-testable against an in-memory fake without the real SDK.
+ * S3Backend is the live implementation.
+ */
+export interface StateBackend {
+    /** Returns object metadata + ETag, or null when the object does not exist. */
+    head(key: string): Promise<HeadResult | null>;
+    get(key: string): Promise<Buffer>;
+    /** Conditional write: throws PreconditionFailedError on a 412. */
+    put(key: string, body: Buffer, opts: {
+        metadata: Record<string, string>;
+        ifMatch?: string;
+        ifNoneMatch?: string;
+    }): Promise<void>;
+}
+export interface BrowserStateStoreConfig {
+    bucket: string;
+    region: string;
+    orgId: string;
+    profileId: string;
+    /** Lease activation generation — the monotonic fencing token (design §3.2). */
+    generation: number;
+    /** bb-browser user-data dir (BB_BROWSER_HOME) to snapshot/restore. */
+    homeDir: string;
+    /** Optional S3 endpoint (MinIO/dev); empty → AWS S3. */
+    endpoint?: string;
+    log: BrowserStateLogger;
+}
+export interface CheckpointResult {
+    ok: boolean;
+    /** skipped because the store is disabled. */
+    disabled?: boolean;
+    /** aborted: a newer generation already holds the object (we are fenced). */
+    fenced?: boolean;
+    /** aborted: conditional-write CAS race (another writer won). */
+    raced?: boolean;
+    /** skipped: a periodic checkpoint whose content is unchanged since the last upload. */
+    unchanged?: boolean;
+    error?: unknown;
+}
+export interface HydrateResult {
+    hydrated: boolean;
+    disabled?: boolean;
+    checksumMismatch?: boolean;
+    error?: unknown;
+}
+/**
+ * BrowserStateStore orchestrates hydrate/checkpoint over a StateBackend. All
+ * checkpoints (periodic + final) are serialized through a single promise chain so
+ * a drain's final checkpoint can never race an in-flight periodic one.
+ */
+export declare class BrowserStateStore {
+    private readonly cfg;
+    private readonly backend;
+    private readonly key;
+    private chain;
+    private lastUploadedSha;
+    constructor(cfg: BrowserStateStoreConfig, backend?: StateBackend);
+    enabled(): boolean;
+    /**
+     * Download + verify + extract the profile's snapshot into homeDir. MUST run
+     * before bb-browser can launch (the pod calls it at startup, before the provider
+     * stream opens). Never throws: any failure (no object, checksum mismatch,
+     * network/cred error) degrades to a fresh start, since a read failure should not
+     * keep the browser from coming up.
+     */
+    hydrate(): Promise<HydrateResult>;
+    /**
+     * Snapshot homeDir to S3. `final` marks the drain (on-close) checkpoint — the
+     * last best-effort flush before the pod exits. Serialized via the chain so
+     * periodic and final checkpoints never overlap. Never throws — returns a result
+     * the caller logs; a failure is bounded loss, not enforced (simplified durability:
+     * no controller-side verify or auto-repair).
+     */
+    checkpoint(opts: {
+        final: boolean;
+    }): Promise<CheckpointResult>;
+    private doCheckpoint;
+}
+/** sha256 hex of a buffer — the snapshot integrity checksum. */
+export declare function sha256(buf: Buffer): string;
+/**
+ * archiveDir tars a directory (excluding lock/cache cruft) then gzips it in-memory.
+ * Uses the system `tar` (present in the browser-docker image and on dev machines —
+ * no extra npm dep) for the tar, and node:zlib for gzip. Gzip is done by zlib (not
+ * `tar -z`) deliberately: zlib's gzip header has a zeroed mtime, so identical
+ * directory content produces byte-identical archives — which lets a periodic
+ * checkpoint skip a redundant upload when nothing changed. Buffering in memory is
+ * fine for browser state (cookies/localStorage/IndexedDB are small); streaming
+ * multipart upload is a fast-follow if profiles grow large.
+ */
+export declare function archiveDir(dir: string): Promise<Buffer>;
+/** extractArchive ungzips then untars a buffer into destDir (created if missing). */
+export declare function extractArchive(buf: Buffer, destDir: string): Promise<void>;
+/**
+ * A 403 from HeadObject. A profile-scoped pod deliberately lacks s3:ListBucket (the
+ * per-profile tenant-isolation boundary), and S3 answers a MISSING object with 403
+ * (not 404) when the caller can't list the bucket — it won't reveal existence. The
+ * pod still holds s3:GetObject on its own prefix, so an existing object HEADs as 200;
+ * a 403 there therefore means "no object", not a real denial. Treating it as
+ * not-found lets a brand-new profile hydrate fresh AND still checkpoint. This can
+ * never overwrite good state: an existing object never 403s (it 200s), and a
+ * genuinely bad/expired credential 403s the subsequent PutObject too, so the
+ * checkpoint fails — bounded loss, logged at the pod (simplified durability: no
+ * controller-side verify or auto-repair).
+ */
+export declare function isAccessDenied(err: unknown): boolean;
+//# sourceMappingURL=browser-state-store.d.ts.map

package/dist/clip-runtime/browser-state-store.d.ts.map

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

package/dist/clip-runtime/browser-state-store.js

@@ -0,0 +1,370 @@
+/**
+ * browser-state-store.ts — S3 externalization of a hosted browser profile's
+ * bb-browser state (design hosted-browser-multitenant §3.2, PR4).
+ *
+ * A hosted browser pod is ephemeral: its Chromium user-data dir (BB_BROWSER_HOME /
+ * `homeDir`, where cookies / localStorage / IndexedDB persist) lives on a pod
+ * `emptyDir` that vanishes on restart. To make the profile durable across pod
+ * restarts we snapshot that dir to S3, so a pod HYDRATES on start and CHECKPOINTS
+ * periodically + on drain. Layout (SSOT shared with the Go controller's
+ * state_store.go): `s3://{bucket}/browser-state/{org_id}/{profile_id}/state.tgz`.
+ *
+ * Correctness under pod churn (the hard part):
+ *   - Integrity: each object carries a sha256 + the generation in metadata. Hydrate
+ *     verifies the checksum; a mismatch is treated as "no state" (start fresh),
+ *     never a crash.
+ *   - Fencing (anti-clobber): a stale/fenced pod (older activation generation) must
+ *     NOT overwrite a newer pod's state. checkpoint() reads the current object's
+ *     generation; if it is newer than ours we abort. The write is additionally a
+ *     conditional PUT (IfMatch on the read ETag / IfNoneMatch on create) so a CAS
+ *     race fails closed (412 → abort).
+ *
+ * Graceful degradation: with no bucket configured (feature not provisioned) the
+ * store is DISABLED — hydrate/checkpoint are no-ops and the pod runs stateless.
+ * Read/credential failures never crash the pod; they degrade to "fresh start" on
+ * hydrate and "checkpoint failed" (logged) on write. Durability is best-effort +
+ * on-close (design §3.2 "simplified durability"): a failed checkpoint is bounded
+ * loss (the delta since the last successful checkpoint), logged at the pod — there
+ * is no controller-side final-checkpoint verify or auto-repair.
+ *
+ * This module is imported ONLY by the browser-pod entrypoint, so @aws-sdk/client-s3
+ * lands only in the parall-browser-pod bundle, never the BYOC daemon bundle.
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+/** S3 object user-metadata keys. Lowercase; the Go controller reads them
+ *  case-insensitively (state_store.go metaValue). SSOT — keep in lockstep. */
+const META_GENERATION = 'generation';
+const META_SHA256 = 'sha256';
+const META_FINAL = 'final';
+const STATE_KEY_PREFIX = 'browser-state';
+const STATE_OBJECT = 'state.tgz';
+/**
+ * Chromium user-data cruft excluded from the snapshot: singleton locks (must never
+ * be restored — Chrome recreates them, and a stale lock blocks startup) and
+ * regenerable caches (large, never login state). Login state — Cookies, Local
+ * Storage, IndexedDB, Local State, Login Data — is deliberately NOT excluded.
+ */
+const ARCHIVE_EXCLUDES = [
+    'SingletonLock',
+    'SingletonCookie',
+    'SingletonSocket',
+    'lockfile',
+    '*/Cache/*',
+    '*/Code Cache/*',
+    '*/GPUCache/*',
+    '*/ShaderCache/*',
+    '*/GrShaderCache/*',
+    '*/DawnCache/*',
+    '*/component_crx_cache/*',
+    '*/Crashpad/*',
+];
+/** buildStateKey is the SSOT key layout, mirrored by the Go controller. */
+export function buildStateKey(orgId, profileId) {
+    return `${STATE_KEY_PREFIX}/${orgId}/${profileId}/${STATE_OBJECT}`;
+}
+/** Thrown by a StateBackend.put when a conditional write precondition fails (S3
+ *  412). The store treats it as "lost the CAS race" and aborts the checkpoint. */
+export class PreconditionFailedError extends Error {
+    constructor(message = 'precondition failed') {
+        super(message);
+        this.name = 'PreconditionFailedError';
+    }
+}
+/**
+ * BrowserStateStore orchestrates hydrate/checkpoint over a StateBackend. All
+ * checkpoints (periodic + final) are serialized through a single promise chain so
+ * a drain's final checkpoint can never race an in-flight periodic one.
+ */
+export class BrowserStateStore {
+    cfg;
+    backend;
+    key;
+    chain = Promise.resolve();
+    lastUploadedSha = null;
+    constructor(cfg, backend) {
+        this.cfg = cfg;
+        this.key = buildStateKey(cfg.orgId, cfg.profileId);
+        // Injected backend wins (tests). Otherwise build a live S3 backend iff a
+        // bucket is configured; no bucket → disabled (stateless pod).
+        this.backend = backend ?? (cfg.bucket ? new S3Backend(buildS3Client(cfg), cfg.bucket) : null);
+    }
+    enabled() {
+        return this.backend !== null;
+    }
+    /**
+     * Download + verify + extract the profile's snapshot into homeDir. MUST run
+     * before bb-browser can launch (the pod calls it at startup, before the provider
+     * stream opens). Never throws: any failure (no object, checksum mismatch,
+     * network/cred error) degrades to a fresh start, since a read failure should not
+     * keep the browser from coming up.
+     */
+    async hydrate() {
+        if (!this.backend) {
+            this.cfg.log.info('browser-state: disabled (no bucket) — fresh start, stateless');
+            return { hydrated: false, disabled: true };
+        }
+        try {
+            const head = await this.backend.head(this.key);
+            if (!head) {
+                this.cfg.log.info(`browser-state: no prior snapshot at ${this.key} — fresh start`);
+                return { hydrated: false };
+            }
+            const buf = await this.backend.get(this.key);
+            const expected = head.metadata[META_SHA256];
+            const actual = sha256(buf);
+            if (!expected) {
+                // The object format REQUIRES a sha256 in metadata. A snapshot without it is
+                // unverifiable (corrupt / non-canonical / partial write) — do NOT extract
+                // unchecked content into homeDir. Treat as not-hydratable (fresh start) and,
+                // like a mismatch, do not overwrite the existing object (see
+                // shouldCheckpointAfterHydrate).
+                this.cfg.log.warn(`browser-state: snapshot at ${this.key} is missing the ${META_SHA256} metadata — cannot verify, ignoring snapshot, fresh start`);
+                return { hydrated: false, checksumMismatch: true };
+            }
+            if (expected !== actual) {
+                this.cfg.log.warn(`browser-state: checksum mismatch (expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…) — ignoring snapshot, fresh start`);
+                return { hydrated: false, checksumMismatch: true };
+            }
+            mkdirSync(this.cfg.homeDir, { recursive: true });
+            await extractArchive(buf, this.cfg.homeDir);
+            this.lastUploadedSha = actual;
+            this.cfg.log.info(`browser-state: hydrated ${buf.length} bytes from ${this.key} (gen=${head.metadata[META_GENERATION] ?? '?'})`);
+            return { hydrated: true };
+        }
+        catch (err) {
+            this.cfg.log.warn(`browser-state: hydrate failed, fresh start: ${errMsg(err)}`);
+            return { hydrated: false, error: err };
+        }
+    }
+    /**
+     * Snapshot homeDir to S3. `final` marks the drain (on-close) checkpoint — the
+     * last best-effort flush before the pod exits. Serialized via the chain so
+     * periodic and final checkpoints never overlap. Never throws — returns a result
+     * the caller logs; a failure is bounded loss, not enforced (simplified durability:
+     * no controller-side verify or auto-repair).
+     */
+    checkpoint(opts) {
+        const run = this.chain.then(() => this.doCheckpoint(opts));
+        // Keep the chain alive regardless of this checkpoint's outcome.
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async doCheckpoint({ final }) {
+        if (!this.backend)
+            return { ok: false, disabled: true };
+        try {
+            // Fencing read: if S3 already holds a NEWER generation, we are a stale/fenced
+            // pod and must not clobber it.
+            const head = await this.backend.head(this.key);
+            if (head) {
+                const currentGen = Number.parseInt(head.metadata[META_GENERATION] ?? '', 10);
+                if (Number.isFinite(currentGen) && currentGen > this.cfg.generation) {
+                    this.cfg.log.warn(`browser-state: FENCED — S3 generation ${currentGen} > ours ${this.cfg.generation}; aborting checkpoint (this pod is superseded)`);
+                    return { ok: false, fenced: true };
+                }
+            }
+            const body = await archiveDir(this.cfg.homeDir);
+            const sha = sha256(body);
+            // Skip a redundant PERIODIC upload when nothing changed; a FINAL (drain)
+            // checkpoint always writes — the on-close flush is unconditional so the last
+            // state is guaranteed committed before the pod exits, even if the bytes match
+            // the last periodic upload. (The `final` metadata marker is informational only:
+            // under simplified durability nothing reads it back — there is no controller-
+            // side release-time guard.)
+            if (!final && this.lastUploadedSha !== null && this.lastUploadedSha === sha) {
+                return { ok: true, unchanged: true };
+            }
+            const metadata = {
+                [META_GENERATION]: String(this.cfg.generation),
+                [META_SHA256]: sha,
+                [META_FINAL]: String(final),
+            };
+            try {
+                await this.backend.put(this.key, body, head ? { metadata, ifMatch: head.etag } : { metadata, ifNoneMatch: '*' });
+            }
+            catch (err) {
+                if (err instanceof PreconditionFailedError || isPreconditionFailed(err)) {
+                    this.cfg.log.warn('browser-state: checkpoint lost the conditional-write race (precondition failed); aborting — another pod holds the object');
+                    return { ok: false, raced: true };
+                }
+                throw err;
+            }
+            this.lastUploadedSha = sha;
+            this.cfg.log.info(`browser-state: checkpoint ok (gen=${this.cfg.generation} final=${final} bytes=${body.length})`);
+            return { ok: true };
+        }
+        catch (err) {
+            this.cfg.log.error(`browser-state: checkpoint failed: ${errMsg(err)}`);
+            return { ok: false, error: err };
+        }
+    }
+}
+/** S3Backend is the live StateBackend over @aws-sdk/client-s3. */
+class S3Backend {
+    client;
+    bucket;
+    constructor(client, bucket) {
+        this.client = client;
+        this.bucket = bucket;
+    }
+    async head(key) {
+        try {
+            const r = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return { etag: r.ETag ?? '', metadata: lowerKeys(r.Metadata ?? {}) };
+        }
+        catch (err) {
+            // A profile-scoped pod has no s3:ListBucket, so S3 answers a missing object
+            // with 403 rather than 404. Treat both as "no object" — see isAccessDenied.
+            if (isNotFound(err) || isAccessDenied(err))
+                return null;
+            throw err;
+        }
+    }
+    async get(key) {
+        const r = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+        const body = r.Body;
+        if (!body?.transformToByteArray) {
+            throw new Error('S3 GetObject returned no readable body');
+        }
+        return Buffer.from(await body.transformToByteArray());
+    }
+    async put(key, body, opts) {
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+                Body: body,
+                Metadata: opts.metadata,
+                ContentType: 'application/gzip',
+                // Server-side encryption (design §3.2). SSE-S3 (AES256) is universally
+                // available on AWS; bucket default encryption makes this explicit, not
+                // conflicting.
+                ServerSideEncryption: 'AES256',
+                ...(opts.ifMatch ? { IfMatch: opts.ifMatch } : {}),
+                ...(opts.ifNoneMatch ? { IfNoneMatch: opts.ifNoneMatch } : {}),
+            }));
+        }
+        catch (err) {
+            if (isPreconditionFailed(err))
+                throw new PreconditionFailedError(errMsg(err));
+            throw err;
+        }
+    }
+}
+function buildS3Client(cfg) {
+    // Credentials come from the default provider chain — the controller injects
+    // short-lived, profile-scoped STS creds as AWS_* env. forcePathStyle is needed
+    // for MinIO/dev endpoints.
+    return new S3Client({
+        region: cfg.region || undefined,
+        ...(cfg.endpoint ? { endpoint: cfg.endpoint, forcePathStyle: true } : {}),
+    });
+}
+/** sha256 hex of a buffer — the snapshot integrity checksum. */
+export function sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * archiveDir tars a directory (excluding lock/cache cruft) then gzips it in-memory.
+ * Uses the system `tar` (present in the browser-docker image and on dev machines —
+ * no extra npm dep) for the tar, and node:zlib for gzip. Gzip is done by zlib (not
+ * `tar -z`) deliberately: zlib's gzip header has a zeroed mtime, so identical
+ * directory content produces byte-identical archives — which lets a periodic
+ * checkpoint skip a redundant upload when nothing changed. Buffering in memory is
+ * fine for browser state (cookies/localStorage/IndexedDB are small); streaming
+ * multipart upload is a fast-follow if profiles grow large.
+ */
+export async function archiveDir(dir) {
+    const args = ['-cf', '-', '-C', dir];
+    for (const ex of ARCHIVE_EXCLUDES)
+        args.push(`--exclude=${ex}`);
+    args.push('.');
+    const tar = await runTar(args, undefined);
+    return gzipSync(tar);
+}
+/** extractArchive ungzips then untars a buffer into destDir (created if missing). */
+export async function extractArchive(buf, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    await runTar(['-xf', '-', '-C', destDir], gunzipSync(buf));
+}
+/**
+ * runTar spawns the system tar, optionally feeding stdin, and resolves stdout as a
+ * Buffer. Rejects on spawn error or non-zero exit (with captured stderr) so a
+ * partial/failed archive can never be silently uploaded or extracted.
+ */
+function runTar(args, stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('tar', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        const out = [];
+        const errOut = [];
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        child.once('error', fail); // ENOENT (no tar) etc.
+        child.stdout.on('data', (c) => out.push(c));
+        child.stderr.on('data', (c) => errOut.push(c));
+        child.once('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (code === 0) {
+                resolve(Buffer.concat(out));
+            }
+            else {
+                reject(new Error(`tar exited ${code}: ${Buffer.concat(errOut).toString('utf8').trim()}`));
+            }
+        });
+        if (stdin !== undefined) {
+            child.stdin.on('error', fail); // EPIPE if tar dies early
+            child.stdin.end(stdin);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** Lowercase metadata keys so lookups are case-insensitive regardless of how the
+ *  SDK/backend canonicalizes them. */
+function lowerKeys(m) {
+    const out = {};
+    for (const [k, v] of Object.entries(m))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+/** A 404 from HeadObject/GetObject — the object does not exist. */
+function isNotFound(err) {
+    const e = err;
+    return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404;
+}
+/**
+ * A 403 from HeadObject. A profile-scoped pod deliberately lacks s3:ListBucket (the
+ * per-profile tenant-isolation boundary), and S3 answers a MISSING object with 403
+ * (not 404) when the caller can't list the bucket — it won't reveal existence. The
+ * pod still holds s3:GetObject on its own prefix, so an existing object HEADs as 200;
+ * a 403 there therefore means "no object", not a real denial. Treating it as
+ * not-found lets a brand-new profile hydrate fresh AND still checkpoint. This can
+ * never overwrite good state: an existing object never 403s (it 200s), and a
+ * genuinely bad/expired credential 403s the subsequent PutObject too, so the
+ * checkpoint fails — bounded loss, logged at the pod (simplified durability: no
+ * controller-side verify or auto-repair).
+ */
+export function isAccessDenied(err) {
+    const e = err;
+    return e?.name === 'AccessDenied' || e?.$metadata?.httpStatusCode === 403;
+}
+/** A 412 from a conditional write — the IfMatch/IfNoneMatch precondition failed. */
+function isPreconditionFailed(err) {
+    const e = err;
+    return e?.name === 'PreconditionFailed' || e?.$metadata?.httpStatusCode === 412;
+}
+function errMsg(err) {
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}

package/dist/clip-runtime/browser-viewer-streamer.d.ts

@@ -29,9 +29,25 @@ export interface ViewerStreamerHost {
         port: number;
     }>;
 }
+/**
+ * bb-viewer's /command control plane is UNAUTHENTICATED, so on the shared agents
+ * cluster its bind host MUST be loopback — a 0.0.0.0 / pod-IP / typo'd value would
+ * silently re-open it cross-tenant. Only these exact loopback forms are accepted;
+ * anything else is rejected (fail fast) at spawn.
+ */
+export declare function isLoopbackBindHost(host: string): boolean;
+/**
+ * Whether a kick targets the CURRENT live streamer (so its process is torn down). A
+ * kick with no explicit target hits whoever is live; an explicit target tears down the
+ * current streamer ONLY when it matches — a stale/replayed session_id must not kill a
+ * newer live viewer (it is only recorded for straggler rejection). currentSessionId
+ * undefined (no live streamer) → never a current-kill.
+ */
+export declare function kickHitsCurrentSession(requested: string | undefined, currentSessionId: string | undefined): boolean;
 export declare class BrowserViewerStreamer {
     private readonly host;
     private readonly streamers;
+    private readonly kickedSessions;
     private stopping;
     constructor(host: ViewerStreamerHost);
     /**
@@ -41,6 +57,19 @@ export declare class BrowserViewerStreamer {
      * MachineBrowserProfileViewerData.
      */
     handleViewerCommand(profileId: string, sessionId: string, command: string, input?: Record<string, unknown>, turn?: ViewerTurnConfig): Promise<Record<string, unknown>>;
+    /**
+     * kick — server-side per-viewer disconnect (design §3.6 PR7). Terminates ONE
+     * viewer's WebRTC session: stop its bb-viewer streamer (killing the process
+     * tears down the peer connection + datachannel) and reject the kicked session's
+     * subsequent commands — while bb-browser + Chromium (the agent's live browser)
+     * keep running. This is explicitly DISTINCT from stopping the pod / profile,
+     * which would kill the agent's browser too; a viewer session is a sub-session of
+     * the profile lease, so a kick does NOT release the lease.
+     *
+     * Targets `input.session_id` if given, else the current streamer's session.
+     * Idempotent: kicking with no live streamer still records the kicked session.
+     */
+    private viewerKick;
     /**
      * stream.start — spawn a FRESH bb-viewer for this profile (killing any prior
      * one), resolve the profile's account-scoped page-target CDP ws URL, and run
@@ -177,7 +206,12 @@ export declare class BrowserViewerStreamer {
      * the inner result, throwing the error message on failure.
      */
     private streamerCommand;
-    /** Kill + remove the profile's bb-viewer streamer, if any. Idempotent. */
+    /**
+     * Kill + remove the profile's bb-viewer streamer, if any. Idempotent. Also
+     * clears any kick marker for the profile: a (re)kill establishes a clean
+     * streamer slot, so a subsequent stream.start starts un-kicked. viewerKick
+     * re-records the kicked session AFTER calling this.
+     */
     killProfileStreamer(profileId: string): void;
     /**
      * Tear down every profile streamer and refuse new spawns (daemon stop).

package/dist/clip-runtime/browser-viewer-streamer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-viewer-streamer.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-viewer-streamer.ts"],"names":[],"mappings":"AAsCA,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpF,gFAAgF;IAChF,kBAAkB,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9E,gEAAgE;IAChE,WAAW,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED,qBAAa,qBAAqB;IAUpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAI9D,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,kBAAkB;IAErD;;;;;OAKG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAyBnC;;;;OAIG;YACW,iBAAiB;IA+C/B;;;;OAIG;YACW,kBAAkB;IAgBhC;;;;;;;;;;OAUG;YACW,iBAAiB;IAuB/B;;;;;;;;OAQG;YACW,kBAAkB;IAuBhC;;;;;;OAMG;YACW,cAAc;IAiC5B;;;;;;;OAOG;YACW,kBAAkB;IAqBhC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,gBAAgB;IA6C9B;;;;;;;;;;;;;;;;;;OAkBG;YACW,wBAAwB;IAetC;;;;;OAKG;YACW,yBAAyB;IAevC;;;;;OAKG;YACW,wBAAwB;IAatC;;;OAGG;YACW,kBAAkB;IAehC,yFAAyF;YAC3E,WAAW;IAgBzB;;;;;OAKG;YACW,aAAa;IA2F3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAqBjB;;;;OAIG;YACW,eAAe;IA+B7B,0EAA0E;IAC1E,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO5C;;;OAGG;IACH,QAAQ,IAAI,IAAI;CAMjB"}
+{"version":3,"file":"browser-viewer-streamer.d.ts","sourceRoot":"","sources":["../../src/clip-runtime/browser-viewer-streamer.ts"],"names":[],"mappings":"AAsCA,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACpF,gFAAgF;IAChF,kBAAkB,CAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9E,gEAAgE;IAChE,WAAW,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,GAAG,SAAS,GACnC,OAAO,CAGT;AAED,qBAAa,qBAAqB;IAiBpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAO9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAI5D,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,kBAAkB;IAErD;;;;;OAKG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAuCnC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;OAIG;YACW,iBAAiB;IA+C/B;;;;OAIG;YACW,kBAAkB;IAgBhC;;;;;;;;;;OAUG;YACW,iBAAiB;IAuB/B;;;;;;;;OAQG;YACW,kBAAkB;IAuBhC;;;;;;OAMG;YACW,cAAc;IAiC5B;;;;;;;OAOG;YACW,kBAAkB;IAqBhC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,gBAAgB;IA6C9B;;;;;;;;;;;;;;;;;;OAkBG;YACW,wBAAwB;IAetC;;;;;OAKG;YACW,yBAAyB;IAevC;;;;;OAKG;YACW,wBAAwB;IAatC;;;OAGG;YACW,kBAAkB;IAehC,yFAAyF;YAC3E,WAAW;IAgBzB;;;;;OAKG;YACW,aAAa;IAiH3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAqBjB;;;;OAIG;YACW,eAAe;IA+B7B;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQ5C;;;OAGG;IACH,QAAQ,IAAI,IAAI;CAMjB"}