@aitne/daemon 0.1.7 → 0.1.9

package/dist/services/browser-history/history-mtime.d.ts

@@ -0,0 +1,8 @@
+export declare const HISTORY_FAMILY_SUFFIXES: readonly ["", "-wal", "-journal"];
+/**
+ * Returns the newest mtime (in ms since epoch) across `historyPath`,
+ * `<historyPath>-wal`, and `<historyPath>-journal`, or null if none of
+ * them exist. Missing siblings are silently ignored — they're optional
+ * by SQLite design.
+ */
+export declare function freshestHistoryMtimeMs(historyPath: string): Promise<number | null>;

package/dist/services/browser-history/history-mtime.js

@@ -0,0 +1,31 @@
+import { stat } from "node:fs/promises";
+// Chromium's `History` is a SQLite database. Both journaling modes route
+// writes through sibling files, so the main `History` file's mtime can
+// lag actual write activity by hours or days:
+//
+//   * WAL mode (Chromium's default on most platforms) — writes land in
+//     `History-wal`; the main file's mtime advances only on checkpoint,
+//     which under light activity may not happen for days.
+//   * Rollback-journal mode (some Chromium forks and post-corruption
+//     fallbacks) — a `History-journal` exists for the duration of each
+//     transaction and is deleted on commit. Long-lived transactions
+//     hold `History`'s mtime fixed at the last commit.
+//
+// Stat'ing only `History` therefore mis-flags an actively-used profile
+// as stale. Callers that want a "is this DB being touched?" signal must
+// consider the family. `-shm` is intentionally excluded — it moves on
+// read-only opens, which would over-trigger "fresh" on a Chrome that
+// opened the DB but isn't writing.
+export const HISTORY_FAMILY_SUFFIXES = ["", "-wal", "-journal"];
+/**
+ * Returns the newest mtime (in ms since epoch) across `historyPath`,
+ * `<historyPath>-wal`, and `<historyPath>-journal`, or null if none of
+ * them exist. Missing siblings are silently ignored — they're optional
+ * by SQLite design.
+ */
+export async function freshestHistoryMtimeMs(historyPath) {
+    const candidates = await Promise.all(HISTORY_FAMILY_SUFFIXES.map((suffix) => stat(`${historyPath}${suffix}`)
+        .then((s) => s.mtimeMs)
+        .catch(() => null)));
+    return candidates.reduce((acc, m) => (m === null ? acc : acc === null ? m : Math.max(acc, m)), null);
+}

package/dist/services/browser-history/interests-reflection-lock.d.ts

@@ -0,0 +1,26 @@
+export declare class InterestsReflectionLockBusyError extends Error {
+    readonly attemptedBy: string;
+    readonly heldBy: string;
+    constructor(attemptedBy: string, heldBy: string);
+}
+/**
+ * Synchronously acquire the lock. Returns a release callback the caller
+ * MUST invoke in a `finally` block — without it the lock leaks and
+ * every subsequent reflection attempt throws
+ * `InterestsReflectionLockBusyError`.
+ *
+ * The retry contract is one-shot: this function does NOT internally
+ * sleep — sync callers cannot block the event loop responsibly. The
+ * dashboard route wraps the call in a 250ms async retry; the scheduler
+ * pre-hook treats contention as a journal-line and moves on (the same
+ * data will refresh on the next cron tick).
+ */
+export declare function acquireInterestsReflectionLock(holder: string): () => void;
+/**
+ * Test-only escape hatch: reset the lock state regardless of holder.
+ * Production code must not use this — the proper teardown is the
+ * `release` callback returned by `acquireInterestsReflectionLock`.
+ */
+export declare function _resetInterestsReflectionLockForTests(): void;
+/** Current holder string, or `null` when the lock is free. */
+export declare function peekInterestsReflectionLockHolder(): string | null;

package/dist/services/browser-history/interests-reflection-lock.js

