@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/managed-chromium/managed-chromium-supervisor.js

@@ -0,0 +1,334 @@
+/**
+ * Supervisor for Instance S (the managed sync-context Chromium).
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.1 / §7.1.
+ *
+ * Designed as a sibling Observer to the existing
+ * `BrowserLifecycleSupervisor` rather than an extension of it. The
+ * existing supervisor is detector-driven (it walks every Chromium-
+ * family install on the host and picks profiles it recognises); the
+ * managed instance is a fixed singleton with a known binary path and
+ * known user-data-dir. The cycle shape is similar but the data sources
+ * are different enough that an internal `managed: boolean` branch in
+ * the existing class would force every branch in every method to
+ * understand both modes. A sibling Observer is cleaner — it reuses the
+ * pure modules (failure-escalation, health-check, cleanup) without
+ * fighting the existing class's invariants.
+ */
+import { readManagedChromiumState, updateManagedChromiumState, } from "../../../db/managed-chromium-state.js";
+import { createLogger } from "../../../logging.js";
+import { chromiumBundleRoot, createHostProfile } from "../lifecycle/platform.js";
+import { cleanupStaleSingletonLock } from "../lifecycle/chromium-launcher.js";
+import { checkBrowserProfileHealth } from "../lifecycle/health-check.js";
+import { detectReauthState, } from "./reauth-detector.js";
+import { launchUnderSandbox } from "./sandbox-launcher.js";
+import { materialiseSandboxPrimitive } from "./sandbox-install.js";
+import { buildInstanceSConfig } from "./supervisor-config.js";
+import { reapStaleBootstrap } from "./setup-bootstrap.js";
+import { reapStaleSiteBootstrap } from "./site-bootstrap.js";
+import { listSiteBootstrapKeys } from "../../../db/managed-chromium-sites-store.js";
+import { DM_RATE_LIMIT_MS, DEFAULT_CHECK_INTERVAL_MINUTES, PAUSE_AFTER_FAILURES, PAUSE_DURATION_MS, } from "./types.js";
+const logger = createLogger("managed-chromium-supervisor");
+const DM_TEMPLATES = {
+    signed_out: () => "Managed Chromium is signed out — Chrome Sync is paused. Open the dashboard → Browser History (managed) → Reconnect to sign in again.",
+    account_changed: (detail) => `Managed Chromium account changed (${detail ?? "unknown"}). Sync is paused until you confirm via dashboard → Browser History (managed) → Reconnect.`,
+    corrupt_local_state: () => "Managed Chromium profile is unreadable. Open the dashboard → Browser History (managed) → Reconnect to repair.",
+    sync_silent: () => "Managed Chromium sync hasn't progressed for >6h. Open the dashboard → Browser History (managed) → Reconnect to re-authenticate.",
+};
+export class ManagedChromiumSupervisor {
+    deps;
+    name = "managed-chromium-supervisor";
+    timer = null;
+    running = false;
+    tickInFlight = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.deps.host = deps.host ?? createHostProfile();
+    }
+    async start() {
+        this.running = true;
+        void this.tick();
+        const intervalMin = this.deps.checkIntervalMinutes ?? DEFAULT_CHECK_INTERVAL_MINUTES;
+        this.timer = setInterval(() => void this.tick(), intervalMin * 60 * 1000);
+        this.timer.unref?.();
+        logger.info({ intervalMin }, "managed-chromium supervisor started");
+    }
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        logger.info("managed-chromium supervisor stopped");
+    }
+    /** Public for testing — runs a single supervisor cycle. */
+    async tick() {
+        if (!this.running || this.tickInFlight)
+            return;
+        this.tickInFlight = true;
+        try {
+            await this.cycleOnce();
+        }
+        catch (err) {
+            logger.error({ err }, "managed-chromium tick failed");
+        }
+        finally {
+            this.tickInFlight = false;
+        }
+    }
+    async cycleOnce() {
+        const state = readManagedChromiumState(this.deps.db);
+        if (!state.enabled)
+            return;
+        // Reap orphaned bootstrap UI windows BEFORE deciding what to do.
+        await reapStaleBootstrap({
+            db: this.deps.db,
+            host: this.deps.host,
+            paDataDir: this.deps.paDataDir,
+            now: this.deps.now,
+        });
+        // MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §16.3 — also sweep
+        // per-site B-2.5 bootstrap rows. Enumerating from the DB (rather
+        // than the registry) catches stale rows whose siteKey has been
+        // removed from the registry between releases; the reaper itself
+        // tolerates a vanished site by force-killing the PID + clearing
+        // the row regardless of whether `getSite` resolves it.
+        for (const siteKey of listSiteBootstrapKeys(this.deps.db)) {
+            try {
+                await reapStaleSiteBootstrap({
+                    db: this.deps.db,
+                    host: this.deps.host,
+                    paDataDir: this.deps.paDataDir,
+                    now: this.deps.now,
+                }, siteKey);
+            }
+            catch (err) {
+                logger.warn({ err, siteKey }, "per-site bootstrap reaper raised; continuing sweep");
+            }
+        }
+        let fresh = readManagedChromiumState(this.deps.db);
+        // Self-healing: re-evaluate infra readiness on every tick so a
+        // stuck `missing_binary` / `missing_sandbox` clears the moment the
+        // operator installs the missing dependency, without requiring a
+        // daemon restart. Mirrors the bootstrap-time pre-flight logic.
+        const host = this.deps.host;
+        const hasBinary = host.browserBinaryFor("chromium") !== null;
+        const hasSandbox = host.sandboxPrimitive.kind !== "none" || fresh.unsandboxedOptIn;
+        if (!hasBinary && fresh.state !== "missing_binary") {
+            updateManagedChromiumState(this.deps.db, (draft) => { draft.state = "missing_binary"; });
+            fresh = readManagedChromiumState(this.deps.db);
+        }
+        else if (hasBinary && !hasSandbox && fresh.state !== "missing_sandbox") {
+            updateManagedChromiumState(this.deps.db, (draft) => { draft.state = "missing_sandbox"; });
+            fresh = readManagedChromiumState(this.deps.db);
+        }
+        else if (hasBinary
+            && hasSandbox
+            && (fresh.state === "missing_binary" || fresh.state === "missing_sandbox")) {
+            updateManagedChromiumState(this.deps.db, (draft) => { draft.state = "needs_setup"; });
+            fresh = readManagedChromiumState(this.deps.db);
+        }
+        if (fresh.state === "off"
+            || fresh.state === "missing_binary"
+            || fresh.state === "missing_sandbox"
+            || fresh.state === "needs_setup"
+            || fresh.state === "disconnected") {
+            // Pre-ready states — supervisor has nothing to launch.
+            return;
+        }
+        const now = (this.deps.now ?? Date.now)();
+        if (fresh.pausedUntil && fresh.pausedUntil > now) {
+            // Paused after consecutive failures.
+            return;
+        }
+        const config = buildInstanceSConfig({
+            host,
+            paDataDir: this.deps.paDataDir,
+            sandbox: host.sandboxPrimitive,
+        });
+        if (!config) {
+            updateManagedChromiumState(this.deps.db, (draft) => {
+                draft.state = "missing_binary";
+            });
+            return;
+        }
+        // Health check FIRST — if Chromium is running and History is fresh,
+        // we don't need to launch.
+        const profileCandidate = pseudoProfileCandidate(config.binaryPath, config.userDataDir);
+        const health = await checkBrowserProfileHealth(host, profileCandidate, now);
+        let actionTaken = "noop";
+        let outcome = "success";
+        try {
+            if (!health.running) {
+                actionTaken = "launch";
+                await cleanupStaleSingletonLock(host, profileCandidate);
+                const sandbox = await (this.deps.resolveSandbox ?? materialiseSandboxPrimitive)(host.sandboxPrimitive, {
+                    paDataDir: this.deps.paDataDir,
+                    binaryPath: config.binaryPath,
+                    userDataDir: config.userDataDir,
+                });
+                const launcher = this.deps.launcher ?? launchUnderSandbox;
+                // The bundle root (parent dir of binary on Linux, .app root on
+                // macOS) is what bwrap / sandbox-exec actually needs to bind —
+                // binding just the entrypoint file leaves Chromium unable to
+                // load helpers and shared libs from its own install dir.
+                const child = launcher(sandbox, {
+                    binary: config.binaryPath,
+                    args: [...config.extraArgs],
+                    writableBindings: [config.userDataDir],
+                    readableBindings: [chromiumBundleRoot(config.binaryPath)],
+                    detached: true,
+                }).child;
+                if (!child.pid)
+                    outcome = "launch_failed";
+            }
+            // Reauth check runs even when we did not launch — Chromium may
+            // be up but signed out.
+            const reauth = await detectReauthState({
+                profileDir: config.userDataDir,
+                lastKnownSignedInUser: fresh.signedInUser,
+                now,
+            });
+            this.applyReauthResult(fresh, reauth, now, actionTaken, outcome);
+        }
+        catch (err) {
+            logger.error({ err }, "managed-chromium cycle errored");
+            this.applyOutcome(fresh, "error", now);
+        }
+        this.recordTelemetry({
+            action: actionTaken,
+            outcome,
+            lastSyncAt: health.historyMtimeMs,
+            syncAgeAtIngestSeconds: health.syncAgeSeconds,
+        });
+    }
+    applyReauthResult(prevState, reauth, now, actionTaken, outcome) {
+        if (reauth.kind === "healthy" && outcome === "success") {
+            updateManagedChromiumState(this.deps.db, (draft) => {
+                draft.lastCheckAt = now;
+                draft.signedInUser = reauth.observedUser ?? draft.signedInUser;
+                draft.consecutiveFailures = 0;
+                draft.pausedUntil = null;
+                if (draft.state !== "ready")
+                    draft.state = "ready";
+            });
+            return;
+        }
+        // Launch failed but the on-disk profile is fine — this is a spawn /
+        // sandbox problem (e.g. a transient sandbox-exec failure), NOT a
+        // sign-out. Bump failure counters so escalation/pause still fires,
+        // but do NOT tell the user to re-authenticate or flip state to
+        // needs_reauth (it stays "ready"); no reauth DM.
+        if (reauth.kind === "healthy") {
+            updateManagedChromiumState(this.deps.db, (draft) => {
+                draft.lastCheckAt = now;
+                const failures = draft.consecutiveFailures + 1;
+                draft.consecutiveFailures = failures;
+                if (failures >= PAUSE_AFTER_FAILURES) {
+                    draft.pausedUntil = now + PAUSE_DURATION_MS;
+                }
+            });
+            return;
+        }
+        // Non-healthy: the reauth-detector observed an explicit problem.
+        // Emit a DM (subject to per-kind cap) and update failure-escalation
+        // counters. `reauth.kind` is provably non-"healthy" here.
+        const dmKind = reauth.kind;
+        const lastDmAt = prevState.lastDmAt[dmKind] ?? 0;
+        const shouldDm = now - lastDmAt >= DM_RATE_LIMIT_MS;
+        if (shouldDm) {
+            void this.sendBrokenSyncDm(dmKind, reauth.detail).catch((err) => {
+                logger.warn({ err, dmKind }, "broken-sync DM dispatch failed");
+            });
+        }
+        updateManagedChromiumState(this.deps.db, (draft) => {
+            draft.state = "needs_reauth";
+            draft.lastCheckAt = now;
+            if (shouldDm)
+                draft.lastDmAt[dmKind] = now;
+            const failures = draft.consecutiveFailures + 1;
+            draft.consecutiveFailures = failures;
+            if (failures >= PAUSE_AFTER_FAILURES) {
+                draft.pausedUntil = now + PAUSE_DURATION_MS;
+            }
+        });
+        this.recordReauthAudit(dmKind, reauth.detail);
+    }
+    applyOutcome(_prev, outcome, now) {
+        updateManagedChromiumState(this.deps.db, (draft) => {
+            draft.lastCheckAt = now;
+            const failures = draft.consecutiveFailures + 1;
+            draft.consecutiveFailures = failures;
+            if (failures >= PAUSE_AFTER_FAILURES) {
+                draft.pausedUntil = now + PAUSE_DURATION_MS;
+            }
+        });
+        this.recordTelemetry({ action: "noop", outcome, lastSyncAt: null, syncAgeAtIngestSeconds: null });
+    }
+    async sendBrokenSyncDm(kind, detail) {
+        if (!this.deps.messageHub) {
+            logger.info({ kind }, "messageHub absent; skipping broken-sync DM");
+            return;
+        }
+        const body = DM_TEMPLATES[kind](detail);
+        await this.deps.messageHub.sendToUser(body, undefined, {
+            dispatchId: `managed-chromium-${kind}-${Date.now()}`,
+            notificationType: "managed_chromium_sync_broken",
+            priority: "P3",
+            contentSummary: body.slice(0, 120),
+        });
+    }
+    recordTelemetry(opts) {
+        try {
+            this.deps.db
+                .prepare(`INSERT INTO agent_actions
+             (action_type, trigger, result, detail, completed_at, source_kind)
+           VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP, ?)`)
+                .run("browser_lifecycle.chromium_sync", "browser_lifecycle", opts.outcome === "success" ? "success" : "failed", JSON.stringify({
+                action_taken: opts.action,
+                outcome: opts.outcome,
+                sync_mtime_after: opts.lastSyncAt,
+                sync_age_at_check_seconds: opts.syncAgeAtIngestSeconds,
+            }), "cron");
+        }
+        catch (err) {
+            logger.warn({ err }, "telemetry insert failed");
+        }
+    }
+    recordReauthAudit(kind, detail) {
+        try {
+            this.deps.db
+                .prepare(`INSERT INTO agent_actions
+             (action_type, trigger, result, detail, completed_at, source_kind)
+           VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP, ?)`)
+                .run("browser_history.sync_broken", "browser_lifecycle", "failed", JSON.stringify({ kind, detail }), "cron");
+        }
+        catch (err) {
+            logger.warn({ err }, "reauth audit insert failed");
+        }
+    }
+}
+/**
+ * The managed instance is a Chromium-family profile but it is NOT a
+ * detector-discovered one. We construct a synthetic
+ * `BrowserProfileCandidate` so the existing pure modules
+ * (`cleanupStaleSingletonLock`, `checkBrowserProfileHealth`) can be
+ * reused as-is. The synthetic shape is consumed only within this file
+ * — it is NOT registered with the detector / lifecycle store.
+ */
+function pseudoProfileCandidate(binaryPath, userDataDir) {
+    return {
+        browser: "chromium",
+        profileName: "Default",
+        userDataDir,
+        historyPath: `${userDataDir}/Default/History`,
+        localStatePath: `${userDataDir}/Local State`,
+        signedIn: true,
+        canonical: true,
+        lastHistoryMtimeMs: null,
+        // The detector type carries more fields than we need; the cast is
+        // intentional and isolated. If the type ever grows required fields
+        // the typecheck will surface here.
+    };
+}
+export const __testing = { pseudoProfileCandidate, DM_TEMPLATES };

