stageflow 0.27.0 → 0.31.0

package/dist/browser/localProfileLock.js

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { lockKey, ownerMatches, sameOwner, } from "./profileLock.js";
+function locksRoot() {
+    return path.join(globalStageflowHome(), "browser", "locks");
+}
+function lockFile(key) {
+    return path.join(locksRoot(), key.scope, `${key.name}.lock`);
+}
+async function readHolder(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (typeof parsed.runId === "string") {
+            return typeof parsed.stageId === "string"
+                ? { runId: parsed.runId, stageId: parsed.stageId }
+                : { runId: parsed.runId };
+        }
+    }
+    catch {
+        // missing or unreadable: treated as free by callers that re-check
+    }
+    return undefined;
+}
+/** A lock file that exists but cannot be parsed (crash, disk full, manual edit). */
+async function isCorrupt(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        return false;
+    }
+    return readHolderFrom(raw) === undefined;
+}
+function readHolderFrom(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.runId === "string") {
+            return typeof parsed.stageId === "string"
+                ? { runId: parsed.runId, stageId: parsed.stageId }
+                : { runId: parsed.runId };
+        }
+    }
+    catch {
+        // unparseable
+    }
+    return undefined;
+}
+/** Removes a corrupt lock file via rename-away; restores it if it turned out valid. */
+async function dropCorrupt(file) {
+    const tomb = `${file}.${process.pid}.${randomUUID()}.stale`;
+    try {
+        await rename(file, tomb);
+    }
+    catch {
+        return true;
+    }
+    if ((await readHolder(tomb)) !== undefined) {
+        await link(tomb, file).catch(() => undefined);
+        await rm(tomb, { force: true });
+        return false;
+    }
+    await rm(tomb, { force: true });
+    return true;
+}
+/** `link` fails with EEXIST when the lock exists, and the content is complete at creation. */
+async function createExclusive(file, owner) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+    try {
+        await link(tmp, file);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+}
+/**
+ * Removes a lock judged stale. The file is renamed away first and re-read, so
+ * a lock another process re-created in the meantime is not dropped.
+ */
+async function dropStale(file, stale) {
+    const tomb = `${file}.${process.pid}.${randomUUID()}.stale`;
+    try {
+        await rename(file, tomb);
+    }
+    catch {
+        return true;
+    }
+    const moved = await readHolder(tomb);
+    if (moved !== undefined && !sameOwner(moved, stale)) {
+        await link(tomb, file).catch(() => undefined);
+        await rm(tomb, { force: true });
+        return false;
+    }
+    await rm(tomb, { force: true });
+    return true;
+}
+async function lockFiles() {
+    const files = [];
+    let scopes;
+    try {
+        scopes = await readdir(locksRoot());
+    }
+    catch {
+        return files;
+    }
+    for (const scope of scopes) {
+        let names;
+        try {
+            names = await readdir(path.join(locksRoot(), scope));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (name.endsWith(".lock"))
+                files.push(path.join(locksRoot(), scope, name));
+        }
+    }
+    return files;
+}
+export function createLocalProfileLock(options = {}) {
+    // Serializes this process's operations per lock file; other processes rely on link/rename atomicity.
+    const chains = new Map();
+    const serialized = (file, task) => {
+        const next = (chains.get(file) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(task);
+        chains.set(file, next);
+        void next.finally(() => {
+            if (chains.get(file) === next)
+                chains.delete(file);
+        });
+        return next;
+    };
+    const releaseFile = (file, owner) => serialized(file, async () => {
+        const current = await readHolder(file);
+        if (current !== undefined && sameOwner(current, owner)) {
+            await rm(file, { force: true });
+        }
+    });
+    return {
+        async acquire(rawKey, owner) {
+            const file = lockFile(lockKey(rawKey));
+            return serialized(file, async () => {
+                for (let attempt = 0; attempt < 3; attempt += 1) {
+                    if (await createExclusive(file, owner)) {
+                        return {
+                            status: "acquired",
+                            release: () => releaseFile(file, owner),
+                        };
+                    }
+                    const current = await readHolder(file);
+                    if (current === undefined) {
+                        if (await isCorrupt(file))
+                            await dropCorrupt(file);
+                        continue;
+                    }
+                    if (sameOwner(current, owner)) {
+                        return {
+                            status: "acquired",
+                            release: () => releaseFile(file, owner),
+                        };
+                    }
+                    if (options.isRunLive !== undefined &&
+                        !(await options.isRunLive(current.runId))) {
+                        if (await dropStale(file, current))
+                            continue;
+                    }
+                    return { status: "queued", holder: current };
+                }
+                const holder = await readHolder(file);
+                return {
+                    status: "queued",
+                    holder: holder ?? { runId: "unknown" },
+                };
+            });
+        },
+        async holder(rawKey) {
+            return readHolder(lockFile(lockKey(rawKey)));
+        },
+        async releaseOwner(target) {
+            for (const file of await lockFiles()) {
+                const current = await readHolder(file);
+                if (current !== undefined && ownerMatches(current, target)) {
+                    await releaseFile(file, current);
+                }
+            }
+        },
+        async reclaimStale(isRunLive) {
+            let dropped = 0;
+            for (const file of await lockFiles()) {
+                const current = await readHolder(file);
+                if (current === undefined) {
+                    if (await isCorrupt(file)) {
+                        if (await serialized(file, () => dropCorrupt(file)))
+                            dropped += 1;
+                    }
+                    continue;
+                }
+                if (await isRunLive(current.runId))
+                    continue;
+                if (await serialized(file, () => dropStale(file, current)))
+                    dropped += 1;
+            }
+            return dropped;
+        },
+    };
+}

package/dist/browser/localProfileStore.d.ts

@@ -0,0 +1,5 @@
+import { type AuditSink } from "./auditSink.js";
+import { type ProfileStore } from "./profileStore.js";
+export declare function createLocalProfileStore(options?: {
+    audit?: AuditSink;
+}): ProfileStore;

package/dist/browser/localProfileStore.js

@@ -0,0 +1,91 @@
+import { access, chmod, mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createLocalAuditSink, safeAudit } from "./auditSink.js";
+import { validateProfileKey, validateProfileScope, } from "./profileStore.js";
+function browserRoot() {
+    return path.join(globalStageflowHome(), "browser");
+}
+function scopeDir(scope) {
+    return path.join(browserRoot(), scope);
+}
+async function ensurePrivateDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createLocalProfileStore(options = {}) {
+    const audit = options.audit ?? createLocalAuditSink();
+    return {
+        async open(rawKey) {
+            const key = validateProfileKey(rawKey);
+            const base = path.join(scopeDir(key.scope), key.name);
+            const profileDir = path.join(base, "profile");
+            const stateDir = path.join(base, "state");
+            const created = !(await exists(base));
+            await ensurePrivateDir(browserRoot());
+            await ensurePrivateDir(scopeDir(key.scope));
+            await ensurePrivateDir(base);
+            await ensurePrivateDir(profileDir);
+            await ensurePrivateDir(stateDir);
+            if (created) {
+                await safeAudit(audit, {
+                    event: "profile_created",
+                    scope: key.scope,
+                    profile: key.name,
+                });
+            }
+            return { key, profileDir, stateDir };
+        },
+        async list(scope) {
+            const dir = scopeDir(validateProfileScope(scope));
+            try {
+                const entries = await readdir(dir, { withFileTypes: true });
+                return entries
+                    .filter((e) => e.isDirectory())
+                    .map((e) => e.name)
+                    .sort();
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return [];
+                throw err;
+            }
+        },
+        async delete(rawKey) {
+            const key = validateProfileKey(rawKey);
+            const target = path.join(scopeDir(key.scope), key.name);
+            const existed = await exists(target);
+            await rm(target, { recursive: true, force: true });
+            if (existed) {
+                await safeAudit(audit, {
+                    event: "profile_deleted",
+                    scope: key.scope,
+                    profile: key.name,
+                });
+            }
+        },
+        async deleteScope(scope) {
+            const valid = validateProfileScope(scope);
+            for (const name of await this.list(valid)) {
+                await safeAudit(audit, {
+                    event: "profile_deleted",
+                    scope: valid,
+                    profile: name,
+                });
+            }
+            await rm(scopeDir(valid), {
+                recursive: true,
+                force: true,
+            });
+        },
+    };
+}

package/dist/browser/loginCheck.d.ts

@@ -0,0 +1,53 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import type { BrowserEnv, BrowserRunner } from "./browserHost.js";
+export declare const BROWSER_LOGIN_CHECK_FILENAME = "browser-login-check.json";
+export type LoginCheckConfig = NonNullable<StageBrowserConfig["check"]>;
+export type LoginState = "logged_in" | "logged_out" | "unknown";
+export type LoginCheckMatch = {
+    state: LoginState;
+    /** `null` when the patterns cannot decide. */
+    logged_in: boolean | null;
+};
+export type LoginCheckResult = LoginCheckMatch & {
+    url: string;
+    attempt: number;
+    check_url: string;
+};
+export declare const OPEN_COMMAND_TIMEOUT_MS = 60000;
+/** Pure: `logged_out_url` wins over `logged_in_url`; no match is `unknown`. */
+export declare function matchLoginState(input: {
+    finalUrl: string;
+    check: Pick<LoginCheckConfig, "logged_in_url" | "logged_out_url">;
+}): LoginCheckMatch;
+export type LoginCheckOptions = {
+    waitMs?: number;
+    settleMs?: number;
+};
+/**
+ * Opens `check.url` in the stage's own browser session (same persisted env, so
+ * no second browser is launched) and matches the settled final address. The
+ * session stays open for the stage; its teardown closes it later.
+ */
+export declare function runLoginCheck(env: BrowserEnv, check: LoginCheckConfig, runner: BrowserRunner, options?: LoginCheckOptions): Promise<LoginCheckMatch & {
+    url: string;
+}>;
+export declare function readStageLoginCheck(runDir: string, stageId: string): Promise<LoginCheckResult | undefined>;
+/**
+ * Computes the Host result once per attempt and persists it in the stage run
+ * dir. A resume of the same attempt reuses the stored value, so the result the
+ * agent saw is the result the emit is validated against.
+ */
+export declare function ensureStageLoginCheck(input: {
+    runDir: string;
+    stageId: string;
+    attempt: number;
+    env: BrowserEnv;
+    check: LoginCheckConfig;
+    runner?: BrowserRunner;
+    options?: LoginCheckOptions;
+}): Promise<LoginCheckResult>;
+export type ExpectedLoginResult = Pick<LoginCheckResult, "state" | "logged_in" | "url">;
+/** Prompt block that hands the Host result to the agent. */
+export declare function loginCheckPromptBlock(result: ExpectedLoginResult): string;
+/** Emit-time validation of the payload against the Host result; `undefined` when valid. */
+export declare function loginCheckIssue(payload: unknown, expected: ExpectedLoginResult): string | undefined;

package/dist/browser/loginCheck.js

@@ -0,0 +1,147 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stageDir } from "../runstore/paths.js";
+import { defaultBrowserRunner } from "./browserTeardown.js";
+export const BROWSER_LOGIN_CHECK_FILENAME = "browser-login-check.json";
+const DEFAULT_WAIT_MS = 15_000;
+const WAIT_TIMEOUT_MARGIN_MS = 15_000;
+export const OPEN_COMMAND_TIMEOUT_MS = 60_000;
+const DEFAULT_SETTLE_MS = 300;
+const MAX_URL_READS = 4;
+/** `*` matches any run of characters (including `/`), `?` one character. Whole-URL match. */
+function globToRegExp(glob) {
+    let source = "";
+    for (const ch of glob.replace(/\*+/g, "*")) {
+        if (ch === "*")
+            source += ".*";
+        else if (ch === "?")
+            source += ".";
+        else
+            source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`, "s");
+}
+function asList(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function matchesAny(url, globs) {
+    return globs.some((glob) => globToRegExp(glob).test(url));
+}
+/** Pure: `logged_out_url` wins over `logged_in_url`; no match is `unknown`. */
+export function matchLoginState(input) {
+    const { finalUrl, check } = input;
+    if (matchesAny(finalUrl, asList(check.logged_out_url))) {
+        return { state: "logged_out", logged_in: false };
+    }
+    if (matchesAny(finalUrl, asList(check.logged_in_url))) {
+        return { state: "logged_in", logged_in: true };
+    }
+    return { state: "unknown", logged_in: null };
+}
+async function readUrl(env, runner) {
+    const got = await runner(["get", "url"], env);
+    if (got.code !== 0) {
+        throw new Error("login check: could not read the page address");
+    }
+    return (got.stdout ?? "").trim();
+}
+/**
+ * Opens `check.url` in the stage's own browser session (same persisted env, so
+ * no second browser is launched) and matches the settled final address. The
+ * session stays open for the stage; its teardown closes it later.
+ */
+export async function runLoginCheck(env, check, runner, options = {}) {
+    const opened = await runner(["open", check.url], env, {
+        timeoutMs: OPEN_COMMAND_TIMEOUT_MS,
+    });
+    if (opened.code !== 0) {
+        throw new Error(`login check: could not open ${check.url}`);
+    }
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    await runner(["wait", "--load", "networkidle", "--timeout", String(waitMs)], env, {
+        timeoutMs: waitMs + WAIT_TIMEOUT_MARGIN_MS,
+    }).catch(() => undefined);
+    const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+    let url = await readUrl(env, runner);
+    for (let i = 1; i < MAX_URL_READS; i++) {
+        if (settleMs > 0)
+            await new Promise((r) => setTimeout(r, settleMs));
+        const next = await readUrl(env, runner);
+        if (next === url)
+            break;
+        url = next;
+    }
+    if (url === "") {
+        throw new Error("login check: the browser reported an empty address");
+    }
+    return { ...matchLoginState({ finalUrl: url, check }), url };
+}
+function resultFile(runDir, stageId) {
+    return path.join(stageDir(runDir, stageId), BROWSER_LOGIN_CHECK_FILENAME);
+}
+export async function readStageLoginCheck(runDir, stageId) {
+    try {
+        const parsed = JSON.parse(await readFile(resultFile(runDir, stageId), "utf8"));
+        if (parsed && typeof parsed === "object" && typeof parsed.url === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        // not computed yet
+    }
+    return undefined;
+}
+/**
+ * Computes the Host result once per attempt and persists it in the stage run
+ * dir. A resume of the same attempt reuses the stored value, so the result the
+ * agent saw is the result the emit is validated against.
+ */
+export async function ensureStageLoginCheck(input) {
+    const existing = await readStageLoginCheck(input.runDir, input.stageId);
+    if (existing !== undefined &&
+        existing.attempt === input.attempt &&
+        existing.check_url === input.check.url) {
+        return existing;
+    }
+    const probed = await runLoginCheck(input.env, input.check, input.runner ?? defaultBrowserRunner, input.options);
+    const result = {
+        ...probed,
+        attempt: input.attempt,
+        check_url: input.check.url,
+    };
+    const file = resultFile(input.runDir, input.stageId);
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmp, file);
+    return result;
+}
+/** Prompt block that hands the Host result to the agent. */
+export function loginCheckPromptBlock(result) {
+    const lines = ["## Host login check", ""];
+    if (result.state === "unknown") {
+        lines.push(`The Host opened the check page and its final address is ${JSON.stringify(result.url)}, but the configured patterns cannot decide whether the session is logged in (result: unknown).`, "The browser session is already open on that page. Use the browser skill to inspect the page (read-only), decide whether the profile is logged in, and emit payload `{ \"logged_in\": <true|false>, \"url\": <that exact address> }`.", "The Host only checks that `logged_in` is a boolean and that `url` equals the address above.");
+    }
+    else {
+        lines.push(`Host login check result: ${JSON.stringify({ logged_in: result.logged_in, url: result.url })}`, "Report exactly this in your envelope payload. Do not browse. The Host rejects any other value.");
+    }
+    return lines.join("\n");
+}
+/** Emit-time validation of the payload against the Host result; `undefined` when valid. */
+export function loginCheckIssue(payload, expected) {
+    const value = payload && typeof payload === "object"
+        ? payload
+        : {};
+    if (typeof value.logged_in !== "boolean") {
+        return "login check payload.logged_in must be a boolean";
+    }
+    if (value.url !== expected.url) {
+        return `login check payload.url must equal the Host-observed address ${JSON.stringify(expected.url)}`;
+    }
+    if (expected.logged_in !== null && value.logged_in !== expected.logged_in) {
+        return `login check payload.logged_in must be ${expected.logged_in} (Host result)`;
+    }
+    return undefined;
+}

