stageflow 0.27.0 → 0.30.0

package/dist/browser/anchor.js

@@ -0,0 +1,127 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultBrowserRunner, writeSessionOwner } from "./browserTeardown.js";
+export const BROWSER_ANCHOR_FILENAME = "anchor.json";
+const ANCHOR_LOCK_DIRNAME = "anchor.lock";
+const LOCK_POLL_MS = 25;
+const LOCK_WAIT_MS = 120_000;
+export function anchorDir(runDir, profileName) {
+    return path.join(runDir, "browser", profileName);
+}
+export async function readPersistedAnchor(runDir, profileName) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(anchorDir(runDir, profileName), BROWSER_ANCHOR_FILENAME), "utf8"));
+        if (typeof parsed.cdpAddress === "string" &&
+            parsed.anchorEnv !== undefined &&
+            typeof parsed.anchorEnv === "object") {
+            return parsed;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            return undefined;
+    }
+    return undefined;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Cross-process mutex: atomic mkdir, stale when the recorded pid is gone. */
+async function withFileLock(dir, fn) {
+    await mkdir(dir, { recursive: true });
+    const lock = path.join(dir, ANCHOR_LOCK_DIRNAME);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(path.join(lock, "pid"), String(process.pid));
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let holder = 0;
+            try {
+                holder = Number.parseInt(await readFile(path.join(lock, "pid"), "utf8"), 10);
+            }
+            catch {
+                // holder is between mkdir and pid write
+            }
+            if (holder > 0 && holder !== process.pid && !pidAlive(holder)) {
+                await rm(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("timed out waiting for the shared browser lock");
+            await new Promise((r) => setTimeout(r, LOCK_POLL_MS));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+const inflight = new Map();
+/**
+ * One shared browser per (run, profile). Concurrent callers in this process
+ * share one promise; other processes serialize on a lock dir. The anchor and
+ * its CDP address are persisted so stages, resume workers and the sweep reuse
+ * them; a dead anchor is restarted and the address refreshed.
+ */
+export function ensureRunProfileBrowser(support, input) {
+    const key = `${input.runDir}\0${input.profile.key.name}\0${input.humanLogin === true ? "h" : ""}`;
+    const existing = inflight.get(key);
+    if (existing !== undefined)
+        return existing;
+    const promise = withFileLock(anchorDir(input.runDir, input.profile.key.name), async () => {
+        const stored = await readPersistedAnchor(input.runDir, input.profile.key.name);
+        const result = await support.host.ensureProfileBrowser({
+            runId: input.runId,
+            browser: input.browser,
+            profile: input.profile,
+            runner: support.runner ?? defaultBrowserRunner,
+            ...(input.humanLogin === true ? { humanLogin: true } : {}),
+            ...(stored !== undefined
+                ? { previous: { cdpAddress: stored.cdpAddress, anchorEnv: stored.anchorEnv } }
+                : {}),
+        });
+        const changed = stored === undefined ||
+            stored.cdpAddress !== result.cdpAddress ||
+            JSON.stringify(stored.anchorEnv) !== JSON.stringify(result.anchorEnv);
+        const persisted = {
+            cdpAddress: result.cdpAddress,
+            anchorEnv: result.anchorEnv,
+            runId: input.runId,
+            profile: input.profile.key.name,
+            restarts: (stored?.restarts ?? 0) + (stored !== undefined && changed ? 1 : 0),
+        };
+        if (changed) {
+            const dir = anchorDir(input.runDir, input.profile.key.name);
+            const file = path.join(dir, BROWSER_ANCHOR_FILENAME);
+            const tmp = `${file}.${process.pid}.tmp`;
+            await writeFile(tmp, `${JSON.stringify(persisted, null, 2)}\n`, { mode: 0o600 });
+            await rename(tmp, file);
+            await writeSessionOwner({
+                runId: input.runId,
+                stageId: `anchor:${input.profile.key.name}`,
+                runDir: input.runDir,
+                env: result.anchorEnv,
+                anchor: true,
+                profile: input.profile.key.name,
+            }).catch(() => undefined);
+        }
+        return { ...result, restarted: stored !== undefined && changed, persisted };
+    }).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, promise);
+    return promise;
+}

package/dist/browser/auditSink.d.ts

@@ -0,0 +1,38 @@
+/** Records carry names, ids and hosts only: never paths, URLs with queries, or cookie values. */
+export type AuditRecord = {
+    event: "profile_created";
+    scope: string;
+    profile: string;
+} | {
+    event: "profile_deleted";
+    scope: string;
+    profile: string;
+} | {
+    event: "profile_used";
+    scope: string;
+    profile: string;
+    runId: string;
+    stageId: string;
+} | {
+    event: "navigation_outside_allowlist";
+    runId: string;
+    stageId: string;
+    profile?: string;
+    host: string;
+} | {
+    event: "allowlist_unverified";
+    runId: string;
+    stageId: string;
+    profile?: string;
+    reason: string;
+};
+export interface AuditSink {
+    record(entry: AuditRecord): Promise<void>;
+}
+export declare function localAuditLogPath(): string;
+export declare function createLocalAuditSink(file?: string): AuditSink;
+export declare function createMemoryAuditSink(): AuditSink & {
+    records: AuditRecord[];
+};
+/** Audit must never break a run. */
+export declare function safeAudit(sink: AuditSink | undefined, entry: AuditRecord): Promise<void>;

package/dist/browser/auditSink.js

@@ -0,0 +1,34 @@
+import { appendFile, chmod, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+export function localAuditLogPath() {
+    return path.join(globalStageflowHome(), "browser", "audit.jsonl");
+}
+export function createLocalAuditSink(file) {
+    return {
+        async record(entry) {
+            const target = file ?? localAuditLogPath();
+            await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+            await appendFile(target, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`, { mode: 0o600 });
+            await chmod(target, 0o600).catch(() => undefined);
+        },
+    };
+}
+export function createMemoryAuditSink() {
+    const records = [];
+    return {
+        records,
+        async record(entry) {
+            records.push(entry);
+        },
+    };
+}
+/** Audit must never break a run. */
+export async function safeAudit(sink, entry) {
+    try {
+        await (sink ?? createLocalAuditSink()).record(entry);
+    }
+    catch {
+        // best-effort
+    }
+}

package/dist/browser/browserHost.d.ts

@@ -0,0 +1,86 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import type { ProfileLock } from "./profileLock.js";
+import type { AuditSink } from "./auditSink.js";
+import type { ProfileHandle, ProfileStore } from "./profileStore.js";
+export type BrowserEnv = Record<string, string>;
+export type BrowserStageRequest = {
+    runId: string;
+    stageId: string;
+    browser: StageBrowserConfig;
+    profile?: ProfileHandle;
+    /** A human must see and use this browser; headless fallback does not apply. */
+    humanLogin?: boolean;
+    /** Required for a stage with a profile: the shared browser's CDP address. */
+    cdpAddress?: string;
+};
+/** The shared browser of one (run, profile): its CDP address and the env that owns it. */
+export type ProfileBrowser = {
+    cdpAddress: string;
+    anchorEnv: BrowserEnv;
+};
+export type ProfileBrowserRequest = {
+    runId: string;
+    browser: StageBrowserConfig;
+    profile: ProfileHandle;
+    humanLogin?: boolean;
+    runner: BrowserRunner;
+    /** Persisted anchor from an earlier call; reused when still alive, else restarted. */
+    previous?: ProfileBrowser;
+};
+export type ProfileBrowserResult = ProfileBrowser & {
+    /** True when a previous anchor existed but its address changed or it was replaced. */
+    restarted: boolean;
+};
+export interface BrowserHost {
+    /**
+     * Starts or reuses the one browser for (run, profile) and returns its CDP
+     * address. Callers serialize per (run, profile) and persist the result.
+     */
+    ensureProfileBrowser(request: ProfileBrowserRequest): Promise<ProfileBrowserResult>;
+    /** Env of one stage's agent-browser session; with a profile it attaches to `cdpAddress` in its own tab. */
+    stageEnv(request: BrowserStageRequest): Promise<BrowserEnv>;
+    /** Env of the session that owns the profile's browser (anchor, or `sf browser login`). */
+    profileBrowserEnv(request: Omit<BrowserStageRequest, "stageId" | "cdpAddress"> & {
+        profile: ProfileHandle;
+    }): Promise<BrowserEnv>;
+}
+/** Runs `agent-browser <args>` with exactly `env` (plus PATH). Injectable for tests. */
+export type BrowserRunner = (args: string[], env: BrowserEnv, 
+/** Per-call limit; the default runner allows 20 s. */
+options?: {
+    timeoutMs?: number;
+}) => Promise<{
+    code: number | null;
+    stdout?: string;
+}>;
+export type StageBrowserSupport = {
+    host: BrowserHost;
+    profiles: ProfileStore;
+    runner?: BrowserRunner;
+    /** Profile lock; defaults to the local lock-file implementation. */
+    locks?: ProfileLock;
+    /** Poll interval while a stage waits for a busy profile. */
+    lockPollMs?: number;
+    /** Upper bound for waiting on the daemon to exit after `close`. */
+    closeWaitMs?: number;
+    /** Login-check bounds; defaults suit real browsers. */
+    loginCheck?: {
+        waitMs?: number;
+        settleMs?: number;
+    };
+    /** Root holding per-session socket dirs; defaults to the local host's root. */
+    socketRoot?: string;
+    /** Defaults to the local audit log in the Stageflow home. */
+    audit?: AuditSink;
+    /** Host-blocked sites; defaults to `browser.blocked_sites` from Host config. */
+    blockedSites?: readonly string[];
+    /** Screen detection for human login stages; defaults to the real Host. */
+    display?: () => {
+        hasDisplay: boolean;
+        docker: boolean;
+    };
+};
+export declare const BROWSER_ENV_PREFIX = "AGENT_BROWSER_";
+export declare function shortHash(value: string, length: number): string;
+export declare const BROWSER_ENV_FILENAME = "browser-env.json";
+export declare const BROWSER_POLICY_FILENAME = "browser-policy.json";

package/dist/browser/browserHost.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+export const BROWSER_ENV_PREFIX = "AGENT_BROWSER_";
+export function shortHash(value, length) {
+    return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+export const BROWSER_ENV_FILENAME = "browser-env.json";
+export const BROWSER_POLICY_FILENAME = "browser-policy.json";

package/dist/browser/browserSweep.d.ts

@@ -0,0 +1,14 @@
+import type { BrowserRunner } from "./browserHost.js";
+export type BrowserSweepOptions = {
+    isRunLive: (runId: string) => Promise<boolean>;
+    socketRoot?: string;
+    runner?: BrowserRunner;
+    closeWaitMs?: number;
+};
+/**
+ * At Host start: close sessions whose run is gone or terminal, clean leftover
+ * files, and leave sessions of live or waiting runs alone.
+ */
+export declare function sweepOrphanBrowserSessions(options: BrowserSweepOptions): Promise<{
+    closed: string[];
+}>;

package/dist/browser/browserSweep.js

@@ -0,0 +1,54 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { BROWSER_OWNER_FILENAME, closeBrowserSession, } from "./browserTeardown.js";
+import { defaultSocketRoot } from "./localBrowserHost.js";
+import { rmdir } from "node:fs/promises";
+async function readOwner(dir) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(dir, BROWSER_OWNER_FILENAME), "utf8"));
+        if (typeof parsed.runId === "string" && parsed.env?.AGENT_BROWSER_SESSION) {
+            return parsed;
+        }
+    }
+    catch {
+        // unreadable owner: treated as ownerless below
+    }
+    return undefined;
+}
+/**
+ * At Host start: close sessions whose run is gone or terminal, clean leftover
+ * files, and leave sessions of live or waiting runs alone.
+ */
+export async function sweepOrphanBrowserSessions(options) {
+    const root = options.socketRoot ?? defaultSocketRoot(process.platform);
+    const closed = [];
+    let dirs;
+    try {
+        dirs = await readdir(root);
+    }
+    catch {
+        return { closed };
+    }
+    const owners = [];
+    for (const name of dirs) {
+        const owner = await readOwner(path.join(root, name));
+        if (owner !== undefined)
+            owners.push(owner);
+    }
+    // Stage sessions attach to the anchor, so they go first.
+    owners.sort((x, y) => Number(x.anchor === true) - Number(y.anchor === true));
+    for (const owner of owners) {
+        if (await options.isRunLive(owner.runId).catch(() => true))
+            continue;
+        const { gone } = await closeBrowserSession(owner.env, {
+            ...(options.runner !== undefined ? { runner: options.runner } : {}),
+            ...(options.closeWaitMs !== undefined
+                ? { closeWaitMs: options.closeWaitMs }
+                : {}),
+        });
+        if (gone)
+            closed.push(owner.env.AGENT_BROWSER_SESSION);
+    }
+    await rmdir(root).catch(() => undefined);
+    return { closed };
+}

package/dist/browser/browserTeardown.d.ts

@@ -0,0 +1,56 @@
+import type { StageLogEvent } from "../runstore/port.js";
+import { type BrowserEnv, type BrowserRunner, type StageBrowserSupport } from "./browserHost.js";
+export declare const BROWSER_OWNER_FILENAME = "owner.json";
+/** Written once a stage's tab and session are closed; cleared when its env is resolved again. */
+export declare const BROWSER_CLOSED_FILENAME = "browser-closed.json";
+export type BrowserSessionOwner = {
+    runId: string;
+    stageId: string;
+    runDir: string;
+    env: BrowserEnv;
+    /** The run's shared browser for `profile`; stage sessions attach to it. */
+    anchor?: true;
+    profile?: string;
+};
+export declare const defaultBrowserRunner: BrowserRunner;
+export declare function writeSessionOwner(owner: BrowserSessionOwner): Promise<void>;
+/**
+ * Gracefully closes the session with the exact env it was launched with, waits
+ * (bounded) for the daemon to disappear, then removes the leftover socket-dir
+ * files. Never signals Chrome: a hard kill loses cookie persistence.
+ */
+export declare function closeBrowserSession(env: BrowserEnv, options?: {
+    runner?: BrowserRunner;
+    closeWaitMs?: number;
+}): Promise<{
+    gone: boolean;
+}>;
+/**
+ * Closes one stage's tab (when it is attached to a shared browser) and then
+ * its session. Chrome, the lease and the other stages stay up. No-op for
+ * stages that never resolved a browser env.
+ */
+export declare function teardownStageBrowser(support: StageBrowserSupport, input: StageTeardownInput): Promise<void>;
+type StageEvents = () => Promise<StageLogEvent[]>;
+type StageTeardownInput = {
+    runId: string;
+    runDir: string;
+    stageId: string;
+    /** Reads the stage's persisted tool activity for the soft allowlist audit. */
+    events?: StageEvents;
+};
+/** Gracefully closes every anchor browser the run started. */
+export declare function closeRunAnchors(support: StageBrowserSupport, run: {
+    runDir: string;
+}): Promise<void>;
+/**
+ * Run end, cancel, abandon or failure: closes stage sessions and tabs, then
+ * the run's anchors, then releases the run's profile leases. `only` closes
+ * just those stages and leaves anchor and leases alone.
+ */
+export declare function teardownRunBrowsers(support: StageBrowserSupport, run: {
+    runId: string;
+    runDir: string;
+    events?: (stageId: string) => Promise<StageLogEvent[]>;
+}, only?: (stageId: string) => boolean): Promise<void>;
+export {};

package/dist/browser/browserTeardown.js

@@ -0,0 +1,235 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { readFile, readdir, rm, rmdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readPersistedBrowserEnv } from "./persistedEnv.js";
+import { stageDir } from "../runstore/paths.js";
+import { auditStageNavigations } from "./navigationAudit.js";
+import { BROWSER_ENV_FILENAME, BROWSER_POLICY_FILENAME, } from "./browserHost.js";
+import { stageProfileLock } from "./stageProfileLock.js";
+import { BROWSER_ANCHOR_FILENAME, anchorDir, readPersistedAnchor, } from "./anchor.js";
+export const BROWSER_OWNER_FILENAME = "owner.json";
+/** Written once a stage's tab and session are closed; cleared when its env is resolved again. */
+export const BROWSER_CLOSED_FILENAME = "browser-closed.json";
+const DEFAULT_CLOSE_WAIT_MS = 10_000;
+const POLL_MS = 50;
+const CLOSE_COMMAND_TIMEOUT_MS = 20_000;
+export const defaultBrowserRunner = (args, env, options) => new Promise((resolve) => {
+    execFile("agent-browser", args, {
+        env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", ...env },
+        timeout: options?.timeoutMs ?? CLOSE_COMMAND_TIMEOUT_MS,
+    }, (err, stdout) => {
+        const code = err?.code;
+        resolve({
+            code: err ? (typeof code === "number" ? code : 1) : 0,
+            stdout: String(stdout ?? ""),
+        });
+    });
+});
+export async function writeSessionOwner(owner) {
+    const dir = owner.env.AGENT_BROWSER_SOCKET_DIR;
+    if (!dir)
+        return;
+    await writeFile(path.join(dir, BROWSER_OWNER_FILENAME), `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+}
+function pidAlive(pidFile) {
+    try {
+        const pid = Number.parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function daemonGone(dir, session) {
+    if (existsSync(path.join(dir, `${session}.sock`)))
+        return false;
+    const pidFile = path.join(dir, `${session}.pid`);
+    return !existsSync(pidFile) || !pidAlive(pidFile);
+}
+async function removeSessionFiles(dir, session) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name.startsWith(`${session}.`) || name === BROWSER_OWNER_FILENAME) {
+            await rm(path.join(dir, name), { force: true });
+        }
+    }
+    await rmdir(dir).catch(() => undefined);
+    await rmdir(path.dirname(dir)).catch(() => undefined);
+}
+/**
+ * Gracefully closes the session with the exact env it was launched with, waits
+ * (bounded) for the daemon to disappear, then removes the leftover socket-dir
+ * files. Never signals Chrome: a hard kill loses cookie persistence.
+ */
+// TODO(multi-tenant): teardown and the orphan sweep assume a local agent-browser runner and a local socket root.
+// A remote BrowserHost (sandbox or provider) needs its own close and sweep path.
+export async function closeBrowserSession(env, options = {}) {
+    const runner = options.runner ?? defaultBrowserRunner;
+    try {
+        await runner(["close"], env);
+    }
+    catch {
+        // close of an already-gone session is not an error
+    }
+    const dir = env.AGENT_BROWSER_SOCKET_DIR;
+    const session = env.AGENT_BROWSER_SESSION;
+    if (!dir || !session)
+        return { gone: true };
+    const deadline = Date.now() + (options.closeWaitMs ?? DEFAULT_CLOSE_WAIT_MS);
+    while (!daemonGone(dir, session)) {
+        if (Date.now() >= deadline)
+            return { gone: false };
+        await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    await removeSessionFiles(dir, session);
+    return { gone: true };
+}
+async function readEnvFile(file) {
+    try {
+        return await readPersistedBrowserEnv(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+function closeOptions(support) {
+    return {
+        ...(support.runner !== undefined ? { runner: support.runner } : {}),
+        ...(support.closeWaitMs !== undefined
+            ? { closeWaitMs: support.closeWaitMs }
+            : {}),
+    };
+}
+/**
+ * Closes one stage's tab (when it is attached to a shared browser) and then
+ * its session. Chrome, the lease and the other stages stay up. No-op for
+ * stages that never resolved a browser env.
+ */
+export function teardownStageBrowser(support, input) {
+    const key = `${input.runDir}\0${input.stageId}`;
+    const running = stageTeardowns.get(key);
+    if (running !== undefined)
+        return running;
+    const promise = teardownStageBrowserOnce(support, input).finally(() => {
+        stageTeardowns.delete(key);
+    });
+    stageTeardowns.set(key, promise);
+    return promise;
+}
+const stageTeardowns = new Map();
+async function readNavigationPolicy(file) {
+    try {
+        const raw = JSON.parse(await readFile(file, "utf8"));
+        if (typeof raw.runId !== "string" ||
+            typeof raw.stageId !== "string" ||
+            !Array.isArray(raw.allow_domains)) {
+            return undefined;
+        }
+        return {
+            runId: raw.runId,
+            stageId: raw.stageId,
+            ...(typeof raw.profile === "string" ? { profile: raw.profile } : {}),
+            allow_domains: raw.allow_domains.filter((d) => typeof d === "string"),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function auditAndClearPolicy(support, input) {
+    const file = path.join(stageDir(input.runDir, input.stageId), BROWSER_POLICY_FILENAME);
+    const policy = await readNavigationPolicy(file);
+    if (policy === undefined)
+        return;
+    await auditStageNavigations(policy, input.events, support.audit).catch(() => undefined);
+    await rm(file, { force: true }).catch(() => undefined);
+}
+async function teardownStageBrowserOnce(support, input) {
+    const env = await readEnvFile(path.join(stageDir(input.runDir, input.stageId), BROWSER_ENV_FILENAME));
+    if (env === undefined)
+        return;
+    await auditAndClearPolicy(support, input);
+    const closedMarker = path.join(stageDir(input.runDir, input.stageId), BROWSER_CLOSED_FILENAME);
+    // A second close would re-attach to the shared browser and could close another stage's tab.
+    if (existsSync(closedMarker))
+        return;
+    if (env.AGENT_BROWSER_CDP !== undefined) {
+        // With the pinned tab as the current tab, `tab close` closes only this stage's tab.
+        await (support.runner ?? defaultBrowserRunner)(["tab", "close"], env).catch(() => undefined);
+    }
+    const { gone } = await closeBrowserSession(env, closeOptions(support));
+    if (gone)
+        await writeFile(closedMarker, "{}\n").catch(() => undefined);
+}
+/** Gracefully closes every anchor browser the run started. */
+export function closeRunAnchors(support, run) {
+    const running = anchorTeardowns.get(run.runDir);
+    if (running !== undefined)
+        return running;
+    const promise = closeRunAnchorsOnce(support, run).finally(() => {
+        anchorTeardowns.delete(run.runDir);
+    });
+    anchorTeardowns.set(run.runDir, promise);
+    return promise;
+}
+const anchorTeardowns = new Map();
+async function closeRunAnchorsOnce(support, run) {
+    let names = [];
+    try {
+        names = await readdir(path.join(run.runDir, "browser"));
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const anchor = await readPersistedAnchor(run.runDir, name);
+        if (anchor === undefined)
+            continue;
+        const { gone } = await closeBrowserSession(anchor.anchorEnv, closeOptions(support)).catch(() => ({ gone: false }));
+        if (gone) {
+            await rm(path.join(anchorDir(run.runDir, name), BROWSER_ANCHOR_FILENAME), {
+                force: true,
+            }).catch(() => undefined);
+        }
+    }
+}
+/**
+ * Run end, cancel, abandon or failure: closes stage sessions and tabs, then
+ * the run's anchors, then releases the run's profile leases. `only` closes
+ * just those stages and leaves anchor and leases alone.
+ */
+export async function teardownRunBrowsers(support, run, only) {
+    let ids = [];
+    try {
+        ids = await readdir(path.join(run.runDir, "stages"));
+    }
+    catch {
+        // no stage dirs: nothing to close
+    }
+    for (const stageId of ids) {
+        if (only !== undefined && !only(stageId))
+            continue;
+        const { events, ...base } = run;
+        await teardownStageBrowser(support, {
+            ...base,
+            stageId,
+            ...(events !== undefined ? { events: () => events(stageId) } : {}),
+        }).catch(() => undefined);
+    }
+    if (only === undefined) {
+        await closeRunAnchors(support, run).catch(() => undefined);
+        await stageProfileLock(support)
+            .releaseOwner({ runId: run.runId })
+            .catch(() => undefined);
+    }
+}

package/dist/browser/fakeRemoteBrowserHost.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserHost } from "./browserHost.js";
+export declare function createFakeRemoteBrowserHost(address: string): BrowserHost;