package/dist/services/browser-history/managed-chromium/reauth-detector.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Re-authentication detector for Instance S.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §7.5. Runs once per
+ * supervisor cycle to decide whether Chrome Sync is healthy or whether
+ * the user needs to re-sign-in / re-authorise the OAuth token.
+ *
+ * Signals consumed (lowest cost first):
+ *   1. `Local State` JSON parses + carries a `signin.signed_in_to` /
+ *      `signin.signed_in_username` (key name varies by Chromium build;
+ *      we check both). Corrupt JSON → `corrupt_local_state`. Missing
+ *      sign-in → `signed_out`.
+ *   2. The signed-in username matches the one observed on the most
+ *      recent supervisor tick (`lastKnownSignedInUser`). Mismatch →
+ *      `account_changed` (a different user signed in via the UI; the
+ *      daemon's OAuth assumptions no longer hold).
+ *   3. `Default/History` file mtime has advanced within the past
+ *      6 hours OR the sync LevelDB has been written within the past
+ *      6 hours. Both stale → `sync_silent` (Chromium is running but
+ *      sync is not progressing).
+ *
+ * Pure module — no DB, no spawn, no IO outside `node:fs/promises`. The
+ * supervisor wraps the result with DM / state-transition logic.
+ */
+import { type ManagedChromiumReauthKind, type ManagedChromiumReauthState } from "./types.js";
+export interface ReauthDetectorInput {
+    profileDir: string;
+    /** Username last observed signed-in (or null on first tick). */
+    lastKnownSignedInUser: string | null;
+    /** Epoch ms; injectable for tests. */
+    now: number;
+    /** Mtime stall threshold; defaults to the 6h constant. */
+    syncSilentThresholdMs?: number;
+}
+export interface ReauthDetectorResult extends ManagedChromiumReauthState {
+    /** Username observed in `Local State` (or null if signed-out). */
+    observedUser: string | null;
+}
+export declare function detectReauthState(input: ReauthDetectorInput): Promise<ReauthDetectorResult>;
+/**
+ * Chromium's `Local State` carries the signed-in user under multiple
+ * keys depending on version. Probe both — the absence of all of them
+ * means signed-out, the presence of any non-empty one wins.
+ */
+export declare function extractSignedInUser(localState: Record<string, unknown>): string | null;
+/**
+ * Sync LevelDB lives at `Default/Sync Data/LevelDB/`. We walk one
+ * directory level to find the most recent write across `.ldb` /
+ * `MANIFEST-*` / `CURRENT` / `LOG`. Returns null when the directory or
+ * any of its files cannot be read.
+ *
+ * Implementation detail: we prefer the inner LevelDB directory and
+ * fall back to the parent `Sync Data` dir only when LevelDB is absent.
+ * Walking both candidates would shadow the inner-file mtime with the
+ * parent's own mtime — every write inside `LevelDB/` advances the
+ * `LevelDB` directory entry's mtime when listed from `Sync Data`, so
+ * the stall threshold would never fire under a merged max.
+ */
+export declare function mostRecentSyncLevelDbWrite(profileDir: string): Promise<number | null>;
+export type { ManagedChromiumReauthKind, ManagedChromiumReauthState };

package/dist/services/browser-history/managed-chromium/reauth-detector.js

@@ -0,0 +1,179 @@
+/**
+ * Re-authentication detector for Instance S.
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §7.5. Runs once per
+ * supervisor cycle to decide whether Chrome Sync is healthy or whether
+ * the user needs to re-sign-in / re-authorise the OAuth token.
+ *
+ * Signals consumed (lowest cost first):
+ *   1. `Local State` JSON parses + carries a `signin.signed_in_to` /
+ *      `signin.signed_in_username` (key name varies by Chromium build;
+ *      we check both). Corrupt JSON → `corrupt_local_state`. Missing
+ *      sign-in → `signed_out`.
+ *   2. The signed-in username matches the one observed on the most
+ *      recent supervisor tick (`lastKnownSignedInUser`). Mismatch →
+ *      `account_changed` (a different user signed in via the UI; the
+ *      daemon's OAuth assumptions no longer hold).
+ *   3. `Default/History` file mtime has advanced within the past
+ *      6 hours OR the sync LevelDB has been written within the past
+ *      6 hours. Both stale → `sync_silent` (Chromium is running but
+ *      sync is not progressing).
+ *
+ * Pure module — no DB, no spawn, no IO outside `node:fs/promises`. The
+ * supervisor wraps the result with DM / state-transition logic.
+ */
+import { stat } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SYNC_SILENT_THRESHOLD_MS, } from "./types.js";
+export async function detectReauthState(input) {
+    const localState = await readLocalState(input.profileDir);
+    if (localState === "missing") {
+        return {
+            kind: "signed_out",
+            observedUser: null,
+            detail: "Local State file missing",
+        };
+    }
+    if (localState === "corrupt") {
+        return {
+            kind: "corrupt_local_state",
+            observedUser: null,
+            detail: "Local State JSON unparseable",
+        };
+    }
+    const observedUser = extractSignedInUser(localState.parsed);
+    if (!observedUser) {
+        return { kind: "signed_out", observedUser: null };
+    }
+    if (input.lastKnownSignedInUser
+        && observedUser !== input.lastKnownSignedInUser) {
+        return {
+            kind: "account_changed",
+            to: observedUser,
+            observedUser,
+            detail: `Local State signin user changed from ${input.lastKnownSignedInUser} → ${observedUser}`,
+        };
+    }
+    const threshold = input.syncSilentThresholdMs ?? SYNC_SILENT_THRESHOLD_MS;
+    const stale = await detectSyncStall(input.profileDir, input.now, threshold);
+    if (stale.kind === "stall") {
+        return {
+            kind: "sync_silent",
+            observedUser,
+            detail: stale.detail,
+        };
+    }
+    return { kind: "healthy", observedUser };
+}
+async function readLocalState(profileDir) {
+    const path = join(profileDir, "Local State");
+    let buf;
+    try {
+        buf = await readFile(path, "utf8");
+    }
+    catch {
+        return "missing";
+    }
+    try {
+        const parsed = JSON.parse(buf);
+        if (typeof parsed !== "object" || parsed === null)
+            return "corrupt";
+        return { parsed };
+    }
+    catch {
+        return "corrupt";
+    }
+}
+/**
+ * Chromium's `Local State` carries the signed-in user under multiple
+ * keys depending on version. Probe both — the absence of all of them
+ * means signed-out, the presence of any non-empty one wins.
+ */
+export function extractSignedInUser(localState) {
+    const signin = localState["signin"];
+    if (signin && typeof signin === "object") {
+        const obj = signin;
+        for (const key of ["signed_in_to", "signed_in_username", "allowed_username"]) {
+            const v = obj[key];
+            if (typeof v === "string" && v.trim().length > 0)
+                return v.trim();
+        }
+    }
+    const profile = localState["profile"];
+    if (profile && typeof profile === "object") {
+        const info = profile.info_cache;
+        if (info && typeof info === "object") {
+            for (const entry of Object.values(info)) {
+                if (entry && typeof entry === "object") {
+                    const userName = entry.user_name;
+                    if (typeof userName === "string" && userName.trim().length > 0) {
+                        return userName.trim();
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+async function detectSyncStall(profileDir, now, thresholdMs) {
+    const historyMtime = await fileMtimeMs(join(profileDir, "Default", "History"));
+    if (historyMtime !== null && now - historyMtime <= thresholdMs) {
+        return { kind: "fresh" };
+    }
+    const syncMtime = await mostRecentSyncLevelDbWrite(profileDir);
+    if (syncMtime !== null && now - syncMtime <= thresholdMs) {
+        return { kind: "fresh" };
+    }
+    return {
+        kind: "stall",
+        detail: `History mtime ${historyMtime ?? "missing"}, sync mtime ${syncMtime ?? "missing"} — both past ${Math.round(thresholdMs / 60_000)} min threshold`,
+    };
+}
+async function fileMtimeMs(path) {
+    try {
+        const s = await stat(path);
+        return s.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sync LevelDB lives at `Default/Sync Data/LevelDB/`. We walk one
+ * directory level to find the most recent write across `.ldb` /
+ * `MANIFEST-*` / `CURRENT` / `LOG`. Returns null when the directory or
+ * any of its files cannot be read.
+ *
+ * Implementation detail: we prefer the inner LevelDB directory and
+ * fall back to the parent `Sync Data` dir only when LevelDB is absent.
+ * Walking both candidates would shadow the inner-file mtime with the
+ * parent's own mtime — every write inside `LevelDB/` advances the
+ * `LevelDB` directory entry's mtime when listed from `Sync Data`, so
+ * the stall threshold would never fire under a merged max.
+ */
+export async function mostRecentSyncLevelDbWrite(profileDir) {
+    const candidates = [
+        join(profileDir, "Default", "Sync Data", "LevelDB"),
+        join(profileDir, "Default", "Sync Data"),
+    ];
+    for (const dir of candidates) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        let best = null;
+        for (const entry of entries) {
+            const m = await fileMtimeMs(join(dir, entry));
+            if (m !== null && (best === null || m > best))
+                best = m;
+        }
+        if (best !== null)
+            return best;
+    }
+    return null;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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 type { SandboxPrimitive } from "../types.js";
+/**
+ * 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 declare function pathAncestors(absolutePath: string): string[];
+/**
+ * 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 declare function escapeSandboxLiteral(path: string): string;
+/**
+ * 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 declare function renderAncestorMetadataLiterals(paths: readonly string[], indent?: string): string;
+export interface SandboxInstallContext {
+    /** Absolute path under PA_DATA_DIR where the installed profile lands. */
+    paDataDir: string;
+    /** Resolved Chromium binary path. */
+    binaryPath: string;
+    /** Resolved per-instance user data dir. */
+    userDataDir: string;
+}
+/**
+ * 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 declare function installSandboxExecProfile(ctx: SandboxInstallContext): Promise<string>;
+/**
+ * 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 declare function materialiseSandboxPrimitive(raw: SandboxPrimitive, ctx: SandboxInstallContext): Promise<SandboxPrimitive>;