package/dist/browser/memoryProfileLock.d.ts

@@ -0,0 +1,2 @@
+import { type ProfileLock, type ProfileLockOptions } from "./profileLock.js";
+export declare function createInMemoryProfileLock(options?: ProfileLockOptions): ProfileLock;

package/dist/browser/memoryProfileLock.js

@@ -0,0 +1,53 @@
+import { lockKey, ownerMatches, sameOwner, } from "./profileLock.js";
+export function createInMemoryProfileLock(options = {}) {
+    const held = new Map();
+    const id = (key) => `${key.scope}\u0000${key.name}`;
+    const releaseIfHeldBy = (k, owner) => {
+        const current = held.get(k);
+        if (current !== undefined && sameOwner(current, owner))
+            held.delete(k);
+    };
+    return {
+        async acquire(rawKey, owner) {
+            const key = lockKey(rawKey);
+            const k = id(key);
+            let current = held.get(k);
+            if (current !== undefined &&
+                !sameOwner(current, owner) &&
+                options.isRunLive !== undefined &&
+                !(await options.isRunLive(current.runId))) {
+                held.delete(k);
+                current = undefined;
+            }
+            if (current !== undefined && !sameOwner(current, owner)) {
+                return { status: "queued", holder: { ...current } };
+            }
+            if (current === undefined)
+                held.set(k, { ...owner });
+            return {
+                status: "acquired",
+                release: async () => releaseIfHeldBy(k, owner),
+            };
+        },
+        async holder(rawKey) {
+            const current = held.get(id(lockKey(rawKey)));
+            return current === undefined ? undefined : { ...current };
+        },
+        async releaseOwner(target) {
+            for (const [k, owner] of [...held]) {
+                if (ownerMatches(owner, target))
+                    held.delete(k);
+            }
+        },
+        async reclaimStale(isRunLive) {
+            let dropped = 0;
+            for (const [k, owner] of [...held]) {
+                if (!(await isRunLive(owner.runId))) {
+                    held.delete(k);
+                    dropped += 1;
+                }
+            }
+            return dropped;
+        },
+    };
+}

