@aitne/daemon 0.1.7 → 0.1.9

package/dist/services/browser-history/managed-chromium/sandbox-install.js

@@ -0,0 +1,123 @@
+/**
+ * Sandbox-asset installer.
+ *
+ * The bundled `agent-assets/sandbox/macos/aitne-chromium.sb` template
+ * contains four placeholders (`%binary_path%`, `%binary_bundle%`,
+ * `%user_data_dir%`, `%ancestor_metadata_literals%`) that must be
+ * substituted with install-time-resolved values before `sandbox-exec`
+ * will load the profile. Substitution is done once at install time and
+ * the result is written to `<PA_DATA_DIR>/sandbox/aitne-chromium.sb`,
+ * which `resolveSandboxPrimitive` then references through
+ * `SandboxPrimitive.profilePath`.
+ *
+ * Idempotent: re-runs overwrite the installed file in-place so binary
+ * upgrades (e.g. user reinstalls Chromium under a new path, or a
+ * Playwright bump moves chromium-NNNN to chromium-NNNN+1) propagate
+ * the next time the bootstrap or supervisor runs.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createLogger } from "../../../logging.js";
+import { chromiumBundleRoot } from "../lifecycle/platform.js";
+const logger = createLogger("managed-chromium-sandbox-install");
+/**
+ * Compute the chain of directory ancestors of an absolute path, from
+ * the top-level component down to (but excluding) the path itself and
+ * excluding `/`. For `/a/b/c` returns `["/a", "/a/b"]`. Used to emit
+ * one `(literal ...)` per ancestor under `(allow file-read-metadata
+ * ...)` so the sandboxed child can traverse to `%binary_bundle%` /
+ * `%user_data_dir%` — required on macOS 26+ where `(subpath ...)` no
+ * longer implicitly grants metadata on parents.
+ */
+export function pathAncestors(absolutePath) {
+    if (!absolutePath.startsWith("/")) {
+        throw new Error(`pathAncestors expects an absolute POSIX path, got: ${absolutePath}`);
+    }
+    const parts = absolutePath.split("/").filter((segment) => segment.length > 0);
+    if (parts.length <= 1)
+        return [];
+    parts.pop();
+    const out = [];
+    let acc = "";
+    for (const segment of parts) {
+        acc = `${acc}/${segment}`;
+        out.push(acc);
+    }
+    return out;
+}
+/**
+ * Escape a path for embedding inside a sandbox profile double-quoted
+ * `(literal "...")` form. macOS sandbox profile strings support
+ * backslash-escaped `"` and `\`. POSIX paths almost never contain
+ * either, but escape defensively so a Playwright cache dir with an
+ * adversarial name cannot break out of the literal.
+ */
+export function escapeSandboxLiteral(path) {
+    return path.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Render the `%ancestor_metadata_literals%` substitution block: the
+ * deduped + sorted union of `pathAncestors(...)` across the supplied
+ * paths, one indented `(literal "...")` per line. If the union is
+ * empty (every input was at the filesystem root) we emit a single
+ * `(literal "/")` so the `(allow file-read-metadata ...)` form stays
+ * syntactically valid — granting metadata on `/` is redundant with
+ * the existing `file-read*` rule, so this is a safe no-op.
+ */
+export function renderAncestorMetadataLiterals(paths, indent = "  ") {
+    const set = new Set();
+    for (const p of paths) {
+        for (const a of pathAncestors(p))
+            set.add(a);
+    }
+    const sorted = [...set].sort();
+    const lines = sorted.length === 0 ? ["/"] : sorted;
+    return lines
+        .map((p) => `${indent}(literal "${escapeSandboxLiteral(p)}")`)
+        .join("\n");
+}
+const ASSET_ROOT_FROM_DIST = resolve(fileURLToPath(import.meta.url), "..", "..", "..", "..", "..", "..", "..", "agent-assets", "sandbox");
+/**
+ * Install / refresh the macOS sandbox-exec profile. Returns the
+ * absolute path of the rendered file so the caller can plug it into
+ * `SandboxPrimitive.profilePath`. No-op on non-darwin platforms.
+ */
+export async function installSandboxExecProfile(ctx) {
+    if (process.platform !== "darwin") {
+        throw new Error("installSandboxExecProfile is darwin-only");
+    }
+    const templatePath = join(ASSET_ROOT_FROM_DIST, "macos", "aitne-chromium.sb");
+    const template = await readFile(templatePath, "utf8");
+    const bundle = chromiumBundleRoot(ctx.binaryPath);
+    const ancestorLiterals = renderAncestorMetadataLiterals([
+        bundle,
+        ctx.userDataDir,
+    ]);
+    const rendered = template
+        .replaceAll("%binary_path%", escapeSandboxLiteral(ctx.binaryPath))
+        .replaceAll("%binary_bundle%", escapeSandboxLiteral(bundle))
+        .replaceAll("%user_data_dir%", escapeSandboxLiteral(ctx.userDataDir))
+        .replaceAll("%ancestor_metadata_literals%", ancestorLiterals);
+    const outDir = join(ctx.paDataDir, "sandbox");
+    await mkdir(outDir, { recursive: true });
+    const outPath = join(outDir, "aitne-chromium.sb");
+    await writeFile(outPath, rendered, { mode: 0o600 });
+    logger.info({ outPath }, "installed sandbox-exec profile");
+    return outPath;
+}
+/**
+ * Resolve the sandbox primitive into a launch-ready shape:
+ *   - macOS: copy the .sb template with placeholders substituted and
+ *     return a primitive whose `profilePath` references the rendered
+ *     file under PA_DATA_DIR/sandbox/.
+ *   - Linux / Windows / none: pass through unchanged (the launcher's
+ *     argv builders consume the same shape they had on input).
+ */
+export async function materialiseSandboxPrimitive(raw, ctx) {
+    if (raw.kind === "sandbox-exec") {
+        const profilePath = await installSandboxExecProfile(ctx);
+        return { kind: "sandbox-exec", profilePath };
+    }
+    return raw;
+}

package/dist/services/browser-history/managed-chromium/sandbox-launcher.d.ts

@@ -0,0 +1,117 @@
+/**
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.4 / §7.4 — OS-specific
+ * sandbox primitive wrappers.
+ *
+ * `launchUnderSandbox` is the single chokepoint every managed-chromium
+ * spawn goes through (Instance S supervisor cycles, bootstrap UI
+ * window, Instance A workflows in B-2). Argv shaping per primitive is
+ * data-driven so each branch stays small and individually testable.
+ *
+ * Defence layering:
+ *   1. The OS-level sandbox (sandbox-exec / bwrap / systemd-run /
+ *      AppContainer) is the outer ring — Chromium itself cannot reach
+ *      arbitrary network destinations or filesystem paths even if a
+ *      page tries to escape.
+ *   2. Inside the sandbox, Chromium's own renderer sandbox is a second
+ *      ring.
+ *   3. Per-workflow CDP `Network.setRequestInterception` (B-2) is the
+ *      innermost ring.
+ */
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { SandboxPrimitive } from "../types.js";
+export interface SandboxLaunchOptions {
+    binary: string;
+    args: readonly string[];
+    /** Bind-mounts / allowlisted dirs for the bwrap branch. */
+    readableBindings?: readonly string[];
+    /** Read-write bind-mounts. Currently only the per-profile user data
+     *  dir. */
+    writableBindings?: readonly string[];
+    /** Spawn options forwarded to `child_process.spawn`. */
+    spawnOptions?: SpawnOptions;
+    /** Whether the spawned child is a detached background process the
+     *  daemon does not own (sets `detached: true`, `stdio: "ignore"`,
+     *  `unref()`). Bootstrap UI windows set this to `false` so the
+     *  daemon can SIGTERM them at the end of sign-in. */
+    detached?: boolean;
+}
+export interface SandboxLaunchResult {
+    child: ChildProcess;
+    /** The argv0 the OS will see — useful for telemetry / ps inspection. */
+    spawnedAs: string;
+    /** Full argv. */
+    spawnedArgs: readonly string[];
+}
+/**
+ * Dispatch on `sandbox.kind` and spawn the Chromium binary under the
+ * matching primitive. Throws (or returns a non-pid-bearing child) if
+ * the primitive's wrapper binary is missing — callers must handle the
+ * `child.on("error")` path.
+ */
+export declare function launchUnderSandbox(sandbox: SandboxPrimitive, options: SandboxLaunchOptions): SandboxLaunchResult;
+/**
+ * macOS `sandbox-exec` argv: `["-f", profile, binary, ...args]`. The
+ * profile path is resolved by `sandbox-install.ts` (copies the bundled
+ * `agent-assets/sandbox/macos/aitne-chromium.sb` into PA_DATA_DIR so
+ * Apple's signature-validating wrapper can read it from a
+ * non-quarantined location).
+ *
+ * On macOS 26+ (when `tahoeOrLater()` returns true) the launcher
+ * injects `--no-sandbox` ahead of the caller's argv. Apple's
+ * `forbidden-sandbox-reinit` default-deny in Tahoe makes Chromium's
+ * middle-ring helper sandboxes (`sandbox_init_with_parameters`) abort
+ * unconditionally — see `darwinTahoeOrLater` in
+ * `lifecycle/platform.ts` for the full rationale. The outer
+ * sandbox-exec ring + the inner CDP route filter remain in force; the
+ * middle ring is dropped because the OS no longer permits it. The
+ * `tahoeOrLater` parameter is exposed for unit-testing so the launcher
+ * can be exercised independently of the host's actual macOS version.
+ */
+export declare function buildSandboxExecArgs(profilePath: string, options: SandboxLaunchOptions, tahoeOrLater?: () => boolean): string[];
+/**
+ * bwrap argv: deny-by-default with explicit `--ro-bind` / `--bind` for
+ * each path the browser needs.
+ *
+ *   --die-with-parent       — child exits when daemon does
+ *   --new-session           — own session so a runaway browser cannot
+ *                              reach the daemon's tty
+ *   --unshare-all           — start with everything unshared
+ *   --share-net             — re-share network (Chromium needs it; the
+ *                              CDP interception layer is the innermost
+ *                              ring per the plan)
+ *   --proc /proc            — minimal procfs
+ *   --dev /dev              — minimal devfs (needed for /dev/null,
+ *                              /dev/urandom, /dev/shm)
+ *   --tmpfs /tmp            — private writable tmp
+ *   --ro-bind <bin> <bin>   — read-only access to /usr (always present);
+ *                              /bin, /lib* are best-effort (--ro-bind-try)
+ *                              to accommodate merged-/usr layouts where they
+ *                              exist only via /usr and lack compat symlinks
+ *   --bind <profile> <profile> — read-write access to the per-instance
+ *                              user data dir only
+ */
+export declare function buildBwrapArgs(options: SandboxLaunchOptions): string[];
+/**
+ * systemd-run argv: transient user-scope unit with cgroup-level
+ * resource ceilings + private filesystem hooks. Less hermetic than
+ * bwrap (no namespace unshare) but available on hosts where bwrap is
+ * not installed.
+ *
+ *   --user --scope               — run as a transient scope under the
+ *                                   caller's user manager (no root)
+ *   --quiet                      — no systemctl chatter on stdout
+ *   --collect                    — discard scope unit on exit
+ *   --property=MemoryMax=…       — cgroup memory ceiling
+ *   --property=TasksMax=…        — cgroup process-count ceiling
+ *   --property=PrivateTmp=true   — private /tmp
+ *   --property=ProtectSystem=strict — read-only /usr, /boot, /etc
+ *   --property=ProtectHome=read-only — read-only $HOME except writable
+ *                                       binds added below
+ *   --property=NoNewPrivileges=true — block setuid/setgid escalation
+ */
+export declare function buildSystemdRunArgs(options: SandboxLaunchOptions): string[];
+export declare const __testing: {
+    buildSandboxExecArgs: typeof buildSandboxExecArgs;
+    buildBwrapArgs: typeof buildBwrapArgs;
+    buildSystemdRunArgs: typeof buildSystemdRunArgs;
+};

package/dist/services/browser-history/managed-chromium/sandbox-launcher.js

@@ -0,0 +1,244 @@
+/**
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.4 / §7.4 — OS-specific
+ * sandbox primitive wrappers.
+ *
+ * `launchUnderSandbox` is the single chokepoint every managed-chromium
+ * spawn goes through (Instance S supervisor cycles, bootstrap UI
+ * window, Instance A workflows in B-2). Argv shaping per primitive is
+ * data-driven so each branch stays small and individually testable.
+ *
+ * Defence layering:
+ *   1. The OS-level sandbox (sandbox-exec / bwrap / systemd-run /
+ *      AppContainer) is the outer ring — Chromium itself cannot reach
+ *      arbitrary network destinations or filesystem paths even if a
+ *      page tries to escape.
+ *   2. Inside the sandbox, Chromium's own renderer sandbox is a second
+ *      ring.
+ *   3. Per-workflow CDP `Network.setRequestInterception` (B-2) is the
+ *      innermost ring.
+ */
+import { spawn, } from "node:child_process";
+import { createRequire } from "node:module";
+import { darwinTahoeOrLater } from "../lifecycle/platform.js";
+/**
+ * Dispatch on `sandbox.kind` and spawn the Chromium binary under the
+ * matching primitive. Throws (or returns a non-pid-bearing child) if
+ * the primitive's wrapper binary is missing — callers must handle the
+ * `child.on("error")` path.
+ */
+export function launchUnderSandbox(sandbox, options) {
+    const baseSpawnOptions = {
+        ...(options.spawnOptions ?? {}),
+        detached: options.detached ?? false,
+        stdio: options.detached ? "ignore" : (options.spawnOptions?.stdio ?? "ignore"),
+        windowsHide: true,
+    };
+    switch (sandbox.kind) {
+        case "sandbox-exec": {
+            const argv = buildSandboxExecArgs(sandbox.profilePath, options);
+            return finalise(spawn("/usr/bin/sandbox-exec", argv, baseSpawnOptions), "/usr/bin/sandbox-exec", argv, options.detached);
+        }
+        case "bubblewrap": {
+            const argv = buildBwrapArgs(options);
+            return finalise(spawn("bwrap", argv, baseSpawnOptions), "bwrap", argv, options.detached);
+        }
+        case "systemd-run": {
+            const argv = buildSystemdRunArgs(options);
+            return finalise(spawn("systemd-run", argv, baseSpawnOptions), "systemd-run", argv, options.detached);
+        }
+        case "appcontainer-jobobject": {
+            // The Windows native helper exposes a JS-callable spawn function
+            // that internally calls CreateProcessAsUser + AssignProcessToJob
+            // Object. Loaded lazily so non-Windows builds do not require the
+            // native binding (which only compiles on win32 + msvc).
+            const native = loadWindowsHelper();
+            const child = native.spawnInAppContainer({
+                profileName: sandbox.profileName,
+                binary: options.binary,
+                args: options.args,
+                detached: options.detached === true,
+                readableBindings: options.readableBindings ?? [],
+                writableBindings: options.writableBindings ?? [],
+            });
+            return { child, spawnedAs: options.binary, spawnedArgs: [...options.args] };
+        }
+        case "none": {
+            // Unsandboxed — operator must have explicitly opted in. The
+            // bootstrap module is the gate; this launcher trusts that gate
+            // was passed.
+            return finalise(spawn(options.binary, [...options.args], baseSpawnOptions), options.binary, [...options.args], options.detached);
+        }
+    }
+}
+function finalise(child, spawnedAs, argv, detached) {
+    if (detached) {
+        try {
+            child.unref();
+        }
+        catch {
+            // unref is best-effort — if the spawn already errored, there is
+            // nothing to unref.
+        }
+    }
+    return { child, spawnedAs, spawnedArgs: argv };
+}
+/**
+ * macOS `sandbox-exec` argv: `["-f", profile, binary, ...args]`. The
+ * profile path is resolved by `sandbox-install.ts` (copies the bundled
+ * `agent-assets/sandbox/macos/aitne-chromium.sb` into PA_DATA_DIR so
+ * Apple's signature-validating wrapper can read it from a
+ * non-quarantined location).
+ *
+ * On macOS 26+ (when `tahoeOrLater()` returns true) the launcher
+ * injects `--no-sandbox` ahead of the caller's argv. Apple's
+ * `forbidden-sandbox-reinit` default-deny in Tahoe makes Chromium's
+ * middle-ring helper sandboxes (`sandbox_init_with_parameters`) abort
+ * unconditionally — see `darwinTahoeOrLater` in
+ * `lifecycle/platform.ts` for the full rationale. The outer
+ * sandbox-exec ring + the inner CDP route filter remain in force; the
+ * middle ring is dropped because the OS no longer permits it. The
+ * `tahoeOrLater` parameter is exposed for unit-testing so the launcher
+ * can be exercised independently of the host's actual macOS version.
+ */
+export function buildSandboxExecArgs(profilePath, options, tahoeOrLater = darwinTahoeOrLater) {
+    if (!profilePath) {
+        throw new Error("sandbox-exec profile path is empty; sandbox-install must run before launch");
+    }
+    const chromiumArgs = tahoeOrLater()
+        ? ["--no-sandbox", ...options.args]
+        : [...options.args];
+    return ["-f", profilePath, options.binary, ...chromiumArgs];
+}
+/**
+ * bwrap argv: deny-by-default with explicit `--ro-bind` / `--bind` for
+ * each path the browser needs.
+ *
+ *   --die-with-parent       — child exits when daemon does
+ *   --new-session           — own session so a runaway browser cannot
+ *                              reach the daemon's tty
+ *   --unshare-all           — start with everything unshared
+ *   --share-net             — re-share network (Chromium needs it; the
+ *                              CDP interception layer is the innermost
+ *                              ring per the plan)
+ *   --proc /proc            — minimal procfs
+ *   --dev /dev              — minimal devfs (needed for /dev/null,
+ *                              /dev/urandom, /dev/shm)
+ *   --tmpfs /tmp            — private writable tmp
+ *   --ro-bind <bin> <bin>   — read-only access to /usr (always present);
+ *                              /bin, /lib* are best-effort (--ro-bind-try)
+ *                              to accommodate merged-/usr layouts where they
+ *                              exist only via /usr and lack compat symlinks
+ *   --bind <profile> <profile> — read-write access to the per-instance
+ *                              user data dir only
+ */
+export function buildBwrapArgs(options) {
+    const argv = [
+        "--die-with-parent",
+        "--new-session",
+        "--unshare-all",
+        "--share-net",
+        "--proc", "/proc",
+        "--dev", "/dev",
+        "--tmpfs", "/tmp",
+        "--tmpfs", "/run",
+        "--ro-bind", "/usr", "/usr",
+        "--ro-bind-try", "/bin", "/bin",
+        "--ro-bind-try", "/lib", "/lib",
+        "--ro-bind-try", "/lib64", "/lib64",
+        "--ro-bind-try", "/lib32", "/lib32",
+        "--ro-bind-try", "/etc/resolv.conf", "/etc/resolv.conf",
+        "--ro-bind-try", "/etc/ssl", "/etc/ssl",
+        "--ro-bind-try", "/etc/ca-certificates", "/etc/ca-certificates",
+        "--ro-bind-try", "/etc/fonts", "/etc/fonts",
+        "--ro-bind-try", "/usr/share/fonts", "/usr/share/fonts",
+        "--ro-bind-try", "/var/lib/dbus", "/var/lib/dbus",
+        "--setenv", "HOME", "/tmp",
+        "--setenv", "XDG_RUNTIME_DIR", "/run",
+        "--setenv", "DISPLAY", process.env.DISPLAY ?? "",
+        "--setenv", "WAYLAND_DISPLAY", process.env.WAYLAND_DISPLAY ?? "",
+    ];
+    for (const path of options.readableBindings ?? []) {
+        argv.push("--ro-bind-try", path, path);
+    }
+    for (const path of options.writableBindings ?? []) {
+        argv.push("--bind-try", path, path);
+    }
+    argv.push("--", options.binary, ...options.args);
+    return argv;
+}
+/**
+ * systemd-run argv: transient user-scope unit with cgroup-level
+ * resource ceilings + private filesystem hooks. Less hermetic than
+ * bwrap (no namespace unshare) but available on hosts where bwrap is
+ * not installed.
+ *
+ *   --user --scope               — run as a transient scope under the
+ *                                   caller's user manager (no root)
+ *   --quiet                      — no systemctl chatter on stdout
+ *   --collect                    — discard scope unit on exit
+ *   --property=MemoryMax=…       — cgroup memory ceiling
+ *   --property=TasksMax=…        — cgroup process-count ceiling
+ *   --property=PrivateTmp=true   — private /tmp
+ *   --property=ProtectSystem=strict — read-only /usr, /boot, /etc
+ *   --property=ProtectHome=read-only — read-only $HOME except writable
+ *                                       binds added below
+ *   --property=NoNewPrivileges=true — block setuid/setgid escalation
+ */
+export function buildSystemdRunArgs(options) {
+    const argv = [
+        "--user",
+        "--scope",
+        "--quiet",
+        "--collect",
+        "--property=MemoryMax=2G",
+        "--property=TasksMax=2048",
+        "--property=PrivateTmp=true",
+        "--property=ProtectSystem=strict",
+        "--property=ProtectHome=read-only",
+        "--property=NoNewPrivileges=true",
+        "--property=LockPersonality=true",
+        "--property=RestrictNamespaces=true",
+        "--property=RestrictRealtime=true",
+        "--property=RestrictSUIDSGID=true",
+    ];
+    // One --property per path: systemd merges repeated list-type unit
+    // properties, so this sidesteps the whitespace-split ambiguity of a
+    // space-joined list value (a path containing a space would otherwise be
+    // parsed as two bogus entries, leaving the profile dir non-writable).
+    const writable = options.writableBindings ?? [];
+    for (const p of writable) {
+        argv.push(`--property=ReadWritePaths=${p}`);
+    }
+    const readable = options.readableBindings ?? [];
+    for (const p of readable) {
+        argv.push(`--property=ReadOnlyPaths=${p}`);
+    }
+    argv.push("--", options.binary, ...options.args);
+    return argv;
+}
+/**
+ * Lazy require of the native binding. On non-Windows hosts (dev / CI)
+ * the binding is not built; the helper falls back to a no-op that
+ * surfaces a clear runtime error so a test accidentally exercising the
+ * appcontainer branch outside Windows fails loudly.
+ */
+function loadWindowsHelper() {
+    if (process.platform !== "win32") {
+        throw new Error("appcontainer-jobobject sandbox primitive is only available on Windows");
+    }
+    // The native binding is loaded via the package barrel `./loader.js`
+    // which falls back gracefully when the .node addon is missing
+    // (fresh source checkout before `npm rebuild`). The daemon ships as
+    // ESM (`"type": "module"`, tsc `module: ES2022`), so `require` is not
+    // a module-scope global — build one via `createRequire` to reach the
+    // CommonJS loader. This branch only runs on win32.
+    const req = createRequire(import.meta.url);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = req("../../../../native/win-appcontainer/loader.js");
+    return mod.loadHelper();
+}
+export const __testing = {
+    buildSandboxExecArgs,
+    buildBwrapArgs,
+    buildSystemdRunArgs,
+};

package/dist/services/browser-history/managed-chromium/setup-bootstrap.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Bootstrap (one-time interactive sign-in) for Instance S.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §7.3.
+ *
+ * Spawn a UI Chromium under the sandbox primitive, open Google's
+ * sign-in URL, persist the PID + deadline into runtime_state. The
+ * dashboard polls status until `Local State` reports a signed-in
+ * username; finalize SIGTERMs the UI window and flips state to
+ * `ready`. An orphan reaper sweeps past-deadline PIDs on every
+ * supervisor tick so an abandoned bootstrap can't leak a UI Chromium
+ * forever.
+ */
+import type Database from "better-sqlite3";
+import type { HostProfile, SandboxPrimitive } from "../types.js";
+import { launchUnderSandbox } from "./sandbox-launcher.js";
+export interface BootstrapDeps {
+    db: Database.Database;
+    host: HostProfile;
+    paDataDir: string;
+    /** Allows tests to inject a clock. */
+    now?: () => number;
+    /** Allows tests to override the timeout. */
+    timeoutMs?: number;
+    /** Allows tests to inject a launcher. */
+    launcher?: typeof launchUnderSandbox;
+    /** Allows tests to skip the real sandbox materialisation. */
+    resolveSandbox?: (raw: SandboxPrimitive) => Promise<SandboxPrimitive>;
+}
+export interface BootstrapStartResult {
+    ok: boolean;
+    pid: number | null;
+    deadlineAt: number | null;
+    reason?: "missing_binary" | "missing_sandbox" | "spawn_failed" | "already_running";
+}
+/**
+ * Start a UI Chromium for interactive sign-in. Two modes:
+ *   - `reauth=false`: assert the profile dir is empty (refuses if the
+ *     dir already holds a signed-in profile, to avoid the
+ *     "two-profiles-collide" failure mode).
+ *   - `reauth=true`: re-uses the existing profile dir so Chromium can
+ *     drive auto-sign-in / 2FA reprompt.
+ */
+export declare function startBootstrap(deps: BootstrapDeps, opts: {
+    reauth: boolean;
+}): Promise<BootstrapStartResult>;
+export type BootstrapStatus = {
+    state: "idle";
+} | {
+    state: "running";
+    pid: number;
+    deadlineAt: number;
+    signedIn: false;
+} | {
+    state: "running";
+    pid: number;
+    deadlineAt: number;
+    signedIn: true;
+    observedUser: string;
+};
+export declare function getBootstrapStatus(deps: Pick<BootstrapDeps, "db" | "paDataDir">): Promise<BootstrapStatus>;
+export interface FinalizeBootstrapResult {
+    ok: boolean;
+    reason?: "not_running" | "not_signed_in";
+    observedUser?: string;
+}
+/**
+ * Finalize bootstrap: SIGTERM the UI Chromium, flip state to `ready`,
+ * record the observed signed-in user. Caller (the API route) is
+ * responsible for following up with supervisor re-registration so the
+ * next tick picks up the new profile.
+ */
+export declare function finalizeBootstrap(deps: BootstrapDeps): Promise<FinalizeBootstrapResult>;
+/**
+ * Orphan reaper. Called from the supervisor's per-cycle hook. Looks at
+ * `runtime_state.managed_chromium.bootstrap`; if `deadlineAt < now`
+ * the orphan Chromium is SIGKILLed and state is reset to `needs_setup`
+ * so the dashboard prompts the user to re-start.
+ */
+export declare function reapStaleBootstrap(deps: BootstrapDeps): Promise<{
+    reaped: boolean;
+}>;
+/**
+ * User-initiated disconnect. SIGKILLs any running Chromium for this
+ * profile and removes the profile dir. The caller (API route) deletes
+ * the runtime_state row afterwards.
+ *
+ * Active termination is mandatory here, NOT delegated to the supervisor
+ * — once the disconnect route flips `enabled=false`, the supervisor
+ * exits its cycle early and would never reap a leaked headless instance.
+ */
+export declare function disconnectInstanceS(deps: BootstrapDeps): Promise<void>;
+/**
+ * Find every Chromium process whose `--user-data-dir` points at the
+ * managed `chromium-sync/` profile and SIGKILL it. Used by the
+ * `/disconnect` and `/enable=false` paths so a leaked headless instance
+ * cannot survive the supervisor's `enabled` short-circuit.
+ *
+ * Best-effort: shells out to `ps` (or PowerShell on Windows) and parses
+ * matching PIDs. A missing tool or empty result is silent — there is
+ * nothing to do.
+ */
+export declare function killManagedChromiumBackground(host: HostProfile, binaryPath: string, paDataDir: string): Promise<void>;
+/**
+ * Enumerate Chromium PIDs whose `--user-data-dir` arg matches
+ * `userDataDir`. Exported so the B-4 boot-time orphan-purchase-Chromium
+ * sweep (MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 "Daemon crash
+ * during the 5-min window") can find every parked Chromium process
+ * under `chromium-automation-purchase/<siteKey>/` without duplicating
+ * the cross-platform `ps` / PowerShell shell-out logic.
+ */
+export declare function findChromiumPidsByUserDataDir(binaryPath: string, userDataDir: string): Promise<number[]>;
+/**
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.3 "Daemon crash during
+ * the 5-min window" — purge orphaned A-purchase Chromium processes.
+ *
+ * After a daemon restart, the SQL-level sweep
+ * (`sweepOrphanedConsumedPurchaseTokens` / `expireStalePurchaseTokens`)
+ * marks the abandoned token rows cancelled, but if a previous daemon
+ * process spawned an A-purchase Chromium (`detached: false`) that the
+ * parent's death didn't reliably terminate — Chromium spawns its own
+ * helper children, the OS may inherit the orphan, the user may have
+ * `nohup`'d the daemon, the launcher could have been suspended — that
+ * Chromium still holds an authenticated cart context and a CDP debug
+ * port open to localhost. Plan §17.3 row 7 specifies SIGKILL on those.
+ *
+ * Implementation: enumerate every direct subdirectory of
+ * `<PA_DATA_DIR>/chromium-automation-purchase/` (each is a `<siteKey>`),
+ * resolve its absolute path, and ask
+ * `findChromiumPidsByUserDataDir(binaryPath, dir)` for matching PIDs.
+ * SIGKILL each via the host abstraction. Best-effort: a missing
+ * directory, missing binary, or a `ps` shell-out failure is silent —
+ * the next workflow run reads the same DB state and the next sweep
+ * tick retries.
+ *
+ * Pure-ish: no DB writes; the SQL-level sweep is the source of truth
+ * for the row state.
+ */
+export declare function killOrphanedPurchaseChromium(host: HostProfile, paDataDir: string): Promise<{
+    killedPids: readonly number[];
+}>;
+declare function isProfileSignedIn(profileDir: string): Promise<boolean>;
+declare function readSignedInUser(profileDir: string): Promise<string | null>;
+export declare const __testing: {
+    GOOGLE_SIGN_IN_URL: string;
+    isProfileSignedIn: typeof isProfileSignedIn;
+    readSignedInUser: typeof readSignedInUser;
+};
+export {};