stageflow 0.25.0 → 0.30.0

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>;

package/dist/browser/persistedEnv.js

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+/** Reads a persisted browser env; undefined when absent, throws on other I/O errors. */
+export async function readPersistedBrowserEnv(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return undefined;
+}

package/dist/browser/profileLock.d.ts

@@ -0,0 +1,40 @@
+import { type ProfileKey } from "./profileStore.js";
+/**
+ * A profile is leased to a run. `stageId` is informational (the stage that
+ * first took the lease) and never part of identity.
+ */
+export type ProfileLockOwner = {
+    runId: string;
+    stageId?: string;
+};
+export type ProfileLockAcquireResult = {
+    status: "acquired";
+    release(): Promise<void>;
+} | {
+    status: "queued";
+    holder: ProfileLockOwner;
+};
+export type RunLiveness = (runId: string) => Promise<boolean>;
+export interface ProfileLock {
+    /**
+     * Any stage of the holder run joins the lease and succeeds at once. A
+     * profile leased to another run returns `queued` with the holder; callers retry.
+     */
+    acquire(key: ProfileKey, owner: ProfileLockOwner): Promise<ProfileLockAcquireResult>;
+    holder(key: ProfileKey): Promise<ProfileLockOwner | undefined>;
+    /** Releases every lease held by this run (run end, cancel, abandon, failure). */
+    releaseOwner(owner: {
+        runId: string;
+    }): Promise<void>;
+    /** Drops locks whose holder run is no longer live; returns the count dropped. */
+    reclaimStale(isRunLive: RunLiveness): Promise<number>;
+}
+export type ProfileLockOptions = {
+    /** When set, `acquire` reclaims a lock whose holder run is not live. */
+    isRunLive?: RunLiveness;
+};
+export declare function sameOwner(a: ProfileLockOwner, b: ProfileLockOwner): boolean;
+export declare function lockKey(key: ProfileKey): ProfileKey;
+export declare function ownerMatches(held: ProfileLockOwner, target: {
+    runId: string;
+}): boolean;

package/dist/browser/profileLock.js

@@ -0,0 +1,10 @@
+import { validateProfileKey } from "./profileStore.js";
+export function sameOwner(a, b) {
+    return a.runId === b.runId;
+}
+export function lockKey(key) {
+    return validateProfileKey(key);
+}
+export function ownerMatches(held, target) {
+    return held.runId === target.runId;
+}

package/dist/browser/profileStore.d.ts

@@ -0,0 +1,23 @@
+export declare const LOCAL_BROWSER_SCOPE = "local";
+export interface ProfileKey {
+    scope: string;
+    name: string;
+}
+export interface ProfileHandle {
+    key: ProfileKey;
+    profileDir: string;
+    stateDir: string;
+}
+export interface ProfileStore {
+    open(key: ProfileKey): Promise<ProfileHandle>;
+    list(scope: string): Promise<string[]>;
+    delete(key: ProfileKey): Promise<void>;
+    deleteScope(scope: string): Promise<void>;
+}
+export declare class InvalidProfileKeyError extends Error {
+    readonly code = "invalid_profile_key";
+    constructor(message: string);
+}
+export declare function validateProfileName(name: unknown): string;
+export declare function validateProfileScope(scope: unknown): string;
+export declare function validateProfileKey(key: ProfileKey): ProfileKey;

package/dist/browser/profileStore.js

@@ -0,0 +1,39 @@
+// TODO(multi-tenant): this fixed scope is the single local owner. Callers import it instead of
+// receiving a scope from the run, so profiles, locks and CLI commands always use "local".
+// A hosted service must give every run an owner scope (set by the Host from the authenticated
+// user, never from YAML) and pass it down. Find every call site with: grep -rn "LOCAL_BROWSER_SCOPE" src
+// See docs/browser-internals.md, "Known limitations" item 3.
+export const LOCAL_BROWSER_SCOPE = "local";
+export class InvalidProfileKeyError extends Error {
+    code = "invalid_profile_key";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidProfileKeyError";
+    }
+}
+const MAX_SEGMENT_LENGTH = 64;
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function validateSegment(label, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new InvalidProfileKeyError(`Profile ${label} must be a non-empty string`);
+    }
+    if (value.length > MAX_SEGMENT_LENGTH) {
+        throw new InvalidProfileKeyError(`Profile ${label} must be at most ${MAX_SEGMENT_LENGTH} characters`);
+    }
+    if (!SEGMENT_PATTERN.test(value) || value.includes("..")) {
+        throw new InvalidProfileKeyError(`Profile ${label} "${value}" may only use letters, digits, ".", "_" and "-", must start with a letter or digit, and must not contain ".."`);
+    }
+    return value;
+}
+export function validateProfileName(name) {
+    return validateSegment("name", name);
+}
+export function validateProfileScope(scope) {
+    return validateSegment("scope", scope);
+}
+export function validateProfileKey(key) {
+    return {
+        scope: validateProfileScope(key?.scope),
+        name: validateProfileName(key?.name),
+    };
+}

package/dist/browser/runLiveness.d.ts

@@ -0,0 +1,13 @@
+import type { RunStatus } from "../runstore/port.js";
+import type { RunLiveness } from "./profileLock.js";
+/**
+ * A run is live while it can still use its browser: not yet terminal. Runs
+ * waiting at a gate keep status "running", so they stay live.
+ */
+export declare function createRunLiveness(source: {
+    readRunMeta(runId: string): Promise<{
+        status?: RunStatus;
+    }>;
+}): RunLiveness;
+/** `cli-<pid>-...` runs are live while that process is; undefined for other run ids. */
+export declare function cliRunLive(runId: string): boolean | undefined;

package/dist/browser/runLiveness.js

@@ -0,0 +1,39 @@
+/**
+ * A run is live while it can still use its browser: not yet terminal. Runs
+ * waiting at a gate keep status "running", so they stay live.
+ */
+export function createRunLiveness(source) {
+    return async (runId) => {
+        const cli = cliRunLive(runId);
+        if (cli !== undefined)
+            return cli;
+        try {
+            const status = (await source.readRunMeta(runId)).status;
+            return (status === undefined ||
+                status === "created" ||
+                status === "queued" ||
+                status === "running");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            if (/not found/i.test(String(err?.message)))
+                return false;
+            throw err;
+        }
+    };
+}
+/** `cli-<pid>-...` runs are live while that process is; undefined for other run ids. */
+export function cliRunLive(runId) {
+    const match = /^cli-(\d+)-/.exec(runId);
+    return match === null ? undefined : pidAlive(Number(match[1]));
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}

package/dist/browser/sitePolicy.d.ts

@@ -0,0 +1,10 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+export declare class BlockedSiteError extends Error {
+    readonly code = "browser_site_blocked";
+    constructor(message: string);
+}
+export declare function normalizeDomain(raw: string): string;
+export declare function hostOf(urlOrHost: string): string | undefined;
+export declare function isBlockedHost(host: string, blocked: readonly string[]): string | undefined;
+/** Throws when the stage's allow_domains or check URLs touch a Host-blocked site. */
+export declare function assertBrowserSitesAllowed(stageId: string, browser: StageBrowserConfig, blocked: readonly string[]): void;