package/dist/browser/memoryProfileStore.d.ts

@@ -0,0 +1,2 @@
+import { type ProfileStore } from "./profileStore.js";
+export declare function createInMemoryProfileStore(): ProfileStore;

package/dist/browser/memoryProfileStore.js

@@ -0,0 +1,31 @@
+import { validateProfileKey, validateProfileScope, } from "./profileStore.js";
+export function createInMemoryProfileStore() {
+    const scopes = new Map();
+    return {
+        async open(rawKey) {
+            const key = validateProfileKey(rawKey);
+            let profiles = scopes.get(key.scope);
+            if (!profiles) {
+                profiles = new Map();
+                scopes.set(key.scope, profiles);
+            }
+            let handle = profiles.get(key.name);
+            if (!handle) {
+                const base = `memory://${key.scope}/${key.name}`;
+                handle = { key, profileDir: `${base}/profile`, stateDir: `${base}/state` };
+                profiles.set(key.name, handle);
+            }
+            return handle;
+        },
+        async list(scope) {
+            return [...(scopes.get(validateProfileScope(scope))?.keys() ?? [])].sort();
+        },
+        async delete(rawKey) {
+            const key = validateProfileKey(rawKey);
+            scopes.get(key.scope)?.delete(key.name);
+        },
+        async deleteScope(scope) {
+            scopes.delete(validateProfileScope(scope));
+        },
+    };
+}

