@aitne/daemon 0.1.8 → 0.1.9

package/dist/services/browser-history/lifecycle/chromium-launcher.js

@@ -0,0 +1,288 @@
+import { spawn } from "node:child_process";
+import { lstat, readlink, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { readSingletonLockOwnerPid } from "./platform.js";
+const CHROMIUM_FLAGS = [
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-component-update",
+    "--disable-features=AutofillServerCommunication,Translate,MediaRouter",
+];
+// Sibling lock files Chromium writes alongside its profile root on Unix.
+// On Windows the equivalent is a named mutex, which dies with the
+// owning process — no on-disk cleanup needed.
+const CHROMIUM_SINGLETON_FILES = [
+    "SingletonLock",
+    "SingletonCookie",
+    "SingletonSocket",
+];
+export function buildChromiumLaunchArgs(host, profile) {
+    const flags = [...CHROMIUM_FLAGS];
+    if (host.os === "linux" && !host.hasDisplay) {
+        flags.push("--headless=new");
+    }
+    else {
+        flags.push("--no-startup-window");
+    }
+    flags.push(`--user-data-dir=${profile.userDataDir}`);
+    flags.push(`--profile-directory=${profile.profileName}`);
+    return flags;
+}
+/**
+ * BROWSER_HISTORY_INTEGRATION_PLAN.md §7.4.5 — "SingletonLock orphaned"
+ * recovery. Chromium writes `SingletonLock` as a symlink whose target
+ * encodes `<host>-<pid>`. When the browser shuts down cleanly the
+ * symlink is removed; a crash leaves it pointing at a dead pid and the
+ * next launch silently no-ops (Chromium refuses to start when it sees
+ * the file). The supervisor cannot recover from this without removing
+ * the stale lock first.
+ *
+ * Implementation reads the symlink target and parses out the pid. If
+ * the lock file is a regular file (some Chromium variants), it falls
+ * through to the host's `isProcessRunning(binary, userDataDir)` probe;
+ * an empty result means no owning process and the lock is removable.
+ *
+ * Windows has no on-disk lock here — Chromium uses a named mutex that
+ * the OS cleans up automatically on process exit, so the function is a
+ * no-op on win32.
+ */
+export async function cleanupStaleSingletonLock(host, profile) {
+    if (host.os === "win32")
+        return "none";
+    let staleOwner = null;
+    let kind = null;
+    try {
+        const lockPath = join(profile.userDataDir, "SingletonLock");
+        const linkStat = await lstat(lockPath).catch(() => null);
+        if (!linkStat)
+            return "none";
+        // `lstat()` does NOT follow symlinks, so it resolves the
+        // symlink/regular-file/missing distinction without chasing the
+        // SingletonLock target — which is a fabricated `<host>-<pid>`
+        // string that never points at a real path. A missing lock throws
+        // ENOENT above and is the only "none" case.
+        try {
+            const target = await readlink(lockPath);
+            kind = "symlink";
+            // Symlink target is `<hostname>-<pid>`. The pid is the last
+            // numeric segment after the final `-`.
+            const match = /-(\d+)$/.exec(target);
+            if (match)
+                staleOwner = Number(match[1]);
+        }
+        catch {
+            kind = "file";
+        }
+    }
+    catch {
+        return "none";
+    }
+    // If the symlink encoded a pid, check whether it's still alive. If we
+    // fell through to the file branch, ask the host abstraction whether
+    // any Chromium instance is currently bound to this profile.
+    const binary = host.browserBinaryFor(profile.browser);
+    const ownerAlive = await (async () => {
+        if (staleOwner !== null) {
+            try {
+                process.kill(staleOwner, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        if (binary) {
+            try {
+                return await host.isProcessRunning(binary, profile.userDataDir);
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    })();
+    if (ownerAlive)
+        return "owned";
+    // No live owner — clean up the lock trio so the next launch succeeds.
+    let removed = false;
+    for (const name of CHROMIUM_SINGLETON_FILES) {
+        try {
+            await rm(join(profile.userDataDir, name), { force: true });
+            removed = true;
+        }
+        catch {
+            // Best-effort cleanup; carry on with the rest.
+        }
+    }
+    return removed ? "removed" : (kind === null ? "none" : "no_owner");
+}
+export async function launchChromiumProfile(host, profile) {
+    const binary = host.browserBinaryFor(profile.browser);
+    if (!binary)
+        return { outcome: "missing_binary" };
+    // Recover from a previous crash that left an orphan SingletonLock.
+    // Without this Chromium silently refuses to start and the supervisor
+    // would mark the browser `launch_failed_recently` forever.
+    const lockState = await cleanupStaleSingletonLock(host, profile);
+    if (lockState === "owned") {
+        // A live Chromium instance already holds this profile (e.g. the
+        // user opened it via Finder / Dock between the supervisor's pre-
+        // launch health probe and this call). Spawning a second instance
+        // would either no-op via process-singleton forwarding or exit
+        // silently — neither advances the History mtime, so the supervisor
+        // would then mis-flag the cycle as `sync_unresponsive`. Tell the
+        // caller so it can treat this as "already running" and let the
+        // next tick re-evaluate via `checkBrowserProfileHealth`.
+        return { outcome: "already_running" };
+    }
+    const args = buildChromiumLaunchArgs(host, profile);
+    const child = spawn(binary, args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+    // `child.pid` is undefined only when spawn fails synchronously — the
+    // emitted `error` event surfaces that via the parent process; we
+    // mirror it here as `missing_binary` so callers don't try to
+    // terminate a phantom PID.
+    if (typeof child.pid !== "number" || child.pid <= 0) {
+        return { outcome: "missing_binary" };
+    }
+    return { outcome: "launched", pid: child.pid };
+}
+/**
+ * Quit a Chromium instance that the supervisor spawned to flush
+ * History — see `supervisor.ts:runProfileCycle` for the calling
+ * context. Without this the daemon-launched Chrome lingers in the
+ * user's dock indefinitely (macOS keeps the app resident after the
+ * last window closes), and 24h later the supervisor starts emitting
+ * `sync_unresponsive` events against it because no actual browsing
+ * advances History's mtime.
+ *
+ * Ownership verification (what `ownership_changed` actually catches):
+ * Just before signalling, we re-read SingletonLock. The check protects
+ * the case where our spawned process exited and a *different* Chromium
+ * — another daemon launch, an external script, etc. — has since taken
+ * over the profile and rewritten the lock. We must not kill that
+ * stranger. It does NOT catch the user-opens-Chrome-via-Dock race:
+ * Chromium's process-singleton IPC forwards a second launch into the
+ * existing owner without touching the lock target, so SingletonLock
+ * still points to `spawnedPid` even when a user-initiated window has
+ * just been attached to it. Mitigating that fully would require a
+ * renderer-process count probe; the residual window is accepted as
+ * narrow because the supervisor only spawns when the browser was
+ * previously *not* running, so users who actively browse Chrome never
+ * hit this path. See the supervisor caller comment for the policy
+ * trade-off.
+ *
+ * Non-symlink locks: some Chromium forks write SingletonLock as a
+ * regular file rather than a symlink, so the PID is not encoded in
+ * the path. For those we fall back to `host.isProcessRunning` — a
+ * weaker signal, but enough to confirm "some Chromium for this
+ * profile is alive" before terminating the PID we spawned 60s ago.
+ *
+ * Returns:
+ *   - `terminated` — SIGTERM (and possibly SIGKILL) was sent.
+ *   - `ownership_changed` — SingletonLock target now encodes a PID
+ *     other than `spawnedPid`; another process owns the profile, so
+ *     we declined to signal.
+ *   - `already_gone` — process is no longer alive, or no Chromium is
+ *     bound to this profile any more (clean exit or external kill);
+ *     nothing to do.
+ *   - `failed` — verification or signalling threw unexpectedly. The
+ *     supervisor logs but does not escalate; the next tick will
+ *     re-evaluate via `checkBrowserProfileHealth`.
+ */
+export async function terminateLaunchedChromium(host, profile, spawnedPid, options = {}) {
+    const gracefulTimeoutMs = options.gracefulTimeoutMs ?? 5000;
+    const pollIntervalMs = options.pollIntervalMs ?? 200;
+    if (!isProcessAlive(spawnedPid))
+        return "already_gone";
+    if (host.os === "win32") {
+        // Windows uses a named mutex, not an on-disk lock — there is no
+        // PID to parse. Fall back to the host-level userDataDir probe to
+        // confirm at least *some* Chromium for this profile is alive
+        // before sending the signal.
+        const binary = host.browserBinaryFor(profile.browser);
+        const ownerAlive = binary
+            ? await host.isProcessRunning(binary, profile.userDataDir).catch(() => false)
+            : false;
+        if (!ownerAlive)
+            return "already_gone";
+    }
+    else {
+        const ownerPid = await readSingletonLockOwnerPid(profile.userDataDir);
+        if (ownerPid !== null) {
+            // Precise check — only kill if SingletonLock still encodes the
+            // exact PID we spawned. A divergence means our spawn died and
+            // something else took the profile; leave that process alone.
+            if (ownerPid !== spawnedPid)
+                return "ownership_changed";
+        }
+        else {
+            // No parseable PID. Two sub-cases to distinguish so we do not
+            // regress Chromium forks that use a regular-file lock:
+            //   (a) lock path does not exist → process is gone, nothing
+            //       to do (already_gone)
+            //   (b) lock path is a regular file (some forks) → ownership
+            //       can't be cross-checked precisely; verify a Chromium
+            //       for this profile is alive via host.isProcessRunning
+            //       and proceed with the weaker confidence
+            const lockKind = await readSingletonLockKind(profile.userDataDir);
+            if (lockKind === "missing")
+                return "already_gone";
+            const binary = host.browserBinaryFor(profile.browser);
+            const ownerAlive = binary
+                ? await host.isProcessRunning(binary, profile.userDataDir).catch(() => false)
+                : false;
+            if (!ownerAlive)
+                return "already_gone";
+        }
+    }
+    try {
+        await host.terminate(spawnedPid, "graceful");
+    }
+    catch {
+        // process.kill threw — usually because the PID exited between the
+        // liveness probe above and the signal. Treat as success.
+        return "terminated";
+    }
+    const deadline = Date.now() + gracefulTimeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(spawnedPid))
+            return "terminated";
+        await sleep(pollIntervalMs);
+    }
+    // Graceful didn't take — escalate. Chromium very occasionally
+    // ignores SIGTERM during a long shutdown step; SIGKILL guarantees
+    // the dock entry is gone before the next tick.
+    try {
+        await host.terminate(spawnedPid, "force");
+    }
+    catch {
+        return isProcessAlive(spawnedPid) ? "failed" : "terminated";
+    }
+    return isProcessAlive(spawnedPid) ? "failed" : "terminated";
+}
+async function readSingletonLockKind(userDataDir) {
+    try {
+        const info = await lstat(join(userDataDir, "SingletonLock"));
+        return info.isSymbolicLink() ? "symlink" : "file";
+    }
+    catch {
+        return "missing";
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/services/browser-history/lifecycle/failure-escalation.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserHistoryLifecycleBrowserState } from "@aitne/shared";
+import type { FailureEscalationInput } from "../types.js";
+export declare function nextBrowserLifecycleState(input: FailureEscalationInput): BrowserHistoryLifecycleBrowserState;

package/dist/services/browser-history/lifecycle/failure-escalation.js

@@ -0,0 +1,54 @@
+const PAUSE_AFTER_FAILURES = 3;
+const PAUSE_MS = 24 * 60 * 60 * 1000;
+function stateForOutcome(outcome) {
+    if (outcome === "sync_unresponsive")
+        return "sync_unresponsive";
+    if (outcome === "launch_failed")
+        return "launch_failed_recently";
+    return "stale"; // outcome === "error"
+}
+export function nextBrowserLifecycleState(input) {
+    if (input.outcome === "paused") {
+        return {
+            state: "lifecycle_paused",
+            lastLaunchAt: null,
+            lastSuccessfulSyncAt: null,
+            lastCheckedAt: input.nowMs,
+            consecutiveFailures: input.consecutiveFailures,
+            pausedUntil: input.nowMs + PAUSE_MS,
+            lastOutcome: input.outcome,
+        };
+    }
+    if (input.outcome === "success" || input.outcome === "skipped") {
+        return {
+            state: input.outcome === "success" ? "healthy" : "stopped",
+            lastLaunchAt: null,
+            lastSuccessfulSyncAt: input.outcome === "success" ? input.nowMs : null,
+            lastCheckedAt: input.nowMs,
+            consecutiveFailures: 0,
+            pausedUntil: null,
+            lastOutcome: input.outcome,
+        };
+    }
+    const failures = input.consecutiveFailures + 1;
+    if (failures >= PAUSE_AFTER_FAILURES) {
+        return {
+            state: "lifecycle_paused",
+            lastLaunchAt: null,
+            lastSuccessfulSyncAt: null,
+            lastCheckedAt: input.nowMs,
+            consecutiveFailures: failures,
+            pausedUntil: input.nowMs + PAUSE_MS,
+            lastOutcome: input.outcome,
+        };
+    }
+    return {
+        state: stateForOutcome(input.outcome),
+        lastLaunchAt: null,
+        lastSuccessfulSyncAt: null,
+        lastCheckedAt: input.nowMs,
+        consecutiveFailures: failures,
+        pausedUntil: null,
+        lastOutcome: input.outcome,
+    };
+}

package/dist/services/browser-history/lifecycle/health-check.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserProfileCandidate, HostProfile } from "../types.js";
+export interface BrowserProfileHealth {
+    running: boolean;
+    historyMtimeMs: number | null;
+    syncAgeSeconds: number | null;
+    stale: boolean;
+}
+export declare function checkBrowserProfileHealth(host: HostProfile, profile: BrowserProfileCandidate, nowMs?: number): Promise<BrowserProfileHealth>;

package/dist/services/browser-history/lifecycle/health-check.js

@@ -0,0 +1,17 @@
+import { freshestHistoryMtimeMs } from "../history-mtime.js";
+export async function checkBrowserProfileHealth(host, profile, nowMs = Date.now()) {
+    const binary = host.browserBinaryFor(profile.browser);
+    const running = binary
+        ? await host.isProcessRunning(binary, profile.userDataDir)
+        : false;
+    const historyMtimeMs = await freshestHistoryMtimeMs(profile.historyPath);
+    const syncAgeSeconds = historyMtimeMs === null
+        ? null
+        : Math.max(0, Math.floor((nowMs - historyMtimeMs) / 1000));
+    return {
+        running,
+        historyMtimeMs,
+        syncAgeSeconds,
+        stale: syncAgeSeconds !== null && syncAgeSeconds > 24 * 60 * 60,
+    };
+}

package/dist/services/browser-history/lifecycle/platform.d.ts

@@ -0,0 +1,99 @@
+import type { ChromiumBrowserKey, HostProfile } from "../types.js";
+/**
+ * Synchronous resolver for the Playwright-managed Chromium binary path.
+ * Exported so the install-completion callback in chromium-install.ts
+ * can share the same source of truth as the HostProfile probe.
+ */
+export declare function playwrightExecutablePathSync(): string | null;
+/**
+ * Compute the "bundle root" of a Chromium binary — the directory the OS
+ * sandbox layer must allow so Chromium can load its own helpers,
+ * frameworks, and resources at runtime.
+ *
+ * macOS: the nearest `.app` ancestor. Covers both `/Applications/
+ *        Chromium.app` (system) and `~/Library/Caches/ms-playwright/
+ *        chromium-*\/chrome-mac-*\/Google Chrome for Testing.app`
+ *        (Playwright cache) layouts. Without the .app subpath in the
+ *        `sandbox-exec` profile, `(deny default)` blocks Chromium from
+ *        reading its own `.framework/*` bundles and the spawn fails
+ *        silently with a renderer crash loop.
+ * Linux/Windows: the binary's parent directory. Playwright ships the
+ *        full chromium build inside `chrome-linux/` or
+ *        `chrome-win{64,}/`; system installs colocate helpers next to
+ *        the binary (`/usr/lib/chromium/` mounted via `/usr` for system
+ *        Chromium). Passing the parent dir as a `--ro-bind` covers all
+ *        the helper binaries bwrap would otherwise hide.
+ *
+ * Side-effect-free; pure path arithmetic. Returns the binary's parent
+ * directory on Apple paths that lack a `.app` ancestor — a safe
+ * conservative default rather than the binary path itself, which only
+ * covers the entrypoint file.
+ */
+/**
+ * macOS 26 (Tahoe, codename Tahoe) ships as Darwin 25.x.y. The kernel
+ * sandbox in this release default-denies the
+ * `forbidden-sandbox-reinit` operation, which is the operation
+ * Chromium's middle ring uses when each helper process (renderer,
+ * GPU, network, utility) calls `sandbox_init_with_parameters()` to
+ * apply its own additional seatbelt profile on top of the outer
+ * sandbox-exec profile.
+ *
+ * Concretely, on macOS 26 a Chromium spawned under our sandbox-exec
+ * outer ring sees every helper abort with
+ * `Failed to initialize sandbox. sandbox initialization failed:
+ * Operation not permitted`, the GPU/network services flap, and
+ * `gpu_data_manager_impl_private.cc` fatals with `GPU process isn't
+ * usable. Goodbye.` This is not a profile-language issue —
+ * `forbidden-sandbox-reinit` is not an operation name v1 sandbox
+ * profiles can `(allow ...)`; it is gated by Apple at a layer below
+ * sandbox-exec, addressable only via private entitlements we have no
+ * legitimate way to acquire.
+ *
+ * The architectural pivot — see also the `--no-sandbox` comment in
+ * `instance-a-config.ts:INSTANCE_A_SHARED_FLAGS` — is to drop the
+ * middle ring on macOS 26+ and rely on the outer (sandbox-exec) +
+ * inner (CDP route filter) rings only. Returning `true` from this
+ * helper instructs the sandbox launcher to inject `--no-sandbox` into
+ * the Chromium argv so the helpers skip the seatbelt reinit step
+ * entirely instead of aborting on it.
+ *
+ * Darwin major-version mapping for reference: macOS 13 → Darwin 22,
+ * macOS 14 → Darwin 23, macOS 15 → Darwin 24, macOS 26 → Darwin 25
+ * (Apple skipped the macOS 16–25 names in favour of a year-aligned
+ * jump). The threshold is `darwinMajor >= 25`.
+ */
+export declare function darwinTahoeOrLater(platform?: NodeJS.Platform, osRelease?: () => string): boolean;
+export declare function chromiumBundleRoot(binaryPath: string): string;
+/**
+ * SingletonLock-based liveness probe. Chromium writes
+ * `<userDataDir>/SingletonLock` as a symlink whose target encodes
+ * `<host>-<pid>` for the owning process; the file is removed on clean
+ * shutdown. This is the same mechanism Chromium uses to enforce single
+ * instance, so reading it is the most direct check for "is this profile
+ * in use".
+ *
+ * It is also the only check that catches a Chromium launched without an
+ * explicit `--user-data-dir=` flag (Finder / Dock / Start-menu launches
+ * inherit the platform default and omit the flag from argv), which the
+ * ps-grep below would otherwise miss.
+ *
+ * Returns false on any error — missing file, regular-file lock used by
+ * some Chromium forks, PID not parseable, or dead PID. Callers should
+ * fall through to a process-table probe for those cases.
+ */
+/**
+ * Parses the SingletonLock symlink target (`<hostname>-<pid>`) and
+ * returns the encoded PID, or `null` when the symlink is missing,
+ * malformed, or the lock is a regular file (some Chromium forks).
+ *
+ * Does NOT verify the PID is still alive — callers that need a
+ * liveness check should compose this with `process.kill(pid, 0)` or
+ * use `singletonLockHasLiveOwner` instead. The supervisor's terminate
+ * path needs the raw PID even when liveness is unclear, so the parse
+ * is exposed separately from the liveness probe.
+ */
+export declare function readSingletonLockOwnerPid(userDataDir: string): Promise<number | null>;
+export declare function singletonLockHasLiveOwner(userDataDir: string): Promise<boolean>;
+export declare function createHostProfile(): HostProfile;
+export declare function resolveLinuxBinaryFromPath(key: ChromiumBrowserKey): Promise<string | null>;
+export declare function pathIsReadable(path: string): boolean;