@@ -0,0 +1,84 @@
+import { createLogger } from "../../logging.js";
+/**
+ * WEEKLY_INTERESTS_REFLECTION_PLAN.md §10.3 — courtesy mutex serialising
+ * `refreshInterestsReflection` against `cleanupInterestsReflection`.
+ *
+ * Both helpers are synchronous in this codebase, and the Node event
+ * loop is single-threaded, so two same-tick invocations cannot
+ * physically interleave. The lock exists for three forward-looking
+ * reasons:
+ *
+ *   1. The design specifies a per-feature write lock that serialises a
+ *      same-minute re-run (e.g. scheduler tick overlapping a dashboard
+ *      "Refresh now" click). The implementation must honour the
+ *      contract even if Node single-thread makes the lock effectively a
+ *      no-op today — otherwise a later async rewrite of the helpers
+ *      would silently lose the serialisation guarantee.
+ *   2. The lock makes contention an explicit, observable error
+ *      (`InterestsReflectionLockBusyError`) rather than a silent
+ *      "lost update" if the implementation ever moves to async FS.
+ *   3. The retry shape (§20 testing strategy — "retry once after 250ms")
+ *      lives here so callers don't reinvent it.
+ *
+ * The lock holder is identified by a free-form `holder` string
+ * (`"refresh:scheduler"` / `"refresh:dashboard"` / `"cleanup:dashboard"`
+ * / `"refresh:test"` / …) so a contention error tells the operator who
+ * was already running. Identity is for diagnostics only — the lock has
+ * no caller-token semantics.
+ */
+const logger = createLogger("interests-reflection-lock");
+export class InterestsReflectionLockBusyError extends Error {
+    attemptedBy;
+    heldBy;
+    constructor(attemptedBy, heldBy) {
+        super(`Interests reflection lock busy: '${attemptedBy}' attempted while '${heldBy}' was running`);
+        this.attemptedBy = attemptedBy;
+        this.heldBy = heldBy;
+        this.name = "InterestsReflectionLockBusyError";
+    }
+}
+let currentHolder = null;
+/**
+ * Synchronously acquire the lock. Returns a release callback the caller
+ * MUST invoke in a `finally` block — without it the lock leaks and
+ * every subsequent reflection attempt throws
+ * `InterestsReflectionLockBusyError`.
+ *
+ * The retry contract is one-shot: this function does NOT internally
+ * sleep — sync callers cannot block the event loop responsibly. The
+ * dashboard route wraps the call in a 250ms async retry; the scheduler
+ * pre-hook treats contention as a journal-line and moves on (the same
+ * data will refresh on the next cron tick).
+ */
+export function acquireInterestsReflectionLock(holder) {
+    if (currentHolder !== null) {
+        logger.debug({ attemptedBy: holder, heldBy: currentHolder }, "Interests reflection lock contention");
+        throw new InterestsReflectionLockBusyError(holder, currentHolder);
+    }
+    currentHolder = holder;
+    let released = false;
+    return function release() {
+        if (released)
+            return;
+        released = true;
+        if (currentHolder !== holder) {
+            // Defensive: a stale release call after the lock was force-cleared
+            // or re-acquired must not nuke an unrelated holder.
+            logger.warn({ holder, currentHolder }, "Interests reflection lock release ignored — holder mismatch");
+            return;
+        }
+        currentHolder = null;
+    };
+}
+/**
+ * Test-only escape hatch: reset the lock state regardless of holder.
+ * Production code must not use this — the proper teardown is the
+ * `release` callback returned by `acquireInterestsReflectionLock`.
+ */
+export function _resetInterestsReflectionLockForTests() {
+    currentHolder = null;
+}
+/** Current holder string, or `null` when the lock is free. */
+export function peekInterestsReflectionLockHolder() {
+    return currentHolder;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * On-demand Playwright Chromium installer.
+ *
+ * Resolves the "first-run UX" problem for the managed-Chromium feature:
+ * instead of asking the operator to `brew install chromium` (or apt /
+ * dnf equivalent) and *then* enable the integration, we let them flip
+ * the master toggle and trigger a daemon-driven download of the
+ * Playwright-pinned Chromium build into `~/.cache/ms-playwright/`
+ * (XDG cache root differs per OS — Playwright manages the layout).
+ *
+ * Rationale (vs. bundling Chromium in the npm tarball):
+ *   - npm tarball size stays where it is (today's package is ~tens of
+ *     MB; bundling Chromium for every supported platform pushes that
+ *     to ~1 GB and turns every Aitne release into a Chromium security
+ *     release).
+ *   - Playwright already ships pre-notarised macOS builds and prebuilt
+ *     Linux/Windows binaries. Aitne does not have to maintain the
+ *     code-signing pipeline.
+ *   - System-installed Chromium (brew / apt / dnf) still wins when
+ *     present — `HostProfile.browserBinaryFor("chromium")` probes the
+ *     OS package first and only falls back to the Playwright cache
+ *     when the OS path resolves to null. Operators who already have
+ *     Chromium installed see zero extra disk usage.
+ *
+ * Concurrency: at most one install runs daemon-wide. A second
+ * `startInstall()` while one is in flight returns `already_running`.
+ *
+ * State persistence: progress is in-memory (the dashboard polls every
+ * second while downloading); the *result* (binary path on success,
+ * error message on failure) is the only durable output, and it lives
+ * implicitly in the Playwright cache on disk — the next boot's
+ * `browserBinaryFor("chromium")` probe will pick it up.
+ */
+export type ChromiumInstallState = "idle" | "downloading" | "verifying" | "completed" | "failed";
+export interface ChromiumInstallStatus {
+    state: ChromiumInstallState;
+    /** 0-100, null until first progress line. */
+    progressPercent: number | null;
+    /** Total MiB reported by Playwright; null until first line. */
+    totalMib: number | null;
+    /** Approximate downloaded MiB (derived from percent × total). */
+    downloadedMib: number | null;
+    startedAt: number | null;
+    completedAt: number | null;
+    /** Resolved binary path on `completed`; null otherwise. */
+    binaryPath: string | null;
+    errorMessage: string | null;
+}
+export declare function getChromiumInstallStatus(): ChromiumInstallStatus;
+/**
+ * Resolve the headed Chromium binary path inside the Playwright cache,
+ * if Playwright has been installed via `playwright install chromium`.
+ * Async wrapper over the synchronous resolver in `platform.ts` — kept
+ * as a `Promise` because the install-completion callback below was
+ * written against an async signature and other future callers may want
+ * to chain a real verification step here (e.g. spawning the binary
+ * with `--version`).
+ */
+export declare function getPlaywrightChromiumPath(): Promise<string | null>;
+declare function resolveCliPath(): string | null;
+export type StartInstallResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "already_running" | "spawn_failed";
+};
+/**
+ * Spawn `node <playwright-core>/cli.js install chromium`. Returns
+ * synchronously after the spawn — completion is observed via
+ * `getChromiumInstallStatus()` polling. Idempotent: a second call
+ * while a download is in flight returns `already_running`.
+ */
+export declare function startChromiumInstall(): StartInstallResult;
+export declare const __testing: {
+    DEFAULT_STATUS: ChromiumInstallStatus;
+    resolveCliPath: typeof resolveCliPath;
+};
+export {};

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