package/dist/browser/navigationAudit.d.ts

@@ -0,0 +1,16 @@
+import type { StageLogEvent } from "../runstore/port.js";
+import { type AuditSink } from "./auditSink.js";
+export type NavigationPolicy = {
+    runId: string;
+    stageId: string;
+    profile?: string;
+    allow_domains: string[];
+};
+/**
+ * Soft allowlist check for profile stages (agent-browser refuses
+ * --allowed-domains with --profile). The only cheap signal is the persisted
+ * bash tool activity: it sees explicit `agent-browser open|goto|navigate <url>`
+ * commands, not redirects, link clicks or in-page navigation. Hosts only are
+ * recorded, never full URLs.
+ */
+export declare function auditStageNavigations(policy: NavigationPolicy, events: (() => Promise<StageLogEvent[]>) | undefined, sink: AuditSink | undefined): Promise<void>;

package/dist/browser/navigationAudit.js

@@ -0,0 +1,53 @@
+import { safeAudit } from "./auditSink.js";
+import { hostOf, normalizeDomain } from "./sitePolicy.js";
+const NAV_COMMAND = /\bagent-browser\b[^\n|;&]*?\s(?:open|goto|navigate|tab\s+new)\s+(?:--?\S+\s+)*["']?([^\s"'|;&]+)/g;
+function allowed(host, allow) {
+    return allow.some((entry) => {
+        const d = normalizeDomain(entry);
+        return host === d || host.endsWith(`.${d}`);
+    });
+}
+/**
+ * Soft allowlist check for profile stages (agent-browser refuses
+ * --allowed-domains with --profile). The only cheap signal is the persisted
+ * bash tool activity: it sees explicit `agent-browser open|goto|navigate <url>`
+ * commands, not redirects, link clicks or in-page navigation. Hosts only are
+ * recorded, never full URLs.
+ */
+export async function auditStageNavigations(policy, events, sink) {
+    if (policy.allow_domains.length === 0)
+        return;
+    const base = {
+        runId: policy.runId,
+        stageId: policy.stageId,
+        ...(policy.profile !== undefined ? { profile: policy.profile } : {}),
+    };
+    let log;
+    try {
+        if (events === undefined)
+            throw new Error("no activity log available");
+        log = await events();
+    }
+    catch {
+        await safeAudit(sink, {
+            event: "allowlist_unverified",
+            ...base,
+            reason: "stage activity log unavailable; navigations were not checked",
+        });
+        return;
+    }
+    const seen = new Set();
+    for (const event of log) {
+        if (event.event !== "tool_start" || !event.argsPreview)
+            continue;
+        for (const match of event.argsPreview.matchAll(NAV_COMMAND)) {
+            const host = hostOf(match[1] ?? "");
+            if (host === undefined || allowed(host, policy.allow_domains))
+                continue;
+            if (seen.has(host))
+                continue;
+            seen.add(host);
+            await safeAudit(sink, { event: "navigation_outside_allowlist", ...base, host });
+        }
+    }
+}

package/dist/browser/persistedEnv.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserEnv } from "./browserHost.js";
+/** Reads a persisted browser env; undefined when absent, throws on other I/O errors. */
+export declare function readPersistedBrowserEnv(file: string): Promise<BrowserEnv | undefined>;