@@ -0,0 +1,206 @@
+/**
+ * On-demand Playwright Chromium installer.
+ *
+ * Resolves the "first-run UX" problem for the managed-Chromium feature:
+ * instead of asking the operator to `brew install chromium` (or apt /
+ * dnf equivalent) and *then* enable the integration, we let them flip
+ * the master toggle and trigger a daemon-driven download of the
+ * Playwright-pinned Chromium build into `~/.cache/ms-playwright/`
+ * (XDG cache root differs per OS — Playwright manages the layout).
+ *
+ * Rationale (vs. bundling Chromium in the npm tarball):
+ *   - npm tarball size stays where it is (today's package is ~tens of
+ *     MB; bundling Chromium for every supported platform pushes that
+ *     to ~1 GB and turns every Aitne release into a Chromium security
+ *     release).
+ *   - Playwright already ships pre-notarised macOS builds and prebuilt
+ *     Linux/Windows binaries. Aitne does not have to maintain the
+ *     code-signing pipeline.
+ *   - System-installed Chromium (brew / apt / dnf) still wins when
+ *     present — `HostProfile.browserBinaryFor("chromium")` probes the
+ *     OS package first and only falls back to the Playwright cache
+ *     when the OS path resolves to null. Operators who already have
+ *     Chromium installed see zero extra disk usage.
+ *
+ * Concurrency: at most one install runs daemon-wide. A second
+ * `startInstall()` while one is in flight returns `already_running`.
+ *
+ * State persistence: progress is in-memory (the dashboard polls every
+ * second while downloading); the *result* (binary path on success,
+ * error message on failure) is the only durable output, and it lives
+ * implicitly in the Playwright cache on disk — the next boot's
+ * `browserBinaryFor("chromium")` probe will pick it up.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { createLogger } from "../../../logging.js";
+import { playwrightExecutablePathSync } from "./platform.js";
+const logger = createLogger("chromium-install");
+const DEFAULT_STATUS = {
+    state: "idle",
+    progressPercent: null,
+    totalMib: null,
+    downloadedMib: null,
+    startedAt: null,
+    completedAt: null,
+    binaryPath: null,
+    errorMessage: null,
+};
+let current = { ...DEFAULT_STATUS };
+let childRef = null;
+export function getChromiumInstallStatus() {
+    return { ...current };
+}
+/**
+ * Resolve the headed Chromium binary path inside the Playwright cache,
+ * if Playwright has been installed via `playwright install chromium`.
+ * Async wrapper over the synchronous resolver in `platform.ts` — kept
+ * as a `Promise` because the install-completion callback below was
+ * written against an async signature and other future callers may want
+ * to chain a real verification step here (e.g. spawning the binary
+ * with `--version`).
+ */
+export async function getPlaywrightChromiumPath() {
+    return playwrightExecutablePathSync();
+}
+function resolveCliPath() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req.resolve("playwright-core/package.json");
+        const cli = join(dirname(pkg), "cli.js");
+        return existsSync(cli) ? cli : null;
+    }
+    catch (err) {
+        logger.warn({ err }, "could not resolve playwright-core/cli.js path");
+        return null;
+    }
+}
+/**
+ * Spawn `node <playwright-core>/cli.js install chromium`. Returns
+ * synchronously after the spawn — completion is observed via
+ * `getChromiumInstallStatus()` polling. Idempotent: a second call
+ * while a download is in flight returns `already_running`.
+ */
+export function startChromiumInstall() {
+    if (current.state === "downloading" || current.state === "verifying") {
+        return { ok: false, reason: "already_running" };
+    }
+    const cli = resolveCliPath();
+    if (!cli) {
+        current = {
+            ...DEFAULT_STATUS,
+            state: "failed",
+            errorMessage: "playwright-core cli.js not resolvable on this host",
+            startedAt: Date.now(),
+            completedAt: Date.now(),
+        };
+        return { ok: false, reason: "spawn_failed" };
+    }
+    current = {
+        ...DEFAULT_STATUS,
+        state: "downloading",
+        startedAt: Date.now(),
+    };
+    try {
+        childRef = spawn(process.execPath, [cli, "install", "chromium"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env },
+        });
+    }
+    catch (err) {
+        childRef = null;
+        current = {
+            ...DEFAULT_STATUS,
+            state: "failed",
+            errorMessage: err instanceof Error ? err.message : String(err),
+            startedAt: Date.now(),
+            completedAt: Date.now(),
+        };
+        return { ok: false, reason: "spawn_failed" };
+    }
+    let buf = "";
+    // Playwright emits progress lines like:
+    //   |████████████░░░░| 60% of 142.3 MiB
+    // ...both during the download phase. After the download:
+    //   Chromium 130.0.6723.116 (playwright build v1208) downloaded to /.../chromium-1208
+    // We parse percent/total from any line that matches the percent
+    // pattern; the "downloaded to" line is our verifying→completed
+    // transition signal (verified once cli.js exits 0).
+    const handleLine = (line) => {
+        const pct = /(\d+(?:\.\d+)?)\s*%\s+of\s+(\d+(?:\.\d+)?)\s*(?:MiB|MB)/i.exec(line);
+        if (pct) {
+            // `\d+` in the regex guarantees both groups parse, but be defensive:
+            // a future regex tweak that allows e.g. an empty group would otherwise
+            // surface as NaN downstream (Math.round(NaN) → NaN → schema rejection).
+            const rawPercent = parseFloat(pct[1]);
+            const rawTotal = parseFloat(pct[2]);
+            const percent = Number.isFinite(rawPercent)
+                ? Math.max(0, Math.min(100, rawPercent))
+                : current.progressPercent ?? 0;
+            current = {
+                ...current,
+                progressPercent: Math.round(percent),
+                totalMib: Number.isFinite(rawTotal) ? rawTotal : current.totalMib,
+                downloadedMib: Number.isFinite(rawTotal)
+                    ? Math.round((percent / 100) * rawTotal * 10) / 10
+                    : current.downloadedMib,
+            };
+            return;
+        }
+        if (/downloaded to/i.test(line)) {
+            current = { ...current, state: "verifying" };
+        }
+    };
+    const pipe = (chunk) => {
+        buf += chunk.toString("utf8");
+        const lines = buf.split(/\r?\n|\r/);
+        buf = lines.pop() ?? "";
+        for (const line of lines)
+            handleLine(line);
+    };
+    childRef.stdout?.on("data", pipe);
+    childRef.stderr?.on("data", pipe);
+    childRef.once("exit", (code, signal) => {
+        childRef = null;
+        if (code === 0) {
+            void getPlaywrightChromiumPath().then((path) => {
+                current = {
+                    ...current,
+                    state: path ? "completed" : "failed",
+                    binaryPath: path,
+                    progressPercent: 100,
+                    completedAt: Date.now(),
+                    errorMessage: path
+                        ? null
+                        : "install exited 0 but Chromium binary path did not resolve",
+                };
+                logger.info({ binaryPath: path }, path
+                    ? "Playwright Chromium install completed"
+                    : "Playwright Chromium install completed but path resolution failed");
+            });
+        }
+        else {
+            current = {
+                ...current,
+                state: "failed",
+                completedAt: Date.now(),
+                errorMessage: `playwright install exited code=${code ?? "?"} signal=${signal ?? "?"}`,
+            };
+            logger.warn({ code, signal }, "Playwright Chromium install exited non-zero");
+        }
+    });
+    childRef.once("error", (err) => {
+        childRef = null;
+        current = {
+            ...current,
+            state: "failed",
+            completedAt: Date.now(),
+            errorMessage: err.message,
+        };
+        logger.error({ err }, "Playwright Chromium install spawn errored");
+    });
+    return { ok: true };
+}
+export const __testing = { DEFAULT_STATUS, resolveCliPath };

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

@@ -0,0 +1,77 @@
+import type { BrowserProfileCandidate, HostProfile } from "../types.js";
+export declare function buildChromiumLaunchArgs(host: HostProfile, profile: BrowserProfileCandidate): string[];
+/**
+ * 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 declare function cleanupStaleSingletonLock(host: HostProfile, profile: BrowserProfileCandidate): Promise<"none" | "no_owner" | "owned" | "removed">;
+export type LaunchChromiumResult = {
+    outcome: "missing_binary";
+} | {
+    outcome: "already_running";
+} | {
+    outcome: "launched";
+    pid: number;
+};
+export declare function launchChromiumProfile(host: HostProfile, profile: BrowserProfileCandidate): Promise<LaunchChromiumResult>;
+/**
+ * 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 declare function terminateLaunchedChromium(host: HostProfile, profile: BrowserProfileCandidate, spawnedPid: number, options?: {
+    gracefulTimeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<"terminated" | "ownership_changed" | "already_gone" | "failed">;